sqlalchemy API Reference
Full documentation for sqlalchemy (2.0.51)
sqlalchemy.ARRAY
Python Library Documentation: class ARRAY in module sqlalchemy.sql.sqltypes
class ARRAY(sqlalchemy.sql.base.SchemaEventTarget, Indexable, Concatenable, sqlalchemy.sql.type_api.TypeEngine)
| ARRAY(item_type: '_TypeEngineArgument[_T]', as_tuple: 'bool' = False, dimensions: 'Optional[int]' = None, zero_indexes: 'bool' = False)
|
| Represent a SQL Array type.
|
| .. note:: This type serves as the basis for all ARRAY operations.
| However, currently **only the PostgreSQL backend has support for SQL
| arrays in SQLAlchemy**. It is recommended to use the PostgreSQL-specific
| :class:`sqlalchemy.dialects.postgresql.ARRAY` type directly when using
| ARRAY types with PostgreSQL, as it provides additional operators
| specific to that backend.
|
| :class:`_types.ARRAY` is part of the Core in support of various SQL
| standard functions such as :class:`_functions.array_agg`
| which explicitly involve
| arrays; however, with the exception of the PostgreSQL backend and possibly
| some third-party dialects, no other SQLAlchemy built-in dialect has support
| for this type.
|
| An :class:`_types.ARRAY` type is constructed given the "type"
| of element::
|
| mytable = Table("mytable", metadata, Column("data", ARRAY(Integer)))
|
| The above type represents an N-dimensional array,
| meaning a supporting backend such as PostgreSQL will interpret values
| with any number of dimensions automatically. To produce an INSERT
| construct that passes in a 1-dimensional array of integers::
|
| connection.execute(mytable.insert(), {"data": [1, 2, 3]})
|
| The :class:`_types.ARRAY` type can be constructed given a fixed number
| of dimensions::
|
| mytable = Table(
| "mytable", metadata, Column("data", ARRAY(Integer, dimensions=2))
| )
|
| Sending a number of dimensions is optional, but recommended if the
| datatype is to represent arrays of more than one dimension. This number
| is used:
|
| * When emitting the type declaration itself to the database, e.g.
| ``INTEGER[][]``
|
| * When translating Python values to database values, and vice versa, e.g.
| an ARRAY of :class:`.Unicode` objects uses this number to efficiently
| access the string values inside of array structures without resorting
| to per-row type inspection
|
| * When used with the Python ``getitem`` accessor, the number of dimensions
| serves to define the kind of type that the ``[]`` operator should
| return, e.g. for an ARRAY of INTEGER with two dimensions::
|
| >>> expr = table.c.column[5] # returns ARRAY(Integer, dimensions=1)
| >>> expr = expr[6] # returns Integer
|
| For 1-dimensional arrays, an :class:`_types.ARRAY` instance with no
| dimension parameter will generally assume single-dimensional behaviors.
|
| SQL expressions of type :class:`_types.ARRAY` have support for "index" and
| "slice" behavior. The ``[]`` operator produces expression
| constructs which will produce the appropriate SQL, both for
| SELECT statements::
|
| select(mytable.c.data[5], mytable.c.data[2:7])
|
| as well as UPDATE statements when the :meth:`_expression.Update.values`
| method is used::
|
| mytable.update().values(
| {mytable.c.data[5]: 7, mytable.c.data[2:7]: [1, 2, 3]}
| )
|
| Indexed access is one-based by default;
| for zero-based index conversion, set :paramref:`_types.ARRAY.zero_indexes`.
|
| The :class:`_types.ARRAY` type also provides for the operators
| :meth:`.types.ARRAY.Comparator.any` and
| :meth:`.types.ARRAY.Comparator.all`. The PostgreSQL-specific version of
| :class:`_types.ARRAY` also provides additional operators.
|
| .. container:: topic
|
| **Detecting Changes in ARRAY columns when using the ORM**
|
| The :class:`_sqltypes.ARRAY` type, when used with the SQLAlchemy ORM,
| does not detect in-place mutations to the array. In order to detect
| these, the :mod:`sqlalchemy.ext.mutable` extension must be used, using
| the :class:`.MutableList` class::
|
| from sqlalchemy import ARRAY
| from sqlalchemy.ext.mutable import MutableList
|
|
| class SomeOrmClass(Base):
| # ...
|
| data = Column(MutableList.as_mutable(ARRAY(Integer)))
|
| This extension will allow "in-place" changes such to the array
| such as ``.append()`` to produce events which will be detected by the
| unit of work. Note that changes to elements **inside** the array,
| including subarrays that are mutated in place, are **not** detected.
|
| Alternatively, assigning a new array value to an ORM element that
| replaces the old one will always trigger a change event.
|
| .. seealso::
|
| :class:`sqlalchemy.dialects.postgresql.ARRAY`
|
| Method resolution order:
| ARRAY
| sqlalchemy.sql.base.SchemaEventTarget
| sqlalchemy.event.registry.EventTarget
| Indexable
| Concatenable
| sqlalchemy.sql.type_api.TypeEngineMixin
| sqlalchemy.sql.type_api.TypeEngine
| sqlalchemy.sql.visitors.Visitable
| typing.Generic
| builtins.object
|
| Methods defined here:
|
| __init__(self, item_type: '_TypeEngineArgument[_T]', as_tuple: 'bool' = False, dimensions: 'Optional[int]' = None, zero_indexes: 'bool' = False)
| Construct an :class:`_types.ARRAY`.
|
| E.g.::
|
| Column("myarray", ARRAY(Integer))
|
| Arguments are:
|
| :param item_type: The data type of items of this array. Note that
| dimensionality is irrelevant here, so multi-dimensional arrays like
| ``INTEGER[][]``, are constructed as ``ARRAY(Integer)``, not as
| ``ARRAY(ARRAY(Integer))`` or such.
|
| :param as_tuple=False: Specify whether return results
| should be converted to tuples from lists. This parameter is
| not generally needed as a Python list corresponds well
| to a SQL array.
|
| :param dimensions: if non-None, the ARRAY will assume a fixed
| number of dimensions. This impacts how the array is declared
| on the database, how it goes about interpreting Python and
| result values, as well as how expression behavior in conjunction
| with the "getitem" operator works. See the description at
| :class:`_types.ARRAY` for additional detail.
|
| :param zero_indexes=False: when True, index values will be converted
| between Python zero-based and SQL one-based indexes, e.g.
| a value of one will be added to all index values before passing
| to the database.
|
| compare_values(self, x: 'Any', y: 'Any') -> 'bool'
| Compare two values for equality.
|
| literal_processor(self, dialect: 'Dialect') -> 'Optional[_LiteralProcessorType[_T]]'
| Return a conversion function for processing literal values that are
| to be rendered directly without using binds.
|
| This function is used when the compiler makes use of the
| "literal_binds" flag, typically used in DDL generation as well
| as in certain scenarios where backends don't accept bound parameters.
|
| Returns a callable which will receive a literal Python value
| as the sole positional argument and will return a string representation
| to be rendered in a SQL statement.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.literal_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.literal_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_literal_param`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| ----------------------------------------------------------------------
| Readonly properties defined here:
|
| hashable
|
| python_type
| Return the Python type object expected to be returned
| by instances of this type, if known.
|
| Basically, for those types which enforce a return type,
| or are known across the board to do such for all common
| DBAPIs (like ``int`` for example), will return that type.
|
| If a return type is not defined, raises
| ``NotImplementedError``.
|
| Note that any type also accommodates NULL in SQL which
| means you can also get back ``None`` from any type
| in practice.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| Comparator = <class 'sqlalchemy.sql.sqltypes.ARRAY.Comparator'>
| Define comparison operations for :class:`_types.ARRAY`.
|
| More operators are available on the dialect-specific form
| of this type. See :class:`.postgresql.ARRAY.Comparator`.
|
|
| __annotations__ = {}
|
| __parameters__ = ()
|
| __visit_name__ = 'ARRAY'
|
| comparator_factory = <class 'sqlalchemy.sql.sqltypes.ARRAY.Comparator'...
| Define comparison operations for :class:`_types.ARRAY`.
|
| More operators are available on the dialect-specific form
| of this type. See :class:`.postgresql.ARRAY.Comparator`.
|
|
| zero_indexes = False
|
| ----------------------------------------------------------------------
| Data descriptors inherited from sqlalchemy.sql.base.SchemaEventTarget:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.base.SchemaEventTarget:
|
| dispatch = <sqlalchemy.event.base.DDLEventsDispatch object>
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.type_api.TypeEngine:
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| __str__(self) -> 'str'
| Return str(self).
|
| adapt(self, cls: 'Type[Union[TypeEngine[Any], TypeEngineMixin]]', **kw: 'Any') -> 'TypeEngine[Any]'
| Produce an "adapted" form of this type, given an "impl" class
| to work with.
|
| This method is used internally to associate generic
| types with "implementation" types that are specific to a particular
| dialect.
|
| as_generic(self, allow_nulltype: 'bool' = False) -> 'TypeEngine[_T]'
| Return an instance of the generic type corresponding to this type
| using heuristic rule. The method may be overridden if this
| heuristic rule is not sufficient.
|
| >>> from sqlalchemy.dialects.mysql import INTEGER
| >>> INTEGER(display_width=4).as_generic()
| Integer()
|
| >>> from sqlalchemy.dialects.mysql import NVARCHAR
| >>> NVARCHAR(length=100).as_generic()
| Unicode(length=100)
|
| .. versionadded:: 1.4.0b2
|
|
| .. seealso::
|
| :ref:`metadata_reflection_dbagnostic_types` - describes the
| use of :meth:`_types.TypeEngine.as_generic` in conjunction with
| the :meth:`_sql.DDLEvents.column_reflect` event, which is its
| intended use.
|
| bind_expression(self, bindvalue: 'BindParameter[_T]') -> 'Optional[ColumnElement[_T]]'
| Given a bind value (i.e. a :class:`.BindParameter` instance),
| return a SQL expression in its place.
|
| This is typically a SQL function that wraps the existing bound
| parameter within the statement. It is used for special data types
| that require literals being wrapped in some special database function
| in order to coerce an application-level value into a database-specific
| format. It is the SQL analogue of the
| :meth:`.TypeEngine.bind_processor` method.
|
| This method is called during the **SQL compilation** phase of a
| statement, when rendering a SQL string. It is **not** called
| against specific values.
|
| Note that this method, when implemented, should always return
| the exact same structure, without any conditional logic, as it
| may be used in an executemany() call against an arbitrary number
| of bound parameter sets.
|
| .. note::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.bind_expression`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.bind_expression`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.bind_expression`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| .. seealso::
|
| :ref:`types_sql_value_processing`
|
| bind_processor(self, dialect: 'Dialect') -> 'Optional[_BindProcessorType[_T]]'
| Return a conversion function for processing bind values.
|
| Returns a callable which will receive a bind parameter value
| as the sole positional argument and will return a value to
| send to the DB-API.
|
| If processing is not necessary, the method should return ``None``.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.bind_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.bind_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_bind_param`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
|
| :param dialect: Dialect instance in use.
|
| coerce_compared_value(self, op: 'Optional[OperatorType]', value: 'Any') -> 'TypeEngine[Any]'
| Suggest a type for a 'coerced' Python value in an expression.
|
| Given an operator and value, gives the type a chance
| to return a type which the value should be coerced into.
|
| The default behavior here is conservative; if the right-hand
| side is already coerced into a SQL type based on its
| Python type, it is usually left alone.
|
| End-user functionality extension here should generally be via
| :class:`.TypeDecorator`, which provides more liberal behavior in that
| it defaults to coercing the other side of the expression into this
| type, thus applying special Python conversions above and beyond those
| needed by the DBAPI to both ides. It also provides the public method
| :meth:`.TypeDecorator.coerce_compared_value` which is intended for
| end-user customization of this behavior.
|
| column_expression(self, colexpr: 'ColumnElement[_T]') -> 'Optional[ColumnElement[_T]]'
| Given a SELECT column expression, return a wrapping SQL expression.
|
| This is typically a SQL function that wraps a column expression
| as rendered in the columns clause of a SELECT statement.
| It is used for special data types that require
| columns to be wrapped in some special database function in order
| to coerce the value before being sent back to the application.
| It is the SQL analogue of the :meth:`.TypeEngine.result_processor`
| method.
|
| .. note:: The :func:`.TypeEngine.column_expression` method is applied
| only to the **outermost columns clause** of a SELECT statement, that
| is, the columns that are to be delivered directly into the returned
| result rows. It does **not** apply to the columns clause inside
| of subqueries. This necessarily avoids double conversions against
| the column and only runs the conversion when ready to be returned
| to the client.
|
| This method is called during the **SQL compilation** phase of a
| statement, when rendering a SQL string. It is **not** called
| against specific values.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.column_expression`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.column_expression`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.column_expression`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
|
| .. seealso::
|
| :ref:`types_sql_value_processing`
|
| compile(self, dialect: 'Optional[Dialect]' = None) -> 'str'
| Produce a string-compiled form of this :class:`.TypeEngine`.
|
| When called with no arguments, uses a "default" dialect
| to produce a string result.
|
| :param dialect: a :class:`.Dialect` instance.
|
| copy(self, **kw: 'Any') -> 'Self'
|
| copy_value(self, value: 'Any') -> 'Any'
|
| dialect_impl(self, dialect: 'Dialect') -> 'TypeEngine[_T]'
| Return a dialect-specific implementation for this
| :class:`.TypeEngine`.
|
| evaluates_none(self) -> 'Self'
| Return a copy of this type which has the
| :attr:`.should_evaluate_none` flag set to True.
|
| E.g.::
|
| Table(
| "some_table",
| metadata,
| Column(
| String(50).evaluates_none(),
| nullable=True,
| server_default="no value",
| ),
| )
|
| The ORM uses this flag to indicate that a positive value of ``None``
| is passed to the column in an INSERT statement, rather than omitting
| the column from the INSERT statement which has the effect of firing
| off column-level defaults. It also allows for types which have
| special behavior associated with the Python None value to indicate
| that the value doesn't necessarily translate into SQL NULL; a
| prime example of this is a JSON type which may wish to persist the
| JSON value ``'null'``.
|
| In all cases, the actual NULL SQL value can be always be
| persisted in any column by using
| the :obj:`_expression.null` SQL construct in an INSERT statement
| or associated with an ORM-mapped attribute.
|
| .. note::
|
| The "evaluates none" flag does **not** apply to a value
| of ``None`` passed to :paramref:`_schema.Column.default` or
| :paramref:`_schema.Column.server_default`; in these cases,
| ``None``
| still means "no default".
|
| .. seealso::
|
| :ref:`session_forcing_null` - in the ORM documentation
|
| :paramref:`.postgresql.JSON.none_as_null` - PostgreSQL JSON
| interaction with this flag.
|
| :attr:`.TypeEngine.should_evaluate_none` - class-level flag
|
| get_dbapi_type(self, dbapi: 'DBAPIModule') -> 'Optional[Any]'
| Return the corresponding type object from the underlying DB-API, if
| any.
|
| This can be useful for calling ``setinputsizes()``, for example.
|
| result_processor(self, dialect: 'Dialect', coltype: 'object') -> 'Optional[_ResultProcessorType[_T]]'
| Return a conversion function for processing result row values.
|
| Returns a callable which will receive a result row column
| value as the sole positional argument and will return a value
| to return to the user.
|
| If processing is not necessary, the method should return ``None``.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.result_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.result_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_result_value`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| :param dialect: Dialect instance in use.
|
| :param coltype: DBAPI coltype argument received in cursor.description.
|
| with_variant(self, type_: '_TypeEngineArgument[Any]', *dialect_names: 'str') -> 'Self'
| Produce a copy of this type object that will utilize the given
| type when applied to the dialect of the given name.
|
| e.g.::
|
| from sqlalchemy.types import String
| from sqlalchemy.dialects import mysql
|
| string_type = String()
|
| string_type = string_type.with_variant(
| mysql.VARCHAR(collation="foo"), "mysql", "mariadb"
| )
|
| The variant mapping indicates that when this type is
| interpreted by a specific dialect, it will instead be
| transmuted into the given type, rather than using the
| primary type.
|
| .. versionchanged:: 2.0 the :meth:`_types.TypeEngine.with_variant`
| method now works with a :class:`_types.TypeEngine` object "in
| place", returning a copy of the original type rather than returning
| a wrapping object; the ``Variant`` class is no longer used.
|
| :param type\_: a :class:`.TypeEngine` that will be selected
| as a variant from the originating type, when a dialect
| of the given name is in use.
| :param \*dialect_names: one or more base names of the dialect which
| uses this type. (i.e. ``'postgresql'``, ``'mysql'``, etc.)
|
| .. versionchanged:: 2.0 multiple dialect names can be specified
| for one variant.
|
| .. seealso::
|
| :ref:`types_with_variant` - illustrates the use of
| :meth:`_types.TypeEngine.with_variant`.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.type_api.TypeEngine:
|
| __orig_bases__ = (<class 'sqlalchemy.sql.visitors.Visitable'>, typing....
|
| render_bind_cast = False
|
| render_literal_cast = False
|
| should_evaluate_none = False
|
| sort_key_function = None
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.visitors.Visitable:
|
| __class_getitem__(key: 'Any') -> 'Any'
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__() -> 'None'
| This method is called when a class is subclassed.
|
| The default implementation does nothing. It may be
| overridden to extend subclasses.
sqlalchemy.AdaptedConnection
Python Library Documentation: class AdaptedConnection in module sqlalchemy.engine.interfaces
class AdaptedConnection(builtins.object)
| Interface of an adapted connection object to support the DBAPI protocol.
|
| Used by asyncio dialects to provide a sync-style pep-249 facade on top
| of the asyncio connection/cursor API provided by the driver.
|
| .. versionadded:: 1.4.24
|
| Methods defined here:
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| run_async(self, fn: 'Callable[[Any], Awaitable[_T]]') -> '_T'
| Run the awaitable returned by the given function, which is passed
| the raw asyncio driver connection.
|
| This is used to invoke awaitable-only methods on the driver connection
| within the context of a "synchronous" method, like a connection
| pool event handler.
|
| E.g.::
|
| engine = create_async_engine(...)
|
|
| @event.listens_for(engine.sync_engine, "connect")
| def register_custom_types(
| dbapi_connection, # ...
| ):
| dbapi_connection.run_async(
| lambda connection: connection.set_type_codec(
| "MyCustomType", encoder, decoder, ...
| )
| )
|
| .. versionadded:: 1.4.30
|
| .. seealso::
|
| :ref:`asyncio_events_run_async`
|
| ----------------------------------------------------------------------
| Readonly properties defined here:
|
| driver_connection
| The connection object as returned by the driver after a connect.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'_connection': 'AsyncIODBAPIConnection'}
sqlalchemy.Alias
Python Library Documentation: class Alias in module sqlalchemy.sql.selectable
class Alias(sqlalchemy.sql.roles.DMLTableRole, FromClauseAlias)
| Alias(*arg: 'Any', **kw: 'Any')
|
| Represents an table or selectable alias (AS).
|
| Represents an alias, as typically applied to any table or
| sub-select within a SQL statement using the ``AS`` keyword (or
| without the keyword on certain databases such as Oracle Database).
|
| This object is constructed from the :func:`_expression.alias` module
| level function as well as the :meth:`_expression.FromClause.alias`
| method available
| on all :class:`_expression.FromClause` subclasses.
|
| .. seealso::
|
| :meth:`_expression.FromClause.alias`
|
| Method resolution order:
| Alias
| sqlalchemy.sql.roles.DMLTableRole
| FromClauseAlias
| AliasedReturnsRows
| NoInit
| NamedFromClause
| FromClause
| sqlalchemy.sql.roles.AnonymizedFromClauseRole
| sqlalchemy.sql.roles.StrictFromClauseRole
| sqlalchemy.sql.roles.FromClauseRole
| sqlalchemy.sql.roles.ColumnsClauseRole
| sqlalchemy.sql.roles.JoinTargetRole
| sqlalchemy.sql.roles.AllowsLambdaRole
| sqlalchemy.sql.roles.UsesInspection
| sqlalchemy.sql.roles.ColumnListRole
| sqlalchemy.sql.roles.StructuralRole
| Selectable
| ReturnsRows
| sqlalchemy.sql.roles.ReturnsRowsRole
| sqlalchemy.sql.roles.SQLRole
| sqlalchemy.sql.elements.DQLDMLClauseElement
| sqlalchemy.sql.elements.ClauseElement
| sqlalchemy.sql.annotation.SupportsWrappingAnnotations
| sqlalchemy.sql.annotation.SupportsAnnotations
| sqlalchemy.sql.cache_key.MemoizedHasCacheKey
| sqlalchemy.sql.cache_key.HasCacheKey
| sqlalchemy.util.langhelpers.HasMemoized
| sqlalchemy.sql.traversals.HasCopyInternals
| sqlalchemy.sql.visitors.ExternallyTraversible
| sqlalchemy.sql.visitors.HasTraverseInternals
| sqlalchemy.sql.elements.CompilerElement
| sqlalchemy.sql.visitors.Visitable
| builtins.object
|
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'element': 'FromClause'}
|
| __visit_name__ = 'alias'
|
| inherit_cache = True
|
| ----------------------------------------------------------------------
| Methods inherited from FromClauseAlias:
|
| description(...)
|
| ----------------------------------------------------------------------
| Methods inherited from AliasedReturnsRows:
|
| implicit_returning(...)
|
| 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.
|
| ----------------------------------------------------------------------
| Readonly properties inherited from AliasedReturnsRows:
|
| original
| Legacy for dialects that are referring to Alias.original.
|
| ----------------------------------------------------------------------
| Methods inherited from NoInit:
|
| __init__(self, *arg: 'Any', **kw: 'Any')
| Initialize self. See help(type(self)) for accurate signature.
|
| ----------------------------------------------------------------------
| Methods inherited from NamedFromClause:
|
| table_valued(self) -> 'TableValuedColumn[Any]'
| Return a :class:`_sql.TableValuedColumn` object for this
| :class:`_expression.FromClause`.
|
| A :class:`_sql.TableValuedColumn` is a :class:`_sql.ColumnElement` that
| represents a complete row in a table. Support for this construct is
| backend dependent, and is supported in various forms by backends
| such as PostgreSQL, Oracle Database and SQL Server.
|
| E.g.:
|
| .. sourcecode:: pycon+sql
|
| >>> from sqlalchemy import select, column, func, table
| >>> a = table("a", column("id"), column("x"), column("y"))
| >>> stmt = select(func.row_to_json(a.table_valued()))
| >>> print(stmt)
| {printsql}SELECT row_to_json(a) AS row_to_json_1
| FROM a
|
| .. versionadded:: 1.4.0b2
|
| .. seealso::
|
| :ref:`tutorial_functions` - in the :ref:`unified_tutorial`
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from NamedFromClause:
|
| named_with_column = True
|
| ----------------------------------------------------------------------
| Methods inherited from FromClause:
|
| alias(self, name: 'Optional[str]' = None, flat: 'bool' = False) -> 'NamedFromClause'
| 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`
|
| c(...)
| A synonym for :attr:`.FromClause.columns`
|
| :return: a :class:`.ColumnCollection`
|
| columns(...)
| 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.
|
| entity_namespace(...)
| 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.
|
| exported_columns(...)
| A :class:`_expression.ColumnCollection`
| that represents the "exported"
| columns of this :class:`_expression.Selectable`.
|
| 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`
|
| foreign_keys(...)
| Return the collection of :class:`_schema.ForeignKey` marker objects
| which this FromClause references.
|
| Each :class:`_schema.ForeignKey` is a member of a
| :class:`_schema.Table`-wide
| :class:`_schema.ForeignKeyConstraint`.
|
| .. seealso::
|
| :attr:`_schema.Table.foreign_key_constraints`
|
| 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
|
| 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`
|
| primary_key(...)
| 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.
|
| select(self) -> 'Select[Any]'
| 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.
|
| 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
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from FromClause:
|
| is_selectable = True
|
| schema = None
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.AllowsLambdaRole:
|
| allows_lambda = True
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.UsesInspection:
|
| uses_inspection = True
|
| ----------------------------------------------------------------------
| Methods inherited from Selectable:
|
| 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.
|
| 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.
|
| 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`.
|
| .. deprecated:: 1.4 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.
|
| ----------------------------------------------------------------------
| Readonly properties inherited from ReturnsRows:
|
| selectable
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.elements.ClauseElement:
|
| __bool__(self)
|
| __getstate__(self)
| Helper for pickle.
|
| __invert__(self)
|
| __repr__(self)
| Return repr(self).
|
| compare(self, other: 'ClauseElement', **kw: 'Any') -> 'bool'
| Compare this :class:`_expression.ClauseElement` to
| the given :class:`_expression.ClauseElement`.
|
| Subclasses should override the default behavior, which is a
| straight identity comparison.
|
| \**kw are arguments consumed by subclass ``compare()`` methods and
| may be used to modify the criteria for comparison
| (see :class:`_expression.ColumnElement`).
|
| params(self, _ClauseElement__optionaldict: 'Optional[Mapping[str, Any]]' = None, **kwargs: 'Any') -> 'Self'
| Return a copy with :func:`_expression.bindparam` elements
| replaced.
|
| Returns a copy of this ClauseElement with
| :func:`_expression.bindparam`
| elements replaced with values taken from the given dictionary::
|
| >>> clause = column("x") + bindparam("foo")
| >>> print(clause.compile().params)
| {'foo':None}
| >>> print(clause.params({"foo": 7}).compile().params)
| {'foo':7}
|
| self_group(self, against: 'Optional[OperatorType]' = None) -> 'ClauseElement'
| 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.
|
| unique_params(self, _ClauseElement__optionaldict: 'Optional[Dict[str, Any]]' = None, **kwargs: 'Any') -> 'Self'
| Return a copy with :func:`_expression.bindparam` elements
| replaced.
|
| Same functionality as :meth:`_expression.ClauseElement.params`,
| except adds `unique=True`
| to affected bind parameters so that multiple statements can be
| used.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.elements.ClauseElement:
|
| is_clause_element = True
|
| is_dml = False
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_instancemethod(fn: '_F') -> '_F'
| Decorate a method memoize its return value.
|
| :meta private:
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_attribute = <class 'sqlalchemy.util.langhelpers.HasMemoized.m...
| A read-only @property that is only evaluated once.
|
| :meta private:
|
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.visitors.HasTraverseInternals:
|
| get_children(self, *, omit_attrs: 'Tuple[str, ...]' = (), **kw: 'Any') -> 'Iterable[HasTraverseInternals]'
| Return immediate child :class:`.visitors.HasTraverseInternals`
| elements of this :class:`.visitors.HasTraverseInternals`.
|
| This is used for visit traversal.
|
| \**kw may contain flags that change the collection that is
| returned, for example to return a subset of items in order to
| cut down on larger traversals, or to return child items from a
| different context (such as schema-level collections instead of
| clause-level).
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.elements.CompilerElement:
|
| __str__(self) -> 'str'
| Return str(self).
|
| compile(self, bind: 'Optional[_HasDialect]' = None, dialect: 'Optional[Dialect]' = None, **kw: 'Any') -> 'Compiled'
| Compile this SQL expression.
|
| The return value is a :class:`~.Compiled` object.
| Calling ``str()`` or ``unicode()`` on the returned value will yield a
| string representation of the result. The
| :class:`~.Compiled` object also can return a
| dictionary of bind parameter names and values
| using the ``params`` accessor.
|
| :param bind: An :class:`.Connection` or :class:`.Engine` which
| can provide a :class:`.Dialect` in order to generate a
| :class:`.Compiled` object. If the ``bind`` and
| ``dialect`` parameters are both omitted, a default SQL compiler
| is used.
|
| :param column_keys: Used for INSERT and UPDATE statements, a list of
| column names which should be present in the VALUES clause of the
| compiled statement. If ``None``, all columns from the target table
| object are rendered.
|
| :param dialect: A :class:`.Dialect` instance which can generate
| a :class:`.Compiled` object. This argument takes precedence over
| the ``bind`` argument.
|
| :param compile_kwargs: optional dictionary of additional parameters
| that will be passed through to the compiler within all "visit"
| methods. This allows any custom flag to be passed through to
| a custom compilation construct, for example. It is also used
| for the case of passing the ``literal_binds`` flag through::
|
| from sqlalchemy.sql import table, column, select
|
| t = table("t", column("x"))
|
| s = select(t).where(t.c.x == 5)
|
| print(s.compile(compile_kwargs={"literal_binds": True}))
|
| .. seealso::
|
| :ref:`faq_sql_expression_string`
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.elements.CompilerElement:
|
| stringify_dialect = 'default'
|
| supports_execution = False
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.visitors.Visitable:
|
| __class_getitem__(key: 'Any') -> 'Any'
|
| __init_subclass__() -> 'None'
| This method is called when a class is subclassed.
|
| The default implementation does nothing. It may be
| overridden to extend subclasses.
sqlalchemy.AliasedReturnsRows
Python Library Documentation: class AliasedReturnsRows in module sqlalchemy.sql.selectable
class AliasedReturnsRows(NoInit, NamedFromClause)
| AliasedReturnsRows(*arg: 'Any', **kw: 'Any')
|
| Base class of aliases against tables, subqueries, and other
| selectables.
|
| Method resolution order:
| AliasedReturnsRows
| NoInit
| NamedFromClause
| FromClause
| sqlalchemy.sql.roles.AnonymizedFromClauseRole
| sqlalchemy.sql.roles.StrictFromClauseRole
| sqlalchemy.sql.roles.FromClauseRole
| sqlalchemy.sql.roles.ColumnsClauseRole
| sqlalchemy.sql.roles.JoinTargetRole
| sqlalchemy.sql.roles.AllowsLambdaRole
| sqlalchemy.sql.roles.UsesInspection
| sqlalchemy.sql.roles.ColumnListRole
| sqlalchemy.sql.roles.StructuralRole
| Selectable
| ReturnsRows
| sqlalchemy.sql.roles.ReturnsRowsRole
| sqlalchemy.sql.roles.SQLRole
| sqlalchemy.sql.elements.DQLDMLClauseElement
| sqlalchemy.sql.elements.ClauseElement
| sqlalchemy.sql.annotation.SupportsWrappingAnnotations
| sqlalchemy.sql.annotation.SupportsAnnotations
| sqlalchemy.sql.cache_key.MemoizedHasCacheKey
| sqlalchemy.sql.cache_key.HasCacheKey
| sqlalchemy.util.langhelpers.HasMemoized
| sqlalchemy.sql.traversals.HasCopyInternals
| sqlalchemy.sql.visitors.ExternallyTraversible
| sqlalchemy.sql.visitors.HasTraverseInternals
| sqlalchemy.sql.elements.CompilerElement
| sqlalchemy.sql.visitors.Visitable
| builtins.object
|
| Methods defined here:
|
| description(...)
|
| implicit_returning(...)
|
| 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.
|
| ----------------------------------------------------------------------
| Readonly properties defined here:
|
| original
| Legacy for dialects that are referring to Alias.original.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'_traverse_internals': '_TraverseInternalsType', 'e...
|
| ----------------------------------------------------------------------
| Methods inherited from NoInit:
|
| __init__(self, *arg: 'Any', **kw: 'Any')
| Initialize self. See help(type(self)) for accurate signature.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from NoInit:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Methods inherited from NamedFromClause:
|
| table_valued(self) -> 'TableValuedColumn[Any]'
| Return a :class:`_sql.TableValuedColumn` object for this
| :class:`_expression.FromClause`.
|
| A :class:`_sql.TableValuedColumn` is a :class:`_sql.ColumnElement` that
| represents a complete row in a table. Support for this construct is
| backend dependent, and is supported in various forms by backends
| such as PostgreSQL, Oracle Database and SQL Server.
|
| E.g.:
|
| .. sourcecode:: pycon+sql
|
| >>> from sqlalchemy import select, column, func, table
| >>> a = table("a", column("id"), column("x"), column("y"))
| >>> stmt = select(func.row_to_json(a.table_valued()))
| >>> print(stmt)
| {printsql}SELECT row_to_json(a) AS row_to_json_1
| FROM a
|
| .. versionadded:: 1.4.0b2
|
| .. seealso::
|
| :ref:`tutorial_functions` - in the :ref:`unified_tutorial`
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from NamedFromClause:
|
| named_with_column = True
|
| ----------------------------------------------------------------------
| Methods inherited from FromClause:
|
| alias(self, name: 'Optional[str]' = None, flat: 'bool' = False) -> 'NamedFromClause'
| 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`
|
| c(...)
| A synonym for :attr:`.FromClause.columns`
|
| :return: a :class:`.ColumnCollection`
|
| columns(...)
| 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.
|
| entity_namespace(...)
| 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.
|
| exported_columns(...)
| A :class:`_expression.ColumnCollection`
| that represents the "exported"
| columns of this :class:`_expression.Selectable`.
|
| 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`
|
| foreign_keys(...)
| Return the collection of :class:`_schema.ForeignKey` marker objects
| which this FromClause references.
|
| Each :class:`_schema.ForeignKey` is a member of a
| :class:`_schema.Table`-wide
| :class:`_schema.ForeignKeyConstraint`.
|
| .. seealso::
|
| :attr:`_schema.Table.foreign_key_constraints`
|
| 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
|
| 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`
|
| primary_key(...)
| 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.
|
| select(self) -> 'Select[Any]'
| 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.
|
| 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
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from FromClause:
|
| __visit_name__ = 'fromclause'
|
| is_selectable = True
|
| schema = None
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.AllowsLambdaRole:
|
| allows_lambda = True
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.UsesInspection:
|
| uses_inspection = True
|
| ----------------------------------------------------------------------
| Methods inherited from Selectable:
|
| 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.
|
| 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.
|
| 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`.
|
| .. deprecated:: 1.4 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.
|
| ----------------------------------------------------------------------
| Readonly properties inherited from ReturnsRows:
|
| selectable
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.elements.ClauseElement:
|
| __bool__(self)
|
| __getstate__(self)
| Helper for pickle.
|
| __invert__(self)
|
| __repr__(self)
| Return repr(self).
|
| compare(self, other: 'ClauseElement', **kw: 'Any') -> 'bool'
| Compare this :class:`_expression.ClauseElement` to
| the given :class:`_expression.ClauseElement`.
|
| Subclasses should override the default behavior, which is a
| straight identity comparison.
|
| \**kw are arguments consumed by subclass ``compare()`` methods and
| may be used to modify the criteria for comparison
| (see :class:`_expression.ColumnElement`).
|
| params(self, _ClauseElement__optionaldict: 'Optional[Mapping[str, Any]]' = None, **kwargs: 'Any') -> 'Self'
| Return a copy with :func:`_expression.bindparam` elements
| replaced.
|
| Returns a copy of this ClauseElement with
| :func:`_expression.bindparam`
| elements replaced with values taken from the given dictionary::
|
| >>> clause = column("x") + bindparam("foo")
| >>> print(clause.compile().params)
| {'foo':None}
| >>> print(clause.params({"foo": 7}).compile().params)
| {'foo':7}
|
| self_group(self, against: 'Optional[OperatorType]' = None) -> 'ClauseElement'
| 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.
|
| unique_params(self, _ClauseElement__optionaldict: 'Optional[Dict[str, Any]]' = None, **kwargs: 'Any') -> 'Self'
| Return a copy with :func:`_expression.bindparam` elements
| replaced.
|
| Same functionality as :meth:`_expression.ClauseElement.params`,
| except adds `unique=True`
| to affected bind parameters so that multiple statements can be
| used.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.elements.ClauseElement:
|
| is_clause_element = True
|
| is_dml = False
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.cache_key.HasCacheKey:
|
| inherit_cache = None
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_instancemethod(fn: '_F') -> '_F'
| Decorate a method memoize its return value.
|
| :meta private:
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_attribute = <class 'sqlalchemy.util.langhelpers.HasMemoized.m...
| A read-only @property that is only evaluated once.
|
| :meta private:
|
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.visitors.HasTraverseInternals:
|
| get_children(self, *, omit_attrs: 'Tuple[str, ...]' = (), **kw: 'Any') -> 'Iterable[HasTraverseInternals]'
| Return immediate child :class:`.visitors.HasTraverseInternals`
| elements of this :class:`.visitors.HasTraverseInternals`.
|
| This is used for visit traversal.
|
| \**kw may contain flags that change the collection that is
| returned, for example to return a subset of items in order to
| cut down on larger traversals, or to return child items from a
| different context (such as schema-level collections instead of
| clause-level).
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.elements.CompilerElement:
|
| __str__(self) -> 'str'
| Return str(self).
|
| compile(self, bind: 'Optional[_HasDialect]' = None, dialect: 'Optional[Dialect]' = None, **kw: 'Any') -> 'Compiled'
| Compile this SQL expression.
|
| The return value is a :class:`~.Compiled` object.
| Calling ``str()`` or ``unicode()`` on the returned value will yield a
| string representation of the result. The
| :class:`~.Compiled` object also can return a
| dictionary of bind parameter names and values
| using the ``params`` accessor.
|
| :param bind: An :class:`.Connection` or :class:`.Engine` which
| can provide a :class:`.Dialect` in order to generate a
| :class:`.Compiled` object. If the ``bind`` and
| ``dialect`` parameters are both omitted, a default SQL compiler
| is used.
|
| :param column_keys: Used for INSERT and UPDATE statements, a list of
| column names which should be present in the VALUES clause of the
| compiled statement. If ``None``, all columns from the target table
| object are rendered.
|
| :param dialect: A :class:`.Dialect` instance which can generate
| a :class:`.Compiled` object. This argument takes precedence over
| the ``bind`` argument.
|
| :param compile_kwargs: optional dictionary of additional parameters
| that will be passed through to the compiler within all "visit"
| methods. This allows any custom flag to be passed through to
| a custom compilation construct, for example. It is also used
| for the case of passing the ``literal_binds`` flag through::
|
| from sqlalchemy.sql import table, column, select
|
| t = table("t", column("x"))
|
| s = select(t).where(t.c.x == 5)
|
| print(s.compile(compile_kwargs={"literal_binds": True}))
|
| .. seealso::
|
| :ref:`faq_sql_expression_string`
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.elements.CompilerElement:
|
| stringify_dialect = 'default'
|
| supports_execution = False
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.visitors.Visitable:
|
| __class_getitem__(key: 'Any') -> 'Any'
|
| __init_subclass__() -> 'None'
| This method is called when a class is subclassed.
|
| The default implementation does nothing. It may be
| overridden to extend subclasses.
sqlalchemy.Any
Python Library Documentation: class Any in module typing class Any(builtins.object) | Any(*args, **kwargs) | | Special type indicating an unconstrained type. | | - Any is compatible with every type. | - Any assumed to have all methods. | - All values assumed to be instances of Any. | | Note that all the above statements are true from the point of view of | static type checkers. At runtime, Any should not be used with instance | checks. | | Static methods defined here: | | __new__(cls, *args, **kwargs) | Create and return a new object. See help(type) for accurate signature. | | ---------------------------------------------------------------------- | Data descriptors defined here: | | __dict__ | dictionary for instance variables | | __weakref__ | list of weak references to the object
sqlalchemy.AssertionPool
Python Library Documentation: class AssertionPool in module sqlalchemy.pool.impl
class AssertionPool(sqlalchemy.pool.base.Pool)
| AssertionPool(*args: 'Any', **kw: 'Any')
|
| A :class:`_pool.Pool` that allows at most one checked out connection at
| any given time.
|
| This will raise an exception if more than one connection is checked out
| at a time. Useful for debugging code that is using more connections
| than desired.
|
| The :class:`.AssertionPool` class **is compatible** with asyncio and
| :func:`_asyncio.create_async_engine`.
|
| Method resolution order:
| AssertionPool
| sqlalchemy.pool.base.Pool
| sqlalchemy.log.Identified
| sqlalchemy.event.registry.EventTarget
| builtins.object
|
| Methods defined here:
|
| __init__(self, *args: 'Any', **kw: 'Any')
| Construct a Pool.
|
| :param creator: a callable function that returns a DB-API
| connection object. The function will be called with
| parameters.
|
| :param recycle: If set to a value other than -1, number of
| seconds between connection recycling, which means upon
| checkout, if this timeout is surpassed the connection will be
| closed and replaced with a newly opened connection. Defaults to -1.
|
| :param logging_name: String identifier which will be used within
| the "name" field of logging records generated within the
| "sqlalchemy.pool" logger. Defaults to a hexstring of the object's
| id.
|
| :param echo: if True, the connection pool will log
| informational output such as when connections are invalidated
| as well as when connections are recycled to the default log handler,
| which defaults to ``sys.stdout`` for output.. If set to the string
| ``"debug"``, the logging will include pool checkouts and checkins.
|
| The :paramref:`_pool.Pool.echo` parameter can also be set from the
| :func:`_sa.create_engine` call by using the
| :paramref:`_sa.create_engine.echo_pool` parameter.
|
| .. seealso::
|
| :ref:`dbengine_logging` - further detail on how to configure
| logging.
|
| :param reset_on_return: Determine steps to take on
| connections as they are returned to the pool, which were
| not otherwise handled by a :class:`_engine.Connection`.
| Available from :func:`_sa.create_engine` via the
| :paramref:`_sa.create_engine.pool_reset_on_return` parameter.
|
| :paramref:`_pool.Pool.reset_on_return` can have any of these values:
|
| * ``"rollback"`` - call rollback() on the connection,
| to release locks and transaction resources.
| This is the default value. The vast majority
| of use cases should leave this value set.
| * ``"commit"`` - call commit() on the connection,
| to release locks and transaction resources.
| A commit here may be desirable for databases that
| cache query plans if a commit is emitted,
| such as Microsoft SQL Server. However, this
| value is more dangerous than 'rollback' because
| any data changes present on the transaction
| are committed unconditionally.
| * ``None`` - don't do anything on the connection.
| This setting may be appropriate if the database / DBAPI
| works in pure "autocommit" mode at all times, or if
| a custom reset handler is established using the
| :meth:`.PoolEvents.reset` event handler.
|
| * ``True`` - same as 'rollback', this is here for
| backwards compatibility.
| * ``False`` - same as None, this is here for
| backwards compatibility.
|
| For further customization of reset on return, the
| :meth:`.PoolEvents.reset` event hook may be used which can perform
| any connection activity desired on reset.
|
| .. seealso::
|
| :ref:`pool_reset_on_return`
|
| :meth:`.PoolEvents.reset`
|
| :param events: a list of 2-tuples, each of the form
| ``(callable, target)`` which will be passed to :func:`.event.listen`
| upon construction. Provided here so that event listeners
| can be assigned via :func:`_sa.create_engine` before dialect-level
| listeners are applied.
|
| :param dialect: a :class:`.Dialect` that will handle the job
| of calling rollback(), close(), or commit() on DBAPI connections.
| If omitted, a built-in "stub" dialect is used. Applications that
| make use of :func:`_sa.create_engine` should not use this parameter
| as it is handled by the engine creation strategy.
|
| :param pre_ping: if True, the pool will emit a "ping" (typically
| "SELECT 1", but is dialect-specific) on the connection
| upon checkout, to test if the connection is alive or not. If not,
| the connection is transparently re-connected and upon success, all
| other pooled connections established prior to that timestamp are
| invalidated. Requires that a dialect is passed as well to
| interpret the disconnection error.
|
| .. versionadded:: 1.2
|
| dispose(self) -> 'None'
| Dispose of this pool.
|
| This method leaves the possibility of checked-out connections
| remaining open, as it only affects connections that are
| idle in the pool.
|
| .. seealso::
|
| :meth:`Pool.recreate`
|
| recreate(self) -> 'AssertionPool'
| Return a new :class:`_pool.Pool`, of the same class as this one
| and configured with identical creation arguments.
|
| This method is used in conjunction with :meth:`dispose`
| to close out an entire :class:`_pool.Pool` and create a new one in
| its place.
|
| status(self) -> 'str'
| Returns a brief description of the state of this pool.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'_checkout_traceback': 'Optional[List[str]]', '_con...
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.pool.base.Pool:
|
| connect(self) -> 'PoolProxiedConnection'
| Return a DBAPI connection from the pool.
|
| The connection is instrumented such that when its
| ``close()`` method is called, the connection will be returned to
| the pool.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from sqlalchemy.pool.base.Pool:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.pool.base.Pool:
|
| dispatch = <sqlalchemy.event.base.PoolEventsDispatch object>
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.log.Identified:
|
| logging_name = None
sqlalchemy.AsyncAdaptedQueuePool
Python Library Documentation: class AsyncAdaptedQueuePool in module sqlalchemy.pool.impl
class AsyncAdaptedQueuePool(QueuePool)
| AsyncAdaptedQueuePool(creator: 'Union[_CreatorFnType, _CreatorWRecFnType]', pool_size: 'int' = 5, max_overflow: 'int' = 10, timeout: 'float' = 30.0, use_lifo: 'bool' = False, **kw: 'Any')
|
| An asyncio-compatible version of :class:`.QueuePool`.
|
| This pool is used by default when using :class:`.AsyncEngine` engines that
| were generated from :func:`_asyncio.create_async_engine`. It uses an
| asyncio-compatible queue implementation that does not use
| ``threading.Lock``.
|
| The arguments and operation of :class:`.AsyncAdaptedQueuePool` are
| otherwise identical to that of :class:`.QueuePool`.
|
| Method resolution order:
| AsyncAdaptedQueuePool
| QueuePool
| sqlalchemy.pool.base.Pool
| sqlalchemy.log.Identified
| sqlalchemy.event.registry.EventTarget
| builtins.object
|
| Data and other attributes defined here:
|
| __annotations__ = {'_queue_class': 'Type[sqla_queue.QueueCommon[Connec...
|
| ----------------------------------------------------------------------
| Methods inherited from QueuePool:
|
| __init__(self, creator: 'Union[_CreatorFnType, _CreatorWRecFnType]', pool_size: 'int' = 5, max_overflow: 'int' = 10, timeout: 'float' = 30.0, use_lifo: 'bool' = False, **kw: 'Any')
| Construct a QueuePool.
|
| :param creator: a callable function that returns a DB-API
| connection object, same as that of :paramref:`_pool.Pool.creator`.
|
| :param pool_size: The size of the pool to be maintained,
| defaults to 5. This is the largest number of connections that
| will be kept persistently in the pool. Note that the pool
| begins with no connections; once this number of connections
| is requested, that number of connections will remain.
| ``pool_size`` can be set to 0 to indicate no size limit; to
| disable pooling, use a :class:`~sqlalchemy.pool.NullPool`
| instead.
|
| :param max_overflow: The maximum overflow size of the
| pool. When the number of checked-out connections reaches the
| size set in pool_size, additional connections will be
| returned up to this limit. When those additional connections
| are returned to the pool, they are disconnected and
| discarded. It follows then that the total number of
| simultaneous connections the pool will allow is pool_size +
| `max_overflow`, and the total number of "sleeping"
| connections the pool will allow is pool_size. `max_overflow`
| can be set to -1 to indicate no overflow limit; no limit
| will be placed on the total number of concurrent
| connections. Defaults to 10.
|
| :param timeout: The number of seconds to wait before giving up
| on returning a connection. Defaults to 30.0. This can be a float
| but is subject to the limitations of Python time functions which
| may not be reliable in the tens of milliseconds.
|
| :param use_lifo: use LIFO (last-in-first-out) when retrieving
| connections instead of FIFO (first-in-first-out). Using LIFO, a
| server-side timeout scheme can reduce the number of connections used
| during non-peak periods of use. When planning for server-side
| timeouts, ensure that a recycle or pre-ping strategy is in use to
| gracefully handle stale connections.
|
| .. versionadded:: 1.3
|
| .. seealso::
|
| :ref:`pool_use_lifo`
|
| :ref:`pool_disconnects`
|
| :param \**kw: Other keyword arguments including
| :paramref:`_pool.Pool.recycle`, :paramref:`_pool.Pool.echo`,
| :paramref:`_pool.Pool.reset_on_return` and others are passed to the
| :class:`_pool.Pool` constructor.
|
| checkedin(self) -> 'int'
|
| checkedout(self) -> 'int'
|
| dispose(self) -> 'None'
| Dispose of this pool.
|
| This method leaves the possibility of checked-out connections
| remaining open, as it only affects connections that are
| idle in the pool.
|
| .. seealso::
|
| :meth:`Pool.recreate`
|
| overflow(self) -> 'int'
|
| recreate(self) -> 'QueuePool'
| Return a new :class:`_pool.Pool`, of the same class as this one
| and configured with identical creation arguments.
|
| This method is used in conjunction with :meth:`dispose`
| to close out an entire :class:`_pool.Pool` and create a new one in
| its place.
|
| size(self) -> 'int'
|
| status(self) -> 'str'
| Returns a brief description of the state of this pool.
|
| timeout(self) -> 'float'
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.pool.base.Pool:
|
| connect(self) -> 'PoolProxiedConnection'
| Return a DBAPI connection from the pool.
|
| The connection is instrumented such that when its
| ``close()`` method is called, the connection will be returned to
| the pool.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from sqlalchemy.pool.base.Pool:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.pool.base.Pool:
|
| dispatch = <sqlalchemy.event.base.PoolEventsDispatch object>
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.log.Identified:
|
| logging_name = None
sqlalchemy.BIGINT
Python Library Documentation: class BIGINT in module sqlalchemy.sql.sqltypes
class BIGINT(BigInteger)
| The SQL BIGINT type.
|
| .. seealso::
|
| :class:`_types.BigInteger` - documentation for the base type.
|
| Method resolution order:
| BIGINT
| BigInteger
| Integer
| HasExpressionLookup
| sqlalchemy.sql.type_api.TypeEngineMixin
| sqlalchemy.sql.type_api.TypeEngine
| sqlalchemy.sql.visitors.Visitable
| typing.Generic
| builtins.object
|
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| __parameters__ = ()
|
| __visit_name__ = 'BIGINT'
|
| ----------------------------------------------------------------------
| Methods inherited from Integer:
|
| get_dbapi_type(self, dbapi)
| Return the corresponding type object from the underlying DB-API, if
| any.
|
| This can be useful for calling ``setinputsizes()``, for example.
|
| literal_processor(self, dialect)
| Return a conversion function for processing literal values that are
| to be rendered directly without using binds.
|
| This function is used when the compiler makes use of the
| "literal_binds" flag, typically used in DDL generation as well
| as in certain scenarios where backends don't accept bound parameters.
|
| Returns a callable which will receive a literal Python value
| as the sole positional argument and will return a string representation
| to be rendered in a SQL statement.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.literal_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.literal_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_literal_param`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| ----------------------------------------------------------------------
| Readonly properties inherited from Integer:
|
| python_type
| Return the Python type object expected to be returned
| by instances of this type, if known.
|
| Basically, for those types which enforce a return type,
| or are known across the board to do such for all common
| DBAPIs (like ``int`` for example), will return that type.
|
| If a return type is not defined, raises
| ``NotImplementedError``.
|
| Note that any type also accommodates NULL in SQL which
| means you can also get back ``None`` from any type
| in practice.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from HasExpressionLookup:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from HasExpressionLookup:
|
| Comparator = <class 'sqlalchemy.sql.sqltypes.HasExpressionLookup.Compa...
|
| comparator_factory = <class 'sqlalchemy.sql.sqltypes.HasExpressionLook...
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.type_api.TypeEngine:
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| __str__(self) -> 'str'
| Return str(self).
|
| adapt(self, cls: 'Type[Union[TypeEngine[Any], TypeEngineMixin]]', **kw: 'Any') -> 'TypeEngine[Any]'
| Produce an "adapted" form of this type, given an "impl" class
| to work with.
|
| This method is used internally to associate generic
| types with "implementation" types that are specific to a particular
| dialect.
|
| as_generic(self, allow_nulltype: 'bool' = False) -> 'TypeEngine[_T]'
| Return an instance of the generic type corresponding to this type
| using heuristic rule. The method may be overridden if this
| heuristic rule is not sufficient.
|
| >>> from sqlalchemy.dialects.mysql import INTEGER
| >>> INTEGER(display_width=4).as_generic()
| Integer()
|
| >>> from sqlalchemy.dialects.mysql import NVARCHAR
| >>> NVARCHAR(length=100).as_generic()
| Unicode(length=100)
|
| .. versionadded:: 1.4.0b2
|
|
| .. seealso::
|
| :ref:`metadata_reflection_dbagnostic_types` - describes the
| use of :meth:`_types.TypeEngine.as_generic` in conjunction with
| the :meth:`_sql.DDLEvents.column_reflect` event, which is its
| intended use.
|
| bind_expression(self, bindvalue: 'BindParameter[_T]') -> 'Optional[ColumnElement[_T]]'
| Given a bind value (i.e. a :class:`.BindParameter` instance),
| return a SQL expression in its place.
|
| This is typically a SQL function that wraps the existing bound
| parameter within the statement. It is used for special data types
| that require literals being wrapped in some special database function
| in order to coerce an application-level value into a database-specific
| format. It is the SQL analogue of the
| :meth:`.TypeEngine.bind_processor` method.
|
| This method is called during the **SQL compilation** phase of a
| statement, when rendering a SQL string. It is **not** called
| against specific values.
|
| Note that this method, when implemented, should always return
| the exact same structure, without any conditional logic, as it
| may be used in an executemany() call against an arbitrary number
| of bound parameter sets.
|
| .. note::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.bind_expression`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.bind_expression`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.bind_expression`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| .. seealso::
|
| :ref:`types_sql_value_processing`
|
| bind_processor(self, dialect: 'Dialect') -> 'Optional[_BindProcessorType[_T]]'
| Return a conversion function for processing bind values.
|
| Returns a callable which will receive a bind parameter value
| as the sole positional argument and will return a value to
| send to the DB-API.
|
| If processing is not necessary, the method should return ``None``.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.bind_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.bind_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_bind_param`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
|
| :param dialect: Dialect instance in use.
|
| coerce_compared_value(self, op: 'Optional[OperatorType]', value: 'Any') -> 'TypeEngine[Any]'
| Suggest a type for a 'coerced' Python value in an expression.
|
| Given an operator and value, gives the type a chance
| to return a type which the value should be coerced into.
|
| The default behavior here is conservative; if the right-hand
| side is already coerced into a SQL type based on its
| Python type, it is usually left alone.
|
| End-user functionality extension here should generally be via
| :class:`.TypeDecorator`, which provides more liberal behavior in that
| it defaults to coercing the other side of the expression into this
| type, thus applying special Python conversions above and beyond those
| needed by the DBAPI to both ides. It also provides the public method
| :meth:`.TypeDecorator.coerce_compared_value` which is intended for
| end-user customization of this behavior.
|
| column_expression(self, colexpr: 'ColumnElement[_T]') -> 'Optional[ColumnElement[_T]]'
| Given a SELECT column expression, return a wrapping SQL expression.
|
| This is typically a SQL function that wraps a column expression
| as rendered in the columns clause of a SELECT statement.
| It is used for special data types that require
| columns to be wrapped in some special database function in order
| to coerce the value before being sent back to the application.
| It is the SQL analogue of the :meth:`.TypeEngine.result_processor`
| method.
|
| .. note:: The :func:`.TypeEngine.column_expression` method is applied
| only to the **outermost columns clause** of a SELECT statement, that
| is, the columns that are to be delivered directly into the returned
| result rows. It does **not** apply to the columns clause inside
| of subqueries. This necessarily avoids double conversions against
| the column and only runs the conversion when ready to be returned
| to the client.
|
| This method is called during the **SQL compilation** phase of a
| statement, when rendering a SQL string. It is **not** called
| against specific values.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.column_expression`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.column_expression`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.column_expression`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
|
| .. seealso::
|
| :ref:`types_sql_value_processing`
|
| compare_values(self, x: 'Any', y: 'Any') -> 'bool'
| Compare two values for equality.
|
| compile(self, dialect: 'Optional[Dialect]' = None) -> 'str'
| Produce a string-compiled form of this :class:`.TypeEngine`.
|
| When called with no arguments, uses a "default" dialect
| to produce a string result.
|
| :param dialect: a :class:`.Dialect` instance.
|
| copy(self, **kw: 'Any') -> 'Self'
|
| copy_value(self, value: 'Any') -> 'Any'
|
| dialect_impl(self, dialect: 'Dialect') -> 'TypeEngine[_T]'
| Return a dialect-specific implementation for this
| :class:`.TypeEngine`.
|
| evaluates_none(self) -> 'Self'
| Return a copy of this type which has the
| :attr:`.should_evaluate_none` flag set to True.
|
| E.g.::
|
| Table(
| "some_table",
| metadata,
| Column(
| String(50).evaluates_none(),
| nullable=True,
| server_default="no value",
| ),
| )
|
| The ORM uses this flag to indicate that a positive value of ``None``
| is passed to the column in an INSERT statement, rather than omitting
| the column from the INSERT statement which has the effect of firing
| off column-level defaults. It also allows for types which have
| special behavior associated with the Python None value to indicate
| that the value doesn't necessarily translate into SQL NULL; a
| prime example of this is a JSON type which may wish to persist the
| JSON value ``'null'``.
|
| In all cases, the actual NULL SQL value can be always be
| persisted in any column by using
| the :obj:`_expression.null` SQL construct in an INSERT statement
| or associated with an ORM-mapped attribute.
|
| .. note::
|
| The "evaluates none" flag does **not** apply to a value
| of ``None`` passed to :paramref:`_schema.Column.default` or
| :paramref:`_schema.Column.server_default`; in these cases,
| ``None``
| still means "no default".
|
| .. seealso::
|
| :ref:`session_forcing_null` - in the ORM documentation
|
| :paramref:`.postgresql.JSON.none_as_null` - PostgreSQL JSON
| interaction with this flag.
|
| :attr:`.TypeEngine.should_evaluate_none` - class-level flag
|
| result_processor(self, dialect: 'Dialect', coltype: 'object') -> 'Optional[_ResultProcessorType[_T]]'
| Return a conversion function for processing result row values.
|
| Returns a callable which will receive a result row column
| value as the sole positional argument and will return a value
| to return to the user.
|
| If processing is not necessary, the method should return ``None``.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.result_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.result_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_result_value`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| :param dialect: Dialect instance in use.
|
| :param coltype: DBAPI coltype argument received in cursor.description.
|
| with_variant(self, type_: '_TypeEngineArgument[Any]', *dialect_names: 'str') -> 'Self'
| Produce a copy of this type object that will utilize the given
| type when applied to the dialect of the given name.
|
| e.g.::
|
| from sqlalchemy.types import String
| from sqlalchemy.dialects import mysql
|
| string_type = String()
|
| string_type = string_type.with_variant(
| mysql.VARCHAR(collation="foo"), "mysql", "mariadb"
| )
|
| The variant mapping indicates that when this type is
| interpreted by a specific dialect, it will instead be
| transmuted into the given type, rather than using the
| primary type.
|
| .. versionchanged:: 2.0 the :meth:`_types.TypeEngine.with_variant`
| method now works with a :class:`_types.TypeEngine` object "in
| place", returning a copy of the original type rather than returning
| a wrapping object; the ``Variant`` class is no longer used.
|
| :param type\_: a :class:`.TypeEngine` that will be selected
| as a variant from the originating type, when a dialect
| of the given name is in use.
| :param \*dialect_names: one or more base names of the dialect which
| uses this type. (i.e. ``'postgresql'``, ``'mysql'``, etc.)
|
| .. versionchanged:: 2.0 multiple dialect names can be specified
| for one variant.
|
| .. seealso::
|
| :ref:`types_with_variant` - illustrates the use of
| :meth:`_types.TypeEngine.with_variant`.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.type_api.TypeEngine:
|
| __orig_bases__ = (<class 'sqlalchemy.sql.visitors.Visitable'>, typing....
|
| hashable = True
|
| render_bind_cast = False
|
| render_literal_cast = False
|
| should_evaluate_none = False
|
| sort_key_function = None
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.visitors.Visitable:
|
| __class_getitem__(key: 'Any') -> 'Any'
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__() -> 'None'
| This method is called when a class is subclassed.
|
| The default implementation does nothing. It may be
| overridden to extend subclasses.
sqlalchemy.BINARY
Python Library Documentation: class BINARY in module sqlalchemy.sql.sqltypes
class BINARY(_Binary)
| BINARY(length: 'Optional[int]' = None)
|
| The SQL BINARY type.
|
| Method resolution order:
| BINARY
| _Binary
| sqlalchemy.sql.type_api.TypeEngine
| sqlalchemy.sql.visitors.Visitable
| typing.Generic
| builtins.object
|
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| __parameters__ = ()
|
| __visit_name__ = 'BINARY'
|
| ----------------------------------------------------------------------
| Methods inherited from _Binary:
|
| __init__(self, length: 'Optional[int]' = None)
| Initialize self. See help(type(self)) for accurate signature.
|
| bind_processor(self, dialect)
| Return a conversion function for processing bind values.
|
| Returns a callable which will receive a bind parameter value
| as the sole positional argument and will return a value to
| send to the DB-API.
|
| If processing is not necessary, the method should return ``None``.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.bind_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.bind_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_bind_param`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
|
| :param dialect: Dialect instance in use.
|
| coerce_compared_value(self, op, value)
| See :meth:`.TypeEngine.coerce_compared_value` for a description.
|
| get_dbapi_type(self, dbapi)
| Return the corresponding type object from the underlying DB-API, if
| any.
|
| This can be useful for calling ``setinputsizes()``, for example.
|
| literal_processor(self, dialect)
| Return a conversion function for processing literal values that are
| to be rendered directly without using binds.
|
| This function is used when the compiler makes use of the
| "literal_binds" flag, typically used in DDL generation as well
| as in certain scenarios where backends don't accept bound parameters.
|
| Returns a callable which will receive a literal Python value
| as the sole positional argument and will return a string representation
| to be rendered in a SQL statement.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.literal_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.literal_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_literal_param`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| result_processor(self, dialect, coltype)
| Return a conversion function for processing result row values.
|
| Returns a callable which will receive a result row column
| value as the sole positional argument and will return a value
| to return to the user.
|
| If processing is not necessary, the method should return ``None``.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.result_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.result_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_result_value`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| :param dialect: Dialect instance in use.
|
| :param coltype: DBAPI coltype argument received in cursor.description.
|
| ----------------------------------------------------------------------
| Readonly properties inherited from _Binary:
|
| python_type
| Return the Python type object expected to be returned
| by instances of this type, if known.
|
| Basically, for those types which enforce a return type,
| or are known across the board to do such for all common
| DBAPIs (like ``int`` for example), will return that type.
|
| If a return type is not defined, raises
| ``NotImplementedError``.
|
| Note that any type also accommodates NULL in SQL which
| means you can also get back ``None`` from any type
| in practice.
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.type_api.TypeEngine:
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| __str__(self) -> 'str'
| Return str(self).
|
| adapt(self, cls: 'Type[Union[TypeEngine[Any], TypeEngineMixin]]', **kw: 'Any') -> 'TypeEngine[Any]'
| Produce an "adapted" form of this type, given an "impl" class
| to work with.
|
| This method is used internally to associate generic
| types with "implementation" types that are specific to a particular
| dialect.
|
| as_generic(self, allow_nulltype: 'bool' = False) -> 'TypeEngine[_T]'
| Return an instance of the generic type corresponding to this type
| using heuristic rule. The method may be overridden if this
| heuristic rule is not sufficient.
|
| >>> from sqlalchemy.dialects.mysql import INTEGER
| >>> INTEGER(display_width=4).as_generic()
| Integer()
|
| >>> from sqlalchemy.dialects.mysql import NVARCHAR
| >>> NVARCHAR(length=100).as_generic()
| Unicode(length=100)
|
| .. versionadded:: 1.4.0b2
|
|
| .. seealso::
|
| :ref:`metadata_reflection_dbagnostic_types` - describes the
| use of :meth:`_types.TypeEngine.as_generic` in conjunction with
| the :meth:`_sql.DDLEvents.column_reflect` event, which is its
| intended use.
|
| bind_expression(self, bindvalue: 'BindParameter[_T]') -> 'Optional[ColumnElement[_T]]'
| Given a bind value (i.e. a :class:`.BindParameter` instance),
| return a SQL expression in its place.
|
| This is typically a SQL function that wraps the existing bound
| parameter within the statement. It is used for special data types
| that require literals being wrapped in some special database function
| in order to coerce an application-level value into a database-specific
| format. It is the SQL analogue of the
| :meth:`.TypeEngine.bind_processor` method.
|
| This method is called during the **SQL compilation** phase of a
| statement, when rendering a SQL string. It is **not** called
| against specific values.
|
| Note that this method, when implemented, should always return
| the exact same structure, without any conditional logic, as it
| may be used in an executemany() call against an arbitrary number
| of bound parameter sets.
|
| .. note::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.bind_expression`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.bind_expression`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.bind_expression`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| .. seealso::
|
| :ref:`types_sql_value_processing`
|
| column_expression(self, colexpr: 'ColumnElement[_T]') -> 'Optional[ColumnElement[_T]]'
| Given a SELECT column expression, return a wrapping SQL expression.
|
| This is typically a SQL function that wraps a column expression
| as rendered in the columns clause of a SELECT statement.
| It is used for special data types that require
| columns to be wrapped in some special database function in order
| to coerce the value before being sent back to the application.
| It is the SQL analogue of the :meth:`.TypeEngine.result_processor`
| method.
|
| .. note:: The :func:`.TypeEngine.column_expression` method is applied
| only to the **outermost columns clause** of a SELECT statement, that
| is, the columns that are to be delivered directly into the returned
| result rows. It does **not** apply to the columns clause inside
| of subqueries. This necessarily avoids double conversions against
| the column and only runs the conversion when ready to be returned
| to the client.
|
| This method is called during the **SQL compilation** phase of a
| statement, when rendering a SQL string. It is **not** called
| against specific values.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.column_expression`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.column_expression`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.column_expression`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
|
| .. seealso::
|
| :ref:`types_sql_value_processing`
|
| compare_values(self, x: 'Any', y: 'Any') -> 'bool'
| Compare two values for equality.
|
| compile(self, dialect: 'Optional[Dialect]' = None) -> 'str'
| Produce a string-compiled form of this :class:`.TypeEngine`.
|
| When called with no arguments, uses a "default" dialect
| to produce a string result.
|
| :param dialect: a :class:`.Dialect` instance.
|
| copy(self, **kw: 'Any') -> 'Self'
|
| copy_value(self, value: 'Any') -> 'Any'
|
| dialect_impl(self, dialect: 'Dialect') -> 'TypeEngine[_T]'
| Return a dialect-specific implementation for this
| :class:`.TypeEngine`.
|
| evaluates_none(self) -> 'Self'
| Return a copy of this type which has the
| :attr:`.should_evaluate_none` flag set to True.
|
| E.g.::
|
| Table(
| "some_table",
| metadata,
| Column(
| String(50).evaluates_none(),
| nullable=True,
| server_default="no value",
| ),
| )
|
| The ORM uses this flag to indicate that a positive value of ``None``
| is passed to the column in an INSERT statement, rather than omitting
| the column from the INSERT statement which has the effect of firing
| off column-level defaults. It also allows for types which have
| special behavior associated with the Python None value to indicate
| that the value doesn't necessarily translate into SQL NULL; a
| prime example of this is a JSON type which may wish to persist the
| JSON value ``'null'``.
|
| In all cases, the actual NULL SQL value can be always be
| persisted in any column by using
| the :obj:`_expression.null` SQL construct in an INSERT statement
| or associated with an ORM-mapped attribute.
|
| .. note::
|
| The "evaluates none" flag does **not** apply to a value
| of ``None`` passed to :paramref:`_schema.Column.default` or
| :paramref:`_schema.Column.server_default`; in these cases,
| ``None``
| still means "no default".
|
| .. seealso::
|
| :ref:`session_forcing_null` - in the ORM documentation
|
| :paramref:`.postgresql.JSON.none_as_null` - PostgreSQL JSON
| interaction with this flag.
|
| :attr:`.TypeEngine.should_evaluate_none` - class-level flag
|
| with_variant(self, type_: '_TypeEngineArgument[Any]', *dialect_names: 'str') -> 'Self'
| Produce a copy of this type object that will utilize the given
| type when applied to the dialect of the given name.
|
| e.g.::
|
| from sqlalchemy.types import String
| from sqlalchemy.dialects import mysql
|
| string_type = String()
|
| string_type = string_type.with_variant(
| mysql.VARCHAR(collation="foo"), "mysql", "mariadb"
| )
|
| The variant mapping indicates that when this type is
| interpreted by a specific dialect, it will instead be
| transmuted into the given type, rather than using the
| primary type.
|
| .. versionchanged:: 2.0 the :meth:`_types.TypeEngine.with_variant`
| method now works with a :class:`_types.TypeEngine` object "in
| place", returning a copy of the original type rather than returning
| a wrapping object; the ``Variant`` class is no longer used.
|
| :param type\_: a :class:`.TypeEngine` that will be selected
| as a variant from the originating type, when a dialect
| of the given name is in use.
| :param \*dialect_names: one or more base names of the dialect which
| uses this type. (i.e. ``'postgresql'``, ``'mysql'``, etc.)
|
| .. versionchanged:: 2.0 multiple dialect names can be specified
| for one variant.
|
| .. seealso::
|
| :ref:`types_with_variant` - illustrates the use of
| :meth:`_types.TypeEngine.with_variant`.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from sqlalchemy.sql.type_api.TypeEngine:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.type_api.TypeEngine:
|
| Comparator = <class 'sqlalchemy.sql.type_api.TypeEngine.Comparator'>
| Base class for custom comparison operations defined at the
| type level. See :attr:`.TypeEngine.comparator_factory`.
|
|
| __orig_bases__ = (<class 'sqlalchemy.sql.visitors.Visitable'>, typing....
|
| comparator_factory = <class 'sqlalchemy.sql.type_api.TypeEngine.Compar...
| Base class for custom comparison operations defined at the
| type level. See :attr:`.TypeEngine.comparator_factory`.
|
|
| hashable = True
|
| render_bind_cast = False
|
| render_literal_cast = False
|
| should_evaluate_none = False
|
| sort_key_function = None
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.visitors.Visitable:
|
| __class_getitem__(key: 'Any') -> 'Any'
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__() -> 'None'
| Function to initialize subclasses.
sqlalchemy.BLANK_SCHEMA
Python Library Documentation: SchemaConst in module sqlalchemy.sql.schema object class SchemaConst(enum.Enum) | SchemaConst(*values) | | Method resolution order: | SchemaConst | enum.Enum | builtins.object | | Data and other attributes defined here: | | BLANK_SCHEMA = <SchemaConst.BLANK_SCHEMA: 2> | | NULL_UNSPECIFIED = <SchemaConst.NULL_UNSPECIFIED: 3> | | RETAIN_SCHEMA = <SchemaConst.RETAIN_SCHEMA: 1> | | ---------------------------------------------------------------------- | Data descriptors inherited from enum.Enum: | | name | The name of the Enum member. | | value | The value of the Enum member. | | ---------------------------------------------------------------------- | Static methods inherited from enum.EnumType: | | __contains__(value) | Return True if `value` is in `cls`. | | `value` is in `cls` if: | 1) `value` is a member of `cls`, or | 2) `value` is the value of one of the `cls`'s members. | | __getitem__(name) | Return the member matching `name`. | | __iter__() | Return members in definition order. | | __len__() | Return the number of members (no aliases) | | ---------------------------------------------------------------------- | Readonly properties inherited from enum.EnumType: | | __members__ | Returns a mapping of member name->value. | | This mapping lists all enum members, including aliases. Note that this | is a read-only view of the internal mapping.
sqlalchemy.BLOB
Python Library Documentation: class BLOB in module sqlalchemy.sql.sqltypes
class BLOB(LargeBinary)
| BLOB(length: 'Optional[int]' = None)
|
| The SQL BLOB type.
|
| Method resolution order:
| BLOB
| LargeBinary
| _Binary
| sqlalchemy.sql.type_api.TypeEngine
| sqlalchemy.sql.visitors.Visitable
| typing.Generic
| builtins.object
|
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| __parameters__ = ()
|
| __visit_name__ = 'BLOB'
|
| ----------------------------------------------------------------------
| Methods inherited from LargeBinary:
|
| __init__(self, length: 'Optional[int]' = None)
| Construct a LargeBinary type.
|
| :param length: optional, a length for the column for use in
| DDL statements, for those binary types that accept a length,
| such as the MySQL BLOB type.
|
| ----------------------------------------------------------------------
| Methods inherited from _Binary:
|
| bind_processor(self, dialect)
| Return a conversion function for processing bind values.
|
| Returns a callable which will receive a bind parameter value
| as the sole positional argument and will return a value to
| send to the DB-API.
|
| If processing is not necessary, the method should return ``None``.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.bind_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.bind_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_bind_param`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
|
| :param dialect: Dialect instance in use.
|
| coerce_compared_value(self, op, value)
| See :meth:`.TypeEngine.coerce_compared_value` for a description.
|
| get_dbapi_type(self, dbapi)
| Return the corresponding type object from the underlying DB-API, if
| any.
|
| This can be useful for calling ``setinputsizes()``, for example.
|
| literal_processor(self, dialect)
| Return a conversion function for processing literal values that are
| to be rendered directly without using binds.
|
| This function is used when the compiler makes use of the
| "literal_binds" flag, typically used in DDL generation as well
| as in certain scenarios where backends don't accept bound parameters.
|
| Returns a callable which will receive a literal Python value
| as the sole positional argument and will return a string representation
| to be rendered in a SQL statement.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.literal_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.literal_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_literal_param`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| result_processor(self, dialect, coltype)
| Return a conversion function for processing result row values.
|
| Returns a callable which will receive a result row column
| value as the sole positional argument and will return a value
| to return to the user.
|
| If processing is not necessary, the method should return ``None``.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.result_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.result_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_result_value`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| :param dialect: Dialect instance in use.
|
| :param coltype: DBAPI coltype argument received in cursor.description.
|
| ----------------------------------------------------------------------
| Readonly properties inherited from _Binary:
|
| python_type
| Return the Python type object expected to be returned
| by instances of this type, if known.
|
| Basically, for those types which enforce a return type,
| or are known across the board to do such for all common
| DBAPIs (like ``int`` for example), will return that type.
|
| If a return type is not defined, raises
| ``NotImplementedError``.
|
| Note that any type also accommodates NULL in SQL which
| means you can also get back ``None`` from any type
| in practice.
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.type_api.TypeEngine:
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| __str__(self) -> 'str'
| Return str(self).
|
| adapt(self, cls: 'Type[Union[TypeEngine[Any], TypeEngineMixin]]', **kw: 'Any') -> 'TypeEngine[Any]'
| Produce an "adapted" form of this type, given an "impl" class
| to work with.
|
| This method is used internally to associate generic
| types with "implementation" types that are specific to a particular
| dialect.
|
| as_generic(self, allow_nulltype: 'bool' = False) -> 'TypeEngine[_T]'
| Return an instance of the generic type corresponding to this type
| using heuristic rule. The method may be overridden if this
| heuristic rule is not sufficient.
|
| >>> from sqlalchemy.dialects.mysql import INTEGER
| >>> INTEGER(display_width=4).as_generic()
| Integer()
|
| >>> from sqlalchemy.dialects.mysql import NVARCHAR
| >>> NVARCHAR(length=100).as_generic()
| Unicode(length=100)
|
| .. versionadded:: 1.4.0b2
|
|
| .. seealso::
|
| :ref:`metadata_reflection_dbagnostic_types` - describes the
| use of :meth:`_types.TypeEngine.as_generic` in conjunction with
| the :meth:`_sql.DDLEvents.column_reflect` event, which is its
| intended use.
|
| bind_expression(self, bindvalue: 'BindParameter[_T]') -> 'Optional[ColumnElement[_T]]'
| Given a bind value (i.e. a :class:`.BindParameter` instance),
| return a SQL expression in its place.
|
| This is typically a SQL function that wraps the existing bound
| parameter within the statement. It is used for special data types
| that require literals being wrapped in some special database function
| in order to coerce an application-level value into a database-specific
| format. It is the SQL analogue of the
| :meth:`.TypeEngine.bind_processor` method.
|
| This method is called during the **SQL compilation** phase of a
| statement, when rendering a SQL string. It is **not** called
| against specific values.
|
| Note that this method, when implemented, should always return
| the exact same structure, without any conditional logic, as it
| may be used in an executemany() call against an arbitrary number
| of bound parameter sets.
|
| .. note::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.bind_expression`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.bind_expression`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.bind_expression`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| .. seealso::
|
| :ref:`types_sql_value_processing`
|
| column_expression(self, colexpr: 'ColumnElement[_T]') -> 'Optional[ColumnElement[_T]]'
| Given a SELECT column expression, return a wrapping SQL expression.
|
| This is typically a SQL function that wraps a column expression
| as rendered in the columns clause of a SELECT statement.
| It is used for special data types that require
| columns to be wrapped in some special database function in order
| to coerce the value before being sent back to the application.
| It is the SQL analogue of the :meth:`.TypeEngine.result_processor`
| method.
|
| .. note:: The :func:`.TypeEngine.column_expression` method is applied
| only to the **outermost columns clause** of a SELECT statement, that
| is, the columns that are to be delivered directly into the returned
| result rows. It does **not** apply to the columns clause inside
| of subqueries. This necessarily avoids double conversions against
| the column and only runs the conversion when ready to be returned
| to the client.
|
| This method is called during the **SQL compilation** phase of a
| statement, when rendering a SQL string. It is **not** called
| against specific values.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.column_expression`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.column_expression`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.column_expression`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
|
| .. seealso::
|
| :ref:`types_sql_value_processing`
|
| compare_values(self, x: 'Any', y: 'Any') -> 'bool'
| Compare two values for equality.
|
| compile(self, dialect: 'Optional[Dialect]' = None) -> 'str'
| Produce a string-compiled form of this :class:`.TypeEngine`.
|
| When called with no arguments, uses a "default" dialect
| to produce a string result.
|
| :param dialect: a :class:`.Dialect` instance.
|
| copy(self, **kw: 'Any') -> 'Self'
|
| copy_value(self, value: 'Any') -> 'Any'
|
| dialect_impl(self, dialect: 'Dialect') -> 'TypeEngine[_T]'
| Return a dialect-specific implementation for this
| :class:`.TypeEngine`.
|
| evaluates_none(self) -> 'Self'
| Return a copy of this type which has the
| :attr:`.should_evaluate_none` flag set to True.
|
| E.g.::
|
| Table(
| "some_table",
| metadata,
| Column(
| String(50).evaluates_none(),
| nullable=True,
| server_default="no value",
| ),
| )
|
| The ORM uses this flag to indicate that a positive value of ``None``
| is passed to the column in an INSERT statement, rather than omitting
| the column from the INSERT statement which has the effect of firing
| off column-level defaults. It also allows for types which have
| special behavior associated with the Python None value to indicate
| that the value doesn't necessarily translate into SQL NULL; a
| prime example of this is a JSON type which may wish to persist the
| JSON value ``'null'``.
|
| In all cases, the actual NULL SQL value can be always be
| persisted in any column by using
| the :obj:`_expression.null` SQL construct in an INSERT statement
| or associated with an ORM-mapped attribute.
|
| .. note::
|
| The "evaluates none" flag does **not** apply to a value
| of ``None`` passed to :paramref:`_schema.Column.default` or
| :paramref:`_schema.Column.server_default`; in these cases,
| ``None``
| still means "no default".
|
| .. seealso::
|
| :ref:`session_forcing_null` - in the ORM documentation
|
| :paramref:`.postgresql.JSON.none_as_null` - PostgreSQL JSON
| interaction with this flag.
|
| :attr:`.TypeEngine.should_evaluate_none` - class-level flag
|
| with_variant(self, type_: '_TypeEngineArgument[Any]', *dialect_names: 'str') -> 'Self'
| Produce a copy of this type object that will utilize the given
| type when applied to the dialect of the given name.
|
| e.g.::
|
| from sqlalchemy.types import String
| from sqlalchemy.dialects import mysql
|
| string_type = String()
|
| string_type = string_type.with_variant(
| mysql.VARCHAR(collation="foo"), "mysql", "mariadb"
| )
|
| The variant mapping indicates that when this type is
| interpreted by a specific dialect, it will instead be
| transmuted into the given type, rather than using the
| primary type.
|
| .. versionchanged:: 2.0 the :meth:`_types.TypeEngine.with_variant`
| method now works with a :class:`_types.TypeEngine` object "in
| place", returning a copy of the original type rather than returning
| a wrapping object; the ``Variant`` class is no longer used.
|
| :param type\_: a :class:`.TypeEngine` that will be selected
| as a variant from the originating type, when a dialect
| of the given name is in use.
| :param \*dialect_names: one or more base names of the dialect which
| uses this type. (i.e. ``'postgresql'``, ``'mysql'``, etc.)
|
| .. versionchanged:: 2.0 multiple dialect names can be specified
| for one variant.
|
| .. seealso::
|
| :ref:`types_with_variant` - illustrates the use of
| :meth:`_types.TypeEngine.with_variant`.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from sqlalchemy.sql.type_api.TypeEngine:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.type_api.TypeEngine:
|
| Comparator = <class 'sqlalchemy.sql.type_api.TypeEngine.Comparator'>
| Base class for custom comparison operations defined at the
| type level. See :attr:`.TypeEngine.comparator_factory`.
|
|
| __orig_bases__ = (<class 'sqlalchemy.sql.visitors.Visitable'>, typing....
|
| comparator_factory = <class 'sqlalchemy.sql.type_api.TypeEngine.Compar...
| Base class for custom comparison operations defined at the
| type level. See :attr:`.TypeEngine.comparator_factory`.
|
|
| hashable = True
|
| render_bind_cast = False
|
| render_literal_cast = False
|
| should_evaluate_none = False
|
| sort_key_function = None
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.visitors.Visitable:
|
| __class_getitem__(key: 'Any') -> 'Any'
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__() -> 'None'
| Function to initialize subclasses.
sqlalchemy.BOOLEAN
Python Library Documentation: class BOOLEAN in module sqlalchemy.sql.sqltypes
class BOOLEAN(Boolean)
| BOOLEAN(create_constraint: 'bool' = False, name: 'Optional[str]' = None, _create_events: 'bool' = True, _adapted_from: 'Optional[SchemaType]' = None)
|
| The SQL BOOLEAN type.
|
| Method resolution order:
| BOOLEAN
| Boolean
| SchemaType
| sqlalchemy.sql.base.SchemaEventTarget
| sqlalchemy.event.registry.EventTarget
| sqlalchemy.sql.type_api.Emulated
| sqlalchemy.sql.type_api.TypeEngineMixin
| sqlalchemy.sql.type_api.TypeEngine
| sqlalchemy.sql.visitors.Visitable
| typing.Generic
| builtins.object
|
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| __parameters__ = ()
|
| __visit_name__ = 'BOOLEAN'
|
| ----------------------------------------------------------------------
| Methods inherited from Boolean:
|
| __init__(self, create_constraint: 'bool' = False, name: 'Optional[str]' = None, _create_events: 'bool' = True, _adapted_from: 'Optional[SchemaType]' = None)
| Construct a Boolean.
|
| :param create_constraint: defaults to False. If the boolean
| is generated as an int/smallint, also create a CHECK constraint
| on the table that ensures 1 or 0 as a value.
|
| .. note:: it is strongly recommended that the CHECK constraint
| have an explicit name in order to support schema-management
| concerns. This can be established either by setting the
| :paramref:`.Boolean.name` parameter or by setting up an
| appropriate naming convention; see
| :ref:`constraint_naming_conventions` for background.
|
| .. versionchanged:: 1.4 - this flag now defaults to False, meaning
| no CHECK constraint is generated for a non-native enumerated
| type.
|
| :param name: if a CHECK constraint is generated, specify
| the name of the constraint.
|
| bind_processor(self, dialect)
| Return a conversion function for processing bind values.
|
| Returns a callable which will receive a bind parameter value
| as the sole positional argument and will return a value to
| send to the DB-API.
|
| If processing is not necessary, the method should return ``None``.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.bind_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.bind_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_bind_param`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
|
| :param dialect: Dialect instance in use.
|
| copy(self, **kw)
|
| literal_processor(self, dialect)
| Return a conversion function for processing literal values that are
| to be rendered directly without using binds.
|
| This function is used when the compiler makes use of the
| "literal_binds" flag, typically used in DDL generation as well
| as in certain scenarios where backends don't accept bound parameters.
|
| Returns a callable which will receive a literal Python value
| as the sole positional argument and will return a string representation
| to be rendered in a SQL statement.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.literal_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.literal_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_literal_param`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| result_processor(self, dialect, coltype)
| Return a conversion function for processing result row values.
|
| Returns a callable which will receive a result row column
| value as the sole positional argument and will return a value
| to return to the user.
|
| If processing is not necessary, the method should return ``None``.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.result_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.result_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_result_value`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| :param dialect: Dialect instance in use.
|
| :param coltype: DBAPI coltype argument received in cursor.description.
|
| ----------------------------------------------------------------------
| Readonly properties inherited from Boolean:
|
| python_type
| Return the Python type object expected to be returned
| by instances of this type, if known.
|
| Basically, for those types which enforce a return type,
| or are known across the board to do such for all common
| DBAPIs (like ``int`` for example), will return that type.
|
| If a return type is not defined, raises
| ``NotImplementedError``.
|
| Note that any type also accommodates NULL in SQL which
| means you can also get back ``None`` from any type
| in practice.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from Boolean:
|
| native = True
|
| ----------------------------------------------------------------------
| Methods inherited from SchemaType:
|
| adapt(self, cls: 'Type[Union[TypeEngine[Any], TypeEngineMixin]]', **kw: 'Any') -> 'TypeEngine[Any]'
|
| create(self, bind: '_CreateDropBind', checkfirst: 'bool' = False) -> 'None'
| Issue CREATE DDL for this type, if applicable.
|
| drop(self, bind: '_CreateDropBind', checkfirst: 'bool' = False) -> 'None'
| Issue DROP DDL for this type, if applicable.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from sqlalchemy.sql.base.SchemaEventTarget:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.base.SchemaEventTarget:
|
| dispatch = <sqlalchemy.event.base.DDLEventsDispatch object>
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.type_api.Emulated:
|
| adapt_to_emulated(self, impltype: 'Type[Union[TypeEngine[Any], TypeEngineMixin]]', **kw: 'Any') -> 'TypeEngine[Any]'
| Given an impl class, adapt this type to the impl assuming
| "emulated".
|
| The impl should also be an "emulated" version of this type,
| most likely the same class as this type itself.
|
| e.g.: sqltypes.Enum adapts to the Enum class.
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.type_api.TypeEngine:
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| __str__(self) -> 'str'
| Return str(self).
|
| as_generic(self, allow_nulltype: 'bool' = False) -> 'TypeEngine[_T]'
| Return an instance of the generic type corresponding to this type
| using heuristic rule. The method may be overridden if this
| heuristic rule is not sufficient.
|
| >>> from sqlalchemy.dialects.mysql import INTEGER
| >>> INTEGER(display_width=4).as_generic()
| Integer()
|
| >>> from sqlalchemy.dialects.mysql import NVARCHAR
| >>> NVARCHAR(length=100).as_generic()
| Unicode(length=100)
|
| .. versionadded:: 1.4.0b2
|
|
| .. seealso::
|
| :ref:`metadata_reflection_dbagnostic_types` - describes the
| use of :meth:`_types.TypeEngine.as_generic` in conjunction with
| the :meth:`_sql.DDLEvents.column_reflect` event, which is its
| intended use.
|
| bind_expression(self, bindvalue: 'BindParameter[_T]') -> 'Optional[ColumnElement[_T]]'
| Given a bind value (i.e. a :class:`.BindParameter` instance),
| return a SQL expression in its place.
|
| This is typically a SQL function that wraps the existing bound
| parameter within the statement. It is used for special data types
| that require literals being wrapped in some special database function
| in order to coerce an application-level value into a database-specific
| format. It is the SQL analogue of the
| :meth:`.TypeEngine.bind_processor` method.
|
| This method is called during the **SQL compilation** phase of a
| statement, when rendering a SQL string. It is **not** called
| against specific values.
|
| Note that this method, when implemented, should always return
| the exact same structure, without any conditional logic, as it
| may be used in an executemany() call against an arbitrary number
| of bound parameter sets.
|
| .. note::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.bind_expression`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.bind_expression`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.bind_expression`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| .. seealso::
|
| :ref:`types_sql_value_processing`
|
| coerce_compared_value(self, op: 'Optional[OperatorType]', value: 'Any') -> 'TypeEngine[Any]'
| Suggest a type for a 'coerced' Python value in an expression.
|
| Given an operator and value, gives the type a chance
| to return a type which the value should be coerced into.
|
| The default behavior here is conservative; if the right-hand
| side is already coerced into a SQL type based on its
| Python type, it is usually left alone.
|
| End-user functionality extension here should generally be via
| :class:`.TypeDecorator`, which provides more liberal behavior in that
| it defaults to coercing the other side of the expression into this
| type, thus applying special Python conversions above and beyond those
| needed by the DBAPI to both ides. It also provides the public method
| :meth:`.TypeDecorator.coerce_compared_value` which is intended for
| end-user customization of this behavior.
|
| column_expression(self, colexpr: 'ColumnElement[_T]') -> 'Optional[ColumnElement[_T]]'
| Given a SELECT column expression, return a wrapping SQL expression.
|
| This is typically a SQL function that wraps a column expression
| as rendered in the columns clause of a SELECT statement.
| It is used for special data types that require
| columns to be wrapped in some special database function in order
| to coerce the value before being sent back to the application.
| It is the SQL analogue of the :meth:`.TypeEngine.result_processor`
| method.
|
| .. note:: The :func:`.TypeEngine.column_expression` method is applied
| only to the **outermost columns clause** of a SELECT statement, that
| is, the columns that are to be delivered directly into the returned
| result rows. It does **not** apply to the columns clause inside
| of subqueries. This necessarily avoids double conversions against
| the column and only runs the conversion when ready to be returned
| to the client.
|
| This method is called during the **SQL compilation** phase of a
| statement, when rendering a SQL string. It is **not** called
| against specific values.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.column_expression`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.column_expression`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.column_expression`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
|
| .. seealso::
|
| :ref:`types_sql_value_processing`
|
| compare_values(self, x: 'Any', y: 'Any') -> 'bool'
| Compare two values for equality.
|
| compile(self, dialect: 'Optional[Dialect]' = None) -> 'str'
| Produce a string-compiled form of this :class:`.TypeEngine`.
|
| When called with no arguments, uses a "default" dialect
| to produce a string result.
|
| :param dialect: a :class:`.Dialect` instance.
|
| copy_value(self, value: 'Any') -> 'Any'
|
| dialect_impl(self, dialect: 'Dialect') -> 'TypeEngine[_T]'
| Return a dialect-specific implementation for this
| :class:`.TypeEngine`.
|
| evaluates_none(self) -> 'Self'
| Return a copy of this type which has the
| :attr:`.should_evaluate_none` flag set to True.
|
| E.g.::
|
| Table(
| "some_table",
| metadata,
| Column(
| String(50).evaluates_none(),
| nullable=True,
| server_default="no value",
| ),
| )
|
| The ORM uses this flag to indicate that a positive value of ``None``
| is passed to the column in an INSERT statement, rather than omitting
| the column from the INSERT statement which has the effect of firing
| off column-level defaults. It also allows for types which have
| special behavior associated with the Python None value to indicate
| that the value doesn't necessarily translate into SQL NULL; a
| prime example of this is a JSON type which may wish to persist the
| JSON value ``'null'``.
|
| In all cases, the actual NULL SQL value can be always be
| persisted in any column by using
| the :obj:`_expression.null` SQL construct in an INSERT statement
| or associated with an ORM-mapped attribute.
|
| .. note::
|
| The "evaluates none" flag does **not** apply to a value
| of ``None`` passed to :paramref:`_schema.Column.default` or
| :paramref:`_schema.Column.server_default`; in these cases,
| ``None``
| still means "no default".
|
| .. seealso::
|
| :ref:`session_forcing_null` - in the ORM documentation
|
| :paramref:`.postgresql.JSON.none_as_null` - PostgreSQL JSON
| interaction with this flag.
|
| :attr:`.TypeEngine.should_evaluate_none` - class-level flag
|
| get_dbapi_type(self, dbapi: 'DBAPIModule') -> 'Optional[Any]'
| Return the corresponding type object from the underlying DB-API, if
| any.
|
| This can be useful for calling ``setinputsizes()``, for example.
|
| with_variant(self, type_: '_TypeEngineArgument[Any]', *dialect_names: 'str') -> 'Self'
| Produce a copy of this type object that will utilize the given
| type when applied to the dialect of the given name.
|
| e.g.::
|
| from sqlalchemy.types import String
| from sqlalchemy.dialects import mysql
|
| string_type = String()
|
| string_type = string_type.with_variant(
| mysql.VARCHAR(collation="foo"), "mysql", "mariadb"
| )
|
| The variant mapping indicates that when this type is
| interpreted by a specific dialect, it will instead be
| transmuted into the given type, rather than using the
| primary type.
|
| .. versionchanged:: 2.0 the :meth:`_types.TypeEngine.with_variant`
| method now works with a :class:`_types.TypeEngine` object "in
| place", returning a copy of the original type rather than returning
| a wrapping object; the ``Variant`` class is no longer used.
|
| :param type\_: a :class:`.TypeEngine` that will be selected
| as a variant from the originating type, when a dialect
| of the given name is in use.
| :param \*dialect_names: one or more base names of the dialect which
| uses this type. (i.e. ``'postgresql'``, ``'mysql'``, etc.)
|
| .. versionchanged:: 2.0 multiple dialect names can be specified
| for one variant.
|
| .. seealso::
|
| :ref:`types_with_variant` - illustrates the use of
| :meth:`_types.TypeEngine.with_variant`.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.type_api.TypeEngine:
|
| Comparator = <class 'sqlalchemy.sql.type_api.TypeEngine.Comparator'>
| Base class for custom comparison operations defined at the
| type level. See :attr:`.TypeEngine.comparator_factory`.
|
|
| __orig_bases__ = (<class 'sqlalchemy.sql.visitors.Visitable'>, typing....
|
| comparator_factory = <class 'sqlalchemy.sql.type_api.TypeEngine.Compar...
| Base class for custom comparison operations defined at the
| type level. See :attr:`.TypeEngine.comparator_factory`.
|
|
| hashable = True
|
| render_bind_cast = False
|
| render_literal_cast = False
|
| should_evaluate_none = False
|
| sort_key_function = None
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.visitors.Visitable:
|
| __class_getitem__(key: 'Any') -> 'Any'
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__() -> 'None'
| This method is called when a class is subclassed.
|
| The default implementation does nothing. It may be
| overridden to extend subclasses.
sqlalchemy.BaseDDLElement
Python Library Documentation: class BaseDDLElement in module sqlalchemy.sql.ddl
class BaseDDLElement(sqlalchemy.sql.elements.ClauseElement)
| The root of DDL constructs, including those that are sub-elements
| within the "create table" and other processes.
|
| .. versionadded:: 2.0
|
| Method resolution order:
| BaseDDLElement
| sqlalchemy.sql.elements.ClauseElement
| sqlalchemy.sql.annotation.SupportsWrappingAnnotations
| sqlalchemy.sql.annotation.SupportsAnnotations
| sqlalchemy.sql.cache_key.MemoizedHasCacheKey
| sqlalchemy.sql.cache_key.HasCacheKey
| sqlalchemy.util.langhelpers.HasMemoized
| sqlalchemy.sql.traversals.HasCopyInternals
| sqlalchemy.sql.visitors.ExternallyTraversible
| sqlalchemy.sql.visitors.HasTraverseInternals
| sqlalchemy.sql.elements.CompilerElement
| sqlalchemy.sql.visitors.Visitable
| builtins.object
|
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.elements.ClauseElement:
|
| __bool__(self)
|
| __getstate__(self)
| Helper for pickle.
|
| __invert__(self)
|
| __repr__(self)
| Return repr(self).
|
| compare(self, other: 'ClauseElement', **kw: 'Any') -> 'bool'
| Compare this :class:`_expression.ClauseElement` to
| the given :class:`_expression.ClauseElement`.
|
| Subclasses should override the default behavior, which is a
| straight identity comparison.
|
| \**kw are arguments consumed by subclass ``compare()`` methods and
| may be used to modify the criteria for comparison
| (see :class:`_expression.ColumnElement`).
|
| description(...)
|
| entity_namespace(...)
|
| params(self, _ClauseElement__optionaldict: 'Optional[Mapping[str, Any]]' = None, **kwargs: 'Any') -> 'Self'
| Return a copy with :func:`_expression.bindparam` elements
| replaced.
|
| Returns a copy of this ClauseElement with
| :func:`_expression.bindparam`
| elements replaced with values taken from the given dictionary::
|
| >>> clause = column("x") + bindparam("foo")
| >>> print(clause.compile().params)
| {'foo':None}
| >>> print(clause.params({"foo": 7}).compile().params)
| {'foo':7}
|
| self_group(self, against: 'Optional[OperatorType]' = None) -> 'ClauseElement'
| 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.
|
| unique_params(self, _ClauseElement__optionaldict: 'Optional[Dict[str, Any]]' = None, **kwargs: 'Any') -> 'Self'
| Return a copy with :func:`_expression.bindparam` elements
| replaced.
|
| Same functionality as :meth:`_expression.ClauseElement.params`,
| except adds `unique=True`
| to affected bind parameters so that multiple statements can be
| used.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from sqlalchemy.sql.elements.ClauseElement:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.elements.ClauseElement:
|
| __visit_name__ = 'clause'
|
| is_clause_element = True
|
| is_dml = False
|
| is_selectable = False
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.cache_key.HasCacheKey:
|
| inherit_cache = None
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_instancemethod(fn: '_F') -> '_F'
| Decorate a method memoize its return value.
|
| :meta private:
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_attribute = <class 'sqlalchemy.util.langhelpers.HasMemoized.m...
| A read-only @property that is only evaluated once.
|
| :meta private:
|
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.visitors.HasTraverseInternals:
|
| get_children(self, *, omit_attrs: 'Tuple[str, ...]' = (), **kw: 'Any') -> 'Iterable[HasTraverseInternals]'
| Return immediate child :class:`.visitors.HasTraverseInternals`
| elements of this :class:`.visitors.HasTraverseInternals`.
|
| This is used for visit traversal.
|
| \**kw may contain flags that change the collection that is
| returned, for example to return a subset of items in order to
| cut down on larger traversals, or to return child items from a
| different context (such as schema-level collections instead of
| clause-level).
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.elements.CompilerElement:
|
| __str__(self) -> 'str'
| Return str(self).
|
| compile(self, bind: 'Optional[_HasDialect]' = None, dialect: 'Optional[Dialect]' = None, **kw: 'Any') -> 'Compiled'
| Compile this SQL expression.
|
| The return value is a :class:`~.Compiled` object.
| Calling ``str()`` or ``unicode()`` on the returned value will yield a
| string representation of the result. The
| :class:`~.Compiled` object also can return a
| dictionary of bind parameter names and values
| using the ``params`` accessor.
|
| :param bind: An :class:`.Connection` or :class:`.Engine` which
| can provide a :class:`.Dialect` in order to generate a
| :class:`.Compiled` object. If the ``bind`` and
| ``dialect`` parameters are both omitted, a default SQL compiler
| is used.
|
| :param column_keys: Used for INSERT and UPDATE statements, a list of
| column names which should be present in the VALUES clause of the
| compiled statement. If ``None``, all columns from the target table
| object are rendered.
|
| :param dialect: A :class:`.Dialect` instance which can generate
| a :class:`.Compiled` object. This argument takes precedence over
| the ``bind`` argument.
|
| :param compile_kwargs: optional dictionary of additional parameters
| that will be passed through to the compiler within all "visit"
| methods. This allows any custom flag to be passed through to
| a custom compilation construct, for example. It is also used
| for the case of passing the ``literal_binds`` flag through::
|
| from sqlalchemy.sql import table, column, select
|
| t = table("t", column("x"))
|
| s = select(t).where(t.c.x == 5)
|
| print(s.compile(compile_kwargs={"literal_binds": True}))
|
| .. seealso::
|
| :ref:`faq_sql_expression_string`
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.elements.CompilerElement:
|
| stringify_dialect = 'default'
|
| supports_execution = False
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.visitors.Visitable:
|
| __class_getitem__(key: 'Any') -> 'Any'
|
| __init_subclass__() -> 'None'
| This method is called when a class is subclassed.
|
| The default implementation does nothing. It may be
| overridden to extend subclasses.
sqlalchemy.BaseRow
Python Library Documentation: class BaseRow in module sqlalchemy.cyextension.resultproxy class BaseRow(builtins.object) | Methods defined here: | | __getattr__(...) | | __getattribute__(self, name, /) | Return getattr(self, name). | | __getitem__(self, key, /) | Return self[key]. | | __getstate__(self) | | __hash__(self, /) | Return hash(self). | | __init__(...) | Row objects are constructed by CursorResult objects. | | __iter__(self, /) | Implement iter(self). | | __len__(self, /) | Return len(self). | | __reduce__(self) | | __setstate__(self, state) | | ---------------------------------------------------------------------- | Static methods defined here: | | __new__(*args, **kwargs) | Create and return a new object. See help(type) for accurate signature. | | ---------------------------------------------------------------------- | Data and other attributes defined here: | | __pyx_vtable__ = <capsule object NULL>
sqlalchemy.BigInteger
Python Library Documentation: class BigInteger in module sqlalchemy.sql.sqltypes
class BigInteger(Integer)
| A type for bigger ``int`` integers.
|
| Typically generates a ``BIGINT`` in DDL, and otherwise acts like
| a normal :class:`.Integer` on the Python side.
|
| Method resolution order:
| BigInteger
| Integer
| HasExpressionLookup
| sqlalchemy.sql.type_api.TypeEngineMixin
| sqlalchemy.sql.type_api.TypeEngine
| sqlalchemy.sql.visitors.Visitable
| typing.Generic
| builtins.object
|
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| __parameters__ = ()
|
| __visit_name__ = 'big_integer'
|
| ----------------------------------------------------------------------
| Methods inherited from Integer:
|
| get_dbapi_type(self, dbapi)
| Return the corresponding type object from the underlying DB-API, if
| any.
|
| This can be useful for calling ``setinputsizes()``, for example.
|
| literal_processor(self, dialect)
| Return a conversion function for processing literal values that are
| to be rendered directly without using binds.
|
| This function is used when the compiler makes use of the
| "literal_binds" flag, typically used in DDL generation as well
| as in certain scenarios where backends don't accept bound parameters.
|
| Returns a callable which will receive a literal Python value
| as the sole positional argument and will return a string representation
| to be rendered in a SQL statement.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.literal_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.literal_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_literal_param`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| ----------------------------------------------------------------------
| Readonly properties inherited from Integer:
|
| python_type
| Return the Python type object expected to be returned
| by instances of this type, if known.
|
| Basically, for those types which enforce a return type,
| or are known across the board to do such for all common
| DBAPIs (like ``int`` for example), will return that type.
|
| If a return type is not defined, raises
| ``NotImplementedError``.
|
| Note that any type also accommodates NULL in SQL which
| means you can also get back ``None`` from any type
| in practice.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from HasExpressionLookup:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from HasExpressionLookup:
|
| Comparator = <class 'sqlalchemy.sql.sqltypes.HasExpressionLookup.Compa...
|
| comparator_factory = <class 'sqlalchemy.sql.sqltypes.HasExpressionLook...
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.type_api.TypeEngine:
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| __str__(self) -> 'str'
| Return str(self).
|
| adapt(self, cls: 'Type[Union[TypeEngine[Any], TypeEngineMixin]]', **kw: 'Any') -> 'TypeEngine[Any]'
| Produce an "adapted" form of this type, given an "impl" class
| to work with.
|
| This method is used internally to associate generic
| types with "implementation" types that are specific to a particular
| dialect.
|
| as_generic(self, allow_nulltype: 'bool' = False) -> 'TypeEngine[_T]'
| Return an instance of the generic type corresponding to this type
| using heuristic rule. The method may be overridden if this
| heuristic rule is not sufficient.
|
| >>> from sqlalchemy.dialects.mysql import INTEGER
| >>> INTEGER(display_width=4).as_generic()
| Integer()
|
| >>> from sqlalchemy.dialects.mysql import NVARCHAR
| >>> NVARCHAR(length=100).as_generic()
| Unicode(length=100)
|
| .. versionadded:: 1.4.0b2
|
|
| .. seealso::
|
| :ref:`metadata_reflection_dbagnostic_types` - describes the
| use of :meth:`_types.TypeEngine.as_generic` in conjunction with
| the :meth:`_sql.DDLEvents.column_reflect` event, which is its
| intended use.
|
| bind_expression(self, bindvalue: 'BindParameter[_T]') -> 'Optional[ColumnElement[_T]]'
| Given a bind value (i.e. a :class:`.BindParameter` instance),
| return a SQL expression in its place.
|
| This is typically a SQL function that wraps the existing bound
| parameter within the statement. It is used for special data types
| that require literals being wrapped in some special database function
| in order to coerce an application-level value into a database-specific
| format. It is the SQL analogue of the
| :meth:`.TypeEngine.bind_processor` method.
|
| This method is called during the **SQL compilation** phase of a
| statement, when rendering a SQL string. It is **not** called
| against specific values.
|
| Note that this method, when implemented, should always return
| the exact same structure, without any conditional logic, as it
| may be used in an executemany() call against an arbitrary number
| of bound parameter sets.
|
| .. note::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.bind_expression`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.bind_expression`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.bind_expression`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| .. seealso::
|
| :ref:`types_sql_value_processing`
|
| bind_processor(self, dialect: 'Dialect') -> 'Optional[_BindProcessorType[_T]]'
| Return a conversion function for processing bind values.
|
| Returns a callable which will receive a bind parameter value
| as the sole positional argument and will return a value to
| send to the DB-API.
|
| If processing is not necessary, the method should return ``None``.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.bind_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.bind_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_bind_param`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
|
| :param dialect: Dialect instance in use.
|
| coerce_compared_value(self, op: 'Optional[OperatorType]', value: 'Any') -> 'TypeEngine[Any]'
| Suggest a type for a 'coerced' Python value in an expression.
|
| Given an operator and value, gives the type a chance
| to return a type which the value should be coerced into.
|
| The default behavior here is conservative; if the right-hand
| side is already coerced into a SQL type based on its
| Python type, it is usually left alone.
|
| End-user functionality extension here should generally be via
| :class:`.TypeDecorator`, which provides more liberal behavior in that
| it defaults to coercing the other side of the expression into this
| type, thus applying special Python conversions above and beyond those
| needed by the DBAPI to both ides. It also provides the public method
| :meth:`.TypeDecorator.coerce_compared_value` which is intended for
| end-user customization of this behavior.
|
| column_expression(self, colexpr: 'ColumnElement[_T]') -> 'Optional[ColumnElement[_T]]'
| Given a SELECT column expression, return a wrapping SQL expression.
|
| This is typically a SQL function that wraps a column expression
| as rendered in the columns clause of a SELECT statement.
| It is used for special data types that require
| columns to be wrapped in some special database function in order
| to coerce the value before being sent back to the application.
| It is the SQL analogue of the :meth:`.TypeEngine.result_processor`
| method.
|
| .. note:: The :func:`.TypeEngine.column_expression` method is applied
| only to the **outermost columns clause** of a SELECT statement, that
| is, the columns that are to be delivered directly into the returned
| result rows. It does **not** apply to the columns clause inside
| of subqueries. This necessarily avoids double conversions against
| the column and only runs the conversion when ready to be returned
| to the client.
|
| This method is called during the **SQL compilation** phase of a
| statement, when rendering a SQL string. It is **not** called
| against specific values.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.column_expression`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.column_expression`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.column_expression`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
|
| .. seealso::
|
| :ref:`types_sql_value_processing`
|
| compare_values(self, x: 'Any', y: 'Any') -> 'bool'
| Compare two values for equality.
|
| compile(self, dialect: 'Optional[Dialect]' = None) -> 'str'
| Produce a string-compiled form of this :class:`.TypeEngine`.
|
| When called with no arguments, uses a "default" dialect
| to produce a string result.
|
| :param dialect: a :class:`.Dialect` instance.
|
| copy(self, **kw: 'Any') -> 'Self'
|
| copy_value(self, value: 'Any') -> 'Any'
|
| dialect_impl(self, dialect: 'Dialect') -> 'TypeEngine[_T]'
| Return a dialect-specific implementation for this
| :class:`.TypeEngine`.
|
| evaluates_none(self) -> 'Self'
| Return a copy of this type which has the
| :attr:`.should_evaluate_none` flag set to True.
|
| E.g.::
|
| Table(
| "some_table",
| metadata,
| Column(
| String(50).evaluates_none(),
| nullable=True,
| server_default="no value",
| ),
| )
|
| The ORM uses this flag to indicate that a positive value of ``None``
| is passed to the column in an INSERT statement, rather than omitting
| the column from the INSERT statement which has the effect of firing
| off column-level defaults. It also allows for types which have
| special behavior associated with the Python None value to indicate
| that the value doesn't necessarily translate into SQL NULL; a
| prime example of this is a JSON type which may wish to persist the
| JSON value ``'null'``.
|
| In all cases, the actual NULL SQL value can be always be
| persisted in any column by using
| the :obj:`_expression.null` SQL construct in an INSERT statement
| or associated with an ORM-mapped attribute.
|
| .. note::
|
| The "evaluates none" flag does **not** apply to a value
| of ``None`` passed to :paramref:`_schema.Column.default` or
| :paramref:`_schema.Column.server_default`; in these cases,
| ``None``
| still means "no default".
|
| .. seealso::
|
| :ref:`session_forcing_null` - in the ORM documentation
|
| :paramref:`.postgresql.JSON.none_as_null` - PostgreSQL JSON
| interaction with this flag.
|
| :attr:`.TypeEngine.should_evaluate_none` - class-level flag
|
| result_processor(self, dialect: 'Dialect', coltype: 'object') -> 'Optional[_ResultProcessorType[_T]]'
| Return a conversion function for processing result row values.
|
| Returns a callable which will receive a result row column
| value as the sole positional argument and will return a value
| to return to the user.
|
| If processing is not necessary, the method should return ``None``.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.result_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.result_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_result_value`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| :param dialect: Dialect instance in use.
|
| :param coltype: DBAPI coltype argument received in cursor.description.
|
| with_variant(self, type_: '_TypeEngineArgument[Any]', *dialect_names: 'str') -> 'Self'
| Produce a copy of this type object that will utilize the given
| type when applied to the dialect of the given name.
|
| e.g.::
|
| from sqlalchemy.types import String
| from sqlalchemy.dialects import mysql
|
| string_type = String()
|
| string_type = string_type.with_variant(
| mysql.VARCHAR(collation="foo"), "mysql", "mariadb"
| )
|
| The variant mapping indicates that when this type is
| interpreted by a specific dialect, it will instead be
| transmuted into the given type, rather than using the
| primary type.
|
| .. versionchanged:: 2.0 the :meth:`_types.TypeEngine.with_variant`
| method now works with a :class:`_types.TypeEngine` object "in
| place", returning a copy of the original type rather than returning
| a wrapping object; the ``Variant`` class is no longer used.
|
| :param type\_: a :class:`.TypeEngine` that will be selected
| as a variant from the originating type, when a dialect
| of the given name is in use.
| :param \*dialect_names: one or more base names of the dialect which
| uses this type. (i.e. ``'postgresql'``, ``'mysql'``, etc.)
|
| .. versionchanged:: 2.0 multiple dialect names can be specified
| for one variant.
|
| .. seealso::
|
| :ref:`types_with_variant` - illustrates the use of
| :meth:`_types.TypeEngine.with_variant`.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.type_api.TypeEngine:
|
| __orig_bases__ = (<class 'sqlalchemy.sql.visitors.Visitable'>, typing....
|
| hashable = True
|
| render_bind_cast = False
|
| render_literal_cast = False
|
| should_evaluate_none = False
|
| sort_key_function = None
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.visitors.Visitable:
|
| __class_getitem__(key: 'Any') -> 'Any'
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__() -> 'None'
| This method is called when a class is subclassed.
|
| The default implementation does nothing. It may be
| overridden to extend subclasses.
sqlalchemy.BinaryExpression
Python Library Documentation: class BinaryExpression in module sqlalchemy.sql.elements
class BinaryExpression(OperatorExpression)
| BinaryExpression(left: 'ColumnElement[Any]', right: 'ColumnElement[Any]', operator: 'OperatorType', type_: 'Optional[_TypeEngineArgument[_T]]' = None, negate: 'Optional[OperatorType]' = None, modifiers: 'Optional[Mapping[str, Any]]' = None)
|
| Represent an expression that is ``LEFT <operator> RIGHT``.
|
| A :class:`.BinaryExpression` is generated automatically
| whenever two column expressions are used in a Python binary expression:
|
| .. sourcecode:: pycon+sql
|
| >>> from sqlalchemy.sql import column
| >>> column("a") + column("b")
| <sqlalchemy.sql.expression.BinaryExpression object at 0x101029dd0>
| >>> print(column("a") + column("b"))
| {printsql}a + b
|
| Method resolution order:
| BinaryExpression
| OperatorExpression
| ColumnElement
| sqlalchemy.sql.roles.ColumnArgumentOrKeyRole
| sqlalchemy.sql.roles.ColumnArgumentRole
| sqlalchemy.sql.roles.StatementOptionRole
| sqlalchemy.sql.roles.WhereHavingRole
| sqlalchemy.sql.roles.OnClauseRole
| sqlalchemy.sql.roles.BinaryElementRole
| sqlalchemy.sql.roles.OrderByRole
| sqlalchemy.sql.roles.ColumnsClauseRole
| sqlalchemy.sql.roles.AllowsLambdaRole
| sqlalchemy.sql.roles.ByOfRole
| sqlalchemy.sql.roles.UsesInspection
| sqlalchemy.sql.roles.ColumnListRole
| sqlalchemy.sql.roles.LimitOffsetRole
| sqlalchemy.sql.roles.DMLColumnRole
| sqlalchemy.sql.roles.DDLConstraintColumnRole
| sqlalchemy.sql.roles.DDLExpressionRole
| sqlalchemy.sql.roles.StructuralRole
| SQLColumnExpression
| SQLCoreOperations
| sqlalchemy.sql.roles.ExpressionElementRole
| sqlalchemy.sql.roles.TypedColumnsClauseRole
| typing.Generic
| sqlalchemy.sql.operators.ColumnOperators
| sqlalchemy.sql.operators.Operators
| sqlalchemy.util.langhelpers.TypingOnly
| sqlalchemy.sql.roles.SQLRole
| DQLDMLClauseElement
| ClauseElement
| sqlalchemy.sql.annotation.SupportsWrappingAnnotations
| sqlalchemy.sql.annotation.SupportsAnnotations
| sqlalchemy.sql.cache_key.MemoizedHasCacheKey
| sqlalchemy.sql.cache_key.HasCacheKey
| sqlalchemy.util.langhelpers.HasMemoized
| sqlalchemy.sql.traversals.HasCopyInternals
| sqlalchemy.sql.visitors.ExternallyTraversible
| sqlalchemy.sql.visitors.HasTraverseInternals
| CompilerElement
| sqlalchemy.sql.visitors.Visitable
| builtins.object
|
| Methods defined here:
|
| __bool__(self)
| Implement Python-side "bool" for BinaryExpression as a
| simple "identity" check for the left and right attributes,
| if the operator is "eq" or "ne". Otherwise the expression
| continues to not support "bool" like all other column expressions.
|
| The rationale here is so that ColumnElement objects can be hashable.
| What? Well, suppose you do this::
|
| c1, c2 = column("x"), column("y")
| s1 = set([c1, c2])
|
| We do that **a lot**, columns inside of sets is an extremely basic
| thing all over the ORM for example.
|
| So what happens if we do this? ::
|
| c1 in s1
|
| Hashing means it will normally use ``__hash__()`` of the object,
| but in case of hash collision, it's going to also do ``c1 == c1``
| and/or ``c1 == c2`` inside. Those operations need to return a
| True/False value. But because we override ``==`` and ``!=``, they're
| going to get a BinaryExpression. Hence we implement ``__bool__`` here
| so that these comparisons behave in this particular context mostly
| like regular object comparisons. Thankfully Python is OK with
| that! Otherwise we'd have to use special set classes for columns
| (which we used to do, decades ago).
|
| __init__(self, left: 'ColumnElement[Any]', right: 'ColumnElement[Any]', operator: 'OperatorType', type_: 'Optional[_TypeEngineArgument[_T]]' = None, negate: 'Optional[OperatorType]' = None, modifiers: 'Optional[Mapping[str, Any]]' = None)
| Initialize self. See help(type(self)) for accurate signature.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'_traverse_internals': '_TraverseInternalsType', 'l...
|
| __orig_bases__ = (sqlalchemy.sql.elements.OperatorExpression[~_T],)
|
| __parameters__ = (~_T,)
|
| __visit_name__ = 'binary'
|
| ----------------------------------------------------------------------
| Methods inherited from OperatorExpression:
|
| self_group(self, against: 'Optional[OperatorType]' = None) -> 'Union[Self, Grouping[_T]]'
| 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.
|
| ----------------------------------------------------------------------
| Readonly properties inherited from OperatorExpression:
|
| is_comparison
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from OperatorExpression:
|
| group = True
|
| ----------------------------------------------------------------------
| Methods inherited from ColumnElement:
|
| __getattr__(self, key: 'str') -> 'Any'
|
| __setstate__(self, state)
|
| base_columns(...)
|
| cast(self, type_: '_TypeEngineArgument[_OPT]') -> 'Cast[_OPT]'
| Produce a type cast, i.e. ``CAST(<expression> AS <type>)``.
|
| This is a shortcut to the :func:`_expression.cast` function.
|
| .. seealso::
|
| :ref:`tutorial_casts`
|
| :func:`_expression.cast`
|
| :func:`_expression.type_coerce`
|
| comparator(...)
|
| label(self, name: 'Optional[str]') -> 'Label[_T]'
| Produce a column label, i.e. ``<columnname> AS <name>``.
|
| This is a shortcut to the :func:`_expression.label` function.
|
| If 'name' is ``None``, an anonymous label name will be generated.
|
| operate(self, op: 'operators.OperatorType', *other: 'Any', **kwargs: 'Any') -> 'ColumnElement[Any]'
| Operate on an argument.
|
| This is the lowest level of operation, raises
| :class:`NotImplementedError` by default.
|
| Overriding this on a subclass can allow common
| behavior to be applied to all operations.
| For example, overriding :class:`.ColumnOperators`
| to apply ``func.lower()`` to the left and right
| side::
|
| class MyComparator(ColumnOperators):
| def operate(self, op, other, **kwargs):
| return op(func.lower(self), func.lower(other), **kwargs)
|
| :param op: Operator callable.
| :param \*other: the 'other' side of the operation. Will
| be a single scalar for most operations.
| :param \**kwargs: modifiers. These may be passed by special
| operators such as :meth:`ColumnOperators.contains`.
|
| proxy_set(...)
| set of all columns we are proxying
|
| as of 2.0 this is explicitly deannotated columns. previously it was
| effectively deannotated columns but wasn't enforced. annotated
| columns should basically not go into sets if at all possible because
| their hashing behavior is very non-performant.
|
| reverse_operate(self, op: 'operators.OperatorType', other: 'Any', **kwargs: 'Any') -> 'ColumnElement[Any]'
| Reverse operate on an argument.
|
| Usage is the same as :meth:`operate`.
|
| shares_lineage(self, othercolumn: 'ColumnElement[Any]') -> 'bool'
| Return True if the given :class:`_expression.ColumnElement`
| has a common ancestor to this :class:`_expression.ColumnElement`.
|
| type(...)
|
| ----------------------------------------------------------------------
| Readonly properties inherited from ColumnElement:
|
| anon_key_label
| .. deprecated:: 1.4 The :attr:`_expression.ColumnElement.anon_key_label` attribute is now private, and the public accessor is deprecated.
|
| anon_label
| .. deprecated:: 1.4 The :attr:`_expression.ColumnElement.anon_label` attribute is now private, and the public accessor is deprecated.
|
| expression
| Return a column expression.
|
| Part of the inspection interface; returns self.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from ColumnElement:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from ColumnElement:
|
| foreign_keys = frozenset()
|
| key = None
|
| primary_key = False
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.AllowsLambdaRole:
|
| allows_lambda = True
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.UsesInspection:
|
| uses_inspection = True
|
| ----------------------------------------------------------------------
| Class methods inherited from typing.Generic:
|
| __class_getitem__(...)
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__(...)
| Function to initialize subclasses.
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.operators.ColumnOperators:
|
| __add__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``+`` operator.
|
| In a column context, produces the clause ``a + b``
| if the parent object has non-string affinity.
| If the parent object has a string affinity,
| produces the concatenation operator, ``a || b`` -
| see :meth:`.ColumnOperators.concat`.
|
| __contains__(self, other: 'Any') -> 'ColumnOperators'
|
| __eq__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``==`` operator.
|
| In a column context, produces the clause ``a = b``.
| If the target is ``None``, produces ``a IS NULL``.
|
| __floordiv__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``//`` operator.
|
| In a column context, produces the clause ``a / b``,
| which is the same as "truediv", but considers the result
| type to be integer.
|
| .. versionadded:: 2.0
|
| __ge__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``>=`` operator.
|
| In a column context, produces the clause ``a >= b``.
|
| __getitem__(self, index: 'Any') -> 'ColumnOperators'
| Implement the [] operator.
|
| This can be used by some database-specific types
| such as PostgreSQL ARRAY and HSTORE.
|
| __gt__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``>`` operator.
|
| In a column context, produces the clause ``a > b``.
|
| __hash__(self, /) from builtins.object
| Return hash(self).
|
| __le__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``<=`` operator.
|
| In a column context, produces the clause ``a <= b``.
|
| __lshift__(self, other: 'Any') -> 'ColumnOperators'
| implement the << operator.
|
| Not used by SQLAlchemy core, this is provided
| for custom operator systems which want to use
| << as an extension point.
|
| __lt__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``<`` operator.
|
| In a column context, produces the clause ``a < b``.
|
| __mod__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``%`` operator.
|
| In a column context, produces the clause ``a % b``.
|
| __mul__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``*`` operator.
|
| In a column context, produces the clause ``a * b``.
|
| __ne__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``!=`` operator.
|
| In a column context, produces the clause ``a != b``.
| If the target is ``None``, produces ``a IS NOT NULL``.
|
| __neg__(self) -> 'ColumnOperators'
| Implement the ``-`` operator.
|
| In a column context, produces the clause ``-a``.
|
| __radd__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``+`` operator in reverse.
|
| See :meth:`.ColumnOperators.__add__`.
|
| __rfloordiv__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``//`` operator in reverse.
|
| See :meth:`.ColumnOperators.__floordiv__`.
|
| __rmod__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``%`` operator in reverse.
|
| See :meth:`.ColumnOperators.__mod__`.
|
| __rmul__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``*`` operator in reverse.
|
| See :meth:`.ColumnOperators.__mul__`.
|
| __rshift__(self, other: 'Any') -> 'ColumnOperators'
| implement the >> operator.
|
| Not used by SQLAlchemy core, this is provided
| for custom operator systems which want to use
| >> as an extension point.
|
| __rsub__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``-`` operator in reverse.
|
| See :meth:`.ColumnOperators.__sub__`.
|
| __rtruediv__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``/`` operator in reverse.
|
| See :meth:`.ColumnOperators.__truediv__`.
|
| __sub__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``-`` operator.
|
| In a column context, produces the clause ``a - b``.
|
| __truediv__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``/`` operator.
|
| In a column context, produces the clause ``a / b``, and
| considers the result type to be numeric.
|
| .. versionchanged:: 2.0 The truediv operator against two integers
| is now considered to return a numeric value. Behavior on specific
| backends may vary.
|
| all_(self) -> 'ColumnOperators'
| Produce an :func:`_expression.all_` clause against the
| parent object.
|
| See the documentation for :func:`_sql.all_` for examples.
|
| .. note:: be sure to not confuse the newer
| :meth:`_sql.ColumnOperators.all_` method with the **legacy**
| version of this method, the :meth:`_types.ARRAY.Comparator.all`
| method that's specific to :class:`_types.ARRAY`, which uses a
| different calling style.
|
| any_(self) -> 'ColumnOperators'
| Produce an :func:`_expression.any_` clause against the
| parent object.
|
| See the documentation for :func:`_sql.any_` for examples.
|
| .. note:: be sure to not confuse the newer
| :meth:`_sql.ColumnOperators.any_` method with the **legacy**
| version of this method, the :meth:`_types.ARRAY.Comparator.any`
| method that's specific to :class:`_types.ARRAY`, which uses a
| different calling style.
|
| asc(self) -> 'ColumnOperators'
| Produce a :func:`_expression.asc` clause against the
| parent object.
|
| between(self, cleft: 'Any', cright: 'Any', symmetric: 'bool' = False) -> 'ColumnOperators'
| Produce a :func:`_expression.between` clause against
| the parent object, given the lower and upper range.
|
| bitwise_and(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise AND operation, typically via the ``&``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_lshift(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise LSHIFT operation, typically via the ``<<``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_not(self) -> 'ColumnOperators'
| Produce a bitwise NOT operation, typically via the ``~``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_or(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise OR operation, typically via the ``|``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_rshift(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise RSHIFT operation, typically via the ``>>``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_xor(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise XOR operation, typically via the ``^``
| operator, or ``#`` for PostgreSQL.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| collate(self, collation: 'str') -> 'ColumnOperators'
| Produce a :func:`_expression.collate` clause against
| the parent object, given the collation string.
|
| .. seealso::
|
| :func:`_expression.collate`
|
| concat(self, other: 'Any') -> 'ColumnOperators'
| Implement the 'concat' operator.
|
| In a column context, produces the clause ``a || b``,
| or uses the ``concat()`` operator on MySQL.
|
| contains(self, other: 'Any', **kw: 'Any') -> 'ColumnOperators'
| Implement the 'contains' operator.
|
| Produces a LIKE expression that tests against a match for the middle
| of a string value:
|
| .. sourcecode:: sql
|
| column LIKE '%' || <other> || '%'
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.contains("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.contains.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.contains.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.contains.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.contains("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE '%' || :param || '%' ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.contains("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE '%' || :param || '%' ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.contains.autoescape`::
|
| somecolumn.contains("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.startswith`
|
| :meth:`.ColumnOperators.endswith`
|
| :meth:`.ColumnOperators.like`
|
| desc(self) -> 'ColumnOperators'
| Produce a :func:`_expression.desc` clause against the
| parent object.
|
| distinct(self) -> 'ColumnOperators'
| Produce a :func:`_expression.distinct` clause against the
| parent object.
|
| endswith(self, other: 'Any', escape: 'Optional[str]' = None, autoescape: 'bool' = False) -> 'ColumnOperators'
| Implement the 'endswith' operator.
|
| Produces a LIKE expression that tests against a match for the end
| of a string value:
|
| .. sourcecode:: sql
|
| column LIKE '%' || <other>
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.endswith("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.endswith.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.endswith.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.endswith.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.endswith("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE '%' || :param ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.endswith("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE '%' || :param ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.endswith.autoescape`::
|
| somecolumn.endswith("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.startswith`
|
| :meth:`.ColumnOperators.contains`
|
| :meth:`.ColumnOperators.like`
|
| icontains(self, other: 'Any', **kw: 'Any') -> 'ColumnOperators'
| Implement the ``icontains`` operator, e.g. case insensitive
| version of :meth:`.ColumnOperators.contains`.
|
| Produces a LIKE expression that tests against an insensitive match
| for the middle of a string value:
|
| .. sourcecode:: sql
|
| lower(column) LIKE '%' || lower(<other>) || '%'
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.icontains("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.icontains.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.icontains.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.icontains.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.icontains("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE '%' || lower(:param) || '%' ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.icontains("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE '%' || lower(:param) || '%' ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.contains.autoescape`::
|
| somecolumn.icontains("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.contains`
|
| iendswith(self, other: 'Any', escape: 'Optional[str]' = None, autoescape: 'bool' = False) -> 'ColumnOperators'
| Implement the ``iendswith`` operator, e.g. case insensitive
| version of :meth:`.ColumnOperators.endswith`.
|
| Produces a LIKE expression that tests against an insensitive match
| for the end of a string value:
|
| .. sourcecode:: sql
|
| lower(column) LIKE '%' || lower(<other>)
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.iendswith("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.iendswith.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.iendswith.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.iendswith.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.iendswith("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE '%' || lower(:param) ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.iendswith("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE '%' || lower(:param) ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.iendswith.autoescape`::
|
| somecolumn.endswith("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.endswith`
|
| ilike(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
| Implement the ``ilike`` operator, e.g. case insensitive LIKE.
|
| In a column context, produces an expression either of the form:
|
| .. sourcecode:: sql
|
| lower(a) LIKE lower(other)
|
| Or on backends that support the ILIKE operator:
|
| .. sourcecode:: sql
|
| a ILIKE other
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.ilike("%foobar%"))
|
| :param other: expression to be compared
| :param escape: optional escape character, renders the ``ESCAPE``
| keyword, e.g.::
|
| somecolumn.ilike("foo/%bar", escape="/")
|
| .. seealso::
|
| :meth:`.ColumnOperators.like`
|
| in_(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``in`` operator.
|
| In a column context, produces the clause ``column IN <other>``.
|
| The given parameter ``other`` may be:
|
| * A list of literal values,
| e.g.::
|
| stmt.where(column.in_([1, 2, 3]))
|
| In this calling form, the list of items is converted to a set of
| bound parameters the same length as the list given:
|
| .. sourcecode:: sql
|
| WHERE COL IN (?, ?, ?)
|
| * A list of tuples may be provided if the comparison is against a
| :func:`.tuple_` containing multiple expressions::
|
| from sqlalchemy import tuple_
|
| stmt.where(tuple_(col1, col2).in_([(1, 10), (2, 20), (3, 30)]))
|
| * An empty list,
| e.g.::
|
| stmt.where(column.in_([]))
|
| In this calling form, the expression renders an "empty set"
| expression. These expressions are tailored to individual backends
| and are generally trying to get an empty SELECT statement as a
| subquery. Such as on SQLite, the expression is:
|
| .. sourcecode:: sql
|
| WHERE col IN (SELECT 1 FROM (SELECT 1) WHERE 1!=1)
|
| .. versionchanged:: 1.4 empty IN expressions now use an
| execution-time generated SELECT subquery in all cases.
|
| * A bound parameter, e.g. :func:`.bindparam`, may be used if it
| includes the :paramref:`.bindparam.expanding` flag::
|
| stmt.where(column.in_(bindparam("value", expanding=True)))
|
| In this calling form, the expression renders a special non-SQL
| placeholder expression that looks like:
|
| .. sourcecode:: sql
|
| WHERE COL IN ([EXPANDING_value])
|
| This placeholder expression is intercepted at statement execution
| time to be converted into the variable number of bound parameter
| form illustrated earlier. If the statement were executed as::
|
| connection.execute(stmt, {"value": [1, 2, 3]})
|
| The database would be passed a bound parameter for each value:
|
| .. sourcecode:: sql
|
| WHERE COL IN (?, ?, ?)
|
| .. versionadded:: 1.2 added "expanding" bound parameters
|
| If an empty list is passed, a special "empty list" expression,
| which is specific to the database in use, is rendered. On
| SQLite this would be:
|
| .. sourcecode:: sql
|
| WHERE COL IN (SELECT 1 FROM (SELECT 1) WHERE 1!=1)
|
| .. versionadded:: 1.3 "expanding" bound parameters now support
| empty lists
|
| * a :func:`_expression.select` construct, which is usually a
| correlated scalar select::
|
| stmt.where(
| column.in_(select(othertable.c.y).where(table.c.x == othertable.c.x))
| )
|
| In this calling form, :meth:`.ColumnOperators.in_` renders as given:
|
| .. sourcecode:: sql
|
| WHERE COL IN (SELECT othertable.y
| FROM othertable WHERE othertable.x = table.x)
|
| :param other: a list of literals, a :func:`_expression.select`
| construct, or a :func:`.bindparam` construct that includes the
| :paramref:`.bindparam.expanding` flag set to True.
|
| is_(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``IS`` operator.
|
| Normally, ``IS`` is generated automatically when comparing to a
| value of ``None``, which resolves to ``NULL``. However, explicit
| usage of ``IS`` may be desirable if comparing to boolean values
| on certain platforms.
|
| .. seealso:: :meth:`.ColumnOperators.is_not`
|
| is_distinct_from(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``IS DISTINCT FROM`` operator.
|
| Renders "a IS DISTINCT FROM b" on most platforms;
| on some such as SQLite may render "a IS NOT b".
|
| is_not(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``IS NOT`` operator.
|
| Normally, ``IS NOT`` is generated automatically when comparing to a
| value of ``None``, which resolves to ``NULL``. However, explicit
| usage of ``IS NOT`` may be desirable if comparing to boolean values
| on certain platforms.
|
| .. versionchanged:: 1.4 The ``is_not()`` operator is renamed from
| ``isnot()`` in previous releases. The previous name remains
| available for backwards compatibility.
|
| .. seealso:: :meth:`.ColumnOperators.is_`
|
| is_not_distinct_from(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``IS NOT DISTINCT FROM`` operator.
|
| Renders "a IS NOT DISTINCT FROM b" on most platforms;
| on some such as SQLite may render "a IS b".
|
| .. versionchanged:: 1.4 The ``is_not_distinct_from()`` operator is
| renamed from ``isnot_distinct_from()`` in previous releases.
| The previous name remains available for backwards compatibility.
|
| isnot = is_not(self, other: 'Any') -> 'ColumnOperators'
|
| isnot_distinct_from = is_not_distinct_from(self, other: 'Any') -> 'ColumnOperators'
|
| istartswith(self, other: 'Any', escape: 'Optional[str]' = None, autoescape: 'bool' = False) -> 'ColumnOperators'
| Implement the ``istartswith`` operator, e.g. case insensitive
| version of :meth:`.ColumnOperators.startswith`.
|
| Produces a LIKE expression that tests against an insensitive
| match for the start of a string value:
|
| .. sourcecode:: sql
|
| lower(column) LIKE lower(<other>) || '%'
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.istartswith("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.istartswith.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.istartswith.escape` parameter will
| establish a given character as an escape character which can be of
| use when the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.istartswith.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.istartswith("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE lower(:param) || '%' ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.istartswith("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE lower(:param) || '%' ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.istartswith.autoescape`::
|
| somecolumn.istartswith("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.startswith`
|
| like(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
| Implement the ``like`` operator.
|
| In a column context, produces the expression:
|
| .. sourcecode:: sql
|
| a LIKE other
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.like("%foobar%"))
|
| :param other: expression to be compared
| :param escape: optional escape character, renders the ``ESCAPE``
| keyword, e.g.::
|
| somecolumn.like("foo/%bar", escape="/")
|
| .. seealso::
|
| :meth:`.ColumnOperators.ilike`
|
| match(self, other: 'Any', **kwargs: 'Any') -> 'ColumnOperators'
| Implements a database-specific 'match' operator.
|
| :meth:`_sql.ColumnOperators.match` attempts to resolve to
| a MATCH-like function or operator provided by the backend.
| Examples include:
|
| * PostgreSQL - renders ``x @@ plainto_tsquery(y)``
|
| .. versionchanged:: 2.0 ``plainto_tsquery()`` is used instead
| of ``to_tsquery()`` for PostgreSQL now; for compatibility with
| other forms, see :ref:`postgresql_match`.
|
|
| * MySQL - renders ``MATCH (x) AGAINST (y IN BOOLEAN MODE)``
|
| .. seealso::
|
| :class:`_mysql.match` - MySQL specific construct with
| additional features.
|
| * Oracle Database - renders ``CONTAINS(x, y)``
| * other backends may provide special implementations.
| * Backends without any special implementation will emit
| the operator as "MATCH". This is compatible with SQLite, for
| example.
|
| not_ilike(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
| implement the ``NOT ILIKE`` operator.
|
| This is equivalent to using negation with
| :meth:`.ColumnOperators.ilike`, i.e. ``~x.ilike(y)``.
|
| .. versionchanged:: 1.4 The ``not_ilike()`` operator is renamed from
| ``notilike()`` in previous releases. The previous name remains
| available for backwards compatibility.
|
| .. seealso::
|
| :meth:`.ColumnOperators.ilike`
|
| not_in(self, other: 'Any') -> 'ColumnOperators'
| implement the ``NOT IN`` operator.
|
| This is equivalent to using negation with
| :meth:`.ColumnOperators.in_`, i.e. ``~x.in_(y)``.
|
| In the case that ``other`` is an empty sequence, the compiler
| produces an "empty not in" expression. This defaults to the
| expression "1 = 1" to produce true in all cases. The
| :paramref:`_sa.create_engine.empty_in_strategy` may be used to
| alter this behavior.
|
| .. versionchanged:: 1.4 The ``not_in()`` operator is renamed from
| ``notin_()`` in previous releases. The previous name remains
| available for backwards compatibility.
|
| .. versionchanged:: 1.2 The :meth:`.ColumnOperators.in_` and
| :meth:`.ColumnOperators.not_in` operators
| now produce a "static" expression for an empty IN sequence
| by default.
|
| .. seealso::
|
| :meth:`.ColumnOperators.in_`
|
| not_like(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
| implement the ``NOT LIKE`` operator.
|
| This is equivalent to using negation with
| :meth:`.ColumnOperators.like`, i.e. ``~x.like(y)``.
|
| .. versionchanged:: 1.4 The ``not_like()`` operator is renamed from
| ``notlike()`` in previous releases. The previous name remains
| available for backwards compatibility.
|
| .. seealso::
|
| :meth:`.ColumnOperators.like`
|
| notilike = not_ilike(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
|
| notin_ = not_in(self, other: 'Any') -> 'ColumnOperators'
|
| notlike = not_like(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
|
| nulls_first(self) -> 'ColumnOperators'
| Produce a :func:`_expression.nulls_first` clause against the
| parent object.
|
| .. versionchanged:: 1.4 The ``nulls_first()`` operator is
| renamed from ``nullsfirst()`` in previous releases.
| The previous name remains available for backwards compatibility.
|
| nulls_last(self) -> 'ColumnOperators'
| Produce a :func:`_expression.nulls_last` clause against the
| parent object.
|
| .. versionchanged:: 1.4 The ``nulls_last()`` operator is
| renamed from ``nullslast()`` in previous releases.
| The previous name remains available for backwards compatibility.
|
| nullsfirst = nulls_first(self) -> 'ColumnOperators'
|
| nullslast = nulls_last(self) -> 'ColumnOperators'
|
| regexp_match(self, pattern: 'Any', flags: 'Optional[str]' = None) -> 'ColumnOperators'
| Implements a database-specific 'regexp match' operator.
|
| E.g.::
|
| stmt = select(table.c.some_column).where(
| table.c.some_column.regexp_match("^(b|c)")
| )
|
| :meth:`_sql.ColumnOperators.regexp_match` attempts to resolve to
| a REGEXP-like function or operator provided by the backend, however
| the specific regular expression syntax and flags available are
| **not backend agnostic**.
|
| Examples include:
|
| * PostgreSQL - renders ``x ~ y`` or ``x !~ y`` when negated.
| * Oracle Database - renders ``REGEXP_LIKE(x, y)``
| * SQLite - uses SQLite's ``REGEXP`` placeholder operator and calls into
| the Python ``re.match()`` builtin.
| * other backends may provide special implementations.
| * Backends without any special implementation will emit
| the operator as "REGEXP" or "NOT REGEXP". This is compatible with
| SQLite and MySQL, for example.
|
| Regular expression support is currently implemented for Oracle
| Database, PostgreSQL, MySQL and MariaDB. Partial support is available
| for SQLite. Support among third-party dialects may vary.
|
| :param pattern: The regular expression pattern string or column
| clause.
| :param flags: Any regular expression string flags to apply, passed as
| plain Python string only. These flags are backend specific.
| Some backends, like PostgreSQL and MariaDB, may alternatively
| specify the flags as part of the pattern.
| When using the ignore case flag 'i' in PostgreSQL, the ignore case
| regexp match operator ``~*`` or ``!~*`` will be used.
|
| .. versionadded:: 1.4
|
| .. versionchanged:: 1.4.48, 2.0.18 Note that due to an implementation
| error, the "flags" parameter previously accepted SQL expression
| objects such as column expressions in addition to plain Python
| strings. This implementation did not work correctly with caching
| and was removed; strings only should be passed for the "flags"
| parameter, as these flags are rendered as literal inline values
| within SQL expressions.
|
| .. seealso::
|
| :meth:`_sql.ColumnOperators.regexp_replace`
|
| regexp_replace(self, pattern: 'Any', replacement: 'Any', flags: 'Optional[str]' = None) -> 'ColumnOperators'
| Implements a database-specific 'regexp replace' operator.
|
| E.g.::
|
| stmt = select(
| table.c.some_column.regexp_replace("b(..)", "XY", flags="g")
| )
|
| :meth:`_sql.ColumnOperators.regexp_replace` attempts to resolve to
| a REGEXP_REPLACE-like function provided by the backend, that
| usually emit the function ``REGEXP_REPLACE()``. However,
| the specific regular expression syntax and flags available are
| **not backend agnostic**.
|
| Regular expression replacement support is currently implemented for
| Oracle Database, PostgreSQL, MySQL 8 or greater and MariaDB. Support
| among third-party dialects may vary.
|
| :param pattern: The regular expression pattern string or column
| clause.
| :param pattern: The replacement string or column clause.
| :param flags: Any regular expression string flags to apply, passed as
| plain Python string only. These flags are backend specific.
| Some backends, like PostgreSQL and MariaDB, may alternatively
| specify the flags as part of the pattern.
|
| .. versionadded:: 1.4
|
| .. versionchanged:: 1.4.48, 2.0.18 Note that due to an implementation
| error, the "flags" parameter previously accepted SQL expression
| objects such as column expressions in addition to plain Python
| strings. This implementation did not work correctly with caching
| and was removed; strings only should be passed for the "flags"
| parameter, as these flags are rendered as literal inline values
| within SQL expressions.
|
|
| .. seealso::
|
| :meth:`_sql.ColumnOperators.regexp_match`
|
| startswith(self, other: 'Any', escape: 'Optional[str]' = None, autoescape: 'bool' = False) -> 'ColumnOperators'
| Implement the ``startswith`` operator.
|
| Produces a LIKE expression that tests against a match for the start
| of a string value:
|
| .. sourcecode:: sql
|
| column LIKE <other> || '%'
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.startswith("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.startswith.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.startswith.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.startswith.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.startswith("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE :param || '%' ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.startswith("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE :param || '%' ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.startswith.autoescape`::
|
| somecolumn.startswith("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.endswith`
|
| :meth:`.ColumnOperators.contains`
|
| :meth:`.ColumnOperators.like`
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.operators.ColumnOperators:
|
| timetuple = None
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.operators.Operators:
|
| __and__(self, other: 'Any') -> 'Operators'
| Implement the ``&`` operator.
|
| When used with SQL expressions, results in an
| AND operation, equivalent to
| :func:`_expression.and_`, that is::
|
| a & b
|
| is equivalent to::
|
| from sqlalchemy import and_
|
| and_(a, b)
|
| Care should be taken when using ``&`` regarding
| operator precedence; the ``&`` operator has the highest precedence.
| The operands should be enclosed in parenthesis if they contain
| further sub expressions::
|
| (a == 2) & (b == 4)
|
| __invert__(self) -> 'Operators'
| Implement the ``~`` operator.
|
| When used with SQL expressions, results in a
| NOT operation, equivalent to
| :func:`_expression.not_`, that is::
|
| ~a
|
| is equivalent to::
|
| from sqlalchemy import not_
|
| not_(a)
|
| __or__(self, other: 'Any') -> 'Operators'
| Implement the ``|`` operator.
|
| When used with SQL expressions, results in an
| OR operation, equivalent to
| :func:`_expression.or_`, that is::
|
| a | b
|
| is equivalent to::
|
| from sqlalchemy import or_
|
| or_(a, b)
|
| Care should be taken when using ``|`` regarding
| operator precedence; the ``|`` operator has the highest precedence.
| The operands should be enclosed in parenthesis if they contain
| further sub expressions::
|
| (a == 2) | (b == 4)
|
| __sa_operate__ = operate(self, op: 'OperatorType', *other: 'Any', **kwargs: 'Any') -> 'Operators'
| Operate on an argument.
|
| This is the lowest level of operation, raises
| :class:`NotImplementedError` by default.
|
| Overriding this on a subclass can allow common
| behavior to be applied to all operations.
| For example, overriding :class:`.ColumnOperators`
| to apply ``func.lower()`` to the left and right
| side::
|
| class MyComparator(ColumnOperators):
| def operate(self, op, other, **kwargs):
| return op(func.lower(self), func.lower(other), **kwargs)
|
| :param op: Operator callable.
| :param \*other: the 'other' side of the operation. Will
| be a single scalar for most operations.
| :param \**kwargs: modifiers. These may be passed by special
| operators such as :meth:`ColumnOperators.contains`.
|
| bool_op(self, opstring: 'str', precedence: 'int' = 0, python_impl: 'Optional[Callable[..., Any]]' = None) -> 'Callable[[Any], Operators]'
| Return a custom boolean operator.
|
| This method is shorthand for calling
| :meth:`.Operators.op` and passing the
| :paramref:`.Operators.op.is_comparison`
| flag with True. A key advantage to using :meth:`.Operators.bool_op`
| is that when using column constructs, the "boolean" nature of the
| returned expression will be present for :pep:`484` purposes.
|
| .. seealso::
|
| :meth:`.Operators.op`
|
| op(self, opstring: 'str', precedence: 'int' = 0, is_comparison: 'bool' = False, return_type: 'Optional[Union[Type[TypeEngine[Any]], TypeEngine[Any]]]' = None, python_impl: 'Optional[Callable[..., Any]]' = None) -> 'Callable[[Any], Operators]'
| Produce a generic operator function.
|
| e.g.::
|
| somecolumn.op("*")(5)
|
| produces::
|
| somecolumn * 5
|
| This function can also be used to make bitwise operators explicit. For
| example::
|
| somecolumn.op("&")(0xFF)
|
| is a bitwise AND of the value in ``somecolumn``.
|
| :param opstring: a string which will be output as the infix operator
| between this element and the expression passed to the
| generated function.
|
| :param precedence: precedence which the database is expected to apply
| to the operator in SQL expressions. This integer value acts as a hint
| for the SQL compiler to know when explicit parenthesis should be
| rendered around a particular operation. A lower number will cause the
| expression to be parenthesized when applied against another operator
| with higher precedence. The default value of ``0`` is lower than all
| operators except for the comma (``,``) and ``AS`` operators. A value
| of 100 will be higher or equal to all operators, and -100 will be
| lower than or equal to all operators.
|
| .. seealso::
|
| :ref:`faq_sql_expression_op_parenthesis` - detailed description
| of how the SQLAlchemy SQL compiler renders parenthesis
|
| :param is_comparison: legacy; if True, the operator will be considered
| as a "comparison" operator, that is which evaluates to a boolean
| true/false value, like ``==``, ``>``, etc. This flag is provided
| so that ORM relationships can establish that the operator is a
| comparison operator when used in a custom join condition.
|
| Using the ``is_comparison`` parameter is superseded by using the
| :meth:`.Operators.bool_op` method instead; this more succinct
| operator sets this parameter automatically, but also provides
| correct :pep:`484` typing support as the returned object will
| express a "boolean" datatype, i.e. ``BinaryExpression[bool]``.
|
| :param return_type: a :class:`.TypeEngine` class or object that will
| force the return type of an expression produced by this operator
| to be of that type. By default, operators that specify
| :paramref:`.Operators.op.is_comparison` will resolve to
| :class:`.Boolean`, and those that do not will be of the same
| type as the left-hand operand.
|
| :param python_impl: an optional Python function that can evaluate
| two Python values in the same way as this operator works when
| run on the database server. Useful for in-Python SQL expression
| evaluation functions, such as for ORM hybrid attributes, and the
| ORM "evaluator" used to match objects in a session after a multi-row
| update or delete.
|
| e.g.::
|
| >>> expr = column("x").op("+", python_impl=lambda a, b: a + b)("y")
|
| The operator for the above expression will also work for non-SQL
| left and right objects::
|
| >>> expr.operator(5, 10)
| 15
|
| .. versionadded:: 2.0
|
|
| .. seealso::
|
| :meth:`.Operators.bool_op`
|
| :ref:`types_operators`
|
| :ref:`relationship_custom_operator`
|
| ----------------------------------------------------------------------
| Methods inherited from ClauseElement:
|
| __getstate__(self)
| Helper for pickle.
|
| __repr__(self)
| Return repr(self).
|
| compare(self, other: 'ClauseElement', **kw: 'Any') -> 'bool'
| Compare this :class:`_expression.ClauseElement` to
| the given :class:`_expression.ClauseElement`.
|
| Subclasses should override the default behavior, which is a
| straight identity comparison.
|
| \**kw are arguments consumed by subclass ``compare()`` methods and
| may be used to modify the criteria for comparison
| (see :class:`_expression.ColumnElement`).
|
| description(...)
|
| entity_namespace(...)
|
| params(self, _ClauseElement__optionaldict: 'Optional[Mapping[str, Any]]' = None, **kwargs: 'Any') -> 'Self'
| Return a copy with :func:`_expression.bindparam` elements
| replaced.
|
| Returns a copy of this ClauseElement with
| :func:`_expression.bindparam`
| elements replaced with values taken from the given dictionary::
|
| >>> clause = column("x") + bindparam("foo")
| >>> print(clause.compile().params)
| {'foo':None}
| >>> print(clause.params({"foo": 7}).compile().params)
| {'foo':7}
|
| unique_params(self, _ClauseElement__optionaldict: 'Optional[Dict[str, Any]]' = None, **kwargs: 'Any') -> 'Self'
| Return a copy with :func:`_expression.bindparam` elements
| replaced.
|
| Same functionality as :meth:`_expression.ClauseElement.params`,
| except adds `unique=True`
| to affected bind parameters so that multiple statements can be
| used.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from ClauseElement:
|
| is_clause_element = True
|
| is_dml = False
|
| is_selectable = False
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.cache_key.HasCacheKey:
|
| inherit_cache = None
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_instancemethod(fn: '_F') -> '_F'
| Decorate a method memoize its return value.
|
| :meta private:
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_attribute = <class 'sqlalchemy.util.langhelpers.HasMemoized.m...
| A read-only @property that is only evaluated once.
|
| :meta private:
|
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.visitors.HasTraverseInternals:
|
| get_children(self, *, omit_attrs: 'Tuple[str, ...]' = (), **kw: 'Any') -> 'Iterable[HasTraverseInternals]'
| Return immediate child :class:`.visitors.HasTraverseInternals`
| elements of this :class:`.visitors.HasTraverseInternals`.
|
| This is used for visit traversal.
|
| \**kw may contain flags that change the collection that is
| returned, for example to return a subset of items in order to
| cut down on larger traversals, or to return child items from a
| different context (such as schema-level collections instead of
| clause-level).
|
| ----------------------------------------------------------------------
| Methods inherited from CompilerElement:
|
| __str__(self) -> 'str'
| Return str(self).
|
| compile(self, bind: 'Optional[_HasDialect]' = None, dialect: 'Optional[Dialect]' = None, **kw: 'Any') -> 'Compiled'
| Compile this SQL expression.
|
| The return value is a :class:`~.Compiled` object.
| Calling ``str()`` or ``unicode()`` on the returned value will yield a
| string representation of the result. The
| :class:`~.Compiled` object also can return a
| dictionary of bind parameter names and values
| using the ``params`` accessor.
|
| :param bind: An :class:`.Connection` or :class:`.Engine` which
| can provide a :class:`.Dialect` in order to generate a
| :class:`.Compiled` object. If the ``bind`` and
| ``dialect`` parameters are both omitted, a default SQL compiler
| is used.
|
| :param column_keys: Used for INSERT and UPDATE statements, a list of
| column names which should be present in the VALUES clause of the
| compiled statement. If ``None``, all columns from the target table
| object are rendered.
|
| :param dialect: A :class:`.Dialect` instance which can generate
| a :class:`.Compiled` object. This argument takes precedence over
| the ``bind`` argument.
|
| :param compile_kwargs: optional dictionary of additional parameters
| that will be passed through to the compiler within all "visit"
| methods. This allows any custom flag to be passed through to
| a custom compilation construct, for example. It is also used
| for the case of passing the ``literal_binds`` flag through::
|
| from sqlalchemy.sql import table, column, select
|
| t = table("t", column("x"))
|
| s = select(t).where(t.c.x == 5)
|
| print(s.compile(compile_kwargs={"literal_binds": True}))
|
| .. seealso::
|
| :ref:`faq_sql_expression_string`
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from CompilerElement:
|
| stringify_dialect = 'default'
|
| supports_execution = False
sqlalchemy.BindParameter
Python Library Documentation: class BindParameter in module sqlalchemy.sql.elements
class BindParameter(sqlalchemy.sql.roles.InElementRole, KeyedColumnElement)
| BindParameter(key: 'Optional[str]', value: 'Any' = _NoArg.NO_ARG, type_: 'Optional[_TypeEngineArgument[_T]]' = None, unique: 'bool' = False, required: 'Union[bool, Literal[_NoArg.NO_ARG]]' = _NoArg.NO_ARG, quote: 'Optional[bool]' = None, callable_: 'Optional[Callable[[], Any]]' = None, expanding: 'bool' = False, isoutparam: 'bool' = False, literal_execute: 'bool' = False, _compared_to_operator: 'Optional[OperatorType]' = None, _compared_to_type: 'Optional[TypeEngine[Any]]' = None, _is_crud: 'bool' = False)
|
| Represent a "bound expression".
|
| :class:`.BindParameter` is invoked explicitly using the
| :func:`.bindparam` function, as in::
|
| from sqlalchemy import bindparam
|
| stmt = select(users_table).where(
| users_table.c.name == bindparam("username")
| )
|
| Detailed discussion of how :class:`.BindParameter` is used is
| at :func:`.bindparam`.
|
| .. seealso::
|
| :func:`.bindparam`
|
| Method resolution order:
| BindParameter
| sqlalchemy.sql.roles.InElementRole
| KeyedColumnElement
| ColumnElement
| sqlalchemy.sql.roles.ColumnArgumentOrKeyRole
| sqlalchemy.sql.roles.ColumnArgumentRole
| sqlalchemy.sql.roles.StatementOptionRole
| sqlalchemy.sql.roles.WhereHavingRole
| sqlalchemy.sql.roles.OnClauseRole
| sqlalchemy.sql.roles.BinaryElementRole
| sqlalchemy.sql.roles.OrderByRole
| sqlalchemy.sql.roles.ColumnsClauseRole
| sqlalchemy.sql.roles.AllowsLambdaRole
| sqlalchemy.sql.roles.ByOfRole
| sqlalchemy.sql.roles.UsesInspection
| sqlalchemy.sql.roles.ColumnListRole
| sqlalchemy.sql.roles.LimitOffsetRole
| sqlalchemy.sql.roles.DMLColumnRole
| sqlalchemy.sql.roles.DDLConstraintColumnRole
| sqlalchemy.sql.roles.DDLExpressionRole
| sqlalchemy.sql.roles.StructuralRole
| SQLColumnExpression
| SQLCoreOperations
| sqlalchemy.sql.roles.ExpressionElementRole
| sqlalchemy.sql.roles.TypedColumnsClauseRole
| typing.Generic
| sqlalchemy.sql.operators.ColumnOperators
| sqlalchemy.sql.operators.Operators
| sqlalchemy.util.langhelpers.TypingOnly
| sqlalchemy.sql.roles.SQLRole
| DQLDMLClauseElement
| ClauseElement
| sqlalchemy.sql.annotation.SupportsWrappingAnnotations
| sqlalchemy.sql.annotation.SupportsAnnotations
| sqlalchemy.sql.cache_key.MemoizedHasCacheKey
| sqlalchemy.sql.cache_key.HasCacheKey
| sqlalchemy.util.langhelpers.HasMemoized
| sqlalchemy.sql.traversals.HasCopyInternals
| sqlalchemy.sql.visitors.ExternallyTraversible
| sqlalchemy.sql.visitors.HasTraverseInternals
| CompilerElement
| sqlalchemy.sql.visitors.Visitable
| builtins.object
|
| Methods defined here:
|
| __getstate__(self)
| execute a deferred value for serialization purposes.
|
| __init__(self, key: 'Optional[str]', value: 'Any' = _NoArg.NO_ARG, type_: 'Optional[_TypeEngineArgument[_T]]' = None, unique: 'bool' = False, required: 'Union[bool, Literal[_NoArg.NO_ARG]]' = _NoArg.NO_ARG, quote: 'Optional[bool]' = None, callable_: 'Optional[Callable[[], Any]]' = None, expanding: 'bool' = False, isoutparam: 'bool' = False, literal_execute: 'bool' = False, _compared_to_operator: 'Optional[OperatorType]' = None, _compared_to_type: 'Optional[TypeEngine[Any]]' = None, _is_crud: 'bool' = False)
| Initialize self. See help(type(self)) for accurate signature.
|
| __repr__(self)
| Return repr(self).
|
| __setstate__(self, state)
|
| render_literal_execute(self) -> 'BindParameter[_T]'
| Produce a copy of this bound parameter that will enable the
| :paramref:`_sql.BindParameter.literal_execute` flag.
|
| The :paramref:`_sql.BindParameter.literal_execute` flag will
| have the effect of the parameter rendered in the compiled SQL
| string using ``[POSTCOMPILE]`` form, which is a special form that
| is converted to be a rendering of the literal value of the parameter
| at SQL execution time. The rationale is to support caching
| of SQL statement strings that can embed per-statement literal values,
| such as LIMIT and OFFSET parameters, in the final SQL string that
| is passed to the DBAPI. Dialects in particular may want to use
| this method within custom compilation schemes.
|
| .. versionadded:: 1.4.5
|
| .. seealso::
|
| :ref:`engine_thirdparty_caching`
|
| ----------------------------------------------------------------------
| Readonly properties defined here:
|
| effective_value
| Return the value of this bound parameter,
| taking into account if the ``callable`` parameter
| was set.
|
| The ``callable`` value will be evaluated
| and returned if present, else ``value``.
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'_traverse_internals': '_TraverseInternalsType', 'k...
|
| __orig_bases__ = (<class 'sqlalchemy.sql.roles.InElementRole'>, sqlalc...
|
| __parameters__ = (~_T,)
|
| __visit_name__ = 'bindparam'
|
| inherit_cache = True
|
| ----------------------------------------------------------------------
| Methods inherited from ColumnElement:
|
| __getattr__(self, key: 'str') -> 'Any'
|
| base_columns(...)
|
| cast(self, type_: '_TypeEngineArgument[_OPT]') -> 'Cast[_OPT]'
| Produce a type cast, i.e. ``CAST(<expression> AS <type>)``.
|
| This is a shortcut to the :func:`_expression.cast` function.
|
| .. seealso::
|
| :ref:`tutorial_casts`
|
| :func:`_expression.cast`
|
| :func:`_expression.type_coerce`
|
| comparator(...)
|
| label(self, name: 'Optional[str]') -> 'Label[_T]'
| Produce a column label, i.e. ``<columnname> AS <name>``.
|
| This is a shortcut to the :func:`_expression.label` function.
|
| If 'name' is ``None``, an anonymous label name will be generated.
|
| operate(self, op: 'operators.OperatorType', *other: 'Any', **kwargs: 'Any') -> 'ColumnElement[Any]'
| Operate on an argument.
|
| This is the lowest level of operation, raises
| :class:`NotImplementedError` by default.
|
| Overriding this on a subclass can allow common
| behavior to be applied to all operations.
| For example, overriding :class:`.ColumnOperators`
| to apply ``func.lower()`` to the left and right
| side::
|
| class MyComparator(ColumnOperators):
| def operate(self, op, other, **kwargs):
| return op(func.lower(self), func.lower(other), **kwargs)
|
| :param op: Operator callable.
| :param \*other: the 'other' side of the operation. Will
| be a single scalar for most operations.
| :param \**kwargs: modifiers. These may be passed by special
| operators such as :meth:`ColumnOperators.contains`.
|
| proxy_set(...)
| set of all columns we are proxying
|
| as of 2.0 this is explicitly deannotated columns. previously it was
| effectively deannotated columns but wasn't enforced. annotated
| columns should basically not go into sets if at all possible because
| their hashing behavior is very non-performant.
|
| reverse_operate(self, op: 'operators.OperatorType', other: 'Any', **kwargs: 'Any') -> 'ColumnElement[Any]'
| Reverse operate on an argument.
|
| Usage is the same as :meth:`operate`.
|
| self_group(self, against: 'Optional[OperatorType]' = None) -> 'ColumnElement[Any]'
| 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.
|
| shares_lineage(self, othercolumn: 'ColumnElement[Any]') -> 'bool'
| Return True if the given :class:`_expression.ColumnElement`
| has a common ancestor to this :class:`_expression.ColumnElement`.
|
| type(...)
|
| ----------------------------------------------------------------------
| Readonly properties inherited from ColumnElement:
|
| anon_key_label
| .. deprecated:: 1.4 The :attr:`_expression.ColumnElement.anon_key_label` attribute is now private, and the public accessor is deprecated.
|
| anon_label
| .. deprecated:: 1.4 The :attr:`_expression.ColumnElement.anon_label` attribute is now private, and the public accessor is deprecated.
|
| expression
| Return a column expression.
|
| Part of the inspection interface; returns self.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from ColumnElement:
|
| foreign_keys = frozenset()
|
| key = None
|
| primary_key = False
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.AllowsLambdaRole:
|
| allows_lambda = True
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.UsesInspection:
|
| uses_inspection = True
|
| ----------------------------------------------------------------------
| Class methods inherited from typing.Generic:
|
| __class_getitem__(...)
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__(...)
| Function to initialize subclasses.
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.operators.ColumnOperators:
|
| __add__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``+`` operator.
|
| In a column context, produces the clause ``a + b``
| if the parent object has non-string affinity.
| If the parent object has a string affinity,
| produces the concatenation operator, ``a || b`` -
| see :meth:`.ColumnOperators.concat`.
|
| __contains__(self, other: 'Any') -> 'ColumnOperators'
|
| __eq__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``==`` operator.
|
| In a column context, produces the clause ``a = b``.
| If the target is ``None``, produces ``a IS NULL``.
|
| __floordiv__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``//`` operator.
|
| In a column context, produces the clause ``a / b``,
| which is the same as "truediv", but considers the result
| type to be integer.
|
| .. versionadded:: 2.0
|
| __ge__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``>=`` operator.
|
| In a column context, produces the clause ``a >= b``.
|
| __getitem__(self, index: 'Any') -> 'ColumnOperators'
| Implement the [] operator.
|
| This can be used by some database-specific types
| such as PostgreSQL ARRAY and HSTORE.
|
| __gt__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``>`` operator.
|
| In a column context, produces the clause ``a > b``.
|
| __hash__(self, /) from builtins.object
| Return hash(self).
|
| __le__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``<=`` operator.
|
| In a column context, produces the clause ``a <= b``.
|
| __lshift__(self, other: 'Any') -> 'ColumnOperators'
| implement the << operator.
|
| Not used by SQLAlchemy core, this is provided
| for custom operator systems which want to use
| << as an extension point.
|
| __lt__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``<`` operator.
|
| In a column context, produces the clause ``a < b``.
|
| __mod__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``%`` operator.
|
| In a column context, produces the clause ``a % b``.
|
| __mul__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``*`` operator.
|
| In a column context, produces the clause ``a * b``.
|
| __ne__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``!=`` operator.
|
| In a column context, produces the clause ``a != b``.
| If the target is ``None``, produces ``a IS NOT NULL``.
|
| __neg__(self) -> 'ColumnOperators'
| Implement the ``-`` operator.
|
| In a column context, produces the clause ``-a``.
|
| __radd__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``+`` operator in reverse.
|
| See :meth:`.ColumnOperators.__add__`.
|
| __rfloordiv__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``//`` operator in reverse.
|
| See :meth:`.ColumnOperators.__floordiv__`.
|
| __rmod__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``%`` operator in reverse.
|
| See :meth:`.ColumnOperators.__mod__`.
|
| __rmul__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``*`` operator in reverse.
|
| See :meth:`.ColumnOperators.__mul__`.
|
| __rshift__(self, other: 'Any') -> 'ColumnOperators'
| implement the >> operator.
|
| Not used by SQLAlchemy core, this is provided
| for custom operator systems which want to use
| >> as an extension point.
|
| __rsub__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``-`` operator in reverse.
|
| See :meth:`.ColumnOperators.__sub__`.
|
| __rtruediv__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``/`` operator in reverse.
|
| See :meth:`.ColumnOperators.__truediv__`.
|
| __sub__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``-`` operator.
|
| In a column context, produces the clause ``a - b``.
|
| __truediv__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``/`` operator.
|
| In a column context, produces the clause ``a / b``, and
| considers the result type to be numeric.
|
| .. versionchanged:: 2.0 The truediv operator against two integers
| is now considered to return a numeric value. Behavior on specific
| backends may vary.
|
| all_(self) -> 'ColumnOperators'
| Produce an :func:`_expression.all_` clause against the
| parent object.
|
| See the documentation for :func:`_sql.all_` for examples.
|
| .. note:: be sure to not confuse the newer
| :meth:`_sql.ColumnOperators.all_` method with the **legacy**
| version of this method, the :meth:`_types.ARRAY.Comparator.all`
| method that's specific to :class:`_types.ARRAY`, which uses a
| different calling style.
|
| any_(self) -> 'ColumnOperators'
| Produce an :func:`_expression.any_` clause against the
| parent object.
|
| See the documentation for :func:`_sql.any_` for examples.
|
| .. note:: be sure to not confuse the newer
| :meth:`_sql.ColumnOperators.any_` method with the **legacy**
| version of this method, the :meth:`_types.ARRAY.Comparator.any`
| method that's specific to :class:`_types.ARRAY`, which uses a
| different calling style.
|
| asc(self) -> 'ColumnOperators'
| Produce a :func:`_expression.asc` clause against the
| parent object.
|
| between(self, cleft: 'Any', cright: 'Any', symmetric: 'bool' = False) -> 'ColumnOperators'
| Produce a :func:`_expression.between` clause against
| the parent object, given the lower and upper range.
|
| bitwise_and(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise AND operation, typically via the ``&``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_lshift(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise LSHIFT operation, typically via the ``<<``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_not(self) -> 'ColumnOperators'
| Produce a bitwise NOT operation, typically via the ``~``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_or(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise OR operation, typically via the ``|``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_rshift(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise RSHIFT operation, typically via the ``>>``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_xor(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise XOR operation, typically via the ``^``
| operator, or ``#`` for PostgreSQL.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| collate(self, collation: 'str') -> 'ColumnOperators'
| Produce a :func:`_expression.collate` clause against
| the parent object, given the collation string.
|
| .. seealso::
|
| :func:`_expression.collate`
|
| concat(self, other: 'Any') -> 'ColumnOperators'
| Implement the 'concat' operator.
|
| In a column context, produces the clause ``a || b``,
| or uses the ``concat()`` operator on MySQL.
|
| contains(self, other: 'Any', **kw: 'Any') -> 'ColumnOperators'
| Implement the 'contains' operator.
|
| Produces a LIKE expression that tests against a match for the middle
| of a string value:
|
| .. sourcecode:: sql
|
| column LIKE '%' || <other> || '%'
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.contains("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.contains.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.contains.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.contains.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.contains("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE '%' || :param || '%' ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.contains("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE '%' || :param || '%' ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.contains.autoescape`::
|
| somecolumn.contains("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.startswith`
|
| :meth:`.ColumnOperators.endswith`
|
| :meth:`.ColumnOperators.like`
|
| desc(self) -> 'ColumnOperators'
| Produce a :func:`_expression.desc` clause against the
| parent object.
|
| distinct(self) -> 'ColumnOperators'
| Produce a :func:`_expression.distinct` clause against the
| parent object.
|
| endswith(self, other: 'Any', escape: 'Optional[str]' = None, autoescape: 'bool' = False) -> 'ColumnOperators'
| Implement the 'endswith' operator.
|
| Produces a LIKE expression that tests against a match for the end
| of a string value:
|
| .. sourcecode:: sql
|
| column LIKE '%' || <other>
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.endswith("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.endswith.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.endswith.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.endswith.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.endswith("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE '%' || :param ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.endswith("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE '%' || :param ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.endswith.autoescape`::
|
| somecolumn.endswith("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.startswith`
|
| :meth:`.ColumnOperators.contains`
|
| :meth:`.ColumnOperators.like`
|
| icontains(self, other: 'Any', **kw: 'Any') -> 'ColumnOperators'
| Implement the ``icontains`` operator, e.g. case insensitive
| version of :meth:`.ColumnOperators.contains`.
|
| Produces a LIKE expression that tests against an insensitive match
| for the middle of a string value:
|
| .. sourcecode:: sql
|
| lower(column) LIKE '%' || lower(<other>) || '%'
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.icontains("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.icontains.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.icontains.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.icontains.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.icontains("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE '%' || lower(:param) || '%' ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.icontains("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE '%' || lower(:param) || '%' ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.contains.autoescape`::
|
| somecolumn.icontains("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.contains`
|
| iendswith(self, other: 'Any', escape: 'Optional[str]' = None, autoescape: 'bool' = False) -> 'ColumnOperators'
| Implement the ``iendswith`` operator, e.g. case insensitive
| version of :meth:`.ColumnOperators.endswith`.
|
| Produces a LIKE expression that tests against an insensitive match
| for the end of a string value:
|
| .. sourcecode:: sql
|
| lower(column) LIKE '%' || lower(<other>)
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.iendswith("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.iendswith.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.iendswith.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.iendswith.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.iendswith("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE '%' || lower(:param) ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.iendswith("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE '%' || lower(:param) ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.iendswith.autoescape`::
|
| somecolumn.endswith("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.endswith`
|
| ilike(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
| Implement the ``ilike`` operator, e.g. case insensitive LIKE.
|
| In a column context, produces an expression either of the form:
|
| .. sourcecode:: sql
|
| lower(a) LIKE lower(other)
|
| Or on backends that support the ILIKE operator:
|
| .. sourcecode:: sql
|
| a ILIKE other
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.ilike("%foobar%"))
|
| :param other: expression to be compared
| :param escape: optional escape character, renders the ``ESCAPE``
| keyword, e.g.::
|
| somecolumn.ilike("foo/%bar", escape="/")
|
| .. seealso::
|
| :meth:`.ColumnOperators.like`
|
| in_(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``in`` operator.
|
| In a column context, produces the clause ``column IN <other>``.
|
| The given parameter ``other`` may be:
|
| * A list of literal values,
| e.g.::
|
| stmt.where(column.in_([1, 2, 3]))
|
| In this calling form, the list of items is converted to a set of
| bound parameters the same length as the list given:
|
| .. sourcecode:: sql
|
| WHERE COL IN (?, ?, ?)
|
| * A list of tuples may be provided if the comparison is against a
| :func:`.tuple_` containing multiple expressions::
|
| from sqlalchemy import tuple_
|
| stmt.where(tuple_(col1, col2).in_([(1, 10), (2, 20), (3, 30)]))
|
| * An empty list,
| e.g.::
|
| stmt.where(column.in_([]))
|
| In this calling form, the expression renders an "empty set"
| expression. These expressions are tailored to individual backends
| and are generally trying to get an empty SELECT statement as a
| subquery. Such as on SQLite, the expression is:
|
| .. sourcecode:: sql
|
| WHERE col IN (SELECT 1 FROM (SELECT 1) WHERE 1!=1)
|
| .. versionchanged:: 1.4 empty IN expressions now use an
| execution-time generated SELECT subquery in all cases.
|
| * A bound parameter, e.g. :func:`.bindparam`, may be used if it
| includes the :paramref:`.bindparam.expanding` flag::
|
| stmt.where(column.in_(bindparam("value", expanding=True)))
|
| In this calling form, the expression renders a special non-SQL
| placeholder expression that looks like:
|
| .. sourcecode:: sql
|
| WHERE COL IN ([EXPANDING_value])
|
| This placeholder expression is intercepted at statement execution
| time to be converted into the variable number of bound parameter
| form illustrated earlier. If the statement were executed as::
|
| connection.execute(stmt, {"value": [1, 2, 3]})
|
| The database would be passed a bound parameter for each value:
|
| .. sourcecode:: sql
|
| WHERE COL IN (?, ?, ?)
|
| .. versionadded:: 1.2 added "expanding" bound parameters
|
| If an empty list is passed, a special "empty list" expression,
| which is specific to the database in use, is rendered. On
| SQLite this would be:
|
| .. sourcecode:: sql
|
| WHERE COL IN (SELECT 1 FROM (SELECT 1) WHERE 1!=1)
|
| .. versionadded:: 1.3 "expanding" bound parameters now support
| empty lists
|
| * a :func:`_expression.select` construct, which is usually a
| correlated scalar select::
|
| stmt.where(
| column.in_(select(othertable.c.y).where(table.c.x == othertable.c.x))
| )
|
| In this calling form, :meth:`.ColumnOperators.in_` renders as given:
|
| .. sourcecode:: sql
|
| WHERE COL IN (SELECT othertable.y
| FROM othertable WHERE othertable.x = table.x)
|
| :param other: a list of literals, a :func:`_expression.select`
| construct, or a :func:`.bindparam` construct that includes the
| :paramref:`.bindparam.expanding` flag set to True.
|
| is_(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``IS`` operator.
|
| Normally, ``IS`` is generated automatically when comparing to a
| value of ``None``, which resolves to ``NULL``. However, explicit
| usage of ``IS`` may be desirable if comparing to boolean values
| on certain platforms.
|
| .. seealso:: :meth:`.ColumnOperators.is_not`
|
| is_distinct_from(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``IS DISTINCT FROM`` operator.
|
| Renders "a IS DISTINCT FROM b" on most platforms;
| on some such as SQLite may render "a IS NOT b".
|
| is_not(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``IS NOT`` operator.
|
| Normally, ``IS NOT`` is generated automatically when comparing to a
| value of ``None``, which resolves to ``NULL``. However, explicit
| usage of ``IS NOT`` may be desirable if comparing to boolean values
| on certain platforms.
|
| .. versionchanged:: 1.4 The ``is_not()`` operator is renamed from
| ``isnot()`` in previous releases. The previous name remains
| available for backwards compatibility.
|
| .. seealso:: :meth:`.ColumnOperators.is_`
|
| is_not_distinct_from(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``IS NOT DISTINCT FROM`` operator.
|
| Renders "a IS NOT DISTINCT FROM b" on most platforms;
| on some such as SQLite may render "a IS b".
|
| .. versionchanged:: 1.4 The ``is_not_distinct_from()`` operator is
| renamed from ``isnot_distinct_from()`` in previous releases.
| The previous name remains available for backwards compatibility.
|
| isnot = is_not(self, other: 'Any') -> 'ColumnOperators'
|
| isnot_distinct_from = is_not_distinct_from(self, other: 'Any') -> 'ColumnOperators'
|
| istartswith(self, other: 'Any', escape: 'Optional[str]' = None, autoescape: 'bool' = False) -> 'ColumnOperators'
| Implement the ``istartswith`` operator, e.g. case insensitive
| version of :meth:`.ColumnOperators.startswith`.
|
| Produces a LIKE expression that tests against an insensitive
| match for the start of a string value:
|
| .. sourcecode:: sql
|
| lower(column) LIKE lower(<other>) || '%'
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.istartswith("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.istartswith.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.istartswith.escape` parameter will
| establish a given character as an escape character which can be of
| use when the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.istartswith.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.istartswith("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE lower(:param) || '%' ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.istartswith("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE lower(:param) || '%' ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.istartswith.autoescape`::
|
| somecolumn.istartswith("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.startswith`
|
| like(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
| Implement the ``like`` operator.
|
| In a column context, produces the expression:
|
| .. sourcecode:: sql
|
| a LIKE other
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.like("%foobar%"))
|
| :param other: expression to be compared
| :param escape: optional escape character, renders the ``ESCAPE``
| keyword, e.g.::
|
| somecolumn.like("foo/%bar", escape="/")
|
| .. seealso::
|
| :meth:`.ColumnOperators.ilike`
|
| match(self, other: 'Any', **kwargs: 'Any') -> 'ColumnOperators'
| Implements a database-specific 'match' operator.
|
| :meth:`_sql.ColumnOperators.match` attempts to resolve to
| a MATCH-like function or operator provided by the backend.
| Examples include:
|
| * PostgreSQL - renders ``x @@ plainto_tsquery(y)``
|
| .. versionchanged:: 2.0 ``plainto_tsquery()`` is used instead
| of ``to_tsquery()`` for PostgreSQL now; for compatibility with
| other forms, see :ref:`postgresql_match`.
|
|
| * MySQL - renders ``MATCH (x) AGAINST (y IN BOOLEAN MODE)``
|
| .. seealso::
|
| :class:`_mysql.match` - MySQL specific construct with
| additional features.
|
| * Oracle Database - renders ``CONTAINS(x, y)``
| * other backends may provide special implementations.
| * Backends without any special implementation will emit
| the operator as "MATCH". This is compatible with SQLite, for
| example.
|
| not_ilike(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
| implement the ``NOT ILIKE`` operator.
|
| This is equivalent to using negation with
| :meth:`.ColumnOperators.ilike`, i.e. ``~x.ilike(y)``.
|
| .. versionchanged:: 1.4 The ``not_ilike()`` operator is renamed from
| ``notilike()`` in previous releases. The previous name remains
| available for backwards compatibility.
|
| .. seealso::
|
| :meth:`.ColumnOperators.ilike`
|
| not_in(self, other: 'Any') -> 'ColumnOperators'
| implement the ``NOT IN`` operator.
|
| This is equivalent to using negation with
| :meth:`.ColumnOperators.in_`, i.e. ``~x.in_(y)``.
|
| In the case that ``other`` is an empty sequence, the compiler
| produces an "empty not in" expression. This defaults to the
| expression "1 = 1" to produce true in all cases. The
| :paramref:`_sa.create_engine.empty_in_strategy` may be used to
| alter this behavior.
|
| .. versionchanged:: 1.4 The ``not_in()`` operator is renamed from
| ``notin_()`` in previous releases. The previous name remains
| available for backwards compatibility.
|
| .. versionchanged:: 1.2 The :meth:`.ColumnOperators.in_` and
| :meth:`.ColumnOperators.not_in` operators
| now produce a "static" expression for an empty IN sequence
| by default.
|
| .. seealso::
|
| :meth:`.ColumnOperators.in_`
|
| not_like(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
| implement the ``NOT LIKE`` operator.
|
| This is equivalent to using negation with
| :meth:`.ColumnOperators.like`, i.e. ``~x.like(y)``.
|
| .. versionchanged:: 1.4 The ``not_like()`` operator is renamed from
| ``notlike()`` in previous releases. The previous name remains
| available for backwards compatibility.
|
| .. seealso::
|
| :meth:`.ColumnOperators.like`
|
| notilike = not_ilike(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
|
| notin_ = not_in(self, other: 'Any') -> 'ColumnOperators'
|
| notlike = not_like(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
|
| nulls_first(self) -> 'ColumnOperators'
| Produce a :func:`_expression.nulls_first` clause against the
| parent object.
|
| .. versionchanged:: 1.4 The ``nulls_first()`` operator is
| renamed from ``nullsfirst()`` in previous releases.
| The previous name remains available for backwards compatibility.
|
| nulls_last(self) -> 'ColumnOperators'
| Produce a :func:`_expression.nulls_last` clause against the
| parent object.
|
| .. versionchanged:: 1.4 The ``nulls_last()`` operator is
| renamed from ``nullslast()`` in previous releases.
| The previous name remains available for backwards compatibility.
|
| nullsfirst = nulls_first(self) -> 'ColumnOperators'
|
| nullslast = nulls_last(self) -> 'ColumnOperators'
|
| regexp_match(self, pattern: 'Any', flags: 'Optional[str]' = None) -> 'ColumnOperators'
| Implements a database-specific 'regexp match' operator.
|
| E.g.::
|
| stmt = select(table.c.some_column).where(
| table.c.some_column.regexp_match("^(b|c)")
| )
|
| :meth:`_sql.ColumnOperators.regexp_match` attempts to resolve to
| a REGEXP-like function or operator provided by the backend, however
| the specific regular expression syntax and flags available are
| **not backend agnostic**.
|
| Examples include:
|
| * PostgreSQL - renders ``x ~ y`` or ``x !~ y`` when negated.
| * Oracle Database - renders ``REGEXP_LIKE(x, y)``
| * SQLite - uses SQLite's ``REGEXP`` placeholder operator and calls into
| the Python ``re.match()`` builtin.
| * other backends may provide special implementations.
| * Backends without any special implementation will emit
| the operator as "REGEXP" or "NOT REGEXP". This is compatible with
| SQLite and MySQL, for example.
|
| Regular expression support is currently implemented for Oracle
| Database, PostgreSQL, MySQL and MariaDB. Partial support is available
| for SQLite. Support among third-party dialects may vary.
|
| :param pattern: The regular expression pattern string or column
| clause.
| :param flags: Any regular expression string flags to apply, passed as
| plain Python string only. These flags are backend specific.
| Some backends, like PostgreSQL and MariaDB, may alternatively
| specify the flags as part of the pattern.
| When using the ignore case flag 'i' in PostgreSQL, the ignore case
| regexp match operator ``~*`` or ``!~*`` will be used.
|
| .. versionadded:: 1.4
|
| .. versionchanged:: 1.4.48, 2.0.18 Note that due to an implementation
| error, the "flags" parameter previously accepted SQL expression
| objects such as column expressions in addition to plain Python
| strings. This implementation did not work correctly with caching
| and was removed; strings only should be passed for the "flags"
| parameter, as these flags are rendered as literal inline values
| within SQL expressions.
|
| .. seealso::
|
| :meth:`_sql.ColumnOperators.regexp_replace`
|
| regexp_replace(self, pattern: 'Any', replacement: 'Any', flags: 'Optional[str]' = None) -> 'ColumnOperators'
| Implements a database-specific 'regexp replace' operator.
|
| E.g.::
|
| stmt = select(
| table.c.some_column.regexp_replace("b(..)", "XY", flags="g")
| )
|
| :meth:`_sql.ColumnOperators.regexp_replace` attempts to resolve to
| a REGEXP_REPLACE-like function provided by the backend, that
| usually emit the function ``REGEXP_REPLACE()``. However,
| the specific regular expression syntax and flags available are
| **not backend agnostic**.
|
| Regular expression replacement support is currently implemented for
| Oracle Database, PostgreSQL, MySQL 8 or greater and MariaDB. Support
| among third-party dialects may vary.
|
| :param pattern: The regular expression pattern string or column
| clause.
| :param pattern: The replacement string or column clause.
| :param flags: Any regular expression string flags to apply, passed as
| plain Python string only. These flags are backend specific.
| Some backends, like PostgreSQL and MariaDB, may alternatively
| specify the flags as part of the pattern.
|
| .. versionadded:: 1.4
|
| .. versionchanged:: 1.4.48, 2.0.18 Note that due to an implementation
| error, the "flags" parameter previously accepted SQL expression
| objects such as column expressions in addition to plain Python
| strings. This implementation did not work correctly with caching
| and was removed; strings only should be passed for the "flags"
| parameter, as these flags are rendered as literal inline values
| within SQL expressions.
|
|
| .. seealso::
|
| :meth:`_sql.ColumnOperators.regexp_match`
|
| startswith(self, other: 'Any', escape: 'Optional[str]' = None, autoescape: 'bool' = False) -> 'ColumnOperators'
| Implement the ``startswith`` operator.
|
| Produces a LIKE expression that tests against a match for the start
| of a string value:
|
| .. sourcecode:: sql
|
| column LIKE <other> || '%'
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.startswith("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.startswith.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.startswith.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.startswith.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.startswith("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE :param || '%' ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.startswith("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE :param || '%' ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.startswith.autoescape`::
|
| somecolumn.startswith("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.endswith`
|
| :meth:`.ColumnOperators.contains`
|
| :meth:`.ColumnOperators.like`
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.operators.ColumnOperators:
|
| timetuple = None
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.operators.Operators:
|
| __and__(self, other: 'Any') -> 'Operators'
| Implement the ``&`` operator.
|
| When used with SQL expressions, results in an
| AND operation, equivalent to
| :func:`_expression.and_`, that is::
|
| a & b
|
| is equivalent to::
|
| from sqlalchemy import and_
|
| and_(a, b)
|
| Care should be taken when using ``&`` regarding
| operator precedence; the ``&`` operator has the highest precedence.
| The operands should be enclosed in parenthesis if they contain
| further sub expressions::
|
| (a == 2) & (b == 4)
|
| __invert__(self) -> 'Operators'
| Implement the ``~`` operator.
|
| When used with SQL expressions, results in a
| NOT operation, equivalent to
| :func:`_expression.not_`, that is::
|
| ~a
|
| is equivalent to::
|
| from sqlalchemy import not_
|
| not_(a)
|
| __or__(self, other: 'Any') -> 'Operators'
| Implement the ``|`` operator.
|
| When used with SQL expressions, results in an
| OR operation, equivalent to
| :func:`_expression.or_`, that is::
|
| a | b
|
| is equivalent to::
|
| from sqlalchemy import or_
|
| or_(a, b)
|
| Care should be taken when using ``|`` regarding
| operator precedence; the ``|`` operator has the highest precedence.
| The operands should be enclosed in parenthesis if they contain
| further sub expressions::
|
| (a == 2) | (b == 4)
|
| __sa_operate__ = operate(self, op: 'OperatorType', *other: 'Any', **kwargs: 'Any') -> 'Operators'
| Operate on an argument.
|
| This is the lowest level of operation, raises
| :class:`NotImplementedError` by default.
|
| Overriding this on a subclass can allow common
| behavior to be applied to all operations.
| For example, overriding :class:`.ColumnOperators`
| to apply ``func.lower()`` to the left and right
| side::
|
| class MyComparator(ColumnOperators):
| def operate(self, op, other, **kwargs):
| return op(func.lower(self), func.lower(other), **kwargs)
|
| :param op: Operator callable.
| :param \*other: the 'other' side of the operation. Will
| be a single scalar for most operations.
| :param \**kwargs: modifiers. These may be passed by special
| operators such as :meth:`ColumnOperators.contains`.
|
| bool_op(self, opstring: 'str', precedence: 'int' = 0, python_impl: 'Optional[Callable[..., Any]]' = None) -> 'Callable[[Any], Operators]'
| Return a custom boolean operator.
|
| This method is shorthand for calling
| :meth:`.Operators.op` and passing the
| :paramref:`.Operators.op.is_comparison`
| flag with True. A key advantage to using :meth:`.Operators.bool_op`
| is that when using column constructs, the "boolean" nature of the
| returned expression will be present for :pep:`484` purposes.
|
| .. seealso::
|
| :meth:`.Operators.op`
|
| op(self, opstring: 'str', precedence: 'int' = 0, is_comparison: 'bool' = False, return_type: 'Optional[Union[Type[TypeEngine[Any]], TypeEngine[Any]]]' = None, python_impl: 'Optional[Callable[..., Any]]' = None) -> 'Callable[[Any], Operators]'
| Produce a generic operator function.
|
| e.g.::
|
| somecolumn.op("*")(5)
|
| produces::
|
| somecolumn * 5
|
| This function can also be used to make bitwise operators explicit. For
| example::
|
| somecolumn.op("&")(0xFF)
|
| is a bitwise AND of the value in ``somecolumn``.
|
| :param opstring: a string which will be output as the infix operator
| between this element and the expression passed to the
| generated function.
|
| :param precedence: precedence which the database is expected to apply
| to the operator in SQL expressions. This integer value acts as a hint
| for the SQL compiler to know when explicit parenthesis should be
| rendered around a particular operation. A lower number will cause the
| expression to be parenthesized when applied against another operator
| with higher precedence. The default value of ``0`` is lower than all
| operators except for the comma (``,``) and ``AS`` operators. A value
| of 100 will be higher or equal to all operators, and -100 will be
| lower than or equal to all operators.
|
| .. seealso::
|
| :ref:`faq_sql_expression_op_parenthesis` - detailed description
| of how the SQLAlchemy SQL compiler renders parenthesis
|
| :param is_comparison: legacy; if True, the operator will be considered
| as a "comparison" operator, that is which evaluates to a boolean
| true/false value, like ``==``, ``>``, etc. This flag is provided
| so that ORM relationships can establish that the operator is a
| comparison operator when used in a custom join condition.
|
| Using the ``is_comparison`` parameter is superseded by using the
| :meth:`.Operators.bool_op` method instead; this more succinct
| operator sets this parameter automatically, but also provides
| correct :pep:`484` typing support as the returned object will
| express a "boolean" datatype, i.e. ``BinaryExpression[bool]``.
|
| :param return_type: a :class:`.TypeEngine` class or object that will
| force the return type of an expression produced by this operator
| to be of that type. By default, operators that specify
| :paramref:`.Operators.op.is_comparison` will resolve to
| :class:`.Boolean`, and those that do not will be of the same
| type as the left-hand operand.
|
| :param python_impl: an optional Python function that can evaluate
| two Python values in the same way as this operator works when
| run on the database server. Useful for in-Python SQL expression
| evaluation functions, such as for ORM hybrid attributes, and the
| ORM "evaluator" used to match objects in a session after a multi-row
| update or delete.
|
| e.g.::
|
| >>> expr = column("x").op("+", python_impl=lambda a, b: a + b)("y")
|
| The operator for the above expression will also work for non-SQL
| left and right objects::
|
| >>> expr.operator(5, 10)
| 15
|
| .. versionadded:: 2.0
|
|
| .. seealso::
|
| :meth:`.Operators.bool_op`
|
| :ref:`types_operators`
|
| :ref:`relationship_custom_operator`
|
| ----------------------------------------------------------------------
| Methods inherited from ClauseElement:
|
| __bool__(self)
|
| compare(self, other: 'ClauseElement', **kw: 'Any') -> 'bool'
| Compare this :class:`_expression.ClauseElement` to
| the given :class:`_expression.ClauseElement`.
|
| Subclasses should override the default behavior, which is a
| straight identity comparison.
|
| \**kw are arguments consumed by subclass ``compare()`` methods and
| may be used to modify the criteria for comparison
| (see :class:`_expression.ColumnElement`).
|
| description(...)
|
| entity_namespace(...)
|
| params(self, _ClauseElement__optionaldict: 'Optional[Mapping[str, Any]]' = None, **kwargs: 'Any') -> 'Self'
| Return a copy with :func:`_expression.bindparam` elements
| replaced.
|
| Returns a copy of this ClauseElement with
| :func:`_expression.bindparam`
| elements replaced with values taken from the given dictionary::
|
| >>> clause = column("x") + bindparam("foo")
| >>> print(clause.compile().params)
| {'foo':None}
| >>> print(clause.params({"foo": 7}).compile().params)
| {'foo':7}
|
| unique_params(self, _ClauseElement__optionaldict: 'Optional[Dict[str, Any]]' = None, **kwargs: 'Any') -> 'Self'
| Return a copy with :func:`_expression.bindparam` elements
| replaced.
|
| Same functionality as :meth:`_expression.ClauseElement.params`,
| except adds `unique=True`
| to affected bind parameters so that multiple statements can be
| used.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from ClauseElement:
|
| is_clause_element = True
|
| is_dml = False
|
| is_selectable = False
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_instancemethod(fn: '_F') -> '_F'
| Decorate a method memoize its return value.
|
| :meta private:
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_attribute = <class 'sqlalchemy.util.langhelpers.HasMemoized.m...
| A read-only @property that is only evaluated once.
|
| :meta private:
|
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.visitors.HasTraverseInternals:
|
| get_children(self, *, omit_attrs: 'Tuple[str, ...]' = (), **kw: 'Any') -> 'Iterable[HasTraverseInternals]'
| Return immediate child :class:`.visitors.HasTraverseInternals`
| elements of this :class:`.visitors.HasTraverseInternals`.
|
| This is used for visit traversal.
|
| \**kw may contain flags that change the collection that is
| returned, for example to return a subset of items in order to
| cut down on larger traversals, or to return child items from a
| different context (such as schema-level collections instead of
| clause-level).
|
| ----------------------------------------------------------------------
| Methods inherited from CompilerElement:
|
| __str__(self) -> 'str'
| Return str(self).
|
| compile(self, bind: 'Optional[_HasDialect]' = None, dialect: 'Optional[Dialect]' = None, **kw: 'Any') -> 'Compiled'
| Compile this SQL expression.
|
| The return value is a :class:`~.Compiled` object.
| Calling ``str()`` or ``unicode()`` on the returned value will yield a
| string representation of the result. The
| :class:`~.Compiled` object also can return a
| dictionary of bind parameter names and values
| using the ``params`` accessor.
|
| :param bind: An :class:`.Connection` or :class:`.Engine` which
| can provide a :class:`.Dialect` in order to generate a
| :class:`.Compiled` object. If the ``bind`` and
| ``dialect`` parameters are both omitted, a default SQL compiler
| is used.
|
| :param column_keys: Used for INSERT and UPDATE statements, a list of
| column names which should be present in the VALUES clause of the
| compiled statement. If ``None``, all columns from the target table
| object are rendered.
|
| :param dialect: A :class:`.Dialect` instance which can generate
| a :class:`.Compiled` object. This argument takes precedence over
| the ``bind`` argument.
|
| :param compile_kwargs: optional dictionary of additional parameters
| that will be passed through to the compiler within all "visit"
| methods. This allows any custom flag to be passed through to
| a custom compilation construct, for example. It is also used
| for the case of passing the ``literal_binds`` flag through::
|
| from sqlalchemy.sql import table, column, select
|
| t = table("t", column("x"))
|
| s = select(t).where(t.c.x == 5)
|
| print(s.compile(compile_kwargs={"literal_binds": True}))
|
| .. seealso::
|
| :ref:`faq_sql_expression_string`
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from CompilerElement:
|
| stringify_dialect = 'default'
|
| supports_execution = False
sqlalchemy.BindTyping
Python Library Documentation: class BindTyping in module sqlalchemy.engine.interfaces class BindTyping(enum.Enum) | BindTyping(*values) | | Define different methods of passing typing information for | bound parameters in a statement to the database driver. | | .. versionadded:: 2.0 | | Method resolution order: | BindTyping | enum.Enum | builtins.object | | Data and other attributes defined here: | | NONE = <BindTyping.NONE: 1> | | RENDER_CASTS = <BindTyping.RENDER_CASTS: 3> | | SETINPUTSIZES = <BindTyping.SETINPUTSIZES: 2> | | ---------------------------------------------------------------------- | Data descriptors inherited from enum.Enum: | | name | The name of the Enum member. | | value | The value of the Enum member. | | ---------------------------------------------------------------------- | Static methods inherited from enum.EnumType: | | __contains__(value) | Return True if `value` is in `cls`. | | `value` is in `cls` if: | 1) `value` is a member of `cls`, or | 2) `value` is the value of one of the `cls`'s members. | | __getitem__(name) | Return the member matching `name`. | | __iter__() | Return members in definition order. | | __len__() | Return the number of members (no aliases) | | ---------------------------------------------------------------------- | Readonly properties inherited from enum.EnumType: | | __members__ | Returns a mapping of member name->value. | | This mapping lists all enum members, including aliases. Note that this | is a read-only view of the internal mapping.
sqlalchemy.Boolean
Python Library Documentation: class Boolean in module sqlalchemy.sql.sqltypes
class Boolean(SchemaType, sqlalchemy.sql.type_api.Emulated, sqlalchemy.sql.type_api.TypeEngine)
| Boolean(create_constraint: 'bool' = False, name: 'Optional[str]' = None, _create_events: 'bool' = True, _adapted_from: 'Optional[SchemaType]' = None)
|
| A bool datatype.
|
| :class:`.Boolean` typically uses BOOLEAN or SMALLINT on the DDL side,
| and on the Python side deals in ``True`` or ``False``.
|
| The :class:`.Boolean` datatype currently has two levels of assertion
| that the values persisted are simple true/false values. For all
| backends, only the Python values ``None``, ``True``, ``False``, ``1``
| or ``0`` are accepted as parameter values. For those backends that
| don't support a "native boolean" datatype, an option exists to
| also create a CHECK constraint on the target column
|
| .. versionchanged:: 1.2 the :class:`.Boolean` datatype now asserts that
| incoming Python values are already in pure boolean form.
|
| Method resolution order:
| Boolean
| SchemaType
| sqlalchemy.sql.base.SchemaEventTarget
| sqlalchemy.event.registry.EventTarget
| sqlalchemy.sql.type_api.Emulated
| sqlalchemy.sql.type_api.TypeEngineMixin
| sqlalchemy.sql.type_api.TypeEngine
| sqlalchemy.sql.visitors.Visitable
| typing.Generic
| builtins.object
|
| Methods defined here:
|
| __init__(self, create_constraint: 'bool' = False, name: 'Optional[str]' = None, _create_events: 'bool' = True, _adapted_from: 'Optional[SchemaType]' = None)
| Construct a Boolean.
|
| :param create_constraint: defaults to False. If the boolean
| is generated as an int/smallint, also create a CHECK constraint
| on the table that ensures 1 or 0 as a value.
|
| .. note:: it is strongly recommended that the CHECK constraint
| have an explicit name in order to support schema-management
| concerns. This can be established either by setting the
| :paramref:`.Boolean.name` parameter or by setting up an
| appropriate naming convention; see
| :ref:`constraint_naming_conventions` for background.
|
| .. versionchanged:: 1.4 - this flag now defaults to False, meaning
| no CHECK constraint is generated for a non-native enumerated
| type.
|
| :param name: if a CHECK constraint is generated, specify
| the name of the constraint.
|
| bind_processor(self, dialect)
| Return a conversion function for processing bind values.
|
| Returns a callable which will receive a bind parameter value
| as the sole positional argument and will return a value to
| send to the DB-API.
|
| If processing is not necessary, the method should return ``None``.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.bind_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.bind_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_bind_param`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
|
| :param dialect: Dialect instance in use.
|
| copy(self, **kw)
|
| literal_processor(self, dialect)
| Return a conversion function for processing literal values that are
| to be rendered directly without using binds.
|
| This function is used when the compiler makes use of the
| "literal_binds" flag, typically used in DDL generation as well
| as in certain scenarios where backends don't accept bound parameters.
|
| Returns a callable which will receive a literal Python value
| as the sole positional argument and will return a string representation
| to be rendered in a SQL statement.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.literal_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.literal_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_literal_param`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| result_processor(self, dialect, coltype)
| Return a conversion function for processing result row values.
|
| Returns a callable which will receive a result row column
| value as the sole positional argument and will return a value
| to return to the user.
|
| If processing is not necessary, the method should return ``None``.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.result_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.result_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_result_value`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| :param dialect: Dialect instance in use.
|
| :param coltype: DBAPI coltype argument received in cursor.description.
|
| ----------------------------------------------------------------------
| Readonly properties defined here:
|
| python_type
| Return the Python type object expected to be returned
| by instances of this type, if known.
|
| Basically, for those types which enforce a return type,
| or are known across the board to do such for all common
| DBAPIs (like ``int`` for example), will return that type.
|
| If a return type is not defined, raises
| ``NotImplementedError``.
|
| Note that any type also accommodates NULL in SQL which
| means you can also get back ``None`` from any type
| in practice.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| __parameters__ = ()
|
| __visit_name__ = 'boolean'
|
| native = True
|
| ----------------------------------------------------------------------
| Methods inherited from SchemaType:
|
| adapt(self, cls: 'Type[Union[TypeEngine[Any], TypeEngineMixin]]', **kw: 'Any') -> 'TypeEngine[Any]'
|
| create(self, bind: '_CreateDropBind', checkfirst: 'bool' = False) -> 'None'
| Issue CREATE DDL for this type, if applicable.
|
| drop(self, bind: '_CreateDropBind', checkfirst: 'bool' = False) -> 'None'
| Issue DROP DDL for this type, if applicable.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from sqlalchemy.sql.base.SchemaEventTarget:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.base.SchemaEventTarget:
|
| dispatch = <sqlalchemy.event.base.DDLEventsDispatch object>
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.type_api.Emulated:
|
| adapt_to_emulated(self, impltype: 'Type[Union[TypeEngine[Any], TypeEngineMixin]]', **kw: 'Any') -> 'TypeEngine[Any]'
| Given an impl class, adapt this type to the impl assuming
| "emulated".
|
| The impl should also be an "emulated" version of this type,
| most likely the same class as this type itself.
|
| e.g.: sqltypes.Enum adapts to the Enum class.
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.type_api.TypeEngine:
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| __str__(self) -> 'str'
| Return str(self).
|
| as_generic(self, allow_nulltype: 'bool' = False) -> 'TypeEngine[_T]'
| Return an instance of the generic type corresponding to this type
| using heuristic rule. The method may be overridden if this
| heuristic rule is not sufficient.
|
| >>> from sqlalchemy.dialects.mysql import INTEGER
| >>> INTEGER(display_width=4).as_generic()
| Integer()
|
| >>> from sqlalchemy.dialects.mysql import NVARCHAR
| >>> NVARCHAR(length=100).as_generic()
| Unicode(length=100)
|
| .. versionadded:: 1.4.0b2
|
|
| .. seealso::
|
| :ref:`metadata_reflection_dbagnostic_types` - describes the
| use of :meth:`_types.TypeEngine.as_generic` in conjunction with
| the :meth:`_sql.DDLEvents.column_reflect` event, which is its
| intended use.
|
| bind_expression(self, bindvalue: 'BindParameter[_T]') -> 'Optional[ColumnElement[_T]]'
| Given a bind value (i.e. a :class:`.BindParameter` instance),
| return a SQL expression in its place.
|
| This is typically a SQL function that wraps the existing bound
| parameter within the statement. It is used for special data types
| that require literals being wrapped in some special database function
| in order to coerce an application-level value into a database-specific
| format. It is the SQL analogue of the
| :meth:`.TypeEngine.bind_processor` method.
|
| This method is called during the **SQL compilation** phase of a
| statement, when rendering a SQL string. It is **not** called
| against specific values.
|
| Note that this method, when implemented, should always return
| the exact same structure, without any conditional logic, as it
| may be used in an executemany() call against an arbitrary number
| of bound parameter sets.
|
| .. note::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.bind_expression`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.bind_expression`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.bind_expression`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| .. seealso::
|
| :ref:`types_sql_value_processing`
|
| coerce_compared_value(self, op: 'Optional[OperatorType]', value: 'Any') -> 'TypeEngine[Any]'
| Suggest a type for a 'coerced' Python value in an expression.
|
| Given an operator and value, gives the type a chance
| to return a type which the value should be coerced into.
|
| The default behavior here is conservative; if the right-hand
| side is already coerced into a SQL type based on its
| Python type, it is usually left alone.
|
| End-user functionality extension here should generally be via
| :class:`.TypeDecorator`, which provides more liberal behavior in that
| it defaults to coercing the other side of the expression into this
| type, thus applying special Python conversions above and beyond those
| needed by the DBAPI to both ides. It also provides the public method
| :meth:`.TypeDecorator.coerce_compared_value` which is intended for
| end-user customization of this behavior.
|
| column_expression(self, colexpr: 'ColumnElement[_T]') -> 'Optional[ColumnElement[_T]]'
| Given a SELECT column expression, return a wrapping SQL expression.
|
| This is typically a SQL function that wraps a column expression
| as rendered in the columns clause of a SELECT statement.
| It is used for special data types that require
| columns to be wrapped in some special database function in order
| to coerce the value before being sent back to the application.
| It is the SQL analogue of the :meth:`.TypeEngine.result_processor`
| method.
|
| .. note:: The :func:`.TypeEngine.column_expression` method is applied
| only to the **outermost columns clause** of a SELECT statement, that
| is, the columns that are to be delivered directly into the returned
| result rows. It does **not** apply to the columns clause inside
| of subqueries. This necessarily avoids double conversions against
| the column and only runs the conversion when ready to be returned
| to the client.
|
| This method is called during the **SQL compilation** phase of a
| statement, when rendering a SQL string. It is **not** called
| against specific values.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.column_expression`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.column_expression`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.column_expression`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
|
| .. seealso::
|
| :ref:`types_sql_value_processing`
|
| compare_values(self, x: 'Any', y: 'Any') -> 'bool'
| Compare two values for equality.
|
| compile(self, dialect: 'Optional[Dialect]' = None) -> 'str'
| Produce a string-compiled form of this :class:`.TypeEngine`.
|
| When called with no arguments, uses a "default" dialect
| to produce a string result.
|
| :param dialect: a :class:`.Dialect` instance.
|
| copy_value(self, value: 'Any') -> 'Any'
|
| dialect_impl(self, dialect: 'Dialect') -> 'TypeEngine[_T]'
| Return a dialect-specific implementation for this
| :class:`.TypeEngine`.
|
| evaluates_none(self) -> 'Self'
| Return a copy of this type which has the
| :attr:`.should_evaluate_none` flag set to True.
|
| E.g.::
|
| Table(
| "some_table",
| metadata,
| Column(
| String(50).evaluates_none(),
| nullable=True,
| server_default="no value",
| ),
| )
|
| The ORM uses this flag to indicate that a positive value of ``None``
| is passed to the column in an INSERT statement, rather than omitting
| the column from the INSERT statement which has the effect of firing
| off column-level defaults. It also allows for types which have
| special behavior associated with the Python None value to indicate
| that the value doesn't necessarily translate into SQL NULL; a
| prime example of this is a JSON type which may wish to persist the
| JSON value ``'null'``.
|
| In all cases, the actual NULL SQL value can be always be
| persisted in any column by using
| the :obj:`_expression.null` SQL construct in an INSERT statement
| or associated with an ORM-mapped attribute.
|
| .. note::
|
| The "evaluates none" flag does **not** apply to a value
| of ``None`` passed to :paramref:`_schema.Column.default` or
| :paramref:`_schema.Column.server_default`; in these cases,
| ``None``
| still means "no default".
|
| .. seealso::
|
| :ref:`session_forcing_null` - in the ORM documentation
|
| :paramref:`.postgresql.JSON.none_as_null` - PostgreSQL JSON
| interaction with this flag.
|
| :attr:`.TypeEngine.should_evaluate_none` - class-level flag
|
| get_dbapi_type(self, dbapi: 'DBAPIModule') -> 'Optional[Any]'
| Return the corresponding type object from the underlying DB-API, if
| any.
|
| This can be useful for calling ``setinputsizes()``, for example.
|
| with_variant(self, type_: '_TypeEngineArgument[Any]', *dialect_names: 'str') -> 'Self'
| Produce a copy of this type object that will utilize the given
| type when applied to the dialect of the given name.
|
| e.g.::
|
| from sqlalchemy.types import String
| from sqlalchemy.dialects import mysql
|
| string_type = String()
|
| string_type = string_type.with_variant(
| mysql.VARCHAR(collation="foo"), "mysql", "mariadb"
| )
|
| The variant mapping indicates that when this type is
| interpreted by a specific dialect, it will instead be
| transmuted into the given type, rather than using the
| primary type.
|
| .. versionchanged:: 2.0 the :meth:`_types.TypeEngine.with_variant`
| method now works with a :class:`_types.TypeEngine` object "in
| place", returning a copy of the original type rather than returning
| a wrapping object; the ``Variant`` class is no longer used.
|
| :param type\_: a :class:`.TypeEngine` that will be selected
| as a variant from the originating type, when a dialect
| of the given name is in use.
| :param \*dialect_names: one or more base names of the dialect which
| uses this type. (i.e. ``'postgresql'``, ``'mysql'``, etc.)
|
| .. versionchanged:: 2.0 multiple dialect names can be specified
| for one variant.
|
| .. seealso::
|
| :ref:`types_with_variant` - illustrates the use of
| :meth:`_types.TypeEngine.with_variant`.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.type_api.TypeEngine:
|
| Comparator = <class 'sqlalchemy.sql.type_api.TypeEngine.Comparator'>
| Base class for custom comparison operations defined at the
| type level. See :attr:`.TypeEngine.comparator_factory`.
|
|
| __orig_bases__ = (<class 'sqlalchemy.sql.visitors.Visitable'>, typing....
|
| comparator_factory = <class 'sqlalchemy.sql.type_api.TypeEngine.Compar...
| Base class for custom comparison operations defined at the
| type level. See :attr:`.TypeEngine.comparator_factory`.
|
|
| hashable = True
|
| render_bind_cast = False
|
| render_literal_cast = False
|
| should_evaluate_none = False
|
| sort_key_function = None
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.visitors.Visitable:
|
| __class_getitem__(key: 'Any') -> 'Any'
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__() -> 'None'
| This method is called when a class is subclassed.
|
| The default implementation does nothing. It may be
| overridden to extend subclasses.
sqlalchemy.BooleanClauseList
Python Library Documentation: class BooleanClauseList in module sqlalchemy.sql.elements
class BooleanClauseList(ExpressionClauseList)
| BooleanClauseList(*arg, **kw)
|
| Method resolution order:
| BooleanClauseList
| ExpressionClauseList
| OperatorExpression
| ColumnElement
| sqlalchemy.sql.roles.ColumnArgumentOrKeyRole
| sqlalchemy.sql.roles.ColumnArgumentRole
| sqlalchemy.sql.roles.StatementOptionRole
| sqlalchemy.sql.roles.WhereHavingRole
| sqlalchemy.sql.roles.OnClauseRole
| sqlalchemy.sql.roles.BinaryElementRole
| sqlalchemy.sql.roles.OrderByRole
| sqlalchemy.sql.roles.ColumnsClauseRole
| sqlalchemy.sql.roles.AllowsLambdaRole
| sqlalchemy.sql.roles.ByOfRole
| sqlalchemy.sql.roles.UsesInspection
| sqlalchemy.sql.roles.ColumnListRole
| sqlalchemy.sql.roles.LimitOffsetRole
| sqlalchemy.sql.roles.DMLColumnRole
| sqlalchemy.sql.roles.DDLConstraintColumnRole
| sqlalchemy.sql.roles.DDLExpressionRole
| sqlalchemy.sql.roles.StructuralRole
| SQLColumnExpression
| SQLCoreOperations
| sqlalchemy.sql.roles.ExpressionElementRole
| sqlalchemy.sql.roles.TypedColumnsClauseRole
| typing.Generic
| sqlalchemy.sql.operators.ColumnOperators
| sqlalchemy.sql.operators.Operators
| sqlalchemy.util.langhelpers.TypingOnly
| sqlalchemy.sql.roles.SQLRole
| DQLDMLClauseElement
| ClauseElement
| sqlalchemy.sql.annotation.SupportsWrappingAnnotations
| sqlalchemy.sql.annotation.SupportsAnnotations
| sqlalchemy.sql.cache_key.MemoizedHasCacheKey
| sqlalchemy.sql.cache_key.HasCacheKey
| sqlalchemy.util.langhelpers.HasMemoized
| sqlalchemy.sql.traversals.HasCopyInternals
| sqlalchemy.sql.visitors.ExternallyTraversible
| sqlalchemy.sql.visitors.HasTraverseInternals
| CompilerElement
| sqlalchemy.sql.visitors.Visitable
| builtins.object
|
| Methods defined here:
|
| __init__(self, *arg, **kw)
| Initialize self. See help(type(self)) for accurate signature.
|
| self_group(self, against: 'Optional[OperatorType]' = None) -> 'Union[Self, Grouping[bool]]'
| 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.
|
| ----------------------------------------------------------------------
| Class methods defined here:
|
| and_(initial_clause: 'Union[Literal[True], _ColumnExpressionArgument[bool], _NoArg]' = _NoArg.NO_ARG, *clauses: '_ColumnExpressionArgument[bool]') -> 'ColumnElement[bool]'
| Produce a conjunction of expressions joined by ``AND``.
|
| See :func:`_sql.and_` for full documentation.
|
| or_(initial_clause: 'Union[Literal[False], _ColumnExpressionArgument[bool], _NoArg]' = _NoArg.NO_ARG, *clauses: '_ColumnExpressionArgument[bool]') -> 'ColumnElement[bool]'
| Produce a conjunction of expressions joined by ``OR``.
|
| See :func:`_sql.or_` for full documentation.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| __orig_bases__ = (sqlalchemy.sql.elements.ExpressionClauseList[bool],)
|
| __parameters__ = ()
|
| __visit_name__ = 'expression_clauselist'
|
| inherit_cache = True
|
| ----------------------------------------------------------------------
| Methods inherited from ExpressionClauseList:
|
| __iter__(self) -> 'Iterator[ColumnElement[Any]]'
|
| __len__(self) -> 'int'
|
| ----------------------------------------------------------------------
| Readonly properties inherited from OperatorExpression:
|
| is_comparison
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from OperatorExpression:
|
| group = True
|
| ----------------------------------------------------------------------
| Methods inherited from ColumnElement:
|
| __getattr__(self, key: 'str') -> 'Any'
|
| __setstate__(self, state)
|
| base_columns(...)
|
| cast(self, type_: '_TypeEngineArgument[_OPT]') -> 'Cast[_OPT]'
| Produce a type cast, i.e. ``CAST(<expression> AS <type>)``.
|
| This is a shortcut to the :func:`_expression.cast` function.
|
| .. seealso::
|
| :ref:`tutorial_casts`
|
| :func:`_expression.cast`
|
| :func:`_expression.type_coerce`
|
| comparator(...)
|
| label(self, name: 'Optional[str]') -> 'Label[_T]'
| Produce a column label, i.e. ``<columnname> AS <name>``.
|
| This is a shortcut to the :func:`_expression.label` function.
|
| If 'name' is ``None``, an anonymous label name will be generated.
|
| operate(self, op: 'operators.OperatorType', *other: 'Any', **kwargs: 'Any') -> 'ColumnElement[Any]'
| Operate on an argument.
|
| This is the lowest level of operation, raises
| :class:`NotImplementedError` by default.
|
| Overriding this on a subclass can allow common
| behavior to be applied to all operations.
| For example, overriding :class:`.ColumnOperators`
| to apply ``func.lower()`` to the left and right
| side::
|
| class MyComparator(ColumnOperators):
| def operate(self, op, other, **kwargs):
| return op(func.lower(self), func.lower(other), **kwargs)
|
| :param op: Operator callable.
| :param \*other: the 'other' side of the operation. Will
| be a single scalar for most operations.
| :param \**kwargs: modifiers. These may be passed by special
| operators such as :meth:`ColumnOperators.contains`.
|
| proxy_set(...)
| set of all columns we are proxying
|
| as of 2.0 this is explicitly deannotated columns. previously it was
| effectively deannotated columns but wasn't enforced. annotated
| columns should basically not go into sets if at all possible because
| their hashing behavior is very non-performant.
|
| reverse_operate(self, op: 'operators.OperatorType', other: 'Any', **kwargs: 'Any') -> 'ColumnElement[Any]'
| Reverse operate on an argument.
|
| Usage is the same as :meth:`operate`.
|
| shares_lineage(self, othercolumn: 'ColumnElement[Any]') -> 'bool'
| Return True if the given :class:`_expression.ColumnElement`
| has a common ancestor to this :class:`_expression.ColumnElement`.
|
| type(...)
|
| ----------------------------------------------------------------------
| Readonly properties inherited from ColumnElement:
|
| anon_key_label
| .. deprecated:: 1.4 The :attr:`_expression.ColumnElement.anon_key_label` attribute is now private, and the public accessor is deprecated.
|
| anon_label
| .. deprecated:: 1.4 The :attr:`_expression.ColumnElement.anon_label` attribute is now private, and the public accessor is deprecated.
|
| expression
| Return a column expression.
|
| Part of the inspection interface; returns self.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from ColumnElement:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from ColumnElement:
|
| foreign_keys = frozenset()
|
| key = None
|
| primary_key = False
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.AllowsLambdaRole:
|
| allows_lambda = True
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.UsesInspection:
|
| uses_inspection = True
|
| ----------------------------------------------------------------------
| Class methods inherited from typing.Generic:
|
| __class_getitem__(...)
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__(...)
| Function to initialize subclasses.
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.operators.ColumnOperators:
|
| __add__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``+`` operator.
|
| In a column context, produces the clause ``a + b``
| if the parent object has non-string affinity.
| If the parent object has a string affinity,
| produces the concatenation operator, ``a || b`` -
| see :meth:`.ColumnOperators.concat`.
|
| __contains__(self, other: 'Any') -> 'ColumnOperators'
|
| __eq__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``==`` operator.
|
| In a column context, produces the clause ``a = b``.
| If the target is ``None``, produces ``a IS NULL``.
|
| __floordiv__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``//`` operator.
|
| In a column context, produces the clause ``a / b``,
| which is the same as "truediv", but considers the result
| type to be integer.
|
| .. versionadded:: 2.0
|
| __ge__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``>=`` operator.
|
| In a column context, produces the clause ``a >= b``.
|
| __getitem__(self, index: 'Any') -> 'ColumnOperators'
| Implement the [] operator.
|
| This can be used by some database-specific types
| such as PostgreSQL ARRAY and HSTORE.
|
| __gt__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``>`` operator.
|
| In a column context, produces the clause ``a > b``.
|
| __hash__(self, /) from builtins.object
| Return hash(self).
|
| __le__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``<=`` operator.
|
| In a column context, produces the clause ``a <= b``.
|
| __lshift__(self, other: 'Any') -> 'ColumnOperators'
| implement the << operator.
|
| Not used by SQLAlchemy core, this is provided
| for custom operator systems which want to use
| << as an extension point.
|
| __lt__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``<`` operator.
|
| In a column context, produces the clause ``a < b``.
|
| __mod__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``%`` operator.
|
| In a column context, produces the clause ``a % b``.
|
| __mul__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``*`` operator.
|
| In a column context, produces the clause ``a * b``.
|
| __ne__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``!=`` operator.
|
| In a column context, produces the clause ``a != b``.
| If the target is ``None``, produces ``a IS NOT NULL``.
|
| __neg__(self) -> 'ColumnOperators'
| Implement the ``-`` operator.
|
| In a column context, produces the clause ``-a``.
|
| __radd__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``+`` operator in reverse.
|
| See :meth:`.ColumnOperators.__add__`.
|
| __rfloordiv__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``//`` operator in reverse.
|
| See :meth:`.ColumnOperators.__floordiv__`.
|
| __rmod__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``%`` operator in reverse.
|
| See :meth:`.ColumnOperators.__mod__`.
|
| __rmul__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``*`` operator in reverse.
|
| See :meth:`.ColumnOperators.__mul__`.
|
| __rshift__(self, other: 'Any') -> 'ColumnOperators'
| implement the >> operator.
|
| Not used by SQLAlchemy core, this is provided
| for custom operator systems which want to use
| >> as an extension point.
|
| __rsub__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``-`` operator in reverse.
|
| See :meth:`.ColumnOperators.__sub__`.
|
| __rtruediv__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``/`` operator in reverse.
|
| See :meth:`.ColumnOperators.__truediv__`.
|
| __sub__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``-`` operator.
|
| In a column context, produces the clause ``a - b``.
|
| __truediv__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``/`` operator.
|
| In a column context, produces the clause ``a / b``, and
| considers the result type to be numeric.
|
| .. versionchanged:: 2.0 The truediv operator against two integers
| is now considered to return a numeric value. Behavior on specific
| backends may vary.
|
| all_(self) -> 'ColumnOperators'
| Produce an :func:`_expression.all_` clause against the
| parent object.
|
| See the documentation for :func:`_sql.all_` for examples.
|
| .. note:: be sure to not confuse the newer
| :meth:`_sql.ColumnOperators.all_` method with the **legacy**
| version of this method, the :meth:`_types.ARRAY.Comparator.all`
| method that's specific to :class:`_types.ARRAY`, which uses a
| different calling style.
|
| any_(self) -> 'ColumnOperators'
| Produce an :func:`_expression.any_` clause against the
| parent object.
|
| See the documentation for :func:`_sql.any_` for examples.
|
| .. note:: be sure to not confuse the newer
| :meth:`_sql.ColumnOperators.any_` method with the **legacy**
| version of this method, the :meth:`_types.ARRAY.Comparator.any`
| method that's specific to :class:`_types.ARRAY`, which uses a
| different calling style.
|
| asc(self) -> 'ColumnOperators'
| Produce a :func:`_expression.asc` clause against the
| parent object.
|
| between(self, cleft: 'Any', cright: 'Any', symmetric: 'bool' = False) -> 'ColumnOperators'
| Produce a :func:`_expression.between` clause against
| the parent object, given the lower and upper range.
|
| bitwise_and(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise AND operation, typically via the ``&``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_lshift(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise LSHIFT operation, typically via the ``<<``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_not(self) -> 'ColumnOperators'
| Produce a bitwise NOT operation, typically via the ``~``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_or(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise OR operation, typically via the ``|``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_rshift(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise RSHIFT operation, typically via the ``>>``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_xor(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise XOR operation, typically via the ``^``
| operator, or ``#`` for PostgreSQL.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| collate(self, collation: 'str') -> 'ColumnOperators'
| Produce a :func:`_expression.collate` clause against
| the parent object, given the collation string.
|
| .. seealso::
|
| :func:`_expression.collate`
|
| concat(self, other: 'Any') -> 'ColumnOperators'
| Implement the 'concat' operator.
|
| In a column context, produces the clause ``a || b``,
| or uses the ``concat()`` operator on MySQL.
|
| contains(self, other: 'Any', **kw: 'Any') -> 'ColumnOperators'
| Implement the 'contains' operator.
|
| Produces a LIKE expression that tests against a match for the middle
| of a string value:
|
| .. sourcecode:: sql
|
| column LIKE '%' || <other> || '%'
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.contains("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.contains.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.contains.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.contains.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.contains("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE '%' || :param || '%' ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.contains("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE '%' || :param || '%' ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.contains.autoescape`::
|
| somecolumn.contains("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.startswith`
|
| :meth:`.ColumnOperators.endswith`
|
| :meth:`.ColumnOperators.like`
|
| desc(self) -> 'ColumnOperators'
| Produce a :func:`_expression.desc` clause against the
| parent object.
|
| distinct(self) -> 'ColumnOperators'
| Produce a :func:`_expression.distinct` clause against the
| parent object.
|
| endswith(self, other: 'Any', escape: 'Optional[str]' = None, autoescape: 'bool' = False) -> 'ColumnOperators'
| Implement the 'endswith' operator.
|
| Produces a LIKE expression that tests against a match for the end
| of a string value:
|
| .. sourcecode:: sql
|
| column LIKE '%' || <other>
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.endswith("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.endswith.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.endswith.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.endswith.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.endswith("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE '%' || :param ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.endswith("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE '%' || :param ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.endswith.autoescape`::
|
| somecolumn.endswith("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.startswith`
|
| :meth:`.ColumnOperators.contains`
|
| :meth:`.ColumnOperators.like`
|
| icontains(self, other: 'Any', **kw: 'Any') -> 'ColumnOperators'
| Implement the ``icontains`` operator, e.g. case insensitive
| version of :meth:`.ColumnOperators.contains`.
|
| Produces a LIKE expression that tests against an insensitive match
| for the middle of a string value:
|
| .. sourcecode:: sql
|
| lower(column) LIKE '%' || lower(<other>) || '%'
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.icontains("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.icontains.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.icontains.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.icontains.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.icontains("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE '%' || lower(:param) || '%' ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.icontains("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE '%' || lower(:param) || '%' ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.contains.autoescape`::
|
| somecolumn.icontains("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.contains`
|
| iendswith(self, other: 'Any', escape: 'Optional[str]' = None, autoescape: 'bool' = False) -> 'ColumnOperators'
| Implement the ``iendswith`` operator, e.g. case insensitive
| version of :meth:`.ColumnOperators.endswith`.
|
| Produces a LIKE expression that tests against an insensitive match
| for the end of a string value:
|
| .. sourcecode:: sql
|
| lower(column) LIKE '%' || lower(<other>)
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.iendswith("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.iendswith.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.iendswith.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.iendswith.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.iendswith("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE '%' || lower(:param) ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.iendswith("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE '%' || lower(:param) ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.iendswith.autoescape`::
|
| somecolumn.endswith("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.endswith`
|
| ilike(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
| Implement the ``ilike`` operator, e.g. case insensitive LIKE.
|
| In a column context, produces an expression either of the form:
|
| .. sourcecode:: sql
|
| lower(a) LIKE lower(other)
|
| Or on backends that support the ILIKE operator:
|
| .. sourcecode:: sql
|
| a ILIKE other
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.ilike("%foobar%"))
|
| :param other: expression to be compared
| :param escape: optional escape character, renders the ``ESCAPE``
| keyword, e.g.::
|
| somecolumn.ilike("foo/%bar", escape="/")
|
| .. seealso::
|
| :meth:`.ColumnOperators.like`
|
| in_(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``in`` operator.
|
| In a column context, produces the clause ``column IN <other>``.
|
| The given parameter ``other`` may be:
|
| * A list of literal values,
| e.g.::
|
| stmt.where(column.in_([1, 2, 3]))
|
| In this calling form, the list of items is converted to a set of
| bound parameters the same length as the list given:
|
| .. sourcecode:: sql
|
| WHERE COL IN (?, ?, ?)
|
| * A list of tuples may be provided if the comparison is against a
| :func:`.tuple_` containing multiple expressions::
|
| from sqlalchemy import tuple_
|
| stmt.where(tuple_(col1, col2).in_([(1, 10), (2, 20), (3, 30)]))
|
| * An empty list,
| e.g.::
|
| stmt.where(column.in_([]))
|
| In this calling form, the expression renders an "empty set"
| expression. These expressions are tailored to individual backends
| and are generally trying to get an empty SELECT statement as a
| subquery. Such as on SQLite, the expression is:
|
| .. sourcecode:: sql
|
| WHERE col IN (SELECT 1 FROM (SELECT 1) WHERE 1!=1)
|
| .. versionchanged:: 1.4 empty IN expressions now use an
| execution-time generated SELECT subquery in all cases.
|
| * A bound parameter, e.g. :func:`.bindparam`, may be used if it
| includes the :paramref:`.bindparam.expanding` flag::
|
| stmt.where(column.in_(bindparam("value", expanding=True)))
|
| In this calling form, the expression renders a special non-SQL
| placeholder expression that looks like:
|
| .. sourcecode:: sql
|
| WHERE COL IN ([EXPANDING_value])
|
| This placeholder expression is intercepted at statement execution
| time to be converted into the variable number of bound parameter
| form illustrated earlier. If the statement were executed as::
|
| connection.execute(stmt, {"value": [1, 2, 3]})
|
| The database would be passed a bound parameter for each value:
|
| .. sourcecode:: sql
|
| WHERE COL IN (?, ?, ?)
|
| .. versionadded:: 1.2 added "expanding" bound parameters
|
| If an empty list is passed, a special "empty list" expression,
| which is specific to the database in use, is rendered. On
| SQLite this would be:
|
| .. sourcecode:: sql
|
| WHERE COL IN (SELECT 1 FROM (SELECT 1) WHERE 1!=1)
|
| .. versionadded:: 1.3 "expanding" bound parameters now support
| empty lists
|
| * a :func:`_expression.select` construct, which is usually a
| correlated scalar select::
|
| stmt.where(
| column.in_(select(othertable.c.y).where(table.c.x == othertable.c.x))
| )
|
| In this calling form, :meth:`.ColumnOperators.in_` renders as given:
|
| .. sourcecode:: sql
|
| WHERE COL IN (SELECT othertable.y
| FROM othertable WHERE othertable.x = table.x)
|
| :param other: a list of literals, a :func:`_expression.select`
| construct, or a :func:`.bindparam` construct that includes the
| :paramref:`.bindparam.expanding` flag set to True.
|
| is_(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``IS`` operator.
|
| Normally, ``IS`` is generated automatically when comparing to a
| value of ``None``, which resolves to ``NULL``. However, explicit
| usage of ``IS`` may be desirable if comparing to boolean values
| on certain platforms.
|
| .. seealso:: :meth:`.ColumnOperators.is_not`
|
| is_distinct_from(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``IS DISTINCT FROM`` operator.
|
| Renders "a IS DISTINCT FROM b" on most platforms;
| on some such as SQLite may render "a IS NOT b".
|
| is_not(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``IS NOT`` operator.
|
| Normally, ``IS NOT`` is generated automatically when comparing to a
| value of ``None``, which resolves to ``NULL``. However, explicit
| usage of ``IS NOT`` may be desirable if comparing to boolean values
| on certain platforms.
|
| .. versionchanged:: 1.4 The ``is_not()`` operator is renamed from
| ``isnot()`` in previous releases. The previous name remains
| available for backwards compatibility.
|
| .. seealso:: :meth:`.ColumnOperators.is_`
|
| is_not_distinct_from(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``IS NOT DISTINCT FROM`` operator.
|
| Renders "a IS NOT DISTINCT FROM b" on most platforms;
| on some such as SQLite may render "a IS b".
|
| .. versionchanged:: 1.4 The ``is_not_distinct_from()`` operator is
| renamed from ``isnot_distinct_from()`` in previous releases.
| The previous name remains available for backwards compatibility.
|
| isnot = is_not(self, other: 'Any') -> 'ColumnOperators'
|
| isnot_distinct_from = is_not_distinct_from(self, other: 'Any') -> 'ColumnOperators'
|
| istartswith(self, other: 'Any', escape: 'Optional[str]' = None, autoescape: 'bool' = False) -> 'ColumnOperators'
| Implement the ``istartswith`` operator, e.g. case insensitive
| version of :meth:`.ColumnOperators.startswith`.
|
| Produces a LIKE expression that tests against an insensitive
| match for the start of a string value:
|
| .. sourcecode:: sql
|
| lower(column) LIKE lower(<other>) || '%'
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.istartswith("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.istartswith.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.istartswith.escape` parameter will
| establish a given character as an escape character which can be of
| use when the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.istartswith.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.istartswith("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE lower(:param) || '%' ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.istartswith("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE lower(:param) || '%' ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.istartswith.autoescape`::
|
| somecolumn.istartswith("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.startswith`
|
| like(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
| Implement the ``like`` operator.
|
| In a column context, produces the expression:
|
| .. sourcecode:: sql
|
| a LIKE other
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.like("%foobar%"))
|
| :param other: expression to be compared
| :param escape: optional escape character, renders the ``ESCAPE``
| keyword, e.g.::
|
| somecolumn.like("foo/%bar", escape="/")
|
| .. seealso::
|
| :meth:`.ColumnOperators.ilike`
|
| match(self, other: 'Any', **kwargs: 'Any') -> 'ColumnOperators'
| Implements a database-specific 'match' operator.
|
| :meth:`_sql.ColumnOperators.match` attempts to resolve to
| a MATCH-like function or operator provided by the backend.
| Examples include:
|
| * PostgreSQL - renders ``x @@ plainto_tsquery(y)``
|
| .. versionchanged:: 2.0 ``plainto_tsquery()`` is used instead
| of ``to_tsquery()`` for PostgreSQL now; for compatibility with
| other forms, see :ref:`postgresql_match`.
|
|
| * MySQL - renders ``MATCH (x) AGAINST (y IN BOOLEAN MODE)``
|
| .. seealso::
|
| :class:`_mysql.match` - MySQL specific construct with
| additional features.
|
| * Oracle Database - renders ``CONTAINS(x, y)``
| * other backends may provide special implementations.
| * Backends without any special implementation will emit
| the operator as "MATCH". This is compatible with SQLite, for
| example.
|
| not_ilike(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
| implement the ``NOT ILIKE`` operator.
|
| This is equivalent to using negation with
| :meth:`.ColumnOperators.ilike`, i.e. ``~x.ilike(y)``.
|
| .. versionchanged:: 1.4 The ``not_ilike()`` operator is renamed from
| ``notilike()`` in previous releases. The previous name remains
| available for backwards compatibility.
|
| .. seealso::
|
| :meth:`.ColumnOperators.ilike`
|
| not_in(self, other: 'Any') -> 'ColumnOperators'
| implement the ``NOT IN`` operator.
|
| This is equivalent to using negation with
| :meth:`.ColumnOperators.in_`, i.e. ``~x.in_(y)``.
|
| In the case that ``other`` is an empty sequence, the compiler
| produces an "empty not in" expression. This defaults to the
| expression "1 = 1" to produce true in all cases. The
| :paramref:`_sa.create_engine.empty_in_strategy` may be used to
| alter this behavior.
|
| .. versionchanged:: 1.4 The ``not_in()`` operator is renamed from
| ``notin_()`` in previous releases. The previous name remains
| available for backwards compatibility.
|
| .. versionchanged:: 1.2 The :meth:`.ColumnOperators.in_` and
| :meth:`.ColumnOperators.not_in` operators
| now produce a "static" expression for an empty IN sequence
| by default.
|
| .. seealso::
|
| :meth:`.ColumnOperators.in_`
|
| not_like(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
| implement the ``NOT LIKE`` operator.
|
| This is equivalent to using negation with
| :meth:`.ColumnOperators.like`, i.e. ``~x.like(y)``.
|
| .. versionchanged:: 1.4 The ``not_like()`` operator is renamed from
| ``notlike()`` in previous releases. The previous name remains
| available for backwards compatibility.
|
| .. seealso::
|
| :meth:`.ColumnOperators.like`
|
| notilike = not_ilike(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
|
| notin_ = not_in(self, other: 'Any') -> 'ColumnOperators'
|
| notlike = not_like(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
|
| nulls_first(self) -> 'ColumnOperators'
| Produce a :func:`_expression.nulls_first` clause against the
| parent object.
|
| .. versionchanged:: 1.4 The ``nulls_first()`` operator is
| renamed from ``nullsfirst()`` in previous releases.
| The previous name remains available for backwards compatibility.
|
| nulls_last(self) -> 'ColumnOperators'
| Produce a :func:`_expression.nulls_last` clause against the
| parent object.
|
| .. versionchanged:: 1.4 The ``nulls_last()`` operator is
| renamed from ``nullslast()`` in previous releases.
| The previous name remains available for backwards compatibility.
|
| nullsfirst = nulls_first(self) -> 'ColumnOperators'
|
| nullslast = nulls_last(self) -> 'ColumnOperators'
|
| regexp_match(self, pattern: 'Any', flags: 'Optional[str]' = None) -> 'ColumnOperators'
| Implements a database-specific 'regexp match' operator.
|
| E.g.::
|
| stmt = select(table.c.some_column).where(
| table.c.some_column.regexp_match("^(b|c)")
| )
|
| :meth:`_sql.ColumnOperators.regexp_match` attempts to resolve to
| a REGEXP-like function or operator provided by the backend, however
| the specific regular expression syntax and flags available are
| **not backend agnostic**.
|
| Examples include:
|
| * PostgreSQL - renders ``x ~ y`` or ``x !~ y`` when negated.
| * Oracle Database - renders ``REGEXP_LIKE(x, y)``
| * SQLite - uses SQLite's ``REGEXP`` placeholder operator and calls into
| the Python ``re.match()`` builtin.
| * other backends may provide special implementations.
| * Backends without any special implementation will emit
| the operator as "REGEXP" or "NOT REGEXP". This is compatible with
| SQLite and MySQL, for example.
|
| Regular expression support is currently implemented for Oracle
| Database, PostgreSQL, MySQL and MariaDB. Partial support is available
| for SQLite. Support among third-party dialects may vary.
|
| :param pattern: The regular expression pattern string or column
| clause.
| :param flags: Any regular expression string flags to apply, passed as
| plain Python string only. These flags are backend specific.
| Some backends, like PostgreSQL and MariaDB, may alternatively
| specify the flags as part of the pattern.
| When using the ignore case flag 'i' in PostgreSQL, the ignore case
| regexp match operator ``~*`` or ``!~*`` will be used.
|
| .. versionadded:: 1.4
|
| .. versionchanged:: 1.4.48, 2.0.18 Note that due to an implementation
| error, the "flags" parameter previously accepted SQL expression
| objects such as column expressions in addition to plain Python
| strings. This implementation did not work correctly with caching
| and was removed; strings only should be passed for the "flags"
| parameter, as these flags are rendered as literal inline values
| within SQL expressions.
|
| .. seealso::
|
| :meth:`_sql.ColumnOperators.regexp_replace`
|
| regexp_replace(self, pattern: 'Any', replacement: 'Any', flags: 'Optional[str]' = None) -> 'ColumnOperators'
| Implements a database-specific 'regexp replace' operator.
|
| E.g.::
|
| stmt = select(
| table.c.some_column.regexp_replace("b(..)", "XY", flags="g")
| )
|
| :meth:`_sql.ColumnOperators.regexp_replace` attempts to resolve to
| a REGEXP_REPLACE-like function provided by the backend, that
| usually emit the function ``REGEXP_REPLACE()``. However,
| the specific regular expression syntax and flags available are
| **not backend agnostic**.
|
| Regular expression replacement support is currently implemented for
| Oracle Database, PostgreSQL, MySQL 8 or greater and MariaDB. Support
| among third-party dialects may vary.
|
| :param pattern: The regular expression pattern string or column
| clause.
| :param pattern: The replacement string or column clause.
| :param flags: Any regular expression string flags to apply, passed as
| plain Python string only. These flags are backend specific.
| Some backends, like PostgreSQL and MariaDB, may alternatively
| specify the flags as part of the pattern.
|
| .. versionadded:: 1.4
|
| .. versionchanged:: 1.4.48, 2.0.18 Note that due to an implementation
| error, the "flags" parameter previously accepted SQL expression
| objects such as column expressions in addition to plain Python
| strings. This implementation did not work correctly with caching
| and was removed; strings only should be passed for the "flags"
| parameter, as these flags are rendered as literal inline values
| within SQL expressions.
|
|
| .. seealso::
|
| :meth:`_sql.ColumnOperators.regexp_match`
|
| startswith(self, other: 'Any', escape: 'Optional[str]' = None, autoescape: 'bool' = False) -> 'ColumnOperators'
| Implement the ``startswith`` operator.
|
| Produces a LIKE expression that tests against a match for the start
| of a string value:
|
| .. sourcecode:: sql
|
| column LIKE <other> || '%'
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.startswith("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.startswith.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.startswith.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.startswith.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.startswith("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE :param || '%' ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.startswith("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE :param || '%' ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.startswith.autoescape`::
|
| somecolumn.startswith("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.endswith`
|
| :meth:`.ColumnOperators.contains`
|
| :meth:`.ColumnOperators.like`
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.operators.ColumnOperators:
|
| timetuple = None
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.operators.Operators:
|
| __and__(self, other: 'Any') -> 'Operators'
| Implement the ``&`` operator.
|
| When used with SQL expressions, results in an
| AND operation, equivalent to
| :func:`_expression.and_`, that is::
|
| a & b
|
| is equivalent to::
|
| from sqlalchemy import and_
|
| and_(a, b)
|
| Care should be taken when using ``&`` regarding
| operator precedence; the ``&`` operator has the highest precedence.
| The operands should be enclosed in parenthesis if they contain
| further sub expressions::
|
| (a == 2) & (b == 4)
|
| __invert__(self) -> 'Operators'
| Implement the ``~`` operator.
|
| When used with SQL expressions, results in a
| NOT operation, equivalent to
| :func:`_expression.not_`, that is::
|
| ~a
|
| is equivalent to::
|
| from sqlalchemy import not_
|
| not_(a)
|
| __or__(self, other: 'Any') -> 'Operators'
| Implement the ``|`` operator.
|
| When used with SQL expressions, results in an
| OR operation, equivalent to
| :func:`_expression.or_`, that is::
|
| a | b
|
| is equivalent to::
|
| from sqlalchemy import or_
|
| or_(a, b)
|
| Care should be taken when using ``|`` regarding
| operator precedence; the ``|`` operator has the highest precedence.
| The operands should be enclosed in parenthesis if they contain
| further sub expressions::
|
| (a == 2) | (b == 4)
|
| __sa_operate__ = operate(self, op: 'OperatorType', *other: 'Any', **kwargs: 'Any') -> 'Operators'
| Operate on an argument.
|
| This is the lowest level of operation, raises
| :class:`NotImplementedError` by default.
|
| Overriding this on a subclass can allow common
| behavior to be applied to all operations.
| For example, overriding :class:`.ColumnOperators`
| to apply ``func.lower()`` to the left and right
| side::
|
| class MyComparator(ColumnOperators):
| def operate(self, op, other, **kwargs):
| return op(func.lower(self), func.lower(other), **kwargs)
|
| :param op: Operator callable.
| :param \*other: the 'other' side of the operation. Will
| be a single scalar for most operations.
| :param \**kwargs: modifiers. These may be passed by special
| operators such as :meth:`ColumnOperators.contains`.
|
| bool_op(self, opstring: 'str', precedence: 'int' = 0, python_impl: 'Optional[Callable[..., Any]]' = None) -> 'Callable[[Any], Operators]'
| Return a custom boolean operator.
|
| This method is shorthand for calling
| :meth:`.Operators.op` and passing the
| :paramref:`.Operators.op.is_comparison`
| flag with True. A key advantage to using :meth:`.Operators.bool_op`
| is that when using column constructs, the "boolean" nature of the
| returned expression will be present for :pep:`484` purposes.
|
| .. seealso::
|
| :meth:`.Operators.op`
|
| op(self, opstring: 'str', precedence: 'int' = 0, is_comparison: 'bool' = False, return_type: 'Optional[Union[Type[TypeEngine[Any]], TypeEngine[Any]]]' = None, python_impl: 'Optional[Callable[..., Any]]' = None) -> 'Callable[[Any], Operators]'
| Produce a generic operator function.
|
| e.g.::
|
| somecolumn.op("*")(5)
|
| produces::
|
| somecolumn * 5
|
| This function can also be used to make bitwise operators explicit. For
| example::
|
| somecolumn.op("&")(0xFF)
|
| is a bitwise AND of the value in ``somecolumn``.
|
| :param opstring: a string which will be output as the infix operator
| between this element and the expression passed to the
| generated function.
|
| :param precedence: precedence which the database is expected to apply
| to the operator in SQL expressions. This integer value acts as a hint
| for the SQL compiler to know when explicit parenthesis should be
| rendered around a particular operation. A lower number will cause the
| expression to be parenthesized when applied against another operator
| with higher precedence. The default value of ``0`` is lower than all
| operators except for the comma (``,``) and ``AS`` operators. A value
| of 100 will be higher or equal to all operators, and -100 will be
| lower than or equal to all operators.
|
| .. seealso::
|
| :ref:`faq_sql_expression_op_parenthesis` - detailed description
| of how the SQLAlchemy SQL compiler renders parenthesis
|
| :param is_comparison: legacy; if True, the operator will be considered
| as a "comparison" operator, that is which evaluates to a boolean
| true/false value, like ``==``, ``>``, etc. This flag is provided
| so that ORM relationships can establish that the operator is a
| comparison operator when used in a custom join condition.
|
| Using the ``is_comparison`` parameter is superseded by using the
| :meth:`.Operators.bool_op` method instead; this more succinct
| operator sets this parameter automatically, but also provides
| correct :pep:`484` typing support as the returned object will
| express a "boolean" datatype, i.e. ``BinaryExpression[bool]``.
|
| :param return_type: a :class:`.TypeEngine` class or object that will
| force the return type of an expression produced by this operator
| to be of that type. By default, operators that specify
| :paramref:`.Operators.op.is_comparison` will resolve to
| :class:`.Boolean`, and those that do not will be of the same
| type as the left-hand operand.
|
| :param python_impl: an optional Python function that can evaluate
| two Python values in the same way as this operator works when
| run on the database server. Useful for in-Python SQL expression
| evaluation functions, such as for ORM hybrid attributes, and the
| ORM "evaluator" used to match objects in a session after a multi-row
| update or delete.
|
| e.g.::
|
| >>> expr = column("x").op("+", python_impl=lambda a, b: a + b)("y")
|
| The operator for the above expression will also work for non-SQL
| left and right objects::
|
| >>> expr.operator(5, 10)
| 15
|
| .. versionadded:: 2.0
|
|
| .. seealso::
|
| :meth:`.Operators.bool_op`
|
| :ref:`types_operators`
|
| :ref:`relationship_custom_operator`
|
| ----------------------------------------------------------------------
| Methods inherited from ClauseElement:
|
| __bool__(self)
|
| __getstate__(self)
| Helper for pickle.
|
| __repr__(self)
| Return repr(self).
|
| compare(self, other: 'ClauseElement', **kw: 'Any') -> 'bool'
| Compare this :class:`_expression.ClauseElement` to
| the given :class:`_expression.ClauseElement`.
|
| Subclasses should override the default behavior, which is a
| straight identity comparison.
|
| \**kw are arguments consumed by subclass ``compare()`` methods and
| may be used to modify the criteria for comparison
| (see :class:`_expression.ColumnElement`).
|
| description(...)
|
| entity_namespace(...)
|
| params(self, _ClauseElement__optionaldict: 'Optional[Mapping[str, Any]]' = None, **kwargs: 'Any') -> 'Self'
| Return a copy with :func:`_expression.bindparam` elements
| replaced.
|
| Returns a copy of this ClauseElement with
| :func:`_expression.bindparam`
| elements replaced with values taken from the given dictionary::
|
| >>> clause = column("x") + bindparam("foo")
| >>> print(clause.compile().params)
| {'foo':None}
| >>> print(clause.params({"foo": 7}).compile().params)
| {'foo':7}
|
| unique_params(self, _ClauseElement__optionaldict: 'Optional[Dict[str, Any]]' = None, **kwargs: 'Any') -> 'Self'
| Return a copy with :func:`_expression.bindparam` elements
| replaced.
|
| Same functionality as :meth:`_expression.ClauseElement.params`,
| except adds `unique=True`
| to affected bind parameters so that multiple statements can be
| used.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from ClauseElement:
|
| is_clause_element = True
|
| is_dml = False
|
| is_selectable = False
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_instancemethod(fn: '_F') -> '_F'
| Decorate a method memoize its return value.
|
| :meta private:
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_attribute = <class 'sqlalchemy.util.langhelpers.HasMemoized.m...
| A read-only @property that is only evaluated once.
|
| :meta private:
|
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.visitors.HasTraverseInternals:
|
| get_children(self, *, omit_attrs: 'Tuple[str, ...]' = (), **kw: 'Any') -> 'Iterable[HasTraverseInternals]'
| Return immediate child :class:`.visitors.HasTraverseInternals`
| elements of this :class:`.visitors.HasTraverseInternals`.
|
| This is used for visit traversal.
|
| \**kw may contain flags that change the collection that is
| returned, for example to return a subset of items in order to
| cut down on larger traversals, or to return child items from a
| different context (such as schema-level collections instead of
| clause-level).
|
| ----------------------------------------------------------------------
| Methods inherited from CompilerElement:
|
| __str__(self) -> 'str'
| Return str(self).
|
| compile(self, bind: 'Optional[_HasDialect]' = None, dialect: 'Optional[Dialect]' = None, **kw: 'Any') -> 'Compiled'
| Compile this SQL expression.
|
| The return value is a :class:`~.Compiled` object.
| Calling ``str()`` or ``unicode()`` on the returned value will yield a
| string representation of the result. The
| :class:`~.Compiled` object also can return a
| dictionary of bind parameter names and values
| using the ``params`` accessor.
|
| :param bind: An :class:`.Connection` or :class:`.Engine` which
| can provide a :class:`.Dialect` in order to generate a
| :class:`.Compiled` object. If the ``bind`` and
| ``dialect`` parameters are both omitted, a default SQL compiler
| is used.
|
| :param column_keys: Used for INSERT and UPDATE statements, a list of
| column names which should be present in the VALUES clause of the
| compiled statement. If ``None``, all columns from the target table
| object are rendered.
|
| :param dialect: A :class:`.Dialect` instance which can generate
| a :class:`.Compiled` object. This argument takes precedence over
| the ``bind`` argument.
|
| :param compile_kwargs: optional dictionary of additional parameters
| that will be passed through to the compiler within all "visit"
| methods. This allows any custom flag to be passed through to
| a custom compilation construct, for example. It is also used
| for the case of passing the ``literal_binds`` flag through::
|
| from sqlalchemy.sql import table, column, select
|
| t = table("t", column("x"))
|
| s = select(t).where(t.c.x == 5)
|
| print(s.compile(compile_kwargs={"literal_binds": True}))
|
| .. seealso::
|
| :ref:`faq_sql_expression_string`
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from CompilerElement:
|
| stringify_dialect = 'default'
|
| supports_execution = False
sqlalchemy.CHAR
Python Library Documentation: class CHAR in module sqlalchemy.sql.sqltypes
class CHAR(String)
| CHAR(length: 'Optional[int]' = None, collation: 'Optional[str]' = None)
|
| The SQL CHAR type.
|
| Method resolution order:
| CHAR
| String
| Concatenable
| sqlalchemy.sql.type_api.TypeEngineMixin
| sqlalchemy.sql.type_api.TypeEngine
| sqlalchemy.sql.visitors.Visitable
| typing.Generic
| builtins.object
|
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| __parameters__ = ()
|
| __visit_name__ = 'CHAR'
|
| ----------------------------------------------------------------------
| Methods inherited from String:
|
| __init__(self, length: 'Optional[int]' = None, collation: 'Optional[str]' = None)
| Create a string-holding type.
|
| :param length: optional, a length for the column for use in
| DDL and CAST expressions. May be safely omitted if no ``CREATE
| TABLE`` will be issued. Certain databases may require a
| ``length`` for use in DDL, and will raise an exception when
| the ``CREATE TABLE`` DDL is issued if a ``VARCHAR``
| with no length is included. Whether the value is
| interpreted as bytes or characters is database specific.
|
| :param collation: Optional, a column-level collation for
| use in DDL and CAST expressions. Renders using the
| COLLATE keyword supported by SQLite, MySQL, and PostgreSQL.
| E.g.:
|
| .. sourcecode:: pycon+sql
|
| >>> from sqlalchemy import cast, select, String
| >>> print(select(cast("some string", String(collation="utf8"))))
| {printsql}SELECT CAST(:param_1 AS VARCHAR COLLATE utf8) AS anon_1
|
| .. note::
|
| In most cases, the :class:`.Unicode` or :class:`.UnicodeText`
| datatypes should be used for a :class:`_schema.Column` that expects
| to store non-ascii data. These datatypes will ensure that the
| correct types are used on the database.
|
| bind_processor(self, dialect: 'Dialect') -> 'Optional[_BindProcessorType[str]]'
| Return a conversion function for processing bind values.
|
| Returns a callable which will receive a bind parameter value
| as the sole positional argument and will return a value to
| send to the DB-API.
|
| If processing is not necessary, the method should return ``None``.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.bind_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.bind_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_bind_param`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
|
| :param dialect: Dialect instance in use.
|
| get_dbapi_type(self, dbapi)
| Return the corresponding type object from the underlying DB-API, if
| any.
|
| This can be useful for calling ``setinputsizes()``, for example.
|
| literal_processor(self, dialect)
| Return a conversion function for processing literal values that are
| to be rendered directly without using binds.
|
| This function is used when the compiler makes use of the
| "literal_binds" flag, typically used in DDL generation as well
| as in certain scenarios where backends don't accept bound parameters.
|
| Returns a callable which will receive a literal Python value
| as the sole positional argument and will return a string representation
| to be rendered in a SQL statement.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.literal_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.literal_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_literal_param`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| result_processor(self, dialect: 'Dialect', coltype: 'object') -> 'Optional[_ResultProcessorType[str]]'
| Return a conversion function for processing result row values.
|
| Returns a callable which will receive a result row column
| value as the sole positional argument and will return a value
| to return to the user.
|
| If processing is not necessary, the method should return ``None``.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.result_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.result_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_result_value`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| :param dialect: Dialect instance in use.
|
| :param coltype: DBAPI coltype argument received in cursor.description.
|
| ----------------------------------------------------------------------
| Readonly properties inherited from String:
|
| python_type
| Return the Python type object expected to be returned
| by instances of this type, if known.
|
| Basically, for those types which enforce a return type,
| or are known across the board to do such for all common
| DBAPIs (like ``int`` for example), will return that type.
|
| If a return type is not defined, raises
| ``NotImplementedError``.
|
| Note that any type also accommodates NULL in SQL which
| means you can also get back ``None`` from any type
| in practice.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from Concatenable:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from Concatenable:
|
| Comparator = <class 'sqlalchemy.sql.sqltypes.Concatenable.Comparator'>
|
| comparator_factory = <class 'sqlalchemy.sql.sqltypes.Concatenable.Comp...
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.type_api.TypeEngine:
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| __str__(self) -> 'str'
| Return str(self).
|
| adapt(self, cls: 'Type[Union[TypeEngine[Any], TypeEngineMixin]]', **kw: 'Any') -> 'TypeEngine[Any]'
| Produce an "adapted" form of this type, given an "impl" class
| to work with.
|
| This method is used internally to associate generic
| types with "implementation" types that are specific to a particular
| dialect.
|
| as_generic(self, allow_nulltype: 'bool' = False) -> 'TypeEngine[_T]'
| Return an instance of the generic type corresponding to this type
| using heuristic rule. The method may be overridden if this
| heuristic rule is not sufficient.
|
| >>> from sqlalchemy.dialects.mysql import INTEGER
| >>> INTEGER(display_width=4).as_generic()
| Integer()
|
| >>> from sqlalchemy.dialects.mysql import NVARCHAR
| >>> NVARCHAR(length=100).as_generic()
| Unicode(length=100)
|
| .. versionadded:: 1.4.0b2
|
|
| .. seealso::
|
| :ref:`metadata_reflection_dbagnostic_types` - describes the
| use of :meth:`_types.TypeEngine.as_generic` in conjunction with
| the :meth:`_sql.DDLEvents.column_reflect` event, which is its
| intended use.
|
| bind_expression(self, bindvalue: 'BindParameter[_T]') -> 'Optional[ColumnElement[_T]]'
| Given a bind value (i.e. a :class:`.BindParameter` instance),
| return a SQL expression in its place.
|
| This is typically a SQL function that wraps the existing bound
| parameter within the statement. It is used for special data types
| that require literals being wrapped in some special database function
| in order to coerce an application-level value into a database-specific
| format. It is the SQL analogue of the
| :meth:`.TypeEngine.bind_processor` method.
|
| This method is called during the **SQL compilation** phase of a
| statement, when rendering a SQL string. It is **not** called
| against specific values.
|
| Note that this method, when implemented, should always return
| the exact same structure, without any conditional logic, as it
| may be used in an executemany() call against an arbitrary number
| of bound parameter sets.
|
| .. note::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.bind_expression`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.bind_expression`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.bind_expression`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| .. seealso::
|
| :ref:`types_sql_value_processing`
|
| coerce_compared_value(self, op: 'Optional[OperatorType]', value: 'Any') -> 'TypeEngine[Any]'
| Suggest a type for a 'coerced' Python value in an expression.
|
| Given an operator and value, gives the type a chance
| to return a type which the value should be coerced into.
|
| The default behavior here is conservative; if the right-hand
| side is already coerced into a SQL type based on its
| Python type, it is usually left alone.
|
| End-user functionality extension here should generally be via
| :class:`.TypeDecorator`, which provides more liberal behavior in that
| it defaults to coercing the other side of the expression into this
| type, thus applying special Python conversions above and beyond those
| needed by the DBAPI to both ides. It also provides the public method
| :meth:`.TypeDecorator.coerce_compared_value` which is intended for
| end-user customization of this behavior.
|
| column_expression(self, colexpr: 'ColumnElement[_T]') -> 'Optional[ColumnElement[_T]]'
| Given a SELECT column expression, return a wrapping SQL expression.
|
| This is typically a SQL function that wraps a column expression
| as rendered in the columns clause of a SELECT statement.
| It is used for special data types that require
| columns to be wrapped in some special database function in order
| to coerce the value before being sent back to the application.
| It is the SQL analogue of the :meth:`.TypeEngine.result_processor`
| method.
|
| .. note:: The :func:`.TypeEngine.column_expression` method is applied
| only to the **outermost columns clause** of a SELECT statement, that
| is, the columns that are to be delivered directly into the returned
| result rows. It does **not** apply to the columns clause inside
| of subqueries. This necessarily avoids double conversions against
| the column and only runs the conversion when ready to be returned
| to the client.
|
| This method is called during the **SQL compilation** phase of a
| statement, when rendering a SQL string. It is **not** called
| against specific values.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.column_expression`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.column_expression`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.column_expression`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
|
| .. seealso::
|
| :ref:`types_sql_value_processing`
|
| compare_values(self, x: 'Any', y: 'Any') -> 'bool'
| Compare two values for equality.
|
| compile(self, dialect: 'Optional[Dialect]' = None) -> 'str'
| Produce a string-compiled form of this :class:`.TypeEngine`.
|
| When called with no arguments, uses a "default" dialect
| to produce a string result.
|
| :param dialect: a :class:`.Dialect` instance.
|
| copy(self, **kw: 'Any') -> 'Self'
|
| copy_value(self, value: 'Any') -> 'Any'
|
| dialect_impl(self, dialect: 'Dialect') -> 'TypeEngine[_T]'
| Return a dialect-specific implementation for this
| :class:`.TypeEngine`.
|
| evaluates_none(self) -> 'Self'
| Return a copy of this type which has the
| :attr:`.should_evaluate_none` flag set to True.
|
| E.g.::
|
| Table(
| "some_table",
| metadata,
| Column(
| String(50).evaluates_none(),
| nullable=True,
| server_default="no value",
| ),
| )
|
| The ORM uses this flag to indicate that a positive value of ``None``
| is passed to the column in an INSERT statement, rather than omitting
| the column from the INSERT statement which has the effect of firing
| off column-level defaults. It also allows for types which have
| special behavior associated with the Python None value to indicate
| that the value doesn't necessarily translate into SQL NULL; a
| prime example of this is a JSON type which may wish to persist the
| JSON value ``'null'``.
|
| In all cases, the actual NULL SQL value can be always be
| persisted in any column by using
| the :obj:`_expression.null` SQL construct in an INSERT statement
| or associated with an ORM-mapped attribute.
|
| .. note::
|
| The "evaluates none" flag does **not** apply to a value
| of ``None`` passed to :paramref:`_schema.Column.default` or
| :paramref:`_schema.Column.server_default`; in these cases,
| ``None``
| still means "no default".
|
| .. seealso::
|
| :ref:`session_forcing_null` - in the ORM documentation
|
| :paramref:`.postgresql.JSON.none_as_null` - PostgreSQL JSON
| interaction with this flag.
|
| :attr:`.TypeEngine.should_evaluate_none` - class-level flag
|
| with_variant(self, type_: '_TypeEngineArgument[Any]', *dialect_names: 'str') -> 'Self'
| Produce a copy of this type object that will utilize the given
| type when applied to the dialect of the given name.
|
| e.g.::
|
| from sqlalchemy.types import String
| from sqlalchemy.dialects import mysql
|
| string_type = String()
|
| string_type = string_type.with_variant(
| mysql.VARCHAR(collation="foo"), "mysql", "mariadb"
| )
|
| The variant mapping indicates that when this type is
| interpreted by a specific dialect, it will instead be
| transmuted into the given type, rather than using the
| primary type.
|
| .. versionchanged:: 2.0 the :meth:`_types.TypeEngine.with_variant`
| method now works with a :class:`_types.TypeEngine` object "in
| place", returning a copy of the original type rather than returning
| a wrapping object; the ``Variant`` class is no longer used.
|
| :param type\_: a :class:`.TypeEngine` that will be selected
| as a variant from the originating type, when a dialect
| of the given name is in use.
| :param \*dialect_names: one or more base names of the dialect which
| uses this type. (i.e. ``'postgresql'``, ``'mysql'``, etc.)
|
| .. versionchanged:: 2.0 multiple dialect names can be specified
| for one variant.
|
| .. seealso::
|
| :ref:`types_with_variant` - illustrates the use of
| :meth:`_types.TypeEngine.with_variant`.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.type_api.TypeEngine:
|
| __orig_bases__ = (<class 'sqlalchemy.sql.visitors.Visitable'>, typing....
|
| hashable = True
|
| render_bind_cast = False
|
| render_literal_cast = False
|
| should_evaluate_none = False
|
| sort_key_function = None
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.visitors.Visitable:
|
| __class_getitem__(key: 'Any') -> 'Any'
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__() -> 'None'
| This method is called when a class is subclassed.
|
| The default implementation does nothing. It may be
| overridden to extend subclasses.
sqlalchemy.CLOB
Python Library Documentation: class CLOB in module sqlalchemy.sql.sqltypes
class CLOB(Text)
| CLOB(length: 'Optional[int]' = None, collation: 'Optional[str]' = None)
|
| The CLOB type.
|
| This type is found in Oracle Database and Informix.
|
| Method resolution order:
| CLOB
| Text
| String
| Concatenable
| sqlalchemy.sql.type_api.TypeEngineMixin
| sqlalchemy.sql.type_api.TypeEngine
| sqlalchemy.sql.visitors.Visitable
| typing.Generic
| builtins.object
|
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| __parameters__ = ()
|
| __visit_name__ = 'CLOB'
|
| ----------------------------------------------------------------------
| Methods inherited from String:
|
| __init__(self, length: 'Optional[int]' = None, collation: 'Optional[str]' = None)
| Create a string-holding type.
|
| :param length: optional, a length for the column for use in
| DDL and CAST expressions. May be safely omitted if no ``CREATE
| TABLE`` will be issued. Certain databases may require a
| ``length`` for use in DDL, and will raise an exception when
| the ``CREATE TABLE`` DDL is issued if a ``VARCHAR``
| with no length is included. Whether the value is
| interpreted as bytes or characters is database specific.
|
| :param collation: Optional, a column-level collation for
| use in DDL and CAST expressions. Renders using the
| COLLATE keyword supported by SQLite, MySQL, and PostgreSQL.
| E.g.:
|
| .. sourcecode:: pycon+sql
|
| >>> from sqlalchemy import cast, select, String
| >>> print(select(cast("some string", String(collation="utf8"))))
| {printsql}SELECT CAST(:param_1 AS VARCHAR COLLATE utf8) AS anon_1
|
| .. note::
|
| In most cases, the :class:`.Unicode` or :class:`.UnicodeText`
| datatypes should be used for a :class:`_schema.Column` that expects
| to store non-ascii data. These datatypes will ensure that the
| correct types are used on the database.
|
| bind_processor(self, dialect: 'Dialect') -> 'Optional[_BindProcessorType[str]]'
| Return a conversion function for processing bind values.
|
| Returns a callable which will receive a bind parameter value
| as the sole positional argument and will return a value to
| send to the DB-API.
|
| If processing is not necessary, the method should return ``None``.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.bind_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.bind_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_bind_param`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
|
| :param dialect: Dialect instance in use.
|
| get_dbapi_type(self, dbapi)
| Return the corresponding type object from the underlying DB-API, if
| any.
|
| This can be useful for calling ``setinputsizes()``, for example.
|
| literal_processor(self, dialect)
| Return a conversion function for processing literal values that are
| to be rendered directly without using binds.
|
| This function is used when the compiler makes use of the
| "literal_binds" flag, typically used in DDL generation as well
| as in certain scenarios where backends don't accept bound parameters.
|
| Returns a callable which will receive a literal Python value
| as the sole positional argument and will return a string representation
| to be rendered in a SQL statement.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.literal_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.literal_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_literal_param`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| result_processor(self, dialect: 'Dialect', coltype: 'object') -> 'Optional[_ResultProcessorType[str]]'
| Return a conversion function for processing result row values.
|
| Returns a callable which will receive a result row column
| value as the sole positional argument and will return a value
| to return to the user.
|
| If processing is not necessary, the method should return ``None``.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.result_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.result_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_result_value`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| :param dialect: Dialect instance in use.
|
| :param coltype: DBAPI coltype argument received in cursor.description.
|
| ----------------------------------------------------------------------
| Readonly properties inherited from String:
|
| python_type
| Return the Python type object expected to be returned
| by instances of this type, if known.
|
| Basically, for those types which enforce a return type,
| or are known across the board to do such for all common
| DBAPIs (like ``int`` for example), will return that type.
|
| If a return type is not defined, raises
| ``NotImplementedError``.
|
| Note that any type also accommodates NULL in SQL which
| means you can also get back ``None`` from any type
| in practice.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from Concatenable:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from Concatenable:
|
| Comparator = <class 'sqlalchemy.sql.sqltypes.Concatenable.Comparator'>
|
| comparator_factory = <class 'sqlalchemy.sql.sqltypes.Concatenable.Comp...
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.type_api.TypeEngine:
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| __str__(self) -> 'str'
| Return str(self).
|
| adapt(self, cls: 'Type[Union[TypeEngine[Any], TypeEngineMixin]]', **kw: 'Any') -> 'TypeEngine[Any]'
| Produce an "adapted" form of this type, given an "impl" class
| to work with.
|
| This method is used internally to associate generic
| types with "implementation" types that are specific to a particular
| dialect.
|
| as_generic(self, allow_nulltype: 'bool' = False) -> 'TypeEngine[_T]'
| Return an instance of the generic type corresponding to this type
| using heuristic rule. The method may be overridden if this
| heuristic rule is not sufficient.
|
| >>> from sqlalchemy.dialects.mysql import INTEGER
| >>> INTEGER(display_width=4).as_generic()
| Integer()
|
| >>> from sqlalchemy.dialects.mysql import NVARCHAR
| >>> NVARCHAR(length=100).as_generic()
| Unicode(length=100)
|
| .. versionadded:: 1.4.0b2
|
|
| .. seealso::
|
| :ref:`metadata_reflection_dbagnostic_types` - describes the
| use of :meth:`_types.TypeEngine.as_generic` in conjunction with
| the :meth:`_sql.DDLEvents.column_reflect` event, which is its
| intended use.
|
| bind_expression(self, bindvalue: 'BindParameter[_T]') -> 'Optional[ColumnElement[_T]]'
| Given a bind value (i.e. a :class:`.BindParameter` instance),
| return a SQL expression in its place.
|
| This is typically a SQL function that wraps the existing bound
| parameter within the statement. It is used for special data types
| that require literals being wrapped in some special database function
| in order to coerce an application-level value into a database-specific
| format. It is the SQL analogue of the
| :meth:`.TypeEngine.bind_processor` method.
|
| This method is called during the **SQL compilation** phase of a
| statement, when rendering a SQL string. It is **not** called
| against specific values.
|
| Note that this method, when implemented, should always return
| the exact same structure, without any conditional logic, as it
| may be used in an executemany() call against an arbitrary number
| of bound parameter sets.
|
| .. note::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.bind_expression`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.bind_expression`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.bind_expression`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| .. seealso::
|
| :ref:`types_sql_value_processing`
|
| coerce_compared_value(self, op: 'Optional[OperatorType]', value: 'Any') -> 'TypeEngine[Any]'
| Suggest a type for a 'coerced' Python value in an expression.
|
| Given an operator and value, gives the type a chance
| to return a type which the value should be coerced into.
|
| The default behavior here is conservative; if the right-hand
| side is already coerced into a SQL type based on its
| Python type, it is usually left alone.
|
| End-user functionality extension here should generally be via
| :class:`.TypeDecorator`, which provides more liberal behavior in that
| it defaults to coercing the other side of the expression into this
| type, thus applying special Python conversions above and beyond those
| needed by the DBAPI to both ides. It also provides the public method
| :meth:`.TypeDecorator.coerce_compared_value` which is intended for
| end-user customization of this behavior.
|
| column_expression(self, colexpr: 'ColumnElement[_T]') -> 'Optional[ColumnElement[_T]]'
| Given a SELECT column expression, return a wrapping SQL expression.
|
| This is typically a SQL function that wraps a column expression
| as rendered in the columns clause of a SELECT statement.
| It is used for special data types that require
| columns to be wrapped in some special database function in order
| to coerce the value before being sent back to the application.
| It is the SQL analogue of the :meth:`.TypeEngine.result_processor`
| method.
|
| .. note:: The :func:`.TypeEngine.column_expression` method is applied
| only to the **outermost columns clause** of a SELECT statement, that
| is, the columns that are to be delivered directly into the returned
| result rows. It does **not** apply to the columns clause inside
| of subqueries. This necessarily avoids double conversions against
| the column and only runs the conversion when ready to be returned
| to the client.
|
| This method is called during the **SQL compilation** phase of a
| statement, when rendering a SQL string. It is **not** called
| against specific values.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.column_expression`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.column_expression`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.column_expression`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
|
| .. seealso::
|
| :ref:`types_sql_value_processing`
|
| compare_values(self, x: 'Any', y: 'Any') -> 'bool'
| Compare two values for equality.
|
| compile(self, dialect: 'Optional[Dialect]' = None) -> 'str'
| Produce a string-compiled form of this :class:`.TypeEngine`.
|
| When called with no arguments, uses a "default" dialect
| to produce a string result.
|
| :param dialect: a :class:`.Dialect` instance.
|
| copy(self, **kw: 'Any') -> 'Self'
|
| copy_value(self, value: 'Any') -> 'Any'
|
| dialect_impl(self, dialect: 'Dialect') -> 'TypeEngine[_T]'
| Return a dialect-specific implementation for this
| :class:`.TypeEngine`.
|
| evaluates_none(self) -> 'Self'
| Return a copy of this type which has the
| :attr:`.should_evaluate_none` flag set to True.
|
| E.g.::
|
| Table(
| "some_table",
| metadata,
| Column(
| String(50).evaluates_none(),
| nullable=True,
| server_default="no value",
| ),
| )
|
| The ORM uses this flag to indicate that a positive value of ``None``
| is passed to the column in an INSERT statement, rather than omitting
| the column from the INSERT statement which has the effect of firing
| off column-level defaults. It also allows for types which have
| special behavior associated with the Python None value to indicate
| that the value doesn't necessarily translate into SQL NULL; a
| prime example of this is a JSON type which may wish to persist the
| JSON value ``'null'``.
|
| In all cases, the actual NULL SQL value can be always be
| persisted in any column by using
| the :obj:`_expression.null` SQL construct in an INSERT statement
| or associated with an ORM-mapped attribute.
|
| .. note::
|
| The "evaluates none" flag does **not** apply to a value
| of ``None`` passed to :paramref:`_schema.Column.default` or
| :paramref:`_schema.Column.server_default`; in these cases,
| ``None``
| still means "no default".
|
| .. seealso::
|
| :ref:`session_forcing_null` - in the ORM documentation
|
| :paramref:`.postgresql.JSON.none_as_null` - PostgreSQL JSON
| interaction with this flag.
|
| :attr:`.TypeEngine.should_evaluate_none` - class-level flag
|
| with_variant(self, type_: '_TypeEngineArgument[Any]', *dialect_names: 'str') -> 'Self'
| Produce a copy of this type object that will utilize the given
| type when applied to the dialect of the given name.
|
| e.g.::
|
| from sqlalchemy.types import String
| from sqlalchemy.dialects import mysql
|
| string_type = String()
|
| string_type = string_type.with_variant(
| mysql.VARCHAR(collation="foo"), "mysql", "mariadb"
| )
|
| The variant mapping indicates that when this type is
| interpreted by a specific dialect, it will instead be
| transmuted into the given type, rather than using the
| primary type.
|
| .. versionchanged:: 2.0 the :meth:`_types.TypeEngine.with_variant`
| method now works with a :class:`_types.TypeEngine` object "in
| place", returning a copy of the original type rather than returning
| a wrapping object; the ``Variant`` class is no longer used.
|
| :param type\_: a :class:`.TypeEngine` that will be selected
| as a variant from the originating type, when a dialect
| of the given name is in use.
| :param \*dialect_names: one or more base names of the dialect which
| uses this type. (i.e. ``'postgresql'``, ``'mysql'``, etc.)
|
| .. versionchanged:: 2.0 multiple dialect names can be specified
| for one variant.
|
| .. seealso::
|
| :ref:`types_with_variant` - illustrates the use of
| :meth:`_types.TypeEngine.with_variant`.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.type_api.TypeEngine:
|
| __orig_bases__ = (<class 'sqlalchemy.sql.visitors.Visitable'>, typing....
|
| hashable = True
|
| render_bind_cast = False
|
| render_literal_cast = False
|
| should_evaluate_none = False
|
| sort_key_function = None
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.visitors.Visitable:
|
| __class_getitem__(key: 'Any') -> 'Any'
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__() -> 'None'
| This method is called when a class is subclassed.
|
| The default implementation does nothing. It may be
| overridden to extend subclasses.
sqlalchemy.CTE
Python Library Documentation: class CTE in module sqlalchemy.sql.selectable
class CTE(sqlalchemy.sql.roles.DMLTableRole, sqlalchemy.sql.roles.IsCTERole, sqlalchemy.sql.base.Generative, HasPrefixes, HasSuffixes, AliasedReturnsRows)
| CTE(*arg: 'Any', **kw: 'Any')
|
| Represent a Common Table Expression.
|
| The :class:`_expression.CTE` object is obtained using the
| :meth:`_sql.SelectBase.cte` method from any SELECT statement. A less often
| available syntax also allows use of the :meth:`_sql.HasCTE.cte` method
| present on :term:`DML` constructs such as :class:`_sql.Insert`,
| :class:`_sql.Update` and
| :class:`_sql.Delete`. See the :meth:`_sql.HasCTE.cte` method for
| usage details on CTEs.
|
| .. seealso::
|
| :ref:`tutorial_subqueries_ctes` - in the 2.0 tutorial
|
| :meth:`_sql.HasCTE.cte` - examples of calling styles
|
| Method resolution order:
| CTE
| sqlalchemy.sql.roles.DMLTableRole
| sqlalchemy.sql.roles.IsCTERole
| sqlalchemy.sql.base.Generative
| HasPrefixes
| HasSuffixes
| AliasedReturnsRows
| NoInit
| NamedFromClause
| FromClause
| sqlalchemy.sql.roles.AnonymizedFromClauseRole
| sqlalchemy.sql.roles.StrictFromClauseRole
| sqlalchemy.sql.roles.FromClauseRole
| sqlalchemy.sql.roles.ColumnsClauseRole
| sqlalchemy.sql.roles.JoinTargetRole
| sqlalchemy.sql.roles.AllowsLambdaRole
| sqlalchemy.sql.roles.UsesInspection
| sqlalchemy.sql.roles.ColumnListRole
| sqlalchemy.sql.roles.StructuralRole
| Selectable
| ReturnsRows
| sqlalchemy.sql.roles.ReturnsRowsRole
| sqlalchemy.sql.roles.SQLRole
| sqlalchemy.sql.elements.DQLDMLClauseElement
| sqlalchemy.sql.elements.ClauseElement
| sqlalchemy.sql.annotation.SupportsWrappingAnnotations
| sqlalchemy.sql.annotation.SupportsAnnotations
| sqlalchemy.sql.cache_key.MemoizedHasCacheKey
| sqlalchemy.sql.cache_key.HasCacheKey
| sqlalchemy.util.langhelpers.HasMemoized
| sqlalchemy.sql.traversals.HasCopyInternals
| sqlalchemy.sql.visitors.ExternallyTraversible
| sqlalchemy.sql.visitors.HasTraverseInternals
| sqlalchemy.sql.elements.CompilerElement
| sqlalchemy.sql.visitors.Visitable
| builtins.object
|
| Methods defined here:
|
| alias(self, name: 'Optional[str]' = None, flat: 'bool' = False) -> 'CTE'
| Return an :class:`_expression.Alias` of this
| :class:`_expression.CTE`.
|
| This method is a CTE-specific specialization of the
| :meth:`_expression.FromClause.alias` method.
|
| .. seealso::
|
| :ref:`tutorial_using_aliases`
|
| :func:`_expression.alias`
|
| union(self, *other: '_SelectStatementForCompoundArgument[Any]') -> 'CTE'
| Return a new :class:`_expression.CTE` with a SQL ``UNION``
| of the original CTE against the given selectables provided
| as positional arguments.
|
| :param \*other: one or more elements with which to create a
| UNION.
|
| .. versionchanged:: 1.4.28 multiple elements are now accepted.
|
| .. seealso::
|
| :meth:`_sql.HasCTE.cte` - examples of calling styles
|
| union_all(self, *other: '_SelectStatementForCompoundArgument[Any]') -> 'CTE'
| Return a new :class:`_expression.CTE` with a SQL ``UNION ALL``
| of the original CTE against the given selectables provided
| as positional arguments.
|
| :param \*other: one or more elements with which to create a
| UNION.
|
| .. versionchanged:: 1.4.28 multiple elements are now accepted.
|
| .. seealso::
|
| :meth:`_sql.HasCTE.cte` - examples of calling styles
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'_traverse_internals': '_TraverseInternalsType', 'e...
|
| __visit_name__ = 'cte'
|
| ----------------------------------------------------------------------
| Methods inherited from HasPrefixes:
|
| prefix_with(self, *prefixes: '_TextCoercedExpressionArgument[Any]', dialect: 'str' = '*') -> 'Self'
| 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.
|
| ----------------------------------------------------------------------
| Methods inherited from HasSuffixes:
|
| suffix_with(self, *suffixes: '_TextCoercedExpressionArgument[Any]', dialect: 'str' = '*') -> 'Self'
| 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.
|
| ----------------------------------------------------------------------
| Methods inherited from AliasedReturnsRows:
|
| description(...)
|
| implicit_returning(...)
|
| 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.
|
| ----------------------------------------------------------------------
| Readonly properties inherited from AliasedReturnsRows:
|
| original
| Legacy for dialects that are referring to Alias.original.
|
| ----------------------------------------------------------------------
| Methods inherited from NoInit:
|
| __init__(self, *arg: 'Any', **kw: 'Any')
| Initialize self. See help(type(self)) for accurate signature.
|
| ----------------------------------------------------------------------
| Methods inherited from NamedFromClause:
|
| table_valued(self) -> 'TableValuedColumn[Any]'
| Return a :class:`_sql.TableValuedColumn` object for this
| :class:`_expression.FromClause`.
|
| A :class:`_sql.TableValuedColumn` is a :class:`_sql.ColumnElement` that
| represents a complete row in a table. Support for this construct is
| backend dependent, and is supported in various forms by backends
| such as PostgreSQL, Oracle Database and SQL Server.
|
| E.g.:
|
| .. sourcecode:: pycon+sql
|
| >>> from sqlalchemy import select, column, func, table
| >>> a = table("a", column("id"), column("x"), column("y"))
| >>> stmt = select(func.row_to_json(a.table_valued()))
| >>> print(stmt)
| {printsql}SELECT row_to_json(a) AS row_to_json_1
| FROM a
|
| .. versionadded:: 1.4.0b2
|
| .. seealso::
|
| :ref:`tutorial_functions` - in the :ref:`unified_tutorial`
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from NamedFromClause:
|
| named_with_column = True
|
| ----------------------------------------------------------------------
| Methods inherited from FromClause:
|
| c(...)
| A synonym for :attr:`.FromClause.columns`
|
| :return: a :class:`.ColumnCollection`
|
| columns(...)
| 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.
|
| entity_namespace(...)
| 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.
|
| exported_columns(...)
| A :class:`_expression.ColumnCollection`
| that represents the "exported"
| columns of this :class:`_expression.Selectable`.
|
| 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`
|
| foreign_keys(...)
| Return the collection of :class:`_schema.ForeignKey` marker objects
| which this FromClause references.
|
| Each :class:`_schema.ForeignKey` is a member of a
| :class:`_schema.Table`-wide
| :class:`_schema.ForeignKeyConstraint`.
|
| .. seealso::
|
| :attr:`_schema.Table.foreign_key_constraints`
|
| 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
|
| 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`
|
| primary_key(...)
| 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.
|
| select(self) -> 'Select[Any]'
| 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.
|
| 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
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from FromClause:
|
| is_selectable = True
|
| schema = None
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.AllowsLambdaRole:
|
| allows_lambda = True
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.UsesInspection:
|
| uses_inspection = True
|
| ----------------------------------------------------------------------
| Methods inherited from Selectable:
|
| 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.
|
| 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.
|
| 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`.
|
| .. deprecated:: 1.4 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.
|
| ----------------------------------------------------------------------
| Readonly properties inherited from ReturnsRows:
|
| selectable
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.elements.ClauseElement:
|
| __bool__(self)
|
| __getstate__(self)
| Helper for pickle.
|
| __invert__(self)
|
| __repr__(self)
| Return repr(self).
|
| compare(self, other: 'ClauseElement', **kw: 'Any') -> 'bool'
| Compare this :class:`_expression.ClauseElement` to
| the given :class:`_expression.ClauseElement`.
|
| Subclasses should override the default behavior, which is a
| straight identity comparison.
|
| \**kw are arguments consumed by subclass ``compare()`` methods and
| may be used to modify the criteria for comparison
| (see :class:`_expression.ColumnElement`).
|
| params(self, _ClauseElement__optionaldict: 'Optional[Mapping[str, Any]]' = None, **kwargs: 'Any') -> 'Self'
| Return a copy with :func:`_expression.bindparam` elements
| replaced.
|
| Returns a copy of this ClauseElement with
| :func:`_expression.bindparam`
| elements replaced with values taken from the given dictionary::
|
| >>> clause = column("x") + bindparam("foo")
| >>> print(clause.compile().params)
| {'foo':None}
| >>> print(clause.params({"foo": 7}).compile().params)
| {'foo':7}
|
| self_group(self, against: 'Optional[OperatorType]' = None) -> 'ClauseElement'
| 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.
|
| unique_params(self, _ClauseElement__optionaldict: 'Optional[Dict[str, Any]]' = None, **kwargs: 'Any') -> 'Self'
| Return a copy with :func:`_expression.bindparam` elements
| replaced.
|
| Same functionality as :meth:`_expression.ClauseElement.params`,
| except adds `unique=True`
| to affected bind parameters so that multiple statements can be
| used.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.elements.ClauseElement:
|
| is_clause_element = True
|
| is_dml = False
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.cache_key.HasCacheKey:
|
| inherit_cache = None
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_instancemethod(fn: '_F') -> '_F'
| Decorate a method memoize its return value.
|
| :meta private:
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_attribute = <class 'sqlalchemy.util.langhelpers.HasMemoized.m...
| A read-only @property that is only evaluated once.
|
| :meta private:
|
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.visitors.HasTraverseInternals:
|
| get_children(self, *, omit_attrs: 'Tuple[str, ...]' = (), **kw: 'Any') -> 'Iterable[HasTraverseInternals]'
| Return immediate child :class:`.visitors.HasTraverseInternals`
| elements of this :class:`.visitors.HasTraverseInternals`.
|
| This is used for visit traversal.
|
| \**kw may contain flags that change the collection that is
| returned, for example to return a subset of items in order to
| cut down on larger traversals, or to return child items from a
| different context (such as schema-level collections instead of
| clause-level).
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.elements.CompilerElement:
|
| __str__(self) -> 'str'
| Return str(self).
|
| compile(self, bind: 'Optional[_HasDialect]' = None, dialect: 'Optional[Dialect]' = None, **kw: 'Any') -> 'Compiled'
| Compile this SQL expression.
|
| The return value is a :class:`~.Compiled` object.
| Calling ``str()`` or ``unicode()`` on the returned value will yield a
| string representation of the result. The
| :class:`~.Compiled` object also can return a
| dictionary of bind parameter names and values
| using the ``params`` accessor.
|
| :param bind: An :class:`.Connection` or :class:`.Engine` which
| can provide a :class:`.Dialect` in order to generate a
| :class:`.Compiled` object. If the ``bind`` and
| ``dialect`` parameters are both omitted, a default SQL compiler
| is used.
|
| :param column_keys: Used for INSERT and UPDATE statements, a list of
| column names which should be present in the VALUES clause of the
| compiled statement. If ``None``, all columns from the target table
| object are rendered.
|
| :param dialect: A :class:`.Dialect` instance which can generate
| a :class:`.Compiled` object. This argument takes precedence over
| the ``bind`` argument.
|
| :param compile_kwargs: optional dictionary of additional parameters
| that will be passed through to the compiler within all "visit"
| methods. This allows any custom flag to be passed through to
| a custom compilation construct, for example. It is also used
| for the case of passing the ``literal_binds`` flag through::
|
| from sqlalchemy.sql import table, column, select
|
| t = table("t", column("x"))
|
| s = select(t).where(t.c.x == 5)
|
| print(s.compile(compile_kwargs={"literal_binds": True}))
|
| .. seealso::
|
| :ref:`faq_sql_expression_string`
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.elements.CompilerElement:
|
| stringify_dialect = 'default'
|
| supports_execution = False
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.visitors.Visitable:
|
| __class_getitem__(key: 'Any') -> 'Any'
|
| __init_subclass__() -> 'None'
| This method is called when a class is subclassed.
|
| The default implementation does nothing. It may be
| overridden to extend subclasses.
sqlalchemy.CacheKey
Python Library Documentation: class CacheKey in module sqlalchemy.sql.cache_key
class CacheKey(builtins.tuple)
| CacheKey(key: ForwardRef('Tuple[Any, ...]'), bindparams: ForwardRef('Sequence[BindParameter[Any]]'))
|
| The key used to identify a SQL statement construct in the
| SQL compilation cache.
|
| .. seealso::
|
| :ref:`sql_caching`
|
| Method resolution order:
| CacheKey
| builtins.tuple
| builtins.object
|
| Methods defined here:
|
| __eq__(self, other: 'Any') -> 'bool'
| Return self==value.
|
| __getnewargs__(self) from collections.CacheKey
| Return self as a plain tuple. Used by copy and pickle.
|
| __hash__(self) -> 'Optional[int]'
| CacheKey itself is not hashable - hash the .key portion
|
| __ne__(self, other: 'Any') -> 'bool'
| Return self!=value.
|
| __repr__(self) from collections.CacheKey
| Return a nicely formatted representation string
|
| __str__(self) -> 'str'
| Return str(self).
|
| _apply_params_to_element(self, original_cache_key: 'CacheKey', target_element: 'ColumnElement[Any]') -> 'ColumnElement[Any]'
|
| _asdict(self) from collections.CacheKey
| Return a new dict which maps field names to their values.
|
| _diff(self, other: 'CacheKey') -> 'str'
|
| _generate_param_dict(self) -> 'Dict[str, Any]'
| used for testing
|
| _replace(self, /, **kwds) from collections.CacheKey
| Return a new CacheKey object replacing specified fields with new values
|
| _whats_different(self, other: 'CacheKey') -> 'Iterator[str]'
|
| to_offline_string(self, statement_cache: 'MutableMapping[Any, str]', statement: 'ClauseElement', parameters: '_CoreSingleExecuteParams') -> 'str'
| Generate an "offline string" form of this :class:`.CacheKey`
|
| The "offline string" is basically the string SQL for the
| statement plus a repr of the bound parameter values in series.
| Whereas the :class:`.CacheKey` object is dependent on in-memory
| identities in order to work as a cache key, the "offline" version
| is suitable for a cache that will work for other processes as well.
|
| The given ``statement_cache`` is a dictionary-like object where the
| string form of the statement itself will be cached. This dictionary
| should be in a longer lived scope in order to reduce the time spent
| stringifying statements.
|
| ----------------------------------------------------------------------
| Class methods defined here:
|
| _diff_tuples(left: 'CacheKey', right: 'CacheKey') -> 'str'
|
| _make(iterable) from collections.CacheKey
| Make a new CacheKey object from a sequence or iterable
|
| ----------------------------------------------------------------------
| Static methods defined here:
|
| __new__(_cls, key: ForwardRef('Tuple[Any, ...]'), bindparams: ForwardRef('Sequence[BindParameter[Any]]')) from namedtuple_CacheKey.CacheKey
| Create new instance of CacheKey(key, bindparams)
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| key
| Alias for field number 0
|
| bindparams
| Alias for field number 1
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'bindparams': ForwardRef('Sequence[BindParameter[An...
|
| __match_args__ = ('key', 'bindparams')
|
| __orig_bases__ = (<function NamedTuple>,)
|
| _field_defaults = {}
|
| _fields = ('key', 'bindparams')
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.tuple:
|
| __add__(self, value, /)
| Return self+value.
|
| __contains__(self, key, /)
| Return bool(key in self).
|
| __ge__(self, value, /)
| Return self>=value.
|
| __getattribute__(self, name, /)
| Return getattr(self, name).
|
| __getitem__(self, key, /)
| Return self[key].
|
| __gt__(self, value, /)
| Return self>value.
|
| __iter__(self, /)
| Implement iter(self).
|
| __le__(self, value, /)
| Return self<=value.
|
| __len__(self, /)
| Return len(self).
|
| __lt__(self, value, /)
| Return self<value.
|
| __mul__(self, value, /)
| Return self*value.
|
| __rmul__(self, value, /)
| Return value*self.
|
| count(self, value, /)
| Return number of occurrences of value.
|
| index(self, value, start=0, stop=9223372036854775807, /)
| Return first index of value.
|
| Raises ValueError if the value is not present.
|
| ----------------------------------------------------------------------
| Class methods inherited from builtins.tuple:
|
| __class_getitem__(...)
| See PEP 585
sqlalchemy.Case
Python Library Documentation: class Case in module sqlalchemy.sql.elements
class Case(ColumnElement)
| Case(*whens: 'Union[typing_Tuple[_ColumnExpressionArgument[bool], Any], Mapping[Any, Any]]', value: 'Optional[Any]' = None, else_: 'Optional[Any]' = None)
|
| Represent a ``CASE`` expression.
|
| :class:`.Case` is produced using the :func:`.case` factory function,
| as in::
|
| from sqlalchemy import case
|
| stmt = select(users_table).where(
| case(
| (users_table.c.name == "wendy", "W"),
| (users_table.c.name == "jack", "J"),
| else_="E",
| )
| )
|
| Details on :class:`.Case` usage is at :func:`.case`.
|
| .. seealso::
|
| :func:`.case`
|
| Method resolution order:
| Case
| ColumnElement
| sqlalchemy.sql.roles.ColumnArgumentOrKeyRole
| sqlalchemy.sql.roles.ColumnArgumentRole
| sqlalchemy.sql.roles.StatementOptionRole
| sqlalchemy.sql.roles.WhereHavingRole
| sqlalchemy.sql.roles.OnClauseRole
| sqlalchemy.sql.roles.BinaryElementRole
| sqlalchemy.sql.roles.OrderByRole
| sqlalchemy.sql.roles.ColumnsClauseRole
| sqlalchemy.sql.roles.AllowsLambdaRole
| sqlalchemy.sql.roles.ByOfRole
| sqlalchemy.sql.roles.UsesInspection
| sqlalchemy.sql.roles.ColumnListRole
| sqlalchemy.sql.roles.LimitOffsetRole
| sqlalchemy.sql.roles.DMLColumnRole
| sqlalchemy.sql.roles.DDLConstraintColumnRole
| sqlalchemy.sql.roles.DDLExpressionRole
| sqlalchemy.sql.roles.StructuralRole
| SQLColumnExpression
| SQLCoreOperations
| sqlalchemy.sql.roles.ExpressionElementRole
| sqlalchemy.sql.roles.TypedColumnsClauseRole
| typing.Generic
| sqlalchemy.sql.operators.ColumnOperators
| sqlalchemy.sql.operators.Operators
| sqlalchemy.util.langhelpers.TypingOnly
| sqlalchemy.sql.roles.SQLRole
| DQLDMLClauseElement
| ClauseElement
| sqlalchemy.sql.annotation.SupportsWrappingAnnotations
| sqlalchemy.sql.annotation.SupportsAnnotations
| sqlalchemy.sql.cache_key.MemoizedHasCacheKey
| sqlalchemy.sql.cache_key.HasCacheKey
| sqlalchemy.util.langhelpers.HasMemoized
| sqlalchemy.sql.traversals.HasCopyInternals
| sqlalchemy.sql.visitors.ExternallyTraversible
| sqlalchemy.sql.visitors.HasTraverseInternals
| CompilerElement
| sqlalchemy.sql.visitors.Visitable
| builtins.object
|
| Methods defined here:
|
| __init__(self, *whens: 'Union[typing_Tuple[_ColumnExpressionArgument[bool], Any], Mapping[Any, Any]]', value: 'Optional[Any]' = None, else_: 'Optional[Any]' = None)
| Initialize self. See help(type(self)) for accurate signature.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'_traverse_internals': '_TraverseInternalsType', 'e...
|
| __orig_bases__ = (sqlalchemy.sql.elements.ColumnElement[~_T],)
|
| __parameters__ = (~_T,)
|
| __visit_name__ = 'case'
|
| ----------------------------------------------------------------------
| Methods inherited from ColumnElement:
|
| __getattr__(self, key: 'str') -> 'Any'
|
| __setstate__(self, state)
|
| base_columns(...)
|
| cast(self, type_: '_TypeEngineArgument[_OPT]') -> 'Cast[_OPT]'
| Produce a type cast, i.e. ``CAST(<expression> AS <type>)``.
|
| This is a shortcut to the :func:`_expression.cast` function.
|
| .. seealso::
|
| :ref:`tutorial_casts`
|
| :func:`_expression.cast`
|
| :func:`_expression.type_coerce`
|
| comparator(...)
|
| label(self, name: 'Optional[str]') -> 'Label[_T]'
| Produce a column label, i.e. ``<columnname> AS <name>``.
|
| This is a shortcut to the :func:`_expression.label` function.
|
| If 'name' is ``None``, an anonymous label name will be generated.
|
| operate(self, op: 'operators.OperatorType', *other: 'Any', **kwargs: 'Any') -> 'ColumnElement[Any]'
| Operate on an argument.
|
| This is the lowest level of operation, raises
| :class:`NotImplementedError` by default.
|
| Overriding this on a subclass can allow common
| behavior to be applied to all operations.
| For example, overriding :class:`.ColumnOperators`
| to apply ``func.lower()`` to the left and right
| side::
|
| class MyComparator(ColumnOperators):
| def operate(self, op, other, **kwargs):
| return op(func.lower(self), func.lower(other), **kwargs)
|
| :param op: Operator callable.
| :param \*other: the 'other' side of the operation. Will
| be a single scalar for most operations.
| :param \**kwargs: modifiers. These may be passed by special
| operators such as :meth:`ColumnOperators.contains`.
|
| proxy_set(...)
| set of all columns we are proxying
|
| as of 2.0 this is explicitly deannotated columns. previously it was
| effectively deannotated columns but wasn't enforced. annotated
| columns should basically not go into sets if at all possible because
| their hashing behavior is very non-performant.
|
| reverse_operate(self, op: 'operators.OperatorType', other: 'Any', **kwargs: 'Any') -> 'ColumnElement[Any]'
| Reverse operate on an argument.
|
| Usage is the same as :meth:`operate`.
|
| self_group(self, against: 'Optional[OperatorType]' = None) -> 'ColumnElement[Any]'
| 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.
|
| shares_lineage(self, othercolumn: 'ColumnElement[Any]') -> 'bool'
| Return True if the given :class:`_expression.ColumnElement`
| has a common ancestor to this :class:`_expression.ColumnElement`.
|
| type(...)
|
| ----------------------------------------------------------------------
| Readonly properties inherited from ColumnElement:
|
| anon_key_label
| .. deprecated:: 1.4 The :attr:`_expression.ColumnElement.anon_key_label` attribute is now private, and the public accessor is deprecated.
|
| anon_label
| .. deprecated:: 1.4 The :attr:`_expression.ColumnElement.anon_label` attribute is now private, and the public accessor is deprecated.
|
| expression
| Return a column expression.
|
| Part of the inspection interface; returns self.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from ColumnElement:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from ColumnElement:
|
| foreign_keys = frozenset()
|
| key = None
|
| primary_key = False
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.AllowsLambdaRole:
|
| allows_lambda = True
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.UsesInspection:
|
| uses_inspection = True
|
| ----------------------------------------------------------------------
| Class methods inherited from typing.Generic:
|
| __class_getitem__(...)
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__(...)
| Function to initialize subclasses.
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.operators.ColumnOperators:
|
| __add__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``+`` operator.
|
| In a column context, produces the clause ``a + b``
| if the parent object has non-string affinity.
| If the parent object has a string affinity,
| produces the concatenation operator, ``a || b`` -
| see :meth:`.ColumnOperators.concat`.
|
| __contains__(self, other: 'Any') -> 'ColumnOperators'
|
| __eq__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``==`` operator.
|
| In a column context, produces the clause ``a = b``.
| If the target is ``None``, produces ``a IS NULL``.
|
| __floordiv__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``//`` operator.
|
| In a column context, produces the clause ``a / b``,
| which is the same as "truediv", but considers the result
| type to be integer.
|
| .. versionadded:: 2.0
|
| __ge__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``>=`` operator.
|
| In a column context, produces the clause ``a >= b``.
|
| __getitem__(self, index: 'Any') -> 'ColumnOperators'
| Implement the [] operator.
|
| This can be used by some database-specific types
| such as PostgreSQL ARRAY and HSTORE.
|
| __gt__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``>`` operator.
|
| In a column context, produces the clause ``a > b``.
|
| __hash__(self, /) from builtins.object
| Return hash(self).
|
| __le__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``<=`` operator.
|
| In a column context, produces the clause ``a <= b``.
|
| __lshift__(self, other: 'Any') -> 'ColumnOperators'
| implement the << operator.
|
| Not used by SQLAlchemy core, this is provided
| for custom operator systems which want to use
| << as an extension point.
|
| __lt__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``<`` operator.
|
| In a column context, produces the clause ``a < b``.
|
| __mod__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``%`` operator.
|
| In a column context, produces the clause ``a % b``.
|
| __mul__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``*`` operator.
|
| In a column context, produces the clause ``a * b``.
|
| __ne__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``!=`` operator.
|
| In a column context, produces the clause ``a != b``.
| If the target is ``None``, produces ``a IS NOT NULL``.
|
| __neg__(self) -> 'ColumnOperators'
| Implement the ``-`` operator.
|
| In a column context, produces the clause ``-a``.
|
| __radd__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``+`` operator in reverse.
|
| See :meth:`.ColumnOperators.__add__`.
|
| __rfloordiv__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``//`` operator in reverse.
|
| See :meth:`.ColumnOperators.__floordiv__`.
|
| __rmod__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``%`` operator in reverse.
|
| See :meth:`.ColumnOperators.__mod__`.
|
| __rmul__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``*`` operator in reverse.
|
| See :meth:`.ColumnOperators.__mul__`.
|
| __rshift__(self, other: 'Any') -> 'ColumnOperators'
| implement the >> operator.
|
| Not used by SQLAlchemy core, this is provided
| for custom operator systems which want to use
| >> as an extension point.
|
| __rsub__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``-`` operator in reverse.
|
| See :meth:`.ColumnOperators.__sub__`.
|
| __rtruediv__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``/`` operator in reverse.
|
| See :meth:`.ColumnOperators.__truediv__`.
|
| __sub__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``-`` operator.
|
| In a column context, produces the clause ``a - b``.
|
| __truediv__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``/`` operator.
|
| In a column context, produces the clause ``a / b``, and
| considers the result type to be numeric.
|
| .. versionchanged:: 2.0 The truediv operator against two integers
| is now considered to return a numeric value. Behavior on specific
| backends may vary.
|
| all_(self) -> 'ColumnOperators'
| Produce an :func:`_expression.all_` clause against the
| parent object.
|
| See the documentation for :func:`_sql.all_` for examples.
|
| .. note:: be sure to not confuse the newer
| :meth:`_sql.ColumnOperators.all_` method with the **legacy**
| version of this method, the :meth:`_types.ARRAY.Comparator.all`
| method that's specific to :class:`_types.ARRAY`, which uses a
| different calling style.
|
| any_(self) -> 'ColumnOperators'
| Produce an :func:`_expression.any_` clause against the
| parent object.
|
| See the documentation for :func:`_sql.any_` for examples.
|
| .. note:: be sure to not confuse the newer
| :meth:`_sql.ColumnOperators.any_` method with the **legacy**
| version of this method, the :meth:`_types.ARRAY.Comparator.any`
| method that's specific to :class:`_types.ARRAY`, which uses a
| different calling style.
|
| asc(self) -> 'ColumnOperators'
| Produce a :func:`_expression.asc` clause against the
| parent object.
|
| between(self, cleft: 'Any', cright: 'Any', symmetric: 'bool' = False) -> 'ColumnOperators'
| Produce a :func:`_expression.between` clause against
| the parent object, given the lower and upper range.
|
| bitwise_and(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise AND operation, typically via the ``&``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_lshift(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise LSHIFT operation, typically via the ``<<``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_not(self) -> 'ColumnOperators'
| Produce a bitwise NOT operation, typically via the ``~``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_or(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise OR operation, typically via the ``|``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_rshift(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise RSHIFT operation, typically via the ``>>``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_xor(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise XOR operation, typically via the ``^``
| operator, or ``#`` for PostgreSQL.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| collate(self, collation: 'str') -> 'ColumnOperators'
| Produce a :func:`_expression.collate` clause against
| the parent object, given the collation string.
|
| .. seealso::
|
| :func:`_expression.collate`
|
| concat(self, other: 'Any') -> 'ColumnOperators'
| Implement the 'concat' operator.
|
| In a column context, produces the clause ``a || b``,
| or uses the ``concat()`` operator on MySQL.
|
| contains(self, other: 'Any', **kw: 'Any') -> 'ColumnOperators'
| Implement the 'contains' operator.
|
| Produces a LIKE expression that tests against a match for the middle
| of a string value:
|
| .. sourcecode:: sql
|
| column LIKE '%' || <other> || '%'
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.contains("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.contains.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.contains.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.contains.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.contains("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE '%' || :param || '%' ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.contains("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE '%' || :param || '%' ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.contains.autoescape`::
|
| somecolumn.contains("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.startswith`
|
| :meth:`.ColumnOperators.endswith`
|
| :meth:`.ColumnOperators.like`
|
| desc(self) -> 'ColumnOperators'
| Produce a :func:`_expression.desc` clause against the
| parent object.
|
| distinct(self) -> 'ColumnOperators'
| Produce a :func:`_expression.distinct` clause against the
| parent object.
|
| endswith(self, other: 'Any', escape: 'Optional[str]' = None, autoescape: 'bool' = False) -> 'ColumnOperators'
| Implement the 'endswith' operator.
|
| Produces a LIKE expression that tests against a match for the end
| of a string value:
|
| .. sourcecode:: sql
|
| column LIKE '%' || <other>
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.endswith("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.endswith.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.endswith.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.endswith.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.endswith("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE '%' || :param ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.endswith("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE '%' || :param ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.endswith.autoescape`::
|
| somecolumn.endswith("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.startswith`
|
| :meth:`.ColumnOperators.contains`
|
| :meth:`.ColumnOperators.like`
|
| icontains(self, other: 'Any', **kw: 'Any') -> 'ColumnOperators'
| Implement the ``icontains`` operator, e.g. case insensitive
| version of :meth:`.ColumnOperators.contains`.
|
| Produces a LIKE expression that tests against an insensitive match
| for the middle of a string value:
|
| .. sourcecode:: sql
|
| lower(column) LIKE '%' || lower(<other>) || '%'
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.icontains("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.icontains.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.icontains.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.icontains.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.icontains("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE '%' || lower(:param) || '%' ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.icontains("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE '%' || lower(:param) || '%' ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.contains.autoescape`::
|
| somecolumn.icontains("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.contains`
|
| iendswith(self, other: 'Any', escape: 'Optional[str]' = None, autoescape: 'bool' = False) -> 'ColumnOperators'
| Implement the ``iendswith`` operator, e.g. case insensitive
| version of :meth:`.ColumnOperators.endswith`.
|
| Produces a LIKE expression that tests against an insensitive match
| for the end of a string value:
|
| .. sourcecode:: sql
|
| lower(column) LIKE '%' || lower(<other>)
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.iendswith("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.iendswith.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.iendswith.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.iendswith.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.iendswith("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE '%' || lower(:param) ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.iendswith("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE '%' || lower(:param) ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.iendswith.autoescape`::
|
| somecolumn.endswith("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.endswith`
|
| ilike(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
| Implement the ``ilike`` operator, e.g. case insensitive LIKE.
|
| In a column context, produces an expression either of the form:
|
| .. sourcecode:: sql
|
| lower(a) LIKE lower(other)
|
| Or on backends that support the ILIKE operator:
|
| .. sourcecode:: sql
|
| a ILIKE other
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.ilike("%foobar%"))
|
| :param other: expression to be compared
| :param escape: optional escape character, renders the ``ESCAPE``
| keyword, e.g.::
|
| somecolumn.ilike("foo/%bar", escape="/")
|
| .. seealso::
|
| :meth:`.ColumnOperators.like`
|
| in_(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``in`` operator.
|
| In a column context, produces the clause ``column IN <other>``.
|
| The given parameter ``other`` may be:
|
| * A list of literal values,
| e.g.::
|
| stmt.where(column.in_([1, 2, 3]))
|
| In this calling form, the list of items is converted to a set of
| bound parameters the same length as the list given:
|
| .. sourcecode:: sql
|
| WHERE COL IN (?, ?, ?)
|
| * A list of tuples may be provided if the comparison is against a
| :func:`.tuple_` containing multiple expressions::
|
| from sqlalchemy import tuple_
|
| stmt.where(tuple_(col1, col2).in_([(1, 10), (2, 20), (3, 30)]))
|
| * An empty list,
| e.g.::
|
| stmt.where(column.in_([]))
|
| In this calling form, the expression renders an "empty set"
| expression. These expressions are tailored to individual backends
| and are generally trying to get an empty SELECT statement as a
| subquery. Such as on SQLite, the expression is:
|
| .. sourcecode:: sql
|
| WHERE col IN (SELECT 1 FROM (SELECT 1) WHERE 1!=1)
|
| .. versionchanged:: 1.4 empty IN expressions now use an
| execution-time generated SELECT subquery in all cases.
|
| * A bound parameter, e.g. :func:`.bindparam`, may be used if it
| includes the :paramref:`.bindparam.expanding` flag::
|
| stmt.where(column.in_(bindparam("value", expanding=True)))
|
| In this calling form, the expression renders a special non-SQL
| placeholder expression that looks like:
|
| .. sourcecode:: sql
|
| WHERE COL IN ([EXPANDING_value])
|
| This placeholder expression is intercepted at statement execution
| time to be converted into the variable number of bound parameter
| form illustrated earlier. If the statement were executed as::
|
| connection.execute(stmt, {"value": [1, 2, 3]})
|
| The database would be passed a bound parameter for each value:
|
| .. sourcecode:: sql
|
| WHERE COL IN (?, ?, ?)
|
| .. versionadded:: 1.2 added "expanding" bound parameters
|
| If an empty list is passed, a special "empty list" expression,
| which is specific to the database in use, is rendered. On
| SQLite this would be:
|
| .. sourcecode:: sql
|
| WHERE COL IN (SELECT 1 FROM (SELECT 1) WHERE 1!=1)
|
| .. versionadded:: 1.3 "expanding" bound parameters now support
| empty lists
|
| * a :func:`_expression.select` construct, which is usually a
| correlated scalar select::
|
| stmt.where(
| column.in_(select(othertable.c.y).where(table.c.x == othertable.c.x))
| )
|
| In this calling form, :meth:`.ColumnOperators.in_` renders as given:
|
| .. sourcecode:: sql
|
| WHERE COL IN (SELECT othertable.y
| FROM othertable WHERE othertable.x = table.x)
|
| :param other: a list of literals, a :func:`_expression.select`
| construct, or a :func:`.bindparam` construct that includes the
| :paramref:`.bindparam.expanding` flag set to True.
|
| is_(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``IS`` operator.
|
| Normally, ``IS`` is generated automatically when comparing to a
| value of ``None``, which resolves to ``NULL``. However, explicit
| usage of ``IS`` may be desirable if comparing to boolean values
| on certain platforms.
|
| .. seealso:: :meth:`.ColumnOperators.is_not`
|
| is_distinct_from(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``IS DISTINCT FROM`` operator.
|
| Renders "a IS DISTINCT FROM b" on most platforms;
| on some such as SQLite may render "a IS NOT b".
|
| is_not(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``IS NOT`` operator.
|
| Normally, ``IS NOT`` is generated automatically when comparing to a
| value of ``None``, which resolves to ``NULL``. However, explicit
| usage of ``IS NOT`` may be desirable if comparing to boolean values
| on certain platforms.
|
| .. versionchanged:: 1.4 The ``is_not()`` operator is renamed from
| ``isnot()`` in previous releases. The previous name remains
| available for backwards compatibility.
|
| .. seealso:: :meth:`.ColumnOperators.is_`
|
| is_not_distinct_from(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``IS NOT DISTINCT FROM`` operator.
|
| Renders "a IS NOT DISTINCT FROM b" on most platforms;
| on some such as SQLite may render "a IS b".
|
| .. versionchanged:: 1.4 The ``is_not_distinct_from()`` operator is
| renamed from ``isnot_distinct_from()`` in previous releases.
| The previous name remains available for backwards compatibility.
|
| isnot = is_not(self, other: 'Any') -> 'ColumnOperators'
|
| isnot_distinct_from = is_not_distinct_from(self, other: 'Any') -> 'ColumnOperators'
|
| istartswith(self, other: 'Any', escape: 'Optional[str]' = None, autoescape: 'bool' = False) -> 'ColumnOperators'
| Implement the ``istartswith`` operator, e.g. case insensitive
| version of :meth:`.ColumnOperators.startswith`.
|
| Produces a LIKE expression that tests against an insensitive
| match for the start of a string value:
|
| .. sourcecode:: sql
|
| lower(column) LIKE lower(<other>) || '%'
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.istartswith("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.istartswith.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.istartswith.escape` parameter will
| establish a given character as an escape character which can be of
| use when the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.istartswith.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.istartswith("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE lower(:param) || '%' ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.istartswith("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE lower(:param) || '%' ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.istartswith.autoescape`::
|
| somecolumn.istartswith("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.startswith`
|
| like(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
| Implement the ``like`` operator.
|
| In a column context, produces the expression:
|
| .. sourcecode:: sql
|
| a LIKE other
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.like("%foobar%"))
|
| :param other: expression to be compared
| :param escape: optional escape character, renders the ``ESCAPE``
| keyword, e.g.::
|
| somecolumn.like("foo/%bar", escape="/")
|
| .. seealso::
|
| :meth:`.ColumnOperators.ilike`
|
| match(self, other: 'Any', **kwargs: 'Any') -> 'ColumnOperators'
| Implements a database-specific 'match' operator.
|
| :meth:`_sql.ColumnOperators.match` attempts to resolve to
| a MATCH-like function or operator provided by the backend.
| Examples include:
|
| * PostgreSQL - renders ``x @@ plainto_tsquery(y)``
|
| .. versionchanged:: 2.0 ``plainto_tsquery()`` is used instead
| of ``to_tsquery()`` for PostgreSQL now; for compatibility with
| other forms, see :ref:`postgresql_match`.
|
|
| * MySQL - renders ``MATCH (x) AGAINST (y IN BOOLEAN MODE)``
|
| .. seealso::
|
| :class:`_mysql.match` - MySQL specific construct with
| additional features.
|
| * Oracle Database - renders ``CONTAINS(x, y)``
| * other backends may provide special implementations.
| * Backends without any special implementation will emit
| the operator as "MATCH". This is compatible with SQLite, for
| example.
|
| not_ilike(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
| implement the ``NOT ILIKE`` operator.
|
| This is equivalent to using negation with
| :meth:`.ColumnOperators.ilike`, i.e. ``~x.ilike(y)``.
|
| .. versionchanged:: 1.4 The ``not_ilike()`` operator is renamed from
| ``notilike()`` in previous releases. The previous name remains
| available for backwards compatibility.
|
| .. seealso::
|
| :meth:`.ColumnOperators.ilike`
|
| not_in(self, other: 'Any') -> 'ColumnOperators'
| implement the ``NOT IN`` operator.
|
| This is equivalent to using negation with
| :meth:`.ColumnOperators.in_`, i.e. ``~x.in_(y)``.
|
| In the case that ``other`` is an empty sequence, the compiler
| produces an "empty not in" expression. This defaults to the
| expression "1 = 1" to produce true in all cases. The
| :paramref:`_sa.create_engine.empty_in_strategy` may be used to
| alter this behavior.
|
| .. versionchanged:: 1.4 The ``not_in()`` operator is renamed from
| ``notin_()`` in previous releases. The previous name remains
| available for backwards compatibility.
|
| .. versionchanged:: 1.2 The :meth:`.ColumnOperators.in_` and
| :meth:`.ColumnOperators.not_in` operators
| now produce a "static" expression for an empty IN sequence
| by default.
|
| .. seealso::
|
| :meth:`.ColumnOperators.in_`
|
| not_like(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
| implement the ``NOT LIKE`` operator.
|
| This is equivalent to using negation with
| :meth:`.ColumnOperators.like`, i.e. ``~x.like(y)``.
|
| .. versionchanged:: 1.4 The ``not_like()`` operator is renamed from
| ``notlike()`` in previous releases. The previous name remains
| available for backwards compatibility.
|
| .. seealso::
|
| :meth:`.ColumnOperators.like`
|
| notilike = not_ilike(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
|
| notin_ = not_in(self, other: 'Any') -> 'ColumnOperators'
|
| notlike = not_like(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
|
| nulls_first(self) -> 'ColumnOperators'
| Produce a :func:`_expression.nulls_first` clause against the
| parent object.
|
| .. versionchanged:: 1.4 The ``nulls_first()`` operator is
| renamed from ``nullsfirst()`` in previous releases.
| The previous name remains available for backwards compatibility.
|
| nulls_last(self) -> 'ColumnOperators'
| Produce a :func:`_expression.nulls_last` clause against the
| parent object.
|
| .. versionchanged:: 1.4 The ``nulls_last()`` operator is
| renamed from ``nullslast()`` in previous releases.
| The previous name remains available for backwards compatibility.
|
| nullsfirst = nulls_first(self) -> 'ColumnOperators'
|
| nullslast = nulls_last(self) -> 'ColumnOperators'
|
| regexp_match(self, pattern: 'Any', flags: 'Optional[str]' = None) -> 'ColumnOperators'
| Implements a database-specific 'regexp match' operator.
|
| E.g.::
|
| stmt = select(table.c.some_column).where(
| table.c.some_column.regexp_match("^(b|c)")
| )
|
| :meth:`_sql.ColumnOperators.regexp_match` attempts to resolve to
| a REGEXP-like function or operator provided by the backend, however
| the specific regular expression syntax and flags available are
| **not backend agnostic**.
|
| Examples include:
|
| * PostgreSQL - renders ``x ~ y`` or ``x !~ y`` when negated.
| * Oracle Database - renders ``REGEXP_LIKE(x, y)``
| * SQLite - uses SQLite's ``REGEXP`` placeholder operator and calls into
| the Python ``re.match()`` builtin.
| * other backends may provide special implementations.
| * Backends without any special implementation will emit
| the operator as "REGEXP" or "NOT REGEXP". This is compatible with
| SQLite and MySQL, for example.
|
| Regular expression support is currently implemented for Oracle
| Database, PostgreSQL, MySQL and MariaDB. Partial support is available
| for SQLite. Support among third-party dialects may vary.
|
| :param pattern: The regular expression pattern string or column
| clause.
| :param flags: Any regular expression string flags to apply, passed as
| plain Python string only. These flags are backend specific.
| Some backends, like PostgreSQL and MariaDB, may alternatively
| specify the flags as part of the pattern.
| When using the ignore case flag 'i' in PostgreSQL, the ignore case
| regexp match operator ``~*`` or ``!~*`` will be used.
|
| .. versionadded:: 1.4
|
| .. versionchanged:: 1.4.48, 2.0.18 Note that due to an implementation
| error, the "flags" parameter previously accepted SQL expression
| objects such as column expressions in addition to plain Python
| strings. This implementation did not work correctly with caching
| and was removed; strings only should be passed for the "flags"
| parameter, as these flags are rendered as literal inline values
| within SQL expressions.
|
| .. seealso::
|
| :meth:`_sql.ColumnOperators.regexp_replace`
|
| regexp_replace(self, pattern: 'Any', replacement: 'Any', flags: 'Optional[str]' = None) -> 'ColumnOperators'
| Implements a database-specific 'regexp replace' operator.
|
| E.g.::
|
| stmt = select(
| table.c.some_column.regexp_replace("b(..)", "XY", flags="g")
| )
|
| :meth:`_sql.ColumnOperators.regexp_replace` attempts to resolve to
| a REGEXP_REPLACE-like function provided by the backend, that
| usually emit the function ``REGEXP_REPLACE()``. However,
| the specific regular expression syntax and flags available are
| **not backend agnostic**.
|
| Regular expression replacement support is currently implemented for
| Oracle Database, PostgreSQL, MySQL 8 or greater and MariaDB. Support
| among third-party dialects may vary.
|
| :param pattern: The regular expression pattern string or column
| clause.
| :param pattern: The replacement string or column clause.
| :param flags: Any regular expression string flags to apply, passed as
| plain Python string only. These flags are backend specific.
| Some backends, like PostgreSQL and MariaDB, may alternatively
| specify the flags as part of the pattern.
|
| .. versionadded:: 1.4
|
| .. versionchanged:: 1.4.48, 2.0.18 Note that due to an implementation
| error, the "flags" parameter previously accepted SQL expression
| objects such as column expressions in addition to plain Python
| strings. This implementation did not work correctly with caching
| and was removed; strings only should be passed for the "flags"
| parameter, as these flags are rendered as literal inline values
| within SQL expressions.
|
|
| .. seealso::
|
| :meth:`_sql.ColumnOperators.regexp_match`
|
| startswith(self, other: 'Any', escape: 'Optional[str]' = None, autoescape: 'bool' = False) -> 'ColumnOperators'
| Implement the ``startswith`` operator.
|
| Produces a LIKE expression that tests against a match for the start
| of a string value:
|
| .. sourcecode:: sql
|
| column LIKE <other> || '%'
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.startswith("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.startswith.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.startswith.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.startswith.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.startswith("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE :param || '%' ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.startswith("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE :param || '%' ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.startswith.autoescape`::
|
| somecolumn.startswith("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.endswith`
|
| :meth:`.ColumnOperators.contains`
|
| :meth:`.ColumnOperators.like`
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.operators.ColumnOperators:
|
| timetuple = None
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.operators.Operators:
|
| __and__(self, other: 'Any') -> 'Operators'
| Implement the ``&`` operator.
|
| When used with SQL expressions, results in an
| AND operation, equivalent to
| :func:`_expression.and_`, that is::
|
| a & b
|
| is equivalent to::
|
| from sqlalchemy import and_
|
| and_(a, b)
|
| Care should be taken when using ``&`` regarding
| operator precedence; the ``&`` operator has the highest precedence.
| The operands should be enclosed in parenthesis if they contain
| further sub expressions::
|
| (a == 2) & (b == 4)
|
| __invert__(self) -> 'Operators'
| Implement the ``~`` operator.
|
| When used with SQL expressions, results in a
| NOT operation, equivalent to
| :func:`_expression.not_`, that is::
|
| ~a
|
| is equivalent to::
|
| from sqlalchemy import not_
|
| not_(a)
|
| __or__(self, other: 'Any') -> 'Operators'
| Implement the ``|`` operator.
|
| When used with SQL expressions, results in an
| OR operation, equivalent to
| :func:`_expression.or_`, that is::
|
| a | b
|
| is equivalent to::
|
| from sqlalchemy import or_
|
| or_(a, b)
|
| Care should be taken when using ``|`` regarding
| operator precedence; the ``|`` operator has the highest precedence.
| The operands should be enclosed in parenthesis if they contain
| further sub expressions::
|
| (a == 2) | (b == 4)
|
| __sa_operate__ = operate(self, op: 'OperatorType', *other: 'Any', **kwargs: 'Any') -> 'Operators'
| Operate on an argument.
|
| This is the lowest level of operation, raises
| :class:`NotImplementedError` by default.
|
| Overriding this on a subclass can allow common
| behavior to be applied to all operations.
| For example, overriding :class:`.ColumnOperators`
| to apply ``func.lower()`` to the left and right
| side::
|
| class MyComparator(ColumnOperators):
| def operate(self, op, other, **kwargs):
| return op(func.lower(self), func.lower(other), **kwargs)
|
| :param op: Operator callable.
| :param \*other: the 'other' side of the operation. Will
| be a single scalar for most operations.
| :param \**kwargs: modifiers. These may be passed by special
| operators such as :meth:`ColumnOperators.contains`.
|
| bool_op(self, opstring: 'str', precedence: 'int' = 0, python_impl: 'Optional[Callable[..., Any]]' = None) -> 'Callable[[Any], Operators]'
| Return a custom boolean operator.
|
| This method is shorthand for calling
| :meth:`.Operators.op` and passing the
| :paramref:`.Operators.op.is_comparison`
| flag with True. A key advantage to using :meth:`.Operators.bool_op`
| is that when using column constructs, the "boolean" nature of the
| returned expression will be present for :pep:`484` purposes.
|
| .. seealso::
|
| :meth:`.Operators.op`
|
| op(self, opstring: 'str', precedence: 'int' = 0, is_comparison: 'bool' = False, return_type: 'Optional[Union[Type[TypeEngine[Any]], TypeEngine[Any]]]' = None, python_impl: 'Optional[Callable[..., Any]]' = None) -> 'Callable[[Any], Operators]'
| Produce a generic operator function.
|
| e.g.::
|
| somecolumn.op("*")(5)
|
| produces::
|
| somecolumn * 5
|
| This function can also be used to make bitwise operators explicit. For
| example::
|
| somecolumn.op("&")(0xFF)
|
| is a bitwise AND of the value in ``somecolumn``.
|
| :param opstring: a string which will be output as the infix operator
| between this element and the expression passed to the
| generated function.
|
| :param precedence: precedence which the database is expected to apply
| to the operator in SQL expressions. This integer value acts as a hint
| for the SQL compiler to know when explicit parenthesis should be
| rendered around a particular operation. A lower number will cause the
| expression to be parenthesized when applied against another operator
| with higher precedence. The default value of ``0`` is lower than all
| operators except for the comma (``,``) and ``AS`` operators. A value
| of 100 will be higher or equal to all operators, and -100 will be
| lower than or equal to all operators.
|
| .. seealso::
|
| :ref:`faq_sql_expression_op_parenthesis` - detailed description
| of how the SQLAlchemy SQL compiler renders parenthesis
|
| :param is_comparison: legacy; if True, the operator will be considered
| as a "comparison" operator, that is which evaluates to a boolean
| true/false value, like ``==``, ``>``, etc. This flag is provided
| so that ORM relationships can establish that the operator is a
| comparison operator when used in a custom join condition.
|
| Using the ``is_comparison`` parameter is superseded by using the
| :meth:`.Operators.bool_op` method instead; this more succinct
| operator sets this parameter automatically, but also provides
| correct :pep:`484` typing support as the returned object will
| express a "boolean" datatype, i.e. ``BinaryExpression[bool]``.
|
| :param return_type: a :class:`.TypeEngine` class or object that will
| force the return type of an expression produced by this operator
| to be of that type. By default, operators that specify
| :paramref:`.Operators.op.is_comparison` will resolve to
| :class:`.Boolean`, and those that do not will be of the same
| type as the left-hand operand.
|
| :param python_impl: an optional Python function that can evaluate
| two Python values in the same way as this operator works when
| run on the database server. Useful for in-Python SQL expression
| evaluation functions, such as for ORM hybrid attributes, and the
| ORM "evaluator" used to match objects in a session after a multi-row
| update or delete.
|
| e.g.::
|
| >>> expr = column("x").op("+", python_impl=lambda a, b: a + b)("y")
|
| The operator for the above expression will also work for non-SQL
| left and right objects::
|
| >>> expr.operator(5, 10)
| 15
|
| .. versionadded:: 2.0
|
|
| .. seealso::
|
| :meth:`.Operators.bool_op`
|
| :ref:`types_operators`
|
| :ref:`relationship_custom_operator`
|
| ----------------------------------------------------------------------
| Methods inherited from ClauseElement:
|
| __bool__(self)
|
| __getstate__(self)
| Helper for pickle.
|
| __repr__(self)
| Return repr(self).
|
| compare(self, other: 'ClauseElement', **kw: 'Any') -> 'bool'
| Compare this :class:`_expression.ClauseElement` to
| the given :class:`_expression.ClauseElement`.
|
| Subclasses should override the default behavior, which is a
| straight identity comparison.
|
| \**kw are arguments consumed by subclass ``compare()`` methods and
| may be used to modify the criteria for comparison
| (see :class:`_expression.ColumnElement`).
|
| description(...)
|
| entity_namespace(...)
|
| params(self, _ClauseElement__optionaldict: 'Optional[Mapping[str, Any]]' = None, **kwargs: 'Any') -> 'Self'
| Return a copy with :func:`_expression.bindparam` elements
| replaced.
|
| Returns a copy of this ClauseElement with
| :func:`_expression.bindparam`
| elements replaced with values taken from the given dictionary::
|
| >>> clause = column("x") + bindparam("foo")
| >>> print(clause.compile().params)
| {'foo':None}
| >>> print(clause.params({"foo": 7}).compile().params)
| {'foo':7}
|
| unique_params(self, _ClauseElement__optionaldict: 'Optional[Dict[str, Any]]' = None, **kwargs: 'Any') -> 'Self'
| Return a copy with :func:`_expression.bindparam` elements
| replaced.
|
| Same functionality as :meth:`_expression.ClauseElement.params`,
| except adds `unique=True`
| to affected bind parameters so that multiple statements can be
| used.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from ClauseElement:
|
| is_clause_element = True
|
| is_dml = False
|
| is_selectable = False
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.cache_key.HasCacheKey:
|
| inherit_cache = None
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_instancemethod(fn: '_F') -> '_F'
| Decorate a method memoize its return value.
|
| :meta private:
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_attribute = <class 'sqlalchemy.util.langhelpers.HasMemoized.m...
| A read-only @property that is only evaluated once.
|
| :meta private:
|
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.visitors.HasTraverseInternals:
|
| get_children(self, *, omit_attrs: 'Tuple[str, ...]' = (), **kw: 'Any') -> 'Iterable[HasTraverseInternals]'
| Return immediate child :class:`.visitors.HasTraverseInternals`
| elements of this :class:`.visitors.HasTraverseInternals`.
|
| This is used for visit traversal.
|
| \**kw may contain flags that change the collection that is
| returned, for example to return a subset of items in order to
| cut down on larger traversals, or to return child items from a
| different context (such as schema-level collections instead of
| clause-level).
|
| ----------------------------------------------------------------------
| Methods inherited from CompilerElement:
|
| __str__(self) -> 'str'
| Return str(self).
|
| compile(self, bind: 'Optional[_HasDialect]' = None, dialect: 'Optional[Dialect]' = None, **kw: 'Any') -> 'Compiled'
| Compile this SQL expression.
|
| The return value is a :class:`~.Compiled` object.
| Calling ``str()`` or ``unicode()`` on the returned value will yield a
| string representation of the result. The
| :class:`~.Compiled` object also can return a
| dictionary of bind parameter names and values
| using the ``params`` accessor.
|
| :param bind: An :class:`.Connection` or :class:`.Engine` which
| can provide a :class:`.Dialect` in order to generate a
| :class:`.Compiled` object. If the ``bind`` and
| ``dialect`` parameters are both omitted, a default SQL compiler
| is used.
|
| :param column_keys: Used for INSERT and UPDATE statements, a list of
| column names which should be present in the VALUES clause of the
| compiled statement. If ``None``, all columns from the target table
| object are rendered.
|
| :param dialect: A :class:`.Dialect` instance which can generate
| a :class:`.Compiled` object. This argument takes precedence over
| the ``bind`` argument.
|
| :param compile_kwargs: optional dictionary of additional parameters
| that will be passed through to the compiler within all "visit"
| methods. This allows any custom flag to be passed through to
| a custom compilation construct, for example. It is also used
| for the case of passing the ``literal_binds`` flag through::
|
| from sqlalchemy.sql import table, column, select
|
| t = table("t", column("x"))
|
| s = select(t).where(t.c.x == 5)
|
| print(s.compile(compile_kwargs={"literal_binds": True}))
|
| .. seealso::
|
| :ref:`faq_sql_expression_string`
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from CompilerElement:
|
| stringify_dialect = 'default'
|
| supports_execution = False
sqlalchemy.Cast
Python Library Documentation: class Cast in module sqlalchemy.sql.elements
class Cast(WrapsColumnExpression)
| Cast(expression: '_ColumnExpressionArgument[Any]', type_: '_TypeEngineArgument[_T]')
|
| Represent a ``CAST`` expression.
|
| :class:`.Cast` is produced using the :func:`.cast` factory function,
| as in::
|
| from sqlalchemy import cast, Numeric
|
| stmt = select(cast(product_table.c.unit_price, Numeric(10, 4)))
|
| Details on :class:`.Cast` usage is at :func:`.cast`.
|
| .. seealso::
|
| :ref:`tutorial_casts`
|
| :func:`.cast`
|
| :func:`.try_cast`
|
| :func:`.type_coerce` - an alternative to CAST that coerces the type
| on the Python side only, which is often sufficient to generate the
| correct SQL and data coercion.
|
| Method resolution order:
| Cast
| WrapsColumnExpression
| ColumnElement
| sqlalchemy.sql.roles.ColumnArgumentOrKeyRole
| sqlalchemy.sql.roles.ColumnArgumentRole
| sqlalchemy.sql.roles.StatementOptionRole
| sqlalchemy.sql.roles.WhereHavingRole
| sqlalchemy.sql.roles.OnClauseRole
| sqlalchemy.sql.roles.BinaryElementRole
| sqlalchemy.sql.roles.OrderByRole
| sqlalchemy.sql.roles.ColumnsClauseRole
| sqlalchemy.sql.roles.AllowsLambdaRole
| sqlalchemy.sql.roles.ByOfRole
| sqlalchemy.sql.roles.UsesInspection
| sqlalchemy.sql.roles.ColumnListRole
| sqlalchemy.sql.roles.LimitOffsetRole
| sqlalchemy.sql.roles.DMLColumnRole
| sqlalchemy.sql.roles.DDLConstraintColumnRole
| sqlalchemy.sql.roles.DDLExpressionRole
| sqlalchemy.sql.roles.StructuralRole
| SQLColumnExpression
| SQLCoreOperations
| sqlalchemy.sql.roles.ExpressionElementRole
| sqlalchemy.sql.roles.TypedColumnsClauseRole
| typing.Generic
| sqlalchemy.sql.operators.ColumnOperators
| sqlalchemy.sql.operators.Operators
| sqlalchemy.util.langhelpers.TypingOnly
| sqlalchemy.sql.roles.SQLRole
| DQLDMLClauseElement
| ClauseElement
| sqlalchemy.sql.annotation.SupportsWrappingAnnotations
| sqlalchemy.sql.annotation.SupportsAnnotations
| sqlalchemy.sql.cache_key.MemoizedHasCacheKey
| sqlalchemy.sql.cache_key.HasCacheKey
| sqlalchemy.util.langhelpers.HasMemoized
| sqlalchemy.sql.traversals.HasCopyInternals
| sqlalchemy.sql.visitors.ExternallyTraversible
| sqlalchemy.sql.visitors.HasTraverseInternals
| CompilerElement
| sqlalchemy.sql.visitors.Visitable
| builtins.object
|
| Methods defined here:
|
| __init__(self, expression: '_ColumnExpressionArgument[Any]', type_: '_TypeEngineArgument[_T]')
| Initialize self. See help(type(self)) for accurate signature.
|
| ----------------------------------------------------------------------
| Readonly properties defined here:
|
| wrapped_column_expression
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'_traverse_internals': '_TraverseInternalsType', 'c...
|
| __orig_bases__ = (sqlalchemy.sql.elements.WrapsColumnExpression[~_T],)
|
| __parameters__ = (~_T,)
|
| __visit_name__ = 'cast'
|
| ----------------------------------------------------------------------
| Methods inherited from ColumnElement:
|
| __getattr__(self, key: 'str') -> 'Any'
|
| __setstate__(self, state)
|
| base_columns(...)
|
| cast(self, type_: '_TypeEngineArgument[_OPT]') -> 'Cast[_OPT]'
| Produce a type cast, i.e. ``CAST(<expression> AS <type>)``.
|
| This is a shortcut to the :func:`_expression.cast` function.
|
| .. seealso::
|
| :ref:`tutorial_casts`
|
| :func:`_expression.cast`
|
| :func:`_expression.type_coerce`
|
| comparator(...)
|
| label(self, name: 'Optional[str]') -> 'Label[_T]'
| Produce a column label, i.e. ``<columnname> AS <name>``.
|
| This is a shortcut to the :func:`_expression.label` function.
|
| If 'name' is ``None``, an anonymous label name will be generated.
|
| operate(self, op: 'operators.OperatorType', *other: 'Any', **kwargs: 'Any') -> 'ColumnElement[Any]'
| Operate on an argument.
|
| This is the lowest level of operation, raises
| :class:`NotImplementedError` by default.
|
| Overriding this on a subclass can allow common
| behavior to be applied to all operations.
| For example, overriding :class:`.ColumnOperators`
| to apply ``func.lower()`` to the left and right
| side::
|
| class MyComparator(ColumnOperators):
| def operate(self, op, other, **kwargs):
| return op(func.lower(self), func.lower(other), **kwargs)
|
| :param op: Operator callable.
| :param \*other: the 'other' side of the operation. Will
| be a single scalar for most operations.
| :param \**kwargs: modifiers. These may be passed by special
| operators such as :meth:`ColumnOperators.contains`.
|
| proxy_set(...)
| set of all columns we are proxying
|
| as of 2.0 this is explicitly deannotated columns. previously it was
| effectively deannotated columns but wasn't enforced. annotated
| columns should basically not go into sets if at all possible because
| their hashing behavior is very non-performant.
|
| reverse_operate(self, op: 'operators.OperatorType', other: 'Any', **kwargs: 'Any') -> 'ColumnElement[Any]'
| Reverse operate on an argument.
|
| Usage is the same as :meth:`operate`.
|
| self_group(self, against: 'Optional[OperatorType]' = None) -> 'ColumnElement[Any]'
| 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.
|
| shares_lineage(self, othercolumn: 'ColumnElement[Any]') -> 'bool'
| Return True if the given :class:`_expression.ColumnElement`
| has a common ancestor to this :class:`_expression.ColumnElement`.
|
| type(...)
|
| ----------------------------------------------------------------------
| Readonly properties inherited from ColumnElement:
|
| anon_key_label
| .. deprecated:: 1.4 The :attr:`_expression.ColumnElement.anon_key_label` attribute is now private, and the public accessor is deprecated.
|
| anon_label
| .. deprecated:: 1.4 The :attr:`_expression.ColumnElement.anon_label` attribute is now private, and the public accessor is deprecated.
|
| expression
| Return a column expression.
|
| Part of the inspection interface; returns self.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from ColumnElement:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from ColumnElement:
|
| foreign_keys = frozenset()
|
| key = None
|
| primary_key = False
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.AllowsLambdaRole:
|
| allows_lambda = True
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.UsesInspection:
|
| uses_inspection = True
|
| ----------------------------------------------------------------------
| Class methods inherited from typing.Generic:
|
| __class_getitem__(...)
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__(...)
| Function to initialize subclasses.
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.operators.ColumnOperators:
|
| __add__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``+`` operator.
|
| In a column context, produces the clause ``a + b``
| if the parent object has non-string affinity.
| If the parent object has a string affinity,
| produces the concatenation operator, ``a || b`` -
| see :meth:`.ColumnOperators.concat`.
|
| __contains__(self, other: 'Any') -> 'ColumnOperators'
|
| __eq__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``==`` operator.
|
| In a column context, produces the clause ``a = b``.
| If the target is ``None``, produces ``a IS NULL``.
|
| __floordiv__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``//`` operator.
|
| In a column context, produces the clause ``a / b``,
| which is the same as "truediv", but considers the result
| type to be integer.
|
| .. versionadded:: 2.0
|
| __ge__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``>=`` operator.
|
| In a column context, produces the clause ``a >= b``.
|
| __getitem__(self, index: 'Any') -> 'ColumnOperators'
| Implement the [] operator.
|
| This can be used by some database-specific types
| such as PostgreSQL ARRAY and HSTORE.
|
| __gt__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``>`` operator.
|
| In a column context, produces the clause ``a > b``.
|
| __hash__(self, /) from builtins.object
| Return hash(self).
|
| __le__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``<=`` operator.
|
| In a column context, produces the clause ``a <= b``.
|
| __lshift__(self, other: 'Any') -> 'ColumnOperators'
| implement the << operator.
|
| Not used by SQLAlchemy core, this is provided
| for custom operator systems which want to use
| << as an extension point.
|
| __lt__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``<`` operator.
|
| In a column context, produces the clause ``a < b``.
|
| __mod__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``%`` operator.
|
| In a column context, produces the clause ``a % b``.
|
| __mul__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``*`` operator.
|
| In a column context, produces the clause ``a * b``.
|
| __ne__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``!=`` operator.
|
| In a column context, produces the clause ``a != b``.
| If the target is ``None``, produces ``a IS NOT NULL``.
|
| __neg__(self) -> 'ColumnOperators'
| Implement the ``-`` operator.
|
| In a column context, produces the clause ``-a``.
|
| __radd__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``+`` operator in reverse.
|
| See :meth:`.ColumnOperators.__add__`.
|
| __rfloordiv__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``//`` operator in reverse.
|
| See :meth:`.ColumnOperators.__floordiv__`.
|
| __rmod__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``%`` operator in reverse.
|
| See :meth:`.ColumnOperators.__mod__`.
|
| __rmul__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``*`` operator in reverse.
|
| See :meth:`.ColumnOperators.__mul__`.
|
| __rshift__(self, other: 'Any') -> 'ColumnOperators'
| implement the >> operator.
|
| Not used by SQLAlchemy core, this is provided
| for custom operator systems which want to use
| >> as an extension point.
|
| __rsub__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``-`` operator in reverse.
|
| See :meth:`.ColumnOperators.__sub__`.
|
| __rtruediv__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``/`` operator in reverse.
|
| See :meth:`.ColumnOperators.__truediv__`.
|
| __sub__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``-`` operator.
|
| In a column context, produces the clause ``a - b``.
|
| __truediv__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``/`` operator.
|
| In a column context, produces the clause ``a / b``, and
| considers the result type to be numeric.
|
| .. versionchanged:: 2.0 The truediv operator against two integers
| is now considered to return a numeric value. Behavior on specific
| backends may vary.
|
| all_(self) -> 'ColumnOperators'
| Produce an :func:`_expression.all_` clause against the
| parent object.
|
| See the documentation for :func:`_sql.all_` for examples.
|
| .. note:: be sure to not confuse the newer
| :meth:`_sql.ColumnOperators.all_` method with the **legacy**
| version of this method, the :meth:`_types.ARRAY.Comparator.all`
| method that's specific to :class:`_types.ARRAY`, which uses a
| different calling style.
|
| any_(self) -> 'ColumnOperators'
| Produce an :func:`_expression.any_` clause against the
| parent object.
|
| See the documentation for :func:`_sql.any_` for examples.
|
| .. note:: be sure to not confuse the newer
| :meth:`_sql.ColumnOperators.any_` method with the **legacy**
| version of this method, the :meth:`_types.ARRAY.Comparator.any`
| method that's specific to :class:`_types.ARRAY`, which uses a
| different calling style.
|
| asc(self) -> 'ColumnOperators'
| Produce a :func:`_expression.asc` clause against the
| parent object.
|
| between(self, cleft: 'Any', cright: 'Any', symmetric: 'bool' = False) -> 'ColumnOperators'
| Produce a :func:`_expression.between` clause against
| the parent object, given the lower and upper range.
|
| bitwise_and(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise AND operation, typically via the ``&``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_lshift(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise LSHIFT operation, typically via the ``<<``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_not(self) -> 'ColumnOperators'
| Produce a bitwise NOT operation, typically via the ``~``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_or(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise OR operation, typically via the ``|``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_rshift(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise RSHIFT operation, typically via the ``>>``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_xor(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise XOR operation, typically via the ``^``
| operator, or ``#`` for PostgreSQL.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| collate(self, collation: 'str') -> 'ColumnOperators'
| Produce a :func:`_expression.collate` clause against
| the parent object, given the collation string.
|
| .. seealso::
|
| :func:`_expression.collate`
|
| concat(self, other: 'Any') -> 'ColumnOperators'
| Implement the 'concat' operator.
|
| In a column context, produces the clause ``a || b``,
| or uses the ``concat()`` operator on MySQL.
|
| contains(self, other: 'Any', **kw: 'Any') -> 'ColumnOperators'
| Implement the 'contains' operator.
|
| Produces a LIKE expression that tests against a match for the middle
| of a string value:
|
| .. sourcecode:: sql
|
| column LIKE '%' || <other> || '%'
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.contains("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.contains.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.contains.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.contains.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.contains("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE '%' || :param || '%' ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.contains("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE '%' || :param || '%' ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.contains.autoescape`::
|
| somecolumn.contains("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.startswith`
|
| :meth:`.ColumnOperators.endswith`
|
| :meth:`.ColumnOperators.like`
|
| desc(self) -> 'ColumnOperators'
| Produce a :func:`_expression.desc` clause against the
| parent object.
|
| distinct(self) -> 'ColumnOperators'
| Produce a :func:`_expression.distinct` clause against the
| parent object.
|
| endswith(self, other: 'Any', escape: 'Optional[str]' = None, autoescape: 'bool' = False) -> 'ColumnOperators'
| Implement the 'endswith' operator.
|
| Produces a LIKE expression that tests against a match for the end
| of a string value:
|
| .. sourcecode:: sql
|
| column LIKE '%' || <other>
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.endswith("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.endswith.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.endswith.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.endswith.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.endswith("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE '%' || :param ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.endswith("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE '%' || :param ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.endswith.autoescape`::
|
| somecolumn.endswith("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.startswith`
|
| :meth:`.ColumnOperators.contains`
|
| :meth:`.ColumnOperators.like`
|
| icontains(self, other: 'Any', **kw: 'Any') -> 'ColumnOperators'
| Implement the ``icontains`` operator, e.g. case insensitive
| version of :meth:`.ColumnOperators.contains`.
|
| Produces a LIKE expression that tests against an insensitive match
| for the middle of a string value:
|
| .. sourcecode:: sql
|
| lower(column) LIKE '%' || lower(<other>) || '%'
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.icontains("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.icontains.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.icontains.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.icontains.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.icontains("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE '%' || lower(:param) || '%' ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.icontains("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE '%' || lower(:param) || '%' ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.contains.autoescape`::
|
| somecolumn.icontains("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.contains`
|
| iendswith(self, other: 'Any', escape: 'Optional[str]' = None, autoescape: 'bool' = False) -> 'ColumnOperators'
| Implement the ``iendswith`` operator, e.g. case insensitive
| version of :meth:`.ColumnOperators.endswith`.
|
| Produces a LIKE expression that tests against an insensitive match
| for the end of a string value:
|
| .. sourcecode:: sql
|
| lower(column) LIKE '%' || lower(<other>)
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.iendswith("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.iendswith.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.iendswith.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.iendswith.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.iendswith("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE '%' || lower(:param) ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.iendswith("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE '%' || lower(:param) ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.iendswith.autoescape`::
|
| somecolumn.endswith("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.endswith`
|
| ilike(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
| Implement the ``ilike`` operator, e.g. case insensitive LIKE.
|
| In a column context, produces an expression either of the form:
|
| .. sourcecode:: sql
|
| lower(a) LIKE lower(other)
|
| Or on backends that support the ILIKE operator:
|
| .. sourcecode:: sql
|
| a ILIKE other
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.ilike("%foobar%"))
|
| :param other: expression to be compared
| :param escape: optional escape character, renders the ``ESCAPE``
| keyword, e.g.::
|
| somecolumn.ilike("foo/%bar", escape="/")
|
| .. seealso::
|
| :meth:`.ColumnOperators.like`
|
| in_(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``in`` operator.
|
| In a column context, produces the clause ``column IN <other>``.
|
| The given parameter ``other`` may be:
|
| * A list of literal values,
| e.g.::
|
| stmt.where(column.in_([1, 2, 3]))
|
| In this calling form, the list of items is converted to a set of
| bound parameters the same length as the list given:
|
| .. sourcecode:: sql
|
| WHERE COL IN (?, ?, ?)
|
| * A list of tuples may be provided if the comparison is against a
| :func:`.tuple_` containing multiple expressions::
|
| from sqlalchemy import tuple_
|
| stmt.where(tuple_(col1, col2).in_([(1, 10), (2, 20), (3, 30)]))
|
| * An empty list,
| e.g.::
|
| stmt.where(column.in_([]))
|
| In this calling form, the expression renders an "empty set"
| expression. These expressions are tailored to individual backends
| and are generally trying to get an empty SELECT statement as a
| subquery. Such as on SQLite, the expression is:
|
| .. sourcecode:: sql
|
| WHERE col IN (SELECT 1 FROM (SELECT 1) WHERE 1!=1)
|
| .. versionchanged:: 1.4 empty IN expressions now use an
| execution-time generated SELECT subquery in all cases.
|
| * A bound parameter, e.g. :func:`.bindparam`, may be used if it
| includes the :paramref:`.bindparam.expanding` flag::
|
| stmt.where(column.in_(bindparam("value", expanding=True)))
|
| In this calling form, the expression renders a special non-SQL
| placeholder expression that looks like:
|
| .. sourcecode:: sql
|
| WHERE COL IN ([EXPANDING_value])
|
| This placeholder expression is intercepted at statement execution
| time to be converted into the variable number of bound parameter
| form illustrated earlier. If the statement were executed as::
|
| connection.execute(stmt, {"value": [1, 2, 3]})
|
| The database would be passed a bound parameter for each value:
|
| .. sourcecode:: sql
|
| WHERE COL IN (?, ?, ?)
|
| .. versionadded:: 1.2 added "expanding" bound parameters
|
| If an empty list is passed, a special "empty list" expression,
| which is specific to the database in use, is rendered. On
| SQLite this would be:
|
| .. sourcecode:: sql
|
| WHERE COL IN (SELECT 1 FROM (SELECT 1) WHERE 1!=1)
|
| .. versionadded:: 1.3 "expanding" bound parameters now support
| empty lists
|
| * a :func:`_expression.select` construct, which is usually a
| correlated scalar select::
|
| stmt.where(
| column.in_(select(othertable.c.y).where(table.c.x == othertable.c.x))
| )
|
| In this calling form, :meth:`.ColumnOperators.in_` renders as given:
|
| .. sourcecode:: sql
|
| WHERE COL IN (SELECT othertable.y
| FROM othertable WHERE othertable.x = table.x)
|
| :param other: a list of literals, a :func:`_expression.select`
| construct, or a :func:`.bindparam` construct that includes the
| :paramref:`.bindparam.expanding` flag set to True.
|
| is_(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``IS`` operator.
|
| Normally, ``IS`` is generated automatically when comparing to a
| value of ``None``, which resolves to ``NULL``. However, explicit
| usage of ``IS`` may be desirable if comparing to boolean values
| on certain platforms.
|
| .. seealso:: :meth:`.ColumnOperators.is_not`
|
| is_distinct_from(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``IS DISTINCT FROM`` operator.
|
| Renders "a IS DISTINCT FROM b" on most platforms;
| on some such as SQLite may render "a IS NOT b".
|
| is_not(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``IS NOT`` operator.
|
| Normally, ``IS NOT`` is generated automatically when comparing to a
| value of ``None``, which resolves to ``NULL``. However, explicit
| usage of ``IS NOT`` may be desirable if comparing to boolean values
| on certain platforms.
|
| .. versionchanged:: 1.4 The ``is_not()`` operator is renamed from
| ``isnot()`` in previous releases. The previous name remains
| available for backwards compatibility.
|
| .. seealso:: :meth:`.ColumnOperators.is_`
|
| is_not_distinct_from(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``IS NOT DISTINCT FROM`` operator.
|
| Renders "a IS NOT DISTINCT FROM b" on most platforms;
| on some such as SQLite may render "a IS b".
|
| .. versionchanged:: 1.4 The ``is_not_distinct_from()`` operator is
| renamed from ``isnot_distinct_from()`` in previous releases.
| The previous name remains available for backwards compatibility.
|
| isnot = is_not(self, other: 'Any') -> 'ColumnOperators'
|
| isnot_distinct_from = is_not_distinct_from(self, other: 'Any') -> 'ColumnOperators'
|
| istartswith(self, other: 'Any', escape: 'Optional[str]' = None, autoescape: 'bool' = False) -> 'ColumnOperators'
| Implement the ``istartswith`` operator, e.g. case insensitive
| version of :meth:`.ColumnOperators.startswith`.
|
| Produces a LIKE expression that tests against an insensitive
| match for the start of a string value:
|
| .. sourcecode:: sql
|
| lower(column) LIKE lower(<other>) || '%'
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.istartswith("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.istartswith.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.istartswith.escape` parameter will
| establish a given character as an escape character which can be of
| use when the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.istartswith.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.istartswith("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE lower(:param) || '%' ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.istartswith("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE lower(:param) || '%' ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.istartswith.autoescape`::
|
| somecolumn.istartswith("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.startswith`
|
| like(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
| Implement the ``like`` operator.
|
| In a column context, produces the expression:
|
| .. sourcecode:: sql
|
| a LIKE other
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.like("%foobar%"))
|
| :param other: expression to be compared
| :param escape: optional escape character, renders the ``ESCAPE``
| keyword, e.g.::
|
| somecolumn.like("foo/%bar", escape="/")
|
| .. seealso::
|
| :meth:`.ColumnOperators.ilike`
|
| match(self, other: 'Any', **kwargs: 'Any') -> 'ColumnOperators'
| Implements a database-specific 'match' operator.
|
| :meth:`_sql.ColumnOperators.match` attempts to resolve to
| a MATCH-like function or operator provided by the backend.
| Examples include:
|
| * PostgreSQL - renders ``x @@ plainto_tsquery(y)``
|
| .. versionchanged:: 2.0 ``plainto_tsquery()`` is used instead
| of ``to_tsquery()`` for PostgreSQL now; for compatibility with
| other forms, see :ref:`postgresql_match`.
|
|
| * MySQL - renders ``MATCH (x) AGAINST (y IN BOOLEAN MODE)``
|
| .. seealso::
|
| :class:`_mysql.match` - MySQL specific construct with
| additional features.
|
| * Oracle Database - renders ``CONTAINS(x, y)``
| * other backends may provide special implementations.
| * Backends without any special implementation will emit
| the operator as "MATCH". This is compatible with SQLite, for
| example.
|
| not_ilike(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
| implement the ``NOT ILIKE`` operator.
|
| This is equivalent to using negation with
| :meth:`.ColumnOperators.ilike`, i.e. ``~x.ilike(y)``.
|
| .. versionchanged:: 1.4 The ``not_ilike()`` operator is renamed from
| ``notilike()`` in previous releases. The previous name remains
| available for backwards compatibility.
|
| .. seealso::
|
| :meth:`.ColumnOperators.ilike`
|
| not_in(self, other: 'Any') -> 'ColumnOperators'
| implement the ``NOT IN`` operator.
|
| This is equivalent to using negation with
| :meth:`.ColumnOperators.in_`, i.e. ``~x.in_(y)``.
|
| In the case that ``other`` is an empty sequence, the compiler
| produces an "empty not in" expression. This defaults to the
| expression "1 = 1" to produce true in all cases. The
| :paramref:`_sa.create_engine.empty_in_strategy` may be used to
| alter this behavior.
|
| .. versionchanged:: 1.4 The ``not_in()`` operator is renamed from
| ``notin_()`` in previous releases. The previous name remains
| available for backwards compatibility.
|
| .. versionchanged:: 1.2 The :meth:`.ColumnOperators.in_` and
| :meth:`.ColumnOperators.not_in` operators
| now produce a "static" expression for an empty IN sequence
| by default.
|
| .. seealso::
|
| :meth:`.ColumnOperators.in_`
|
| not_like(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
| implement the ``NOT LIKE`` operator.
|
| This is equivalent to using negation with
| :meth:`.ColumnOperators.like`, i.e. ``~x.like(y)``.
|
| .. versionchanged:: 1.4 The ``not_like()`` operator is renamed from
| ``notlike()`` in previous releases. The previous name remains
| available for backwards compatibility.
|
| .. seealso::
|
| :meth:`.ColumnOperators.like`
|
| notilike = not_ilike(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
|
| notin_ = not_in(self, other: 'Any') -> 'ColumnOperators'
|
| notlike = not_like(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
|
| nulls_first(self) -> 'ColumnOperators'
| Produce a :func:`_expression.nulls_first` clause against the
| parent object.
|
| .. versionchanged:: 1.4 The ``nulls_first()`` operator is
| renamed from ``nullsfirst()`` in previous releases.
| The previous name remains available for backwards compatibility.
|
| nulls_last(self) -> 'ColumnOperators'
| Produce a :func:`_expression.nulls_last` clause against the
| parent object.
|
| .. versionchanged:: 1.4 The ``nulls_last()`` operator is
| renamed from ``nullslast()`` in previous releases.
| The previous name remains available for backwards compatibility.
|
| nullsfirst = nulls_first(self) -> 'ColumnOperators'
|
| nullslast = nulls_last(self) -> 'ColumnOperators'
|
| regexp_match(self, pattern: 'Any', flags: 'Optional[str]' = None) -> 'ColumnOperators'
| Implements a database-specific 'regexp match' operator.
|
| E.g.::
|
| stmt = select(table.c.some_column).where(
| table.c.some_column.regexp_match("^(b|c)")
| )
|
| :meth:`_sql.ColumnOperators.regexp_match` attempts to resolve to
| a REGEXP-like function or operator provided by the backend, however
| the specific regular expression syntax and flags available are
| **not backend agnostic**.
|
| Examples include:
|
| * PostgreSQL - renders ``x ~ y`` or ``x !~ y`` when negated.
| * Oracle Database - renders ``REGEXP_LIKE(x, y)``
| * SQLite - uses SQLite's ``REGEXP`` placeholder operator and calls into
| the Python ``re.match()`` builtin.
| * other backends may provide special implementations.
| * Backends without any special implementation will emit
| the operator as "REGEXP" or "NOT REGEXP". This is compatible with
| SQLite and MySQL, for example.
|
| Regular expression support is currently implemented for Oracle
| Database, PostgreSQL, MySQL and MariaDB. Partial support is available
| for SQLite. Support among third-party dialects may vary.
|
| :param pattern: The regular expression pattern string or column
| clause.
| :param flags: Any regular expression string flags to apply, passed as
| plain Python string only. These flags are backend specific.
| Some backends, like PostgreSQL and MariaDB, may alternatively
| specify the flags as part of the pattern.
| When using the ignore case flag 'i' in PostgreSQL, the ignore case
| regexp match operator ``~*`` or ``!~*`` will be used.
|
| .. versionadded:: 1.4
|
| .. versionchanged:: 1.4.48, 2.0.18 Note that due to an implementation
| error, the "flags" parameter previously accepted SQL expression
| objects such as column expressions in addition to plain Python
| strings. This implementation did not work correctly with caching
| and was removed; strings only should be passed for the "flags"
| parameter, as these flags are rendered as literal inline values
| within SQL expressions.
|
| .. seealso::
|
| :meth:`_sql.ColumnOperators.regexp_replace`
|
| regexp_replace(self, pattern: 'Any', replacement: 'Any', flags: 'Optional[str]' = None) -> 'ColumnOperators'
| Implements a database-specific 'regexp replace' operator.
|
| E.g.::
|
| stmt = select(
| table.c.some_column.regexp_replace("b(..)", "XY", flags="g")
| )
|
| :meth:`_sql.ColumnOperators.regexp_replace` attempts to resolve to
| a REGEXP_REPLACE-like function provided by the backend, that
| usually emit the function ``REGEXP_REPLACE()``. However,
| the specific regular expression syntax and flags available are
| **not backend agnostic**.
|
| Regular expression replacement support is currently implemented for
| Oracle Database, PostgreSQL, MySQL 8 or greater and MariaDB. Support
| among third-party dialects may vary.
|
| :param pattern: The regular expression pattern string or column
| clause.
| :param pattern: The replacement string or column clause.
| :param flags: Any regular expression string flags to apply, passed as
| plain Python string only. These flags are backend specific.
| Some backends, like PostgreSQL and MariaDB, may alternatively
| specify the flags as part of the pattern.
|
| .. versionadded:: 1.4
|
| .. versionchanged:: 1.4.48, 2.0.18 Note that due to an implementation
| error, the "flags" parameter previously accepted SQL expression
| objects such as column expressions in addition to plain Python
| strings. This implementation did not work correctly with caching
| and was removed; strings only should be passed for the "flags"
| parameter, as these flags are rendered as literal inline values
| within SQL expressions.
|
|
| .. seealso::
|
| :meth:`_sql.ColumnOperators.regexp_match`
|
| startswith(self, other: 'Any', escape: 'Optional[str]' = None, autoescape: 'bool' = False) -> 'ColumnOperators'
| Implement the ``startswith`` operator.
|
| Produces a LIKE expression that tests against a match for the start
| of a string value:
|
| .. sourcecode:: sql
|
| column LIKE <other> || '%'
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.startswith("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.startswith.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.startswith.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.startswith.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.startswith("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE :param || '%' ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.startswith("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE :param || '%' ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.startswith.autoescape`::
|
| somecolumn.startswith("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.endswith`
|
| :meth:`.ColumnOperators.contains`
|
| :meth:`.ColumnOperators.like`
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.operators.ColumnOperators:
|
| timetuple = None
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.operators.Operators:
|
| __and__(self, other: 'Any') -> 'Operators'
| Implement the ``&`` operator.
|
| When used with SQL expressions, results in an
| AND operation, equivalent to
| :func:`_expression.and_`, that is::
|
| a & b
|
| is equivalent to::
|
| from sqlalchemy import and_
|
| and_(a, b)
|
| Care should be taken when using ``&`` regarding
| operator precedence; the ``&`` operator has the highest precedence.
| The operands should be enclosed in parenthesis if they contain
| further sub expressions::
|
| (a == 2) & (b == 4)
|
| __invert__(self) -> 'Operators'
| Implement the ``~`` operator.
|
| When used with SQL expressions, results in a
| NOT operation, equivalent to
| :func:`_expression.not_`, that is::
|
| ~a
|
| is equivalent to::
|
| from sqlalchemy import not_
|
| not_(a)
|
| __or__(self, other: 'Any') -> 'Operators'
| Implement the ``|`` operator.
|
| When used with SQL expressions, results in an
| OR operation, equivalent to
| :func:`_expression.or_`, that is::
|
| a | b
|
| is equivalent to::
|
| from sqlalchemy import or_
|
| or_(a, b)
|
| Care should be taken when using ``|`` regarding
| operator precedence; the ``|`` operator has the highest precedence.
| The operands should be enclosed in parenthesis if they contain
| further sub expressions::
|
| (a == 2) | (b == 4)
|
| __sa_operate__ = operate(self, op: 'OperatorType', *other: 'Any', **kwargs: 'Any') -> 'Operators'
| Operate on an argument.
|
| This is the lowest level of operation, raises
| :class:`NotImplementedError` by default.
|
| Overriding this on a subclass can allow common
| behavior to be applied to all operations.
| For example, overriding :class:`.ColumnOperators`
| to apply ``func.lower()`` to the left and right
| side::
|
| class MyComparator(ColumnOperators):
| def operate(self, op, other, **kwargs):
| return op(func.lower(self), func.lower(other), **kwargs)
|
| :param op: Operator callable.
| :param \*other: the 'other' side of the operation. Will
| be a single scalar for most operations.
| :param \**kwargs: modifiers. These may be passed by special
| operators such as :meth:`ColumnOperators.contains`.
|
| bool_op(self, opstring: 'str', precedence: 'int' = 0, python_impl: 'Optional[Callable[..., Any]]' = None) -> 'Callable[[Any], Operators]'
| Return a custom boolean operator.
|
| This method is shorthand for calling
| :meth:`.Operators.op` and passing the
| :paramref:`.Operators.op.is_comparison`
| flag with True. A key advantage to using :meth:`.Operators.bool_op`
| is that when using column constructs, the "boolean" nature of the
| returned expression will be present for :pep:`484` purposes.
|
| .. seealso::
|
| :meth:`.Operators.op`
|
| op(self, opstring: 'str', precedence: 'int' = 0, is_comparison: 'bool' = False, return_type: 'Optional[Union[Type[TypeEngine[Any]], TypeEngine[Any]]]' = None, python_impl: 'Optional[Callable[..., Any]]' = None) -> 'Callable[[Any], Operators]'
| Produce a generic operator function.
|
| e.g.::
|
| somecolumn.op("*")(5)
|
| produces::
|
| somecolumn * 5
|
| This function can also be used to make bitwise operators explicit. For
| example::
|
| somecolumn.op("&")(0xFF)
|
| is a bitwise AND of the value in ``somecolumn``.
|
| :param opstring: a string which will be output as the infix operator
| between this element and the expression passed to the
| generated function.
|
| :param precedence: precedence which the database is expected to apply
| to the operator in SQL expressions. This integer value acts as a hint
| for the SQL compiler to know when explicit parenthesis should be
| rendered around a particular operation. A lower number will cause the
| expression to be parenthesized when applied against another operator
| with higher precedence. The default value of ``0`` is lower than all
| operators except for the comma (``,``) and ``AS`` operators. A value
| of 100 will be higher or equal to all operators, and -100 will be
| lower than or equal to all operators.
|
| .. seealso::
|
| :ref:`faq_sql_expression_op_parenthesis` - detailed description
| of how the SQLAlchemy SQL compiler renders parenthesis
|
| :param is_comparison: legacy; if True, the operator will be considered
| as a "comparison" operator, that is which evaluates to a boolean
| true/false value, like ``==``, ``>``, etc. This flag is provided
| so that ORM relationships can establish that the operator is a
| comparison operator when used in a custom join condition.
|
| Using the ``is_comparison`` parameter is superseded by using the
| :meth:`.Operators.bool_op` method instead; this more succinct
| operator sets this parameter automatically, but also provides
| correct :pep:`484` typing support as the returned object will
| express a "boolean" datatype, i.e. ``BinaryExpression[bool]``.
|
| :param return_type: a :class:`.TypeEngine` class or object that will
| force the return type of an expression produced by this operator
| to be of that type. By default, operators that specify
| :paramref:`.Operators.op.is_comparison` will resolve to
| :class:`.Boolean`, and those that do not will be of the same
| type as the left-hand operand.
|
| :param python_impl: an optional Python function that can evaluate
| two Python values in the same way as this operator works when
| run on the database server. Useful for in-Python SQL expression
| evaluation functions, such as for ORM hybrid attributes, and the
| ORM "evaluator" used to match objects in a session after a multi-row
| update or delete.
|
| e.g.::
|
| >>> expr = column("x").op("+", python_impl=lambda a, b: a + b)("y")
|
| The operator for the above expression will also work for non-SQL
| left and right objects::
|
| >>> expr.operator(5, 10)
| 15
|
| .. versionadded:: 2.0
|
|
| .. seealso::
|
| :meth:`.Operators.bool_op`
|
| :ref:`types_operators`
|
| :ref:`relationship_custom_operator`
|
| ----------------------------------------------------------------------
| Methods inherited from ClauseElement:
|
| __bool__(self)
|
| __getstate__(self)
| Helper for pickle.
|
| __repr__(self)
| Return repr(self).
|
| compare(self, other: 'ClauseElement', **kw: 'Any') -> 'bool'
| Compare this :class:`_expression.ClauseElement` to
| the given :class:`_expression.ClauseElement`.
|
| Subclasses should override the default behavior, which is a
| straight identity comparison.
|
| \**kw are arguments consumed by subclass ``compare()`` methods and
| may be used to modify the criteria for comparison
| (see :class:`_expression.ColumnElement`).
|
| description(...)
|
| entity_namespace(...)
|
| params(self, _ClauseElement__optionaldict: 'Optional[Mapping[str, Any]]' = None, **kwargs: 'Any') -> 'Self'
| Return a copy with :func:`_expression.bindparam` elements
| replaced.
|
| Returns a copy of this ClauseElement with
| :func:`_expression.bindparam`
| elements replaced with values taken from the given dictionary::
|
| >>> clause = column("x") + bindparam("foo")
| >>> print(clause.compile().params)
| {'foo':None}
| >>> print(clause.params({"foo": 7}).compile().params)
| {'foo':7}
|
| unique_params(self, _ClauseElement__optionaldict: 'Optional[Dict[str, Any]]' = None, **kwargs: 'Any') -> 'Self'
| Return a copy with :func:`_expression.bindparam` elements
| replaced.
|
| Same functionality as :meth:`_expression.ClauseElement.params`,
| except adds `unique=True`
| to affected bind parameters so that multiple statements can be
| used.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from ClauseElement:
|
| is_clause_element = True
|
| is_dml = False
|
| is_selectable = False
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.cache_key.HasCacheKey:
|
| inherit_cache = None
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_instancemethod(fn: '_F') -> '_F'
| Decorate a method memoize its return value.
|
| :meta private:
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_attribute = <class 'sqlalchemy.util.langhelpers.HasMemoized.m...
| A read-only @property that is only evaluated once.
|
| :meta private:
|
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.visitors.HasTraverseInternals:
|
| get_children(self, *, omit_attrs: 'Tuple[str, ...]' = (), **kw: 'Any') -> 'Iterable[HasTraverseInternals]'
| Return immediate child :class:`.visitors.HasTraverseInternals`
| elements of this :class:`.visitors.HasTraverseInternals`.
|
| This is used for visit traversal.
|
| \**kw may contain flags that change the collection that is
| returned, for example to return a subset of items in order to
| cut down on larger traversals, or to return child items from a
| different context (such as schema-level collections instead of
| clause-level).
|
| ----------------------------------------------------------------------
| Methods inherited from CompilerElement:
|
| __str__(self) -> 'str'
| Return str(self).
|
| compile(self, bind: 'Optional[_HasDialect]' = None, dialect: 'Optional[Dialect]' = None, **kw: 'Any') -> 'Compiled'
| Compile this SQL expression.
|
| The return value is a :class:`~.Compiled` object.
| Calling ``str()`` or ``unicode()`` on the returned value will yield a
| string representation of the result. The
| :class:`~.Compiled` object also can return a
| dictionary of bind parameter names and values
| using the ``params`` accessor.
|
| :param bind: An :class:`.Connection` or :class:`.Engine` which
| can provide a :class:`.Dialect` in order to generate a
| :class:`.Compiled` object. If the ``bind`` and
| ``dialect`` parameters are both omitted, a default SQL compiler
| is used.
|
| :param column_keys: Used for INSERT and UPDATE statements, a list of
| column names which should be present in the VALUES clause of the
| compiled statement. If ``None``, all columns from the target table
| object are rendered.
|
| :param dialect: A :class:`.Dialect` instance which can generate
| a :class:`.Compiled` object. This argument takes precedence over
| the ``bind`` argument.
|
| :param compile_kwargs: optional dictionary of additional parameters
| that will be passed through to the compiler within all "visit"
| methods. This allows any custom flag to be passed through to
| a custom compilation construct, for example. It is also used
| for the case of passing the ``literal_binds`` flag through::
|
| from sqlalchemy.sql import table, column, select
|
| t = table("t", column("x"))
|
| s = select(t).where(t.c.x == 5)
|
| print(s.compile(compile_kwargs={"literal_binds": True}))
|
| .. seealso::
|
| :ref:`faq_sql_expression_string`
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from CompilerElement:
|
| stringify_dialect = 'default'
|
| supports_execution = False
sqlalchemy.CheckConstraint
Python Library Documentation: class CheckConstraint in module sqlalchemy.sql.schema
class CheckConstraint(ColumnCollectionConstraint)
| CheckConstraint(sqltext: '_TextCoercedExpressionArgument[Any]', name: '_ConstraintNameArgument' = None, deferrable: 'Optional[bool]' = None, initially: 'Optional[str]' = None, table: 'Optional[Table]' = None, info: 'Optional[_InfoType]' = None, _create_rule: 'Optional[Any]' = None, _autoattach: 'bool' = True, _type_bound: 'bool' = False, **dialect_kw: 'Any') -> 'None'
|
| A table- or column-level CHECK constraint.
|
| Can be included in the definition of a Table or Column.
|
| Method resolution order:
| CheckConstraint
| ColumnCollectionConstraint
| ColumnCollectionMixin
| Constraint
| sqlalchemy.sql.base.DialectKWArgs
| HasConditionalDDL
| SchemaItem
| sqlalchemy.sql.base.SchemaVisitable
| sqlalchemy.sql.base.SchemaEventTarget
| sqlalchemy.event.registry.EventTarget
| sqlalchemy.sql.visitors.Visitable
| builtins.object
|
| Methods defined here:
|
| __init__(self, sqltext: '_TextCoercedExpressionArgument[Any]', name: '_ConstraintNameArgument' = None, deferrable: 'Optional[bool]' = None, initially: 'Optional[str]' = None, table: 'Optional[Table]' = None, info: 'Optional[_InfoType]' = None, _create_rule: 'Optional[Any]' = None, _autoattach: 'bool' = True, _type_bound: 'bool' = False, **dialect_kw: 'Any') -> 'None'
| Construct a CHECK constraint.
|
| :param sqltext:
| A string containing the constraint definition, which will be used
| verbatim, or a SQL expression construct. If given as a string,
| the object is converted to a :func:`_expression.text` object.
| If the textual
| string includes a colon character, escape this using a backslash::
|
| CheckConstraint(r"foo ~ E'a(?\:b|c)d")
|
| .. warning:: The :paramref:`.CheckConstraint.sqltext` argument to :class:`.CheckConstraint` can be passed as a Python string argument, which will be treated as **trusted SQL text** and rendered as given. **DO NOT PASS UNTRUSTED INPUT TO THIS PARAMETER**.
|
|
|
| :param name:
| Optional, the in-database name of the constraint.
|
| :param deferrable:
| Optional bool. If set, emit DEFERRABLE or NOT DEFERRABLE when
| issuing DDL for this constraint.
|
| :param initially:
| Optional string. If set, emit INITIALLY <value> when issuing DDL
| for this constraint.
|
| :param info: Optional data dictionary which will be populated into the
| :attr:`.SchemaItem.info` attribute of this object.
|
| copy(self, *, target_table: 'Optional[Table]' = None, **kw: 'Any') -> 'CheckConstraint'
| .. deprecated:: 1.4 The :meth:`_schema.CheckConstraint.copy` method is deprecated and will be removed in a future release.
|
| ----------------------------------------------------------------------
| Readonly properties defined here:
|
| is_column_level
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| __visit_name__ = 'table_or_column_check_constraint'
|
| ----------------------------------------------------------------------
| Methods inherited from ColumnCollectionConstraint:
|
| __contains__(self, x: 'Any') -> 'bool'
|
| __iter__(self) -> 'Iterator[Column[Any]]'
|
| __len__(self) -> 'int'
|
| contains_column(self, col: 'Column[Any]') -> 'bool'
| Return True if this constraint contains the given column.
|
| Note that this object also contains an attribute ``.columns``
| which is a :class:`_expression.ColumnCollection` of
| :class:`_schema.Column` objects.
|
| ----------------------------------------------------------------------
| Methods inherited from ColumnCollectionMixin:
|
| c(...)
|
| columns(...)
|
| ----------------------------------------------------------------------
| Data descriptors inherited from ColumnCollectionMixin:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Readonly properties inherited from Constraint:
|
| table
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.base.DialectKWArgs:
|
| dialect_options(...)
| A collection of keyword arguments specified as dialect-specific
| options to this construct.
|
| This is a two-level nested registry, keyed to ``<dialect_name>``
| and ``<argument_name>``. For example, the ``postgresql_where``
| argument would be locatable as::
|
| arg = my_object.dialect_options["postgresql"]["where"]
|
| .. versionadded:: 0.9.2
|
| .. seealso::
|
| :attr:`.DialectKWArgs.dialect_kwargs` - flat dictionary form
|
| get_dialect_option(self, dialect: 'Dialect', argument_name: 'str', *, else_: 'Any' = None, deprecated_fallback: 'Optional[str]' = None) -> 'Any'
| Return the value of a dialect-specific option, or *else_* if
| this dialect does not register the given argument.
|
| This is useful for DDL compilers that may be inherited by
| third-party dialects whose ``construct_arguments`` do not
| include the same set of keys as the parent dialect.
|
| :param dialect: The dialect for which to retrieve the option.
| :param argument_name: The name of the argument to retrieve.
| :param else\_: The value to return if the argument is not present.
| :param deprecated_fallback: Optional dialect name to fall back to
| if the argument is not present for the current dialect. If the
| argument is present for the fallback dialect but not the current
| dialect, a deprecation warning will be emitted.
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.base.DialectKWArgs:
|
| argument_for(dialect_name: 'str', argument_name: 'str', default: 'Any') -> 'None'
| Add a new kind of dialect-specific keyword argument for this class.
|
| E.g.::
|
| Index.argument_for("mydialect", "length", None)
|
| some_index = Index("a", "b", mydialect_length=5)
|
| The :meth:`.DialectKWArgs.argument_for` method is a per-argument
| way adding extra arguments to the
| :attr:`.DefaultDialect.construct_arguments` dictionary. This
| dictionary provides a list of argument names accepted by various
| schema-level constructs on behalf of a dialect.
|
| New dialects should typically specify this dictionary all at once as a
| data member of the dialect class. The use case for ad-hoc addition of
| argument names is typically for end-user code that is also using
| a custom compilation scheme which consumes the additional arguments.
|
| :param dialect_name: name of a dialect. The dialect must be
| locatable, else a :class:`.NoSuchModuleError` is raised. The
| dialect must also include an existing
| :attr:`.DefaultDialect.construct_arguments` collection, indicating
| that it participates in the keyword-argument validation and default
| system, else :class:`.ArgumentError` is raised. If the dialect does
| not include this collection, then any keyword argument can be
| specified on behalf of this dialect already. All dialects packaged
| within SQLAlchemy include this collection, however for third party
| dialects, support may vary.
|
| :param argument_name: name of the parameter.
|
| :param default: default value of the parameter.
|
| ----------------------------------------------------------------------
| Readonly properties inherited from sqlalchemy.sql.base.DialectKWArgs:
|
| dialect_kwargs
| A collection of keyword arguments specified as dialect-specific
| options to this construct.
|
| The arguments are present here in their original ``<dialect>_<kwarg>``
| format. Only arguments that were actually passed are included;
| unlike the :attr:`.DialectKWArgs.dialect_options` collection, which
| contains all options known by this dialect including defaults.
|
| The collection is also writable; keys are accepted of the
| form ``<dialect>_<kwarg>`` where the value will be assembled
| into the list of options.
|
| .. seealso::
|
| :attr:`.DialectKWArgs.dialect_options` - nested dictionary form
|
| kwargs
| A synonym for :attr:`.DialectKWArgs.dialect_kwargs`.
|
| ----------------------------------------------------------------------
| Methods inherited from HasConditionalDDL:
|
| ddl_if(self, dialect: 'Optional[str]' = None, callable_: 'Optional[ddl.DDLIfCallable]' = None, state: 'Optional[Any]' = None) -> 'Self'
| apply a conditional DDL rule to this schema item.
|
| These rules work in a similar manner to the
| :meth:`.ExecutableDDLElement.execute_if` callable, with the added
| feature that the criteria may be checked within the DDL compilation
| phase for a construct such as :class:`.CreateTable`.
| :meth:`.HasConditionalDDL.ddl_if` currently applies towards the
| :class:`.Index` construct as well as all :class:`.Constraint`
| constructs.
|
| :param dialect: string name of a dialect, or a tuple of string names
| to indicate multiple dialect types.
|
| :param callable\_: a callable that is constructed using the same form
| as that described in
| :paramref:`.ExecutableDDLElement.execute_if.callable_`.
|
| :param state: any arbitrary object that will be passed to the
| callable, if present.
|
| .. versionadded:: 2.0
|
| .. seealso::
|
| :ref:`schema_ddl_ddl_if` - background and usage examples
|
| ----------------------------------------------------------------------
| Methods inherited from SchemaItem:
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| info(...)
| Info dictionary associated with the object, allowing user-defined
| data to be associated with this :class:`.SchemaItem`.
|
| The dictionary is automatically generated when first accessed.
| It can also be specified in the constructor of some objects,
| such as :class:`_schema.Table` and :class:`_schema.Column`.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from SchemaItem:
|
| create_drop_stringify_dialect = 'default'
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.base.SchemaEventTarget:
|
| dispatch = <sqlalchemy.event.base.DDLEventsDispatch object>
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.visitors.Visitable:
|
| __class_getitem__(key: 'Any') -> 'Any'
|
| __init_subclass__() -> 'None'
| This method is called when a class is subclassed.
|
| The default implementation does nothing. It may be
| overridden to extend subclasses.
sqlalchemy.ChunkedIteratorResult
Python Library Documentation: class ChunkedIteratorResult in module sqlalchemy.engine.result
class ChunkedIteratorResult(IteratorResult)
| ChunkedIteratorResult(cursor_metadata: 'ResultMetaData', chunks: 'Callable[[Optional[int]], Iterator[Sequence[_InterimRowType[_R]]]]', source_supports_scalars: 'bool' = False, raw: 'Optional[Result[Any]]' = None, dynamic_yield_per: 'bool' = False)
|
| An :class:`_engine.IteratorResult` that works from an
| iterator-producing callable.
|
| The given ``chunks`` argument is a function that is given a number of rows
| to return in each chunk, or ``None`` for all rows. The function should
| then return an un-consumed iterator of lists, each list of the requested
| size.
|
| The function can be called at any time again, in which case it should
| continue from the same result set but adjust the chunk size as given.
|
| .. versionadded:: 1.4
|
| Method resolution order:
| ChunkedIteratorResult
| IteratorResult
| Result
| _WithKeys
| ResultInternal
| sqlalchemy.sql.base.InPlaceGenerative
| sqlalchemy.util.langhelpers.HasMemoized
| typing.Generic
| builtins.object
|
| Methods defined here:
|
| __init__(self, cursor_metadata: 'ResultMetaData', chunks: 'Callable[[Optional[int]], Iterator[Sequence[_InterimRowType[_R]]]]', source_supports_scalars: 'bool' = False, raw: 'Optional[Result[Any]]' = None, dynamic_yield_per: 'bool' = False)
| Initialize self. See help(type(self)) for accurate signature.
|
| yield_per(self, num: 'int') -> 'Self'
| Configure the row-fetching strategy to fetch ``num`` rows at a time.
|
| This impacts the underlying behavior of the result when iterating over
| the result object, or otherwise making use of methods such as
| :meth:`_engine.Result.fetchone` that return one row at a time. Data
| from the underlying cursor or other data source will be buffered up to
| this many rows in memory, and the buffered collection will then be
| yielded out one row at a time or as many rows are requested. Each time
| the buffer clears, it will be refreshed to this many rows or as many
| rows remain if fewer remain.
|
| The :meth:`_engine.Result.yield_per` method is generally used in
| conjunction with the
| :paramref:`_engine.Connection.execution_options.stream_results`
| execution option, which will allow the database dialect in use to make
| use of a server side cursor, if the DBAPI supports a specific "server
| side cursor" mode separate from its default mode of operation.
|
| .. tip::
|
| Consider using the
| :paramref:`_engine.Connection.execution_options.yield_per`
| execution option, which will simultaneously set
| :paramref:`_engine.Connection.execution_options.stream_results`
| to ensure the use of server side cursors, as well as automatically
| invoke the :meth:`_engine.Result.yield_per` method to establish
| a fixed row buffer size at once.
|
| The :paramref:`_engine.Connection.execution_options.yield_per`
| execution option is available for ORM operations, with
| :class:`_orm.Session`-oriented use described at
| :ref:`orm_queryguide_yield_per`. The Core-only version which works
| with :class:`_engine.Connection` is new as of SQLAlchemy 1.4.40.
|
| .. versionadded:: 1.4
|
| :param num: number of rows to fetch each time the buffer is refilled.
| If set to a value below 1, fetches all rows for the next buffer.
|
| .. seealso::
|
| :ref:`engine_stream_results` - describes Core behavior for
| :meth:`_engine.Result.yield_per`
|
| :ref:`orm_queryguide_yield_per` - in the :ref:`queryguide_toplevel`
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| __orig_bases__ = (sqlalchemy.engine.result.IteratorResult[~_TP],)
|
| __parameters__ = (~_TP,)
|
| ----------------------------------------------------------------------
| Readonly properties inherited from IteratorResult:
|
| closed
| Return ``True`` if this :class:`_engine.IteratorResult` was
| **hard closed** by explicitly calling the :meth:`_engine.Result.close`
| method.
|
| The attribute is **not** True if the :class:`_engine.Result` was only
| **soft closed**; a "soft close" is the style of close that takes place
| for example when the :class:`.CursorResult` is returned for a DML
| only statement without RETURNING, or when all result rows are fetched.
|
| .. seealso::
|
| :attr:`.CursorResult.returns_rows` - attribute specific to
| :class:`.CursorResult` which indicates if the result is one that
| may return zero or more rows
|
| ----------------------------------------------------------------------
| Data descriptors inherited from IteratorResult:
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Methods inherited from Result:
|
| __enter__(self) -> 'Self'
|
| __exit__(self, type_: 'Any', value: 'Any', traceback: 'Any') -> 'None'
|
| __iter__(self) -> 'Iterator[Row[_TP]]'
|
| __next__(self) -> 'Row[_TP]'
|
| all(self) -> 'Sequence[Row[_TP]]'
| Return all rows in a sequence.
|
| Closes the result set after invocation. Subsequent invocations
| will return an empty sequence.
|
| .. versionadded:: 1.4
|
| :return: a sequence of :class:`_engine.Row` objects.
|
| .. seealso::
|
| :ref:`engine_stream_results` - How to stream a large result set
| without loading it completely in python.
|
| close(self) -> 'None'
| Hard close this :class:`_engine.Result`.
|
| The behavior of this method is implementation specific, and is
| not implemented by default. The method should generally end
| the resources in use by the result object and also cause any
| subsequent iteration or row fetching to raise
| :class:`.ResourceClosedError`.
|
| .. versionadded:: 1.4.27 - ``.close()`` was previously not generally
| available for all :class:`_engine.Result` classes, instead only
| being available on the :class:`_engine.CursorResult` returned for
| Core statement executions. As most other result objects, namely the
| ones used by the ORM, are proxying a :class:`_engine.CursorResult`
| in any case, this allows the underlying cursor result to be closed
| from the outside facade for the case when the ORM query is using
| the ``yield_per`` execution option where it does not immediately
| exhaust and autoclose the database cursor.
|
| columns(self, *col_expressions: '_KeyIndexType') -> 'Self'
| Establish the columns that should be returned in each row.
|
| This method may be used to limit the columns returned as well
| as to reorder them. The given list of expressions are normally
| a series of integers or string key names. They may also be
| appropriate :class:`.ColumnElement` objects which correspond to
| a given statement construct.
|
| .. versionchanged:: 2.0 Due to a bug in 1.4, the
| :meth:`_engine.Result.columns` method had an incorrect behavior
| where calling upon the method with just one index would cause the
| :class:`_engine.Result` object to yield scalar values rather than
| :class:`_engine.Row` objects. In version 2.0, this behavior
| has been corrected such that calling upon
| :meth:`_engine.Result.columns` with a single index will
| produce a :class:`_engine.Result` object that continues
| to yield :class:`_engine.Row` objects, which include
| only a single column.
|
| E.g.::
|
| statement = select(table.c.x, table.c.y, table.c.z)
| result = connection.execute(statement)
|
| for z, y in result.columns("z", "y"):
| ...
|
| Example of using the column objects from the statement itself::
|
| for z, y in result.columns(
| statement.selected_columns.c.z, statement.selected_columns.c.y
| ):
| ...
|
| .. versionadded:: 1.4
|
| :param \*col_expressions: indicates columns to be returned. Elements
| may be integer row indexes, string column names, or appropriate
| :class:`.ColumnElement` objects corresponding to a select construct.
|
| :return: this :class:`_engine.Result` object with the modifications
| given.
|
| fetchall(self) -> 'Sequence[Row[_TP]]'
| A synonym for the :meth:`_engine.Result.all` method.
|
| fetchmany(self, size: 'Optional[int]' = None) -> 'Sequence[Row[_TP]]'
| Fetch many rows.
|
| When all rows are exhausted, returns an empty sequence.
|
| This method is provided for backwards compatibility with
| SQLAlchemy 1.x.x.
|
| To fetch rows in groups, use the :meth:`_engine.Result.partitions`
| method.
|
| :return: a sequence of :class:`_engine.Row` objects.
|
| .. seealso::
|
| :meth:`_engine.Result.partitions`
|
| fetchone(self) -> 'Optional[Row[_TP]]'
| Fetch one row.
|
| When all rows are exhausted, returns None.
|
| This method is provided for backwards compatibility with
| SQLAlchemy 1.x.x.
|
| To fetch the first row of a result only, use the
| :meth:`_engine.Result.first` method. To iterate through all
| rows, iterate the :class:`_engine.Result` object directly.
|
| :return: a :class:`_engine.Row` object if no filters are applied,
| or ``None`` if no rows remain.
|
| first(self) -> 'Optional[Row[_TP]]'
| Fetch the first row or ``None`` if no row is present.
|
| Closes the result set and discards remaining rows.
|
| .. note:: This method returns one **row**, e.g. tuple, by default.
| To return exactly one single scalar value, that is, the first
| column of the first row, use the
| :meth:`_engine.Result.scalar` method,
| or combine :meth:`_engine.Result.scalars` and
| :meth:`_engine.Result.first`.
|
| Additionally, in contrast to the behavior of the legacy ORM
| :meth:`_orm.Query.first` method, **no limit is applied** to the
| SQL query which was invoked to produce this
| :class:`_engine.Result`;
| for a DBAPI driver that buffers results in memory before yielding
| rows, all rows will be sent to the Python process and all but
| the first row will be discarded.
|
| .. seealso::
|
| :ref:`migration_20_unify_select`
|
| :return: a :class:`_engine.Row` object, or None
| if no rows remain.
|
| .. seealso::
|
| :meth:`_engine.Result.scalar`
|
| :meth:`_engine.Result.one`
|
| freeze(self) -> 'FrozenResult[_TP]'
| Return a callable object that will produce copies of this
| :class:`_engine.Result` when invoked.
|
| The callable object returned is an instance of
| :class:`_engine.FrozenResult`.
|
| This is used for result set caching. The method must be called
| on the result when it has been unconsumed, and calling the method
| will consume the result fully. When the :class:`_engine.FrozenResult`
| is retrieved from a cache, it can be called any number of times where
| it will produce a new :class:`_engine.Result` object each time
| against its stored set of rows.
|
| .. seealso::
|
| :ref:`do_orm_execute_re_executing` - example usage within the
| ORM to implement a result-set cache.
|
| mappings(self) -> 'MappingResult'
| Apply a mappings filter to returned rows, returning an instance of
| :class:`_engine.MappingResult`.
|
| When this filter is applied, fetching rows will return
| :class:`_engine.RowMapping` objects instead of :class:`_engine.Row`
| objects.
|
| .. versionadded:: 1.4
|
| :return: a new :class:`_engine.MappingResult` filtering object
| referring to this :class:`_engine.Result` object.
|
| merge(self, *others: 'Result[Any]') -> 'MergedResult[_TP]'
| Merge this :class:`_engine.Result` with other compatible result
| objects.
|
| The object returned is an instance of :class:`_engine.MergedResult`,
| which will be composed of iterators from the given result
| objects.
|
| The new result will use the metadata from this result object.
| The subsequent result objects must be against an identical
| set of result / cursor metadata, otherwise the behavior is
| undefined.
|
| one(self) -> 'Row[_TP]'
| Return exactly one row or raise an exception.
|
| Raises :class:`_exc.NoResultFound` if the result returns no
| rows, or :class:`_exc.MultipleResultsFound` if multiple rows
| would be returned.
|
| .. note:: This method returns one **row**, e.g. tuple, by default.
| To return exactly one single scalar value, that is, the first
| column of the first row, use the
| :meth:`_engine.Result.scalar_one` method, or combine
| :meth:`_engine.Result.scalars` and
| :meth:`_engine.Result.one`.
|
| .. versionadded:: 1.4
|
| :return: The first :class:`_engine.Row`.
|
| :raises: :class:`.MultipleResultsFound`, :class:`.NoResultFound`
|
| .. seealso::
|
| :meth:`_engine.Result.first`
|
| :meth:`_engine.Result.one_or_none`
|
| :meth:`_engine.Result.scalar_one`
|
| one_or_none(self) -> 'Optional[Row[_TP]]'
| Return at most one result or raise an exception.
|
| Returns ``None`` if the result has no rows.
| Raises :class:`.MultipleResultsFound`
| if multiple rows are returned.
|
| .. versionadded:: 1.4
|
| :return: The first :class:`_engine.Row` or ``None`` if no row
| is available.
|
| :raises: :class:`.MultipleResultsFound`
|
| .. seealso::
|
| :meth:`_engine.Result.first`
|
| :meth:`_engine.Result.one`
|
| partitions(self, size: 'Optional[int]' = None) -> 'Iterator[Sequence[Row[_TP]]]'
| Iterate through sub-lists of rows of the size given.
|
| Each list will be of the size given, excluding the last list to
| be yielded, which may have a small number of rows. No empty
| lists will be yielded.
|
| The result object is automatically closed when the iterator
| is fully consumed.
|
| Note that the backend driver will usually buffer the entire result
| ahead of time unless the
| :paramref:`.Connection.execution_options.stream_results` execution
| option is used indicating that the driver should not pre-buffer
| results, if possible. Not all drivers support this option and
| the option is silently ignored for those who do not.
|
| When using the ORM, the :meth:`_engine.Result.partitions` method
| is typically more effective from a memory perspective when it is
| combined with use of the
| :ref:`yield_per execution option <orm_queryguide_yield_per>`,
| which instructs both the DBAPI driver to use server side cursors,
| if available, as well as instructs the ORM loading internals to only
| build a certain amount of ORM objects from a result at a time before
| yielding them out.
|
| .. versionadded:: 1.4
|
| :param size: indicate the maximum number of rows to be present
| in each list yielded. If None, makes use of the value set by
| the :meth:`_engine.Result.yield_per`, method, if it were called,
| or the :paramref:`_engine.Connection.execution_options.yield_per`
| execution option, which is equivalent in this regard. If
| yield_per weren't set, it makes use of the
| :meth:`_engine.Result.fetchmany` default, which may be backend
| specific and not well defined.
|
| :return: iterator of lists
|
| .. seealso::
|
| :ref:`engine_stream_results`
|
| :ref:`orm_queryguide_yield_per` - in the :ref:`queryguide_toplevel`
|
| scalar(self) -> 'Any'
| Fetch the first column of the first row, and close the result set.
|
| Returns ``None`` if there are no rows to fetch.
|
| No validation is performed to test if additional rows remain.
|
| After calling this method, the object is fully closed,
| e.g. the :meth:`_engine.CursorResult.close`
| method will have been called.
|
| :return: a Python scalar value, or ``None`` if no rows remain.
|
| scalar_one(self) -> 'Any'
| Return exactly one scalar result or raise an exception.
|
| This is equivalent to calling :meth:`_engine.Result.scalars` and
| then :meth:`_engine.ScalarResult.one`.
|
| .. seealso::
|
| :meth:`_engine.ScalarResult.one`
|
| :meth:`_engine.Result.scalars`
|
| scalar_one_or_none(self) -> 'Optional[Any]'
| Return exactly one scalar result or ``None``.
|
| This is equivalent to calling :meth:`_engine.Result.scalars` and
| then :meth:`_engine.ScalarResult.one_or_none`.
|
| .. seealso::
|
| :meth:`_engine.ScalarResult.one_or_none`
|
| :meth:`_engine.Result.scalars`
|
| scalars(self, index: '_KeyIndexType' = 0) -> 'ScalarResult[Any]'
| Return a :class:`_engine.ScalarResult` filtering object which
| will return single elements rather than :class:`_row.Row` objects.
|
| E.g.::
|
| >>> result = conn.execute(text("select int_id from table"))
| >>> result.scalars().all()
| [1, 2, 3]
|
| When results are fetched from the :class:`_engine.ScalarResult`
| filtering object, the single column-row that would be returned by the
| :class:`_engine.Result` is instead returned as the column's value.
|
| .. versionadded:: 1.4
|
| :param index: integer or row key indicating the column to be fetched
| from each row, defaults to ``0`` indicating the first column.
|
| :return: a new :class:`_engine.ScalarResult` filtering object referring
| to this :class:`_engine.Result` object.
|
| tuples(self) -> 'TupleResult[_TP]'
| Apply a "typed tuple" typing filter to returned rows.
|
| This method returns the same :class:`_engine.Result` object
| at runtime,
| however annotates as returning a :class:`_engine.TupleResult` object
| that will indicate to :pep:`484` typing tools that plain typed
| ``Tuple`` instances are returned rather than rows. This allows
| tuple unpacking and ``__getitem__`` access of :class:`_engine.Row`
| objects to by typed, for those cases where the statement invoked
| itself included typing information.
|
| .. versionadded:: 2.0
|
| :return: the :class:`_engine.TupleResult` type at typing time.
|
| .. seealso::
|
| :attr:`_engine.Result.t` - shorter synonym
|
| :attr:`_engine.Row._t` - :class:`_engine.Row` version
|
| unique(self, strategy: 'Optional[_UniqueFilterType]' = None) -> 'Self'
| Apply unique filtering to the objects returned by this
| :class:`_engine.Result`.
|
| When this filter is applied with no arguments, the rows or objects
| returned will filtered such that each row is returned uniquely. The
| algorithm used to determine this uniqueness is by default the Python
| hashing identity of the whole tuple. In some cases a specialized
| per-entity hashing scheme may be used, such as when using the ORM, a
| scheme is applied which works against the primary key identity of
| returned objects.
|
| The unique filter is applied **after all other filters**, which means
| if the columns returned have been refined using a method such as the
| :meth:`_engine.Result.columns` or :meth:`_engine.Result.scalars`
| method, the uniquing is applied to **only the column or columns
| returned**. This occurs regardless of the order in which these
| methods have been called upon the :class:`_engine.Result` object.
|
| The unique filter also changes the calculus used for methods like
| :meth:`_engine.Result.fetchmany` and :meth:`_engine.Result.partitions`.
| When using :meth:`_engine.Result.unique`, these methods will continue
| to yield the number of rows or objects requested, after uniquing
| has been applied. However, this necessarily impacts the buffering
| behavior of the underlying cursor or datasource, such that multiple
| underlying calls to ``cursor.fetchmany()`` may be necessary in order
| to accumulate enough objects in order to provide a unique collection
| of the requested size.
|
| :param strategy: a callable that will be applied to rows or objects
| being iterated, which should return an object that represents the
| unique value of the row. A Python ``set()`` is used to store
| these identities. If not passed, a default uniqueness strategy
| is used which may have been assembled by the source of this
| :class:`_engine.Result` object.
|
| ----------------------------------------------------------------------
| Readonly properties inherited from Result:
|
| t
| Apply a "typed tuple" typing filter to returned rows.
|
| The :attr:`_engine.Result.t` attribute is a synonym for
| calling the :meth:`_engine.Result.tuples` method.
|
| .. versionadded:: 2.0
|
| ----------------------------------------------------------------------
| Data descriptors inherited from Result:
|
| __dict__
| dictionary for instance variables
|
| ----------------------------------------------------------------------
| Methods inherited from _WithKeys:
|
| keys(self) -> 'RMKeyView'
| Return an iterable view which yields the string keys that would
| be represented by each :class:`_engine.Row`.
|
| The keys can represent the labels of the columns returned by a core
| statement or the names of the orm classes returned by an orm
| execution.
|
| The view also can be tested for key containment using the Python
| ``in`` operator, which will test both for the string keys represented
| in the view, as well as for alternate keys such as column objects.
|
| .. versionchanged:: 1.4 a key view object is returned rather than a
| plain list.
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_instancemethod(fn: '_F') -> '_F'
| Decorate a method memoize its return value.
|
| :meta private:
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_attribute = <class 'sqlalchemy.util.langhelpers.HasMemoized.m...
| A read-only @property that is only evaluated once.
|
| :meta private:
|
|
| ----------------------------------------------------------------------
| Class methods inherited from typing.Generic:
|
| __class_getitem__(...)
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__(...)
| Function to initialize subclasses.
sqlalchemy.ClauseElement
Python Library Documentation: class ClauseElement in module sqlalchemy.sql.elements
class ClauseElement(sqlalchemy.sql.annotation.SupportsWrappingAnnotations, sqlalchemy.sql.cache_key.MemoizedHasCacheKey, sqlalchemy.sql.traversals.HasCopyInternals, sqlalchemy.sql.visitors.ExternallyTraversible, CompilerElement)
| Base class for elements of a programmatically constructed SQL
| expression.
|
| Method resolution order:
| ClauseElement
| sqlalchemy.sql.annotation.SupportsWrappingAnnotations
| sqlalchemy.sql.annotation.SupportsAnnotations
| sqlalchemy.sql.cache_key.MemoizedHasCacheKey
| sqlalchemy.sql.cache_key.HasCacheKey
| sqlalchemy.util.langhelpers.HasMemoized
| sqlalchemy.sql.traversals.HasCopyInternals
| sqlalchemy.sql.visitors.ExternallyTraversible
| sqlalchemy.sql.visitors.HasTraverseInternals
| CompilerElement
| sqlalchemy.sql.visitors.Visitable
| builtins.object
|
| Methods defined here:
|
| __bool__(self)
|
| __getstate__(self)
| Helper for pickle.
|
| __invert__(self)
|
| __repr__(self)
| Return repr(self).
|
| compare(self, other: 'ClauseElement', **kw: 'Any') -> 'bool'
| Compare this :class:`_expression.ClauseElement` to
| the given :class:`_expression.ClauseElement`.
|
| Subclasses should override the default behavior, which is a
| straight identity comparison.
|
| \**kw are arguments consumed by subclass ``compare()`` methods and
| may be used to modify the criteria for comparison
| (see :class:`_expression.ColumnElement`).
|
| description(...)
|
| entity_namespace(...)
|
| params(self, _ClauseElement__optionaldict: 'Optional[Mapping[str, Any]]' = None, **kwargs: 'Any') -> 'Self'
| Return a copy with :func:`_expression.bindparam` elements
| replaced.
|
| Returns a copy of this ClauseElement with
| :func:`_expression.bindparam`
| elements replaced with values taken from the given dictionary::
|
| >>> clause = column("x") + bindparam("foo")
| >>> print(clause.compile().params)
| {'foo':None}
| >>> print(clause.params({"foo": 7}).compile().params)
| {'foo':7}
|
| self_group(self, against: 'Optional[OperatorType]' = None) -> 'ClauseElement'
| 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.
|
| unique_params(self, _ClauseElement__optionaldict: 'Optional[Dict[str, Any]]' = None, **kwargs: 'Any') -> 'Self'
| Return a copy with :func:`_expression.bindparam` elements
| replaced.
|
| Same functionality as :meth:`_expression.ClauseElement.params`,
| except adds `unique=True`
| to affected bind parameters so that multiple statements can be
| used.
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'_cache_key_traversal': '_CacheKeyTraversalType', '...
|
| __visit_name__ = 'clause'
|
| is_clause_element = True
|
| is_dml = False
|
| is_selectable = False
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.cache_key.HasCacheKey:
|
| inherit_cache = None
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_instancemethod(fn: '_F') -> '_F'
| Decorate a method memoize its return value.
|
| :meta private:
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_attribute = <class 'sqlalchemy.util.langhelpers.HasMemoized.m...
| A read-only @property that is only evaluated once.
|
| :meta private:
|
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.visitors.HasTraverseInternals:
|
| get_children(self, *, omit_attrs: 'Tuple[str, ...]' = (), **kw: 'Any') -> 'Iterable[HasTraverseInternals]'
| Return immediate child :class:`.visitors.HasTraverseInternals`
| elements of this :class:`.visitors.HasTraverseInternals`.
|
| This is used for visit traversal.
|
| \**kw may contain flags that change the collection that is
| returned, for example to return a subset of items in order to
| cut down on larger traversals, or to return child items from a
| different context (such as schema-level collections instead of
| clause-level).
|
| ----------------------------------------------------------------------
| Methods inherited from CompilerElement:
|
| __str__(self) -> 'str'
| Return str(self).
|
| compile(self, bind: 'Optional[_HasDialect]' = None, dialect: 'Optional[Dialect]' = None, **kw: 'Any') -> 'Compiled'
| Compile this SQL expression.
|
| The return value is a :class:`~.Compiled` object.
| Calling ``str()`` or ``unicode()`` on the returned value will yield a
| string representation of the result. The
| :class:`~.Compiled` object also can return a
| dictionary of bind parameter names and values
| using the ``params`` accessor.
|
| :param bind: An :class:`.Connection` or :class:`.Engine` which
| can provide a :class:`.Dialect` in order to generate a
| :class:`.Compiled` object. If the ``bind`` and
| ``dialect`` parameters are both omitted, a default SQL compiler
| is used.
|
| :param column_keys: Used for INSERT and UPDATE statements, a list of
| column names which should be present in the VALUES clause of the
| compiled statement. If ``None``, all columns from the target table
| object are rendered.
|
| :param dialect: A :class:`.Dialect` instance which can generate
| a :class:`.Compiled` object. This argument takes precedence over
| the ``bind`` argument.
|
| :param compile_kwargs: optional dictionary of additional parameters
| that will be passed through to the compiler within all "visit"
| methods. This allows any custom flag to be passed through to
| a custom compilation construct, for example. It is also used
| for the case of passing the ``literal_binds`` flag through::
|
| from sqlalchemy.sql import table, column, select
|
| t = table("t", column("x"))
|
| s = select(t).where(t.c.x == 5)
|
| print(s.compile(compile_kwargs={"literal_binds": True}))
|
| .. seealso::
|
| :ref:`faq_sql_expression_string`
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from CompilerElement:
|
| stringify_dialect = 'default'
|
| supports_execution = False
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.visitors.Visitable:
|
| __class_getitem__(key: 'Any') -> 'Any'
|
| __init_subclass__() -> 'None'
| This method is called when a class is subclassed.
|
| The default implementation does nothing. It may be
| overridden to extend subclasses.
sqlalchemy.ClauseList
Python Library Documentation: class ClauseList in module sqlalchemy.sql.elements
class ClauseList(sqlalchemy.sql.roles.InElementRole, sqlalchemy.sql.roles.OrderByRole, sqlalchemy.sql.roles.ColumnsClauseRole, sqlalchemy.sql.roles.DMLColumnRole, DQLDMLClauseElement)
| ClauseList(*clauses: '_ColumnExpressionArgument[Any]', operator: 'OperatorType' = <function comma_op at 0x000002D3E11B7060>, group: 'bool' = True, group_contents: 'bool' = True, _literal_as_text_role: 'Type[roles.SQLRole]' = <class 'sqlalchemy.sql.roles.WhereHavingRole'>)
|
| Describe a list of clauses, separated by an operator.
|
| By default, is comma-separated, such as a column listing.
|
| Method resolution order:
| ClauseList
| sqlalchemy.sql.roles.InElementRole
| sqlalchemy.sql.roles.OrderByRole
| sqlalchemy.sql.roles.ColumnsClauseRole
| sqlalchemy.sql.roles.AllowsLambdaRole
| sqlalchemy.sql.roles.ByOfRole
| sqlalchemy.sql.roles.UsesInspection
| sqlalchemy.sql.roles.ColumnListRole
| sqlalchemy.sql.roles.DMLColumnRole
| sqlalchemy.sql.roles.SQLRole
| DQLDMLClauseElement
| ClauseElement
| sqlalchemy.sql.annotation.SupportsWrappingAnnotations
| sqlalchemy.sql.annotation.SupportsAnnotations
| sqlalchemy.sql.cache_key.MemoizedHasCacheKey
| sqlalchemy.sql.cache_key.HasCacheKey
| sqlalchemy.util.langhelpers.HasMemoized
| sqlalchemy.sql.traversals.HasCopyInternals
| sqlalchemy.sql.visitors.ExternallyTraversible
| sqlalchemy.sql.visitors.HasTraverseInternals
| CompilerElement
| sqlalchemy.sql.visitors.Visitable
| builtins.object
|
| Methods defined here:
|
| __init__(self, *clauses: '_ColumnExpressionArgument[Any]', operator: 'OperatorType' = <function comma_op at 0x000002D3E11B7060>, group: 'bool' = True, group_contents: 'bool' = True, _literal_as_text_role: 'Type[roles.SQLRole]' = <class 'sqlalchemy.sql.roles.WhereHavingRole'>)
| Initialize self. See help(type(self)) for accurate signature.
|
| __iter__(self) -> 'Iterator[ColumnElement[Any]]'
|
| __len__(self) -> 'int'
|
| append(self, clause)
|
| self_group(self, against: 'Optional[OperatorType]' = None) -> 'Union[Self, Grouping[Any]]'
| 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.
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'_traverse_internals': '_TraverseInternalsType', 'c...
|
| __visit_name__ = 'clauselist'
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.AllowsLambdaRole:
|
| allows_lambda = True
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.UsesInspection:
|
| uses_inspection = True
|
| ----------------------------------------------------------------------
| Methods inherited from ClauseElement:
|
| __bool__(self)
|
| __getstate__(self)
| Helper for pickle.
|
| __invert__(self)
|
| __repr__(self)
| Return repr(self).
|
| compare(self, other: 'ClauseElement', **kw: 'Any') -> 'bool'
| Compare this :class:`_expression.ClauseElement` to
| the given :class:`_expression.ClauseElement`.
|
| Subclasses should override the default behavior, which is a
| straight identity comparison.
|
| \**kw are arguments consumed by subclass ``compare()`` methods and
| may be used to modify the criteria for comparison
| (see :class:`_expression.ColumnElement`).
|
| description(...)
|
| entity_namespace(...)
|
| params(self, _ClauseElement__optionaldict: 'Optional[Mapping[str, Any]]' = None, **kwargs: 'Any') -> 'Self'
| Return a copy with :func:`_expression.bindparam` elements
| replaced.
|
| Returns a copy of this ClauseElement with
| :func:`_expression.bindparam`
| elements replaced with values taken from the given dictionary::
|
| >>> clause = column("x") + bindparam("foo")
| >>> print(clause.compile().params)
| {'foo':None}
| >>> print(clause.params({"foo": 7}).compile().params)
| {'foo':7}
|
| unique_params(self, _ClauseElement__optionaldict: 'Optional[Dict[str, Any]]' = None, **kwargs: 'Any') -> 'Self'
| Return a copy with :func:`_expression.bindparam` elements
| replaced.
|
| Same functionality as :meth:`_expression.ClauseElement.params`,
| except adds `unique=True`
| to affected bind parameters so that multiple statements can be
| used.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from ClauseElement:
|
| is_clause_element = True
|
| is_dml = False
|
| is_selectable = False
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.cache_key.HasCacheKey:
|
| inherit_cache = None
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_instancemethod(fn: '_F') -> '_F'
| Decorate a method memoize its return value.
|
| :meta private:
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_attribute = <class 'sqlalchemy.util.langhelpers.HasMemoized.m...
| A read-only @property that is only evaluated once.
|
| :meta private:
|
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.visitors.HasTraverseInternals:
|
| get_children(self, *, omit_attrs: 'Tuple[str, ...]' = (), **kw: 'Any') -> 'Iterable[HasTraverseInternals]'
| Return immediate child :class:`.visitors.HasTraverseInternals`
| elements of this :class:`.visitors.HasTraverseInternals`.
|
| This is used for visit traversal.
|
| \**kw may contain flags that change the collection that is
| returned, for example to return a subset of items in order to
| cut down on larger traversals, or to return child items from a
| different context (such as schema-level collections instead of
| clause-level).
|
| ----------------------------------------------------------------------
| Methods inherited from CompilerElement:
|
| __str__(self) -> 'str'
| Return str(self).
|
| compile(self, bind: 'Optional[_HasDialect]' = None, dialect: 'Optional[Dialect]' = None, **kw: 'Any') -> 'Compiled'
| Compile this SQL expression.
|
| The return value is a :class:`~.Compiled` object.
| Calling ``str()`` or ``unicode()`` on the returned value will yield a
| string representation of the result. The
| :class:`~.Compiled` object also can return a
| dictionary of bind parameter names and values
| using the ``params`` accessor.
|
| :param bind: An :class:`.Connection` or :class:`.Engine` which
| can provide a :class:`.Dialect` in order to generate a
| :class:`.Compiled` object. If the ``bind`` and
| ``dialect`` parameters are both omitted, a default SQL compiler
| is used.
|
| :param column_keys: Used for INSERT and UPDATE statements, a list of
| column names which should be present in the VALUES clause of the
| compiled statement. If ``None``, all columns from the target table
| object are rendered.
|
| :param dialect: A :class:`.Dialect` instance which can generate
| a :class:`.Compiled` object. This argument takes precedence over
| the ``bind`` argument.
|
| :param compile_kwargs: optional dictionary of additional parameters
| that will be passed through to the compiler within all "visit"
| methods. This allows any custom flag to be passed through to
| a custom compilation construct, for example. It is also used
| for the case of passing the ``literal_binds`` flag through::
|
| from sqlalchemy.sql import table, column, select
|
| t = table("t", column("x"))
|
| s = select(t).where(t.c.x == 5)
|
| print(s.compile(compile_kwargs={"literal_binds": True}))
|
| .. seealso::
|
| :ref:`faq_sql_expression_string`
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from CompilerElement:
|
| stringify_dialect = 'default'
|
| supports_execution = False
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.visitors.Visitable:
|
| __class_getitem__(key: 'Any') -> 'Any'
|
| __init_subclass__() -> 'None'
| This method is called when a class is subclassed.
|
| The default implementation does nothing. It may be
| overridden to extend subclasses.
sqlalchemy.CollectionAggregate
Python Library Documentation: class CollectionAggregate in module sqlalchemy.sql.elements
class CollectionAggregate(UnaryExpression)
| CollectionAggregate(element: 'ColumnElement[Any]', *, operator: 'Optional[OperatorType]' = None, modifier: 'Optional[OperatorType]' = None, type_: 'Optional[_TypeEngineArgument[_T]]' = None, wraps_column_expression: 'bool' = False)
|
| Forms the basis for right-hand collection operator modifiers
| ANY and ALL.
|
| The ANY and ALL keywords are available in different ways on different
| backends. On PostgreSQL, they only work for an ARRAY type. On
| MySQL, they only work for subqueries.
|
| Method resolution order:
| CollectionAggregate
| UnaryExpression
| ColumnElement
| sqlalchemy.sql.roles.ColumnArgumentOrKeyRole
| sqlalchemy.sql.roles.ColumnArgumentRole
| sqlalchemy.sql.roles.StatementOptionRole
| sqlalchemy.sql.roles.WhereHavingRole
| sqlalchemy.sql.roles.OnClauseRole
| sqlalchemy.sql.roles.BinaryElementRole
| sqlalchemy.sql.roles.OrderByRole
| sqlalchemy.sql.roles.ColumnsClauseRole
| sqlalchemy.sql.roles.AllowsLambdaRole
| sqlalchemy.sql.roles.ByOfRole
| sqlalchemy.sql.roles.UsesInspection
| sqlalchemy.sql.roles.ColumnListRole
| sqlalchemy.sql.roles.LimitOffsetRole
| sqlalchemy.sql.roles.DMLColumnRole
| sqlalchemy.sql.roles.DDLConstraintColumnRole
| sqlalchemy.sql.roles.DDLExpressionRole
| sqlalchemy.sql.roles.StructuralRole
| SQLColumnExpression
| SQLCoreOperations
| sqlalchemy.sql.roles.ExpressionElementRole
| sqlalchemy.sql.roles.TypedColumnsClauseRole
| typing.Generic
| sqlalchemy.sql.operators.ColumnOperators
| sqlalchemy.sql.operators.Operators
| sqlalchemy.util.langhelpers.TypingOnly
| sqlalchemy.sql.roles.SQLRole
| DQLDMLClauseElement
| ClauseElement
| sqlalchemy.sql.annotation.SupportsWrappingAnnotations
| sqlalchemy.sql.annotation.SupportsAnnotations
| sqlalchemy.sql.cache_key.MemoizedHasCacheKey
| sqlalchemy.sql.cache_key.HasCacheKey
| sqlalchemy.util.langhelpers.HasMemoized
| sqlalchemy.sql.traversals.HasCopyInternals
| sqlalchemy.sql.visitors.ExternallyTraversible
| sqlalchemy.sql.visitors.HasTraverseInternals
| CompilerElement
| sqlalchemy.sql.visitors.Visitable
| builtins.object
|
| Methods defined here:
|
| operate(self, op: 'OperatorType', *other: 'Any', **kwargs: 'Any') -> 'ColumnElement[_T]'
| Operate on an argument.
|
| This is the lowest level of operation, raises
| :class:`NotImplementedError` by default.
|
| Overriding this on a subclass can allow common
| behavior to be applied to all operations.
| For example, overriding :class:`.ColumnOperators`
| to apply ``func.lower()`` to the left and right
| side::
|
| class MyComparator(ColumnOperators):
| def operate(self, op, other, **kwargs):
| return op(func.lower(self), func.lower(other), **kwargs)
|
| :param op: Operator callable.
| :param \*other: the 'other' side of the operation. Will
| be a single scalar for most operations.
| :param \**kwargs: modifiers. These may be passed by special
| operators such as :meth:`ColumnOperators.contains`.
|
| reverse_operate(self, op: 'OperatorType', other: 'Any', **kwargs: 'Any') -> 'ColumnElement[_T]'
| Reverse operate on an argument.
|
| Usage is the same as :meth:`operate`.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| __orig_bases__ = (sqlalchemy.sql.elements.UnaryExpression[~_T],)
|
| __parameters__ = (~_T,)
|
| inherit_cache = True
|
| ----------------------------------------------------------------------
| Methods inherited from UnaryExpression:
|
| __init__(self, element: 'ColumnElement[Any]', *, operator: 'Optional[OperatorType]' = None, modifier: 'Optional[OperatorType]' = None, type_: 'Optional[_TypeEngineArgument[_T]]' = None, wraps_column_expression: 'bool' = False)
| Initialize self. See help(type(self)) for accurate signature.
|
| self_group(self, against: 'Optional[OperatorType]' = None) -> 'Union[Self, Grouping[_T]]'
| 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.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from UnaryExpression:
|
| __visit_name__ = 'unary'
|
| ----------------------------------------------------------------------
| Methods inherited from ColumnElement:
|
| __getattr__(self, key: 'str') -> 'Any'
|
| __setstate__(self, state)
|
| base_columns(...)
|
| cast(self, type_: '_TypeEngineArgument[_OPT]') -> 'Cast[_OPT]'
| Produce a type cast, i.e. ``CAST(<expression> AS <type>)``.
|
| This is a shortcut to the :func:`_expression.cast` function.
|
| .. seealso::
|
| :ref:`tutorial_casts`
|
| :func:`_expression.cast`
|
| :func:`_expression.type_coerce`
|
| comparator(...)
|
| label(self, name: 'Optional[str]') -> 'Label[_T]'
| Produce a column label, i.e. ``<columnname> AS <name>``.
|
| This is a shortcut to the :func:`_expression.label` function.
|
| If 'name' is ``None``, an anonymous label name will be generated.
|
| proxy_set(...)
| set of all columns we are proxying
|
| as of 2.0 this is explicitly deannotated columns. previously it was
| effectively deannotated columns but wasn't enforced. annotated
| columns should basically not go into sets if at all possible because
| their hashing behavior is very non-performant.
|
| shares_lineage(self, othercolumn: 'ColumnElement[Any]') -> 'bool'
| Return True if the given :class:`_expression.ColumnElement`
| has a common ancestor to this :class:`_expression.ColumnElement`.
|
| type(...)
|
| ----------------------------------------------------------------------
| Readonly properties inherited from ColumnElement:
|
| anon_key_label
| .. deprecated:: 1.4 The :attr:`_expression.ColumnElement.anon_key_label` attribute is now private, and the public accessor is deprecated.
|
| anon_label
| .. deprecated:: 1.4 The :attr:`_expression.ColumnElement.anon_label` attribute is now private, and the public accessor is deprecated.
|
| expression
| Return a column expression.
|
| Part of the inspection interface; returns self.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from ColumnElement:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from ColumnElement:
|
| foreign_keys = frozenset()
|
| key = None
|
| primary_key = False
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.AllowsLambdaRole:
|
| allows_lambda = True
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.UsesInspection:
|
| uses_inspection = True
|
| ----------------------------------------------------------------------
| Class methods inherited from typing.Generic:
|
| __class_getitem__(...)
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__(...)
| Function to initialize subclasses.
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.operators.ColumnOperators:
|
| __add__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``+`` operator.
|
| In a column context, produces the clause ``a + b``
| if the parent object has non-string affinity.
| If the parent object has a string affinity,
| produces the concatenation operator, ``a || b`` -
| see :meth:`.ColumnOperators.concat`.
|
| __contains__(self, other: 'Any') -> 'ColumnOperators'
|
| __eq__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``==`` operator.
|
| In a column context, produces the clause ``a = b``.
| If the target is ``None``, produces ``a IS NULL``.
|
| __floordiv__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``//`` operator.
|
| In a column context, produces the clause ``a / b``,
| which is the same as "truediv", but considers the result
| type to be integer.
|
| .. versionadded:: 2.0
|
| __ge__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``>=`` operator.
|
| In a column context, produces the clause ``a >= b``.
|
| __getitem__(self, index: 'Any') -> 'ColumnOperators'
| Implement the [] operator.
|
| This can be used by some database-specific types
| such as PostgreSQL ARRAY and HSTORE.
|
| __gt__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``>`` operator.
|
| In a column context, produces the clause ``a > b``.
|
| __hash__(self, /) from builtins.object
| Return hash(self).
|
| __le__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``<=`` operator.
|
| In a column context, produces the clause ``a <= b``.
|
| __lshift__(self, other: 'Any') -> 'ColumnOperators'
| implement the << operator.
|
| Not used by SQLAlchemy core, this is provided
| for custom operator systems which want to use
| << as an extension point.
|
| __lt__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``<`` operator.
|
| In a column context, produces the clause ``a < b``.
|
| __mod__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``%`` operator.
|
| In a column context, produces the clause ``a % b``.
|
| __mul__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``*`` operator.
|
| In a column context, produces the clause ``a * b``.
|
| __ne__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``!=`` operator.
|
| In a column context, produces the clause ``a != b``.
| If the target is ``None``, produces ``a IS NOT NULL``.
|
| __neg__(self) -> 'ColumnOperators'
| Implement the ``-`` operator.
|
| In a column context, produces the clause ``-a``.
|
| __radd__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``+`` operator in reverse.
|
| See :meth:`.ColumnOperators.__add__`.
|
| __rfloordiv__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``//`` operator in reverse.
|
| See :meth:`.ColumnOperators.__floordiv__`.
|
| __rmod__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``%`` operator in reverse.
|
| See :meth:`.ColumnOperators.__mod__`.
|
| __rmul__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``*`` operator in reverse.
|
| See :meth:`.ColumnOperators.__mul__`.
|
| __rshift__(self, other: 'Any') -> 'ColumnOperators'
| implement the >> operator.
|
| Not used by SQLAlchemy core, this is provided
| for custom operator systems which want to use
| >> as an extension point.
|
| __rsub__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``-`` operator in reverse.
|
| See :meth:`.ColumnOperators.__sub__`.
|
| __rtruediv__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``/`` operator in reverse.
|
| See :meth:`.ColumnOperators.__truediv__`.
|
| __sub__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``-`` operator.
|
| In a column context, produces the clause ``a - b``.
|
| __truediv__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``/`` operator.
|
| In a column context, produces the clause ``a / b``, and
| considers the result type to be numeric.
|
| .. versionchanged:: 2.0 The truediv operator against two integers
| is now considered to return a numeric value. Behavior on specific
| backends may vary.
|
| all_(self) -> 'ColumnOperators'
| Produce an :func:`_expression.all_` clause against the
| parent object.
|
| See the documentation for :func:`_sql.all_` for examples.
|
| .. note:: be sure to not confuse the newer
| :meth:`_sql.ColumnOperators.all_` method with the **legacy**
| version of this method, the :meth:`_types.ARRAY.Comparator.all`
| method that's specific to :class:`_types.ARRAY`, which uses a
| different calling style.
|
| any_(self) -> 'ColumnOperators'
| Produce an :func:`_expression.any_` clause against the
| parent object.
|
| See the documentation for :func:`_sql.any_` for examples.
|
| .. note:: be sure to not confuse the newer
| :meth:`_sql.ColumnOperators.any_` method with the **legacy**
| version of this method, the :meth:`_types.ARRAY.Comparator.any`
| method that's specific to :class:`_types.ARRAY`, which uses a
| different calling style.
|
| asc(self) -> 'ColumnOperators'
| Produce a :func:`_expression.asc` clause against the
| parent object.
|
| between(self, cleft: 'Any', cright: 'Any', symmetric: 'bool' = False) -> 'ColumnOperators'
| Produce a :func:`_expression.between` clause against
| the parent object, given the lower and upper range.
|
| bitwise_and(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise AND operation, typically via the ``&``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_lshift(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise LSHIFT operation, typically via the ``<<``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_not(self) -> 'ColumnOperators'
| Produce a bitwise NOT operation, typically via the ``~``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_or(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise OR operation, typically via the ``|``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_rshift(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise RSHIFT operation, typically via the ``>>``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_xor(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise XOR operation, typically via the ``^``
| operator, or ``#`` for PostgreSQL.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| collate(self, collation: 'str') -> 'ColumnOperators'
| Produce a :func:`_expression.collate` clause against
| the parent object, given the collation string.
|
| .. seealso::
|
| :func:`_expression.collate`
|
| concat(self, other: 'Any') -> 'ColumnOperators'
| Implement the 'concat' operator.
|
| In a column context, produces the clause ``a || b``,
| or uses the ``concat()`` operator on MySQL.
|
| contains(self, other: 'Any', **kw: 'Any') -> 'ColumnOperators'
| Implement the 'contains' operator.
|
| Produces a LIKE expression that tests against a match for the middle
| of a string value:
|
| .. sourcecode:: sql
|
| column LIKE '%' || <other> || '%'
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.contains("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.contains.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.contains.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.contains.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.contains("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE '%' || :param || '%' ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.contains("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE '%' || :param || '%' ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.contains.autoescape`::
|
| somecolumn.contains("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.startswith`
|
| :meth:`.ColumnOperators.endswith`
|
| :meth:`.ColumnOperators.like`
|
| desc(self) -> 'ColumnOperators'
| Produce a :func:`_expression.desc` clause against the
| parent object.
|
| distinct(self) -> 'ColumnOperators'
| Produce a :func:`_expression.distinct` clause against the
| parent object.
|
| endswith(self, other: 'Any', escape: 'Optional[str]' = None, autoescape: 'bool' = False) -> 'ColumnOperators'
| Implement the 'endswith' operator.
|
| Produces a LIKE expression that tests against a match for the end
| of a string value:
|
| .. sourcecode:: sql
|
| column LIKE '%' || <other>
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.endswith("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.endswith.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.endswith.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.endswith.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.endswith("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE '%' || :param ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.endswith("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE '%' || :param ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.endswith.autoescape`::
|
| somecolumn.endswith("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.startswith`
|
| :meth:`.ColumnOperators.contains`
|
| :meth:`.ColumnOperators.like`
|
| icontains(self, other: 'Any', **kw: 'Any') -> 'ColumnOperators'
| Implement the ``icontains`` operator, e.g. case insensitive
| version of :meth:`.ColumnOperators.contains`.
|
| Produces a LIKE expression that tests against an insensitive match
| for the middle of a string value:
|
| .. sourcecode:: sql
|
| lower(column) LIKE '%' || lower(<other>) || '%'
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.icontains("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.icontains.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.icontains.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.icontains.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.icontains("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE '%' || lower(:param) || '%' ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.icontains("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE '%' || lower(:param) || '%' ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.contains.autoescape`::
|
| somecolumn.icontains("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.contains`
|
| iendswith(self, other: 'Any', escape: 'Optional[str]' = None, autoescape: 'bool' = False) -> 'ColumnOperators'
| Implement the ``iendswith`` operator, e.g. case insensitive
| version of :meth:`.ColumnOperators.endswith`.
|
| Produces a LIKE expression that tests against an insensitive match
| for the end of a string value:
|
| .. sourcecode:: sql
|
| lower(column) LIKE '%' || lower(<other>)
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.iendswith("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.iendswith.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.iendswith.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.iendswith.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.iendswith("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE '%' || lower(:param) ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.iendswith("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE '%' || lower(:param) ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.iendswith.autoescape`::
|
| somecolumn.endswith("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.endswith`
|
| ilike(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
| Implement the ``ilike`` operator, e.g. case insensitive LIKE.
|
| In a column context, produces an expression either of the form:
|
| .. sourcecode:: sql
|
| lower(a) LIKE lower(other)
|
| Or on backends that support the ILIKE operator:
|
| .. sourcecode:: sql
|
| a ILIKE other
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.ilike("%foobar%"))
|
| :param other: expression to be compared
| :param escape: optional escape character, renders the ``ESCAPE``
| keyword, e.g.::
|
| somecolumn.ilike("foo/%bar", escape="/")
|
| .. seealso::
|
| :meth:`.ColumnOperators.like`
|
| in_(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``in`` operator.
|
| In a column context, produces the clause ``column IN <other>``.
|
| The given parameter ``other`` may be:
|
| * A list of literal values,
| e.g.::
|
| stmt.where(column.in_([1, 2, 3]))
|
| In this calling form, the list of items is converted to a set of
| bound parameters the same length as the list given:
|
| .. sourcecode:: sql
|
| WHERE COL IN (?, ?, ?)
|
| * A list of tuples may be provided if the comparison is against a
| :func:`.tuple_` containing multiple expressions::
|
| from sqlalchemy import tuple_
|
| stmt.where(tuple_(col1, col2).in_([(1, 10), (2, 20), (3, 30)]))
|
| * An empty list,
| e.g.::
|
| stmt.where(column.in_([]))
|
| In this calling form, the expression renders an "empty set"
| expression. These expressions are tailored to individual backends
| and are generally trying to get an empty SELECT statement as a
| subquery. Such as on SQLite, the expression is:
|
| .. sourcecode:: sql
|
| WHERE col IN (SELECT 1 FROM (SELECT 1) WHERE 1!=1)
|
| .. versionchanged:: 1.4 empty IN expressions now use an
| execution-time generated SELECT subquery in all cases.
|
| * A bound parameter, e.g. :func:`.bindparam`, may be used if it
| includes the :paramref:`.bindparam.expanding` flag::
|
| stmt.where(column.in_(bindparam("value", expanding=True)))
|
| In this calling form, the expression renders a special non-SQL
| placeholder expression that looks like:
|
| .. sourcecode:: sql
|
| WHERE COL IN ([EXPANDING_value])
|
| This placeholder expression is intercepted at statement execution
| time to be converted into the variable number of bound parameter
| form illustrated earlier. If the statement were executed as::
|
| connection.execute(stmt, {"value": [1, 2, 3]})
|
| The database would be passed a bound parameter for each value:
|
| .. sourcecode:: sql
|
| WHERE COL IN (?, ?, ?)
|
| .. versionadded:: 1.2 added "expanding" bound parameters
|
| If an empty list is passed, a special "empty list" expression,
| which is specific to the database in use, is rendered. On
| SQLite this would be:
|
| .. sourcecode:: sql
|
| WHERE COL IN (SELECT 1 FROM (SELECT 1) WHERE 1!=1)
|
| .. versionadded:: 1.3 "expanding" bound parameters now support
| empty lists
|
| * a :func:`_expression.select` construct, which is usually a
| correlated scalar select::
|
| stmt.where(
| column.in_(select(othertable.c.y).where(table.c.x == othertable.c.x))
| )
|
| In this calling form, :meth:`.ColumnOperators.in_` renders as given:
|
| .. sourcecode:: sql
|
| WHERE COL IN (SELECT othertable.y
| FROM othertable WHERE othertable.x = table.x)
|
| :param other: a list of literals, a :func:`_expression.select`
| construct, or a :func:`.bindparam` construct that includes the
| :paramref:`.bindparam.expanding` flag set to True.
|
| is_(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``IS`` operator.
|
| Normally, ``IS`` is generated automatically when comparing to a
| value of ``None``, which resolves to ``NULL``. However, explicit
| usage of ``IS`` may be desirable if comparing to boolean values
| on certain platforms.
|
| .. seealso:: :meth:`.ColumnOperators.is_not`
|
| is_distinct_from(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``IS DISTINCT FROM`` operator.
|
| Renders "a IS DISTINCT FROM b" on most platforms;
| on some such as SQLite may render "a IS NOT b".
|
| is_not(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``IS NOT`` operator.
|
| Normally, ``IS NOT`` is generated automatically when comparing to a
| value of ``None``, which resolves to ``NULL``. However, explicit
| usage of ``IS NOT`` may be desirable if comparing to boolean values
| on certain platforms.
|
| .. versionchanged:: 1.4 The ``is_not()`` operator is renamed from
| ``isnot()`` in previous releases. The previous name remains
| available for backwards compatibility.
|
| .. seealso:: :meth:`.ColumnOperators.is_`
|
| is_not_distinct_from(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``IS NOT DISTINCT FROM`` operator.
|
| Renders "a IS NOT DISTINCT FROM b" on most platforms;
| on some such as SQLite may render "a IS b".
|
| .. versionchanged:: 1.4 The ``is_not_distinct_from()`` operator is
| renamed from ``isnot_distinct_from()`` in previous releases.
| The previous name remains available for backwards compatibility.
|
| isnot = is_not(self, other: 'Any') -> 'ColumnOperators'
|
| isnot_distinct_from = is_not_distinct_from(self, other: 'Any') -> 'ColumnOperators'
|
| istartswith(self, other: 'Any', escape: 'Optional[str]' = None, autoescape: 'bool' = False) -> 'ColumnOperators'
| Implement the ``istartswith`` operator, e.g. case insensitive
| version of :meth:`.ColumnOperators.startswith`.
|
| Produces a LIKE expression that tests against an insensitive
| match for the start of a string value:
|
| .. sourcecode:: sql
|
| lower(column) LIKE lower(<other>) || '%'
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.istartswith("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.istartswith.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.istartswith.escape` parameter will
| establish a given character as an escape character which can be of
| use when the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.istartswith.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.istartswith("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE lower(:param) || '%' ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.istartswith("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE lower(:param) || '%' ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.istartswith.autoescape`::
|
| somecolumn.istartswith("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.startswith`
|
| like(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
| Implement the ``like`` operator.
|
| In a column context, produces the expression:
|
| .. sourcecode:: sql
|
| a LIKE other
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.like("%foobar%"))
|
| :param other: expression to be compared
| :param escape: optional escape character, renders the ``ESCAPE``
| keyword, e.g.::
|
| somecolumn.like("foo/%bar", escape="/")
|
| .. seealso::
|
| :meth:`.ColumnOperators.ilike`
|
| match(self, other: 'Any', **kwargs: 'Any') -> 'ColumnOperators'
| Implements a database-specific 'match' operator.
|
| :meth:`_sql.ColumnOperators.match` attempts to resolve to
| a MATCH-like function or operator provided by the backend.
| Examples include:
|
| * PostgreSQL - renders ``x @@ plainto_tsquery(y)``
|
| .. versionchanged:: 2.0 ``plainto_tsquery()`` is used instead
| of ``to_tsquery()`` for PostgreSQL now; for compatibility with
| other forms, see :ref:`postgresql_match`.
|
|
| * MySQL - renders ``MATCH (x) AGAINST (y IN BOOLEAN MODE)``
|
| .. seealso::
|
| :class:`_mysql.match` - MySQL specific construct with
| additional features.
|
| * Oracle Database - renders ``CONTAINS(x, y)``
| * other backends may provide special implementations.
| * Backends without any special implementation will emit
| the operator as "MATCH". This is compatible with SQLite, for
| example.
|
| not_ilike(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
| implement the ``NOT ILIKE`` operator.
|
| This is equivalent to using negation with
| :meth:`.ColumnOperators.ilike`, i.e. ``~x.ilike(y)``.
|
| .. versionchanged:: 1.4 The ``not_ilike()`` operator is renamed from
| ``notilike()`` in previous releases. The previous name remains
| available for backwards compatibility.
|
| .. seealso::
|
| :meth:`.ColumnOperators.ilike`
|
| not_in(self, other: 'Any') -> 'ColumnOperators'
| implement the ``NOT IN`` operator.
|
| This is equivalent to using negation with
| :meth:`.ColumnOperators.in_`, i.e. ``~x.in_(y)``.
|
| In the case that ``other`` is an empty sequence, the compiler
| produces an "empty not in" expression. This defaults to the
| expression "1 = 1" to produce true in all cases. The
| :paramref:`_sa.create_engine.empty_in_strategy` may be used to
| alter this behavior.
|
| .. versionchanged:: 1.4 The ``not_in()`` operator is renamed from
| ``notin_()`` in previous releases. The previous name remains
| available for backwards compatibility.
|
| .. versionchanged:: 1.2 The :meth:`.ColumnOperators.in_` and
| :meth:`.ColumnOperators.not_in` operators
| now produce a "static" expression for an empty IN sequence
| by default.
|
| .. seealso::
|
| :meth:`.ColumnOperators.in_`
|
| not_like(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
| implement the ``NOT LIKE`` operator.
|
| This is equivalent to using negation with
| :meth:`.ColumnOperators.like`, i.e. ``~x.like(y)``.
|
| .. versionchanged:: 1.4 The ``not_like()`` operator is renamed from
| ``notlike()`` in previous releases. The previous name remains
| available for backwards compatibility.
|
| .. seealso::
|
| :meth:`.ColumnOperators.like`
|
| notilike = not_ilike(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
|
| notin_ = not_in(self, other: 'Any') -> 'ColumnOperators'
|
| notlike = not_like(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
|
| nulls_first(self) -> 'ColumnOperators'
| Produce a :func:`_expression.nulls_first` clause against the
| parent object.
|
| .. versionchanged:: 1.4 The ``nulls_first()`` operator is
| renamed from ``nullsfirst()`` in previous releases.
| The previous name remains available for backwards compatibility.
|
| nulls_last(self) -> 'ColumnOperators'
| Produce a :func:`_expression.nulls_last` clause against the
| parent object.
|
| .. versionchanged:: 1.4 The ``nulls_last()`` operator is
| renamed from ``nullslast()`` in previous releases.
| The previous name remains available for backwards compatibility.
|
| nullsfirst = nulls_first(self) -> 'ColumnOperators'
|
| nullslast = nulls_last(self) -> 'ColumnOperators'
|
| regexp_match(self, pattern: 'Any', flags: 'Optional[str]' = None) -> 'ColumnOperators'
| Implements a database-specific 'regexp match' operator.
|
| E.g.::
|
| stmt = select(table.c.some_column).where(
| table.c.some_column.regexp_match("^(b|c)")
| )
|
| :meth:`_sql.ColumnOperators.regexp_match` attempts to resolve to
| a REGEXP-like function or operator provided by the backend, however
| the specific regular expression syntax and flags available are
| **not backend agnostic**.
|
| Examples include:
|
| * PostgreSQL - renders ``x ~ y`` or ``x !~ y`` when negated.
| * Oracle Database - renders ``REGEXP_LIKE(x, y)``
| * SQLite - uses SQLite's ``REGEXP`` placeholder operator and calls into
| the Python ``re.match()`` builtin.
| * other backends may provide special implementations.
| * Backends without any special implementation will emit
| the operator as "REGEXP" or "NOT REGEXP". This is compatible with
| SQLite and MySQL, for example.
|
| Regular expression support is currently implemented for Oracle
| Database, PostgreSQL, MySQL and MariaDB. Partial support is available
| for SQLite. Support among third-party dialects may vary.
|
| :param pattern: The regular expression pattern string or column
| clause.
| :param flags: Any regular expression string flags to apply, passed as
| plain Python string only. These flags are backend specific.
| Some backends, like PostgreSQL and MariaDB, may alternatively
| specify the flags as part of the pattern.
| When using the ignore case flag 'i' in PostgreSQL, the ignore case
| regexp match operator ``~*`` or ``!~*`` will be used.
|
| .. versionadded:: 1.4
|
| .. versionchanged:: 1.4.48, 2.0.18 Note that due to an implementation
| error, the "flags" parameter previously accepted SQL expression
| objects such as column expressions in addition to plain Python
| strings. This implementation did not work correctly with caching
| and was removed; strings only should be passed for the "flags"
| parameter, as these flags are rendered as literal inline values
| within SQL expressions.
|
| .. seealso::
|
| :meth:`_sql.ColumnOperators.regexp_replace`
|
| regexp_replace(self, pattern: 'Any', replacement: 'Any', flags: 'Optional[str]' = None) -> 'ColumnOperators'
| Implements a database-specific 'regexp replace' operator.
|
| E.g.::
|
| stmt = select(
| table.c.some_column.regexp_replace("b(..)", "XY", flags="g")
| )
|
| :meth:`_sql.ColumnOperators.regexp_replace` attempts to resolve to
| a REGEXP_REPLACE-like function provided by the backend, that
| usually emit the function ``REGEXP_REPLACE()``. However,
| the specific regular expression syntax and flags available are
| **not backend agnostic**.
|
| Regular expression replacement support is currently implemented for
| Oracle Database, PostgreSQL, MySQL 8 or greater and MariaDB. Support
| among third-party dialects may vary.
|
| :param pattern: The regular expression pattern string or column
| clause.
| :param pattern: The replacement string or column clause.
| :param flags: Any regular expression string flags to apply, passed as
| plain Python string only. These flags are backend specific.
| Some backends, like PostgreSQL and MariaDB, may alternatively
| specify the flags as part of the pattern.
|
| .. versionadded:: 1.4
|
| .. versionchanged:: 1.4.48, 2.0.18 Note that due to an implementation
| error, the "flags" parameter previously accepted SQL expression
| objects such as column expressions in addition to plain Python
| strings. This implementation did not work correctly with caching
| and was removed; strings only should be passed for the "flags"
| parameter, as these flags are rendered as literal inline values
| within SQL expressions.
|
|
| .. seealso::
|
| :meth:`_sql.ColumnOperators.regexp_match`
|
| startswith(self, other: 'Any', escape: 'Optional[str]' = None, autoescape: 'bool' = False) -> 'ColumnOperators'
| Implement the ``startswith`` operator.
|
| Produces a LIKE expression that tests against a match for the start
| of a string value:
|
| .. sourcecode:: sql
|
| column LIKE <other> || '%'
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.startswith("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.startswith.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.startswith.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.startswith.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.startswith("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE :param || '%' ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.startswith("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE :param || '%' ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.startswith.autoescape`::
|
| somecolumn.startswith("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.endswith`
|
| :meth:`.ColumnOperators.contains`
|
| :meth:`.ColumnOperators.like`
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.operators.ColumnOperators:
|
| timetuple = None
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.operators.Operators:
|
| __and__(self, other: 'Any') -> 'Operators'
| Implement the ``&`` operator.
|
| When used with SQL expressions, results in an
| AND operation, equivalent to
| :func:`_expression.and_`, that is::
|
| a & b
|
| is equivalent to::
|
| from sqlalchemy import and_
|
| and_(a, b)
|
| Care should be taken when using ``&`` regarding
| operator precedence; the ``&`` operator has the highest precedence.
| The operands should be enclosed in parenthesis if they contain
| further sub expressions::
|
| (a == 2) & (b == 4)
|
| __invert__(self) -> 'Operators'
| Implement the ``~`` operator.
|
| When used with SQL expressions, results in a
| NOT operation, equivalent to
| :func:`_expression.not_`, that is::
|
| ~a
|
| is equivalent to::
|
| from sqlalchemy import not_
|
| not_(a)
|
| __or__(self, other: 'Any') -> 'Operators'
| Implement the ``|`` operator.
|
| When used with SQL expressions, results in an
| OR operation, equivalent to
| :func:`_expression.or_`, that is::
|
| a | b
|
| is equivalent to::
|
| from sqlalchemy import or_
|
| or_(a, b)
|
| Care should be taken when using ``|`` regarding
| operator precedence; the ``|`` operator has the highest precedence.
| The operands should be enclosed in parenthesis if they contain
| further sub expressions::
|
| (a == 2) | (b == 4)
|
| __sa_operate__ = operate(self, op: 'OperatorType', *other: 'Any', **kwargs: 'Any') -> 'Operators'
| Operate on an argument.
|
| This is the lowest level of operation, raises
| :class:`NotImplementedError` by default.
|
| Overriding this on a subclass can allow common
| behavior to be applied to all operations.
| For example, overriding :class:`.ColumnOperators`
| to apply ``func.lower()`` to the left and right
| side::
|
| class MyComparator(ColumnOperators):
| def operate(self, op, other, **kwargs):
| return op(func.lower(self), func.lower(other), **kwargs)
|
| :param op: Operator callable.
| :param \*other: the 'other' side of the operation. Will
| be a single scalar for most operations.
| :param \**kwargs: modifiers. These may be passed by special
| operators such as :meth:`ColumnOperators.contains`.
|
| bool_op(self, opstring: 'str', precedence: 'int' = 0, python_impl: 'Optional[Callable[..., Any]]' = None) -> 'Callable[[Any], Operators]'
| Return a custom boolean operator.
|
| This method is shorthand for calling
| :meth:`.Operators.op` and passing the
| :paramref:`.Operators.op.is_comparison`
| flag with True. A key advantage to using :meth:`.Operators.bool_op`
| is that when using column constructs, the "boolean" nature of the
| returned expression will be present for :pep:`484` purposes.
|
| .. seealso::
|
| :meth:`.Operators.op`
|
| op(self, opstring: 'str', precedence: 'int' = 0, is_comparison: 'bool' = False, return_type: 'Optional[Union[Type[TypeEngine[Any]], TypeEngine[Any]]]' = None, python_impl: 'Optional[Callable[..., Any]]' = None) -> 'Callable[[Any], Operators]'
| Produce a generic operator function.
|
| e.g.::
|
| somecolumn.op("*")(5)
|
| produces::
|
| somecolumn * 5
|
| This function can also be used to make bitwise operators explicit. For
| example::
|
| somecolumn.op("&")(0xFF)
|
| is a bitwise AND of the value in ``somecolumn``.
|
| :param opstring: a string which will be output as the infix operator
| between this element and the expression passed to the
| generated function.
|
| :param precedence: precedence which the database is expected to apply
| to the operator in SQL expressions. This integer value acts as a hint
| for the SQL compiler to know when explicit parenthesis should be
| rendered around a particular operation. A lower number will cause the
| expression to be parenthesized when applied against another operator
| with higher precedence. The default value of ``0`` is lower than all
| operators except for the comma (``,``) and ``AS`` operators. A value
| of 100 will be higher or equal to all operators, and -100 will be
| lower than or equal to all operators.
|
| .. seealso::
|
| :ref:`faq_sql_expression_op_parenthesis` - detailed description
| of how the SQLAlchemy SQL compiler renders parenthesis
|
| :param is_comparison: legacy; if True, the operator will be considered
| as a "comparison" operator, that is which evaluates to a boolean
| true/false value, like ``==``, ``>``, etc. This flag is provided
| so that ORM relationships can establish that the operator is a
| comparison operator when used in a custom join condition.
|
| Using the ``is_comparison`` parameter is superseded by using the
| :meth:`.Operators.bool_op` method instead; this more succinct
| operator sets this parameter automatically, but also provides
| correct :pep:`484` typing support as the returned object will
| express a "boolean" datatype, i.e. ``BinaryExpression[bool]``.
|
| :param return_type: a :class:`.TypeEngine` class or object that will
| force the return type of an expression produced by this operator
| to be of that type. By default, operators that specify
| :paramref:`.Operators.op.is_comparison` will resolve to
| :class:`.Boolean`, and those that do not will be of the same
| type as the left-hand operand.
|
| :param python_impl: an optional Python function that can evaluate
| two Python values in the same way as this operator works when
| run on the database server. Useful for in-Python SQL expression
| evaluation functions, such as for ORM hybrid attributes, and the
| ORM "evaluator" used to match objects in a session after a multi-row
| update or delete.
|
| e.g.::
|
| >>> expr = column("x").op("+", python_impl=lambda a, b: a + b)("y")
|
| The operator for the above expression will also work for non-SQL
| left and right objects::
|
| >>> expr.operator(5, 10)
| 15
|
| .. versionadded:: 2.0
|
|
| .. seealso::
|
| :meth:`.Operators.bool_op`
|
| :ref:`types_operators`
|
| :ref:`relationship_custom_operator`
|
| ----------------------------------------------------------------------
| Methods inherited from ClauseElement:
|
| __bool__(self)
|
| __getstate__(self)
| Helper for pickle.
|
| __repr__(self)
| Return repr(self).
|
| compare(self, other: 'ClauseElement', **kw: 'Any') -> 'bool'
| Compare this :class:`_expression.ClauseElement` to
| the given :class:`_expression.ClauseElement`.
|
| Subclasses should override the default behavior, which is a
| straight identity comparison.
|
| \**kw are arguments consumed by subclass ``compare()`` methods and
| may be used to modify the criteria for comparison
| (see :class:`_expression.ColumnElement`).
|
| description(...)
|
| entity_namespace(...)
|
| params(self, _ClauseElement__optionaldict: 'Optional[Mapping[str, Any]]' = None, **kwargs: 'Any') -> 'Self'
| Return a copy with :func:`_expression.bindparam` elements
| replaced.
|
| Returns a copy of this ClauseElement with
| :func:`_expression.bindparam`
| elements replaced with values taken from the given dictionary::
|
| >>> clause = column("x") + bindparam("foo")
| >>> print(clause.compile().params)
| {'foo':None}
| >>> print(clause.params({"foo": 7}).compile().params)
| {'foo':7}
|
| unique_params(self, _ClauseElement__optionaldict: 'Optional[Dict[str, Any]]' = None, **kwargs: 'Any') -> 'Self'
| Return a copy with :func:`_expression.bindparam` elements
| replaced.
|
| Same functionality as :meth:`_expression.ClauseElement.params`,
| except adds `unique=True`
| to affected bind parameters so that multiple statements can be
| used.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from ClauseElement:
|
| is_clause_element = True
|
| is_dml = False
|
| is_selectable = False
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_instancemethod(fn: '_F') -> '_F'
| Decorate a method memoize its return value.
|
| :meta private:
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_attribute = <class 'sqlalchemy.util.langhelpers.HasMemoized.m...
| A read-only @property that is only evaluated once.
|
| :meta private:
|
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.visitors.HasTraverseInternals:
|
| get_children(self, *, omit_attrs: 'Tuple[str, ...]' = (), **kw: 'Any') -> 'Iterable[HasTraverseInternals]'
| Return immediate child :class:`.visitors.HasTraverseInternals`
| elements of this :class:`.visitors.HasTraverseInternals`.
|
| This is used for visit traversal.
|
| \**kw may contain flags that change the collection that is
| returned, for example to return a subset of items in order to
| cut down on larger traversals, or to return child items from a
| different context (such as schema-level collections instead of
| clause-level).
|
| ----------------------------------------------------------------------
| Methods inherited from CompilerElement:
|
| __str__(self) -> 'str'
| Return str(self).
|
| compile(self, bind: 'Optional[_HasDialect]' = None, dialect: 'Optional[Dialect]' = None, **kw: 'Any') -> 'Compiled'
| Compile this SQL expression.
|
| The return value is a :class:`~.Compiled` object.
| Calling ``str()`` or ``unicode()`` on the returned value will yield a
| string representation of the result. The
| :class:`~.Compiled` object also can return a
| dictionary of bind parameter names and values
| using the ``params`` accessor.
|
| :param bind: An :class:`.Connection` or :class:`.Engine` which
| can provide a :class:`.Dialect` in order to generate a
| :class:`.Compiled` object. If the ``bind`` and
| ``dialect`` parameters are both omitted, a default SQL compiler
| is used.
|
| :param column_keys: Used for INSERT and UPDATE statements, a list of
| column names which should be present in the VALUES clause of the
| compiled statement. If ``None``, all columns from the target table
| object are rendered.
|
| :param dialect: A :class:`.Dialect` instance which can generate
| a :class:`.Compiled` object. This argument takes precedence over
| the ``bind`` argument.
|
| :param compile_kwargs: optional dictionary of additional parameters
| that will be passed through to the compiler within all "visit"
| methods. This allows any custom flag to be passed through to
| a custom compilation construct, for example. It is also used
| for the case of passing the ``literal_binds`` flag through::
|
| from sqlalchemy.sql import table, column, select
|
| t = table("t", column("x"))
|
| s = select(t).where(t.c.x == 5)
|
| print(s.compile(compile_kwargs={"literal_binds": True}))
|
| .. seealso::
|
| :ref:`faq_sql_expression_string`
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from CompilerElement:
|
| stringify_dialect = 'default'
|
| supports_execution = False
sqlalchemy.Column
Python Library Documentation: class Column in module sqlalchemy.sql.schema
class Column(sqlalchemy.sql.base.DialectKWArgs, SchemaItem, sqlalchemy.sql.elements.ColumnClause)
| Column(_Column__name_pos: 'Optional[Union[str, _TypeEngineArgument[_T], SchemaEventTarget]]' = None, _Column__type_pos: 'Optional[Union[_TypeEngineArgument[_T], SchemaEventTarget]]' = None, *args: 'SchemaEventTarget', name: 'Optional[str]' = None, type_: 'Optional[_TypeEngineArgument[_T]]' = None, autoincrement: '_AutoIncrementType' = 'auto', default: 'Optional[Any]' = _NoArg.NO_ARG, insert_default: 'Optional[Any]' = _NoArg.NO_ARG, doc: 'Optional[str]' = None, key: 'Optional[str]' = None, index: 'Optional[bool]' = None, unique: 'Optional[bool]' = None, info: 'Optional[_InfoType]' = None, nullable: 'Optional[Union[bool, Literal[SchemaConst.NULL_UNSPECIFIED]]]' = <SchemaConst.NULL_UNSPECIFIED: 3>, onupdate: 'Optional[Any]' = None, primary_key: 'bool' = False, server_default: 'Optional[_ServerDefaultArgument]' = None, server_onupdate: 'Optional[_ServerOnUpdateArgument]' = None, quote: 'Optional[bool]' = None, system: 'bool' = False, comment: 'Optional[str]' = None, insert_sentinel: 'bool' = False, _omit_from_statements: 'bool' = False, _proxies: 'Optional[Any]' = None, **dialect_kwargs: 'Any')
|
| Represents a column in a database table.
|
| Method resolution order:
| Column
| sqlalchemy.sql.base.DialectKWArgs
| SchemaItem
| sqlalchemy.sql.base.SchemaVisitable
| sqlalchemy.sql.base.SchemaEventTarget
| sqlalchemy.event.registry.EventTarget
| sqlalchemy.sql.elements.ColumnClause
| sqlalchemy.sql.roles.DDLReferredColumnRole
| sqlalchemy.sql.roles.LabeledColumnExprRole
| sqlalchemy.sql.roles.StrAsPlainColumnRole
| sqlalchemy.sql.base.Immutable
| sqlalchemy.sql.elements.NamedColumn
| sqlalchemy.sql.elements.KeyedColumnElement
| sqlalchemy.sql.elements.ColumnElement
| sqlalchemy.sql.roles.ColumnArgumentOrKeyRole
| sqlalchemy.sql.roles.ColumnArgumentRole
| sqlalchemy.sql.roles.StatementOptionRole
| sqlalchemy.sql.roles.WhereHavingRole
| sqlalchemy.sql.roles.OnClauseRole
| sqlalchemy.sql.roles.BinaryElementRole
| sqlalchemy.sql.roles.OrderByRole
| sqlalchemy.sql.roles.ColumnsClauseRole
| sqlalchemy.sql.roles.AllowsLambdaRole
| sqlalchemy.sql.roles.ByOfRole
| sqlalchemy.sql.roles.UsesInspection
| sqlalchemy.sql.roles.ColumnListRole
| sqlalchemy.sql.roles.LimitOffsetRole
| sqlalchemy.sql.roles.DMLColumnRole
| sqlalchemy.sql.roles.DDLConstraintColumnRole
| sqlalchemy.sql.roles.DDLExpressionRole
| sqlalchemy.sql.roles.StructuralRole
| sqlalchemy.sql.elements.SQLColumnExpression
| sqlalchemy.sql.elements.SQLCoreOperations
| sqlalchemy.sql.roles.ExpressionElementRole
| sqlalchemy.sql.roles.TypedColumnsClauseRole
| typing.Generic
| sqlalchemy.sql.operators.ColumnOperators
| sqlalchemy.sql.operators.Operators
| sqlalchemy.util.langhelpers.TypingOnly
| sqlalchemy.sql.roles.SQLRole
| sqlalchemy.sql.elements.DQLDMLClauseElement
| sqlalchemy.sql.elements.ClauseElement
| sqlalchemy.sql.annotation.SupportsWrappingAnnotations
| sqlalchemy.sql.annotation.SupportsAnnotations
| sqlalchemy.sql.cache_key.MemoizedHasCacheKey
| sqlalchemy.sql.cache_key.HasCacheKey
| sqlalchemy.util.langhelpers.HasMemoized
| sqlalchemy.sql.traversals.HasCopyInternals
| sqlalchemy.sql.visitors.ExternallyTraversible
| sqlalchemy.sql.visitors.HasTraverseInternals
| sqlalchemy.sql.elements.CompilerElement
| sqlalchemy.sql.visitors.Visitable
| builtins.object
|
| Methods defined here:
|
| __init__(self, _Column__name_pos: 'Optional[Union[str, _TypeEngineArgument[_T], SchemaEventTarget]]' = None, _Column__type_pos: 'Optional[Union[_TypeEngineArgument[_T], SchemaEventTarget]]' = None, *args: 'SchemaEventTarget', name: 'Optional[str]' = None, type_: 'Optional[_TypeEngineArgument[_T]]' = None, autoincrement: '_AutoIncrementType' = 'auto', default: 'Optional[Any]' = _NoArg.NO_ARG, insert_default: 'Optional[Any]' = _NoArg.NO_ARG, doc: 'Optional[str]' = None, key: 'Optional[str]' = None, index: 'Optional[bool]' = None, unique: 'Optional[bool]' = None, info: 'Optional[_InfoType]' = None, nullable: 'Optional[Union[bool, Literal[SchemaConst.NULL_UNSPECIFIED]]]' = <SchemaConst.NULL_UNSPECIFIED: 3>, onupdate: 'Optional[Any]' = None, primary_key: 'bool' = False, server_default: 'Optional[_ServerDefaultArgument]' = None, server_onupdate: 'Optional[_ServerOnUpdateArgument]' = None, quote: 'Optional[bool]' = None, system: 'bool' = False, comment: 'Optional[str]' = None, insert_sentinel: 'bool' = False, _omit_from_statements: 'bool' = False, _proxies: 'Optional[Any]' = None, **dialect_kwargs: 'Any')
| Construct a new ``Column`` object.
|
| :param name: The name of this column as represented in the database.
| This argument may be the first positional argument, or specified
| via keyword.
|
| Names which contain no upper case characters
| will be treated as case insensitive names, and will not be quoted
| unless they are a reserved word. Names with any number of upper
| case characters will be quoted and sent exactly. Note that this
| behavior applies even for databases which standardize upper
| case names as case insensitive such as Oracle Database.
|
| The name field may be omitted at construction time and applied
| later, at any time before the Column is associated with a
| :class:`_schema.Table`. This is to support convenient
| usage within the :mod:`~sqlalchemy.ext.declarative` extension.
|
| :param type\_: The column's type, indicated using an instance which
| subclasses :class:`~sqlalchemy.types.TypeEngine`. If no arguments
| are required for the type, the class of the type can be sent
| as well, e.g.::
|
| # use a type with arguments
| Column("data", String(50))
|
| # use no arguments
| Column("level", Integer)
|
| The ``type`` argument may be the second positional argument
| or specified by keyword.
|
| If the ``type`` is ``None`` or is omitted, it will first default to
| the special type :class:`.NullType`. If and when this
| :class:`_schema.Column` is made to refer to another column using
| :class:`_schema.ForeignKey` and/or
| :class:`_schema.ForeignKeyConstraint`, the type
| of the remote-referenced column will be copied to this column as
| well, at the moment that the foreign key is resolved against that
| remote :class:`_schema.Column` object.
|
| :param \*args: Additional positional arguments include various
| :class:`.SchemaItem` derived constructs which will be applied
| as options to the column. These include instances of
| :class:`.Constraint`, :class:`_schema.ForeignKey`,
| :class:`.ColumnDefault`, :class:`.Sequence`, :class:`.Computed`
| :class:`.Identity`. In some cases an
| equivalent keyword argument is available such as ``server_default``,
| ``default`` and ``unique``.
|
| :param autoincrement: Set up "auto increment" semantics for an
| **integer primary key column with no foreign key dependencies**
| (see later in this docstring for a more specific definition).
| This may influence the :term:`DDL` that will be emitted for
| this column during a table create, as well as how the column
| will be considered when INSERT statements are compiled and
| executed.
|
| The default value is the string ``"auto"``,
| which indicates that a single-column (i.e. non-composite) primary key
| that is of an INTEGER type with no other client-side or server-side
| default constructs indicated should receive auto increment semantics
| automatically. Other values include ``True`` (force this column to
| have auto-increment semantics for a :term:`composite primary key` as
| well), ``False`` (this column should never have auto-increment
| semantics), and the string ``"ignore_fk"`` (special-case for foreign
| key columns, see below).
|
| The term "auto increment semantics" refers both to the kind of DDL
| that will be emitted for the column within a CREATE TABLE statement,
| when methods such as :meth:`.MetaData.create_all` and
| :meth:`.Table.create` are invoked, as well as how the column will be
| considered when an INSERT statement is compiled and emitted to the
| database:
|
| * **DDL rendering** (i.e. :meth:`.MetaData.create_all`,
| :meth:`.Table.create`): When used on a :class:`.Column` that has
| no other
| default-generating construct associated with it (such as a
| :class:`.Sequence` or :class:`.Identity` construct), the parameter
| will imply that database-specific keywords such as PostgreSQL
| ``SERIAL``, MySQL ``AUTO_INCREMENT``, or ``IDENTITY`` on SQL Server
| should also be rendered. Not every database backend has an
| "implied" default generator available; for example the Oracle Database
| backends always needs an explicit construct such as
| :class:`.Identity` to be included with a :class:`.Column` in order
| for the DDL rendered to include auto-generating constructs to also
| be produced in the database.
|
| * **INSERT semantics** (i.e. when a :func:`_sql.insert` construct is
| compiled into a SQL string and is then executed on a database using
| :meth:`_engine.Connection.execute` or equivalent): A single-row
| INSERT statement will be known to produce a new integer primary key
| value automatically for this column, which will be accessible
| after the statement is invoked via the
| :attr:`.CursorResult.inserted_primary_key` attribute upon the
| :class:`_result.Result` object. This also applies towards use of the
| ORM when ORM-mapped objects are persisted to the database,
| indicating that a new integer primary key will be available to
| become part of the :term:`identity key` for that object. This
| behavior takes place regardless of what DDL constructs are
| associated with the :class:`_schema.Column` and is independent
| of the "DDL Rendering" behavior discussed in the previous note
| above.
|
| The parameter may be set to ``True`` to indicate that a column which
| is part of a composite (i.e. multi-column) primary key should
| have autoincrement semantics, though note that only one column
| within a primary key may have this setting. It can also
| be set to ``True`` to indicate autoincrement semantics on a
| column that has a client-side or server-side default configured,
| however note that not all dialects can accommodate all styles
| of default as an "autoincrement". It can also be
| set to ``False`` on a single-column primary key that has a
| datatype of INTEGER in order to disable auto increment semantics
| for that column.
|
| The setting *only* has an effect for columns which are:
|
| * Integer derived (i.e. INT, SMALLINT, BIGINT).
|
| * Part of the primary key
|
| * Not referring to another column via :class:`_schema.ForeignKey`,
| unless
| the value is specified as ``'ignore_fk'``::
|
| # turn on autoincrement for this column despite
| # the ForeignKey()
| Column(
| "id",
| ForeignKey("other.id"),
| primary_key=True,
| autoincrement="ignore_fk",
| )
|
| It is typically not desirable to have "autoincrement" enabled on a
| column that refers to another via foreign key, as such a column is
| required to refer to a value that originates from elsewhere.
|
| The setting has these effects on columns that meet the
| above criteria:
|
| * DDL issued for the column, if the column does not already include
| a default generating construct supported by the backend such as
| :class:`.Identity`, will include database-specific
| keywords intended to signify this column as an
| "autoincrement" column for specific backends. Behavior for
| primary SQLAlchemy dialects includes:
|
| * AUTO INCREMENT on MySQL and MariaDB
| * SERIAL on PostgreSQL
| * IDENTITY on MS-SQL - this occurs even without the
| :class:`.Identity` construct as the
| :paramref:`.Column.autoincrement` parameter pre-dates this
| construct.
| * SQLite - SQLite integer primary key columns are implicitly
| "auto incrementing" and no additional keywords are rendered;
| to render the special SQLite keyword ``AUTOINCREMENT``
| is not included as this is unnecessary and not recommended
| by the database vendor. See the section
| :ref:`sqlite_autoincrement` for more background.
| * Oracle Database - The Oracle Database dialects have no default "autoincrement"
| feature available at this time, instead the :class:`.Identity`
| construct is recommended to achieve this (the :class:`.Sequence`
| construct may also be used).
| * Third-party dialects - consult those dialects' documentation
| for details on their specific behaviors.
|
| * When a single-row :func:`_sql.insert` construct is compiled and
| executed, which does not set the :meth:`_sql.Insert.inline`
| modifier, newly generated primary key values for this column
| will be automatically retrieved upon statement execution
| using a method specific to the database driver in use:
|
| * MySQL, SQLite - calling upon ``cursor.lastrowid()``
| (see
| `https://www.python.org/dev/peps/pep-0249/#lastrowid
| <https://www.python.org/dev/peps/pep-0249/#lastrowid>`_)
| * PostgreSQL, SQL Server, Oracle Database - use RETURNING or an equivalent
| construct when rendering an INSERT statement, and then retrieving
| the newly generated primary key values after execution
| * PostgreSQL, Oracle Database for :class:`_schema.Table` objects that
| set :paramref:`_schema.Table.implicit_returning` to False -
| for a :class:`.Sequence` only, the :class:`.Sequence` is invoked
| explicitly before the INSERT statement takes place so that the
| newly generated primary key value is available to the client
| * SQL Server for :class:`_schema.Table` objects that
| set :paramref:`_schema.Table.implicit_returning` to False -
| the ``SELECT scope_identity()`` construct is used after the
| INSERT statement is invoked to retrieve the newly generated
| primary key value.
| * Third-party dialects - consult those dialects' documentation
| for details on their specific behaviors.
|
| * For multiple-row :func:`_sql.insert` constructs invoked with
| a list of parameters (i.e. "executemany" semantics), primary-key
| retrieving behaviors are generally disabled, however there may
| be special APIs that may be used to retrieve lists of new
| primary key values for an "executemany", such as the psycopg2
| "fast insertmany" feature. Such features are very new and
| may not yet be well covered in documentation.
|
| :param default: A scalar, Python callable, or
| :class:`_expression.ColumnElement` expression representing the
| *default value* for this column, which will be invoked upon insert
| if this column is otherwise not specified in the VALUES clause of
| the insert. This is a shortcut to using :class:`.ColumnDefault` as
| a positional argument; see that class for full detail on the
| structure of the argument.
|
| Contrast this argument to
| :paramref:`_schema.Column.server_default`
| which creates a default generator on the database side.
|
| .. seealso::
|
| :ref:`metadata_defaults_toplevel`
|
| :param insert_default: An alias of :paramref:`.Column.default`
| for compatibility with :func:`_orm.mapped_column`.
|
| .. versionadded: 2.0.31
|
| :param doc: optional String that can be used by the ORM or similar
| to document attributes on the Python side. This attribute does
| **not** render SQL comments; use the
| :paramref:`_schema.Column.comment`
| parameter for this purpose.
|
| :param key: An optional string identifier which will identify this
| ``Column`` object on the :class:`_schema.Table`.
| When a key is provided,
| this is the only identifier referencing the ``Column`` within the
| application, including ORM attribute mapping; the ``name`` field
| is used only when rendering SQL.
|
| :param index: When ``True``, indicates that a :class:`_schema.Index`
| construct will be automatically generated for this
| :class:`_schema.Column`, which will result in a "CREATE INDEX"
| statement being emitted for the :class:`_schema.Table` when the DDL
| create operation is invoked.
|
| Using this flag is equivalent to making use of the
| :class:`_schema.Index` construct explicitly at the level of the
| :class:`_schema.Table` construct itself::
|
| Table(
| "some_table",
| metadata,
| Column("x", Integer),
| Index("ix_some_table_x", "x"),
| )
|
| To add the :paramref:`_schema.Index.unique` flag to the
| :class:`_schema.Index`, set both the
| :paramref:`_schema.Column.unique` and
| :paramref:`_schema.Column.index` flags to True simultaneously,
| which will have the effect of rendering the "CREATE UNIQUE INDEX"
| DDL instruction instead of "CREATE INDEX".
|
| The name of the index is generated using the
| :ref:`default naming convention <constraint_default_naming_convention>`
| which for the :class:`_schema.Index` construct is of the form
| ``ix_<tablename>_<columnname>``.
|
| As this flag is intended only as a convenience for the common case
| of adding a single-column, default configured index to a table
| definition, explicit use of the :class:`_schema.Index` construct
| should be preferred for most use cases, including composite indexes
| that encompass more than one column, indexes with SQL expressions
| or ordering, backend-specific index configuration options, and
| indexes that use a specific name.
|
| .. note:: the :attr:`_schema.Column.index` attribute on
| :class:`_schema.Column`
| **does not indicate** if this column is indexed or not, only
| if this flag was explicitly set here. To view indexes on
| a column, view the :attr:`_schema.Table.indexes` collection
| or use :meth:`_reflection.Inspector.get_indexes`.
|
| .. seealso::
|
| :ref:`schema_indexes`
|
| :ref:`constraint_naming_conventions`
|
| :paramref:`_schema.Column.unique`
|
| :param info: Optional data dictionary which will be populated into the
| :attr:`.SchemaItem.info` attribute of this object.
|
| :param nullable: When set to ``False``, will cause the "NOT NULL"
| phrase to be added when generating DDL for the column. When
| ``True``, will normally generate nothing (in SQL this defaults to
| "NULL"), except in some very specific backend-specific edge cases
| where "NULL" may render explicitly.
| Defaults to ``True`` unless :paramref:`_schema.Column.primary_key`
| is also ``True`` or the column specifies a :class:`_sql.Identity`,
| in which case it defaults to ``False``.
| This parameter is only used when issuing CREATE TABLE statements.
|
| .. note::
|
| When the column specifies a :class:`_sql.Identity` this
| parameter is in general ignored by the DDL compiler. The
| PostgreSQL database allows nullable identity column by
| setting this parameter to ``True`` explicitly.
|
| :param onupdate: A scalar, Python callable, or
| :class:`~sqlalchemy.sql.expression.ClauseElement` representing a
| default value to be applied to the column within UPDATE
| statements, which will be invoked upon update if this column is not
| present in the SET clause of the update. This is a shortcut to
| using :class:`.ColumnDefault` as a positional argument with
| ``for_update=True``.
|
| .. seealso::
|
| :ref:`metadata_defaults` - complete discussion of onupdate
|
| :param primary_key: If ``True``, marks this column as a primary key
| column. Multiple columns can have this flag set to specify
| composite primary keys. As an alternative, the primary key of a
| :class:`_schema.Table` can be specified via an explicit
| :class:`.PrimaryKeyConstraint` object.
|
| :param server_default: A :class:`.FetchedValue` instance, str, Unicode
| or :func:`~sqlalchemy.sql.expression.text` construct representing
| the DDL DEFAULT value for the column.
|
| String types will be emitted as-is, surrounded by single quotes::
|
| Column("x", Text, server_default="val")
|
| will render:
|
| .. sourcecode:: sql
|
| x TEXT DEFAULT 'val'
|
| A :func:`~sqlalchemy.sql.expression.text` expression will be
| rendered as-is, without quotes::
|
| Column("y", DateTime, server_default=text("NOW()"))
|
| will render:
|
| .. sourcecode:: sql
|
| y DATETIME DEFAULT NOW()
|
| Strings and text() will be converted into a
| :class:`.DefaultClause` object upon initialization.
|
| This parameter can also accept complex combinations of contextually
| valid SQLAlchemy expressions or constructs::
|
| from sqlalchemy import create_engine
| from sqlalchemy import Table, Column, MetaData, ARRAY, Text
| from sqlalchemy.dialects.postgresql import array
|
| engine = create_engine(
| "postgresql+psycopg2://scott:tiger@localhost/mydatabase"
| )
| metadata_obj = MetaData()
| tbl = Table(
| "foo",
| metadata_obj,
| Column(
| "bar", ARRAY(Text), server_default=array(["biz", "bang", "bash"])
| ),
| )
| metadata_obj.create_all(engine)
|
| The above results in a table created with the following SQL:
|
| .. sourcecode:: sql
|
| CREATE TABLE foo (
| bar TEXT[] DEFAULT ARRAY['biz', 'bang', 'bash']
| )
|
| Use :class:`.FetchedValue` to indicate that an already-existing
| column will generate a default value on the database side which
| will be available to SQLAlchemy for post-fetch after inserts. This
| construct does not specify any DDL and the implementation is left
| to the database, such as via a trigger.
|
| .. seealso::
|
| :ref:`server_defaults` - complete discussion of server side
| defaults
|
| :param server_onupdate: A :class:`.FetchedValue` instance
| representing a database-side default generation function,
| such as a trigger. This
| indicates to SQLAlchemy that a newly generated value will be
| available after updates. This construct does not actually
| implement any kind of generation function within the database,
| which instead must be specified separately.
|
|
| .. warning:: This directive **does not** currently produce MySQL's
| "ON UPDATE CURRENT_TIMESTAMP()" clause. See
| :ref:`mysql_timestamp_onupdate` for background on how to
| produce this clause.
|
| .. seealso::
|
| :ref:`triggered_columns`
|
| :param quote: Force quoting of this column's name on or off,
| corresponding to ``True`` or ``False``. When left at its default
| of ``None``, the column identifier will be quoted according to
| whether the name is case sensitive (identifiers with at least one
| upper case character are treated as case sensitive), or if it's a
| reserved word. This flag is only needed to force quoting of a
| reserved word which is not known by the SQLAlchemy dialect.
|
| :param unique: When ``True``, and the :paramref:`_schema.Column.index`
| parameter is left at its default value of ``False``,
| indicates that a :class:`_schema.UniqueConstraint`
| construct will be automatically generated for this
| :class:`_schema.Column`,
| which will result in a "UNIQUE CONSTRAINT" clause referring
| to this column being included
| in the ``CREATE TABLE`` statement emitted, when the DDL create
| operation for the :class:`_schema.Table` object is invoked.
|
| When this flag is ``True`` while the
| :paramref:`_schema.Column.index` parameter is simultaneously
| set to ``True``, the effect instead is that a
| :class:`_schema.Index` construct which includes the
| :paramref:`_schema.Index.unique` parameter set to ``True``
| is generated. See the documentation for
| :paramref:`_schema.Column.index` for additional detail.
|
| Using this flag is equivalent to making use of the
| :class:`_schema.UniqueConstraint` construct explicitly at the
| level of the :class:`_schema.Table` construct itself::
|
| Table("some_table", metadata, Column("x", Integer), UniqueConstraint("x"))
|
| The :paramref:`_schema.UniqueConstraint.name` parameter
| of the unique constraint object is left at its default value
| of ``None``; in the absence of a :ref:`naming convention <constraint_naming_conventions>`
| for the enclosing :class:`_schema.MetaData`, the UNIQUE CONSTRAINT
| construct will be emitted as unnamed, which typically invokes
| a database-specific naming convention to take place.
|
| As this flag is intended only as a convenience for the common case
| of adding a single-column, default configured unique constraint to a table
| definition, explicit use of the :class:`_schema.UniqueConstraint` construct
| should be preferred for most use cases, including composite constraints
| that encompass more than one column, backend-specific index configuration options, and
| constraints that use a specific name.
|
| .. note:: the :attr:`_schema.Column.unique` attribute on
| :class:`_schema.Column`
| **does not indicate** if this column has a unique constraint or
| not, only if this flag was explicitly set here. To view
| indexes and unique constraints that may involve this column,
| view the
| :attr:`_schema.Table.indexes` and/or
| :attr:`_schema.Table.constraints` collections or use
| :meth:`_reflection.Inspector.get_indexes` and/or
| :meth:`_reflection.Inspector.get_unique_constraints`
|
| .. seealso::
|
| :ref:`schema_unique_constraint`
|
| :ref:`constraint_naming_conventions`
|
| :paramref:`_schema.Column.index`
|
| :param system: When ``True``, indicates this is a "system" column,
| that is a column which is automatically made available by the
| database, and should not be included in the columns list for a
| ``CREATE TABLE`` statement.
|
| For more elaborate scenarios where columns should be
| conditionally rendered differently on different backends,
| consider custom compilation rules for :class:`.CreateColumn`.
|
| :param comment: Optional string that will render an SQL comment on
| table creation.
|
| .. versionadded:: 1.2 Added the
| :paramref:`_schema.Column.comment`
| parameter to :class:`_schema.Column`.
|
| :param insert_sentinel: Marks this :class:`_schema.Column` as an
| :term:`insert sentinel` used for optimizing the performance of the
| :term:`insertmanyvalues` feature for tables that don't
| otherwise have qualifying primary key configurations.
|
| .. versionadded:: 2.0.10
|
| .. seealso::
|
| :func:`_schema.insert_sentinel` - all in one helper for declaring
| sentinel columns
|
| :ref:`engine_insertmanyvalues`
|
| :ref:`engine_insertmanyvalues_sentinel_columns`
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| __str__(self) -> 'str'
| Return str(self).
|
| append_foreign_key(self, fk: 'ForeignKey') -> 'None'
|
| copy(self, **kw: 'Any') -> 'Column[Any]'
| .. deprecated:: 1.4 The :meth:`_schema.Column.copy` method is deprecated and will be removed in a future release.
|
| references(self, column: 'Column[Any]') -> 'bool'
| Return True if this Column references the given column via foreign
| key.
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'computed': 'Optional[Computed]', 'constraints': 'S...
|
| __orig_bases__ = (<class 'sqlalchemy.sql.base.DialectKWArgs'>, <class ...
|
| __parameters__ = (~_T,)
|
| __visit_name__ = 'column'
|
| inherit_cache = True
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.base.DialectKWArgs:
|
| dialect_options(...)
| A collection of keyword arguments specified as dialect-specific
| options to this construct.
|
| This is a two-level nested registry, keyed to ``<dialect_name>``
| and ``<argument_name>``. For example, the ``postgresql_where``
| argument would be locatable as::
|
| arg = my_object.dialect_options["postgresql"]["where"]
|
| .. versionadded:: 0.9.2
|
| .. seealso::
|
| :attr:`.DialectKWArgs.dialect_kwargs` - flat dictionary form
|
| get_dialect_option(self, dialect: 'Dialect', argument_name: 'str', *, else_: 'Any' = None, deprecated_fallback: 'Optional[str]' = None) -> 'Any'
| Return the value of a dialect-specific option, or *else_* if
| this dialect does not register the given argument.
|
| This is useful for DDL compilers that may be inherited by
| third-party dialects whose ``construct_arguments`` do not
| include the same set of keys as the parent dialect.
|
| :param dialect: The dialect for which to retrieve the option.
| :param argument_name: The name of the argument to retrieve.
| :param else\_: The value to return if the argument is not present.
| :param deprecated_fallback: Optional dialect name to fall back to
| if the argument is not present for the current dialect. If the
| argument is present for the fallback dialect but not the current
| dialect, a deprecation warning will be emitted.
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.base.DialectKWArgs:
|
| argument_for(dialect_name: 'str', argument_name: 'str', default: 'Any') -> 'None'
| Add a new kind of dialect-specific keyword argument for this class.
|
| E.g.::
|
| Index.argument_for("mydialect", "length", None)
|
| some_index = Index("a", "b", mydialect_length=5)
|
| The :meth:`.DialectKWArgs.argument_for` method is a per-argument
| way adding extra arguments to the
| :attr:`.DefaultDialect.construct_arguments` dictionary. This
| dictionary provides a list of argument names accepted by various
| schema-level constructs on behalf of a dialect.
|
| New dialects should typically specify this dictionary all at once as a
| data member of the dialect class. The use case for ad-hoc addition of
| argument names is typically for end-user code that is also using
| a custom compilation scheme which consumes the additional arguments.
|
| :param dialect_name: name of a dialect. The dialect must be
| locatable, else a :class:`.NoSuchModuleError` is raised. The
| dialect must also include an existing
| :attr:`.DefaultDialect.construct_arguments` collection, indicating
| that it participates in the keyword-argument validation and default
| system, else :class:`.ArgumentError` is raised. If the dialect does
| not include this collection, then any keyword argument can be
| specified on behalf of this dialect already. All dialects packaged
| within SQLAlchemy include this collection, however for third party
| dialects, support may vary.
|
| :param argument_name: name of the parameter.
|
| :param default: default value of the parameter.
|
| ----------------------------------------------------------------------
| Readonly properties inherited from sqlalchemy.sql.base.DialectKWArgs:
|
| dialect_kwargs
| A collection of keyword arguments specified as dialect-specific
| options to this construct.
|
| The arguments are present here in their original ``<dialect>_<kwarg>``
| format. Only arguments that were actually passed are included;
| unlike the :attr:`.DialectKWArgs.dialect_options` collection, which
| contains all options known by this dialect including defaults.
|
| The collection is also writable; keys are accepted of the
| form ``<dialect>_<kwarg>`` where the value will be assembled
| into the list of options.
|
| .. seealso::
|
| :attr:`.DialectKWArgs.dialect_options` - nested dictionary form
|
| kwargs
| A synonym for :attr:`.DialectKWArgs.dialect_kwargs`.
|
| ----------------------------------------------------------------------
| Methods inherited from SchemaItem:
|
| info(...)
| Info dictionary associated with the object, allowing user-defined
| data to be associated with this :class:`.SchemaItem`.
|
| The dictionary is automatically generated when first accessed.
| It can also be specified in the constructor of some objects,
| such as :class:`_schema.Table` and :class:`_schema.Column`.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from SchemaItem:
|
| create_drop_stringify_dialect = 'default'
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.base.SchemaEventTarget:
|
| dispatch = <sqlalchemy.event.base.DDLEventsDispatch object>
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.elements.ColumnClause:
|
| get_children(self, *, column_tables=False, **kw)
| Return immediate child :class:`.visitors.HasTraverseInternals`
| elements of this :class:`.visitors.HasTraverseInternals`.
|
| This is used for visit traversal.
|
| \**kw may contain flags that change the collection that is
| returned, for example to return a subset of items in order to
| cut down on larger traversals, or to return child items from a
| different context (such as schema-level collections instead of
| clause-level).
|
| ----------------------------------------------------------------------
| Readonly properties inherited from sqlalchemy.sql.elements.ColumnClause:
|
| entity_namespace
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.elements.ColumnClause:
|
| default = None
|
| onupdate = None
|
| server_default = None
|
| server_onupdate = None
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.base.Immutable:
|
| params(self, *optionaldict: 'Any', **kwargs: 'Any') -> 'NoReturn'
|
| unique_params(self, *optionaldict: 'Any', **kwargs: 'Any') -> 'NoReturn'
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.elements.NamedColumn:
|
| description(...)
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.elements.NamedColumn:
|
| is_literal = False
|
| table = None
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.elements.ColumnElement:
|
| __getattr__(self, key: 'str') -> 'Any'
|
| __setstate__(self, state)
|
| base_columns(...)
|
| cast(self, type_: '_TypeEngineArgument[_OPT]') -> 'Cast[_OPT]'
| Produce a type cast, i.e. ``CAST(<expression> AS <type>)``.
|
| This is a shortcut to the :func:`_expression.cast` function.
|
| .. seealso::
|
| :ref:`tutorial_casts`
|
| :func:`_expression.cast`
|
| :func:`_expression.type_coerce`
|
| comparator(...)
|
| label(self, name: 'Optional[str]') -> 'Label[_T]'
| Produce a column label, i.e. ``<columnname> AS <name>``.
|
| This is a shortcut to the :func:`_expression.label` function.
|
| If 'name' is ``None``, an anonymous label name will be generated.
|
| operate(self, op: 'operators.OperatorType', *other: 'Any', **kwargs: 'Any') -> 'ColumnElement[Any]'
| Operate on an argument.
|
| This is the lowest level of operation, raises
| :class:`NotImplementedError` by default.
|
| Overriding this on a subclass can allow common
| behavior to be applied to all operations.
| For example, overriding :class:`.ColumnOperators`
| to apply ``func.lower()`` to the left and right
| side::
|
| class MyComparator(ColumnOperators):
| def operate(self, op, other, **kwargs):
| return op(func.lower(self), func.lower(other), **kwargs)
|
| :param op: Operator callable.
| :param \*other: the 'other' side of the operation. Will
| be a single scalar for most operations.
| :param \**kwargs: modifiers. These may be passed by special
| operators such as :meth:`ColumnOperators.contains`.
|
| proxy_set(...)
| set of all columns we are proxying
|
| as of 2.0 this is explicitly deannotated columns. previously it was
| effectively deannotated columns but wasn't enforced. annotated
| columns should basically not go into sets if at all possible because
| their hashing behavior is very non-performant.
|
| reverse_operate(self, op: 'operators.OperatorType', other: 'Any', **kwargs: 'Any') -> 'ColumnElement[Any]'
| Reverse operate on an argument.
|
| Usage is the same as :meth:`operate`.
|
| self_group(self, against: 'Optional[OperatorType]' = None) -> 'ColumnElement[Any]'
| 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.
|
| shares_lineage(self, othercolumn: 'ColumnElement[Any]') -> 'bool'
| Return True if the given :class:`_expression.ColumnElement`
| has a common ancestor to this :class:`_expression.ColumnElement`.
|
| type(...)
|
| ----------------------------------------------------------------------
| Readonly properties inherited from sqlalchemy.sql.elements.ColumnElement:
|
| anon_key_label
| .. deprecated:: 1.4 The :attr:`_expression.ColumnElement.anon_key_label` attribute is now private, and the public accessor is deprecated.
|
| anon_label
| .. deprecated:: 1.4 The :attr:`_expression.ColumnElement.anon_label` attribute is now private, and the public accessor is deprecated.
|
| expression
| Return a column expression.
|
| Part of the inspection interface; returns self.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.elements.ColumnElement:
|
| foreign_keys = frozenset()
|
| key = None
|
| primary_key = False
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.AllowsLambdaRole:
|
| allows_lambda = True
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.UsesInspection:
|
| uses_inspection = True
|
| ----------------------------------------------------------------------
| Class methods inherited from typing.Generic:
|
| __class_getitem__(...)
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__(...)
| Function to initialize subclasses.
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.operators.ColumnOperators:
|
| __add__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``+`` operator.
|
| In a column context, produces the clause ``a + b``
| if the parent object has non-string affinity.
| If the parent object has a string affinity,
| produces the concatenation operator, ``a || b`` -
| see :meth:`.ColumnOperators.concat`.
|
| __contains__(self, other: 'Any') -> 'ColumnOperators'
|
| __eq__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``==`` operator.
|
| In a column context, produces the clause ``a = b``.
| If the target is ``None``, produces ``a IS NULL``.
|
| __floordiv__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``//`` operator.
|
| In a column context, produces the clause ``a / b``,
| which is the same as "truediv", but considers the result
| type to be integer.
|
| .. versionadded:: 2.0
|
| __ge__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``>=`` operator.
|
| In a column context, produces the clause ``a >= b``.
|
| __getitem__(self, index: 'Any') -> 'ColumnOperators'
| Implement the [] operator.
|
| This can be used by some database-specific types
| such as PostgreSQL ARRAY and HSTORE.
|
| __gt__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``>`` operator.
|
| In a column context, produces the clause ``a > b``.
|
| __hash__(self, /) from builtins.object
| Return hash(self).
|
| __le__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``<=`` operator.
|
| In a column context, produces the clause ``a <= b``.
|
| __lshift__(self, other: 'Any') -> 'ColumnOperators'
| implement the << operator.
|
| Not used by SQLAlchemy core, this is provided
| for custom operator systems which want to use
| << as an extension point.
|
| __lt__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``<`` operator.
|
| In a column context, produces the clause ``a < b``.
|
| __mod__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``%`` operator.
|
| In a column context, produces the clause ``a % b``.
|
| __mul__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``*`` operator.
|
| In a column context, produces the clause ``a * b``.
|
| __ne__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``!=`` operator.
|
| In a column context, produces the clause ``a != b``.
| If the target is ``None``, produces ``a IS NOT NULL``.
|
| __neg__(self) -> 'ColumnOperators'
| Implement the ``-`` operator.
|
| In a column context, produces the clause ``-a``.
|
| __radd__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``+`` operator in reverse.
|
| See :meth:`.ColumnOperators.__add__`.
|
| __rfloordiv__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``//`` operator in reverse.
|
| See :meth:`.ColumnOperators.__floordiv__`.
|
| __rmod__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``%`` operator in reverse.
|
| See :meth:`.ColumnOperators.__mod__`.
|
| __rmul__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``*`` operator in reverse.
|
| See :meth:`.ColumnOperators.__mul__`.
|
| __rshift__(self, other: 'Any') -> 'ColumnOperators'
| implement the >> operator.
|
| Not used by SQLAlchemy core, this is provided
| for custom operator systems which want to use
| >> as an extension point.
|
| __rsub__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``-`` operator in reverse.
|
| See :meth:`.ColumnOperators.__sub__`.
|
| __rtruediv__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``/`` operator in reverse.
|
| See :meth:`.ColumnOperators.__truediv__`.
|
| __sub__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``-`` operator.
|
| In a column context, produces the clause ``a - b``.
|
| __truediv__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``/`` operator.
|
| In a column context, produces the clause ``a / b``, and
| considers the result type to be numeric.
|
| .. versionchanged:: 2.0 The truediv operator against two integers
| is now considered to return a numeric value. Behavior on specific
| backends may vary.
|
| all_(self) -> 'ColumnOperators'
| Produce an :func:`_expression.all_` clause against the
| parent object.
|
| See the documentation for :func:`_sql.all_` for examples.
|
| .. note:: be sure to not confuse the newer
| :meth:`_sql.ColumnOperators.all_` method with the **legacy**
| version of this method, the :meth:`_types.ARRAY.Comparator.all`
| method that's specific to :class:`_types.ARRAY`, which uses a
| different calling style.
|
| any_(self) -> 'ColumnOperators'
| Produce an :func:`_expression.any_` clause against the
| parent object.
|
| See the documentation for :func:`_sql.any_` for examples.
|
| .. note:: be sure to not confuse the newer
| :meth:`_sql.ColumnOperators.any_` method with the **legacy**
| version of this method, the :meth:`_types.ARRAY.Comparator.any`
| method that's specific to :class:`_types.ARRAY`, which uses a
| different calling style.
|
| asc(self) -> 'ColumnOperators'
| Produce a :func:`_expression.asc` clause against the
| parent object.
|
| between(self, cleft: 'Any', cright: 'Any', symmetric: 'bool' = False) -> 'ColumnOperators'
| Produce a :func:`_expression.between` clause against
| the parent object, given the lower and upper range.
|
| bitwise_and(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise AND operation, typically via the ``&``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_lshift(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise LSHIFT operation, typically via the ``<<``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_not(self) -> 'ColumnOperators'
| Produce a bitwise NOT operation, typically via the ``~``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_or(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise OR operation, typically via the ``|``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_rshift(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise RSHIFT operation, typically via the ``>>``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_xor(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise XOR operation, typically via the ``^``
| operator, or ``#`` for PostgreSQL.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| collate(self, collation: 'str') -> 'ColumnOperators'
| Produce a :func:`_expression.collate` clause against
| the parent object, given the collation string.
|
| .. seealso::
|
| :func:`_expression.collate`
|
| concat(self, other: 'Any') -> 'ColumnOperators'
| Implement the 'concat' operator.
|
| In a column context, produces the clause ``a || b``,
| or uses the ``concat()`` operator on MySQL.
|
| contains(self, other: 'Any', **kw: 'Any') -> 'ColumnOperators'
| Implement the 'contains' operator.
|
| Produces a LIKE expression that tests against a match for the middle
| of a string value:
|
| .. sourcecode:: sql
|
| column LIKE '%' || <other> || '%'
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.contains("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.contains.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.contains.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.contains.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.contains("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE '%' || :param || '%' ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.contains("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE '%' || :param || '%' ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.contains.autoescape`::
|
| somecolumn.contains("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.startswith`
|
| :meth:`.ColumnOperators.endswith`
|
| :meth:`.ColumnOperators.like`
|
| desc(self) -> 'ColumnOperators'
| Produce a :func:`_expression.desc` clause against the
| parent object.
|
| distinct(self) -> 'ColumnOperators'
| Produce a :func:`_expression.distinct` clause against the
| parent object.
|
| endswith(self, other: 'Any', escape: 'Optional[str]' = None, autoescape: 'bool' = False) -> 'ColumnOperators'
| Implement the 'endswith' operator.
|
| Produces a LIKE expression that tests against a match for the end
| of a string value:
|
| .. sourcecode:: sql
|
| column LIKE '%' || <other>
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.endswith("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.endswith.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.endswith.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.endswith.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.endswith("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE '%' || :param ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.endswith("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE '%' || :param ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.endswith.autoescape`::
|
| somecolumn.endswith("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.startswith`
|
| :meth:`.ColumnOperators.contains`
|
| :meth:`.ColumnOperators.like`
|
| icontains(self, other: 'Any', **kw: 'Any') -> 'ColumnOperators'
| Implement the ``icontains`` operator, e.g. case insensitive
| version of :meth:`.ColumnOperators.contains`.
|
| Produces a LIKE expression that tests against an insensitive match
| for the middle of a string value:
|
| .. sourcecode:: sql
|
| lower(column) LIKE '%' || lower(<other>) || '%'
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.icontains("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.icontains.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.icontains.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.icontains.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.icontains("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE '%' || lower(:param) || '%' ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.icontains("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE '%' || lower(:param) || '%' ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.contains.autoescape`::
|
| somecolumn.icontains("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.contains`
|
| iendswith(self, other: 'Any', escape: 'Optional[str]' = None, autoescape: 'bool' = False) -> 'ColumnOperators'
| Implement the ``iendswith`` operator, e.g. case insensitive
| version of :meth:`.ColumnOperators.endswith`.
|
| Produces a LIKE expression that tests against an insensitive match
| for the end of a string value:
|
| .. sourcecode:: sql
|
| lower(column) LIKE '%' || lower(<other>)
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.iendswith("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.iendswith.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.iendswith.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.iendswith.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.iendswith("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE '%' || lower(:param) ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.iendswith("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE '%' || lower(:param) ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.iendswith.autoescape`::
|
| somecolumn.endswith("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.endswith`
|
| ilike(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
| Implement the ``ilike`` operator, e.g. case insensitive LIKE.
|
| In a column context, produces an expression either of the form:
|
| .. sourcecode:: sql
|
| lower(a) LIKE lower(other)
|
| Or on backends that support the ILIKE operator:
|
| .. sourcecode:: sql
|
| a ILIKE other
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.ilike("%foobar%"))
|
| :param other: expression to be compared
| :param escape: optional escape character, renders the ``ESCAPE``
| keyword, e.g.::
|
| somecolumn.ilike("foo/%bar", escape="/")
|
| .. seealso::
|
| :meth:`.ColumnOperators.like`
|
| in_(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``in`` operator.
|
| In a column context, produces the clause ``column IN <other>``.
|
| The given parameter ``other`` may be:
|
| * A list of literal values,
| e.g.::
|
| stmt.where(column.in_([1, 2, 3]))
|
| In this calling form, the list of items is converted to a set of
| bound parameters the same length as the list given:
|
| .. sourcecode:: sql
|
| WHERE COL IN (?, ?, ?)
|
| * A list of tuples may be provided if the comparison is against a
| :func:`.tuple_` containing multiple expressions::
|
| from sqlalchemy import tuple_
|
| stmt.where(tuple_(col1, col2).in_([(1, 10), (2, 20), (3, 30)]))
|
| * An empty list,
| e.g.::
|
| stmt.where(column.in_([]))
|
| In this calling form, the expression renders an "empty set"
| expression. These expressions are tailored to individual backends
| and are generally trying to get an empty SELECT statement as a
| subquery. Such as on SQLite, the expression is:
|
| .. sourcecode:: sql
|
| WHERE col IN (SELECT 1 FROM (SELECT 1) WHERE 1!=1)
|
| .. versionchanged:: 1.4 empty IN expressions now use an
| execution-time generated SELECT subquery in all cases.
|
| * A bound parameter, e.g. :func:`.bindparam`, may be used if it
| includes the :paramref:`.bindparam.expanding` flag::
|
| stmt.where(column.in_(bindparam("value", expanding=True)))
|
| In this calling form, the expression renders a special non-SQL
| placeholder expression that looks like:
|
| .. sourcecode:: sql
|
| WHERE COL IN ([EXPANDING_value])
|
| This placeholder expression is intercepted at statement execution
| time to be converted into the variable number of bound parameter
| form illustrated earlier. If the statement were executed as::
|
| connection.execute(stmt, {"value": [1, 2, 3]})
|
| The database would be passed a bound parameter for each value:
|
| .. sourcecode:: sql
|
| WHERE COL IN (?, ?, ?)
|
| .. versionadded:: 1.2 added "expanding" bound parameters
|
| If an empty list is passed, a special "empty list" expression,
| which is specific to the database in use, is rendered. On
| SQLite this would be:
|
| .. sourcecode:: sql
|
| WHERE COL IN (SELECT 1 FROM (SELECT 1) WHERE 1!=1)
|
| .. versionadded:: 1.3 "expanding" bound parameters now support
| empty lists
|
| * a :func:`_expression.select` construct, which is usually a
| correlated scalar select::
|
| stmt.where(
| column.in_(select(othertable.c.y).where(table.c.x == othertable.c.x))
| )
|
| In this calling form, :meth:`.ColumnOperators.in_` renders as given:
|
| .. sourcecode:: sql
|
| WHERE COL IN (SELECT othertable.y
| FROM othertable WHERE othertable.x = table.x)
|
| :param other: a list of literals, a :func:`_expression.select`
| construct, or a :func:`.bindparam` construct that includes the
| :paramref:`.bindparam.expanding` flag set to True.
|
| is_(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``IS`` operator.
|
| Normally, ``IS`` is generated automatically when comparing to a
| value of ``None``, which resolves to ``NULL``. However, explicit
| usage of ``IS`` may be desirable if comparing to boolean values
| on certain platforms.
|
| .. seealso:: :meth:`.ColumnOperators.is_not`
|
| is_distinct_from(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``IS DISTINCT FROM`` operator.
|
| Renders "a IS DISTINCT FROM b" on most platforms;
| on some such as SQLite may render "a IS NOT b".
|
| is_not(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``IS NOT`` operator.
|
| Normally, ``IS NOT`` is generated automatically when comparing to a
| value of ``None``, which resolves to ``NULL``. However, explicit
| usage of ``IS NOT`` may be desirable if comparing to boolean values
| on certain platforms.
|
| .. versionchanged:: 1.4 The ``is_not()`` operator is renamed from
| ``isnot()`` in previous releases. The previous name remains
| available for backwards compatibility.
|
| .. seealso:: :meth:`.ColumnOperators.is_`
|
| is_not_distinct_from(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``IS NOT DISTINCT FROM`` operator.
|
| Renders "a IS NOT DISTINCT FROM b" on most platforms;
| on some such as SQLite may render "a IS b".
|
| .. versionchanged:: 1.4 The ``is_not_distinct_from()`` operator is
| renamed from ``isnot_distinct_from()`` in previous releases.
| The previous name remains available for backwards compatibility.
|
| isnot = is_not(self, other: 'Any') -> 'ColumnOperators'
|
| isnot_distinct_from = is_not_distinct_from(self, other: 'Any') -> 'ColumnOperators'
|
| istartswith(self, other: 'Any', escape: 'Optional[str]' = None, autoescape: 'bool' = False) -> 'ColumnOperators'
| Implement the ``istartswith`` operator, e.g. case insensitive
| version of :meth:`.ColumnOperators.startswith`.
|
| Produces a LIKE expression that tests against an insensitive
| match for the start of a string value:
|
| .. sourcecode:: sql
|
| lower(column) LIKE lower(<other>) || '%'
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.istartswith("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.istartswith.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.istartswith.escape` parameter will
| establish a given character as an escape character which can be of
| use when the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.istartswith.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.istartswith("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE lower(:param) || '%' ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.istartswith("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE lower(:param) || '%' ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.istartswith.autoescape`::
|
| somecolumn.istartswith("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.startswith`
|
| like(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
| Implement the ``like`` operator.
|
| In a column context, produces the expression:
|
| .. sourcecode:: sql
|
| a LIKE other
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.like("%foobar%"))
|
| :param other: expression to be compared
| :param escape: optional escape character, renders the ``ESCAPE``
| keyword, e.g.::
|
| somecolumn.like("foo/%bar", escape="/")
|
| .. seealso::
|
| :meth:`.ColumnOperators.ilike`
|
| match(self, other: 'Any', **kwargs: 'Any') -> 'ColumnOperators'
| Implements a database-specific 'match' operator.
|
| :meth:`_sql.ColumnOperators.match` attempts to resolve to
| a MATCH-like function or operator provided by the backend.
| Examples include:
|
| * PostgreSQL - renders ``x @@ plainto_tsquery(y)``
|
| .. versionchanged:: 2.0 ``plainto_tsquery()`` is used instead
| of ``to_tsquery()`` for PostgreSQL now; for compatibility with
| other forms, see :ref:`postgresql_match`.
|
|
| * MySQL - renders ``MATCH (x) AGAINST (y IN BOOLEAN MODE)``
|
| .. seealso::
|
| :class:`_mysql.match` - MySQL specific construct with
| additional features.
|
| * Oracle Database - renders ``CONTAINS(x, y)``
| * other backends may provide special implementations.
| * Backends without any special implementation will emit
| the operator as "MATCH". This is compatible with SQLite, for
| example.
|
| not_ilike(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
| implement the ``NOT ILIKE`` operator.
|
| This is equivalent to using negation with
| :meth:`.ColumnOperators.ilike`, i.e. ``~x.ilike(y)``.
|
| .. versionchanged:: 1.4 The ``not_ilike()`` operator is renamed from
| ``notilike()`` in previous releases. The previous name remains
| available for backwards compatibility.
|
| .. seealso::
|
| :meth:`.ColumnOperators.ilike`
|
| not_in(self, other: 'Any') -> 'ColumnOperators'
| implement the ``NOT IN`` operator.
|
| This is equivalent to using negation with
| :meth:`.ColumnOperators.in_`, i.e. ``~x.in_(y)``.
|
| In the case that ``other`` is an empty sequence, the compiler
| produces an "empty not in" expression. This defaults to the
| expression "1 = 1" to produce true in all cases. The
| :paramref:`_sa.create_engine.empty_in_strategy` may be used to
| alter this behavior.
|
| .. versionchanged:: 1.4 The ``not_in()`` operator is renamed from
| ``notin_()`` in previous releases. The previous name remains
| available for backwards compatibility.
|
| .. versionchanged:: 1.2 The :meth:`.ColumnOperators.in_` and
| :meth:`.ColumnOperators.not_in` operators
| now produce a "static" expression for an empty IN sequence
| by default.
|
| .. seealso::
|
| :meth:`.ColumnOperators.in_`
|
| not_like(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
| implement the ``NOT LIKE`` operator.
|
| This is equivalent to using negation with
| :meth:`.ColumnOperators.like`, i.e. ``~x.like(y)``.
|
| .. versionchanged:: 1.4 The ``not_like()`` operator is renamed from
| ``notlike()`` in previous releases. The previous name remains
| available for backwards compatibility.
|
| .. seealso::
|
| :meth:`.ColumnOperators.like`
|
| notilike = not_ilike(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
|
| notin_ = not_in(self, other: 'Any') -> 'ColumnOperators'
|
| notlike = not_like(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
|
| nulls_first(self) -> 'ColumnOperators'
| Produce a :func:`_expression.nulls_first` clause against the
| parent object.
|
| .. versionchanged:: 1.4 The ``nulls_first()`` operator is
| renamed from ``nullsfirst()`` in previous releases.
| The previous name remains available for backwards compatibility.
|
| nulls_last(self) -> 'ColumnOperators'
| Produce a :func:`_expression.nulls_last` clause against the
| parent object.
|
| .. versionchanged:: 1.4 The ``nulls_last()`` operator is
| renamed from ``nullslast()`` in previous releases.
| The previous name remains available for backwards compatibility.
|
| nullsfirst = nulls_first(self) -> 'ColumnOperators'
|
| nullslast = nulls_last(self) -> 'ColumnOperators'
|
| regexp_match(self, pattern: 'Any', flags: 'Optional[str]' = None) -> 'ColumnOperators'
| Implements a database-specific 'regexp match' operator.
|
| E.g.::
|
| stmt = select(table.c.some_column).where(
| table.c.some_column.regexp_match("^(b|c)")
| )
|
| :meth:`_sql.ColumnOperators.regexp_match` attempts to resolve to
| a REGEXP-like function or operator provided by the backend, however
| the specific regular expression syntax and flags available are
| **not backend agnostic**.
|
| Examples include:
|
| * PostgreSQL - renders ``x ~ y`` or ``x !~ y`` when negated.
| * Oracle Database - renders ``REGEXP_LIKE(x, y)``
| * SQLite - uses SQLite's ``REGEXP`` placeholder operator and calls into
| the Python ``re.match()`` builtin.
| * other backends may provide special implementations.
| * Backends without any special implementation will emit
| the operator as "REGEXP" or "NOT REGEXP". This is compatible with
| SQLite and MySQL, for example.
|
| Regular expression support is currently implemented for Oracle
| Database, PostgreSQL, MySQL and MariaDB. Partial support is available
| for SQLite. Support among third-party dialects may vary.
|
| :param pattern: The regular expression pattern string or column
| clause.
| :param flags: Any regular expression string flags to apply, passed as
| plain Python string only. These flags are backend specific.
| Some backends, like PostgreSQL and MariaDB, may alternatively
| specify the flags as part of the pattern.
| When using the ignore case flag 'i' in PostgreSQL, the ignore case
| regexp match operator ``~*`` or ``!~*`` will be used.
|
| .. versionadded:: 1.4
|
| .. versionchanged:: 1.4.48, 2.0.18 Note that due to an implementation
| error, the "flags" parameter previously accepted SQL expression
| objects such as column expressions in addition to plain Python
| strings. This implementation did not work correctly with caching
| and was removed; strings only should be passed for the "flags"
| parameter, as these flags are rendered as literal inline values
| within SQL expressions.
|
| .. seealso::
|
| :meth:`_sql.ColumnOperators.regexp_replace`
|
| regexp_replace(self, pattern: 'Any', replacement: 'Any', flags: 'Optional[str]' = None) -> 'ColumnOperators'
| Implements a database-specific 'regexp replace' operator.
|
| E.g.::
|
| stmt = select(
| table.c.some_column.regexp_replace("b(..)", "XY", flags="g")
| )
|
| :meth:`_sql.ColumnOperators.regexp_replace` attempts to resolve to
| a REGEXP_REPLACE-like function provided by the backend, that
| usually emit the function ``REGEXP_REPLACE()``. However,
| the specific regular expression syntax and flags available are
| **not backend agnostic**.
|
| Regular expression replacement support is currently implemented for
| Oracle Database, PostgreSQL, MySQL 8 or greater and MariaDB. Support
| among third-party dialects may vary.
|
| :param pattern: The regular expression pattern string or column
| clause.
| :param pattern: The replacement string or column clause.
| :param flags: Any regular expression string flags to apply, passed as
| plain Python string only. These flags are backend specific.
| Some backends, like PostgreSQL and MariaDB, may alternatively
| specify the flags as part of the pattern.
|
| .. versionadded:: 1.4
|
| .. versionchanged:: 1.4.48, 2.0.18 Note that due to an implementation
| error, the "flags" parameter previously accepted SQL expression
| objects such as column expressions in addition to plain Python
| strings. This implementation did not work correctly with caching
| and was removed; strings only should be passed for the "flags"
| parameter, as these flags are rendered as literal inline values
| within SQL expressions.
|
|
| .. seealso::
|
| :meth:`_sql.ColumnOperators.regexp_match`
|
| startswith(self, other: 'Any', escape: 'Optional[str]' = None, autoescape: 'bool' = False) -> 'ColumnOperators'
| Implement the ``startswith`` operator.
|
| Produces a LIKE expression that tests against a match for the start
| of a string value:
|
| .. sourcecode:: sql
|
| column LIKE <other> || '%'
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.startswith("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.startswith.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.startswith.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.startswith.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.startswith("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE :param || '%' ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.startswith("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE :param || '%' ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.startswith.autoescape`::
|
| somecolumn.startswith("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.endswith`
|
| :meth:`.ColumnOperators.contains`
|
| :meth:`.ColumnOperators.like`
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.operators.ColumnOperators:
|
| timetuple = None
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.operators.Operators:
|
| __and__(self, other: 'Any') -> 'Operators'
| Implement the ``&`` operator.
|
| When used with SQL expressions, results in an
| AND operation, equivalent to
| :func:`_expression.and_`, that is::
|
| a & b
|
| is equivalent to::
|
| from sqlalchemy import and_
|
| and_(a, b)
|
| Care should be taken when using ``&`` regarding
| operator precedence; the ``&`` operator has the highest precedence.
| The operands should be enclosed in parenthesis if they contain
| further sub expressions::
|
| (a == 2) & (b == 4)
|
| __invert__(self) -> 'Operators'
| Implement the ``~`` operator.
|
| When used with SQL expressions, results in a
| NOT operation, equivalent to
| :func:`_expression.not_`, that is::
|
| ~a
|
| is equivalent to::
|
| from sqlalchemy import not_
|
| not_(a)
|
| __or__(self, other: 'Any') -> 'Operators'
| Implement the ``|`` operator.
|
| When used with SQL expressions, results in an
| OR operation, equivalent to
| :func:`_expression.or_`, that is::
|
| a | b
|
| is equivalent to::
|
| from sqlalchemy import or_
|
| or_(a, b)
|
| Care should be taken when using ``|`` regarding
| operator precedence; the ``|`` operator has the highest precedence.
| The operands should be enclosed in parenthesis if they contain
| further sub expressions::
|
| (a == 2) | (b == 4)
|
| __sa_operate__ = operate(self, op: 'OperatorType', *other: 'Any', **kwargs: 'Any') -> 'Operators'
| Operate on an argument.
|
| This is the lowest level of operation, raises
| :class:`NotImplementedError` by default.
|
| Overriding this on a subclass can allow common
| behavior to be applied to all operations.
| For example, overriding :class:`.ColumnOperators`
| to apply ``func.lower()`` to the left and right
| side::
|
| class MyComparator(ColumnOperators):
| def operate(self, op, other, **kwargs):
| return op(func.lower(self), func.lower(other), **kwargs)
|
| :param op: Operator callable.
| :param \*other: the 'other' side of the operation. Will
| be a single scalar for most operations.
| :param \**kwargs: modifiers. These may be passed by special
| operators such as :meth:`ColumnOperators.contains`.
|
| bool_op(self, opstring: 'str', precedence: 'int' = 0, python_impl: 'Optional[Callable[..., Any]]' = None) -> 'Callable[[Any], Operators]'
| Return a custom boolean operator.
|
| This method is shorthand for calling
| :meth:`.Operators.op` and passing the
| :paramref:`.Operators.op.is_comparison`
| flag with True. A key advantage to using :meth:`.Operators.bool_op`
| is that when using column constructs, the "boolean" nature of the
| returned expression will be present for :pep:`484` purposes.
|
| .. seealso::
|
| :meth:`.Operators.op`
|
| op(self, opstring: 'str', precedence: 'int' = 0, is_comparison: 'bool' = False, return_type: 'Optional[Union[Type[TypeEngine[Any]], TypeEngine[Any]]]' = None, python_impl: 'Optional[Callable[..., Any]]' = None) -> 'Callable[[Any], Operators]'
| Produce a generic operator function.
|
| e.g.::
|
| somecolumn.op("*")(5)
|
| produces::
|
| somecolumn * 5
|
| This function can also be used to make bitwise operators explicit. For
| example::
|
| somecolumn.op("&")(0xFF)
|
| is a bitwise AND of the value in ``somecolumn``.
|
| :param opstring: a string which will be output as the infix operator
| between this element and the expression passed to the
| generated function.
|
| :param precedence: precedence which the database is expected to apply
| to the operator in SQL expressions. This integer value acts as a hint
| for the SQL compiler to know when explicit parenthesis should be
| rendered around a particular operation. A lower number will cause the
| expression to be parenthesized when applied against another operator
| with higher precedence. The default value of ``0`` is lower than all
| operators except for the comma (``,``) and ``AS`` operators. A value
| of 100 will be higher or equal to all operators, and -100 will be
| lower than or equal to all operators.
|
| .. seealso::
|
| :ref:`faq_sql_expression_op_parenthesis` - detailed description
| of how the SQLAlchemy SQL compiler renders parenthesis
|
| :param is_comparison: legacy; if True, the operator will be considered
| as a "comparison" operator, that is which evaluates to a boolean
| true/false value, like ``==``, ``>``, etc. This flag is provided
| so that ORM relationships can establish that the operator is a
| comparison operator when used in a custom join condition.
|
| Using the ``is_comparison`` parameter is superseded by using the
| :meth:`.Operators.bool_op` method instead; this more succinct
| operator sets this parameter automatically, but also provides
| correct :pep:`484` typing support as the returned object will
| express a "boolean" datatype, i.e. ``BinaryExpression[bool]``.
|
| :param return_type: a :class:`.TypeEngine` class or object that will
| force the return type of an expression produced by this operator
| to be of that type. By default, operators that specify
| :paramref:`.Operators.op.is_comparison` will resolve to
| :class:`.Boolean`, and those that do not will be of the same
| type as the left-hand operand.
|
| :param python_impl: an optional Python function that can evaluate
| two Python values in the same way as this operator works when
| run on the database server. Useful for in-Python SQL expression
| evaluation functions, such as for ORM hybrid attributes, and the
| ORM "evaluator" used to match objects in a session after a multi-row
| update or delete.
|
| e.g.::
|
| >>> expr = column("x").op("+", python_impl=lambda a, b: a + b)("y")
|
| The operator for the above expression will also work for non-SQL
| left and right objects::
|
| >>> expr.operator(5, 10)
| 15
|
| .. versionadded:: 2.0
|
|
| .. seealso::
|
| :meth:`.Operators.bool_op`
|
| :ref:`types_operators`
|
| :ref:`relationship_custom_operator`
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.elements.ClauseElement:
|
| __bool__(self)
|
| __getstate__(self)
| Helper for pickle.
|
| compare(self, other: 'ClauseElement', **kw: 'Any') -> 'bool'
| Compare this :class:`_expression.ClauseElement` to
| the given :class:`_expression.ClauseElement`.
|
| Subclasses should override the default behavior, which is a
| straight identity comparison.
|
| \**kw are arguments consumed by subclass ``compare()`` methods and
| may be used to modify the criteria for comparison
| (see :class:`_expression.ColumnElement`).
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.elements.ClauseElement:
|
| is_clause_element = True
|
| is_dml = False
|
| is_selectable = False
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_instancemethod(fn: '_F') -> '_F'
| Decorate a method memoize its return value.
|
| :meta private:
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_attribute = <class 'sqlalchemy.util.langhelpers.HasMemoized.m...
| A read-only @property that is only evaluated once.
|
| :meta private:
|
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.elements.CompilerElement:
|
| compile(self, bind: 'Optional[_HasDialect]' = None, dialect: 'Optional[Dialect]' = None, **kw: 'Any') -> 'Compiled'
| Compile this SQL expression.
|
| The return value is a :class:`~.Compiled` object.
| Calling ``str()`` or ``unicode()`` on the returned value will yield a
| string representation of the result. The
| :class:`~.Compiled` object also can return a
| dictionary of bind parameter names and values
| using the ``params`` accessor.
|
| :param bind: An :class:`.Connection` or :class:`.Engine` which
| can provide a :class:`.Dialect` in order to generate a
| :class:`.Compiled` object. If the ``bind`` and
| ``dialect`` parameters are both omitted, a default SQL compiler
| is used.
|
| :param column_keys: Used for INSERT and UPDATE statements, a list of
| column names which should be present in the VALUES clause of the
| compiled statement. If ``None``, all columns from the target table
| object are rendered.
|
| :param dialect: A :class:`.Dialect` instance which can generate
| a :class:`.Compiled` object. This argument takes precedence over
| the ``bind`` argument.
|
| :param compile_kwargs: optional dictionary of additional parameters
| that will be passed through to the compiler within all "visit"
| methods. This allows any custom flag to be passed through to
| a custom compilation construct, for example. It is also used
| for the case of passing the ``literal_binds`` flag through::
|
| from sqlalchemy.sql import table, column, select
|
| t = table("t", column("x"))
|
| s = select(t).where(t.c.x == 5)
|
| print(s.compile(compile_kwargs={"literal_binds": True}))
|
| .. seealso::
|
| :ref:`faq_sql_expression_string`
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.elements.CompilerElement:
|
| stringify_dialect = 'default'
|
| supports_execution = False
sqlalchemy.ColumnClause
Python Library Documentation: class ColumnClause in module sqlalchemy.sql.elements
class ColumnClause(sqlalchemy.sql.roles.DDLReferredColumnRole, sqlalchemy.sql.roles.LabeledColumnExprRole, sqlalchemy.sql.roles.StrAsPlainColumnRole, sqlalchemy.sql.base.Immutable, NamedColumn)
| ColumnClause(text: 'str', type_: 'Optional[_TypeEngineArgument[_T]]' = None, is_literal: 'bool' = False, _selectable: 'Optional[FromClause]' = None)
|
| Represents a column expression from any textual string.
|
| The :class:`.ColumnClause`, a lightweight analogue to the
| :class:`_schema.Column` class, is typically invoked using the
| :func:`_expression.column` function, as in::
|
| from sqlalchemy import column
|
| id, name = column("id"), column("name")
| stmt = select(id, name).select_from("user")
|
| The above statement would produce SQL like:
|
| .. sourcecode:: sql
|
| SELECT id, name FROM user
|
| :class:`.ColumnClause` is the immediate superclass of the schema-specific
| :class:`_schema.Column` object. While the :class:`_schema.Column`
| class has all the
| same capabilities as :class:`.ColumnClause`, the :class:`.ColumnClause`
| class is usable by itself in those cases where behavioral requirements
| are limited to simple SQL expression generation. The object has none of
| the associations with schema-level metadata or with execution-time
| behavior that :class:`_schema.Column` does,
| so in that sense is a "lightweight"
| version of :class:`_schema.Column`.
|
| Full details on :class:`.ColumnClause` usage is at
| :func:`_expression.column`.
|
| .. seealso::
|
| :func:`_expression.column`
|
| :class:`_schema.Column`
|
| Method resolution order:
| ColumnClause
| sqlalchemy.sql.roles.DDLReferredColumnRole
| sqlalchemy.sql.roles.LabeledColumnExprRole
| sqlalchemy.sql.roles.StrAsPlainColumnRole
| sqlalchemy.sql.base.Immutable
| NamedColumn
| KeyedColumnElement
| ColumnElement
| sqlalchemy.sql.roles.ColumnArgumentOrKeyRole
| sqlalchemy.sql.roles.ColumnArgumentRole
| sqlalchemy.sql.roles.StatementOptionRole
| sqlalchemy.sql.roles.WhereHavingRole
| sqlalchemy.sql.roles.OnClauseRole
| sqlalchemy.sql.roles.BinaryElementRole
| sqlalchemy.sql.roles.OrderByRole
| sqlalchemy.sql.roles.ColumnsClauseRole
| sqlalchemy.sql.roles.AllowsLambdaRole
| sqlalchemy.sql.roles.ByOfRole
| sqlalchemy.sql.roles.UsesInspection
| sqlalchemy.sql.roles.ColumnListRole
| sqlalchemy.sql.roles.LimitOffsetRole
| sqlalchemy.sql.roles.DMLColumnRole
| sqlalchemy.sql.roles.DDLConstraintColumnRole
| sqlalchemy.sql.roles.DDLExpressionRole
| sqlalchemy.sql.roles.StructuralRole
| SQLColumnExpression
| SQLCoreOperations
| sqlalchemy.sql.roles.ExpressionElementRole
| sqlalchemy.sql.roles.TypedColumnsClauseRole
| typing.Generic
| sqlalchemy.sql.operators.ColumnOperators
| sqlalchemy.sql.operators.Operators
| sqlalchemy.util.langhelpers.TypingOnly
| sqlalchemy.sql.roles.SQLRole
| DQLDMLClauseElement
| ClauseElement
| sqlalchemy.sql.annotation.SupportsWrappingAnnotations
| sqlalchemy.sql.annotation.SupportsAnnotations
| sqlalchemy.sql.cache_key.MemoizedHasCacheKey
| sqlalchemy.sql.cache_key.HasCacheKey
| sqlalchemy.util.langhelpers.HasMemoized
| sqlalchemy.sql.traversals.HasCopyInternals
| sqlalchemy.sql.visitors.ExternallyTraversible
| sqlalchemy.sql.visitors.HasTraverseInternals
| CompilerElement
| sqlalchemy.sql.visitors.Visitable
| builtins.object
|
| Methods defined here:
|
| __init__(self, text: 'str', type_: 'Optional[_TypeEngineArgument[_T]]' = None, is_literal: 'bool' = False, _selectable: 'Optional[FromClause]' = None)
| Initialize self. See help(type(self)) for accurate signature.
|
| get_children(self, *, column_tables=False, **kw)
| Return immediate child :class:`.visitors.HasTraverseInternals`
| elements of this :class:`.visitors.HasTraverseInternals`.
|
| This is used for visit traversal.
|
| \**kw may contain flags that change the collection that is
| returned, for example to return a subset of items in order to
| cut down on larger traversals, or to return child items from a
| different context (such as schema-level collections instead of
| clause-level).
|
| ----------------------------------------------------------------------
| Readonly properties defined here:
|
| entity_namespace
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'_traverse_internals': '_TraverseInternalsType', 'd...
|
| __orig_bases__ = (<class 'sqlalchemy.sql.roles.DDLReferredColumnRole'>...
|
| __parameters__ = (~_T,)
|
| __visit_name__ = 'column'
|
| default = None
|
| onupdate = None
|
| server_default = None
|
| server_onupdate = None
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.base.Immutable:
|
| params(self, *optionaldict: 'Any', **kwargs: 'Any') -> 'NoReturn'
|
| unique_params(self, *optionaldict: 'Any', **kwargs: 'Any') -> 'NoReturn'
|
| ----------------------------------------------------------------------
| Methods inherited from NamedColumn:
|
| description(...)
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from NamedColumn:
|
| is_literal = False
|
| table = None
|
| ----------------------------------------------------------------------
| Methods inherited from ColumnElement:
|
| __getattr__(self, key: 'str') -> 'Any'
|
| __setstate__(self, state)
|
| base_columns(...)
|
| cast(self, type_: '_TypeEngineArgument[_OPT]') -> 'Cast[_OPT]'
| Produce a type cast, i.e. ``CAST(<expression> AS <type>)``.
|
| This is a shortcut to the :func:`_expression.cast` function.
|
| .. seealso::
|
| :ref:`tutorial_casts`
|
| :func:`_expression.cast`
|
| :func:`_expression.type_coerce`
|
| comparator(...)
|
| label(self, name: 'Optional[str]') -> 'Label[_T]'
| Produce a column label, i.e. ``<columnname> AS <name>``.
|
| This is a shortcut to the :func:`_expression.label` function.
|
| If 'name' is ``None``, an anonymous label name will be generated.
|
| operate(self, op: 'operators.OperatorType', *other: 'Any', **kwargs: 'Any') -> 'ColumnElement[Any]'
| Operate on an argument.
|
| This is the lowest level of operation, raises
| :class:`NotImplementedError` by default.
|
| Overriding this on a subclass can allow common
| behavior to be applied to all operations.
| For example, overriding :class:`.ColumnOperators`
| to apply ``func.lower()`` to the left and right
| side::
|
| class MyComparator(ColumnOperators):
| def operate(self, op, other, **kwargs):
| return op(func.lower(self), func.lower(other), **kwargs)
|
| :param op: Operator callable.
| :param \*other: the 'other' side of the operation. Will
| be a single scalar for most operations.
| :param \**kwargs: modifiers. These may be passed by special
| operators such as :meth:`ColumnOperators.contains`.
|
| proxy_set(...)
| set of all columns we are proxying
|
| as of 2.0 this is explicitly deannotated columns. previously it was
| effectively deannotated columns but wasn't enforced. annotated
| columns should basically not go into sets if at all possible because
| their hashing behavior is very non-performant.
|
| reverse_operate(self, op: 'operators.OperatorType', other: 'Any', **kwargs: 'Any') -> 'ColumnElement[Any]'
| Reverse operate on an argument.
|
| Usage is the same as :meth:`operate`.
|
| self_group(self, against: 'Optional[OperatorType]' = None) -> 'ColumnElement[Any]'
| 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.
|
| shares_lineage(self, othercolumn: 'ColumnElement[Any]') -> 'bool'
| Return True if the given :class:`_expression.ColumnElement`
| has a common ancestor to this :class:`_expression.ColumnElement`.
|
| type(...)
|
| ----------------------------------------------------------------------
| Readonly properties inherited from ColumnElement:
|
| anon_key_label
| .. deprecated:: 1.4 The :attr:`_expression.ColumnElement.anon_key_label` attribute is now private, and the public accessor is deprecated.
|
| anon_label
| .. deprecated:: 1.4 The :attr:`_expression.ColumnElement.anon_label` attribute is now private, and the public accessor is deprecated.
|
| expression
| Return a column expression.
|
| Part of the inspection interface; returns self.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from ColumnElement:
|
| foreign_keys = frozenset()
|
| key = None
|
| primary_key = False
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.AllowsLambdaRole:
|
| allows_lambda = True
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.UsesInspection:
|
| uses_inspection = True
|
| ----------------------------------------------------------------------
| Class methods inherited from typing.Generic:
|
| __class_getitem__(...)
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__(...)
| Function to initialize subclasses.
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.operators.ColumnOperators:
|
| __add__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``+`` operator.
|
| In a column context, produces the clause ``a + b``
| if the parent object has non-string affinity.
| If the parent object has a string affinity,
| produces the concatenation operator, ``a || b`` -
| see :meth:`.ColumnOperators.concat`.
|
| __contains__(self, other: 'Any') -> 'ColumnOperators'
|
| __eq__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``==`` operator.
|
| In a column context, produces the clause ``a = b``.
| If the target is ``None``, produces ``a IS NULL``.
|
| __floordiv__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``//`` operator.
|
| In a column context, produces the clause ``a / b``,
| which is the same as "truediv", but considers the result
| type to be integer.
|
| .. versionadded:: 2.0
|
| __ge__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``>=`` operator.
|
| In a column context, produces the clause ``a >= b``.
|
| __getitem__(self, index: 'Any') -> 'ColumnOperators'
| Implement the [] operator.
|
| This can be used by some database-specific types
| such as PostgreSQL ARRAY and HSTORE.
|
| __gt__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``>`` operator.
|
| In a column context, produces the clause ``a > b``.
|
| __hash__(self, /) from builtins.object
| Return hash(self).
|
| __le__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``<=`` operator.
|
| In a column context, produces the clause ``a <= b``.
|
| __lshift__(self, other: 'Any') -> 'ColumnOperators'
| implement the << operator.
|
| Not used by SQLAlchemy core, this is provided
| for custom operator systems which want to use
| << as an extension point.
|
| __lt__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``<`` operator.
|
| In a column context, produces the clause ``a < b``.
|
| __mod__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``%`` operator.
|
| In a column context, produces the clause ``a % b``.
|
| __mul__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``*`` operator.
|
| In a column context, produces the clause ``a * b``.
|
| __ne__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``!=`` operator.
|
| In a column context, produces the clause ``a != b``.
| If the target is ``None``, produces ``a IS NOT NULL``.
|
| __neg__(self) -> 'ColumnOperators'
| Implement the ``-`` operator.
|
| In a column context, produces the clause ``-a``.
|
| __radd__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``+`` operator in reverse.
|
| See :meth:`.ColumnOperators.__add__`.
|
| __rfloordiv__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``//`` operator in reverse.
|
| See :meth:`.ColumnOperators.__floordiv__`.
|
| __rmod__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``%`` operator in reverse.
|
| See :meth:`.ColumnOperators.__mod__`.
|
| __rmul__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``*`` operator in reverse.
|
| See :meth:`.ColumnOperators.__mul__`.
|
| __rshift__(self, other: 'Any') -> 'ColumnOperators'
| implement the >> operator.
|
| Not used by SQLAlchemy core, this is provided
| for custom operator systems which want to use
| >> as an extension point.
|
| __rsub__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``-`` operator in reverse.
|
| See :meth:`.ColumnOperators.__sub__`.
|
| __rtruediv__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``/`` operator in reverse.
|
| See :meth:`.ColumnOperators.__truediv__`.
|
| __sub__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``-`` operator.
|
| In a column context, produces the clause ``a - b``.
|
| __truediv__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``/`` operator.
|
| In a column context, produces the clause ``a / b``, and
| considers the result type to be numeric.
|
| .. versionchanged:: 2.0 The truediv operator against two integers
| is now considered to return a numeric value. Behavior on specific
| backends may vary.
|
| all_(self) -> 'ColumnOperators'
| Produce an :func:`_expression.all_` clause against the
| parent object.
|
| See the documentation for :func:`_sql.all_` for examples.
|
| .. note:: be sure to not confuse the newer
| :meth:`_sql.ColumnOperators.all_` method with the **legacy**
| version of this method, the :meth:`_types.ARRAY.Comparator.all`
| method that's specific to :class:`_types.ARRAY`, which uses a
| different calling style.
|
| any_(self) -> 'ColumnOperators'
| Produce an :func:`_expression.any_` clause against the
| parent object.
|
| See the documentation for :func:`_sql.any_` for examples.
|
| .. note:: be sure to not confuse the newer
| :meth:`_sql.ColumnOperators.any_` method with the **legacy**
| version of this method, the :meth:`_types.ARRAY.Comparator.any`
| method that's specific to :class:`_types.ARRAY`, which uses a
| different calling style.
|
| asc(self) -> 'ColumnOperators'
| Produce a :func:`_expression.asc` clause against the
| parent object.
|
| between(self, cleft: 'Any', cright: 'Any', symmetric: 'bool' = False) -> 'ColumnOperators'
| Produce a :func:`_expression.between` clause against
| the parent object, given the lower and upper range.
|
| bitwise_and(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise AND operation, typically via the ``&``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_lshift(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise LSHIFT operation, typically via the ``<<``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_not(self) -> 'ColumnOperators'
| Produce a bitwise NOT operation, typically via the ``~``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_or(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise OR operation, typically via the ``|``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_rshift(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise RSHIFT operation, typically via the ``>>``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_xor(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise XOR operation, typically via the ``^``
| operator, or ``#`` for PostgreSQL.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| collate(self, collation: 'str') -> 'ColumnOperators'
| Produce a :func:`_expression.collate` clause against
| the parent object, given the collation string.
|
| .. seealso::
|
| :func:`_expression.collate`
|
| concat(self, other: 'Any') -> 'ColumnOperators'
| Implement the 'concat' operator.
|
| In a column context, produces the clause ``a || b``,
| or uses the ``concat()`` operator on MySQL.
|
| contains(self, other: 'Any', **kw: 'Any') -> 'ColumnOperators'
| Implement the 'contains' operator.
|
| Produces a LIKE expression that tests against a match for the middle
| of a string value:
|
| .. sourcecode:: sql
|
| column LIKE '%' || <other> || '%'
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.contains("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.contains.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.contains.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.contains.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.contains("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE '%' || :param || '%' ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.contains("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE '%' || :param || '%' ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.contains.autoescape`::
|
| somecolumn.contains("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.startswith`
|
| :meth:`.ColumnOperators.endswith`
|
| :meth:`.ColumnOperators.like`
|
| desc(self) -> 'ColumnOperators'
| Produce a :func:`_expression.desc` clause against the
| parent object.
|
| distinct(self) -> 'ColumnOperators'
| Produce a :func:`_expression.distinct` clause against the
| parent object.
|
| endswith(self, other: 'Any', escape: 'Optional[str]' = None, autoescape: 'bool' = False) -> 'ColumnOperators'
| Implement the 'endswith' operator.
|
| Produces a LIKE expression that tests against a match for the end
| of a string value:
|
| .. sourcecode:: sql
|
| column LIKE '%' || <other>
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.endswith("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.endswith.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.endswith.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.endswith.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.endswith("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE '%' || :param ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.endswith("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE '%' || :param ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.endswith.autoescape`::
|
| somecolumn.endswith("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.startswith`
|
| :meth:`.ColumnOperators.contains`
|
| :meth:`.ColumnOperators.like`
|
| icontains(self, other: 'Any', **kw: 'Any') -> 'ColumnOperators'
| Implement the ``icontains`` operator, e.g. case insensitive
| version of :meth:`.ColumnOperators.contains`.
|
| Produces a LIKE expression that tests against an insensitive match
| for the middle of a string value:
|
| .. sourcecode:: sql
|
| lower(column) LIKE '%' || lower(<other>) || '%'
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.icontains("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.icontains.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.icontains.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.icontains.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.icontains("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE '%' || lower(:param) || '%' ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.icontains("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE '%' || lower(:param) || '%' ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.contains.autoescape`::
|
| somecolumn.icontains("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.contains`
|
| iendswith(self, other: 'Any', escape: 'Optional[str]' = None, autoescape: 'bool' = False) -> 'ColumnOperators'
| Implement the ``iendswith`` operator, e.g. case insensitive
| version of :meth:`.ColumnOperators.endswith`.
|
| Produces a LIKE expression that tests against an insensitive match
| for the end of a string value:
|
| .. sourcecode:: sql
|
| lower(column) LIKE '%' || lower(<other>)
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.iendswith("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.iendswith.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.iendswith.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.iendswith.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.iendswith("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE '%' || lower(:param) ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.iendswith("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE '%' || lower(:param) ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.iendswith.autoescape`::
|
| somecolumn.endswith("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.endswith`
|
| ilike(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
| Implement the ``ilike`` operator, e.g. case insensitive LIKE.
|
| In a column context, produces an expression either of the form:
|
| .. sourcecode:: sql
|
| lower(a) LIKE lower(other)
|
| Or on backends that support the ILIKE operator:
|
| .. sourcecode:: sql
|
| a ILIKE other
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.ilike("%foobar%"))
|
| :param other: expression to be compared
| :param escape: optional escape character, renders the ``ESCAPE``
| keyword, e.g.::
|
| somecolumn.ilike("foo/%bar", escape="/")
|
| .. seealso::
|
| :meth:`.ColumnOperators.like`
|
| in_(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``in`` operator.
|
| In a column context, produces the clause ``column IN <other>``.
|
| The given parameter ``other`` may be:
|
| * A list of literal values,
| e.g.::
|
| stmt.where(column.in_([1, 2, 3]))
|
| In this calling form, the list of items is converted to a set of
| bound parameters the same length as the list given:
|
| .. sourcecode:: sql
|
| WHERE COL IN (?, ?, ?)
|
| * A list of tuples may be provided if the comparison is against a
| :func:`.tuple_` containing multiple expressions::
|
| from sqlalchemy import tuple_
|
| stmt.where(tuple_(col1, col2).in_([(1, 10), (2, 20), (3, 30)]))
|
| * An empty list,
| e.g.::
|
| stmt.where(column.in_([]))
|
| In this calling form, the expression renders an "empty set"
| expression. These expressions are tailored to individual backends
| and are generally trying to get an empty SELECT statement as a
| subquery. Such as on SQLite, the expression is:
|
| .. sourcecode:: sql
|
| WHERE col IN (SELECT 1 FROM (SELECT 1) WHERE 1!=1)
|
| .. versionchanged:: 1.4 empty IN expressions now use an
| execution-time generated SELECT subquery in all cases.
|
| * A bound parameter, e.g. :func:`.bindparam`, may be used if it
| includes the :paramref:`.bindparam.expanding` flag::
|
| stmt.where(column.in_(bindparam("value", expanding=True)))
|
| In this calling form, the expression renders a special non-SQL
| placeholder expression that looks like:
|
| .. sourcecode:: sql
|
| WHERE COL IN ([EXPANDING_value])
|
| This placeholder expression is intercepted at statement execution
| time to be converted into the variable number of bound parameter
| form illustrated earlier. If the statement were executed as::
|
| connection.execute(stmt, {"value": [1, 2, 3]})
|
| The database would be passed a bound parameter for each value:
|
| .. sourcecode:: sql
|
| WHERE COL IN (?, ?, ?)
|
| .. versionadded:: 1.2 added "expanding" bound parameters
|
| If an empty list is passed, a special "empty list" expression,
| which is specific to the database in use, is rendered. On
| SQLite this would be:
|
| .. sourcecode:: sql
|
| WHERE COL IN (SELECT 1 FROM (SELECT 1) WHERE 1!=1)
|
| .. versionadded:: 1.3 "expanding" bound parameters now support
| empty lists
|
| * a :func:`_expression.select` construct, which is usually a
| correlated scalar select::
|
| stmt.where(
| column.in_(select(othertable.c.y).where(table.c.x == othertable.c.x))
| )
|
| In this calling form, :meth:`.ColumnOperators.in_` renders as given:
|
| .. sourcecode:: sql
|
| WHERE COL IN (SELECT othertable.y
| FROM othertable WHERE othertable.x = table.x)
|
| :param other: a list of literals, a :func:`_expression.select`
| construct, or a :func:`.bindparam` construct that includes the
| :paramref:`.bindparam.expanding` flag set to True.
|
| is_(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``IS`` operator.
|
| Normally, ``IS`` is generated automatically when comparing to a
| value of ``None``, which resolves to ``NULL``. However, explicit
| usage of ``IS`` may be desirable if comparing to boolean values
| on certain platforms.
|
| .. seealso:: :meth:`.ColumnOperators.is_not`
|
| is_distinct_from(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``IS DISTINCT FROM`` operator.
|
| Renders "a IS DISTINCT FROM b" on most platforms;
| on some such as SQLite may render "a IS NOT b".
|
| is_not(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``IS NOT`` operator.
|
| Normally, ``IS NOT`` is generated automatically when comparing to a
| value of ``None``, which resolves to ``NULL``. However, explicit
| usage of ``IS NOT`` may be desirable if comparing to boolean values
| on certain platforms.
|
| .. versionchanged:: 1.4 The ``is_not()`` operator is renamed from
| ``isnot()`` in previous releases. The previous name remains
| available for backwards compatibility.
|
| .. seealso:: :meth:`.ColumnOperators.is_`
|
| is_not_distinct_from(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``IS NOT DISTINCT FROM`` operator.
|
| Renders "a IS NOT DISTINCT FROM b" on most platforms;
| on some such as SQLite may render "a IS b".
|
| .. versionchanged:: 1.4 The ``is_not_distinct_from()`` operator is
| renamed from ``isnot_distinct_from()`` in previous releases.
| The previous name remains available for backwards compatibility.
|
| isnot = is_not(self, other: 'Any') -> 'ColumnOperators'
|
| isnot_distinct_from = is_not_distinct_from(self, other: 'Any') -> 'ColumnOperators'
|
| istartswith(self, other: 'Any', escape: 'Optional[str]' = None, autoescape: 'bool' = False) -> 'ColumnOperators'
| Implement the ``istartswith`` operator, e.g. case insensitive
| version of :meth:`.ColumnOperators.startswith`.
|
| Produces a LIKE expression that tests against an insensitive
| match for the start of a string value:
|
| .. sourcecode:: sql
|
| lower(column) LIKE lower(<other>) || '%'
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.istartswith("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.istartswith.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.istartswith.escape` parameter will
| establish a given character as an escape character which can be of
| use when the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.istartswith.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.istartswith("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE lower(:param) || '%' ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.istartswith("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE lower(:param) || '%' ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.istartswith.autoescape`::
|
| somecolumn.istartswith("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.startswith`
|
| like(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
| Implement the ``like`` operator.
|
| In a column context, produces the expression:
|
| .. sourcecode:: sql
|
| a LIKE other
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.like("%foobar%"))
|
| :param other: expression to be compared
| :param escape: optional escape character, renders the ``ESCAPE``
| keyword, e.g.::
|
| somecolumn.like("foo/%bar", escape="/")
|
| .. seealso::
|
| :meth:`.ColumnOperators.ilike`
|
| match(self, other: 'Any', **kwargs: 'Any') -> 'ColumnOperators'
| Implements a database-specific 'match' operator.
|
| :meth:`_sql.ColumnOperators.match` attempts to resolve to
| a MATCH-like function or operator provided by the backend.
| Examples include:
|
| * PostgreSQL - renders ``x @@ plainto_tsquery(y)``
|
| .. versionchanged:: 2.0 ``plainto_tsquery()`` is used instead
| of ``to_tsquery()`` for PostgreSQL now; for compatibility with
| other forms, see :ref:`postgresql_match`.
|
|
| * MySQL - renders ``MATCH (x) AGAINST (y IN BOOLEAN MODE)``
|
| .. seealso::
|
| :class:`_mysql.match` - MySQL specific construct with
| additional features.
|
| * Oracle Database - renders ``CONTAINS(x, y)``
| * other backends may provide special implementations.
| * Backends without any special implementation will emit
| the operator as "MATCH". This is compatible with SQLite, for
| example.
|
| not_ilike(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
| implement the ``NOT ILIKE`` operator.
|
| This is equivalent to using negation with
| :meth:`.ColumnOperators.ilike`, i.e. ``~x.ilike(y)``.
|
| .. versionchanged:: 1.4 The ``not_ilike()`` operator is renamed from
| ``notilike()`` in previous releases. The previous name remains
| available for backwards compatibility.
|
| .. seealso::
|
| :meth:`.ColumnOperators.ilike`
|
| not_in(self, other: 'Any') -> 'ColumnOperators'
| implement the ``NOT IN`` operator.
|
| This is equivalent to using negation with
| :meth:`.ColumnOperators.in_`, i.e. ``~x.in_(y)``.
|
| In the case that ``other`` is an empty sequence, the compiler
| produces an "empty not in" expression. This defaults to the
| expression "1 = 1" to produce true in all cases. The
| :paramref:`_sa.create_engine.empty_in_strategy` may be used to
| alter this behavior.
|
| .. versionchanged:: 1.4 The ``not_in()`` operator is renamed from
| ``notin_()`` in previous releases. The previous name remains
| available for backwards compatibility.
|
| .. versionchanged:: 1.2 The :meth:`.ColumnOperators.in_` and
| :meth:`.ColumnOperators.not_in` operators
| now produce a "static" expression for an empty IN sequence
| by default.
|
| .. seealso::
|
| :meth:`.ColumnOperators.in_`
|
| not_like(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
| implement the ``NOT LIKE`` operator.
|
| This is equivalent to using negation with
| :meth:`.ColumnOperators.like`, i.e. ``~x.like(y)``.
|
| .. versionchanged:: 1.4 The ``not_like()`` operator is renamed from
| ``notlike()`` in previous releases. The previous name remains
| available for backwards compatibility.
|
| .. seealso::
|
| :meth:`.ColumnOperators.like`
|
| notilike = not_ilike(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
|
| notin_ = not_in(self, other: 'Any') -> 'ColumnOperators'
|
| notlike = not_like(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
|
| nulls_first(self) -> 'ColumnOperators'
| Produce a :func:`_expression.nulls_first` clause against the
| parent object.
|
| .. versionchanged:: 1.4 The ``nulls_first()`` operator is
| renamed from ``nullsfirst()`` in previous releases.
| The previous name remains available for backwards compatibility.
|
| nulls_last(self) -> 'ColumnOperators'
| Produce a :func:`_expression.nulls_last` clause against the
| parent object.
|
| .. versionchanged:: 1.4 The ``nulls_last()`` operator is
| renamed from ``nullslast()`` in previous releases.
| The previous name remains available for backwards compatibility.
|
| nullsfirst = nulls_first(self) -> 'ColumnOperators'
|
| nullslast = nulls_last(self) -> 'ColumnOperators'
|
| regexp_match(self, pattern: 'Any', flags: 'Optional[str]' = None) -> 'ColumnOperators'
| Implements a database-specific 'regexp match' operator.
|
| E.g.::
|
| stmt = select(table.c.some_column).where(
| table.c.some_column.regexp_match("^(b|c)")
| )
|
| :meth:`_sql.ColumnOperators.regexp_match` attempts to resolve to
| a REGEXP-like function or operator provided by the backend, however
| the specific regular expression syntax and flags available are
| **not backend agnostic**.
|
| Examples include:
|
| * PostgreSQL - renders ``x ~ y`` or ``x !~ y`` when negated.
| * Oracle Database - renders ``REGEXP_LIKE(x, y)``
| * SQLite - uses SQLite's ``REGEXP`` placeholder operator and calls into
| the Python ``re.match()`` builtin.
| * other backends may provide special implementations.
| * Backends without any special implementation will emit
| the operator as "REGEXP" or "NOT REGEXP". This is compatible with
| SQLite and MySQL, for example.
|
| Regular expression support is currently implemented for Oracle
| Database, PostgreSQL, MySQL and MariaDB. Partial support is available
| for SQLite. Support among third-party dialects may vary.
|
| :param pattern: The regular expression pattern string or column
| clause.
| :param flags: Any regular expression string flags to apply, passed as
| plain Python string only. These flags are backend specific.
| Some backends, like PostgreSQL and MariaDB, may alternatively
| specify the flags as part of the pattern.
| When using the ignore case flag 'i' in PostgreSQL, the ignore case
| regexp match operator ``~*`` or ``!~*`` will be used.
|
| .. versionadded:: 1.4
|
| .. versionchanged:: 1.4.48, 2.0.18 Note that due to an implementation
| error, the "flags" parameter previously accepted SQL expression
| objects such as column expressions in addition to plain Python
| strings. This implementation did not work correctly with caching
| and was removed; strings only should be passed for the "flags"
| parameter, as these flags are rendered as literal inline values
| within SQL expressions.
|
| .. seealso::
|
| :meth:`_sql.ColumnOperators.regexp_replace`
|
| regexp_replace(self, pattern: 'Any', replacement: 'Any', flags: 'Optional[str]' = None) -> 'ColumnOperators'
| Implements a database-specific 'regexp replace' operator.
|
| E.g.::
|
| stmt = select(
| table.c.some_column.regexp_replace("b(..)", "XY", flags="g")
| )
|
| :meth:`_sql.ColumnOperators.regexp_replace` attempts to resolve to
| a REGEXP_REPLACE-like function provided by the backend, that
| usually emit the function ``REGEXP_REPLACE()``. However,
| the specific regular expression syntax and flags available are
| **not backend agnostic**.
|
| Regular expression replacement support is currently implemented for
| Oracle Database, PostgreSQL, MySQL 8 or greater and MariaDB. Support
| among third-party dialects may vary.
|
| :param pattern: The regular expression pattern string or column
| clause.
| :param pattern: The replacement string or column clause.
| :param flags: Any regular expression string flags to apply, passed as
| plain Python string only. These flags are backend specific.
| Some backends, like PostgreSQL and MariaDB, may alternatively
| specify the flags as part of the pattern.
|
| .. versionadded:: 1.4
|
| .. versionchanged:: 1.4.48, 2.0.18 Note that due to an implementation
| error, the "flags" parameter previously accepted SQL expression
| objects such as column expressions in addition to plain Python
| strings. This implementation did not work correctly with caching
| and was removed; strings only should be passed for the "flags"
| parameter, as these flags are rendered as literal inline values
| within SQL expressions.
|
|
| .. seealso::
|
| :meth:`_sql.ColumnOperators.regexp_match`
|
| startswith(self, other: 'Any', escape: 'Optional[str]' = None, autoescape: 'bool' = False) -> 'ColumnOperators'
| Implement the ``startswith`` operator.
|
| Produces a LIKE expression that tests against a match for the start
| of a string value:
|
| .. sourcecode:: sql
|
| column LIKE <other> || '%'
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.startswith("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.startswith.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.startswith.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.startswith.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.startswith("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE :param || '%' ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.startswith("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE :param || '%' ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.startswith.autoescape`::
|
| somecolumn.startswith("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.endswith`
|
| :meth:`.ColumnOperators.contains`
|
| :meth:`.ColumnOperators.like`
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.operators.ColumnOperators:
|
| timetuple = None
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.operators.Operators:
|
| __and__(self, other: 'Any') -> 'Operators'
| Implement the ``&`` operator.
|
| When used with SQL expressions, results in an
| AND operation, equivalent to
| :func:`_expression.and_`, that is::
|
| a & b
|
| is equivalent to::
|
| from sqlalchemy import and_
|
| and_(a, b)
|
| Care should be taken when using ``&`` regarding
| operator precedence; the ``&`` operator has the highest precedence.
| The operands should be enclosed in parenthesis if they contain
| further sub expressions::
|
| (a == 2) & (b == 4)
|
| __invert__(self) -> 'Operators'
| Implement the ``~`` operator.
|
| When used with SQL expressions, results in a
| NOT operation, equivalent to
| :func:`_expression.not_`, that is::
|
| ~a
|
| is equivalent to::
|
| from sqlalchemy import not_
|
| not_(a)
|
| __or__(self, other: 'Any') -> 'Operators'
| Implement the ``|`` operator.
|
| When used with SQL expressions, results in an
| OR operation, equivalent to
| :func:`_expression.or_`, that is::
|
| a | b
|
| is equivalent to::
|
| from sqlalchemy import or_
|
| or_(a, b)
|
| Care should be taken when using ``|`` regarding
| operator precedence; the ``|`` operator has the highest precedence.
| The operands should be enclosed in parenthesis if they contain
| further sub expressions::
|
| (a == 2) | (b == 4)
|
| __sa_operate__ = operate(self, op: 'OperatorType', *other: 'Any', **kwargs: 'Any') -> 'Operators'
| Operate on an argument.
|
| This is the lowest level of operation, raises
| :class:`NotImplementedError` by default.
|
| Overriding this on a subclass can allow common
| behavior to be applied to all operations.
| For example, overriding :class:`.ColumnOperators`
| to apply ``func.lower()`` to the left and right
| side::
|
| class MyComparator(ColumnOperators):
| def operate(self, op, other, **kwargs):
| return op(func.lower(self), func.lower(other), **kwargs)
|
| :param op: Operator callable.
| :param \*other: the 'other' side of the operation. Will
| be a single scalar for most operations.
| :param \**kwargs: modifiers. These may be passed by special
| operators such as :meth:`ColumnOperators.contains`.
|
| bool_op(self, opstring: 'str', precedence: 'int' = 0, python_impl: 'Optional[Callable[..., Any]]' = None) -> 'Callable[[Any], Operators]'
| Return a custom boolean operator.
|
| This method is shorthand for calling
| :meth:`.Operators.op` and passing the
| :paramref:`.Operators.op.is_comparison`
| flag with True. A key advantage to using :meth:`.Operators.bool_op`
| is that when using column constructs, the "boolean" nature of the
| returned expression will be present for :pep:`484` purposes.
|
| .. seealso::
|
| :meth:`.Operators.op`
|
| op(self, opstring: 'str', precedence: 'int' = 0, is_comparison: 'bool' = False, return_type: 'Optional[Union[Type[TypeEngine[Any]], TypeEngine[Any]]]' = None, python_impl: 'Optional[Callable[..., Any]]' = None) -> 'Callable[[Any], Operators]'
| Produce a generic operator function.
|
| e.g.::
|
| somecolumn.op("*")(5)
|
| produces::
|
| somecolumn * 5
|
| This function can also be used to make bitwise operators explicit. For
| example::
|
| somecolumn.op("&")(0xFF)
|
| is a bitwise AND of the value in ``somecolumn``.
|
| :param opstring: a string which will be output as the infix operator
| between this element and the expression passed to the
| generated function.
|
| :param precedence: precedence which the database is expected to apply
| to the operator in SQL expressions. This integer value acts as a hint
| for the SQL compiler to know when explicit parenthesis should be
| rendered around a particular operation. A lower number will cause the
| expression to be parenthesized when applied against another operator
| with higher precedence. The default value of ``0`` is lower than all
| operators except for the comma (``,``) and ``AS`` operators. A value
| of 100 will be higher or equal to all operators, and -100 will be
| lower than or equal to all operators.
|
| .. seealso::
|
| :ref:`faq_sql_expression_op_parenthesis` - detailed description
| of how the SQLAlchemy SQL compiler renders parenthesis
|
| :param is_comparison: legacy; if True, the operator will be considered
| as a "comparison" operator, that is which evaluates to a boolean
| true/false value, like ``==``, ``>``, etc. This flag is provided
| so that ORM relationships can establish that the operator is a
| comparison operator when used in a custom join condition.
|
| Using the ``is_comparison`` parameter is superseded by using the
| :meth:`.Operators.bool_op` method instead; this more succinct
| operator sets this parameter automatically, but also provides
| correct :pep:`484` typing support as the returned object will
| express a "boolean" datatype, i.e. ``BinaryExpression[bool]``.
|
| :param return_type: a :class:`.TypeEngine` class or object that will
| force the return type of an expression produced by this operator
| to be of that type. By default, operators that specify
| :paramref:`.Operators.op.is_comparison` will resolve to
| :class:`.Boolean`, and those that do not will be of the same
| type as the left-hand operand.
|
| :param python_impl: an optional Python function that can evaluate
| two Python values in the same way as this operator works when
| run on the database server. Useful for in-Python SQL expression
| evaluation functions, such as for ORM hybrid attributes, and the
| ORM "evaluator" used to match objects in a session after a multi-row
| update or delete.
|
| e.g.::
|
| >>> expr = column("x").op("+", python_impl=lambda a, b: a + b)("y")
|
| The operator for the above expression will also work for non-SQL
| left and right objects::
|
| >>> expr.operator(5, 10)
| 15
|
| .. versionadded:: 2.0
|
|
| .. seealso::
|
| :meth:`.Operators.bool_op`
|
| :ref:`types_operators`
|
| :ref:`relationship_custom_operator`
|
| ----------------------------------------------------------------------
| Methods inherited from ClauseElement:
|
| __bool__(self)
|
| __getstate__(self)
| Helper for pickle.
|
| __repr__(self)
| Return repr(self).
|
| compare(self, other: 'ClauseElement', **kw: 'Any') -> 'bool'
| Compare this :class:`_expression.ClauseElement` to
| the given :class:`_expression.ClauseElement`.
|
| Subclasses should override the default behavior, which is a
| straight identity comparison.
|
| \**kw are arguments consumed by subclass ``compare()`` methods and
| may be used to modify the criteria for comparison
| (see :class:`_expression.ColumnElement`).
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from ClauseElement:
|
| is_clause_element = True
|
| is_dml = False
|
| is_selectable = False
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.cache_key.HasCacheKey:
|
| inherit_cache = None
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_instancemethod(fn: '_F') -> '_F'
| Decorate a method memoize its return value.
|
| :meta private:
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_attribute = <class 'sqlalchemy.util.langhelpers.HasMemoized.m...
| A read-only @property that is only evaluated once.
|
| :meta private:
|
|
| ----------------------------------------------------------------------
| Methods inherited from CompilerElement:
|
| __str__(self) -> 'str'
| Return str(self).
|
| compile(self, bind: 'Optional[_HasDialect]' = None, dialect: 'Optional[Dialect]' = None, **kw: 'Any') -> 'Compiled'
| Compile this SQL expression.
|
| The return value is a :class:`~.Compiled` object.
| Calling ``str()`` or ``unicode()`` on the returned value will yield a
| string representation of the result. The
| :class:`~.Compiled` object also can return a
| dictionary of bind parameter names and values
| using the ``params`` accessor.
|
| :param bind: An :class:`.Connection` or :class:`.Engine` which
| can provide a :class:`.Dialect` in order to generate a
| :class:`.Compiled` object. If the ``bind`` and
| ``dialect`` parameters are both omitted, a default SQL compiler
| is used.
|
| :param column_keys: Used for INSERT and UPDATE statements, a list of
| column names which should be present in the VALUES clause of the
| compiled statement. If ``None``, all columns from the target table
| object are rendered.
|
| :param dialect: A :class:`.Dialect` instance which can generate
| a :class:`.Compiled` object. This argument takes precedence over
| the ``bind`` argument.
|
| :param compile_kwargs: optional dictionary of additional parameters
| that will be passed through to the compiler within all "visit"
| methods. This allows any custom flag to be passed through to
| a custom compilation construct, for example. It is also used
| for the case of passing the ``literal_binds`` flag through::
|
| from sqlalchemy.sql import table, column, select
|
| t = table("t", column("x"))
|
| s = select(t).where(t.c.x == 5)
|
| print(s.compile(compile_kwargs={"literal_binds": True}))
|
| .. seealso::
|
| :ref:`faq_sql_expression_string`
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from CompilerElement:
|
| stringify_dialect = 'default'
|
| supports_execution = False
sqlalchemy.ColumnCollection
Python Library Documentation: class ColumnCollection in module sqlalchemy.sql.base
class ColumnCollection(typing.Generic)
| ColumnCollection(columns: 'Optional[Iterable[Tuple[_COLKEY, _COL_co]]]' = None)
|
| Collection of :class:`_expression.ColumnElement` instances,
| typically for
| :class:`_sql.FromClause` objects.
|
| The :class:`_sql.ColumnCollection` object is most commonly available
| as the :attr:`_schema.Table.c` or :attr:`_schema.Table.columns` collection
| on the :class:`_schema.Table` object, introduced at
| :ref:`metadata_tables_and_columns`.
|
| The :class:`_expression.ColumnCollection` has both mapping- and sequence-
| like behaviors. A :class:`_expression.ColumnCollection` usually stores
| :class:`_schema.Column` objects, which are then accessible both via mapping
| style access as well as attribute access style.
|
| To access :class:`_schema.Column` objects using ordinary attribute-style
| access, specify the name like any other object attribute, such as below
| a column named ``employee_name`` is accessed::
|
| >>> employee_table.c.employee_name
|
| To access columns that have names with special characters or spaces,
| index-style access is used, such as below which illustrates a column named
| ``employee ' payment`` is accessed::
|
| >>> employee_table.c["employee ' payment"]
|
| As the :class:`_sql.ColumnCollection` object provides a Python dictionary
| interface, common dictionary method names like
| :meth:`_sql.ColumnCollection.keys`, :meth:`_sql.ColumnCollection.values`,
| and :meth:`_sql.ColumnCollection.items` are available, which means that
| database columns that are keyed under these names also need to use indexed
| access::
|
| >>> employee_table.c["values"]
|
|
| The name for which a :class:`_schema.Column` would be present is normally
| that of the :paramref:`_schema.Column.key` parameter. In some contexts,
| such as a :class:`_sql.Select` object that uses a label style set
| using the :meth:`_sql.Select.set_label_style` method, a column of a certain
| key may instead be represented under a particular label name such
| as ``tablename_columnname``::
|
| >>> from sqlalchemy import select, column, table
| >>> from sqlalchemy import LABEL_STYLE_TABLENAME_PLUS_COL
| >>> t = table("t", column("c"))
| >>> stmt = select(t).set_label_style(LABEL_STYLE_TABLENAME_PLUS_COL)
| >>> subq = stmt.subquery()
| >>> subq.c.t_c
| <sqlalchemy.sql.elements.ColumnClause at 0x7f59dcf04fa0; t_c>
|
| :class:`.ColumnCollection` also indexes the columns in order and allows
| them to be accessible by their integer position::
|
| >>> cc[0]
| Column('x', Integer(), table=None)
| >>> cc[1]
| Column('y', Integer(), table=None)
|
| .. versionadded:: 1.4 :class:`_expression.ColumnCollection`
| allows integer-based
| index access to the collection.
|
| Iterating the collection yields the column expressions in order::
|
| >>> list(cc)
| [Column('x', Integer(), table=None),
| Column('y', Integer(), table=None)]
|
| The base :class:`_expression.ColumnCollection` object can store
| duplicates, which can
| mean either two columns with the same key, in which case the column
| returned by key access is **arbitrary**::
|
| >>> x1, x2 = Column("x", Integer), Column("x", Integer)
| >>> cc = ColumnCollection(columns=[(x1.name, x1), (x2.name, x2)])
| >>> list(cc)
| [Column('x', Integer(), table=None),
| Column('x', Integer(), table=None)]
| >>> cc["x"] is x1
| False
| >>> cc["x"] is x2
| True
|
| Or it can also mean the same column multiple times. These cases are
| supported as :class:`_expression.ColumnCollection`
| is used to represent the columns in
| a SELECT statement which may include duplicates.
|
| A special subclass :class:`.DedupeColumnCollection` exists which instead
| maintains SQLAlchemy's older behavior of not allowing duplicates; this
| collection is used for schema level objects like :class:`_schema.Table`
| and
| :class:`.PrimaryKeyConstraint` where this deduping is helpful. The
| :class:`.DedupeColumnCollection` class also has additional mutation methods
| as the schema constructs have more use cases that require removal and
| replacement of columns.
|
| .. versionchanged:: 1.4 :class:`_expression.ColumnCollection`
| now stores duplicate
| column keys as well as the same column in multiple positions. The
| :class:`.DedupeColumnCollection` class is added to maintain the
| former behavior in those cases where deduplication as well as
| additional replace/remove operations are needed.
|
| Method resolution order:
| ColumnCollection
| typing.Generic
| builtins.object
|
| Methods defined here:
|
| __bool__(self) -> 'bool'
|
| __clause_element__(self) -> 'ClauseList'
|
| __contains__(self, key: 'str') -> 'bool'
|
| __delitem__(self, key: 'str') -> 'NoReturn'
|
| __eq__(self, other: 'Any') -> 'bool'
| Return self==value.
|
| __getattr__(self, key: 'str') -> '_COL_co'
|
| __getitem__(self, key: 'Union[str, int, slice, Tuple[Union[str, int], ...]]') -> 'Union[ReadOnlyColumnCollection[_COLKEY, _COL_co], _COL_co]'
|
| __getstate__(self) -> 'Dict[str, Any]'
| Helper for pickle.
|
| __init__(self, columns: 'Optional[Iterable[Tuple[_COLKEY, _COL_co]]]' = None)
| Initialize self. See help(type(self)) for accurate signature.
|
| __iter__(self) -> 'Iterator[_COL_co]'
|
| __len__(self) -> 'int'
|
| __setattr__(self, key: 'str', obj: 'Any') -> 'NoReturn'
| Implement setattr(self, name, value).
|
| __setitem__(self, key: 'str', value: 'Any') -> 'NoReturn'
|
| __setstate__(self, state: 'Dict[str, Any]') -> 'None'
|
| __str__(self) -> 'str'
| Return str(self).
|
| add(self, column: 'ColumnElement[Any]', key: 'Optional[_COLKEY]' = None) -> 'None'
| Add a column to this :class:`_sql.ColumnCollection`.
|
| .. note::
|
| This method is **not normally used by user-facing code**, as the
| :class:`_sql.ColumnCollection` is usually part of an existing
| object such as a :class:`_schema.Table`. To add a
| :class:`_schema.Column` to an existing :class:`_schema.Table`
| object, use the :meth:`_schema.Table.append_column` method.
|
| as_readonly(self) -> 'ReadOnlyColumnCollection[_COLKEY, _COL_co]'
| Return a "read only" form of this
| :class:`_sql.ColumnCollection`.
|
| clear(self) -> 'NoReturn'
| Dictionary clear() is not implemented for
| :class:`_sql.ColumnCollection`.
|
| compare(self, other: 'ColumnCollection[_COLKEY, _COL_co]') -> 'bool'
| Compare this :class:`_expression.ColumnCollection` to another
| based on the names of the keys
|
| contains_column(self, col: 'ColumnElement[Any]') -> 'bool'
| Checks if a column object exists in this collection
|
| corresponding_column(self, column: '_COL', require_embedded: 'bool' = False) -> 'Optional[Union[_COL, _COL_co]]'
| Given a :class:`_expression.ColumnElement`, return the exported
| :class:`_expression.ColumnElement` object from this
| :class:`_expression.ColumnCollection`
| 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::
|
| :meth:`_expression.Selectable.corresponding_column`
| - invokes this method
| against the collection returned by
| :attr:`_expression.Selectable.exported_columns`.
|
| .. versionchanged:: 1.4 the implementation for ``corresponding_column``
| was moved onto the :class:`_expression.ColumnCollection` itself.
|
| get(self, key: 'str', default: 'Optional[_COL]' = None) -> 'Optional[Union[_COL_co, _COL]]'
| Get a :class:`_sql.ColumnClause` or :class:`_schema.Column` object
| based on a string key name from this
| :class:`_expression.ColumnCollection`.
|
| items(self) -> 'List[Tuple[_COLKEY, _COL_co]]'
| Return a sequence of (key, column) tuples for all columns in this
| collection each consisting of a string key name and a
| :class:`_sql.ColumnClause` or
| :class:`_schema.Column` object.
|
| keys(self) -> 'List[_COLKEY]'
| Return a sequence of string key names for all columns in this
| collection.
|
| remove(self, column: 'Any') -> 'NoReturn'
|
| update(self, iter_: 'Any') -> 'NoReturn'
| Dictionary update() is not implemented for
| :class:`_sql.ColumnCollection`.
|
| values(self) -> 'List[_COL_co]'
| Return a sequence of :class:`_sql.ColumnClause` or
| :class:`_schema.Column` objects for all columns in this
| collection.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'__hash__': 'Optional[int]', '_collection': 'List[T...
|
| __hash__ = None
|
| __orig_bases__ = (typing.Generic[~_COLKEY, +_COL_co],)
|
| __parameters__ = (~_COLKEY, +_COL_co)
|
| ----------------------------------------------------------------------
| Class methods inherited from typing.Generic:
|
| __class_getitem__(...)
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__(...)
| Function to initialize subclasses.
sqlalchemy.ColumnDefault
Python Library Documentation: class ColumnDefault in module sqlalchemy.sql.schema
class ColumnDefault(DefaultGenerator, abc.ABC)
| ColumnDefault(arg: 'Any' = None, for_update: 'bool' = False) -> 'ColumnDefault'
|
| A plain default value on a column.
|
| This could correspond to a constant, a callable function,
| or a SQL clause.
|
| :class:`.ColumnDefault` is generated automatically
| whenever the ``default``, ``onupdate`` arguments of
| :class:`_schema.Column` are used. A :class:`.ColumnDefault`
| can be passed positionally as well.
|
| For example, the following::
|
| Column("foo", Integer, default=50)
|
| Is equivalent to::
|
| Column("foo", Integer, ColumnDefault(50))
|
| Method resolution order:
| ColumnDefault
| DefaultGenerator
| sqlalchemy.sql.base.Executable
| sqlalchemy.sql.roles.StatementRole
| sqlalchemy.sql.roles.SQLRole
| SchemaItem
| sqlalchemy.sql.base.SchemaVisitable
| sqlalchemy.sql.base.SchemaEventTarget
| sqlalchemy.event.registry.EventTarget
| sqlalchemy.sql.visitors.Visitable
| abc.ABC
| builtins.object
|
| Methods defined here:
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| ----------------------------------------------------------------------
| Static methods defined here:
|
| __new__(cls, arg: 'Any' = None, for_update: 'bool' = False) -> 'ColumnDefault'
| Construct a new :class:`.ColumnDefault`.
|
|
| :param arg: argument representing the default value.
| May be one of the following:
|
| * a plain non-callable Python value, such as a
| string, integer, boolean, or other simple type.
| The default value will be used as is each time.
| * a SQL expression, that is one which derives from
| :class:`_expression.ColumnElement`. The SQL expression will
| be rendered into the INSERT or UPDATE statement,
| or in the case of a primary key column when
| RETURNING is not used may be
| pre-executed before an INSERT within a SELECT.
| * A Python callable. The function will be invoked for each
| new row subject to an INSERT or UPDATE.
| The callable must accept exactly
| zero or one positional arguments. The one-argument form
| will receive an instance of the :class:`.ExecutionContext`,
| which provides contextual information as to the current
| :class:`_engine.Connection` in use as well as the current
| statement and parameters.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __abstractmethods__ = frozenset()
|
| __annotations__ = {'arg': 'Any'}
|
| ----------------------------------------------------------------------
| Methods inherited from DefaultGenerator:
|
| __init__(self, for_update: 'bool' = False) -> 'None'
| Initialize self. See help(type(self)) for accurate signature.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from DefaultGenerator:
|
| __visit_name__ = 'default_generator'
|
| has_arg = False
|
| is_callable = False
|
| is_clause_element = False
|
| is_identity = False
|
| is_scalar = False
|
| is_sentinel = False
|
| is_sequence = False
|
| is_server_default = False
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.base.Executable:
|
| execution_options(self, **kw: 'Any') -> 'Self'
| Set non-SQL options for the statement which take effect during
| execution.
|
| Execution options can be set at many scopes, including per-statement,
| per-connection, or per execution, using methods such as
| :meth:`_engine.Connection.execution_options` and parameters which
| accept a dictionary of options such as
| :paramref:`_engine.Connection.execute.execution_options` and
| :paramref:`_orm.Session.execute.execution_options`.
|
| The primary characteristic of an execution option, as opposed to
| other kinds of options such as ORM loader options, is that
| **execution options never affect the compiled SQL of a query, only
| things that affect how the SQL statement itself is invoked or how
| results are fetched**. That is, execution options are not part of
| what's accommodated by SQL compilation nor are they considered part of
| the cached state of a statement.
|
| The :meth:`_sql.Executable.execution_options` method is
| :term:`generative`, as
| is the case for the method as applied to the :class:`_engine.Engine`
| and :class:`_orm.Query` objects, which means when the method is called,
| a copy of the object is returned, which applies the given parameters to
| that new copy, but leaves the original unchanged::
|
| statement = select(table.c.x, table.c.y)
| new_statement = statement.execution_options(my_option=True)
|
| An exception to this behavior is the :class:`_engine.Connection`
| object, where the :meth:`_engine.Connection.execution_options` method
| is explicitly **not** generative.
|
| The kinds of options that may be passed to
| :meth:`_sql.Executable.execution_options` and other related methods and
| parameter dictionaries include parameters that are explicitly consumed
| by SQLAlchemy Core or ORM, as well as arbitrary keyword arguments not
| defined by SQLAlchemy, which means the methods and/or parameter
| dictionaries may be used for user-defined parameters that interact with
| custom code, which may access the parameters using methods such as
| :meth:`_sql.Executable.get_execution_options` and
| :meth:`_engine.Connection.get_execution_options`, or within selected
| event hooks using a dedicated ``execution_options`` event parameter
| such as
| :paramref:`_events.ConnectionEvents.before_execute.execution_options`
| or :attr:`_orm.ORMExecuteState.execution_options`, e.g.::
|
| from sqlalchemy import event
|
|
| @event.listens_for(some_engine, "before_execute")
| def _process_opt(conn, statement, multiparams, params, execution_options):
| "run a SQL function before invoking a statement"
|
| if execution_options.get("do_special_thing", False):
| conn.exec_driver_sql("run_special_function()")
|
| Within the scope of options that are explicitly recognized by
| SQLAlchemy, most apply to specific classes of objects and not others.
| The most common execution options include:
|
| * :paramref:`_engine.Connection.execution_options.isolation_level` -
| sets the isolation level for a connection or a class of connections
| via an :class:`_engine.Engine`. This option is accepted only
| by :class:`_engine.Connection` or :class:`_engine.Engine`.
|
| * :paramref:`_engine.Connection.execution_options.stream_results` -
| indicates results should be fetched using a server side cursor;
| this option is accepted by :class:`_engine.Connection`, by the
| :paramref:`_engine.Connection.execute.execution_options` parameter
| on :meth:`_engine.Connection.execute`, and additionally by
| :meth:`_sql.Executable.execution_options` on a SQL statement object,
| as well as by ORM constructs like :meth:`_orm.Session.execute`.
|
| * :paramref:`_engine.Connection.execution_options.compiled_cache` -
| indicates a dictionary that will serve as the
| :ref:`SQL compilation cache <sql_caching>`
| for a :class:`_engine.Connection` or :class:`_engine.Engine`, as
| well as for ORM methods like :meth:`_orm.Session.execute`.
| Can be passed as ``None`` to disable caching for statements.
| This option is not accepted by
| :meth:`_sql.Executable.execution_options` as it is inadvisable to
| carry along a compilation cache within a statement object.
|
| * :paramref:`_engine.Connection.execution_options.schema_translate_map`
| - a mapping of schema names used by the
| :ref:`Schema Translate Map <schema_translating>` feature, accepted
| by :class:`_engine.Connection`, :class:`_engine.Engine`,
| :class:`_sql.Executable`, as well as by ORM constructs
| like :meth:`_orm.Session.execute`.
|
| .. seealso::
|
| :meth:`_engine.Connection.execution_options`
|
| :paramref:`_engine.Connection.execute.execution_options`
|
| :paramref:`_orm.Session.execute.execution_options`
|
| :ref:`orm_queryguide_execution_options` - documentation on all
| ORM-specific execution options
|
| get_execution_options(self) -> '_ExecuteOptions'
| Get the non-SQL options which will take effect during execution.
|
| .. versionadded:: 1.3
|
| .. seealso::
|
| :meth:`.Executable.execution_options`
|
| options(self, *options: 'ExecutableOption') -> 'Self'
| Apply options to this statement.
|
| In the general sense, options are any kind of Python object
| that can be interpreted by the SQL compiler for the statement.
| These options can be consumed by specific dialects or specific kinds
| of compilers.
|
| The most commonly known kind of option are the ORM level options
| that apply "eager load" and other loading behaviors to an ORM
| query. However, options can theoretically be used for many other
| purposes.
|
| For background on specific kinds of options for specific kinds of
| statements, refer to the documentation for those option objects.
|
| .. versionchanged:: 1.4 - added :meth:`.Executable.options` to
| Core statement objects towards the goal of allowing unified
| Core / ORM querying capabilities.
|
| .. seealso::
|
| :ref:`loading_columns` - refers to options specific to the usage
| of ORM queries
|
| :ref:`relationship_loader_options` - refers to options specific
| to the usage of ORM queries
|
| ----------------------------------------------------------------------
| Data descriptors inherited from sqlalchemy.sql.base.Executable:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.base.Executable:
|
| is_delete = False
|
| is_dml = False
|
| is_from_statement = False
|
| is_insert = False
|
| is_select = False
|
| is_text = False
|
| is_update = False
|
| supports_execution = True
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.SQLRole:
|
| allows_lambda = False
|
| uses_inspection = False
|
| ----------------------------------------------------------------------
| Methods inherited from SchemaItem:
|
| info(...)
| Info dictionary associated with the object, allowing user-defined
| data to be associated with this :class:`.SchemaItem`.
|
| The dictionary is automatically generated when first accessed.
| It can also be specified in the constructor of some objects,
| such as :class:`_schema.Table` and :class:`_schema.Column`.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from SchemaItem:
|
| create_drop_stringify_dialect = 'default'
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.base.SchemaEventTarget:
|
| dispatch = <sqlalchemy.event.base.DDLEventsDispatch object>
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.visitors.Visitable:
|
| __class_getitem__(key: 'Any') -> 'Any'
|
| __init_subclass__() -> 'None'
| This method is called when a class is subclassed.
|
| The default implementation does nothing. It may be
| overridden to extend subclasses.
sqlalchemy.ColumnElement
Python Library Documentation: class ColumnElement in module sqlalchemy.sql.elements
class ColumnElement(sqlalchemy.sql.roles.ColumnArgumentOrKeyRole, sqlalchemy.sql.roles.StatementOptionRole, sqlalchemy.sql.roles.WhereHavingRole, sqlalchemy.sql.roles.BinaryElementRole, sqlalchemy.sql.roles.OrderByRole, sqlalchemy.sql.roles.ColumnsClauseRole, sqlalchemy.sql.roles.LimitOffsetRole, sqlalchemy.sql.roles.DMLColumnRole, sqlalchemy.sql.roles.DDLConstraintColumnRole, sqlalchemy.sql.roles.DDLExpressionRole, SQLColumnExpression, DQLDMLClauseElement)
| Represent a column-oriented SQL expression suitable for usage in the
| "columns" clause, WHERE clause etc. of a statement.
|
| While the most familiar kind of :class:`_expression.ColumnElement` is the
| :class:`_schema.Column` object, :class:`_expression.ColumnElement`
| serves as the basis
| for any unit that may be present in a SQL expression, including
| the expressions themselves, SQL functions, bound parameters,
| literal expressions, keywords such as ``NULL``, etc.
| :class:`_expression.ColumnElement`
| is the ultimate base class for all such elements.
|
| A wide variety of SQLAlchemy Core functions work at the SQL expression
| level, and are intended to accept instances of
| :class:`_expression.ColumnElement` as
| arguments. These functions will typically document that they accept a
| "SQL expression" as an argument. What this means in terms of SQLAlchemy
| usually refers to an input which is either already in the form of a
| :class:`_expression.ColumnElement` object,
| or a value which can be **coerced** into
| one. The coercion rules followed by most, but not all, SQLAlchemy Core
| functions with regards to SQL expressions are as follows:
|
| * a literal Python value, such as a string, integer or floating
| point value, boolean, datetime, ``Decimal`` object, or virtually
| any other Python object, will be coerced into a "literal bound
| value". This generally means that a :func:`.bindparam` will be
| produced featuring the given value embedded into the construct; the
| resulting :class:`.BindParameter` object is an instance of
| :class:`_expression.ColumnElement`.
| The Python value will ultimately be sent
| to the DBAPI at execution time as a parameterized argument to the
| ``execute()`` or ``executemany()`` methods, after SQLAlchemy
| type-specific converters (e.g. those provided by any associated
| :class:`.TypeEngine` objects) are applied to the value.
|
| * any special object value, typically ORM-level constructs, which
| feature an accessor called ``__clause_element__()``. The Core
| expression system looks for this method when an object of otherwise
| unknown type is passed to a function that is looking to coerce the
| argument into a :class:`_expression.ColumnElement` and sometimes a
| :class:`_expression.SelectBase` expression.
| It is used within the ORM to
| convert from ORM-specific objects like mapped classes and
| mapped attributes into Core expression objects.
|
| * The Python ``None`` value is typically interpreted as ``NULL``,
| which in SQLAlchemy Core produces an instance of :func:`.null`.
|
| A :class:`_expression.ColumnElement` provides the ability to generate new
| :class:`_expression.ColumnElement`
| objects using Python expressions. This means that Python operators
| such as ``==``, ``!=`` and ``<`` are overloaded to mimic SQL operations,
| and allow the instantiation of further :class:`_expression.ColumnElement`
| instances
| which are composed from other, more fundamental
| :class:`_expression.ColumnElement`
| objects. For example, two :class:`.ColumnClause` objects can be added
| together with the addition operator ``+`` to produce
| a :class:`.BinaryExpression`.
| Both :class:`.ColumnClause` and :class:`.BinaryExpression` are subclasses
| of :class:`_expression.ColumnElement`:
|
| .. sourcecode:: pycon+sql
|
| >>> from sqlalchemy.sql import column
| >>> column("a") + column("b")
| <sqlalchemy.sql.expression.BinaryExpression object at 0x101029dd0>
| >>> print(column("a") + column("b"))
| {printsql}a + b
|
| .. seealso::
|
| :class:`_schema.Column`
|
| :func:`_expression.column`
|
| Method resolution order:
| ColumnElement
| sqlalchemy.sql.roles.ColumnArgumentOrKeyRole
| sqlalchemy.sql.roles.ColumnArgumentRole
| sqlalchemy.sql.roles.StatementOptionRole
| sqlalchemy.sql.roles.WhereHavingRole
| sqlalchemy.sql.roles.OnClauseRole
| sqlalchemy.sql.roles.BinaryElementRole
| sqlalchemy.sql.roles.OrderByRole
| sqlalchemy.sql.roles.ColumnsClauseRole
| sqlalchemy.sql.roles.AllowsLambdaRole
| sqlalchemy.sql.roles.ByOfRole
| sqlalchemy.sql.roles.UsesInspection
| sqlalchemy.sql.roles.ColumnListRole
| sqlalchemy.sql.roles.LimitOffsetRole
| sqlalchemy.sql.roles.DMLColumnRole
| sqlalchemy.sql.roles.DDLConstraintColumnRole
| sqlalchemy.sql.roles.DDLExpressionRole
| sqlalchemy.sql.roles.StructuralRole
| SQLColumnExpression
| SQLCoreOperations
| sqlalchemy.sql.roles.ExpressionElementRole
| sqlalchemy.sql.roles.TypedColumnsClauseRole
| typing.Generic
| sqlalchemy.sql.operators.ColumnOperators
| sqlalchemy.sql.operators.Operators
| sqlalchemy.util.langhelpers.TypingOnly
| sqlalchemy.sql.roles.SQLRole
| DQLDMLClauseElement
| ClauseElement
| sqlalchemy.sql.annotation.SupportsWrappingAnnotations
| sqlalchemy.sql.annotation.SupportsAnnotations
| sqlalchemy.sql.cache_key.MemoizedHasCacheKey
| sqlalchemy.sql.cache_key.HasCacheKey
| sqlalchemy.util.langhelpers.HasMemoized
| sqlalchemy.sql.traversals.HasCopyInternals
| sqlalchemy.sql.visitors.ExternallyTraversible
| sqlalchemy.sql.visitors.HasTraverseInternals
| CompilerElement
| sqlalchemy.sql.visitors.Visitable
| builtins.object
|
| Methods defined here:
|
| __getattr__(self, key: 'str') -> 'Any'
|
| __setstate__(self, state)
|
| base_columns(...)
|
| cast(self, type_: '_TypeEngineArgument[_OPT]') -> 'Cast[_OPT]'
| Produce a type cast, i.e. ``CAST(<expression> AS <type>)``.
|
| This is a shortcut to the :func:`_expression.cast` function.
|
| .. seealso::
|
| :ref:`tutorial_casts`
|
| :func:`_expression.cast`
|
| :func:`_expression.type_coerce`
|
| comparator(...)
|
| label(self, name: 'Optional[str]') -> 'Label[_T]'
| Produce a column label, i.e. ``<columnname> AS <name>``.
|
| This is a shortcut to the :func:`_expression.label` function.
|
| If 'name' is ``None``, an anonymous label name will be generated.
|
| operate(self, op: 'operators.OperatorType', *other: 'Any', **kwargs: 'Any') -> 'ColumnElement[Any]'
| Operate on an argument.
|
| This is the lowest level of operation, raises
| :class:`NotImplementedError` by default.
|
| Overriding this on a subclass can allow common
| behavior to be applied to all operations.
| For example, overriding :class:`.ColumnOperators`
| to apply ``func.lower()`` to the left and right
| side::
|
| class MyComparator(ColumnOperators):
| def operate(self, op, other, **kwargs):
| return op(func.lower(self), func.lower(other), **kwargs)
|
| :param op: Operator callable.
| :param \*other: the 'other' side of the operation. Will
| be a single scalar for most operations.
| :param \**kwargs: modifiers. These may be passed by special
| operators such as :meth:`ColumnOperators.contains`.
|
| proxy_set(...)
| set of all columns we are proxying
|
| as of 2.0 this is explicitly deannotated columns. previously it was
| effectively deannotated columns but wasn't enforced. annotated
| columns should basically not go into sets if at all possible because
| their hashing behavior is very non-performant.
|
| reverse_operate(self, op: 'operators.OperatorType', other: 'Any', **kwargs: 'Any') -> 'ColumnElement[Any]'
| Reverse operate on an argument.
|
| Usage is the same as :meth:`operate`.
|
| self_group(self, against: 'Optional[OperatorType]' = None) -> 'ColumnElement[Any]'
| 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.
|
| shares_lineage(self, othercolumn: 'ColumnElement[Any]') -> 'bool'
| Return True if the given :class:`_expression.ColumnElement`
| has a common ancestor to this :class:`_expression.ColumnElement`.
|
| type(...)
|
| ----------------------------------------------------------------------
| Readonly properties defined here:
|
| anon_key_label
| .. deprecated:: 1.4 The :attr:`_expression.ColumnElement.anon_key_label` attribute is now private, and the public accessor is deprecated.
|
| anon_label
| .. deprecated:: 1.4 The :attr:`_expression.ColumnElement.anon_label` attribute is now private, and the public accessor is deprecated.
|
| expression
| Return a column expression.
|
| Part of the inspection interface; returns self.
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'_alt_names': 'Sequence[str]', '_insert_sentinel': ...
|
| __orig_bases__ = (<class 'sqlalchemy.sql.roles.ColumnArgumentOrKeyRole...
|
| __parameters__ = (~_T,)
|
| __visit_name__ = 'column_element'
|
| foreign_keys = frozenset()
|
| key = None
|
| primary_key = False
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.AllowsLambdaRole:
|
| allows_lambda = True
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.UsesInspection:
|
| uses_inspection = True
|
| ----------------------------------------------------------------------
| Class methods inherited from typing.Generic:
|
| __class_getitem__(...)
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__(...)
| Function to initialize subclasses.
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.operators.ColumnOperators:
|
| __add__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``+`` operator.
|
| In a column context, produces the clause ``a + b``
| if the parent object has non-string affinity.
| If the parent object has a string affinity,
| produces the concatenation operator, ``a || b`` -
| see :meth:`.ColumnOperators.concat`.
|
| __contains__(self, other: 'Any') -> 'ColumnOperators'
|
| __eq__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``==`` operator.
|
| In a column context, produces the clause ``a = b``.
| If the target is ``None``, produces ``a IS NULL``.
|
| __floordiv__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``//`` operator.
|
| In a column context, produces the clause ``a / b``,
| which is the same as "truediv", but considers the result
| type to be integer.
|
| .. versionadded:: 2.0
|
| __ge__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``>=`` operator.
|
| In a column context, produces the clause ``a >= b``.
|
| __getitem__(self, index: 'Any') -> 'ColumnOperators'
| Implement the [] operator.
|
| This can be used by some database-specific types
| such as PostgreSQL ARRAY and HSTORE.
|
| __gt__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``>`` operator.
|
| In a column context, produces the clause ``a > b``.
|
| __hash__(self, /) from builtins.object
| Return hash(self).
|
| __le__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``<=`` operator.
|
| In a column context, produces the clause ``a <= b``.
|
| __lshift__(self, other: 'Any') -> 'ColumnOperators'
| implement the << operator.
|
| Not used by SQLAlchemy core, this is provided
| for custom operator systems which want to use
| << as an extension point.
|
| __lt__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``<`` operator.
|
| In a column context, produces the clause ``a < b``.
|
| __mod__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``%`` operator.
|
| In a column context, produces the clause ``a % b``.
|
| __mul__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``*`` operator.
|
| In a column context, produces the clause ``a * b``.
|
| __ne__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``!=`` operator.
|
| In a column context, produces the clause ``a != b``.
| If the target is ``None``, produces ``a IS NOT NULL``.
|
| __neg__(self) -> 'ColumnOperators'
| Implement the ``-`` operator.
|
| In a column context, produces the clause ``-a``.
|
| __radd__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``+`` operator in reverse.
|
| See :meth:`.ColumnOperators.__add__`.
|
| __rfloordiv__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``//`` operator in reverse.
|
| See :meth:`.ColumnOperators.__floordiv__`.
|
| __rmod__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``%`` operator in reverse.
|
| See :meth:`.ColumnOperators.__mod__`.
|
| __rmul__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``*`` operator in reverse.
|
| See :meth:`.ColumnOperators.__mul__`.
|
| __rshift__(self, other: 'Any') -> 'ColumnOperators'
| implement the >> operator.
|
| Not used by SQLAlchemy core, this is provided
| for custom operator systems which want to use
| >> as an extension point.
|
| __rsub__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``-`` operator in reverse.
|
| See :meth:`.ColumnOperators.__sub__`.
|
| __rtruediv__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``/`` operator in reverse.
|
| See :meth:`.ColumnOperators.__truediv__`.
|
| __sub__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``-`` operator.
|
| In a column context, produces the clause ``a - b``.
|
| __truediv__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``/`` operator.
|
| In a column context, produces the clause ``a / b``, and
| considers the result type to be numeric.
|
| .. versionchanged:: 2.0 The truediv operator against two integers
| is now considered to return a numeric value. Behavior on specific
| backends may vary.
|
| all_(self) -> 'ColumnOperators'
| Produce an :func:`_expression.all_` clause against the
| parent object.
|
| See the documentation for :func:`_sql.all_` for examples.
|
| .. note:: be sure to not confuse the newer
| :meth:`_sql.ColumnOperators.all_` method with the **legacy**
| version of this method, the :meth:`_types.ARRAY.Comparator.all`
| method that's specific to :class:`_types.ARRAY`, which uses a
| different calling style.
|
| any_(self) -> 'ColumnOperators'
| Produce an :func:`_expression.any_` clause against the
| parent object.
|
| See the documentation for :func:`_sql.any_` for examples.
|
| .. note:: be sure to not confuse the newer
| :meth:`_sql.ColumnOperators.any_` method with the **legacy**
| version of this method, the :meth:`_types.ARRAY.Comparator.any`
| method that's specific to :class:`_types.ARRAY`, which uses a
| different calling style.
|
| asc(self) -> 'ColumnOperators'
| Produce a :func:`_expression.asc` clause against the
| parent object.
|
| between(self, cleft: 'Any', cright: 'Any', symmetric: 'bool' = False) -> 'ColumnOperators'
| Produce a :func:`_expression.between` clause against
| the parent object, given the lower and upper range.
|
| bitwise_and(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise AND operation, typically via the ``&``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_lshift(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise LSHIFT operation, typically via the ``<<``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_not(self) -> 'ColumnOperators'
| Produce a bitwise NOT operation, typically via the ``~``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_or(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise OR operation, typically via the ``|``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_rshift(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise RSHIFT operation, typically via the ``>>``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_xor(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise XOR operation, typically via the ``^``
| operator, or ``#`` for PostgreSQL.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| collate(self, collation: 'str') -> 'ColumnOperators'
| Produce a :func:`_expression.collate` clause against
| the parent object, given the collation string.
|
| .. seealso::
|
| :func:`_expression.collate`
|
| concat(self, other: 'Any') -> 'ColumnOperators'
| Implement the 'concat' operator.
|
| In a column context, produces the clause ``a || b``,
| or uses the ``concat()`` operator on MySQL.
|
| contains(self, other: 'Any', **kw: 'Any') -> 'ColumnOperators'
| Implement the 'contains' operator.
|
| Produces a LIKE expression that tests against a match for the middle
| of a string value:
|
| .. sourcecode:: sql
|
| column LIKE '%' || <other> || '%'
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.contains("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.contains.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.contains.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.contains.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.contains("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE '%' || :param || '%' ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.contains("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE '%' || :param || '%' ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.contains.autoescape`::
|
| somecolumn.contains("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.startswith`
|
| :meth:`.ColumnOperators.endswith`
|
| :meth:`.ColumnOperators.like`
|
| desc(self) -> 'ColumnOperators'
| Produce a :func:`_expression.desc` clause against the
| parent object.
|
| distinct(self) -> 'ColumnOperators'
| Produce a :func:`_expression.distinct` clause against the
| parent object.
|
| endswith(self, other: 'Any', escape: 'Optional[str]' = None, autoescape: 'bool' = False) -> 'ColumnOperators'
| Implement the 'endswith' operator.
|
| Produces a LIKE expression that tests against a match for the end
| of a string value:
|
| .. sourcecode:: sql
|
| column LIKE '%' || <other>
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.endswith("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.endswith.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.endswith.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.endswith.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.endswith("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE '%' || :param ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.endswith("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE '%' || :param ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.endswith.autoescape`::
|
| somecolumn.endswith("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.startswith`
|
| :meth:`.ColumnOperators.contains`
|
| :meth:`.ColumnOperators.like`
|
| icontains(self, other: 'Any', **kw: 'Any') -> 'ColumnOperators'
| Implement the ``icontains`` operator, e.g. case insensitive
| version of :meth:`.ColumnOperators.contains`.
|
| Produces a LIKE expression that tests against an insensitive match
| for the middle of a string value:
|
| .. sourcecode:: sql
|
| lower(column) LIKE '%' || lower(<other>) || '%'
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.icontains("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.icontains.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.icontains.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.icontains.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.icontains("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE '%' || lower(:param) || '%' ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.icontains("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE '%' || lower(:param) || '%' ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.contains.autoescape`::
|
| somecolumn.icontains("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.contains`
|
| iendswith(self, other: 'Any', escape: 'Optional[str]' = None, autoescape: 'bool' = False) -> 'ColumnOperators'
| Implement the ``iendswith`` operator, e.g. case insensitive
| version of :meth:`.ColumnOperators.endswith`.
|
| Produces a LIKE expression that tests against an insensitive match
| for the end of a string value:
|
| .. sourcecode:: sql
|
| lower(column) LIKE '%' || lower(<other>)
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.iendswith("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.iendswith.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.iendswith.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.iendswith.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.iendswith("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE '%' || lower(:param) ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.iendswith("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE '%' || lower(:param) ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.iendswith.autoescape`::
|
| somecolumn.endswith("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.endswith`
|
| ilike(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
| Implement the ``ilike`` operator, e.g. case insensitive LIKE.
|
| In a column context, produces an expression either of the form:
|
| .. sourcecode:: sql
|
| lower(a) LIKE lower(other)
|
| Or on backends that support the ILIKE operator:
|
| .. sourcecode:: sql
|
| a ILIKE other
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.ilike("%foobar%"))
|
| :param other: expression to be compared
| :param escape: optional escape character, renders the ``ESCAPE``
| keyword, e.g.::
|
| somecolumn.ilike("foo/%bar", escape="/")
|
| .. seealso::
|
| :meth:`.ColumnOperators.like`
|
| in_(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``in`` operator.
|
| In a column context, produces the clause ``column IN <other>``.
|
| The given parameter ``other`` may be:
|
| * A list of literal values,
| e.g.::
|
| stmt.where(column.in_([1, 2, 3]))
|
| In this calling form, the list of items is converted to a set of
| bound parameters the same length as the list given:
|
| .. sourcecode:: sql
|
| WHERE COL IN (?, ?, ?)
|
| * A list of tuples may be provided if the comparison is against a
| :func:`.tuple_` containing multiple expressions::
|
| from sqlalchemy import tuple_
|
| stmt.where(tuple_(col1, col2).in_([(1, 10), (2, 20), (3, 30)]))
|
| * An empty list,
| e.g.::
|
| stmt.where(column.in_([]))
|
| In this calling form, the expression renders an "empty set"
| expression. These expressions are tailored to individual backends
| and are generally trying to get an empty SELECT statement as a
| subquery. Such as on SQLite, the expression is:
|
| .. sourcecode:: sql
|
| WHERE col IN (SELECT 1 FROM (SELECT 1) WHERE 1!=1)
|
| .. versionchanged:: 1.4 empty IN expressions now use an
| execution-time generated SELECT subquery in all cases.
|
| * A bound parameter, e.g. :func:`.bindparam`, may be used if it
| includes the :paramref:`.bindparam.expanding` flag::
|
| stmt.where(column.in_(bindparam("value", expanding=True)))
|
| In this calling form, the expression renders a special non-SQL
| placeholder expression that looks like:
|
| .. sourcecode:: sql
|
| WHERE COL IN ([EXPANDING_value])
|
| This placeholder expression is intercepted at statement execution
| time to be converted into the variable number of bound parameter
| form illustrated earlier. If the statement were executed as::
|
| connection.execute(stmt, {"value": [1, 2, 3]})
|
| The database would be passed a bound parameter for each value:
|
| .. sourcecode:: sql
|
| WHERE COL IN (?, ?, ?)
|
| .. versionadded:: 1.2 added "expanding" bound parameters
|
| If an empty list is passed, a special "empty list" expression,
| which is specific to the database in use, is rendered. On
| SQLite this would be:
|
| .. sourcecode:: sql
|
| WHERE COL IN (SELECT 1 FROM (SELECT 1) WHERE 1!=1)
|
| .. versionadded:: 1.3 "expanding" bound parameters now support
| empty lists
|
| * a :func:`_expression.select` construct, which is usually a
| correlated scalar select::
|
| stmt.where(
| column.in_(select(othertable.c.y).where(table.c.x == othertable.c.x))
| )
|
| In this calling form, :meth:`.ColumnOperators.in_` renders as given:
|
| .. sourcecode:: sql
|
| WHERE COL IN (SELECT othertable.y
| FROM othertable WHERE othertable.x = table.x)
|
| :param other: a list of literals, a :func:`_expression.select`
| construct, or a :func:`.bindparam` construct that includes the
| :paramref:`.bindparam.expanding` flag set to True.
|
| is_(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``IS`` operator.
|
| Normally, ``IS`` is generated automatically when comparing to a
| value of ``None``, which resolves to ``NULL``. However, explicit
| usage of ``IS`` may be desirable if comparing to boolean values
| on certain platforms.
|
| .. seealso:: :meth:`.ColumnOperators.is_not`
|
| is_distinct_from(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``IS DISTINCT FROM`` operator.
|
| Renders "a IS DISTINCT FROM b" on most platforms;
| on some such as SQLite may render "a IS NOT b".
|
| is_not(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``IS NOT`` operator.
|
| Normally, ``IS NOT`` is generated automatically when comparing to a
| value of ``None``, which resolves to ``NULL``. However, explicit
| usage of ``IS NOT`` may be desirable if comparing to boolean values
| on certain platforms.
|
| .. versionchanged:: 1.4 The ``is_not()`` operator is renamed from
| ``isnot()`` in previous releases. The previous name remains
| available for backwards compatibility.
|
| .. seealso:: :meth:`.ColumnOperators.is_`
|
| is_not_distinct_from(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``IS NOT DISTINCT FROM`` operator.
|
| Renders "a IS NOT DISTINCT FROM b" on most platforms;
| on some such as SQLite may render "a IS b".
|
| .. versionchanged:: 1.4 The ``is_not_distinct_from()`` operator is
| renamed from ``isnot_distinct_from()`` in previous releases.
| The previous name remains available for backwards compatibility.
|
| isnot = is_not(self, other: 'Any') -> 'ColumnOperators'
|
| isnot_distinct_from = is_not_distinct_from(self, other: 'Any') -> 'ColumnOperators'
|
| istartswith(self, other: 'Any', escape: 'Optional[str]' = None, autoescape: 'bool' = False) -> 'ColumnOperators'
| Implement the ``istartswith`` operator, e.g. case insensitive
| version of :meth:`.ColumnOperators.startswith`.
|
| Produces a LIKE expression that tests against an insensitive
| match for the start of a string value:
|
| .. sourcecode:: sql
|
| lower(column) LIKE lower(<other>) || '%'
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.istartswith("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.istartswith.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.istartswith.escape` parameter will
| establish a given character as an escape character which can be of
| use when the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.istartswith.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.istartswith("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE lower(:param) || '%' ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.istartswith("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE lower(:param) || '%' ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.istartswith.autoescape`::
|
| somecolumn.istartswith("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.startswith`
|
| like(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
| Implement the ``like`` operator.
|
| In a column context, produces the expression:
|
| .. sourcecode:: sql
|
| a LIKE other
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.like("%foobar%"))
|
| :param other: expression to be compared
| :param escape: optional escape character, renders the ``ESCAPE``
| keyword, e.g.::
|
| somecolumn.like("foo/%bar", escape="/")
|
| .. seealso::
|
| :meth:`.ColumnOperators.ilike`
|
| match(self, other: 'Any', **kwargs: 'Any') -> 'ColumnOperators'
| Implements a database-specific 'match' operator.
|
| :meth:`_sql.ColumnOperators.match` attempts to resolve to
| a MATCH-like function or operator provided by the backend.
| Examples include:
|
| * PostgreSQL - renders ``x @@ plainto_tsquery(y)``
|
| .. versionchanged:: 2.0 ``plainto_tsquery()`` is used instead
| of ``to_tsquery()`` for PostgreSQL now; for compatibility with
| other forms, see :ref:`postgresql_match`.
|
|
| * MySQL - renders ``MATCH (x) AGAINST (y IN BOOLEAN MODE)``
|
| .. seealso::
|
| :class:`_mysql.match` - MySQL specific construct with
| additional features.
|
| * Oracle Database - renders ``CONTAINS(x, y)``
| * other backends may provide special implementations.
| * Backends without any special implementation will emit
| the operator as "MATCH". This is compatible with SQLite, for
| example.
|
| not_ilike(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
| implement the ``NOT ILIKE`` operator.
|
| This is equivalent to using negation with
| :meth:`.ColumnOperators.ilike`, i.e. ``~x.ilike(y)``.
|
| .. versionchanged:: 1.4 The ``not_ilike()`` operator is renamed from
| ``notilike()`` in previous releases. The previous name remains
| available for backwards compatibility.
|
| .. seealso::
|
| :meth:`.ColumnOperators.ilike`
|
| not_in(self, other: 'Any') -> 'ColumnOperators'
| implement the ``NOT IN`` operator.
|
| This is equivalent to using negation with
| :meth:`.ColumnOperators.in_`, i.e. ``~x.in_(y)``.
|
| In the case that ``other`` is an empty sequence, the compiler
| produces an "empty not in" expression. This defaults to the
| expression "1 = 1" to produce true in all cases. The
| :paramref:`_sa.create_engine.empty_in_strategy` may be used to
| alter this behavior.
|
| .. versionchanged:: 1.4 The ``not_in()`` operator is renamed from
| ``notin_()`` in previous releases. The previous name remains
| available for backwards compatibility.
|
| .. versionchanged:: 1.2 The :meth:`.ColumnOperators.in_` and
| :meth:`.ColumnOperators.not_in` operators
| now produce a "static" expression for an empty IN sequence
| by default.
|
| .. seealso::
|
| :meth:`.ColumnOperators.in_`
|
| not_like(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
| implement the ``NOT LIKE`` operator.
|
| This is equivalent to using negation with
| :meth:`.ColumnOperators.like`, i.e. ``~x.like(y)``.
|
| .. versionchanged:: 1.4 The ``not_like()`` operator is renamed from
| ``notlike()`` in previous releases. The previous name remains
| available for backwards compatibility.
|
| .. seealso::
|
| :meth:`.ColumnOperators.like`
|
| notilike = not_ilike(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
|
| notin_ = not_in(self, other: 'Any') -> 'ColumnOperators'
|
| notlike = not_like(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
|
| nulls_first(self) -> 'ColumnOperators'
| Produce a :func:`_expression.nulls_first` clause against the
| parent object.
|
| .. versionchanged:: 1.4 The ``nulls_first()`` operator is
| renamed from ``nullsfirst()`` in previous releases.
| The previous name remains available for backwards compatibility.
|
| nulls_last(self) -> 'ColumnOperators'
| Produce a :func:`_expression.nulls_last` clause against the
| parent object.
|
| .. versionchanged:: 1.4 The ``nulls_last()`` operator is
| renamed from ``nullslast()`` in previous releases.
| The previous name remains available for backwards compatibility.
|
| nullsfirst = nulls_first(self) -> 'ColumnOperators'
|
| nullslast = nulls_last(self) -> 'ColumnOperators'
|
| regexp_match(self, pattern: 'Any', flags: 'Optional[str]' = None) -> 'ColumnOperators'
| Implements a database-specific 'regexp match' operator.
|
| E.g.::
|
| stmt = select(table.c.some_column).where(
| table.c.some_column.regexp_match("^(b|c)")
| )
|
| :meth:`_sql.ColumnOperators.regexp_match` attempts to resolve to
| a REGEXP-like function or operator provided by the backend, however
| the specific regular expression syntax and flags available are
| **not backend agnostic**.
|
| Examples include:
|
| * PostgreSQL - renders ``x ~ y`` or ``x !~ y`` when negated.
| * Oracle Database - renders ``REGEXP_LIKE(x, y)``
| * SQLite - uses SQLite's ``REGEXP`` placeholder operator and calls into
| the Python ``re.match()`` builtin.
| * other backends may provide special implementations.
| * Backends without any special implementation will emit
| the operator as "REGEXP" or "NOT REGEXP". This is compatible with
| SQLite and MySQL, for example.
|
| Regular expression support is currently implemented for Oracle
| Database, PostgreSQL, MySQL and MariaDB. Partial support is available
| for SQLite. Support among third-party dialects may vary.
|
| :param pattern: The regular expression pattern string or column
| clause.
| :param flags: Any regular expression string flags to apply, passed as
| plain Python string only. These flags are backend specific.
| Some backends, like PostgreSQL and MariaDB, may alternatively
| specify the flags as part of the pattern.
| When using the ignore case flag 'i' in PostgreSQL, the ignore case
| regexp match operator ``~*`` or ``!~*`` will be used.
|
| .. versionadded:: 1.4
|
| .. versionchanged:: 1.4.48, 2.0.18 Note that due to an implementation
| error, the "flags" parameter previously accepted SQL expression
| objects such as column expressions in addition to plain Python
| strings. This implementation did not work correctly with caching
| and was removed; strings only should be passed for the "flags"
| parameter, as these flags are rendered as literal inline values
| within SQL expressions.
|
| .. seealso::
|
| :meth:`_sql.ColumnOperators.regexp_replace`
|
| regexp_replace(self, pattern: 'Any', replacement: 'Any', flags: 'Optional[str]' = None) -> 'ColumnOperators'
| Implements a database-specific 'regexp replace' operator.
|
| E.g.::
|
| stmt = select(
| table.c.some_column.regexp_replace("b(..)", "XY", flags="g")
| )
|
| :meth:`_sql.ColumnOperators.regexp_replace` attempts to resolve to
| a REGEXP_REPLACE-like function provided by the backend, that
| usually emit the function ``REGEXP_REPLACE()``. However,
| the specific regular expression syntax and flags available are
| **not backend agnostic**.
|
| Regular expression replacement support is currently implemented for
| Oracle Database, PostgreSQL, MySQL 8 or greater and MariaDB. Support
| among third-party dialects may vary.
|
| :param pattern: The regular expression pattern string or column
| clause.
| :param pattern: The replacement string or column clause.
| :param flags: Any regular expression string flags to apply, passed as
| plain Python string only. These flags are backend specific.
| Some backends, like PostgreSQL and MariaDB, may alternatively
| specify the flags as part of the pattern.
|
| .. versionadded:: 1.4
|
| .. versionchanged:: 1.4.48, 2.0.18 Note that due to an implementation
| error, the "flags" parameter previously accepted SQL expression
| objects such as column expressions in addition to plain Python
| strings. This implementation did not work correctly with caching
| and was removed; strings only should be passed for the "flags"
| parameter, as these flags are rendered as literal inline values
| within SQL expressions.
|
|
| .. seealso::
|
| :meth:`_sql.ColumnOperators.regexp_match`
|
| startswith(self, other: 'Any', escape: 'Optional[str]' = None, autoescape: 'bool' = False) -> 'ColumnOperators'
| Implement the ``startswith`` operator.
|
| Produces a LIKE expression that tests against a match for the start
| of a string value:
|
| .. sourcecode:: sql
|
| column LIKE <other> || '%'
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.startswith("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.startswith.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.startswith.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.startswith.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.startswith("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE :param || '%' ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.startswith("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE :param || '%' ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.startswith.autoescape`::
|
| somecolumn.startswith("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.endswith`
|
| :meth:`.ColumnOperators.contains`
|
| :meth:`.ColumnOperators.like`
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.operators.ColumnOperators:
|
| timetuple = None
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.operators.Operators:
|
| __and__(self, other: 'Any') -> 'Operators'
| Implement the ``&`` operator.
|
| When used with SQL expressions, results in an
| AND operation, equivalent to
| :func:`_expression.and_`, that is::
|
| a & b
|
| is equivalent to::
|
| from sqlalchemy import and_
|
| and_(a, b)
|
| Care should be taken when using ``&`` regarding
| operator precedence; the ``&`` operator has the highest precedence.
| The operands should be enclosed in parenthesis if they contain
| further sub expressions::
|
| (a == 2) & (b == 4)
|
| __invert__(self) -> 'Operators'
| Implement the ``~`` operator.
|
| When used with SQL expressions, results in a
| NOT operation, equivalent to
| :func:`_expression.not_`, that is::
|
| ~a
|
| is equivalent to::
|
| from sqlalchemy import not_
|
| not_(a)
|
| __or__(self, other: 'Any') -> 'Operators'
| Implement the ``|`` operator.
|
| When used with SQL expressions, results in an
| OR operation, equivalent to
| :func:`_expression.or_`, that is::
|
| a | b
|
| is equivalent to::
|
| from sqlalchemy import or_
|
| or_(a, b)
|
| Care should be taken when using ``|`` regarding
| operator precedence; the ``|`` operator has the highest precedence.
| The operands should be enclosed in parenthesis if they contain
| further sub expressions::
|
| (a == 2) | (b == 4)
|
| __sa_operate__ = operate(self, op: 'OperatorType', *other: 'Any', **kwargs: 'Any') -> 'Operators'
| Operate on an argument.
|
| This is the lowest level of operation, raises
| :class:`NotImplementedError` by default.
|
| Overriding this on a subclass can allow common
| behavior to be applied to all operations.
| For example, overriding :class:`.ColumnOperators`
| to apply ``func.lower()`` to the left and right
| side::
|
| class MyComparator(ColumnOperators):
| def operate(self, op, other, **kwargs):
| return op(func.lower(self), func.lower(other), **kwargs)
|
| :param op: Operator callable.
| :param \*other: the 'other' side of the operation. Will
| be a single scalar for most operations.
| :param \**kwargs: modifiers. These may be passed by special
| operators such as :meth:`ColumnOperators.contains`.
|
| bool_op(self, opstring: 'str', precedence: 'int' = 0, python_impl: 'Optional[Callable[..., Any]]' = None) -> 'Callable[[Any], Operators]'
| Return a custom boolean operator.
|
| This method is shorthand for calling
| :meth:`.Operators.op` and passing the
| :paramref:`.Operators.op.is_comparison`
| flag with True. A key advantage to using :meth:`.Operators.bool_op`
| is that when using column constructs, the "boolean" nature of the
| returned expression will be present for :pep:`484` purposes.
|
| .. seealso::
|
| :meth:`.Operators.op`
|
| op(self, opstring: 'str', precedence: 'int' = 0, is_comparison: 'bool' = False, return_type: 'Optional[Union[Type[TypeEngine[Any]], TypeEngine[Any]]]' = None, python_impl: 'Optional[Callable[..., Any]]' = None) -> 'Callable[[Any], Operators]'
| Produce a generic operator function.
|
| e.g.::
|
| somecolumn.op("*")(5)
|
| produces::
|
| somecolumn * 5
|
| This function can also be used to make bitwise operators explicit. For
| example::
|
| somecolumn.op("&")(0xFF)
|
| is a bitwise AND of the value in ``somecolumn``.
|
| :param opstring: a string which will be output as the infix operator
| between this element and the expression passed to the
| generated function.
|
| :param precedence: precedence which the database is expected to apply
| to the operator in SQL expressions. This integer value acts as a hint
| for the SQL compiler to know when explicit parenthesis should be
| rendered around a particular operation. A lower number will cause the
| expression to be parenthesized when applied against another operator
| with higher precedence. The default value of ``0`` is lower than all
| operators except for the comma (``,``) and ``AS`` operators. A value
| of 100 will be higher or equal to all operators, and -100 will be
| lower than or equal to all operators.
|
| .. seealso::
|
| :ref:`faq_sql_expression_op_parenthesis` - detailed description
| of how the SQLAlchemy SQL compiler renders parenthesis
|
| :param is_comparison: legacy; if True, the operator will be considered
| as a "comparison" operator, that is which evaluates to a boolean
| true/false value, like ``==``, ``>``, etc. This flag is provided
| so that ORM relationships can establish that the operator is a
| comparison operator when used in a custom join condition.
|
| Using the ``is_comparison`` parameter is superseded by using the
| :meth:`.Operators.bool_op` method instead; this more succinct
| operator sets this parameter automatically, but also provides
| correct :pep:`484` typing support as the returned object will
| express a "boolean" datatype, i.e. ``BinaryExpression[bool]``.
|
| :param return_type: a :class:`.TypeEngine` class or object that will
| force the return type of an expression produced by this operator
| to be of that type. By default, operators that specify
| :paramref:`.Operators.op.is_comparison` will resolve to
| :class:`.Boolean`, and those that do not will be of the same
| type as the left-hand operand.
|
| :param python_impl: an optional Python function that can evaluate
| two Python values in the same way as this operator works when
| run on the database server. Useful for in-Python SQL expression
| evaluation functions, such as for ORM hybrid attributes, and the
| ORM "evaluator" used to match objects in a session after a multi-row
| update or delete.
|
| e.g.::
|
| >>> expr = column("x").op("+", python_impl=lambda a, b: a + b)("y")
|
| The operator for the above expression will also work for non-SQL
| left and right objects::
|
| >>> expr.operator(5, 10)
| 15
|
| .. versionadded:: 2.0
|
|
| .. seealso::
|
| :meth:`.Operators.bool_op`
|
| :ref:`types_operators`
|
| :ref:`relationship_custom_operator`
|
| ----------------------------------------------------------------------
| Methods inherited from ClauseElement:
|
| __bool__(self)
|
| __getstate__(self)
| Helper for pickle.
|
| __repr__(self)
| Return repr(self).
|
| compare(self, other: 'ClauseElement', **kw: 'Any') -> 'bool'
| Compare this :class:`_expression.ClauseElement` to
| the given :class:`_expression.ClauseElement`.
|
| Subclasses should override the default behavior, which is a
| straight identity comparison.
|
| \**kw are arguments consumed by subclass ``compare()`` methods and
| may be used to modify the criteria for comparison
| (see :class:`_expression.ColumnElement`).
|
| description(...)
|
| entity_namespace(...)
|
| params(self, _ClauseElement__optionaldict: 'Optional[Mapping[str, Any]]' = None, **kwargs: 'Any') -> 'Self'
| Return a copy with :func:`_expression.bindparam` elements
| replaced.
|
| Returns a copy of this ClauseElement with
| :func:`_expression.bindparam`
| elements replaced with values taken from the given dictionary::
|
| >>> clause = column("x") + bindparam("foo")
| >>> print(clause.compile().params)
| {'foo':None}
| >>> print(clause.params({"foo": 7}).compile().params)
| {'foo':7}
|
| unique_params(self, _ClauseElement__optionaldict: 'Optional[Dict[str, Any]]' = None, **kwargs: 'Any') -> 'Self'
| Return a copy with :func:`_expression.bindparam` elements
| replaced.
|
| Same functionality as :meth:`_expression.ClauseElement.params`,
| except adds `unique=True`
| to affected bind parameters so that multiple statements can be
| used.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from ClauseElement:
|
| is_clause_element = True
|
| is_dml = False
|
| is_selectable = False
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.cache_key.HasCacheKey:
|
| inherit_cache = None
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_instancemethod(fn: '_F') -> '_F'
| Decorate a method memoize its return value.
|
| :meta private:
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_attribute = <class 'sqlalchemy.util.langhelpers.HasMemoized.m...
| A read-only @property that is only evaluated once.
|
| :meta private:
|
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.visitors.HasTraverseInternals:
|
| get_children(self, *, omit_attrs: 'Tuple[str, ...]' = (), **kw: 'Any') -> 'Iterable[HasTraverseInternals]'
| Return immediate child :class:`.visitors.HasTraverseInternals`
| elements of this :class:`.visitors.HasTraverseInternals`.
|
| This is used for visit traversal.
|
| \**kw may contain flags that change the collection that is
| returned, for example to return a subset of items in order to
| cut down on larger traversals, or to return child items from a
| different context (such as schema-level collections instead of
| clause-level).
|
| ----------------------------------------------------------------------
| Methods inherited from CompilerElement:
|
| __str__(self) -> 'str'
| Return str(self).
|
| compile(self, bind: 'Optional[_HasDialect]' = None, dialect: 'Optional[Dialect]' = None, **kw: 'Any') -> 'Compiled'
| Compile this SQL expression.
|
| The return value is a :class:`~.Compiled` object.
| Calling ``str()`` or ``unicode()`` on the returned value will yield a
| string representation of the result. The
| :class:`~.Compiled` object also can return a
| dictionary of bind parameter names and values
| using the ``params`` accessor.
|
| :param bind: An :class:`.Connection` or :class:`.Engine` which
| can provide a :class:`.Dialect` in order to generate a
| :class:`.Compiled` object. If the ``bind`` and
| ``dialect`` parameters are both omitted, a default SQL compiler
| is used.
|
| :param column_keys: Used for INSERT and UPDATE statements, a list of
| column names which should be present in the VALUES clause of the
| compiled statement. If ``None``, all columns from the target table
| object are rendered.
|
| :param dialect: A :class:`.Dialect` instance which can generate
| a :class:`.Compiled` object. This argument takes precedence over
| the ``bind`` argument.
|
| :param compile_kwargs: optional dictionary of additional parameters
| that will be passed through to the compiler within all "visit"
| methods. This allows any custom flag to be passed through to
| a custom compilation construct, for example. It is also used
| for the case of passing the ``literal_binds`` flag through::
|
| from sqlalchemy.sql import table, column, select
|
| t = table("t", column("x"))
|
| s = select(t).where(t.c.x == 5)
|
| print(s.compile(compile_kwargs={"literal_binds": True}))
|
| .. seealso::
|
| :ref:`faq_sql_expression_string`
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from CompilerElement:
|
| stringify_dialect = 'default'
|
| supports_execution = False
sqlalchemy.ColumnExpressionArgument
Python Library Documentation: _UnionGenericAlias in module typing
Union = typing.Union
Union type; Union[X, Y] means either X or Y.
On Python 3.10 and higher, the | operator
can also be used to denote unions;
X | Y means the same thing to the type checker as Union[X, Y].
To define a union, use e.g. Union[int, str]. Details:
- The arguments must be types and there must be at least one.
- None as an argument is a special case and is replaced by
type(None).
- Unions of unions are flattened, e.g.::
assert Union[Union[int, str], float] == Union[int, str, float]
- Unions of a single argument vanish, e.g.::
assert Union[int] == int # The constructor actually returns int
- Redundant arguments are skipped, e.g.::
assert Union[int, str, int] == Union[int, str]
- When comparing unions, the argument order is ignored, e.g.::
assert Union[int, str] == Union[str, int]
- You cannot subclass or instantiate a union.
- You can use Optional[X] as a shorthand for Union[X, None].
sqlalchemy.ColumnOperators
Python Library Documentation: class ColumnOperators in module sqlalchemy.sql.operators
class ColumnOperators(Operators)
| Defines boolean, comparison, and other operators for
| :class:`_expression.ColumnElement` expressions.
|
| By default, all methods call down to
| :meth:`.operate` or :meth:`.reverse_operate`,
| passing in the appropriate operator function from the
| Python builtin ``operator`` module or
| a SQLAlchemy-specific operator function from
| :mod:`sqlalchemy.expression.operators`. For example
| the ``__eq__`` function::
|
| def __eq__(self, other):
| return self.operate(operators.eq, other)
|
| Where ``operators.eq`` is essentially::
|
| def eq(a, b):
| return a == b
|
| The core column expression unit :class:`_expression.ColumnElement`
| overrides :meth:`.Operators.operate` and others
| to return further :class:`_expression.ColumnElement` constructs,
| so that the ``==`` operation above is replaced by a clause
| construct.
|
| .. seealso::
|
| :ref:`types_operators`
|
| :attr:`.TypeEngine.comparator_factory`
|
| :class:`.ColumnOperators`
|
| :class:`.PropComparator`
|
| Method resolution order:
| ColumnOperators
| Operators
| builtins.object
|
| Methods defined here:
|
| __add__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``+`` operator.
|
| In a column context, produces the clause ``a + b``
| if the parent object has non-string affinity.
| If the parent object has a string affinity,
| produces the concatenation operator, ``a || b`` -
| see :meth:`.ColumnOperators.concat`.
|
| __contains__(self, other: 'Any') -> 'ColumnOperators'
|
| __eq__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``==`` operator.
|
| In a column context, produces the clause ``a = b``.
| If the target is ``None``, produces ``a IS NULL``.
|
| __floordiv__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``//`` operator.
|
| In a column context, produces the clause ``a / b``,
| which is the same as "truediv", but considers the result
| type to be integer.
|
| .. versionadded:: 2.0
|
| __ge__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``>=`` operator.
|
| In a column context, produces the clause ``a >= b``.
|
| __getitem__(self, index: 'Any') -> 'ColumnOperators'
| Implement the [] operator.
|
| This can be used by some database-specific types
| such as PostgreSQL ARRAY and HSTORE.
|
| __gt__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``>`` operator.
|
| In a column context, produces the clause ``a > b``.
|
| __hash__(self, /) from builtins.object
| Return hash(self).
|
| __le__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``<=`` operator.
|
| In a column context, produces the clause ``a <= b``.
|
| __lshift__(self, other: 'Any') -> 'ColumnOperators'
| implement the << operator.
|
| Not used by SQLAlchemy core, this is provided
| for custom operator systems which want to use
| << as an extension point.
|
| __lt__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``<`` operator.
|
| In a column context, produces the clause ``a < b``.
|
| __mod__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``%`` operator.
|
| In a column context, produces the clause ``a % b``.
|
| __mul__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``*`` operator.
|
| In a column context, produces the clause ``a * b``.
|
| __ne__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``!=`` operator.
|
| In a column context, produces the clause ``a != b``.
| If the target is ``None``, produces ``a IS NOT NULL``.
|
| __neg__(self) -> 'ColumnOperators'
| Implement the ``-`` operator.
|
| In a column context, produces the clause ``-a``.
|
| __radd__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``+`` operator in reverse.
|
| See :meth:`.ColumnOperators.__add__`.
|
| __rfloordiv__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``//`` operator in reverse.
|
| See :meth:`.ColumnOperators.__floordiv__`.
|
| __rmod__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``%`` operator in reverse.
|
| See :meth:`.ColumnOperators.__mod__`.
|
| __rmul__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``*`` operator in reverse.
|
| See :meth:`.ColumnOperators.__mul__`.
|
| __rshift__(self, other: 'Any') -> 'ColumnOperators'
| implement the >> operator.
|
| Not used by SQLAlchemy core, this is provided
| for custom operator systems which want to use
| >> as an extension point.
|
| __rsub__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``-`` operator in reverse.
|
| See :meth:`.ColumnOperators.__sub__`.
|
| __rtruediv__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``/`` operator in reverse.
|
| See :meth:`.ColumnOperators.__truediv__`.
|
| __sub__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``-`` operator.
|
| In a column context, produces the clause ``a - b``.
|
| __truediv__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``/`` operator.
|
| In a column context, produces the clause ``a / b``, and
| considers the result type to be numeric.
|
| .. versionchanged:: 2.0 The truediv operator against two integers
| is now considered to return a numeric value. Behavior on specific
| backends may vary.
|
| all_(self) -> 'ColumnOperators'
| Produce an :func:`_expression.all_` clause against the
| parent object.
|
| See the documentation for :func:`_sql.all_` for examples.
|
| .. note:: be sure to not confuse the newer
| :meth:`_sql.ColumnOperators.all_` method with the **legacy**
| version of this method, the :meth:`_types.ARRAY.Comparator.all`
| method that's specific to :class:`_types.ARRAY`, which uses a
| different calling style.
|
| any_(self) -> 'ColumnOperators'
| Produce an :func:`_expression.any_` clause against the
| parent object.
|
| See the documentation for :func:`_sql.any_` for examples.
|
| .. note:: be sure to not confuse the newer
| :meth:`_sql.ColumnOperators.any_` method with the **legacy**
| version of this method, the :meth:`_types.ARRAY.Comparator.any`
| method that's specific to :class:`_types.ARRAY`, which uses a
| different calling style.
|
| asc(self) -> 'ColumnOperators'
| Produce a :func:`_expression.asc` clause against the
| parent object.
|
| between(self, cleft: 'Any', cright: 'Any', symmetric: 'bool' = False) -> 'ColumnOperators'
| Produce a :func:`_expression.between` clause against
| the parent object, given the lower and upper range.
|
| bitwise_and(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise AND operation, typically via the ``&``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_lshift(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise LSHIFT operation, typically via the ``<<``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_not(self) -> 'ColumnOperators'
| Produce a bitwise NOT operation, typically via the ``~``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_or(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise OR operation, typically via the ``|``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_rshift(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise RSHIFT operation, typically via the ``>>``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_xor(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise XOR operation, typically via the ``^``
| operator, or ``#`` for PostgreSQL.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| collate(self, collation: 'str') -> 'ColumnOperators'
| Produce a :func:`_expression.collate` clause against
| the parent object, given the collation string.
|
| .. seealso::
|
| :func:`_expression.collate`
|
| concat(self, other: 'Any') -> 'ColumnOperators'
| Implement the 'concat' operator.
|
| In a column context, produces the clause ``a || b``,
| or uses the ``concat()`` operator on MySQL.
|
| contains(self, other: 'Any', **kw: 'Any') -> 'ColumnOperators'
| Implement the 'contains' operator.
|
| Produces a LIKE expression that tests against a match for the middle
| of a string value:
|
| .. sourcecode:: sql
|
| column LIKE '%' || <other> || '%'
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.contains("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.contains.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.contains.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.contains.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.contains("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE '%' || :param || '%' ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.contains("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE '%' || :param || '%' ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.contains.autoescape`::
|
| somecolumn.contains("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.startswith`
|
| :meth:`.ColumnOperators.endswith`
|
| :meth:`.ColumnOperators.like`
|
| desc(self) -> 'ColumnOperators'
| Produce a :func:`_expression.desc` clause against the
| parent object.
|
| distinct(self) -> 'ColumnOperators'
| Produce a :func:`_expression.distinct` clause against the
| parent object.
|
| endswith(self, other: 'Any', escape: 'Optional[str]' = None, autoescape: 'bool' = False) -> 'ColumnOperators'
| Implement the 'endswith' operator.
|
| Produces a LIKE expression that tests against a match for the end
| of a string value:
|
| .. sourcecode:: sql
|
| column LIKE '%' || <other>
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.endswith("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.endswith.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.endswith.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.endswith.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.endswith("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE '%' || :param ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.endswith("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE '%' || :param ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.endswith.autoescape`::
|
| somecolumn.endswith("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.startswith`
|
| :meth:`.ColumnOperators.contains`
|
| :meth:`.ColumnOperators.like`
|
| icontains(self, other: 'Any', **kw: 'Any') -> 'ColumnOperators'
| Implement the ``icontains`` operator, e.g. case insensitive
| version of :meth:`.ColumnOperators.contains`.
|
| Produces a LIKE expression that tests against an insensitive match
| for the middle of a string value:
|
| .. sourcecode:: sql
|
| lower(column) LIKE '%' || lower(<other>) || '%'
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.icontains("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.icontains.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.icontains.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.icontains.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.icontains("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE '%' || lower(:param) || '%' ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.icontains("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE '%' || lower(:param) || '%' ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.contains.autoescape`::
|
| somecolumn.icontains("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.contains`
|
| iendswith(self, other: 'Any', escape: 'Optional[str]' = None, autoescape: 'bool' = False) -> 'ColumnOperators'
| Implement the ``iendswith`` operator, e.g. case insensitive
| version of :meth:`.ColumnOperators.endswith`.
|
| Produces a LIKE expression that tests against an insensitive match
| for the end of a string value:
|
| .. sourcecode:: sql
|
| lower(column) LIKE '%' || lower(<other>)
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.iendswith("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.iendswith.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.iendswith.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.iendswith.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.iendswith("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE '%' || lower(:param) ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.iendswith("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE '%' || lower(:param) ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.iendswith.autoescape`::
|
| somecolumn.endswith("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.endswith`
|
| ilike(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
| Implement the ``ilike`` operator, e.g. case insensitive LIKE.
|
| In a column context, produces an expression either of the form:
|
| .. sourcecode:: sql
|
| lower(a) LIKE lower(other)
|
| Or on backends that support the ILIKE operator:
|
| .. sourcecode:: sql
|
| a ILIKE other
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.ilike("%foobar%"))
|
| :param other: expression to be compared
| :param escape: optional escape character, renders the ``ESCAPE``
| keyword, e.g.::
|
| somecolumn.ilike("foo/%bar", escape="/")
|
| .. seealso::
|
| :meth:`.ColumnOperators.like`
|
| in_(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``in`` operator.
|
| In a column context, produces the clause ``column IN <other>``.
|
| The given parameter ``other`` may be:
|
| * A list of literal values,
| e.g.::
|
| stmt.where(column.in_([1, 2, 3]))
|
| In this calling form, the list of items is converted to a set of
| bound parameters the same length as the list given:
|
| .. sourcecode:: sql
|
| WHERE COL IN (?, ?, ?)
|
| * A list of tuples may be provided if the comparison is against a
| :func:`.tuple_` containing multiple expressions::
|
| from sqlalchemy import tuple_
|
| stmt.where(tuple_(col1, col2).in_([(1, 10), (2, 20), (3, 30)]))
|
| * An empty list,
| e.g.::
|
| stmt.where(column.in_([]))
|
| In this calling form, the expression renders an "empty set"
| expression. These expressions are tailored to individual backends
| and are generally trying to get an empty SELECT statement as a
| subquery. Such as on SQLite, the expression is:
|
| .. sourcecode:: sql
|
| WHERE col IN (SELECT 1 FROM (SELECT 1) WHERE 1!=1)
|
| .. versionchanged:: 1.4 empty IN expressions now use an
| execution-time generated SELECT subquery in all cases.
|
| * A bound parameter, e.g. :func:`.bindparam`, may be used if it
| includes the :paramref:`.bindparam.expanding` flag::
|
| stmt.where(column.in_(bindparam("value", expanding=True)))
|
| In this calling form, the expression renders a special non-SQL
| placeholder expression that looks like:
|
| .. sourcecode:: sql
|
| WHERE COL IN ([EXPANDING_value])
|
| This placeholder expression is intercepted at statement execution
| time to be converted into the variable number of bound parameter
| form illustrated earlier. If the statement were executed as::
|
| connection.execute(stmt, {"value": [1, 2, 3]})
|
| The database would be passed a bound parameter for each value:
|
| .. sourcecode:: sql
|
| WHERE COL IN (?, ?, ?)
|
| .. versionadded:: 1.2 added "expanding" bound parameters
|
| If an empty list is passed, a special "empty list" expression,
| which is specific to the database in use, is rendered. On
| SQLite this would be:
|
| .. sourcecode:: sql
|
| WHERE COL IN (SELECT 1 FROM (SELECT 1) WHERE 1!=1)
|
| .. versionadded:: 1.3 "expanding" bound parameters now support
| empty lists
|
| * a :func:`_expression.select` construct, which is usually a
| correlated scalar select::
|
| stmt.where(
| column.in_(select(othertable.c.y).where(table.c.x == othertable.c.x))
| )
|
| In this calling form, :meth:`.ColumnOperators.in_` renders as given:
|
| .. sourcecode:: sql
|
| WHERE COL IN (SELECT othertable.y
| FROM othertable WHERE othertable.x = table.x)
|
| :param other: a list of literals, a :func:`_expression.select`
| construct, or a :func:`.bindparam` construct that includes the
| :paramref:`.bindparam.expanding` flag set to True.
|
| is_(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``IS`` operator.
|
| Normally, ``IS`` is generated automatically when comparing to a
| value of ``None``, which resolves to ``NULL``. However, explicit
| usage of ``IS`` may be desirable if comparing to boolean values
| on certain platforms.
|
| .. seealso:: :meth:`.ColumnOperators.is_not`
|
| is_distinct_from(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``IS DISTINCT FROM`` operator.
|
| Renders "a IS DISTINCT FROM b" on most platforms;
| on some such as SQLite may render "a IS NOT b".
|
| is_not(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``IS NOT`` operator.
|
| Normally, ``IS NOT`` is generated automatically when comparing to a
| value of ``None``, which resolves to ``NULL``. However, explicit
| usage of ``IS NOT`` may be desirable if comparing to boolean values
| on certain platforms.
|
| .. versionchanged:: 1.4 The ``is_not()`` operator is renamed from
| ``isnot()`` in previous releases. The previous name remains
| available for backwards compatibility.
|
| .. seealso:: :meth:`.ColumnOperators.is_`
|
| is_not_distinct_from(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``IS NOT DISTINCT FROM`` operator.
|
| Renders "a IS NOT DISTINCT FROM b" on most platforms;
| on some such as SQLite may render "a IS b".
|
| .. versionchanged:: 1.4 The ``is_not_distinct_from()`` operator is
| renamed from ``isnot_distinct_from()`` in previous releases.
| The previous name remains available for backwards compatibility.
|
| isnot = is_not(self, other: 'Any') -> 'ColumnOperators'
|
| isnot_distinct_from = is_not_distinct_from(self, other: 'Any') -> 'ColumnOperators'
|
| istartswith(self, other: 'Any', escape: 'Optional[str]' = None, autoescape: 'bool' = False) -> 'ColumnOperators'
| Implement the ``istartswith`` operator, e.g. case insensitive
| version of :meth:`.ColumnOperators.startswith`.
|
| Produces a LIKE expression that tests against an insensitive
| match for the start of a string value:
|
| .. sourcecode:: sql
|
| lower(column) LIKE lower(<other>) || '%'
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.istartswith("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.istartswith.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.istartswith.escape` parameter will
| establish a given character as an escape character which can be of
| use when the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.istartswith.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.istartswith("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE lower(:param) || '%' ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.istartswith("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE lower(:param) || '%' ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.istartswith.autoescape`::
|
| somecolumn.istartswith("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.startswith`
|
| like(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
| Implement the ``like`` operator.
|
| In a column context, produces the expression:
|
| .. sourcecode:: sql
|
| a LIKE other
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.like("%foobar%"))
|
| :param other: expression to be compared
| :param escape: optional escape character, renders the ``ESCAPE``
| keyword, e.g.::
|
| somecolumn.like("foo/%bar", escape="/")
|
| .. seealso::
|
| :meth:`.ColumnOperators.ilike`
|
| match(self, other: 'Any', **kwargs: 'Any') -> 'ColumnOperators'
| Implements a database-specific 'match' operator.
|
| :meth:`_sql.ColumnOperators.match` attempts to resolve to
| a MATCH-like function or operator provided by the backend.
| Examples include:
|
| * PostgreSQL - renders ``x @@ plainto_tsquery(y)``
|
| .. versionchanged:: 2.0 ``plainto_tsquery()`` is used instead
| of ``to_tsquery()`` for PostgreSQL now; for compatibility with
| other forms, see :ref:`postgresql_match`.
|
|
| * MySQL - renders ``MATCH (x) AGAINST (y IN BOOLEAN MODE)``
|
| .. seealso::
|
| :class:`_mysql.match` - MySQL specific construct with
| additional features.
|
| * Oracle Database - renders ``CONTAINS(x, y)``
| * other backends may provide special implementations.
| * Backends without any special implementation will emit
| the operator as "MATCH". This is compatible with SQLite, for
| example.
|
| not_ilike(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
| implement the ``NOT ILIKE`` operator.
|
| This is equivalent to using negation with
| :meth:`.ColumnOperators.ilike`, i.e. ``~x.ilike(y)``.
|
| .. versionchanged:: 1.4 The ``not_ilike()`` operator is renamed from
| ``notilike()`` in previous releases. The previous name remains
| available for backwards compatibility.
|
| .. seealso::
|
| :meth:`.ColumnOperators.ilike`
|
| not_in(self, other: 'Any') -> 'ColumnOperators'
| implement the ``NOT IN`` operator.
|
| This is equivalent to using negation with
| :meth:`.ColumnOperators.in_`, i.e. ``~x.in_(y)``.
|
| In the case that ``other`` is an empty sequence, the compiler
| produces an "empty not in" expression. This defaults to the
| expression "1 = 1" to produce true in all cases. The
| :paramref:`_sa.create_engine.empty_in_strategy` may be used to
| alter this behavior.
|
| .. versionchanged:: 1.4 The ``not_in()`` operator is renamed from
| ``notin_()`` in previous releases. The previous name remains
| available for backwards compatibility.
|
| .. versionchanged:: 1.2 The :meth:`.ColumnOperators.in_` and
| :meth:`.ColumnOperators.not_in` operators
| now produce a "static" expression for an empty IN sequence
| by default.
|
| .. seealso::
|
| :meth:`.ColumnOperators.in_`
|
| not_like(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
| implement the ``NOT LIKE`` operator.
|
| This is equivalent to using negation with
| :meth:`.ColumnOperators.like`, i.e. ``~x.like(y)``.
|
| .. versionchanged:: 1.4 The ``not_like()`` operator is renamed from
| ``notlike()`` in previous releases. The previous name remains
| available for backwards compatibility.
|
| .. seealso::
|
| :meth:`.ColumnOperators.like`
|
| notilike = not_ilike(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
|
| notin_ = not_in(self, other: 'Any') -> 'ColumnOperators'
|
| notlike = not_like(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
|
| nulls_first(self) -> 'ColumnOperators'
| Produce a :func:`_expression.nulls_first` clause against the
| parent object.
|
| .. versionchanged:: 1.4 The ``nulls_first()`` operator is
| renamed from ``nullsfirst()`` in previous releases.
| The previous name remains available for backwards compatibility.
|
| nulls_last(self) -> 'ColumnOperators'
| Produce a :func:`_expression.nulls_last` clause against the
| parent object.
|
| .. versionchanged:: 1.4 The ``nulls_last()`` operator is
| renamed from ``nullslast()`` in previous releases.
| The previous name remains available for backwards compatibility.
|
| nullsfirst = nulls_first(self) -> 'ColumnOperators'
|
| nullslast = nulls_last(self) -> 'ColumnOperators'
|
| regexp_match(self, pattern: 'Any', flags: 'Optional[str]' = None) -> 'ColumnOperators'
| Implements a database-specific 'regexp match' operator.
|
| E.g.::
|
| stmt = select(table.c.some_column).where(
| table.c.some_column.regexp_match("^(b|c)")
| )
|
| :meth:`_sql.ColumnOperators.regexp_match` attempts to resolve to
| a REGEXP-like function or operator provided by the backend, however
| the specific regular expression syntax and flags available are
| **not backend agnostic**.
|
| Examples include:
|
| * PostgreSQL - renders ``x ~ y`` or ``x !~ y`` when negated.
| * Oracle Database - renders ``REGEXP_LIKE(x, y)``
| * SQLite - uses SQLite's ``REGEXP`` placeholder operator and calls into
| the Python ``re.match()`` builtin.
| * other backends may provide special implementations.
| * Backends without any special implementation will emit
| the operator as "REGEXP" or "NOT REGEXP". This is compatible with
| SQLite and MySQL, for example.
|
| Regular expression support is currently implemented for Oracle
| Database, PostgreSQL, MySQL and MariaDB. Partial support is available
| for SQLite. Support among third-party dialects may vary.
|
| :param pattern: The regular expression pattern string or column
| clause.
| :param flags: Any regular expression string flags to apply, passed as
| plain Python string only. These flags are backend specific.
| Some backends, like PostgreSQL and MariaDB, may alternatively
| specify the flags as part of the pattern.
| When using the ignore case flag 'i' in PostgreSQL, the ignore case
| regexp match operator ``~*`` or ``!~*`` will be used.
|
| .. versionadded:: 1.4
|
| .. versionchanged:: 1.4.48, 2.0.18 Note that due to an implementation
| error, the "flags" parameter previously accepted SQL expression
| objects such as column expressions in addition to plain Python
| strings. This implementation did not work correctly with caching
| and was removed; strings only should be passed for the "flags"
| parameter, as these flags are rendered as literal inline values
| within SQL expressions.
|
| .. seealso::
|
| :meth:`_sql.ColumnOperators.regexp_replace`
|
| regexp_replace(self, pattern: 'Any', replacement: 'Any', flags: 'Optional[str]' = None) -> 'ColumnOperators'
| Implements a database-specific 'regexp replace' operator.
|
| E.g.::
|
| stmt = select(
| table.c.some_column.regexp_replace("b(..)", "XY", flags="g")
| )
|
| :meth:`_sql.ColumnOperators.regexp_replace` attempts to resolve to
| a REGEXP_REPLACE-like function provided by the backend, that
| usually emit the function ``REGEXP_REPLACE()``. However,
| the specific regular expression syntax and flags available are
| **not backend agnostic**.
|
| Regular expression replacement support is currently implemented for
| Oracle Database, PostgreSQL, MySQL 8 or greater and MariaDB. Support
| among third-party dialects may vary.
|
| :param pattern: The regular expression pattern string or column
| clause.
| :param pattern: The replacement string or column clause.
| :param flags: Any regular expression string flags to apply, passed as
| plain Python string only. These flags are backend specific.
| Some backends, like PostgreSQL and MariaDB, may alternatively
| specify the flags as part of the pattern.
|
| .. versionadded:: 1.4
|
| .. versionchanged:: 1.4.48, 2.0.18 Note that due to an implementation
| error, the "flags" parameter previously accepted SQL expression
| objects such as column expressions in addition to plain Python
| strings. This implementation did not work correctly with caching
| and was removed; strings only should be passed for the "flags"
| parameter, as these flags are rendered as literal inline values
| within SQL expressions.
|
|
| .. seealso::
|
| :meth:`_sql.ColumnOperators.regexp_match`
|
| startswith(self, other: 'Any', escape: 'Optional[str]' = None, autoescape: 'bool' = False) -> 'ColumnOperators'
| Implement the ``startswith`` operator.
|
| Produces a LIKE expression that tests against a match for the start
| of a string value:
|
| .. sourcecode:: sql
|
| column LIKE <other> || '%'
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.startswith("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.startswith.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.startswith.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.startswith.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.startswith("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE :param || '%' ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.startswith("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE :param || '%' ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.startswith.autoescape`::
|
| somecolumn.startswith("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.endswith`
|
| :meth:`.ColumnOperators.contains`
|
| :meth:`.ColumnOperators.like`
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'timetuple': 'Literal[None]'}
|
| timetuple = None
|
| ----------------------------------------------------------------------
| Methods inherited from Operators:
|
| __and__(self, other: 'Any') -> 'Operators'
| Implement the ``&`` operator.
|
| When used with SQL expressions, results in an
| AND operation, equivalent to
| :func:`_expression.and_`, that is::
|
| a & b
|
| is equivalent to::
|
| from sqlalchemy import and_
|
| and_(a, b)
|
| Care should be taken when using ``&`` regarding
| operator precedence; the ``&`` operator has the highest precedence.
| The operands should be enclosed in parenthesis if they contain
| further sub expressions::
|
| (a == 2) & (b == 4)
|
| __invert__(self) -> 'Operators'
| Implement the ``~`` operator.
|
| When used with SQL expressions, results in a
| NOT operation, equivalent to
| :func:`_expression.not_`, that is::
|
| ~a
|
| is equivalent to::
|
| from sqlalchemy import not_
|
| not_(a)
|
| __or__(self, other: 'Any') -> 'Operators'
| Implement the ``|`` operator.
|
| When used with SQL expressions, results in an
| OR operation, equivalent to
| :func:`_expression.or_`, that is::
|
| a | b
|
| is equivalent to::
|
| from sqlalchemy import or_
|
| or_(a, b)
|
| Care should be taken when using ``|`` regarding
| operator precedence; the ``|`` operator has the highest precedence.
| The operands should be enclosed in parenthesis if they contain
| further sub expressions::
|
| (a == 2) | (b == 4)
|
| __sa_operate__ = operate(self, op: 'OperatorType', *other: 'Any', **kwargs: 'Any') -> 'Operators'
|
| bool_op(self, opstring: 'str', precedence: 'int' = 0, python_impl: 'Optional[Callable[..., Any]]' = None) -> 'Callable[[Any], Operators]'
| Return a custom boolean operator.
|
| This method is shorthand for calling
| :meth:`.Operators.op` and passing the
| :paramref:`.Operators.op.is_comparison`
| flag with True. A key advantage to using :meth:`.Operators.bool_op`
| is that when using column constructs, the "boolean" nature of the
| returned expression will be present for :pep:`484` purposes.
|
| .. seealso::
|
| :meth:`.Operators.op`
|
| op(self, opstring: 'str', precedence: 'int' = 0, is_comparison: 'bool' = False, return_type: 'Optional[Union[Type[TypeEngine[Any]], TypeEngine[Any]]]' = None, python_impl: 'Optional[Callable[..., Any]]' = None) -> 'Callable[[Any], Operators]'
| Produce a generic operator function.
|
| e.g.::
|
| somecolumn.op("*")(5)
|
| produces::
|
| somecolumn * 5
|
| This function can also be used to make bitwise operators explicit. For
| example::
|
| somecolumn.op("&")(0xFF)
|
| is a bitwise AND of the value in ``somecolumn``.
|
| :param opstring: a string which will be output as the infix operator
| between this element and the expression passed to the
| generated function.
|
| :param precedence: precedence which the database is expected to apply
| to the operator in SQL expressions. This integer value acts as a hint
| for the SQL compiler to know when explicit parenthesis should be
| rendered around a particular operation. A lower number will cause the
| expression to be parenthesized when applied against another operator
| with higher precedence. The default value of ``0`` is lower than all
| operators except for the comma (``,``) and ``AS`` operators. A value
| of 100 will be higher or equal to all operators, and -100 will be
| lower than or equal to all operators.
|
| .. seealso::
|
| :ref:`faq_sql_expression_op_parenthesis` - detailed description
| of how the SQLAlchemy SQL compiler renders parenthesis
|
| :param is_comparison: legacy; if True, the operator will be considered
| as a "comparison" operator, that is which evaluates to a boolean
| true/false value, like ``==``, ``>``, etc. This flag is provided
| so that ORM relationships can establish that the operator is a
| comparison operator when used in a custom join condition.
|
| Using the ``is_comparison`` parameter is superseded by using the
| :meth:`.Operators.bool_op` method instead; this more succinct
| operator sets this parameter automatically, but also provides
| correct :pep:`484` typing support as the returned object will
| express a "boolean" datatype, i.e. ``BinaryExpression[bool]``.
|
| :param return_type: a :class:`.TypeEngine` class or object that will
| force the return type of an expression produced by this operator
| to be of that type. By default, operators that specify
| :paramref:`.Operators.op.is_comparison` will resolve to
| :class:`.Boolean`, and those that do not will be of the same
| type as the left-hand operand.
|
| :param python_impl: an optional Python function that can evaluate
| two Python values in the same way as this operator works when
| run on the database server. Useful for in-Python SQL expression
| evaluation functions, such as for ORM hybrid attributes, and the
| ORM "evaluator" used to match objects in a session after a multi-row
| update or delete.
|
| e.g.::
|
| >>> expr = column("x").op("+", python_impl=lambda a, b: a + b)("y")
|
| The operator for the above expression will also work for non-SQL
| left and right objects::
|
| >>> expr.operator(5, 10)
| 15
|
| .. versionadded:: 2.0
|
|
| .. seealso::
|
| :meth:`.Operators.bool_op`
|
| :ref:`types_operators`
|
| :ref:`relationship_custom_operator`
|
| operate(self, op: 'OperatorType', *other: 'Any', **kwargs: 'Any') -> 'Operators'
| Operate on an argument.
|
| This is the lowest level of operation, raises
| :class:`NotImplementedError` by default.
|
| Overriding this on a subclass can allow common
| behavior to be applied to all operations.
| For example, overriding :class:`.ColumnOperators`
| to apply ``func.lower()`` to the left and right
| side::
|
| class MyComparator(ColumnOperators):
| def operate(self, op, other, **kwargs):
| return op(func.lower(self), func.lower(other), **kwargs)
|
| :param op: Operator callable.
| :param \*other: the 'other' side of the operation. Will
| be a single scalar for most operations.
| :param \**kwargs: modifiers. These may be passed by special
| operators such as :meth:`ColumnOperators.contains`.
|
| reverse_operate(self, op: 'OperatorType', other: 'Any', **kwargs: 'Any') -> 'Operators'
| Reverse operate on an argument.
|
| Usage is the same as :meth:`operate`.
sqlalchemy.Compiled
Python Library Documentation: class Compiled in module sqlalchemy.sql.compiler
class Compiled(builtins.object)
| Compiled(dialect: 'Dialect', statement: 'Optional[ClauseElement]', schema_translate_map: 'Optional[SchemaTranslateMapType]' = None, render_schema_translate: 'bool' = False, compile_kwargs: 'Mapping[str, Any]' = immutabledict({}))
|
| Represent a compiled SQL or DDL expression.
|
| The ``__str__`` method of the ``Compiled`` object should produce
| the actual text of the statement. ``Compiled`` objects are
| specific to their underlying database dialect, and also may
| or may not be specific to the columns referenced within a
| particular set of bind parameters. In no case should the
| ``Compiled`` object be dependent on the actual values of those
| bind parameters, even though it may reference those values as
| defaults.
|
| Methods defined here:
|
| __init__(self, dialect: 'Dialect', statement: 'Optional[ClauseElement]', schema_translate_map: 'Optional[SchemaTranslateMapType]' = None, render_schema_translate: 'bool' = False, compile_kwargs: 'Mapping[str, Any]' = immutabledict({}))
| Construct a new :class:`.Compiled` object.
|
| :param dialect: :class:`.Dialect` to compile against.
|
| :param statement: :class:`_expression.ClauseElement` to be compiled.
|
| :param schema_translate_map: dictionary of schema names to be
| translated when forming the resultant SQL
|
| .. seealso::
|
| :ref:`schema_translating`
|
| :param compile_kwargs: additional kwargs that will be
| passed to the initial call to :meth:`.Compiled.process`.
|
| __str__(self) -> 'str'
| Return the string text of the generated SQL or DDL.
|
| construct_params(self, params: 'Optional[_CoreSingleExecuteParams]' = None, extracted_parameters: 'Optional[Sequence[BindParameter[Any]]]' = None, escape_names: 'bool' = True) -> 'Optional[_MutableCoreSingleExecuteParams]'
| Return the bind params for this compiled object.
|
| :param params: a dict of string/object pairs whose values will
| override bind values compiled in to the
| statement.
|
| process(self, obj: 'Visitable', **kwargs: 'Any') -> 'str'
|
| visit_unsupported_compilation(self, element, err, **kw)
|
| ----------------------------------------------------------------------
| Class methods defined here:
|
| __init_subclass__() -> 'None'
| This method is called when a class is subclassed.
|
| The default implementation does nothing. It may be
| overridden to extend subclasses.
|
| ----------------------------------------------------------------------
| Readonly properties defined here:
|
| params
| Return the bind params for this compiled object.
|
| sql_compiler
| Return a Compiled that is capable of processing SQL expressions.
|
| If this compiler is one, it would likely just return 'self'.
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'_annotations': '_AnnotationDict', '_cached_metadat...
|
| cache_key = None
|
| compile_state = None
|
| dml_compile_state = None
|
| execution_options = immutabledict({})
|
| is_ddl = False
|
| is_sql = False
|
| schema_translate_map = None
|
| statement = None
|
| string = ''
sqlalchemy.CompoundSelect
Python Library Documentation: class CompoundSelect in module sqlalchemy.sql.selectable
class CompoundSelect(sqlalchemy.sql.base.HasCompileState, GenerativeSelect, TypedReturnsRows)
| CompoundSelect(keyword: '_CompoundSelectKeyword', *selects: '_SelectStatementForCompoundArgument[_TP]')
|
| Forms the basis of ``UNION``, ``UNION ALL``, and other
| SELECT-based set operations.
|
|
| .. seealso::
|
| :func:`_expression.union`
|
| :func:`_expression.union_all`
|
| :func:`_expression.intersect`
|
| :func:`_expression.intersect_all`
|
| :func:`_expression.except`
|
| :func:`_expression.except_all`
|
| Method resolution order:
| CompoundSelect
| sqlalchemy.sql.base.HasCompileState
| GenerativeSelect
| sqlalchemy.sql.base.DialectKWArgs
| SelectBase
| sqlalchemy.sql.roles.SelectStatementRole
| TypedReturnsRows
| ExecutableReturnsRows
| sqlalchemy.sql.base.Executable
| sqlalchemy.sql.roles.StatementRole
| sqlalchemy.sql.roles.DMLSelectRole
| sqlalchemy.sql.roles.CompoundElementRole
| sqlalchemy.sql.roles.AllowsLambdaRole
| sqlalchemy.sql.roles.InElementRole
| HasCTE
| sqlalchemy.sql.roles.HasCTERole
| SelectsRows
| sqlalchemy.sql.annotation.SupportsCloneAnnotations
| Selectable
| ReturnsRows
| sqlalchemy.sql.roles.ReturnsRowsRole
| sqlalchemy.sql.roles.SQLRole
| sqlalchemy.sql.elements.DQLDMLClauseElement
| sqlalchemy.sql.elements.ClauseElement
| sqlalchemy.sql.annotation.SupportsWrappingAnnotations
| sqlalchemy.sql.annotation.SupportsAnnotations
| sqlalchemy.sql.cache_key.MemoizedHasCacheKey
| sqlalchemy.sql.cache_key.HasCacheKey
| sqlalchemy.sql.base.Generative
| sqlalchemy.util.langhelpers.HasMemoized
| sqlalchemy.sql.traversals.HasCopyInternals
| sqlalchemy.sql.visitors.ExternallyTraversible
| sqlalchemy.sql.visitors.HasTraverseInternals
| sqlalchemy.sql.elements.CompilerElement
| sqlalchemy.sql.visitors.Visitable
| typing.Generic
| builtins.object
|
| Methods defined here:
|
| __init__(self, keyword: '_CompoundSelectKeyword', *selects: '_SelectStatementForCompoundArgument[_TP]')
| Initialize self. See help(type(self)) for accurate signature.
|
| 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.
|
| selected_columns(...)
| A :class:`_expression.ColumnCollection`
| representing the columns that
| this SELECT statement or similar construct returns in its result set,
| not including :class:`_sql.TextClause` constructs.
|
| For a :class:`_expression.CompoundSelect`, the
| :attr:`_expression.CompoundSelect.selected_columns`
| attribute returns the selected
| columns of the first SELECT statement contained within the series of
| statements within the set operation.
|
| .. seealso::
|
| :attr:`_sql.Select.selected_columns`
|
| .. versionadded:: 1.4
|
| self_group(self, against: 'Optional[OperatorType]' = None) -> 'GroupedElement'
| 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.
|
| set_label_style(self, style: 'SelectLabelStyle') -> 'Self'
| Return a new selectable with the specified label style.
|
| There are three "label styles" available,
| :attr:`_sql.SelectLabelStyle.LABEL_STYLE_DISAMBIGUATE_ONLY`,
| :attr:`_sql.SelectLabelStyle.LABEL_STYLE_TABLENAME_PLUS_COL`, and
| :attr:`_sql.SelectLabelStyle.LABEL_STYLE_NONE`. The default style is
| :attr:`_sql.SelectLabelStyle.LABEL_STYLE_DISAMBIGUATE_ONLY`.
|
| In modern SQLAlchemy, there is not generally a need to change the
| labeling style, as per-expression labels are more effectively used by
| making use of the :meth:`_sql.ColumnElement.label` method. In past
| versions, :data:`_sql.LABEL_STYLE_TABLENAME_PLUS_COL` was used to
| disambiguate same-named columns from different tables, aliases, or
| subqueries; the newer :data:`_sql.LABEL_STYLE_DISAMBIGUATE_ONLY` now
| applies labels only to names that conflict with an existing name so
| that the impact of this labeling is minimal.
|
| The rationale for disambiguation is mostly so that all column
| expressions are available from a given :attr:`_sql.FromClause.c`
| collection when a subquery is created.
|
| .. versionadded:: 1.4 - the
| :meth:`_sql.GenerativeSelect.set_label_style` method replaces the
| previous combination of ``.apply_labels()``, ``.with_labels()`` and
| ``use_labels=True`` methods and/or parameters.
|
| .. seealso::
|
| :data:`_sql.LABEL_STYLE_DISAMBIGUATE_ONLY`
|
| :data:`_sql.LABEL_STYLE_TABLENAME_PLUS_COL`
|
| :data:`_sql.LABEL_STYLE_NONE`
|
| :data:`_sql.LABEL_STYLE_DEFAULT`
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| EXCEPT = <_CompoundSelectKeyword.EXCEPT: 'EXCEPT'>
|
| EXCEPT_ALL = <_CompoundSelectKeyword.EXCEPT_ALL: 'EXCEPT ALL'>
|
| INTERSECT = <_CompoundSelectKeyword.INTERSECT: 'INTERSECT'>
|
| INTERSECT_ALL = <_CompoundSelectKeyword.INTERSECT_ALL: 'INTERSECT ALL'...
|
| UNION = <_CompoundSelectKeyword.UNION: 'UNION'>
|
| UNION_ALL = <_CompoundSelectKeyword.UNION_ALL: 'UNION ALL'>
|
| __annotations__ = {'_traverse_internals': '_TraverseInternalsType', 's...
|
| __parameters__ = ()
|
| __visit_name__ = 'compound_select'
|
| ----------------------------------------------------------------------
| Methods inherited from GenerativeSelect:
|
| fetch(self, count: '_LimitOffsetType', with_ties: 'bool' = False, percent: 'bool' = False, **dialect_kw: 'Any') -> 'Self'
| Return a new selectable with the given FETCH FIRST criterion
| applied.
|
| This is a numeric value which usually renders as ``FETCH {FIRST | NEXT}
| [ count ] {ROW | ROWS} {ONLY | WITH TIES}`` expression in the resulting
| select. This functionality is is currently implemented for Oracle
| Database, PostgreSQL, MSSQL.
|
| Use :meth:`_sql.GenerativeSelect.offset` to specify the offset.
|
| .. note::
|
| The :meth:`_sql.GenerativeSelect.fetch` method will replace
| any clause applied with :meth:`_sql.GenerativeSelect.limit`.
|
| .. versionadded:: 1.4
|
| :param count: an integer COUNT parameter, or a SQL expression
| that provides an integer result. When ``percent=True`` this will
| represent the percentage of rows to return, not the absolute value.
| Pass ``None`` to reset it.
|
| :param with_ties: When ``True``, the WITH TIES option is used
| to return any additional rows that tie for the last place in the
| result set according to the ``ORDER BY`` clause. The
| ``ORDER BY`` may be mandatory in this case. Defaults to ``False``
|
| :param percent: When ``True``, ``count`` represents the percentage
| of the total number of selected rows to return. Defaults to ``False``
|
| :param \**dialect_kw: Additional dialect-specific keyword arguments
| may be accepted by dialects.
|
| .. versionadded:: 2.0.41
|
| .. seealso::
|
| :meth:`_sql.GenerativeSelect.limit`
|
| :meth:`_sql.GenerativeSelect.offset`
|
| get_label_style(self) -> 'SelectLabelStyle'
| Retrieve the current label style.
|
| .. versionadded:: 1.4
|
| group_by(self, _GenerativeSelect__first: 'Union[Literal[None, _NoArg.NO_ARG], _ColumnExpressionOrStrLabelArgument[Any]]' = _NoArg.NO_ARG, *clauses: '_ColumnExpressionOrStrLabelArgument[Any]') -> 'Self'
| Return a new selectable with the given list of GROUP BY
| criterion applied.
|
| All existing GROUP BY settings can be suppressed by passing ``None``.
|
| e.g.::
|
| stmt = select(table.c.name, func.max(table.c.stat)).group_by(table.c.name)
|
| :param \*clauses: a series of :class:`_expression.ColumnElement`
| constructs which will be used to generate an GROUP BY clause.
|
| Alternatively, an individual entry may also be the string name of a
| label located elsewhere in the columns clause of the statement which
| will be matched and rendered in a backend-specific way based on
| context; see :ref:`tutorial_order_by_label` for background on string
| label matching in ORDER BY and GROUP BY expressions.
|
| .. seealso::
|
| :ref:`tutorial_group_by_w_aggregates` - in the
| :ref:`unified_tutorial`
|
| :ref:`tutorial_order_by_label` - in the :ref:`unified_tutorial`
|
| limit(self, limit: '_LimitOffsetType') -> 'Self'
| Return a new selectable with the given LIMIT criterion
| applied.
|
| This is a numerical value which usually renders as a ``LIMIT``
| expression in the resulting select. Backends that don't
| support ``LIMIT`` will attempt to provide similar
| functionality.
|
| .. note::
|
| The :meth:`_sql.GenerativeSelect.limit` method will replace
| any clause applied with :meth:`_sql.GenerativeSelect.fetch`.
|
| :param limit: an integer LIMIT parameter, or a SQL expression
| that provides an integer result. Pass ``None`` to reset it.
|
| .. seealso::
|
| :meth:`_sql.GenerativeSelect.fetch`
|
| :meth:`_sql.GenerativeSelect.offset`
|
| offset(self, offset: '_LimitOffsetType') -> 'Self'
| Return a new selectable with the given OFFSET criterion
| applied.
|
|
| This is a numeric value which usually renders as an ``OFFSET``
| expression in the resulting select. Backends that don't
| support ``OFFSET`` will attempt to provide similar
| functionality.
|
| :param offset: an integer OFFSET parameter, or a SQL expression
| that provides an integer result. Pass ``None`` to reset it.
|
| .. seealso::
|
| :meth:`_sql.GenerativeSelect.limit`
|
| :meth:`_sql.GenerativeSelect.fetch`
|
| order_by(self, _GenerativeSelect__first: 'Union[Literal[None, _NoArg.NO_ARG], _ColumnExpressionOrStrLabelArgument[Any]]' = _NoArg.NO_ARG, *clauses: '_ColumnExpressionOrStrLabelArgument[Any]') -> 'Self'
| Return a new selectable with the given list of ORDER BY
| criteria applied.
|
| e.g.::
|
| stmt = select(table).order_by(table.c.id, table.c.name)
|
| Calling this method multiple times is equivalent to calling it once
| with all the clauses concatenated. All existing ORDER BY criteria may
| be cancelled by passing ``None`` by itself. New ORDER BY criteria may
| then be added by invoking :meth:`_orm.Query.order_by` again, e.g.::
|
| # will erase all ORDER BY and ORDER BY new_col alone
| stmt = stmt.order_by(None).order_by(new_col)
|
| :param \*clauses: a series of :class:`_expression.ColumnElement`
| constructs which will be used to generate an ORDER BY clause.
|
| Alternatively, an individual entry may also be the string name of a
| label located elsewhere in the columns clause of the statement which
| will be matched and rendered in a backend-specific way based on
| context; see :ref:`tutorial_order_by_label` for background on string
| label matching in ORDER BY and GROUP BY expressions.
|
| .. seealso::
|
| :ref:`tutorial_order_by` - in the :ref:`unified_tutorial`
|
| :ref:`tutorial_order_by_label` - in the :ref:`unified_tutorial`
|
| slice(self, start: 'int', stop: 'int') -> 'Self'
| Apply LIMIT / OFFSET to this statement based on a slice.
|
| The start and stop indices behave like the argument to Python's
| built-in :func:`range` function. This method provides an
| alternative to using ``LIMIT``/``OFFSET`` to get a slice of the
| query.
|
| For example, ::
|
| stmt = select(User).order_by(User.id).slice(1, 3)
|
| renders as
|
| .. sourcecode:: sql
|
| SELECT users.id AS users_id,
| users.name AS users_name
| FROM users ORDER BY users.id
| LIMIT ? OFFSET ?
| (2, 1)
|
| .. note::
|
| The :meth:`_sql.GenerativeSelect.slice` method will replace
| any clause applied with :meth:`_sql.GenerativeSelect.fetch`.
|
| .. versionadded:: 1.4 Added the :meth:`_sql.GenerativeSelect.slice`
| method generalized from the ORM.
|
| .. seealso::
|
| :meth:`_sql.GenerativeSelect.limit`
|
| :meth:`_sql.GenerativeSelect.offset`
|
| :meth:`_sql.GenerativeSelect.fetch`
|
| with_for_update(self, *, nowait: 'bool' = False, read: 'bool' = False, of: 'Optional[_ForUpdateOfArgument]' = None, skip_locked: 'bool' = False, key_share: 'bool' = False) -> 'Self'
| Specify a ``FOR UPDATE`` clause for this
| :class:`_expression.GenerativeSelect`.
|
| E.g.::
|
| stmt = select(table).with_for_update(nowait=True)
|
| On a database like PostgreSQL or Oracle Database, the above would
| render a statement like:
|
| .. sourcecode:: sql
|
| SELECT table.a, table.b FROM table FOR UPDATE NOWAIT
|
| on other backends, the ``nowait`` option is ignored and instead
| would produce:
|
| .. sourcecode:: sql
|
| SELECT table.a, table.b FROM table FOR UPDATE
|
| When called with no arguments, the statement will render with
| the suffix ``FOR UPDATE``. Additional arguments can then be
| provided which allow for common database-specific
| variants.
|
| :param nowait: boolean; will render ``FOR UPDATE NOWAIT`` on Oracle
| Database and PostgreSQL dialects.
|
| :param read: boolean; will render ``LOCK IN SHARE MODE`` on MySQL,
| ``FOR SHARE`` on PostgreSQL. On PostgreSQL, when combined with
| ``nowait``, will render ``FOR SHARE NOWAIT``.
|
| :param of: SQL expression or list of SQL expression elements,
| (typically :class:`_schema.Column` objects or a compatible expression,
| for some backends may also be a table expression) which will render
| into a ``FOR UPDATE OF`` clause; supported by PostgreSQL, Oracle
| Database, some MySQL versions and possibly others. May render as a
| table or as a column depending on backend.
|
| :param skip_locked: boolean, will render ``FOR UPDATE SKIP LOCKED`` on
| Oracle Database and PostgreSQL dialects or ``FOR SHARE SKIP LOCKED``
| if ``read=True`` is also specified.
|
| :param key_share: boolean, will render ``FOR NO KEY UPDATE``,
| or if combined with ``read=True`` will render ``FOR KEY SHARE``,
| on the PostgreSQL dialect.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from GenerativeSelect:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.base.DialectKWArgs:
|
| dialect_options(...)
| A collection of keyword arguments specified as dialect-specific
| options to this construct.
|
| This is a two-level nested registry, keyed to ``<dialect_name>``
| and ``<argument_name>``. For example, the ``postgresql_where``
| argument would be locatable as::
|
| arg = my_object.dialect_options["postgresql"]["where"]
|
| .. versionadded:: 0.9.2
|
| .. seealso::
|
| :attr:`.DialectKWArgs.dialect_kwargs` - flat dictionary form
|
| get_dialect_option(self, dialect: 'Dialect', argument_name: 'str', *, else_: 'Any' = None, deprecated_fallback: 'Optional[str]' = None) -> 'Any'
| Return the value of a dialect-specific option, or *else_* if
| this dialect does not register the given argument.
|
| This is useful for DDL compilers that may be inherited by
| third-party dialects whose ``construct_arguments`` do not
| include the same set of keys as the parent dialect.
|
| :param dialect: The dialect for which to retrieve the option.
| :param argument_name: The name of the argument to retrieve.
| :param else\_: The value to return if the argument is not present.
| :param deprecated_fallback: Optional dialect name to fall back to
| if the argument is not present for the current dialect. If the
| argument is present for the fallback dialect but not the current
| dialect, a deprecation warning will be emitted.
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.base.DialectKWArgs:
|
| argument_for(dialect_name: 'str', argument_name: 'str', default: 'Any') -> 'None'
| Add a new kind of dialect-specific keyword argument for this class.
|
| E.g.::
|
| Index.argument_for("mydialect", "length", None)
|
| some_index = Index("a", "b", mydialect_length=5)
|
| The :meth:`.DialectKWArgs.argument_for` method is a per-argument
| way adding extra arguments to the
| :attr:`.DefaultDialect.construct_arguments` dictionary. This
| dictionary provides a list of argument names accepted by various
| schema-level constructs on behalf of a dialect.
|
| New dialects should typically specify this dictionary all at once as a
| data member of the dialect class. The use case for ad-hoc addition of
| argument names is typically for end-user code that is also using
| a custom compilation scheme which consumes the additional arguments.
|
| :param dialect_name: name of a dialect. The dialect must be
| locatable, else a :class:`.NoSuchModuleError` is raised. The
| dialect must also include an existing
| :attr:`.DefaultDialect.construct_arguments` collection, indicating
| that it participates in the keyword-argument validation and default
| system, else :class:`.ArgumentError` is raised. If the dialect does
| not include this collection, then any keyword argument can be
| specified on behalf of this dialect already. All dialects packaged
| within SQLAlchemy include this collection, however for third party
| dialects, support may vary.
|
| :param argument_name: name of the parameter.
|
| :param default: default value of the parameter.
|
| ----------------------------------------------------------------------
| Readonly properties inherited from sqlalchemy.sql.base.DialectKWArgs:
|
| dialect_kwargs
| A collection of keyword arguments specified as dialect-specific
| options to this construct.
|
| The arguments are present here in their original ``<dialect>_<kwarg>``
| format. Only arguments that were actually passed are included;
| unlike the :attr:`.DialectKWArgs.dialect_options` collection, which
| contains all options known by this dialect including defaults.
|
| The collection is also writable; keys are accepted of the
| form ``<dialect>_<kwarg>`` where the value will be assembled
| into the list of options.
|
| .. seealso::
|
| :attr:`.DialectKWArgs.dialect_options` - nested dictionary form
|
| kwargs
| A synonym for :attr:`.DialectKWArgs.dialect_kwargs`.
|
| ----------------------------------------------------------------------
| Methods inherited from SelectBase:
|
| alias(self, name: 'Optional[str]' = None, flat: 'bool' = False) -> 'Subquery'
| 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.
|
| as_scalar(self) -> 'ScalarSelect[Any]'
| .. 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`.
|
| exists(self) -> 'Exists'
| 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
|
| label(self, name: 'Optional[str]') -> 'Label[Any]'
| Return a 'scalar' representation of this selectable, embedded as a
| subquery with a label.
|
| .. seealso::
|
| :meth:`_expression.SelectBase.scalar_subquery`.
|
| 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.
|
| scalar_subquery(self) -> 'ScalarSelect[Any]'
| 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
|
| select(self, *arg: 'Any', **kw: 'Any') -> 'Select[Any]'
| .. 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.
|
| subquery(self, name: 'Optional[str]' = None) -> '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:
|
| .. sourcecode:: sql
|
| 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:
|
| .. sourcecode:: sql
|
| 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
|
| ----------------------------------------------------------------------
| Readonly properties inherited from SelectBase:
|
| c
| .. 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.
|
| columns
|
| 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`
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from SelectBase:
|
| is_select = True
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from TypedReturnsRows:
|
| __orig_bases__ = (<class 'sqlalchemy.sql.selectable.ExecutableReturnsR...
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.base.Executable:
|
| execution_options(self, **kw: 'Any') -> 'Self'
| Set non-SQL options for the statement which take effect during
| execution.
|
| Execution options can be set at many scopes, including per-statement,
| per-connection, or per execution, using methods such as
| :meth:`_engine.Connection.execution_options` and parameters which
| accept a dictionary of options such as
| :paramref:`_engine.Connection.execute.execution_options` and
| :paramref:`_orm.Session.execute.execution_options`.
|
| The primary characteristic of an execution option, as opposed to
| other kinds of options such as ORM loader options, is that
| **execution options never affect the compiled SQL of a query, only
| things that affect how the SQL statement itself is invoked or how
| results are fetched**. That is, execution options are not part of
| what's accommodated by SQL compilation nor are they considered part of
| the cached state of a statement.
|
| The :meth:`_sql.Executable.execution_options` method is
| :term:`generative`, as
| is the case for the method as applied to the :class:`_engine.Engine`
| and :class:`_orm.Query` objects, which means when the method is called,
| a copy of the object is returned, which applies the given parameters to
| that new copy, but leaves the original unchanged::
|
| statement = select(table.c.x, table.c.y)
| new_statement = statement.execution_options(my_option=True)
|
| An exception to this behavior is the :class:`_engine.Connection`
| object, where the :meth:`_engine.Connection.execution_options` method
| is explicitly **not** generative.
|
| The kinds of options that may be passed to
| :meth:`_sql.Executable.execution_options` and other related methods and
| parameter dictionaries include parameters that are explicitly consumed
| by SQLAlchemy Core or ORM, as well as arbitrary keyword arguments not
| defined by SQLAlchemy, which means the methods and/or parameter
| dictionaries may be used for user-defined parameters that interact with
| custom code, which may access the parameters using methods such as
| :meth:`_sql.Executable.get_execution_options` and
| :meth:`_engine.Connection.get_execution_options`, or within selected
| event hooks using a dedicated ``execution_options`` event parameter
| such as
| :paramref:`_events.ConnectionEvents.before_execute.execution_options`
| or :attr:`_orm.ORMExecuteState.execution_options`, e.g.::
|
| from sqlalchemy import event
|
|
| @event.listens_for(some_engine, "before_execute")
| def _process_opt(conn, statement, multiparams, params, execution_options):
| "run a SQL function before invoking a statement"
|
| if execution_options.get("do_special_thing", False):
| conn.exec_driver_sql("run_special_function()")
|
| Within the scope of options that are explicitly recognized by
| SQLAlchemy, most apply to specific classes of objects and not others.
| The most common execution options include:
|
| * :paramref:`_engine.Connection.execution_options.isolation_level` -
| sets the isolation level for a connection or a class of connections
| via an :class:`_engine.Engine`. This option is accepted only
| by :class:`_engine.Connection` or :class:`_engine.Engine`.
|
| * :paramref:`_engine.Connection.execution_options.stream_results` -
| indicates results should be fetched using a server side cursor;
| this option is accepted by :class:`_engine.Connection`, by the
| :paramref:`_engine.Connection.execute.execution_options` parameter
| on :meth:`_engine.Connection.execute`, and additionally by
| :meth:`_sql.Executable.execution_options` on a SQL statement object,
| as well as by ORM constructs like :meth:`_orm.Session.execute`.
|
| * :paramref:`_engine.Connection.execution_options.compiled_cache` -
| indicates a dictionary that will serve as the
| :ref:`SQL compilation cache <sql_caching>`
| for a :class:`_engine.Connection` or :class:`_engine.Engine`, as
| well as for ORM methods like :meth:`_orm.Session.execute`.
| Can be passed as ``None`` to disable caching for statements.
| This option is not accepted by
| :meth:`_sql.Executable.execution_options` as it is inadvisable to
| carry along a compilation cache within a statement object.
|
| * :paramref:`_engine.Connection.execution_options.schema_translate_map`
| - a mapping of schema names used by the
| :ref:`Schema Translate Map <schema_translating>` feature, accepted
| by :class:`_engine.Connection`, :class:`_engine.Engine`,
| :class:`_sql.Executable`, as well as by ORM constructs
| like :meth:`_orm.Session.execute`.
|
| .. seealso::
|
| :meth:`_engine.Connection.execution_options`
|
| :paramref:`_engine.Connection.execute.execution_options`
|
| :paramref:`_orm.Session.execute.execution_options`
|
| :ref:`orm_queryguide_execution_options` - documentation on all
| ORM-specific execution options
|
| get_execution_options(self) -> '_ExecuteOptions'
| Get the non-SQL options which will take effect during execution.
|
| .. versionadded:: 1.3
|
| .. seealso::
|
| :meth:`.Executable.execution_options`
|
| options(self, *options: 'ExecutableOption') -> 'Self'
| Apply options to this statement.
|
| In the general sense, options are any kind of Python object
| that can be interpreted by the SQL compiler for the statement.
| These options can be consumed by specific dialects or specific kinds
| of compilers.
|
| The most commonly known kind of option are the ORM level options
| that apply "eager load" and other loading behaviors to an ORM
| query. However, options can theoretically be used for many other
| purposes.
|
| For background on specific kinds of options for specific kinds of
| statements, refer to the documentation for those option objects.
|
| .. versionchanged:: 1.4 - added :meth:`.Executable.options` to
| Core statement objects towards the goal of allowing unified
| Core / ORM querying capabilities.
|
| .. seealso::
|
| :ref:`loading_columns` - refers to options specific to the usage
| of ORM queries
|
| :ref:`relationship_loader_options` - refers to options specific
| to the usage of ORM queries
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.base.Executable:
|
| is_delete = False
|
| is_dml = False
|
| is_from_statement = False
|
| is_insert = False
|
| is_text = False
|
| is_update = False
|
| supports_execution = True
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.AllowsLambdaRole:
|
| allows_lambda = True
|
| ----------------------------------------------------------------------
| Methods inherited from HasCTE:
|
| add_cte(self, *ctes: 'CTE', nest_here: 'bool' = False) -> 'Self'
| Add one or more :class:`_sql.CTE` constructs to this statement.
|
| This method will associate the given :class:`_sql.CTE` constructs with
| the parent statement such that they will each be unconditionally
| rendered in the WITH clause of the final statement, even if not
| referenced elsewhere within the statement or any sub-selects.
|
| The optional :paramref:`.HasCTE.add_cte.nest_here` parameter when set
| to True will have the effect that each given :class:`_sql.CTE` will
| render in a WITH clause rendered directly along with this statement,
| rather than being moved to the top of the ultimate rendered statement,
| even if this statement is rendered as a subquery within a larger
| statement.
|
| This method has two general uses. One is to embed CTE statements that
| serve some purpose without being referenced explicitly, such as the use
| case of embedding a DML statement such as an INSERT or UPDATE as a CTE
| inline with a primary statement that may draw from its results
| indirectly. The other is to provide control over the exact placement
| of a particular series of CTE constructs that should remain rendered
| directly in terms of a particular statement that may be nested in a
| larger statement.
|
| E.g.::
|
| from sqlalchemy import table, column, select
|
| t = table("t", column("c1"), column("c2"))
|
| ins = t.insert().values({"c1": "x", "c2": "y"}).cte()
|
| stmt = select(t).add_cte(ins)
|
| Would render:
|
| .. sourcecode:: sql
|
| WITH anon_1 AS (
| INSERT INTO t (c1, c2) VALUES (:param_1, :param_2)
| )
| SELECT t.c1, t.c2
| FROM t
|
| Above, the "anon_1" CTE is not referenced in the SELECT
| statement, however still accomplishes the task of running an INSERT
| statement.
|
| Similarly in a DML-related context, using the PostgreSQL
| :class:`_postgresql.Insert` construct to generate an "upsert"::
|
| from sqlalchemy import table, column
| from sqlalchemy.dialects.postgresql import insert
|
| t = table("t", column("c1"), column("c2"))
|
| delete_statement_cte = t.delete().where(t.c.c1 < 1).cte("deletions")
|
| insert_stmt = insert(t).values({"c1": 1, "c2": 2})
| update_statement = insert_stmt.on_conflict_do_update(
| index_elements=[t.c.c1],
| set_={
| "c1": insert_stmt.excluded.c1,
| "c2": insert_stmt.excluded.c2,
| },
| ).add_cte(delete_statement_cte)
|
| print(update_statement)
|
| The above statement renders as:
|
| .. sourcecode:: sql
|
| WITH deletions AS (
| DELETE FROM t WHERE t.c1 < %(c1_1)s
| )
| INSERT INTO t (c1, c2) VALUES (%(c1)s, %(c2)s)
| ON CONFLICT (c1) DO UPDATE SET c1 = excluded.c1, c2 = excluded.c2
|
| .. versionadded:: 1.4.21
|
| :param \*ctes: zero or more :class:`.CTE` constructs.
|
| .. versionchanged:: 2.0 Multiple CTE instances are accepted
|
| :param nest_here: if True, the given CTE or CTEs will be rendered
| as though they specified the :paramref:`.HasCTE.cte.nesting` flag
| to ``True`` when they were added to this :class:`.HasCTE`.
| Assuming the given CTEs are not referenced in an outer-enclosing
| statement as well, the CTEs given should render at the level of
| this statement when this flag is given.
|
| .. versionadded:: 2.0
|
| .. seealso::
|
| :paramref:`.HasCTE.cte.nesting`
|
| cte(self, name: 'Optional[str]' = None, recursive: 'bool' = False, nesting: 'bool' = False) -> 'CTE'
| Return a new :class:`_expression.CTE`,
| or Common Table Expression instance.
|
| Common table expressions are a SQL standard whereby SELECT
| statements can draw upon secondary statements specified along
| with the primary statement, using a clause called "WITH".
| Special semantics regarding UNION can also be employed to
| allow "recursive" queries, where a SELECT statement can draw
| upon the set of rows that have previously been selected.
|
| CTEs can also be applied to DML constructs UPDATE, INSERT
| and DELETE on some databases, both as a source of CTE rows
| when combined with RETURNING, as well as a consumer of
| CTE rows.
|
| SQLAlchemy detects :class:`_expression.CTE` objects, which are treated
| similarly to :class:`_expression.Alias` objects, as special elements
| to be delivered to the FROM clause of the statement as well
| as to a WITH clause at the top of the statement.
|
| For special prefixes such as PostgreSQL "MATERIALIZED" and
| "NOT MATERIALIZED", the :meth:`_expression.CTE.prefix_with`
| method may be
| used to establish these.
|
| .. versionchanged:: 1.3.13 Added support for prefixes.
| In particular - MATERIALIZED and NOT MATERIALIZED.
|
| :param name: name given to the common table expression. Like
| :meth:`_expression.FromClause.alias`, the name can be left as
| ``None`` in which case an anonymous symbol will be used at query
| compile time.
| :param recursive: if ``True``, will render ``WITH RECURSIVE``.
| A recursive common table expression is intended to be used in
| conjunction with UNION ALL in order to derive rows
| from those already selected.
| :param nesting: if ``True``, will render the CTE locally to the
| statement in which it is referenced. For more complex scenarios,
| the :meth:`.HasCTE.add_cte` method using the
| :paramref:`.HasCTE.add_cte.nest_here`
| parameter may also be used to more carefully
| control the exact placement of a particular CTE.
|
| .. versionadded:: 1.4.24
|
| .. seealso::
|
| :meth:`.HasCTE.add_cte`
|
| The following examples include two from PostgreSQL's documentation at
| https://www.postgresql.org/docs/current/static/queries-with.html,
| as well as additional examples.
|
| Example 1, non recursive::
|
| from sqlalchemy import (
| Table,
| Column,
| String,
| Integer,
| MetaData,
| select,
| func,
| )
|
| metadata = MetaData()
|
| orders = Table(
| "orders",
| metadata,
| Column("region", String),
| Column("amount", Integer),
| Column("product", String),
| Column("quantity", Integer),
| )
|
| regional_sales = (
| select(orders.c.region, func.sum(orders.c.amount).label("total_sales"))
| .group_by(orders.c.region)
| .cte("regional_sales")
| )
|
|
| top_regions = (
| select(regional_sales.c.region)
| .where(
| regional_sales.c.total_sales
| > select(func.sum(regional_sales.c.total_sales) / 10)
| )
| .cte("top_regions")
| )
|
| statement = (
| select(
| orders.c.region,
| orders.c.product,
| func.sum(orders.c.quantity).label("product_units"),
| func.sum(orders.c.amount).label("product_sales"),
| )
| .where(orders.c.region.in_(select(top_regions.c.region)))
| .group_by(orders.c.region, orders.c.product)
| )
|
| result = conn.execute(statement).fetchall()
|
| Example 2, WITH RECURSIVE::
|
| from sqlalchemy import (
| Table,
| Column,
| String,
| Integer,
| MetaData,
| select,
| func,
| )
|
| metadata = MetaData()
|
| parts = Table(
| "parts",
| metadata,
| Column("part", String),
| Column("sub_part", String),
| Column("quantity", Integer),
| )
|
| included_parts = (
| select(parts.c.sub_part, parts.c.part, parts.c.quantity)
| .where(parts.c.part == "our part")
| .cte(recursive=True)
| )
|
|
| incl_alias = included_parts.alias()
| parts_alias = parts.alias()
| included_parts = included_parts.union_all(
| select(
| parts_alias.c.sub_part, parts_alias.c.part, parts_alias.c.quantity
| ).where(parts_alias.c.part == incl_alias.c.sub_part)
| )
|
| statement = select(
| included_parts.c.sub_part,
| func.sum(included_parts.c.quantity).label("total_quantity"),
| ).group_by(included_parts.c.sub_part)
|
| result = conn.execute(statement).fetchall()
|
| Example 3, an upsert using UPDATE and INSERT with CTEs::
|
| from datetime import date
| from sqlalchemy import (
| MetaData,
| Table,
| Column,
| Integer,
| Date,
| select,
| literal,
| and_,
| exists,
| )
|
| metadata = MetaData()
|
| visitors = Table(
| "visitors",
| metadata,
| Column("product_id", Integer, primary_key=True),
| Column("date", Date, primary_key=True),
| Column("count", Integer),
| )
|
| # add 5 visitors for the product_id == 1
| product_id = 1
| day = date.today()
| count = 5
|
| update_cte = (
| visitors.update()
| .where(
| and_(visitors.c.product_id == product_id, visitors.c.date == day)
| )
| .values(count=visitors.c.count + count)
| .returning(literal(1))
| .cte("update_cte")
| )
|
| upsert = visitors.insert().from_select(
| [visitors.c.product_id, visitors.c.date, visitors.c.count],
| select(literal(product_id), literal(day), literal(count)).where(
| ~exists(update_cte.select())
| ),
| )
|
| connection.execute(upsert)
|
| Example 4, Nesting CTE (SQLAlchemy 1.4.24 and above)::
|
| value_a = select(literal("root").label("n")).cte("value_a")
|
| # A nested CTE with the same name as the root one
| value_a_nested = select(literal("nesting").label("n")).cte(
| "value_a", nesting=True
| )
|
| # Nesting CTEs takes ascendency locally
| # over the CTEs at a higher level
| value_b = select(value_a_nested.c.n).cte("value_b")
|
| value_ab = select(value_a.c.n.label("a"), value_b.c.n.label("b"))
|
| The above query will render the second CTE nested inside the first,
| shown with inline parameters below as:
|
| .. sourcecode:: sql
|
| WITH
| value_a AS
| (SELECT 'root' AS n),
| value_b AS
| (WITH value_a AS
| (SELECT 'nesting' AS n)
| SELECT value_a.n AS n FROM value_a)
| SELECT value_a.n AS a, value_b.n AS b
| FROM value_a, value_b
|
| The same CTE can be set up using the :meth:`.HasCTE.add_cte` method
| as follows (SQLAlchemy 2.0 and above)::
|
| value_a = select(literal("root").label("n")).cte("value_a")
|
| # A nested CTE with the same name as the root one
| value_a_nested = select(literal("nesting").label("n")).cte("value_a")
|
| # Nesting CTEs takes ascendency locally
| # over the CTEs at a higher level
| value_b = (
| select(value_a_nested.c.n)
| .add_cte(value_a_nested, nest_here=True)
| .cte("value_b")
| )
|
| value_ab = select(value_a.c.n.label("a"), value_b.c.n.label("b"))
|
| Example 5, Non-Linear CTE (SQLAlchemy 1.4.28 and above)::
|
| edge = Table(
| "edge",
| metadata,
| Column("id", Integer, primary_key=True),
| Column("left", Integer),
| Column("right", Integer),
| )
|
| root_node = select(literal(1).label("node")).cte("nodes", recursive=True)
|
| left_edge = select(edge.c.left).join(
| root_node, edge.c.right == root_node.c.node
| )
| right_edge = select(edge.c.right).join(
| root_node, edge.c.left == root_node.c.node
| )
|
| subgraph_cte = root_node.union(left_edge, right_edge)
|
| subgraph = select(subgraph_cte)
|
| The above query will render 2 UNIONs inside the recursive CTE:
|
| .. sourcecode:: sql
|
| WITH RECURSIVE nodes(node) AS (
| SELECT 1 AS node
| UNION
| SELECT edge."left" AS "left"
| FROM edge JOIN nodes ON edge."right" = nodes.node
| UNION
| SELECT edge."right" AS "right"
| FROM edge JOIN nodes ON edge."left" = nodes.node
| )
| SELECT nodes.node FROM nodes
|
| .. seealso::
|
| :meth:`_orm.Query.cte` - ORM version of
| :meth:`_expression.HasCTE.cte`.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from HasCTE:
|
| name_cte_columns = False
|
| ----------------------------------------------------------------------
| Methods inherited from Selectable:
|
| 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.
|
| 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`.
|
| .. deprecated:: 1.4 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.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from Selectable:
|
| is_selectable = True
|
| ----------------------------------------------------------------------
| Readonly properties inherited from ReturnsRows:
|
| selectable
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.SQLRole:
|
| uses_inspection = False
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.elements.ClauseElement:
|
| __bool__(self)
|
| __getstate__(self)
| Helper for pickle.
|
| __invert__(self)
|
| __repr__(self)
| Return repr(self).
|
| compare(self, other: 'ClauseElement', **kw: 'Any') -> 'bool'
| Compare this :class:`_expression.ClauseElement` to
| the given :class:`_expression.ClauseElement`.
|
| Subclasses should override the default behavior, which is a
| straight identity comparison.
|
| \**kw are arguments consumed by subclass ``compare()`` methods and
| may be used to modify the criteria for comparison
| (see :class:`_expression.ColumnElement`).
|
| description(...)
|
| entity_namespace(...)
|
| params(self, _ClauseElement__optionaldict: 'Optional[Mapping[str, Any]]' = None, **kwargs: 'Any') -> 'Self'
| Return a copy with :func:`_expression.bindparam` elements
| replaced.
|
| Returns a copy of this ClauseElement with
| :func:`_expression.bindparam`
| elements replaced with values taken from the given dictionary::
|
| >>> clause = column("x") + bindparam("foo")
| >>> print(clause.compile().params)
| {'foo':None}
| >>> print(clause.params({"foo": 7}).compile().params)
| {'foo':7}
|
| unique_params(self, _ClauseElement__optionaldict: 'Optional[Dict[str, Any]]' = None, **kwargs: 'Any') -> 'Self'
| Return a copy with :func:`_expression.bindparam` elements
| replaced.
|
| Same functionality as :meth:`_expression.ClauseElement.params`,
| except adds `unique=True`
| to affected bind parameters so that multiple statements can be
| used.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.elements.ClauseElement:
|
| is_clause_element = True
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.cache_key.HasCacheKey:
|
| inherit_cache = None
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_instancemethod(fn: '_F') -> '_F'
| Decorate a method memoize its return value.
|
| :meta private:
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_attribute = <class 'sqlalchemy.util.langhelpers.HasMemoized.m...
| A read-only @property that is only evaluated once.
|
| :meta private:
|
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.visitors.HasTraverseInternals:
|
| get_children(self, *, omit_attrs: 'Tuple[str, ...]' = (), **kw: 'Any') -> 'Iterable[HasTraverseInternals]'
| Return immediate child :class:`.visitors.HasTraverseInternals`
| elements of this :class:`.visitors.HasTraverseInternals`.
|
| This is used for visit traversal.
|
| \**kw may contain flags that change the collection that is
| returned, for example to return a subset of items in order to
| cut down on larger traversals, or to return child items from a
| different context (such as schema-level collections instead of
| clause-level).
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.elements.CompilerElement:
|
| __str__(self) -> 'str'
| Return str(self).
|
| compile(self, bind: 'Optional[_HasDialect]' = None, dialect: 'Optional[Dialect]' = None, **kw: 'Any') -> 'Compiled'
| Compile this SQL expression.
|
| The return value is a :class:`~.Compiled` object.
| Calling ``str()`` or ``unicode()`` on the returned value will yield a
| string representation of the result. The
| :class:`~.Compiled` object also can return a
| dictionary of bind parameter names and values
| using the ``params`` accessor.
|
| :param bind: An :class:`.Connection` or :class:`.Engine` which
| can provide a :class:`.Dialect` in order to generate a
| :class:`.Compiled` object. If the ``bind`` and
| ``dialect`` parameters are both omitted, a default SQL compiler
| is used.
|
| :param column_keys: Used for INSERT and UPDATE statements, a list of
| column names which should be present in the VALUES clause of the
| compiled statement. If ``None``, all columns from the target table
| object are rendered.
|
| :param dialect: A :class:`.Dialect` instance which can generate
| a :class:`.Compiled` object. This argument takes precedence over
| the ``bind`` argument.
|
| :param compile_kwargs: optional dictionary of additional parameters
| that will be passed through to the compiler within all "visit"
| methods. This allows any custom flag to be passed through to
| a custom compilation construct, for example. It is also used
| for the case of passing the ``literal_binds`` flag through::
|
| from sqlalchemy.sql import table, column, select
|
| t = table("t", column("x"))
|
| s = select(t).where(t.c.x == 5)
|
| print(s.compile(compile_kwargs={"literal_binds": True}))
|
| .. seealso::
|
| :ref:`faq_sql_expression_string`
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.elements.CompilerElement:
|
| stringify_dialect = 'default'
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.visitors.Visitable:
|
| __class_getitem__(key: 'Any') -> 'Any'
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__() -> 'None'
| This method is called when a class is subclassed.
|
| The default implementation does nothing. It may be
| overridden to extend subclasses.
sqlalchemy.Computed
Python Library Documentation: class Computed in module sqlalchemy.sql.schema
class Computed(FetchedValue, SchemaItem)
| Computed(sqltext: '_DDLColumnArgument', persisted: 'Optional[bool]' = None) -> 'None'
|
| Defines a generated column, i.e. "GENERATED ALWAYS AS" syntax.
|
| The :class:`.Computed` construct is an inline construct added to the
| argument list of a :class:`_schema.Column` object::
|
| from sqlalchemy import Computed
|
| Table(
| "square",
| metadata_obj,
| Column("side", Float, nullable=False),
| Column("area", Float, Computed("side * side")),
| )
|
| See the linked documentation below for complete details.
|
| .. versionadded:: 1.3.11
|
| .. seealso::
|
| :ref:`computed_ddl`
|
| Method resolution order:
| Computed
| FetchedValue
| SchemaItem
| sqlalchemy.sql.base.SchemaVisitable
| sqlalchemy.sql.base.SchemaEventTarget
| sqlalchemy.event.registry.EventTarget
| sqlalchemy.sql.visitors.Visitable
| builtins.object
|
| Methods defined here:
|
| __init__(self, sqltext: '_DDLColumnArgument', persisted: 'Optional[bool]' = None) -> 'None'
| Construct a GENERATED ALWAYS AS DDL construct to accompany a
| :class:`_schema.Column`.
|
| :param sqltext:
| A string containing the column generation expression, which will be
| used verbatim, or a SQL expression construct, such as a
| :func:`_expression.text`
| object. If given as a string, the object is converted to a
| :func:`_expression.text` object.
|
| .. warning:: The :paramref:`.Computed.sqltext` argument to :class:`.Computed` can be passed as a Python string argument, which will be treated as **trusted SQL text** and rendered as given. **DO NOT PASS UNTRUSTED INPUT TO THIS PARAMETER**.
|
|
|
| :param persisted:
| Optional, controls how this column should be persisted by the
| database. Possible values are:
|
| * ``None``, the default, it will use the default persistence
| defined by the database.
| * ``True``, will render ``GENERATED ALWAYS AS ... STORED``, or the
| equivalent for the target database if supported.
| * ``False``, will render ``GENERATED ALWAYS AS ... VIRTUAL``, or
| the equivalent for the target database if supported.
|
| Specifying ``True`` or ``False`` may raise an error when the DDL
| is emitted to the target database if the database does not support
| that persistence option. Leaving this parameter at its default
| of ``None`` is guaranteed to succeed for all databases that support
| ``GENERATED ALWAYS AS``.
|
| copy(self, *, target_table: 'Optional[Table]' = None, **kw: 'Any') -> 'Computed'
| .. deprecated:: 1.4 The :meth:`_schema.Computed.copy` method is deprecated and will be removed in a future release.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'column': 'Optional[Column[Any]]'}
|
| __visit_name__ = 'computed_column'
|
| ----------------------------------------------------------------------
| Methods inherited from FetchedValue:
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from FetchedValue:
|
| has_argument = False
|
| is_clause_element = False
|
| is_identity = False
|
| is_server_default = True
|
| reflected = False
|
| ----------------------------------------------------------------------
| Methods inherited from SchemaItem:
|
| info(...)
| Info dictionary associated with the object, allowing user-defined
| data to be associated with this :class:`.SchemaItem`.
|
| The dictionary is automatically generated when first accessed.
| It can also be specified in the constructor of some objects,
| such as :class:`_schema.Table` and :class:`_schema.Column`.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from SchemaItem:
|
| create_drop_stringify_dialect = 'default'
|
| ----------------------------------------------------------------------
| Data descriptors inherited from sqlalchemy.sql.base.SchemaEventTarget:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.base.SchemaEventTarget:
|
| dispatch = <sqlalchemy.event.base.DDLEventsDispatch object>
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.visitors.Visitable:
|
| __class_getitem__(key: 'Any') -> 'Any'
|
| __init_subclass__() -> 'None'
| This method is called when a class is subclassed.
|
| The default implementation does nothing. It may be
| overridden to extend subclasses.
sqlalchemy.Connection
Python Library Documentation: class Connection in module sqlalchemy.engine.base
class Connection(sqlalchemy.engine.interfaces.ConnectionEventsTarget, sqlalchemy.inspection.Inspectable)
| Connection(engine: 'Engine', connection: 'Optional[PoolProxiedConnection]' = None, _has_events: 'Optional[bool]' = None, _allow_revalidate: 'bool' = True, _allow_autobegin: 'bool' = True)
|
| Provides high-level functionality for a wrapped DB-API connection.
|
| The :class:`_engine.Connection` object is procured by calling the
| :meth:`_engine.Engine.connect` method of the :class:`_engine.Engine`
| object, and provides services for execution of SQL statements as well
| as transaction control.
|
| The Connection object is **not** thread-safe. While a Connection can be
| shared among threads using properly synchronized access, it is still
| possible that the underlying DBAPI connection may not support shared
| access between threads. Check the DBAPI documentation for details.
|
| The Connection object represents a single DBAPI connection checked out
| from the connection pool. In this state, the connection pool has no
| affect upon the connection, including its expiration or timeout state.
| For the connection pool to properly manage connections, connections
| should be returned to the connection pool (i.e. ``connection.close()``)
| whenever the connection is not in use.
|
| .. index::
| single: thread safety; Connection
|
| Method resolution order:
| Connection
| sqlalchemy.engine.interfaces.ConnectionEventsTarget
| sqlalchemy.event.registry.EventTarget
| sqlalchemy.inspection.Inspectable
| typing.Generic
| builtins.object
|
| Methods defined here:
|
| __enter__(self) -> 'Connection'
|
| __exit__(self, type_: 'Any', value: 'Any', traceback: 'Any') -> 'None'
|
| __init__(self, engine: 'Engine', connection: 'Optional[PoolProxiedConnection]' = None, _has_events: 'Optional[bool]' = None, _allow_revalidate: 'bool' = True, _allow_autobegin: 'bool' = True)
| Construct a new Connection.
|
| begin(self) -> 'RootTransaction'
| Begin a transaction prior to autobegin occurring.
|
| E.g.::
|
| with engine.connect() as conn:
| with conn.begin() as trans:
| conn.execute(table.insert(), {"username": "sandy"})
|
| The returned object is an instance of :class:`_engine.RootTransaction`.
| This object represents the "scope" of the transaction,
| which completes when either the :meth:`_engine.Transaction.rollback`
| or :meth:`_engine.Transaction.commit` method is called; the object
| also works as a context manager as illustrated above.
|
| The :meth:`_engine.Connection.begin` method begins a
| transaction that normally will be begun in any case when the connection
| is first used to execute a statement. The reason this method might be
| used would be to invoke the :meth:`_events.ConnectionEvents.begin`
| event at a specific time, or to organize code within the scope of a
| connection checkout in terms of context managed blocks, such as::
|
| with engine.connect() as conn:
| with conn.begin():
| conn.execute(...)
| conn.execute(...)
|
| with conn.begin():
| conn.execute(...)
| conn.execute(...)
|
| The above code is not fundamentally any different in its behavior than
| the following code which does not use
| :meth:`_engine.Connection.begin`; the below style is known
| as "commit as you go" style::
|
| with engine.connect() as conn:
| conn.execute(...)
| conn.execute(...)
| conn.commit()
|
| conn.execute(...)
| conn.execute(...)
| conn.commit()
|
| From a database point of view, the :meth:`_engine.Connection.begin`
| method does not emit any SQL or change the state of the underlying
| DBAPI connection in any way; the Python DBAPI does not have any
| concept of explicit transaction begin.
|
| .. seealso::
|
| :ref:`tutorial_working_with_transactions` - in the
| :ref:`unified_tutorial`
|
| :meth:`_engine.Connection.begin_nested` - use a SAVEPOINT
|
| :meth:`_engine.Connection.begin_twophase` -
| use a two phase /XID transaction
|
| :meth:`_engine.Engine.begin` - context manager available from
| :class:`_engine.Engine`
|
| begin_nested(self) -> 'NestedTransaction'
| Begin a nested transaction (i.e. SAVEPOINT) and return a transaction
| handle that controls the scope of the SAVEPOINT.
|
| E.g.::
|
| with engine.begin() as connection:
| with connection.begin_nested():
| connection.execute(table.insert(), {"username": "sandy"})
|
| The returned object is an instance of
| :class:`_engine.NestedTransaction`, which includes transactional
| methods :meth:`_engine.NestedTransaction.commit` and
| :meth:`_engine.NestedTransaction.rollback`; for a nested transaction,
| these methods correspond to the operations "RELEASE SAVEPOINT <name>"
| and "ROLLBACK TO SAVEPOINT <name>". The name of the savepoint is local
| to the :class:`_engine.NestedTransaction` object and is generated
| automatically. Like any other :class:`_engine.Transaction`, the
| :class:`_engine.NestedTransaction` may be used as a context manager as
| illustrated above which will "release" or "rollback" corresponding to
| if the operation within the block were successful or raised an
| exception.
|
| Nested transactions require SAVEPOINT support in the underlying
| database, else the behavior is undefined. SAVEPOINT is commonly used to
| run operations within a transaction that may fail, while continuing the
| outer transaction. E.g.::
|
| from sqlalchemy import exc
|
| with engine.begin() as connection:
| trans = connection.begin_nested()
| try:
| connection.execute(table.insert(), {"username": "sandy"})
| trans.commit()
| except exc.IntegrityError: # catch for duplicate username
| trans.rollback() # rollback to savepoint
|
| # outer transaction continues
| connection.execute(...)
|
| If :meth:`_engine.Connection.begin_nested` is called without first
| calling :meth:`_engine.Connection.begin` or
| :meth:`_engine.Engine.begin`, the :class:`_engine.Connection` object
| will "autobegin" the outer transaction first. This outer transaction
| may be committed using "commit-as-you-go" style, e.g.::
|
| with engine.connect() as connection: # begin() wasn't called
|
| with connection.begin_nested(): # will auto-"begin()" first
| connection.execute(...)
| # savepoint is released
|
| connection.execute(...)
|
| # explicitly commit outer transaction
| connection.commit()
|
| # can continue working with connection here
|
| .. versionchanged:: 2.0
|
| :meth:`_engine.Connection.begin_nested` will now participate
| in the connection "autobegin" behavior that is new as of
| 2.0 / "future" style connections in 1.4.
|
| .. seealso::
|
| :meth:`_engine.Connection.begin`
|
| :ref:`session_begin_nested` - ORM support for SAVEPOINT
|
| begin_twophase(self, xid: 'Optional[Any]' = None) -> 'TwoPhaseTransaction'
| Begin a two-phase or XA transaction and return a transaction
| handle.
|
| The returned object is an instance of :class:`.TwoPhaseTransaction`,
| which in addition to the methods provided by
| :class:`.Transaction`, also provides a
| :meth:`~.TwoPhaseTransaction.prepare` method.
|
| :param xid: the two phase transaction id. If not supplied, a
| random id will be generated. The accepted type and value depends on
| the driver in use.
|
| .. seealso::
|
| :meth:`_engine.Connection.begin`
|
| :meth:`_engine.Connection.begin_twophase`
|
| close(self) -> 'None'
| Close this :class:`_engine.Connection`.
|
| This results in a release of the underlying database
| resources, that is, the DBAPI connection referenced
| internally. The DBAPI connection is typically restored
| back to the connection-holding :class:`_pool.Pool` referenced
| by the :class:`_engine.Engine` that produced this
| :class:`_engine.Connection`. Any transactional state present on
| the DBAPI connection is also unconditionally released via
| the DBAPI connection's ``rollback()`` method, regardless
| of any :class:`.Transaction` object that may be
| outstanding with regards to this :class:`_engine.Connection`.
|
| This has the effect of also calling :meth:`_engine.Connection.rollback`
| if any transaction is in place.
|
| After :meth:`_engine.Connection.close` is called, the
| :class:`_engine.Connection` is permanently in a closed state,
| and will allow no further operations.
|
| commit(self) -> 'None'
| Commit the transaction that is currently in progress.
|
| This method commits the current transaction if one has been started.
| If no transaction was started, the method has no effect, assuming
| the connection is in a non-invalidated state.
|
| A transaction is begun on a :class:`_engine.Connection` automatically
| whenever a statement is first executed, or when the
| :meth:`_engine.Connection.begin` method is called.
|
| .. note:: The :meth:`_engine.Connection.commit` method only acts upon
| the primary database transaction that is linked to the
| :class:`_engine.Connection` object. It does not operate upon a
| SAVEPOINT that would have been invoked from the
| :meth:`_engine.Connection.begin_nested` method; for control of a
| SAVEPOINT, call :meth:`_engine.NestedTransaction.commit` on the
| :class:`_engine.NestedTransaction` that is returned by the
| :meth:`_engine.Connection.begin_nested` method itself.
|
| commit_prepared(self, xid: 'Any', recover: 'bool' = False) -> 'None'
|
| detach(self) -> 'None'
| Detach the underlying DB-API connection from its connection pool.
|
| E.g.::
|
| with engine.connect() as conn:
| conn.detach()
| conn.execute(text("SET search_path TO schema1, schema2"))
|
| # work with connection
|
| # connection is fully closed (since we used "with:", can
| # also call .close())
|
| This :class:`_engine.Connection` instance will remain usable.
| When closed
| (or exited from a context manager context as above),
| the DB-API connection will be literally closed and not
| returned to its originating pool.
|
| This method can be used to insulate the rest of an application
| from a modified state on a connection (such as a transaction
| isolation level or similar).
|
| exec_driver_sql(self, statement: 'str', parameters: 'Optional[_DBAPIAnyExecuteParams]' = None, execution_options: 'Optional[CoreExecuteOptionsParameter]' = None) -> 'CursorResult[Any]'
| Executes a string SQL statement on the DBAPI cursor directly,
| without any SQL compilation steps.
|
| This can be used to pass any string directly to the
| ``cursor.execute()`` method of the DBAPI in use.
|
| :param statement: The statement str to be executed. Bound parameters
| must use the underlying DBAPI's paramstyle, such as "qmark",
| "pyformat", "format", etc.
|
| :param parameters: represent bound parameter values to be used in the
| execution. The format is one of: a dictionary of named parameters,
| a tuple of positional parameters, or a list containing either
| dictionaries or tuples for multiple-execute support.
|
| :return: a :class:`_engine.CursorResult`.
|
| E.g. multiple dictionaries::
|
|
| conn.exec_driver_sql(
| "INSERT INTO table (id, value) VALUES (%(id)s, %(value)s)",
| [{"id": 1, "value": "v1"}, {"id": 2, "value": "v2"}],
| )
|
| Single dictionary::
|
| conn.exec_driver_sql(
| "INSERT INTO table (id, value) VALUES (%(id)s, %(value)s)",
| dict(id=1, value="v1"),
| )
|
| Single tuple::
|
| conn.exec_driver_sql(
| "INSERT INTO table (id, value) VALUES (?, ?)", (1, "v1")
| )
|
| .. note:: The :meth:`_engine.Connection.exec_driver_sql` method does
| not participate in the
| :meth:`_events.ConnectionEvents.before_execute` and
| :meth:`_events.ConnectionEvents.after_execute` events. To
| intercept calls to :meth:`_engine.Connection.exec_driver_sql`, use
| :meth:`_events.ConnectionEvents.before_cursor_execute` and
| :meth:`_events.ConnectionEvents.after_cursor_execute`.
|
| .. seealso::
|
| :pep:`249`
|
| execute(self, statement: 'Executable', parameters: 'Optional[_CoreAnyExecuteParams]' = None, *, execution_options: 'Optional[CoreExecuteOptionsParameter]' = None) -> 'CursorResult[Any]'
| Executes a SQL statement construct and returns a
| :class:`_engine.CursorResult`.
|
| :param statement: The statement to be executed. This is always
| an object that is in both the :class:`_expression.ClauseElement` and
| :class:`_expression.Executable` hierarchies, including:
|
| * :class:`_expression.Select`
| * :class:`_expression.Insert`, :class:`_expression.Update`,
| :class:`_expression.Delete`
| * :class:`_expression.TextClause` and
| :class:`_expression.TextualSelect`
| * :class:`_schema.DDL` and objects which inherit from
| :class:`_schema.ExecutableDDLElement`
|
| :param parameters: parameters which will be bound into the statement.
| This may be either a dictionary of parameter names to values,
| or a mutable sequence (e.g. a list) of dictionaries. When a
| list of dictionaries is passed, the underlying statement execution
| will make use of the DBAPI ``cursor.executemany()`` method.
| When a single dictionary is passed, the DBAPI ``cursor.execute()``
| method will be used.
|
| :param execution_options: optional dictionary of execution options,
| which will be associated with the statement execution. This
| dictionary can provide a subset of the options that are accepted
| by :meth:`_engine.Connection.execution_options`.
|
| :return: a :class:`_engine.Result` object.
|
| execution_options(self, **opt: 'Any') -> 'Connection'
| Set non-SQL options for the connection which take effect
| during execution.
|
| This method modifies this :class:`_engine.Connection` **in-place**;
| the return value is the same :class:`_engine.Connection` object
| upon which the method is called. Note that this is in contrast
| to the behavior of the ``execution_options`` methods on other
| objects such as :meth:`_engine.Engine.execution_options` and
| :meth:`_sql.Executable.execution_options`. The rationale is that many
| such execution options necessarily modify the state of the base
| DBAPI connection in any case so there is no feasible means of
| keeping the effect of such an option localized to a "sub" connection.
|
| .. versionchanged:: 2.0 The :meth:`_engine.Connection.execution_options`
| method, in contrast to other objects with this method, modifies
| the connection in-place without creating copy of it.
|
| As discussed elsewhere, the :meth:`_engine.Connection.execution_options`
| method accepts any arbitrary parameters including user defined names.
| All parameters given are consumable in a number of ways including
| by using the :meth:`_engine.Connection.get_execution_options` method.
| See the examples at :meth:`_sql.Executable.execution_options`
| and :meth:`_engine.Engine.execution_options`.
|
| The keywords that are currently recognized by SQLAlchemy itself
| include all those listed under :meth:`.Executable.execution_options`,
| as well as others that are specific to :class:`_engine.Connection`.
|
| :param compiled_cache: Available on: :class:`_engine.Connection`,
| :class:`_engine.Engine`.
|
| A dictionary where :class:`.Compiled` objects
| will be cached when the :class:`_engine.Connection`
| compiles a clause
| expression into a :class:`.Compiled` object. This dictionary will
| supersede the statement cache that may be configured on the
| :class:`_engine.Engine` itself. If set to None, caching
| is disabled, even if the engine has a configured cache size.
|
| Note that the ORM makes use of its own "compiled" caches for
| some operations, including flush operations. The caching
| used by the ORM internally supersedes a cache dictionary
| specified here.
|
| :param logging_token: Available on: :class:`_engine.Connection`,
| :class:`_engine.Engine`, :class:`_sql.Executable`.
|
| Adds the specified string token surrounded by brackets in log
| messages logged by the connection, i.e. the logging that's enabled
| either via the :paramref:`_sa.create_engine.echo` flag or via the
| ``logging.getLogger("sqlalchemy.engine")`` logger. This allows a
| per-connection or per-sub-engine token to be available which is
| useful for debugging concurrent connection scenarios.
|
| .. versionadded:: 1.4.0b2
|
| .. seealso::
|
| :ref:`dbengine_logging_tokens` - usage example
|
| :paramref:`_sa.create_engine.logging_name` - adds a name to the
| name used by the Python logger object itself.
|
| :param isolation_level: Available on: :class:`_engine.Connection`,
| :class:`_engine.Engine`.
|
| Set the transaction isolation level for the lifespan of this
| :class:`_engine.Connection` object.
| Valid values include those string
| values accepted by the :paramref:`_sa.create_engine.isolation_level`
| parameter passed to :func:`_sa.create_engine`. These levels are
| semi-database specific; see individual dialect documentation for
| valid levels.
|
| The isolation level option applies the isolation level by emitting
| statements on the DBAPI connection, and **necessarily affects the
| original Connection object overall**. The isolation level will remain
| at the given setting until explicitly changed, or when the DBAPI
| connection itself is :term:`released` to the connection pool, i.e. the
| :meth:`_engine.Connection.close` method is called, at which time an
| event handler will emit additional statements on the DBAPI connection
| in order to revert the isolation level change.
|
| .. note:: The ``isolation_level`` execution option may only be
| established before the :meth:`_engine.Connection.begin` method is
| called, as well as before any SQL statements are emitted which
| would otherwise trigger "autobegin", or directly after a call to
| :meth:`_engine.Connection.commit` or
| :meth:`_engine.Connection.rollback`. A database cannot change the
| isolation level on a transaction in progress.
|
| .. note:: The ``isolation_level`` execution option is implicitly
| reset if the :class:`_engine.Connection` is invalidated, e.g. via
| the :meth:`_engine.Connection.invalidate` method, or if a
| disconnection error occurs. The new connection produced after the
| invalidation will **not** have the selected isolation level
| re-applied to it automatically.
|
| .. seealso::
|
| :ref:`dbapi_autocommit`
|
| :meth:`_engine.Connection.get_isolation_level`
| - view current actual level
|
| :param no_parameters: Available on: :class:`_engine.Connection`,
| :class:`_sql.Executable`.
|
| When ``True``, if the final parameter
| list or dictionary is totally empty, will invoke the
| statement on the cursor as ``cursor.execute(statement)``,
| not passing the parameter collection at all.
| Some DBAPIs such as psycopg2 and mysql-python consider
| percent signs as significant only when parameters are
| present; this option allows code to generate SQL
| containing percent signs (and possibly other characters)
| that is neutral regarding whether it's executed by the DBAPI
| or piped into a script that's later invoked by
| command line tools.
|
| :param stream_results: Available on: :class:`_engine.Connection`,
| :class:`_sql.Executable`.
|
| Indicate to the dialect that results should be "streamed" and not
| pre-buffered, if possible. For backends such as PostgreSQL, MySQL
| and MariaDB, this indicates the use of a "server side cursor" as
| opposed to a client side cursor. Other backends such as that of
| Oracle Database may already use server side cursors by default.
|
| The usage of
| :paramref:`_engine.Connection.execution_options.stream_results` is
| usually combined with setting a fixed number of rows to to be fetched
| in batches, to allow for efficient iteration of database rows while
| at the same time not loading all result rows into memory at once;
| this can be configured on a :class:`_engine.Result` object using the
| :meth:`_engine.Result.yield_per` method, after execution has
| returned a new :class:`_engine.Result`. If
| :meth:`_engine.Result.yield_per` is not used,
| the :paramref:`_engine.Connection.execution_options.stream_results`
| mode of operation will instead use a dynamically sized buffer
| which buffers sets of rows at a time, growing on each batch
| based on a fixed growth size up until a limit which may
| be configured using the
| :paramref:`_engine.Connection.execution_options.max_row_buffer`
| parameter.
|
| When using the ORM to fetch ORM mapped objects from a result,
| :meth:`_engine.Result.yield_per` should always be used with
| :paramref:`_engine.Connection.execution_options.stream_results`,
| so that the ORM does not fetch all rows into new ORM objects at once.
|
| For typical use, the
| :paramref:`_engine.Connection.execution_options.yield_per` execution
| option should be preferred, which sets up both
| :paramref:`_engine.Connection.execution_options.stream_results` and
| :meth:`_engine.Result.yield_per` at once. This option is supported
| both at a core level by :class:`_engine.Connection` as well as by the
| ORM :class:`_engine.Session`; the latter is described at
| :ref:`orm_queryguide_yield_per`.
|
| .. seealso::
|
| :ref:`engine_stream_results` - background on
| :paramref:`_engine.Connection.execution_options.stream_results`
|
| :paramref:`_engine.Connection.execution_options.max_row_buffer`
|
| :paramref:`_engine.Connection.execution_options.yield_per`
|
| :ref:`orm_queryguide_yield_per` - in the :ref:`queryguide_toplevel`
| describing the ORM version of ``yield_per``
|
| :param max_row_buffer: Available on: :class:`_engine.Connection`,
| :class:`_sql.Executable`. Sets a maximum
| buffer size to use when the
| :paramref:`_engine.Connection.execution_options.stream_results`
| execution option is used on a backend that supports server side
| cursors. The default value if not specified is 1000.
|
| .. seealso::
|
| :paramref:`_engine.Connection.execution_options.stream_results`
|
| :ref:`engine_stream_results`
|
|
| :param yield_per: Available on: :class:`_engine.Connection`,
| :class:`_sql.Executable`. Integer value applied which will
| set the :paramref:`_engine.Connection.execution_options.stream_results`
| execution option and invoke :meth:`_engine.Result.yield_per`
| automatically at once. Allows equivalent functionality as
| is present when using this parameter with the ORM.
|
| .. versionadded:: 1.4.40
|
| .. seealso::
|
| :ref:`engine_stream_results` - background and examples
| on using server side cursors with Core.
|
| :ref:`orm_queryguide_yield_per` - in the :ref:`queryguide_toplevel`
| describing the ORM version of ``yield_per``
|
| :param insertmanyvalues_page_size: Available on: :class:`_engine.Connection`,
| :class:`_engine.Engine`. Number of rows to format into an
| INSERT statement when the statement uses "insertmanyvalues" mode,
| which is a paged form of bulk insert that is used for many backends
| when using :term:`executemany` execution typically in conjunction
| with RETURNING. Defaults to 1000. May also be modified on a
| per-engine basis using the
| :paramref:`_sa.create_engine.insertmanyvalues_page_size` parameter.
|
| .. versionadded:: 2.0
|
| .. seealso::
|
| :ref:`engine_insertmanyvalues`
|
| :param schema_translate_map: Available on: :class:`_engine.Connection`,
| :class:`_engine.Engine`, :class:`_sql.Executable`.
|
| A dictionary mapping schema names to schema names, that will be
| applied to the :paramref:`_schema.Table.schema` element of each
| :class:`_schema.Table`
| encountered when SQL or DDL expression elements
| are compiled into strings; the resulting schema name will be
| converted based on presence in the map of the original name.
|
| .. seealso::
|
| :ref:`schema_translating`
|
| :param preserve_rowcount: Boolean; when True, the ``cursor.rowcount``
| attribute will be unconditionally memoized within the result and
| made available via the :attr:`.CursorResult.rowcount` attribute.
| Normally, this attribute is only preserved for UPDATE and DELETE
| statements. Using this option, the DBAPIs rowcount value can
| be accessed for other kinds of statements such as INSERT and SELECT,
| to the degree that the DBAPI supports these statements. See
| :attr:`.CursorResult.rowcount` for notes regarding the behavior
| of this attribute.
|
| .. versionadded:: 2.0.28
|
| .. seealso::
|
| :meth:`_engine.Engine.execution_options`
|
| :meth:`.Executable.execution_options`
|
| :meth:`_engine.Connection.get_execution_options`
|
| :ref:`orm_queryguide_execution_options` - documentation on all
| ORM-specific execution options
|
| get_execution_options(self) -> '_ExecuteOptions'
| Get the non-SQL options which will take effect during execution.
|
| .. versionadded:: 1.3
|
| .. seealso::
|
| :meth:`_engine.Connection.execution_options`
|
| get_isolation_level(self) -> 'IsolationLevel'
| Return the current **actual** isolation level that's present on
| the database within the scope of this connection.
|
| This attribute will perform a live SQL operation against the database
| in order to procure the current isolation level, so the value returned
| is the actual level on the underlying DBAPI connection regardless of
| how this state was set. This will be one of the four actual isolation
| modes ``READ UNCOMMITTED``, ``READ COMMITTED``, ``REPEATABLE READ``,
| ``SERIALIZABLE``. It will **not** include the ``AUTOCOMMIT`` isolation
| level setting. Third party dialects may also feature additional
| isolation level settings.
|
| .. note:: This method **will not report** on the ``AUTOCOMMIT``
| isolation level, which is a separate :term:`dbapi` setting that's
| independent of **actual** isolation level. When ``AUTOCOMMIT`` is
| in use, the database connection still has a "traditional" isolation
| mode in effect, that is typically one of the four values
| ``READ UNCOMMITTED``, ``READ COMMITTED``, ``REPEATABLE READ``,
| ``SERIALIZABLE``.
|
| Compare to the :attr:`_engine.Connection.default_isolation_level`
| accessor which returns the isolation level that is present on the
| database at initial connection time.
|
| .. seealso::
|
| :attr:`_engine.Connection.default_isolation_level`
| - view default level
|
| :paramref:`_sa.create_engine.isolation_level`
| - set per :class:`_engine.Engine` isolation level
|
| :paramref:`.Connection.execution_options.isolation_level`
| - set per :class:`_engine.Connection` isolation level
|
| get_nested_transaction(self) -> 'Optional[NestedTransaction]'
| Return the current nested transaction in progress, if any.
|
| .. versionadded:: 1.4
|
| get_transaction(self) -> 'Optional[RootTransaction]'
| Return the current root transaction in progress, if any.
|
| .. versionadded:: 1.4
|
| in_nested_transaction(self) -> 'bool'
| Return True if a transaction is in progress.
|
| in_transaction(self) -> 'bool'
| Return True if a transaction is in progress.
|
| invalidate(self, exception: 'Optional[BaseException]' = None) -> 'None'
| Invalidate the underlying DBAPI connection associated with
| this :class:`_engine.Connection`.
|
| An attempt will be made to close the underlying DBAPI connection
| immediately; however if this operation fails, the error is logged
| but not raised. The connection is then discarded whether or not
| close() succeeded.
|
| Upon the next use (where "use" typically means using the
| :meth:`_engine.Connection.execute` method or similar),
| this :class:`_engine.Connection` will attempt to
| procure a new DBAPI connection using the services of the
| :class:`_pool.Pool` as a source of connectivity (e.g.
| a "reconnection").
|
| If a transaction was in progress (e.g. the
| :meth:`_engine.Connection.begin` method has been called) when
| :meth:`_engine.Connection.invalidate` method is called, at the DBAPI
| level all state associated with this transaction is lost, as
| the DBAPI connection is closed. The :class:`_engine.Connection`
| will not allow a reconnection to proceed until the
| :class:`.Transaction` object is ended, by calling the
| :meth:`.Transaction.rollback` method; until that point, any attempt at
| continuing to use the :class:`_engine.Connection` will raise an
| :class:`~sqlalchemy.exc.InvalidRequestError`.
| This is to prevent applications from accidentally
| continuing an ongoing transactional operations despite the
| fact that the transaction has been lost due to an
| invalidation.
|
| The :meth:`_engine.Connection.invalidate` method,
| just like auto-invalidation,
| will at the connection pool level invoke the
| :meth:`_events.PoolEvents.invalidate` event.
|
| :param exception: an optional ``Exception`` instance that's the
| reason for the invalidation. is passed along to event handlers
| and logging functions.
|
| .. seealso::
|
| :ref:`pool_connection_invalidation`
|
| recover_twophase(self) -> 'List[Any]'
|
| rollback(self) -> 'None'
| Roll back the transaction that is currently in progress.
|
| This method rolls back the current transaction if one has been started.
| If no transaction was started, the method has no effect. If a
| transaction was started and the connection is in an invalidated state,
| the transaction is cleared using this method.
|
| A transaction is begun on a :class:`_engine.Connection` automatically
| whenever a statement is first executed, or when the
| :meth:`_engine.Connection.begin` method is called.
|
| .. note:: The :meth:`_engine.Connection.rollback` method only acts
| upon the primary database transaction that is linked to the
| :class:`_engine.Connection` object. It does not operate upon a
| SAVEPOINT that would have been invoked from the
| :meth:`_engine.Connection.begin_nested` method; for control of a
| SAVEPOINT, call :meth:`_engine.NestedTransaction.rollback` on the
| :class:`_engine.NestedTransaction` that is returned by the
| :meth:`_engine.Connection.begin_nested` method itself.
|
| rollback_prepared(self, xid: 'Any', recover: 'bool' = False) -> 'None'
|
| scalar(self, statement: 'Executable', parameters: 'Optional[_CoreSingleExecuteParams]' = None, *, execution_options: 'Optional[CoreExecuteOptionsParameter]' = None) -> 'Any'
| Executes a SQL statement construct and returns a scalar object.
|
| This method is shorthand for invoking the
| :meth:`_engine.Result.scalar` method after invoking the
| :meth:`_engine.Connection.execute` method. Parameters are equivalent.
|
| :return: a scalar Python value representing the first column of the
| first row returned.
|
| scalars(self, statement: 'Executable', parameters: 'Optional[_CoreAnyExecuteParams]' = None, *, execution_options: 'Optional[CoreExecuteOptionsParameter]' = None) -> 'ScalarResult[Any]'
| Executes and returns a scalar result set, which yields scalar values
| from the first column of each row.
|
| This method is equivalent to calling :meth:`_engine.Connection.execute`
| to receive a :class:`_result.Result` object, then invoking the
| :meth:`_result.Result.scalars` method to produce a
| :class:`_result.ScalarResult` instance.
|
| :return: a :class:`_result.ScalarResult`
|
| .. versionadded:: 1.4.24
|
| schema_for_object(self, obj: 'HasSchemaAttr') -> 'Optional[str]'
| Return the schema name for the given schema item taking into
| account current schema translate map.
|
| ----------------------------------------------------------------------
| Readonly properties defined here:
|
| closed
| Return True if this connection is closed.
|
| connection
| The underlying DB-API connection managed by this Connection.
|
| This is a SQLAlchemy connection-pool proxied connection
| which then has the attribute
| :attr:`_pool._ConnectionFairy.dbapi_connection` that refers to the
| actual driver connection.
|
| .. seealso::
|
|
| :ref:`dbapi_connections`
|
| default_isolation_level
| The initial-connection time isolation level associated with the
| :class:`_engine.Dialect` in use.
|
| This value is independent of the
| :paramref:`.Connection.execution_options.isolation_level` and
| :paramref:`.Engine.execution_options.isolation_level` execution
| options, and is determined by the :class:`_engine.Dialect` when the
| first connection is created, by performing a SQL query against the
| database for the current isolation level before any additional commands
| have been emitted.
|
| Calling this accessor does not invoke any new SQL queries.
|
| .. seealso::
|
| :meth:`_engine.Connection.get_isolation_level`
| - view current actual isolation level
|
| :paramref:`_sa.create_engine.isolation_level`
| - set per :class:`_engine.Engine` isolation level
|
| :paramref:`.Connection.execution_options.isolation_level`
| - set per :class:`_engine.Connection` isolation level
|
| info
| Info dictionary associated with the underlying DBAPI connection
| referred to by this :class:`_engine.Connection`, allowing user-defined
| data to be associated with the connection.
|
| The data here will follow along with the DBAPI connection including
| after it is returned to the connection pool and used again
| in subsequent instances of :class:`_engine.Connection`.
|
| invalidated
| Return True if this connection was invalidated.
|
| This does not indicate whether or not the connection was
| invalidated at the pool level, however
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'_dbapi_connection': 'Optional[PoolProxiedConnectio...
|
| __orig_bases__ = (<class 'sqlalchemy.engine.interfaces.ConnectionEvent...
|
| __parameters__ = ()
|
| should_close_with_result = False
|
| ----------------------------------------------------------------------
| Data descriptors inherited from sqlalchemy.engine.interfaces.ConnectionEventsTarget:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.engine.interfaces.ConnectionEventsTarget:
|
| dispatch = <sqlalchemy.event.base.ConnectionEventsDispatch object>
|
| ----------------------------------------------------------------------
| Class methods inherited from typing.Generic:
|
| __class_getitem__(...)
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__(...)
| Function to initialize subclasses.
sqlalchemy.Constraint
Python Library Documentation: class Constraint in module sqlalchemy.sql.schema
class Constraint(sqlalchemy.sql.base.DialectKWArgs, HasConditionalDDL, SchemaItem)
| Constraint(name: '_ConstraintNameArgument' = None, deferrable: 'Optional[bool]' = None, initially: 'Optional[str]' = None, info: 'Optional[_InfoType]' = None, comment: 'Optional[str]' = None, _create_rule: 'Optional[Any]' = None, _type_bound: 'bool' = False, **dialect_kw: 'Any') -> 'None'
|
| A table-level SQL constraint.
|
| :class:`_schema.Constraint` serves as the base class for the series of
| constraint objects that can be associated with :class:`_schema.Table`
| objects, including :class:`_schema.PrimaryKeyConstraint`,
| :class:`_schema.ForeignKeyConstraint`
| :class:`_schema.UniqueConstraint`, and
| :class:`_schema.CheckConstraint`.
|
| Method resolution order:
| Constraint
| sqlalchemy.sql.base.DialectKWArgs
| HasConditionalDDL
| SchemaItem
| sqlalchemy.sql.base.SchemaVisitable
| sqlalchemy.sql.base.SchemaEventTarget
| sqlalchemy.event.registry.EventTarget
| sqlalchemy.sql.visitors.Visitable
| builtins.object
|
| Methods defined here:
|
| __init__(self, name: '_ConstraintNameArgument' = None, deferrable: 'Optional[bool]' = None, initially: 'Optional[str]' = None, info: 'Optional[_InfoType]' = None, comment: 'Optional[str]' = None, _create_rule: 'Optional[Any]' = None, _type_bound: 'bool' = False, **dialect_kw: 'Any') -> 'None'
| Create a SQL constraint.
|
| :param name:
| Optional, the in-database name of this ``Constraint``.
|
| :param deferrable:
| Optional bool. If set, emit DEFERRABLE or NOT DEFERRABLE when
| issuing DDL for this constraint.
|
| :param initially:
| Optional string. If set, emit INITIALLY <value> when issuing DDL
| for this constraint.
|
| :param info: Optional data dictionary which will be populated into the
| :attr:`.SchemaItem.info` attribute of this object.
|
| :param comment: Optional string that will render an SQL comment on
| foreign key constraint creation.
|
| .. versionadded:: 2.0
|
| :param \**dialect_kw: Additional keyword arguments are dialect
| specific, and passed in the form ``<dialectname>_<argname>``. See
| the documentation regarding an individual dialect at
| :ref:`dialect_toplevel` for detail on documented arguments.
|
| :param _create_rule:
| used internally by some datatypes that also create constraints.
|
| :param _type_bound:
| used internally to indicate that this constraint is associated with
| a specific datatype.
|
| copy(self, **kw: 'Any') -> 'Self'
| .. deprecated:: 1.4 The :meth:`_schema.Constraint.copy` method is deprecated and will be removed in a future release.
|
| ----------------------------------------------------------------------
| Readonly properties defined here:
|
| table
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'_column_flag': 'bool', '_creation_order': 'int'}
|
| __visit_name__ = 'constraint'
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.base.DialectKWArgs:
|
| dialect_options(...)
| A collection of keyword arguments specified as dialect-specific
| options to this construct.
|
| This is a two-level nested registry, keyed to ``<dialect_name>``
| and ``<argument_name>``. For example, the ``postgresql_where``
| argument would be locatable as::
|
| arg = my_object.dialect_options["postgresql"]["where"]
|
| .. versionadded:: 0.9.2
|
| .. seealso::
|
| :attr:`.DialectKWArgs.dialect_kwargs` - flat dictionary form
|
| get_dialect_option(self, dialect: 'Dialect', argument_name: 'str', *, else_: 'Any' = None, deprecated_fallback: 'Optional[str]' = None) -> 'Any'
| Return the value of a dialect-specific option, or *else_* if
| this dialect does not register the given argument.
|
| This is useful for DDL compilers that may be inherited by
| third-party dialects whose ``construct_arguments`` do not
| include the same set of keys as the parent dialect.
|
| :param dialect: The dialect for which to retrieve the option.
| :param argument_name: The name of the argument to retrieve.
| :param else\_: The value to return if the argument is not present.
| :param deprecated_fallback: Optional dialect name to fall back to
| if the argument is not present for the current dialect. If the
| argument is present for the fallback dialect but not the current
| dialect, a deprecation warning will be emitted.
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.base.DialectKWArgs:
|
| argument_for(dialect_name: 'str', argument_name: 'str', default: 'Any') -> 'None'
| Add a new kind of dialect-specific keyword argument for this class.
|
| E.g.::
|
| Index.argument_for("mydialect", "length", None)
|
| some_index = Index("a", "b", mydialect_length=5)
|
| The :meth:`.DialectKWArgs.argument_for` method is a per-argument
| way adding extra arguments to the
| :attr:`.DefaultDialect.construct_arguments` dictionary. This
| dictionary provides a list of argument names accepted by various
| schema-level constructs on behalf of a dialect.
|
| New dialects should typically specify this dictionary all at once as a
| data member of the dialect class. The use case for ad-hoc addition of
| argument names is typically for end-user code that is also using
| a custom compilation scheme which consumes the additional arguments.
|
| :param dialect_name: name of a dialect. The dialect must be
| locatable, else a :class:`.NoSuchModuleError` is raised. The
| dialect must also include an existing
| :attr:`.DefaultDialect.construct_arguments` collection, indicating
| that it participates in the keyword-argument validation and default
| system, else :class:`.ArgumentError` is raised. If the dialect does
| not include this collection, then any keyword argument can be
| specified on behalf of this dialect already. All dialects packaged
| within SQLAlchemy include this collection, however for third party
| dialects, support may vary.
|
| :param argument_name: name of the parameter.
|
| :param default: default value of the parameter.
|
| ----------------------------------------------------------------------
| Readonly properties inherited from sqlalchemy.sql.base.DialectKWArgs:
|
| dialect_kwargs
| A collection of keyword arguments specified as dialect-specific
| options to this construct.
|
| The arguments are present here in their original ``<dialect>_<kwarg>``
| format. Only arguments that were actually passed are included;
| unlike the :attr:`.DialectKWArgs.dialect_options` collection, which
| contains all options known by this dialect including defaults.
|
| The collection is also writable; keys are accepted of the
| form ``<dialect>_<kwarg>`` where the value will be assembled
| into the list of options.
|
| .. seealso::
|
| :attr:`.DialectKWArgs.dialect_options` - nested dictionary form
|
| kwargs
| A synonym for :attr:`.DialectKWArgs.dialect_kwargs`.
|
| ----------------------------------------------------------------------
| Methods inherited from HasConditionalDDL:
|
| ddl_if(self, dialect: 'Optional[str]' = None, callable_: 'Optional[ddl.DDLIfCallable]' = None, state: 'Optional[Any]' = None) -> 'Self'
| apply a conditional DDL rule to this schema item.
|
| These rules work in a similar manner to the
| :meth:`.ExecutableDDLElement.execute_if` callable, with the added
| feature that the criteria may be checked within the DDL compilation
| phase for a construct such as :class:`.CreateTable`.
| :meth:`.HasConditionalDDL.ddl_if` currently applies towards the
| :class:`.Index` construct as well as all :class:`.Constraint`
| constructs.
|
| :param dialect: string name of a dialect, or a tuple of string names
| to indicate multiple dialect types.
|
| :param callable\_: a callable that is constructed using the same form
| as that described in
| :paramref:`.ExecutableDDLElement.execute_if.callable_`.
|
| :param state: any arbitrary object that will be passed to the
| callable, if present.
|
| .. versionadded:: 2.0
|
| .. seealso::
|
| :ref:`schema_ddl_ddl_if` - background and usage examples
|
| ----------------------------------------------------------------------
| Methods inherited from SchemaItem:
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| info(...)
| Info dictionary associated with the object, allowing user-defined
| data to be associated with this :class:`.SchemaItem`.
|
| The dictionary is automatically generated when first accessed.
| It can also be specified in the constructor of some objects,
| such as :class:`_schema.Table` and :class:`_schema.Column`.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from SchemaItem:
|
| create_drop_stringify_dialect = 'default'
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.base.SchemaEventTarget:
|
| dispatch = <sqlalchemy.event.base.DDLEventsDispatch object>
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.visitors.Visitable:
|
| __class_getitem__(key: 'Any') -> 'Any'
|
| __init_subclass__() -> 'None'
| This method is called when a class is subclassed.
|
| The default implementation does nothing. It may be
| overridden to extend subclasses.
sqlalchemy.CreateEnginePlugin
Python Library Documentation: class CreateEnginePlugin in module sqlalchemy.engine.interfaces
class CreateEnginePlugin(builtins.object)
| CreateEnginePlugin(url: 'URL', kwargs: 'Dict[str, Any]')
|
| A set of hooks intended to augment the construction of an
| :class:`_engine.Engine` object based on entrypoint names in a URL.
|
| The purpose of :class:`_engine.CreateEnginePlugin` is to allow third-party
| systems to apply engine, pool and dialect level event listeners without
| the need for the target application to be modified; instead, the plugin
| names can be added to the database URL. Target applications for
| :class:`_engine.CreateEnginePlugin` include:
|
| * connection and SQL performance tools, e.g. which use events to track
| number of checkouts and/or time spent with statements
|
| * connectivity plugins such as proxies
|
| A rudimentary :class:`_engine.CreateEnginePlugin` that attaches a logger
| to an :class:`_engine.Engine` object might look like::
|
|
| import logging
|
| from sqlalchemy.engine import CreateEnginePlugin
| from sqlalchemy import event
|
|
| class LogCursorEventsPlugin(CreateEnginePlugin):
| def __init__(self, url, kwargs):
| # consume the parameter "log_cursor_logging_name" from the
| # URL query
| logging_name = url.query.get(
| "log_cursor_logging_name", "log_cursor"
| )
|
| self.log = logging.getLogger(logging_name)
|
| def update_url(self, url):
| "update the URL to one that no longer includes our parameters"
| return url.difference_update_query(["log_cursor_logging_name"])
|
| def engine_created(self, engine):
| "attach an event listener after the new Engine is constructed"
| event.listen(engine, "before_cursor_execute", self._log_event)
|
| def _log_event(
| self,
| conn,
| cursor,
| statement,
| parameters,
| context,
| executemany,
| ):
|
| self.log.info("Plugin logged cursor event: %s", statement)
|
| Plugins are registered using entry points in a similar way as that
| of dialects::
|
| entry_points = {
| "sqlalchemy.plugins": [
| "log_cursor_plugin = myapp.plugins:LogCursorEventsPlugin"
| ]
| }
|
| A plugin that uses the above names would be invoked from a database
| URL as in::
|
| from sqlalchemy import create_engine
|
| engine = create_engine(
| "mysql+pymysql://scott:tiger@localhost/test?"
| "plugin=log_cursor_plugin&log_cursor_logging_name=mylogger"
| )
|
| The ``plugin`` URL parameter supports multiple instances, so that a URL
| may specify multiple plugins; they are loaded in the order stated
| in the URL::
|
| engine = create_engine(
| "mysql+pymysql://scott:tiger@localhost/test?"
| "plugin=plugin_one&plugin=plugin_twp&plugin=plugin_three"
| )
|
| The plugin names may also be passed directly to :func:`_sa.create_engine`
| using the :paramref:`_sa.create_engine.plugins` argument::
|
| engine = create_engine(
| "mysql+pymysql://scott:tiger@localhost/test", plugins=["myplugin"]
| )
|
| .. versionadded:: 1.2.3 plugin names can also be specified
| to :func:`_sa.create_engine` as a list
|
| A plugin may consume plugin-specific arguments from the
| :class:`_engine.URL` object as well as the ``kwargs`` dictionary, which is
| the dictionary of arguments passed to the :func:`_sa.create_engine`
| call. "Consuming" these arguments includes that they must be removed
| when the plugin initializes, so that the arguments are not passed along
| to the :class:`_engine.Dialect` constructor, where they will raise an
| :class:`_exc.ArgumentError` because they are not known by the dialect.
|
| As of version 1.4 of SQLAlchemy, arguments should continue to be consumed
| from the ``kwargs`` dictionary directly, by removing the values with a
| method such as ``dict.pop``. Arguments from the :class:`_engine.URL` object
| should be consumed by implementing the
| :meth:`_engine.CreateEnginePlugin.update_url` method, returning a new copy
| of the :class:`_engine.URL` with plugin-specific parameters removed::
|
| class MyPlugin(CreateEnginePlugin):
| def __init__(self, url, kwargs):
| self.my_argument_one = url.query["my_argument_one"]
| self.my_argument_two = url.query["my_argument_two"]
| self.my_argument_three = kwargs.pop("my_argument_three", None)
|
| def update_url(self, url):
| return url.difference_update_query(
| ["my_argument_one", "my_argument_two"]
| )
|
| Arguments like those illustrated above would be consumed from a
| :func:`_sa.create_engine` call such as::
|
| from sqlalchemy import create_engine
|
| engine = create_engine(
| "mysql+pymysql://scott:tiger@localhost/test?"
| "plugin=myplugin&my_argument_one=foo&my_argument_two=bar",
| my_argument_three="bat",
| )
|
| .. versionchanged:: 1.4
|
| The :class:`_engine.URL` object is now immutable; a
| :class:`_engine.CreateEnginePlugin` that needs to alter the
| :class:`_engine.URL` should implement the newly added
| :meth:`_engine.CreateEnginePlugin.update_url` method, which
| is invoked after the plugin is constructed.
|
| For migration, construct the plugin in the following way, checking
| for the existence of the :meth:`_engine.CreateEnginePlugin.update_url`
| method to detect which version is running::
|
| class MyPlugin(CreateEnginePlugin):
| def __init__(self, url, kwargs):
| if hasattr(CreateEnginePlugin, "update_url"):
| # detect the 1.4 API
| self.my_argument_one = url.query["my_argument_one"]
| self.my_argument_two = url.query["my_argument_two"]
| else:
| # detect the 1.3 and earlier API - mutate the
| # URL directly
| self.my_argument_one = url.query.pop("my_argument_one")
| self.my_argument_two = url.query.pop("my_argument_two")
|
| self.my_argument_three = kwargs.pop("my_argument_three", None)
|
| def update_url(self, url):
| # this method is only called in the 1.4 version
| return url.difference_update_query(
| ["my_argument_one", "my_argument_two"]
| )
|
| .. seealso::
|
| :ref:`change_5526` - overview of the :class:`_engine.URL` change which
| also includes notes regarding :class:`_engine.CreateEnginePlugin`.
|
|
| When the engine creation process completes and produces the
| :class:`_engine.Engine` object, it is again passed to the plugin via the
| :meth:`_engine.CreateEnginePlugin.engine_created` hook. In this hook, additional
| changes can be made to the engine, most typically involving setup of
| events (e.g. those defined in :ref:`core_event_toplevel`).
|
| Methods defined here:
|
| __init__(self, url: 'URL', kwargs: 'Dict[str, Any]')
| Construct a new :class:`.CreateEnginePlugin`.
|
| The plugin object is instantiated individually for each call
| to :func:`_sa.create_engine`. A single :class:`_engine.
| Engine` will be
| passed to the :meth:`.CreateEnginePlugin.engine_created` method
| corresponding to this URL.
|
| :param url: the :class:`_engine.URL` object. The plugin may inspect
| the :class:`_engine.URL` for arguments. Arguments used by the
| plugin should be removed, by returning an updated :class:`_engine.URL`
| from the :meth:`_engine.CreateEnginePlugin.update_url` method.
|
| .. versionchanged:: 1.4
|
| The :class:`_engine.URL` object is now immutable, so a
| :class:`_engine.CreateEnginePlugin` that needs to alter the
| :class:`_engine.URL` object should implement the
| :meth:`_engine.CreateEnginePlugin.update_url` method.
|
| :param kwargs: The keyword arguments passed to
| :func:`_sa.create_engine`.
|
| engine_created(self, engine: 'Engine') -> 'None'
| Receive the :class:`_engine.Engine`
| object when it is fully constructed.
|
| The plugin may make additional changes to the engine, such as
| registering engine or connection pool events.
|
| handle_dialect_kwargs(self, dialect_cls: 'Type[Dialect]', dialect_args: 'Dict[str, Any]') -> 'None'
| parse and modify dialect kwargs
|
| handle_pool_kwargs(self, pool_cls: 'Type[Pool]', pool_args: 'Dict[str, Any]') -> 'None'
| parse and modify pool kwargs
|
| update_url(self, url: 'URL') -> 'URL'
| Update the :class:`_engine.URL`.
|
| A new :class:`_engine.URL` should be returned. This method is
| typically used to consume configuration arguments from the
| :class:`_engine.URL` which must be removed, as they will not be
| recognized by the dialect. The
| :meth:`_engine.URL.difference_update_query` method is available
| to remove these arguments. See the docstring at
| :class:`_engine.CreateEnginePlugin` for an example.
|
|
| .. versionadded:: 1.4
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
sqlalchemy.CursorResult
Python Library Documentation: class CursorResult in module sqlalchemy.engine.cursor
class CursorResult(sqlalchemy.engine.result.Result)
| CursorResult(context: 'DefaultExecutionContext', cursor_strategy: 'ResultFetchStrategy', cursor_description: 'Optional[_DBAPICursorDescription]')
|
| A Result that is representing state from a DBAPI cursor.
|
| .. versionchanged:: 1.4 The :class:`.CursorResult``
| class replaces the previous :class:`.ResultProxy` interface.
| This classes are based on the :class:`.Result` calling API
| which provides an updated usage model and calling facade for
| SQLAlchemy Core and SQLAlchemy ORM.
|
| Returns database rows via the :class:`.Row` class, which provides
| additional API features and behaviors on top of the raw data returned by
| the DBAPI. Through the use of filters such as the :meth:`.Result.scalars`
| method, other kinds of objects may also be returned.
|
| .. seealso::
|
| :ref:`tutorial_selecting_data` - introductory material for accessing
| :class:`_engine.CursorResult` and :class:`.Row` objects.
|
| Method resolution order:
| CursorResult
| sqlalchemy.engine.result.Result
| sqlalchemy.engine.result._WithKeys
| sqlalchemy.engine.result.ResultInternal
| sqlalchemy.sql.base.InPlaceGenerative
| sqlalchemy.util.langhelpers.HasMemoized
| typing.Generic
| builtins.object
|
| Methods defined here:
|
| __init__(self, context: 'DefaultExecutionContext', cursor_strategy: 'ResultFetchStrategy', cursor_description: 'Optional[_DBAPICursorDescription]')
| Initialize self. See help(type(self)) for accurate signature.
|
| close(self) -> 'None'
| Close this :class:`_engine.CursorResult`.
|
| This closes out the underlying DBAPI cursor corresponding to the
| statement execution, if one is still present. Note that the DBAPI
| cursor is automatically released when the :class:`_engine.CursorResult`
| exhausts all available rows. :meth:`_engine.CursorResult.close` is
| generally an optional method except in the case when discarding a
| :class:`_engine.CursorResult` that still has additional rows pending
| for fetch.
|
| After this method is called, it is no longer valid to call upon
| the fetch methods, which will raise a :class:`.ResourceClosedError`
| on subsequent use.
|
| .. seealso::
|
| :ref:`connections_toplevel`
|
| last_inserted_params(self) -> 'Union[List[_MutableCoreSingleExecuteParams], _MutableCoreSingleExecuteParams]'
| Return the collection of inserted parameters from this
| execution.
|
| Raises :class:`~sqlalchemy.exc.InvalidRequestError` if the executed
| statement is not a compiled expression construct
| or is not an insert() construct.
|
| last_updated_params(self) -> 'Union[List[_MutableCoreSingleExecuteParams], _MutableCoreSingleExecuteParams]'
| Return the collection of updated parameters from this
| execution.
|
| Raises :class:`~sqlalchemy.exc.InvalidRequestError` if the executed
| statement is not a compiled expression construct
| or is not an update() construct.
|
| lastrow_has_defaults(self) -> 'bool'
| Return ``lastrow_has_defaults()`` from the underlying
| :class:`.ExecutionContext`.
|
| See :class:`.ExecutionContext` for details.
|
| merge(self, *others: 'Result[Any]') -> 'MergedResult[Any]'
| Merge this :class:`_engine.Result` with other compatible result
| objects.
|
| The object returned is an instance of :class:`_engine.MergedResult`,
| which will be composed of iterators from the given result
| objects.
|
| The new result will use the metadata from this result object.
| The subsequent result objects must be against an identical
| set of result / cursor metadata, otherwise the behavior is
| undefined.
|
| postfetch_cols(self) -> 'Optional[Sequence[Column[Any]]]'
| Return ``postfetch_cols()`` from the underlying
| :class:`.ExecutionContext`.
|
| See :class:`.ExecutionContext` for details.
|
| Raises :class:`~sqlalchemy.exc.InvalidRequestError` if the executed
| statement is not a compiled expression construct
| or is not an insert() or update() construct.
|
| prefetch_cols(self) -> 'Optional[Sequence[Column[Any]]]'
| Return ``prefetch_cols()`` from the underlying
| :class:`.ExecutionContext`.
|
| See :class:`.ExecutionContext` for details.
|
| Raises :class:`~sqlalchemy.exc.InvalidRequestError` if the executed
| statement is not a compiled expression construct
| or is not an insert() or update() construct.
|
| rowcount(...)
| Return the 'rowcount' for this result.
|
| The primary purpose of 'rowcount' is to report the number of rows
| matched by the WHERE criterion of an UPDATE or DELETE statement
| executed once (i.e. for a single parameter set), which may then be
| compared to the number of rows expected to be updated or deleted as a
| means of asserting data integrity.
|
| This attribute is transferred from the ``cursor.rowcount`` attribute
| of the DBAPI before the cursor is closed, to support DBAPIs that
| don't make this value available after cursor close. Some DBAPIs may
| offer meaningful values for other kinds of statements, such as INSERT
| and SELECT statements as well. In order to retrieve ``cursor.rowcount``
| for these statements, set the
| :paramref:`.Connection.execution_options.preserve_rowcount`
| execution option to True, which will cause the ``cursor.rowcount``
| value to be unconditionally memoized before any results are returned
| or the cursor is closed, regardless of statement type.
|
| For cases where the DBAPI does not support rowcount for a particular
| kind of statement and/or execution, the returned value will be ``-1``,
| which is delivered directly from the DBAPI and is part of :pep:`249`.
| All DBAPIs should support rowcount for single-parameter-set
| UPDATE and DELETE statements, however.
|
| .. note::
|
| Notes regarding :attr:`_engine.CursorResult.rowcount`:
|
|
| * This attribute returns the number of rows *matched*,
| which is not necessarily the same as the number of rows
| that were actually *modified*. For example, an UPDATE statement
| may have no net change on a given row if the SET values
| given are the same as those present in the row already.
| Such a row would be matched but not modified.
| On backends that feature both styles, such as MySQL,
| rowcount is configured to return the match
| count in all cases.
|
| * :attr:`_engine.CursorResult.rowcount` in the default case is
| *only* useful in conjunction with an UPDATE or DELETE statement,
| and only with a single set of parameters. For other kinds of
| statements, SQLAlchemy will not attempt to pre-memoize the value
| unless the
| :paramref:`.Connection.execution_options.preserve_rowcount`
| execution option is used. Note that contrary to :pep:`249`, many
| DBAPIs do not support rowcount values for statements that are not
| UPDATE or DELETE, particularly when rows are being returned which
| are not fully pre-buffered. DBAPIs that dont support rowcount
| for a particular kind of statement should return the value ``-1``
| for such statements.
|
| * :attr:`_engine.CursorResult.rowcount` may not be meaningful
| when executing a single statement with multiple parameter sets
| (i.e. an :term:`executemany`). Most DBAPIs do not sum "rowcount"
| values across multiple parameter sets and will return ``-1``
| when accessed.
|
| * SQLAlchemy's :ref:`engine_insertmanyvalues` feature does support
| a correct population of :attr:`_engine.CursorResult.rowcount`
| when the :paramref:`.Connection.execution_options.preserve_rowcount`
| execution option is set to True.
|
| * Statements that use RETURNING may not support rowcount, returning
| a ``-1`` value instead.
|
| .. seealso::
|
| :ref:`tutorial_update_delete_rowcount` - in the :ref:`unified_tutorial`
|
| :paramref:`.Connection.execution_options.preserve_rowcount`
|
| splice_horizontally(self, other: 'CursorResult[Any]') -> 'Self'
| Return a new :class:`.CursorResult` that "horizontally splices"
| together the rows of this :class:`.CursorResult` with that of another
| :class:`.CursorResult`.
|
| .. tip:: This method is for the benefit of the SQLAlchemy ORM and is
| not intended for general use.
|
| "horizontally splices" means that for each row in the first and second
| result sets, a new row that concatenates the two rows together is
| produced, which then becomes the new row. The incoming
| :class:`.CursorResult` must have the identical number of rows. It is
| typically expected that the two result sets come from the same sort
| order as well, as the result rows are spliced together based on their
| position in the result.
|
| The expected use case here is so that multiple INSERT..RETURNING
| statements (which definitely need to be sorted) against different
| tables can produce a single result that looks like a JOIN of those two
| tables.
|
| E.g.::
|
| r1 = connection.execute(
| users.insert().returning(
| users.c.user_name, users.c.user_id, sort_by_parameter_order=True
| ),
| user_values,
| )
|
| r2 = connection.execute(
| addresses.insert().returning(
| addresses.c.address_id,
| addresses.c.address,
| addresses.c.user_id,
| sort_by_parameter_order=True,
| ),
| address_values,
| )
|
| rows = r1.splice_horizontally(r2).all()
| assert rows == [
| ("john", 1, 1, "foo@bar.com", 1),
| ("jack", 2, 2, "bar@bat.com", 2),
| ]
|
| .. versionadded:: 2.0
|
| .. seealso::
|
| :meth:`.CursorResult.splice_vertically`
|
| splice_vertically(self, other: 'CursorResult[Any]') -> 'Self'
| Return a new :class:`.CursorResult` that "vertically splices",
| i.e. "extends", the rows of this :class:`.CursorResult` with that of
| another :class:`.CursorResult`.
|
| .. tip:: This method is for the benefit of the SQLAlchemy ORM and is
| not intended for general use.
|
| "vertically splices" means the rows of the given result are appended to
| the rows of this cursor result. The incoming :class:`.CursorResult`
| must have rows that represent the identical list of columns in the
| identical order as they are in this :class:`.CursorResult`.
|
| .. versionadded:: 2.0
|
| .. seealso::
|
| :meth:`.CursorResult.splice_horizontally`
|
| supports_sane_multi_rowcount(self) -> 'bool'
| Return ``supports_sane_multi_rowcount`` from the dialect.
|
| See :attr:`_engine.CursorResult.rowcount` for background.
|
| supports_sane_rowcount(self) -> 'bool'
| Return ``supports_sane_rowcount`` from the dialect.
|
| See :attr:`_engine.CursorResult.rowcount` for background.
|
| yield_per(self, num: 'int') -> 'Self'
| Configure the row-fetching strategy to fetch ``num`` rows at a time.
|
| This impacts the underlying behavior of the result when iterating over
| the result object, or otherwise making use of methods such as
| :meth:`_engine.Result.fetchone` that return one row at a time. Data
| from the underlying cursor or other data source will be buffered up to
| this many rows in memory, and the buffered collection will then be
| yielded out one row at a time or as many rows are requested. Each time
| the buffer clears, it will be refreshed to this many rows or as many
| rows remain if fewer remain.
|
| The :meth:`_engine.Result.yield_per` method is generally used in
| conjunction with the
| :paramref:`_engine.Connection.execution_options.stream_results`
| execution option, which will allow the database dialect in use to make
| use of a server side cursor, if the DBAPI supports a specific "server
| side cursor" mode separate from its default mode of operation.
|
| .. tip::
|
| Consider using the
| :paramref:`_engine.Connection.execution_options.yield_per`
| execution option, which will simultaneously set
| :paramref:`_engine.Connection.execution_options.stream_results`
| to ensure the use of server side cursors, as well as automatically
| invoke the :meth:`_engine.Result.yield_per` method to establish
| a fixed row buffer size at once.
|
| The :paramref:`_engine.Connection.execution_options.yield_per`
| execution option is available for ORM operations, with
| :class:`_orm.Session`-oriented use described at
| :ref:`orm_queryguide_yield_per`. The Core-only version which works
| with :class:`_engine.Connection` is new as of SQLAlchemy 1.4.40.
|
| .. versionadded:: 1.4
|
| :param num: number of rows to fetch each time the buffer is refilled.
| If set to a value below 1, fetches all rows for the next buffer.
|
| .. seealso::
|
| :ref:`engine_stream_results` - describes Core behavior for
| :meth:`_engine.Result.yield_per`
|
| :ref:`orm_queryguide_yield_per` - in the :ref:`queryguide_toplevel`
|
| ----------------------------------------------------------------------
| Readonly properties defined here:
|
| inserted_primary_key
| Return the primary key for the row just inserted.
|
| The return value is a :class:`_result.Row` object representing
| a named tuple of primary key values in the order in which the
| primary key columns are configured in the source
| :class:`_schema.Table`.
|
| .. versionchanged:: 1.4.8 - the
| :attr:`_engine.CursorResult.inserted_primary_key`
| value is now a named tuple via the :class:`_result.Row` class,
| rather than a plain tuple.
|
| This accessor only applies to single row :func:`_expression.insert`
| constructs which did not explicitly specify
| :meth:`_expression.Insert.returning`. Support for multirow inserts,
| while not yet available for most backends, would be accessed using
| the :attr:`_engine.CursorResult.inserted_primary_key_rows` accessor.
|
| Note that primary key columns which specify a server_default clause, or
| otherwise do not qualify as "autoincrement" columns (see the notes at
| :class:`_schema.Column`), and were generated using the database-side
| default, will appear in this list as ``None`` unless the backend
| supports "returning" and the insert statement executed with the
| "implicit returning" enabled.
|
| Raises :class:`~sqlalchemy.exc.InvalidRequestError` if the executed
| statement is not a compiled expression construct
| or is not an insert() construct.
|
| inserted_primary_key_rows
| Return the value of
| :attr:`_engine.CursorResult.inserted_primary_key`
| as a row contained within a list; some dialects may support a
| multiple row form as well.
|
| .. note:: As indicated below, in current SQLAlchemy versions this
| accessor is only useful beyond what's already supplied by
| :attr:`_engine.CursorResult.inserted_primary_key` when using the
| :ref:`postgresql_psycopg2` dialect. Future versions hope to
| generalize this feature to more dialects.
|
| This accessor is added to support dialects that offer the feature
| that is currently implemented by the :ref:`psycopg2_executemany_mode`
| feature, currently **only the psycopg2 dialect**, which provides
| for many rows to be INSERTed at once while still retaining the
| behavior of being able to return server-generated primary key values.
|
| * **When using the psycopg2 dialect, or other dialects that may support
| "fast executemany" style inserts in upcoming releases** : When
| invoking an INSERT statement while passing a list of rows as the
| second argument to :meth:`_engine.Connection.execute`, this accessor
| will then provide a list of rows, where each row contains the primary
| key value for each row that was INSERTed.
|
| * **When using all other dialects / backends that don't yet support
| this feature**: This accessor is only useful for **single row INSERT
| statements**, and returns the same information as that of the
| :attr:`_engine.CursorResult.inserted_primary_key` within a
| single-element list. When an INSERT statement is executed in
| conjunction with a list of rows to be INSERTed, the list will contain
| one row per row inserted in the statement, however it will contain
| ``None`` for any server-generated values.
|
| Future releases of SQLAlchemy will further generalize the
| "fast execution helper" feature of psycopg2 to suit other dialects,
| thus allowing this accessor to be of more general use.
|
| .. versionadded:: 1.4
|
| .. seealso::
|
| :attr:`_engine.CursorResult.inserted_primary_key`
|
| is_insert
| True if this :class:`_engine.CursorResult` is the result
| of a executing an expression language compiled
| :func:`_expression.insert` construct.
|
| When True, this implies that the
| :attr:`inserted_primary_key` attribute is accessible,
| assuming the statement did not include
| a user defined "returning" construct.
|
| lastrowid
| Return the 'lastrowid' accessor on the DBAPI cursor.
|
| This is a DBAPI specific method and is only functional
| for those backends which support it, for statements
| where it is appropriate. It's behavior is not
| consistent across backends.
|
| Usage of this method is normally unnecessary when
| using insert() expression constructs; the
| :attr:`~CursorResult.inserted_primary_key` attribute provides a
| tuple of primary key values for a newly inserted row,
| regardless of database backend.
|
| returned_defaults
| Return the values of default columns that were fetched using
| the :meth:`.ValuesBase.return_defaults` feature.
|
| The value is an instance of :class:`.Row`, or ``None``
| if :meth:`.ValuesBase.return_defaults` was not used or if the
| backend does not support RETURNING.
|
| .. seealso::
|
| :meth:`.ValuesBase.return_defaults`
|
| returned_defaults_rows
| Return a list of rows each containing the values of default
| columns that were fetched using
| the :meth:`.ValuesBase.return_defaults` feature.
|
| The return value is a list of :class:`.Row` objects.
|
| .. versionadded:: 1.4
|
| returns_rows
| True if this :class:`_engine.CursorResult` returns zero or more
| rows.
|
| I.e. if it is legal to call the methods
| :meth:`_engine.CursorResult.fetchone`,
| :meth:`_engine.CursorResult.fetchmany`
| :meth:`_engine.CursorResult.fetchall`.
|
| Overall, the value of :attr:`_engine.CursorResult.returns_rows` should
| always be synonymous with whether or not the DBAPI cursor had a
| ``.description`` attribute, indicating the presence of result columns,
| noting that a cursor that returns zero rows still has a
| ``.description`` if a row-returning statement was emitted.
|
| This attribute should be True for all results that are against
| SELECT statements, as well as for DML statements INSERT/UPDATE/DELETE
| that use RETURNING. For INSERT/UPDATE/DELETE statements that were
| not using RETURNING, the value will usually be False, however
| there are some dialect-specific exceptions to this, such as when
| using the MSSQL / pyodbc dialect a SELECT is emitted inline in
| order to retrieve an inserted primary key value.
|
| .. seealso::
|
| :meth:`.Result.close`
|
| :attr:`.Result.closed`
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| connection
|
| context
|
| cursor
|
| cursor_strategy
|
| dialect
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'_metadata': 'Union[CursorResultMetaData, _NoResult...
|
| __orig_bases__ = (sqlalchemy.engine.result.Result[~_T],)
|
| __parameters__ = (~_T,)
|
| closed = False
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.engine.result.Result:
|
| __enter__(self) -> 'Self'
|
| __exit__(self, type_: 'Any', value: 'Any', traceback: 'Any') -> 'None'
|
| __iter__(self) -> 'Iterator[Row[_TP]]'
|
| __next__(self) -> 'Row[_TP]'
|
| all(self) -> 'Sequence[Row[_TP]]'
| Return all rows in a sequence.
|
| Closes the result set after invocation. Subsequent invocations
| will return an empty sequence.
|
| .. versionadded:: 1.4
|
| :return: a sequence of :class:`_engine.Row` objects.
|
| .. seealso::
|
| :ref:`engine_stream_results` - How to stream a large result set
| without loading it completely in python.
|
| columns(self, *col_expressions: '_KeyIndexType') -> 'Self'
| Establish the columns that should be returned in each row.
|
| This method may be used to limit the columns returned as well
| as to reorder them. The given list of expressions are normally
| a series of integers or string key names. They may also be
| appropriate :class:`.ColumnElement` objects which correspond to
| a given statement construct.
|
| .. versionchanged:: 2.0 Due to a bug in 1.4, the
| :meth:`_engine.Result.columns` method had an incorrect behavior
| where calling upon the method with just one index would cause the
| :class:`_engine.Result` object to yield scalar values rather than
| :class:`_engine.Row` objects. In version 2.0, this behavior
| has been corrected such that calling upon
| :meth:`_engine.Result.columns` with a single index will
| produce a :class:`_engine.Result` object that continues
| to yield :class:`_engine.Row` objects, which include
| only a single column.
|
| E.g.::
|
| statement = select(table.c.x, table.c.y, table.c.z)
| result = connection.execute(statement)
|
| for z, y in result.columns("z", "y"):
| ...
|
| Example of using the column objects from the statement itself::
|
| for z, y in result.columns(
| statement.selected_columns.c.z, statement.selected_columns.c.y
| ):
| ...
|
| .. versionadded:: 1.4
|
| :param \*col_expressions: indicates columns to be returned. Elements
| may be integer row indexes, string column names, or appropriate
| :class:`.ColumnElement` objects corresponding to a select construct.
|
| :return: this :class:`_engine.Result` object with the modifications
| given.
|
| fetchall(self) -> 'Sequence[Row[_TP]]'
| A synonym for the :meth:`_engine.Result.all` method.
|
| fetchmany(self, size: 'Optional[int]' = None) -> 'Sequence[Row[_TP]]'
| Fetch many rows.
|
| When all rows are exhausted, returns an empty sequence.
|
| This method is provided for backwards compatibility with
| SQLAlchemy 1.x.x.
|
| To fetch rows in groups, use the :meth:`_engine.Result.partitions`
| method.
|
| :return: a sequence of :class:`_engine.Row` objects.
|
| .. seealso::
|
| :meth:`_engine.Result.partitions`
|
| fetchone(self) -> 'Optional[Row[_TP]]'
| Fetch one row.
|
| When all rows are exhausted, returns None.
|
| This method is provided for backwards compatibility with
| SQLAlchemy 1.x.x.
|
| To fetch the first row of a result only, use the
| :meth:`_engine.Result.first` method. To iterate through all
| rows, iterate the :class:`_engine.Result` object directly.
|
| :return: a :class:`_engine.Row` object if no filters are applied,
| or ``None`` if no rows remain.
|
| first(self) -> 'Optional[Row[_TP]]'
| Fetch the first row or ``None`` if no row is present.
|
| Closes the result set and discards remaining rows.
|
| .. note:: This method returns one **row**, e.g. tuple, by default.
| To return exactly one single scalar value, that is, the first
| column of the first row, use the
| :meth:`_engine.Result.scalar` method,
| or combine :meth:`_engine.Result.scalars` and
| :meth:`_engine.Result.first`.
|
| Additionally, in contrast to the behavior of the legacy ORM
| :meth:`_orm.Query.first` method, **no limit is applied** to the
| SQL query which was invoked to produce this
| :class:`_engine.Result`;
| for a DBAPI driver that buffers results in memory before yielding
| rows, all rows will be sent to the Python process and all but
| the first row will be discarded.
|
| .. seealso::
|
| :ref:`migration_20_unify_select`
|
| :return: a :class:`_engine.Row` object, or None
| if no rows remain.
|
| .. seealso::
|
| :meth:`_engine.Result.scalar`
|
| :meth:`_engine.Result.one`
|
| freeze(self) -> 'FrozenResult[_TP]'
| Return a callable object that will produce copies of this
| :class:`_engine.Result` when invoked.
|
| The callable object returned is an instance of
| :class:`_engine.FrozenResult`.
|
| This is used for result set caching. The method must be called
| on the result when it has been unconsumed, and calling the method
| will consume the result fully. When the :class:`_engine.FrozenResult`
| is retrieved from a cache, it can be called any number of times where
| it will produce a new :class:`_engine.Result` object each time
| against its stored set of rows.
|
| .. seealso::
|
| :ref:`do_orm_execute_re_executing` - example usage within the
| ORM to implement a result-set cache.
|
| mappings(self) -> 'MappingResult'
| Apply a mappings filter to returned rows, returning an instance of
| :class:`_engine.MappingResult`.
|
| When this filter is applied, fetching rows will return
| :class:`_engine.RowMapping` objects instead of :class:`_engine.Row`
| objects.
|
| .. versionadded:: 1.4
|
| :return: a new :class:`_engine.MappingResult` filtering object
| referring to this :class:`_engine.Result` object.
|
| one(self) -> 'Row[_TP]'
| Return exactly one row or raise an exception.
|
| Raises :class:`_exc.NoResultFound` if the result returns no
| rows, or :class:`_exc.MultipleResultsFound` if multiple rows
| would be returned.
|
| .. note:: This method returns one **row**, e.g. tuple, by default.
| To return exactly one single scalar value, that is, the first
| column of the first row, use the
| :meth:`_engine.Result.scalar_one` method, or combine
| :meth:`_engine.Result.scalars` and
| :meth:`_engine.Result.one`.
|
| .. versionadded:: 1.4
|
| :return: The first :class:`_engine.Row`.
|
| :raises: :class:`.MultipleResultsFound`, :class:`.NoResultFound`
|
| .. seealso::
|
| :meth:`_engine.Result.first`
|
| :meth:`_engine.Result.one_or_none`
|
| :meth:`_engine.Result.scalar_one`
|
| one_or_none(self) -> 'Optional[Row[_TP]]'
| Return at most one result or raise an exception.
|
| Returns ``None`` if the result has no rows.
| Raises :class:`.MultipleResultsFound`
| if multiple rows are returned.
|
| .. versionadded:: 1.4
|
| :return: The first :class:`_engine.Row` or ``None`` if no row
| is available.
|
| :raises: :class:`.MultipleResultsFound`
|
| .. seealso::
|
| :meth:`_engine.Result.first`
|
| :meth:`_engine.Result.one`
|
| partitions(self, size: 'Optional[int]' = None) -> 'Iterator[Sequence[Row[_TP]]]'
| Iterate through sub-lists of rows of the size given.
|
| Each list will be of the size given, excluding the last list to
| be yielded, which may have a small number of rows. No empty
| lists will be yielded.
|
| The result object is automatically closed when the iterator
| is fully consumed.
|
| Note that the backend driver will usually buffer the entire result
| ahead of time unless the
| :paramref:`.Connection.execution_options.stream_results` execution
| option is used indicating that the driver should not pre-buffer
| results, if possible. Not all drivers support this option and
| the option is silently ignored for those who do not.
|
| When using the ORM, the :meth:`_engine.Result.partitions` method
| is typically more effective from a memory perspective when it is
| combined with use of the
| :ref:`yield_per execution option <orm_queryguide_yield_per>`,
| which instructs both the DBAPI driver to use server side cursors,
| if available, as well as instructs the ORM loading internals to only
| build a certain amount of ORM objects from a result at a time before
| yielding them out.
|
| .. versionadded:: 1.4
|
| :param size: indicate the maximum number of rows to be present
| in each list yielded. If None, makes use of the value set by
| the :meth:`_engine.Result.yield_per`, method, if it were called,
| or the :paramref:`_engine.Connection.execution_options.yield_per`
| execution option, which is equivalent in this regard. If
| yield_per weren't set, it makes use of the
| :meth:`_engine.Result.fetchmany` default, which may be backend
| specific and not well defined.
|
| :return: iterator of lists
|
| .. seealso::
|
| :ref:`engine_stream_results`
|
| :ref:`orm_queryguide_yield_per` - in the :ref:`queryguide_toplevel`
|
| scalar(self) -> 'Any'
| Fetch the first column of the first row, and close the result set.
|
| Returns ``None`` if there are no rows to fetch.
|
| No validation is performed to test if additional rows remain.
|
| After calling this method, the object is fully closed,
| e.g. the :meth:`_engine.CursorResult.close`
| method will have been called.
|
| :return: a Python scalar value, or ``None`` if no rows remain.
|
| scalar_one(self) -> 'Any'
| Return exactly one scalar result or raise an exception.
|
| This is equivalent to calling :meth:`_engine.Result.scalars` and
| then :meth:`_engine.ScalarResult.one`.
|
| .. seealso::
|
| :meth:`_engine.ScalarResult.one`
|
| :meth:`_engine.Result.scalars`
|
| scalar_one_or_none(self) -> 'Optional[Any]'
| Return exactly one scalar result or ``None``.
|
| This is equivalent to calling :meth:`_engine.Result.scalars` and
| then :meth:`_engine.ScalarResult.one_or_none`.
|
| .. seealso::
|
| :meth:`_engine.ScalarResult.one_or_none`
|
| :meth:`_engine.Result.scalars`
|
| scalars(self, index: '_KeyIndexType' = 0) -> 'ScalarResult[Any]'
| Return a :class:`_engine.ScalarResult` filtering object which
| will return single elements rather than :class:`_row.Row` objects.
|
| E.g.::
|
| >>> result = conn.execute(text("select int_id from table"))
| >>> result.scalars().all()
| [1, 2, 3]
|
| When results are fetched from the :class:`_engine.ScalarResult`
| filtering object, the single column-row that would be returned by the
| :class:`_engine.Result` is instead returned as the column's value.
|
| .. versionadded:: 1.4
|
| :param index: integer or row key indicating the column to be fetched
| from each row, defaults to ``0`` indicating the first column.
|
| :return: a new :class:`_engine.ScalarResult` filtering object referring
| to this :class:`_engine.Result` object.
|
| tuples(self) -> 'TupleResult[_TP]'
| Apply a "typed tuple" typing filter to returned rows.
|
| This method returns the same :class:`_engine.Result` object
| at runtime,
| however annotates as returning a :class:`_engine.TupleResult` object
| that will indicate to :pep:`484` typing tools that plain typed
| ``Tuple`` instances are returned rather than rows. This allows
| tuple unpacking and ``__getitem__`` access of :class:`_engine.Row`
| objects to by typed, for those cases where the statement invoked
| itself included typing information.
|
| .. versionadded:: 2.0
|
| :return: the :class:`_engine.TupleResult` type at typing time.
|
| .. seealso::
|
| :attr:`_engine.Result.t` - shorter synonym
|
| :attr:`_engine.Row._t` - :class:`_engine.Row` version
|
| unique(self, strategy: 'Optional[_UniqueFilterType]' = None) -> 'Self'
| Apply unique filtering to the objects returned by this
| :class:`_engine.Result`.
|
| When this filter is applied with no arguments, the rows or objects
| returned will filtered such that each row is returned uniquely. The
| algorithm used to determine this uniqueness is by default the Python
| hashing identity of the whole tuple. In some cases a specialized
| per-entity hashing scheme may be used, such as when using the ORM, a
| scheme is applied which works against the primary key identity of
| returned objects.
|
| The unique filter is applied **after all other filters**, which means
| if the columns returned have been refined using a method such as the
| :meth:`_engine.Result.columns` or :meth:`_engine.Result.scalars`
| method, the uniquing is applied to **only the column or columns
| returned**. This occurs regardless of the order in which these
| methods have been called upon the :class:`_engine.Result` object.
|
| The unique filter also changes the calculus used for methods like
| :meth:`_engine.Result.fetchmany` and :meth:`_engine.Result.partitions`.
| When using :meth:`_engine.Result.unique`, these methods will continue
| to yield the number of rows or objects requested, after uniquing
| has been applied. However, this necessarily impacts the buffering
| behavior of the underlying cursor or datasource, such that multiple
| underlying calls to ``cursor.fetchmany()`` may be necessary in order
| to accumulate enough objects in order to provide a unique collection
| of the requested size.
|
| :param strategy: a callable that will be applied to rows or objects
| being iterated, which should return an object that represents the
| unique value of the row. A Python ``set()`` is used to store
| these identities. If not passed, a default uniqueness strategy
| is used which may have been assembled by the source of this
| :class:`_engine.Result` object.
|
| ----------------------------------------------------------------------
| Readonly properties inherited from sqlalchemy.engine.result.Result:
|
| t
| Apply a "typed tuple" typing filter to returned rows.
|
| The :attr:`_engine.Result.t` attribute is a synonym for
| calling the :meth:`_engine.Result.tuples` method.
|
| .. versionadded:: 2.0
|
| ----------------------------------------------------------------------
| Data descriptors inherited from sqlalchemy.engine.result.Result:
|
| __dict__
| dictionary for instance variables
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.engine.result._WithKeys:
|
| keys(self) -> 'RMKeyView'
| Return an iterable view which yields the string keys that would
| be represented by each :class:`_engine.Row`.
|
| The keys can represent the labels of the columns returned by a core
| statement or the names of the orm classes returned by an orm
| execution.
|
| The view also can be tested for key containment using the Python
| ``in`` operator, which will test both for the string keys represented
| in the view, as well as for alternate keys such as column objects.
|
| .. versionchanged:: 1.4 a key view object is returned rather than a
| plain list.
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_instancemethod(fn: '_F') -> '_F'
| Decorate a method memoize its return value.
|
| :meta private:
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_attribute = <class 'sqlalchemy.util.langhelpers.HasMemoized.m...
| A read-only @property that is only evaluated once.
|
| :meta private:
|
|
| ----------------------------------------------------------------------
| Class methods inherited from typing.Generic:
|
| __class_getitem__(...)
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__(...)
| Function to initialize subclasses.
sqlalchemy.DATE
Python Library Documentation: class DATE in module sqlalchemy.sql.sqltypes
class DATE(Date)
| The SQL DATE type.
|
| Method resolution order:
| DATE
| Date
| _RenderISO8601NoT
| HasExpressionLookup
| sqlalchemy.sql.type_api.TypeEngineMixin
| sqlalchemy.sql.type_api.TypeEngine
| sqlalchemy.sql.visitors.Visitable
| typing.Generic
| builtins.object
|
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| __parameters__ = ()
|
| __visit_name__ = 'DATE'
|
| ----------------------------------------------------------------------
| Methods inherited from Date:
|
| get_dbapi_type(self, dbapi)
| Return the corresponding type object from the underlying DB-API, if
| any.
|
| This can be useful for calling ``setinputsizes()``, for example.
|
| literal_processor(self, dialect)
| Return a conversion function for processing literal values that are
| to be rendered directly without using binds.
|
| This function is used when the compiler makes use of the
| "literal_binds" flag, typically used in DDL generation as well
| as in certain scenarios where backends don't accept bound parameters.
|
| Returns a callable which will receive a literal Python value
| as the sole positional argument and will return a string representation
| to be rendered in a SQL statement.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.literal_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.literal_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_literal_param`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| ----------------------------------------------------------------------
| Readonly properties inherited from Date:
|
| python_type
| Return the Python type object expected to be returned
| by instances of this type, if known.
|
| Basically, for those types which enforce a return type,
| or are known across the board to do such for all common
| DBAPIs (like ``int`` for example), will return that type.
|
| If a return type is not defined, raises
| ``NotImplementedError``.
|
| Note that any type also accommodates NULL in SQL which
| means you can also get back ``None`` from any type
| in practice.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from _RenderISO8601NoT:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from HasExpressionLookup:
|
| Comparator = <class 'sqlalchemy.sql.sqltypes.HasExpressionLookup.Compa...
|
| comparator_factory = <class 'sqlalchemy.sql.sqltypes.HasExpressionLook...
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.type_api.TypeEngine:
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| __str__(self) -> 'str'
| Return str(self).
|
| adapt(self, cls: 'Type[Union[TypeEngine[Any], TypeEngineMixin]]', **kw: 'Any') -> 'TypeEngine[Any]'
| Produce an "adapted" form of this type, given an "impl" class
| to work with.
|
| This method is used internally to associate generic
| types with "implementation" types that are specific to a particular
| dialect.
|
| as_generic(self, allow_nulltype: 'bool' = False) -> 'TypeEngine[_T]'
| Return an instance of the generic type corresponding to this type
| using heuristic rule. The method may be overridden if this
| heuristic rule is not sufficient.
|
| >>> from sqlalchemy.dialects.mysql import INTEGER
| >>> INTEGER(display_width=4).as_generic()
| Integer()
|
| >>> from sqlalchemy.dialects.mysql import NVARCHAR
| >>> NVARCHAR(length=100).as_generic()
| Unicode(length=100)
|
| .. versionadded:: 1.4.0b2
|
|
| .. seealso::
|
| :ref:`metadata_reflection_dbagnostic_types` - describes the
| use of :meth:`_types.TypeEngine.as_generic` in conjunction with
| the :meth:`_sql.DDLEvents.column_reflect` event, which is its
| intended use.
|
| bind_expression(self, bindvalue: 'BindParameter[_T]') -> 'Optional[ColumnElement[_T]]'
| Given a bind value (i.e. a :class:`.BindParameter` instance),
| return a SQL expression in its place.
|
| This is typically a SQL function that wraps the existing bound
| parameter within the statement. It is used for special data types
| that require literals being wrapped in some special database function
| in order to coerce an application-level value into a database-specific
| format. It is the SQL analogue of the
| :meth:`.TypeEngine.bind_processor` method.
|
| This method is called during the **SQL compilation** phase of a
| statement, when rendering a SQL string. It is **not** called
| against specific values.
|
| Note that this method, when implemented, should always return
| the exact same structure, without any conditional logic, as it
| may be used in an executemany() call against an arbitrary number
| of bound parameter sets.
|
| .. note::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.bind_expression`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.bind_expression`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.bind_expression`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| .. seealso::
|
| :ref:`types_sql_value_processing`
|
| bind_processor(self, dialect: 'Dialect') -> 'Optional[_BindProcessorType[_T]]'
| Return a conversion function for processing bind values.
|
| Returns a callable which will receive a bind parameter value
| as the sole positional argument and will return a value to
| send to the DB-API.
|
| If processing is not necessary, the method should return ``None``.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.bind_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.bind_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_bind_param`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
|
| :param dialect: Dialect instance in use.
|
| coerce_compared_value(self, op: 'Optional[OperatorType]', value: 'Any') -> 'TypeEngine[Any]'
| Suggest a type for a 'coerced' Python value in an expression.
|
| Given an operator and value, gives the type a chance
| to return a type which the value should be coerced into.
|
| The default behavior here is conservative; if the right-hand
| side is already coerced into a SQL type based on its
| Python type, it is usually left alone.
|
| End-user functionality extension here should generally be via
| :class:`.TypeDecorator`, which provides more liberal behavior in that
| it defaults to coercing the other side of the expression into this
| type, thus applying special Python conversions above and beyond those
| needed by the DBAPI to both ides. It also provides the public method
| :meth:`.TypeDecorator.coerce_compared_value` which is intended for
| end-user customization of this behavior.
|
| column_expression(self, colexpr: 'ColumnElement[_T]') -> 'Optional[ColumnElement[_T]]'
| Given a SELECT column expression, return a wrapping SQL expression.
|
| This is typically a SQL function that wraps a column expression
| as rendered in the columns clause of a SELECT statement.
| It is used for special data types that require
| columns to be wrapped in some special database function in order
| to coerce the value before being sent back to the application.
| It is the SQL analogue of the :meth:`.TypeEngine.result_processor`
| method.
|
| .. note:: The :func:`.TypeEngine.column_expression` method is applied
| only to the **outermost columns clause** of a SELECT statement, that
| is, the columns that are to be delivered directly into the returned
| result rows. It does **not** apply to the columns clause inside
| of subqueries. This necessarily avoids double conversions against
| the column and only runs the conversion when ready to be returned
| to the client.
|
| This method is called during the **SQL compilation** phase of a
| statement, when rendering a SQL string. It is **not** called
| against specific values.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.column_expression`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.column_expression`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.column_expression`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
|
| .. seealso::
|
| :ref:`types_sql_value_processing`
|
| compare_values(self, x: 'Any', y: 'Any') -> 'bool'
| Compare two values for equality.
|
| compile(self, dialect: 'Optional[Dialect]' = None) -> 'str'
| Produce a string-compiled form of this :class:`.TypeEngine`.
|
| When called with no arguments, uses a "default" dialect
| to produce a string result.
|
| :param dialect: a :class:`.Dialect` instance.
|
| copy(self, **kw: 'Any') -> 'Self'
|
| copy_value(self, value: 'Any') -> 'Any'
|
| dialect_impl(self, dialect: 'Dialect') -> 'TypeEngine[_T]'
| Return a dialect-specific implementation for this
| :class:`.TypeEngine`.
|
| evaluates_none(self) -> 'Self'
| Return a copy of this type which has the
| :attr:`.should_evaluate_none` flag set to True.
|
| E.g.::
|
| Table(
| "some_table",
| metadata,
| Column(
| String(50).evaluates_none(),
| nullable=True,
| server_default="no value",
| ),
| )
|
| The ORM uses this flag to indicate that a positive value of ``None``
| is passed to the column in an INSERT statement, rather than omitting
| the column from the INSERT statement which has the effect of firing
| off column-level defaults. It also allows for types which have
| special behavior associated with the Python None value to indicate
| that the value doesn't necessarily translate into SQL NULL; a
| prime example of this is a JSON type which may wish to persist the
| JSON value ``'null'``.
|
| In all cases, the actual NULL SQL value can be always be
| persisted in any column by using
| the :obj:`_expression.null` SQL construct in an INSERT statement
| or associated with an ORM-mapped attribute.
|
| .. note::
|
| The "evaluates none" flag does **not** apply to a value
| of ``None`` passed to :paramref:`_schema.Column.default` or
| :paramref:`_schema.Column.server_default`; in these cases,
| ``None``
| still means "no default".
|
| .. seealso::
|
| :ref:`session_forcing_null` - in the ORM documentation
|
| :paramref:`.postgresql.JSON.none_as_null` - PostgreSQL JSON
| interaction with this flag.
|
| :attr:`.TypeEngine.should_evaluate_none` - class-level flag
|
| result_processor(self, dialect: 'Dialect', coltype: 'object') -> 'Optional[_ResultProcessorType[_T]]'
| Return a conversion function for processing result row values.
|
| Returns a callable which will receive a result row column
| value as the sole positional argument and will return a value
| to return to the user.
|
| If processing is not necessary, the method should return ``None``.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.result_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.result_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_result_value`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| :param dialect: Dialect instance in use.
|
| :param coltype: DBAPI coltype argument received in cursor.description.
|
| with_variant(self, type_: '_TypeEngineArgument[Any]', *dialect_names: 'str') -> 'Self'
| Produce a copy of this type object that will utilize the given
| type when applied to the dialect of the given name.
|
| e.g.::
|
| from sqlalchemy.types import String
| from sqlalchemy.dialects import mysql
|
| string_type = String()
|
| string_type = string_type.with_variant(
| mysql.VARCHAR(collation="foo"), "mysql", "mariadb"
| )
|
| The variant mapping indicates that when this type is
| interpreted by a specific dialect, it will instead be
| transmuted into the given type, rather than using the
| primary type.
|
| .. versionchanged:: 2.0 the :meth:`_types.TypeEngine.with_variant`
| method now works with a :class:`_types.TypeEngine` object "in
| place", returning a copy of the original type rather than returning
| a wrapping object; the ``Variant`` class is no longer used.
|
| :param type\_: a :class:`.TypeEngine` that will be selected
| as a variant from the originating type, when a dialect
| of the given name is in use.
| :param \*dialect_names: one or more base names of the dialect which
| uses this type. (i.e. ``'postgresql'``, ``'mysql'``, etc.)
|
| .. versionchanged:: 2.0 multiple dialect names can be specified
| for one variant.
|
| .. seealso::
|
| :ref:`types_with_variant` - illustrates the use of
| :meth:`_types.TypeEngine.with_variant`.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.type_api.TypeEngine:
|
| __orig_bases__ = (<class 'sqlalchemy.sql.visitors.Visitable'>, typing....
|
| hashable = True
|
| render_bind_cast = False
|
| render_literal_cast = False
|
| should_evaluate_none = False
|
| sort_key_function = None
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.visitors.Visitable:
|
| __class_getitem__(key: 'Any') -> 'Any'
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__() -> 'None'
| This method is called when a class is subclassed.
|
| The default implementation does nothing. It may be
| overridden to extend subclasses.
sqlalchemy.DATETIME
Python Library Documentation: class DATETIME in module sqlalchemy.sql.sqltypes
class DATETIME(DateTime)
| DATETIME(timezone: 'bool' = False)
|
| The SQL DATETIME type.
|
| Method resolution order:
| DATETIME
| DateTime
| _RenderISO8601NoT
| HasExpressionLookup
| sqlalchemy.sql.type_api.TypeEngineMixin
| sqlalchemy.sql.type_api.TypeEngine
| sqlalchemy.sql.visitors.Visitable
| typing.Generic
| builtins.object
|
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| __parameters__ = ()
|
| __visit_name__ = 'DATETIME'
|
| ----------------------------------------------------------------------
| Methods inherited from DateTime:
|
| __init__(self, timezone: 'bool' = False)
| Construct a new :class:`.DateTime`.
|
| :param timezone: boolean. Indicates that the datetime type should
| enable timezone support, if available on the
| **base date/time-holding type only**. It is recommended
| to make use of the :class:`_types.TIMESTAMP` datatype directly when
| using this flag, as some databases include separate generic
| date/time-holding types distinct from the timezone-capable
| TIMESTAMP datatype, such as Oracle Database.
|
| get_dbapi_type(self, dbapi)
| Return the corresponding type object from the underlying DB-API, if
| any.
|
| This can be useful for calling ``setinputsizes()``, for example.
|
| literal_processor(self, dialect)
| Return a conversion function for processing literal values that are
| to be rendered directly without using binds.
|
| This function is used when the compiler makes use of the
| "literal_binds" flag, typically used in DDL generation as well
| as in certain scenarios where backends don't accept bound parameters.
|
| Returns a callable which will receive a literal Python value
| as the sole positional argument and will return a string representation
| to be rendered in a SQL statement.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.literal_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.literal_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_literal_param`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| ----------------------------------------------------------------------
| Readonly properties inherited from DateTime:
|
| python_type
| Return the Python type object expected to be returned
| by instances of this type, if known.
|
| Basically, for those types which enforce a return type,
| or are known across the board to do such for all common
| DBAPIs (like ``int`` for example), will return that type.
|
| If a return type is not defined, raises
| ``NotImplementedError``.
|
| Note that any type also accommodates NULL in SQL which
| means you can also get back ``None`` from any type
| in practice.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from _RenderISO8601NoT:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from HasExpressionLookup:
|
| Comparator = <class 'sqlalchemy.sql.sqltypes.HasExpressionLookup.Compa...
|
| comparator_factory = <class 'sqlalchemy.sql.sqltypes.HasExpressionLook...
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.type_api.TypeEngine:
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| __str__(self) -> 'str'
| Return str(self).
|
| adapt(self, cls: 'Type[Union[TypeEngine[Any], TypeEngineMixin]]', **kw: 'Any') -> 'TypeEngine[Any]'
| Produce an "adapted" form of this type, given an "impl" class
| to work with.
|
| This method is used internally to associate generic
| types with "implementation" types that are specific to a particular
| dialect.
|
| as_generic(self, allow_nulltype: 'bool' = False) -> 'TypeEngine[_T]'
| Return an instance of the generic type corresponding to this type
| using heuristic rule. The method may be overridden if this
| heuristic rule is not sufficient.
|
| >>> from sqlalchemy.dialects.mysql import INTEGER
| >>> INTEGER(display_width=4).as_generic()
| Integer()
|
| >>> from sqlalchemy.dialects.mysql import NVARCHAR
| >>> NVARCHAR(length=100).as_generic()
| Unicode(length=100)
|
| .. versionadded:: 1.4.0b2
|
|
| .. seealso::
|
| :ref:`metadata_reflection_dbagnostic_types` - describes the
| use of :meth:`_types.TypeEngine.as_generic` in conjunction with
| the :meth:`_sql.DDLEvents.column_reflect` event, which is its
| intended use.
|
| bind_expression(self, bindvalue: 'BindParameter[_T]') -> 'Optional[ColumnElement[_T]]'
| Given a bind value (i.e. a :class:`.BindParameter` instance),
| return a SQL expression in its place.
|
| This is typically a SQL function that wraps the existing bound
| parameter within the statement. It is used for special data types
| that require literals being wrapped in some special database function
| in order to coerce an application-level value into a database-specific
| format. It is the SQL analogue of the
| :meth:`.TypeEngine.bind_processor` method.
|
| This method is called during the **SQL compilation** phase of a
| statement, when rendering a SQL string. It is **not** called
| against specific values.
|
| Note that this method, when implemented, should always return
| the exact same structure, without any conditional logic, as it
| may be used in an executemany() call against an arbitrary number
| of bound parameter sets.
|
| .. note::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.bind_expression`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.bind_expression`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.bind_expression`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| .. seealso::
|
| :ref:`types_sql_value_processing`
|
| bind_processor(self, dialect: 'Dialect') -> 'Optional[_BindProcessorType[_T]]'
| Return a conversion function for processing bind values.
|
| Returns a callable which will receive a bind parameter value
| as the sole positional argument and will return a value to
| send to the DB-API.
|
| If processing is not necessary, the method should return ``None``.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.bind_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.bind_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_bind_param`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
|
| :param dialect: Dialect instance in use.
|
| coerce_compared_value(self, op: 'Optional[OperatorType]', value: 'Any') -> 'TypeEngine[Any]'
| Suggest a type for a 'coerced' Python value in an expression.
|
| Given an operator and value, gives the type a chance
| to return a type which the value should be coerced into.
|
| The default behavior here is conservative; if the right-hand
| side is already coerced into a SQL type based on its
| Python type, it is usually left alone.
|
| End-user functionality extension here should generally be via
| :class:`.TypeDecorator`, which provides more liberal behavior in that
| it defaults to coercing the other side of the expression into this
| type, thus applying special Python conversions above and beyond those
| needed by the DBAPI to both ides. It also provides the public method
| :meth:`.TypeDecorator.coerce_compared_value` which is intended for
| end-user customization of this behavior.
|
| column_expression(self, colexpr: 'ColumnElement[_T]') -> 'Optional[ColumnElement[_T]]'
| Given a SELECT column expression, return a wrapping SQL expression.
|
| This is typically a SQL function that wraps a column expression
| as rendered in the columns clause of a SELECT statement.
| It is used for special data types that require
| columns to be wrapped in some special database function in order
| to coerce the value before being sent back to the application.
| It is the SQL analogue of the :meth:`.TypeEngine.result_processor`
| method.
|
| .. note:: The :func:`.TypeEngine.column_expression` method is applied
| only to the **outermost columns clause** of a SELECT statement, that
| is, the columns that are to be delivered directly into the returned
| result rows. It does **not** apply to the columns clause inside
| of subqueries. This necessarily avoids double conversions against
| the column and only runs the conversion when ready to be returned
| to the client.
|
| This method is called during the **SQL compilation** phase of a
| statement, when rendering a SQL string. It is **not** called
| against specific values.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.column_expression`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.column_expression`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.column_expression`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
|
| .. seealso::
|
| :ref:`types_sql_value_processing`
|
| compare_values(self, x: 'Any', y: 'Any') -> 'bool'
| Compare two values for equality.
|
| compile(self, dialect: 'Optional[Dialect]' = None) -> 'str'
| Produce a string-compiled form of this :class:`.TypeEngine`.
|
| When called with no arguments, uses a "default" dialect
| to produce a string result.
|
| :param dialect: a :class:`.Dialect` instance.
|
| copy(self, **kw: 'Any') -> 'Self'
|
| copy_value(self, value: 'Any') -> 'Any'
|
| dialect_impl(self, dialect: 'Dialect') -> 'TypeEngine[_T]'
| Return a dialect-specific implementation for this
| :class:`.TypeEngine`.
|
| evaluates_none(self) -> 'Self'
| Return a copy of this type which has the
| :attr:`.should_evaluate_none` flag set to True.
|
| E.g.::
|
| Table(
| "some_table",
| metadata,
| Column(
| String(50).evaluates_none(),
| nullable=True,
| server_default="no value",
| ),
| )
|
| The ORM uses this flag to indicate that a positive value of ``None``
| is passed to the column in an INSERT statement, rather than omitting
| the column from the INSERT statement which has the effect of firing
| off column-level defaults. It also allows for types which have
| special behavior associated with the Python None value to indicate
| that the value doesn't necessarily translate into SQL NULL; a
| prime example of this is a JSON type which may wish to persist the
| JSON value ``'null'``.
|
| In all cases, the actual NULL SQL value can be always be
| persisted in any column by using
| the :obj:`_expression.null` SQL construct in an INSERT statement
| or associated with an ORM-mapped attribute.
|
| .. note::
|
| The "evaluates none" flag does **not** apply to a value
| of ``None`` passed to :paramref:`_schema.Column.default` or
| :paramref:`_schema.Column.server_default`; in these cases,
| ``None``
| still means "no default".
|
| .. seealso::
|
| :ref:`session_forcing_null` - in the ORM documentation
|
| :paramref:`.postgresql.JSON.none_as_null` - PostgreSQL JSON
| interaction with this flag.
|
| :attr:`.TypeEngine.should_evaluate_none` - class-level flag
|
| result_processor(self, dialect: 'Dialect', coltype: 'object') -> 'Optional[_ResultProcessorType[_T]]'
| Return a conversion function for processing result row values.
|
| Returns a callable which will receive a result row column
| value as the sole positional argument and will return a value
| to return to the user.
|
| If processing is not necessary, the method should return ``None``.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.result_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.result_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_result_value`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| :param dialect: Dialect instance in use.
|
| :param coltype: DBAPI coltype argument received in cursor.description.
|
| with_variant(self, type_: '_TypeEngineArgument[Any]', *dialect_names: 'str') -> 'Self'
| Produce a copy of this type object that will utilize the given
| type when applied to the dialect of the given name.
|
| e.g.::
|
| from sqlalchemy.types import String
| from sqlalchemy.dialects import mysql
|
| string_type = String()
|
| string_type = string_type.with_variant(
| mysql.VARCHAR(collation="foo"), "mysql", "mariadb"
| )
|
| The variant mapping indicates that when this type is
| interpreted by a specific dialect, it will instead be
| transmuted into the given type, rather than using the
| primary type.
|
| .. versionchanged:: 2.0 the :meth:`_types.TypeEngine.with_variant`
| method now works with a :class:`_types.TypeEngine` object "in
| place", returning a copy of the original type rather than returning
| a wrapping object; the ``Variant`` class is no longer used.
|
| :param type\_: a :class:`.TypeEngine` that will be selected
| as a variant from the originating type, when a dialect
| of the given name is in use.
| :param \*dialect_names: one or more base names of the dialect which
| uses this type. (i.e. ``'postgresql'``, ``'mysql'``, etc.)
|
| .. versionchanged:: 2.0 multiple dialect names can be specified
| for one variant.
|
| .. seealso::
|
| :ref:`types_with_variant` - illustrates the use of
| :meth:`_types.TypeEngine.with_variant`.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.type_api.TypeEngine:
|
| __orig_bases__ = (<class 'sqlalchemy.sql.visitors.Visitable'>, typing....
|
| hashable = True
|
| render_bind_cast = False
|
| render_literal_cast = False
|
| should_evaluate_none = False
|
| sort_key_function = None
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.visitors.Visitable:
|
| __class_getitem__(key: 'Any') -> 'Any'
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__() -> 'None'
| This method is called when a class is subclassed.
|
| The default implementation does nothing. It may be
| overridden to extend subclasses.
sqlalchemy.DDL
Python Library Documentation: class DDL in module sqlalchemy.sql.ddl
class DDL(ExecutableDDLElement)
| DDL(statement, context=None)
|
| A literal DDL statement.
|
| Specifies literal SQL DDL to be executed by the database. DDL objects
| function as DDL event listeners, and can be subscribed to those events
| listed in :class:`.DDLEvents`, using either :class:`_schema.Table` or
| :class:`_schema.MetaData` objects as targets.
| Basic templating support allows
| a single DDL instance to handle repetitive tasks for multiple tables.
|
| Examples::
|
| from sqlalchemy import event, DDL
|
| tbl = Table("users", metadata, Column("uid", Integer))
| event.listen(tbl, "before_create", DDL("DROP TRIGGER users_trigger"))
|
| spow = DDL("ALTER TABLE %(table)s SET secretpowers TRUE")
| event.listen(tbl, "after_create", spow.execute_if(dialect="somedb"))
|
| drop_spow = DDL("ALTER TABLE users SET secretpowers FALSE")
| connection.execute(drop_spow)
|
| When operating on Table events, the following ``statement``
| string substitutions are available:
|
| .. sourcecode:: text
|
| %(table)s - the Table name, with any required quoting applied
| %(schema)s - the schema name, with any required quoting applied
| %(fullname)s - the Table name including schema, quoted if needed
|
| The DDL's "context", if any, will be combined with the standard
| substitutions noted above. Keys present in the context will override
| the standard substitutions.
|
| Method resolution order:
| DDL
| ExecutableDDLElement
| sqlalchemy.sql.roles.DDLRole
| sqlalchemy.sql.base.Executable
| sqlalchemy.sql.roles.StatementRole
| sqlalchemy.sql.roles.SQLRole
| BaseDDLElement
| sqlalchemy.sql.elements.ClauseElement
| sqlalchemy.sql.annotation.SupportsWrappingAnnotations
| sqlalchemy.sql.annotation.SupportsAnnotations
| sqlalchemy.sql.cache_key.MemoizedHasCacheKey
| sqlalchemy.sql.cache_key.HasCacheKey
| sqlalchemy.util.langhelpers.HasMemoized
| sqlalchemy.sql.traversals.HasCopyInternals
| sqlalchemy.sql.visitors.ExternallyTraversible
| sqlalchemy.sql.visitors.HasTraverseInternals
| sqlalchemy.sql.elements.CompilerElement
| sqlalchemy.sql.visitors.Visitable
| builtins.object
|
| Methods defined here:
|
| __init__(self, statement, context=None)
| Create a DDL statement.
|
| :param statement:
| A string or unicode string to be executed. Statements will be
| processed with Python's string formatting operator using
| a fixed set of string substitutions, as well as additional
| substitutions provided by the optional :paramref:`.DDL.context`
| parameter.
|
| A literal '%' in a statement must be escaped as '%%'.
|
| SQL bind parameters are not available in DDL statements.
|
| :param context:
| Optional dictionary, defaults to None. These values will be
| available for use in string substitutions on the DDL statement.
|
| .. seealso::
|
| :class:`.DDLEvents`
|
| :ref:`event_toplevel`
|
| __repr__(self)
| Return repr(self).
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| __visit_name__ = 'ddl'
|
| ----------------------------------------------------------------------
| Methods inherited from ExecutableDDLElement:
|
| __call__(self, target, bind, **kw)
| Execute the DDL as a ddl_listener.
|
| against(self, target: 'SchemaItem') -> 'Self'
| Return a copy of this :class:`_schema.ExecutableDDLElement` which
| will include the given target.
|
| This essentially applies the given item to the ``.target`` attribute of
| the returned :class:`_schema.ExecutableDDLElement` object. This target
| is then usable by event handlers and compilation routines in order to
| provide services such as tokenization of a DDL string in terms of a
| particular :class:`_schema.Table`.
|
| When a :class:`_schema.ExecutableDDLElement` object is established as
| an event handler for the :meth:`_events.DDLEvents.before_create` or
| :meth:`_events.DDLEvents.after_create` events, and the event then
| occurs for a given target such as a :class:`_schema.Constraint` or
| :class:`_schema.Table`, that target is established with a copy of the
| :class:`_schema.ExecutableDDLElement` object using this method, which
| then proceeds to the :meth:`_schema.ExecutableDDLElement.execute`
| method in order to invoke the actual DDL instruction.
|
| :param target: a :class:`_schema.SchemaItem` that will be the subject
| of a DDL operation.
|
| :return: a copy of this :class:`_schema.ExecutableDDLElement` with the
| ``.target`` attribute assigned to the given
| :class:`_schema.SchemaItem`.
|
| .. seealso::
|
| :class:`_schema.DDL` - uses tokenization against the "target" when
| processing the DDL string.
|
| execute_if(self, dialect: 'Optional[str]' = None, callable_: 'Optional[DDLIfCallable]' = None, state: 'Optional[Any]' = None) -> 'Self'
| Return a callable that will execute this
| :class:`_ddl.ExecutableDDLElement` conditionally within an event
| handler.
|
| Used to provide a wrapper for event listening::
|
| event.listen(
| metadata,
| "before_create",
| DDL("my_ddl").execute_if(dialect="postgresql"),
| )
|
| :param dialect: May be a string or tuple of strings.
| If a string, it will be compared to the name of the
| executing database dialect::
|
| DDL("something").execute_if(dialect="postgresql")
|
| If a tuple, specifies multiple dialect names::
|
| DDL("something").execute_if(dialect=("postgresql", "mysql"))
|
| :param callable\_: A callable, which will be invoked with
| three positional arguments as well as optional keyword
| arguments:
|
| :ddl:
| This DDL element.
|
| :target:
| The :class:`_schema.Table` or :class:`_schema.MetaData`
| object which is the
| target of this event. May be None if the DDL is executed
| explicitly.
|
| :bind:
| The :class:`_engine.Connection` being used for DDL execution.
| May be None if this construct is being created inline within
| a table, in which case ``compiler`` will be present.
|
| :tables:
| Optional keyword argument - a list of Table objects which are to
| be created/ dropped within a MetaData.create_all() or drop_all()
| method call.
|
| :dialect: keyword argument, but always present - the
| :class:`.Dialect` involved in the operation.
|
| :compiler: keyword argument. Will be ``None`` for an engine
| level DDL invocation, but will refer to a :class:`.DDLCompiler`
| if this DDL element is being created inline within a table.
|
| :state:
| Optional keyword argument - will be the ``state`` argument
| passed to this function.
|
| :checkfirst:
| Keyword argument, will be True if the 'checkfirst' flag was
| set during the call to ``create()``, ``create_all()``,
| ``drop()``, ``drop_all()``.
|
| If the callable returns a True value, the DDL statement will be
| executed.
|
| :param state: any value which will be passed to the callable\_
| as the ``state`` keyword argument.
|
| .. seealso::
|
| :meth:`.SchemaItem.ddl_if`
|
| :class:`.DDLEvents`
|
| :ref:`event_toplevel`
|
| ----------------------------------------------------------------------
| Data descriptors inherited from ExecutableDDLElement:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from ExecutableDDLElement:
|
| target = None
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.base.Executable:
|
| execution_options(self, **kw: 'Any') -> 'Self'
| Set non-SQL options for the statement which take effect during
| execution.
|
| Execution options can be set at many scopes, including per-statement,
| per-connection, or per execution, using methods such as
| :meth:`_engine.Connection.execution_options` and parameters which
| accept a dictionary of options such as
| :paramref:`_engine.Connection.execute.execution_options` and
| :paramref:`_orm.Session.execute.execution_options`.
|
| The primary characteristic of an execution option, as opposed to
| other kinds of options such as ORM loader options, is that
| **execution options never affect the compiled SQL of a query, only
| things that affect how the SQL statement itself is invoked or how
| results are fetched**. That is, execution options are not part of
| what's accommodated by SQL compilation nor are they considered part of
| the cached state of a statement.
|
| The :meth:`_sql.Executable.execution_options` method is
| :term:`generative`, as
| is the case for the method as applied to the :class:`_engine.Engine`
| and :class:`_orm.Query` objects, which means when the method is called,
| a copy of the object is returned, which applies the given parameters to
| that new copy, but leaves the original unchanged::
|
| statement = select(table.c.x, table.c.y)
| new_statement = statement.execution_options(my_option=True)
|
| An exception to this behavior is the :class:`_engine.Connection`
| object, where the :meth:`_engine.Connection.execution_options` method
| is explicitly **not** generative.
|
| The kinds of options that may be passed to
| :meth:`_sql.Executable.execution_options` and other related methods and
| parameter dictionaries include parameters that are explicitly consumed
| by SQLAlchemy Core or ORM, as well as arbitrary keyword arguments not
| defined by SQLAlchemy, which means the methods and/or parameter
| dictionaries may be used for user-defined parameters that interact with
| custom code, which may access the parameters using methods such as
| :meth:`_sql.Executable.get_execution_options` and
| :meth:`_engine.Connection.get_execution_options`, or within selected
| event hooks using a dedicated ``execution_options`` event parameter
| such as
| :paramref:`_events.ConnectionEvents.before_execute.execution_options`
| or :attr:`_orm.ORMExecuteState.execution_options`, e.g.::
|
| from sqlalchemy import event
|
|
| @event.listens_for(some_engine, "before_execute")
| def _process_opt(conn, statement, multiparams, params, execution_options):
| "run a SQL function before invoking a statement"
|
| if execution_options.get("do_special_thing", False):
| conn.exec_driver_sql("run_special_function()")
|
| Within the scope of options that are explicitly recognized by
| SQLAlchemy, most apply to specific classes of objects and not others.
| The most common execution options include:
|
| * :paramref:`_engine.Connection.execution_options.isolation_level` -
| sets the isolation level for a connection or a class of connections
| via an :class:`_engine.Engine`. This option is accepted only
| by :class:`_engine.Connection` or :class:`_engine.Engine`.
|
| * :paramref:`_engine.Connection.execution_options.stream_results` -
| indicates results should be fetched using a server side cursor;
| this option is accepted by :class:`_engine.Connection`, by the
| :paramref:`_engine.Connection.execute.execution_options` parameter
| on :meth:`_engine.Connection.execute`, and additionally by
| :meth:`_sql.Executable.execution_options` on a SQL statement object,
| as well as by ORM constructs like :meth:`_orm.Session.execute`.
|
| * :paramref:`_engine.Connection.execution_options.compiled_cache` -
| indicates a dictionary that will serve as the
| :ref:`SQL compilation cache <sql_caching>`
| for a :class:`_engine.Connection` or :class:`_engine.Engine`, as
| well as for ORM methods like :meth:`_orm.Session.execute`.
| Can be passed as ``None`` to disable caching for statements.
| This option is not accepted by
| :meth:`_sql.Executable.execution_options` as it is inadvisable to
| carry along a compilation cache within a statement object.
|
| * :paramref:`_engine.Connection.execution_options.schema_translate_map`
| - a mapping of schema names used by the
| :ref:`Schema Translate Map <schema_translating>` feature, accepted
| by :class:`_engine.Connection`, :class:`_engine.Engine`,
| :class:`_sql.Executable`, as well as by ORM constructs
| like :meth:`_orm.Session.execute`.
|
| .. seealso::
|
| :meth:`_engine.Connection.execution_options`
|
| :paramref:`_engine.Connection.execute.execution_options`
|
| :paramref:`_orm.Session.execute.execution_options`
|
| :ref:`orm_queryguide_execution_options` - documentation on all
| ORM-specific execution options
|
| get_execution_options(self) -> '_ExecuteOptions'
| Get the non-SQL options which will take effect during execution.
|
| .. versionadded:: 1.3
|
| .. seealso::
|
| :meth:`.Executable.execution_options`
|
| options(self, *options: 'ExecutableOption') -> 'Self'
| Apply options to this statement.
|
| In the general sense, options are any kind of Python object
| that can be interpreted by the SQL compiler for the statement.
| These options can be consumed by specific dialects or specific kinds
| of compilers.
|
| The most commonly known kind of option are the ORM level options
| that apply "eager load" and other loading behaviors to an ORM
| query. However, options can theoretically be used for many other
| purposes.
|
| For background on specific kinds of options for specific kinds of
| statements, refer to the documentation for those option objects.
|
| .. versionchanged:: 1.4 - added :meth:`.Executable.options` to
| Core statement objects towards the goal of allowing unified
| Core / ORM querying capabilities.
|
| .. seealso::
|
| :ref:`loading_columns` - refers to options specific to the usage
| of ORM queries
|
| :ref:`relationship_loader_options` - refers to options specific
| to the usage of ORM queries
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.base.Executable:
|
| is_delete = False
|
| is_dml = False
|
| is_from_statement = False
|
| is_insert = False
|
| is_select = False
|
| is_text = False
|
| is_update = False
|
| supports_execution = True
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.SQLRole:
|
| allows_lambda = False
|
| uses_inspection = False
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.elements.ClauseElement:
|
| __bool__(self)
|
| __getstate__(self)
| Helper for pickle.
|
| __invert__(self)
|
| compare(self, other: 'ClauseElement', **kw: 'Any') -> 'bool'
| Compare this :class:`_expression.ClauseElement` to
| the given :class:`_expression.ClauseElement`.
|
| Subclasses should override the default behavior, which is a
| straight identity comparison.
|
| \**kw are arguments consumed by subclass ``compare()`` methods and
| may be used to modify the criteria for comparison
| (see :class:`_expression.ColumnElement`).
|
| description(...)
|
| entity_namespace(...)
|
| params(self, _ClauseElement__optionaldict: 'Optional[Mapping[str, Any]]' = None, **kwargs: 'Any') -> 'Self'
| Return a copy with :func:`_expression.bindparam` elements
| replaced.
|
| Returns a copy of this ClauseElement with
| :func:`_expression.bindparam`
| elements replaced with values taken from the given dictionary::
|
| >>> clause = column("x") + bindparam("foo")
| >>> print(clause.compile().params)
| {'foo':None}
| >>> print(clause.params({"foo": 7}).compile().params)
| {'foo':7}
|
| self_group(self, against: 'Optional[OperatorType]' = None) -> 'ClauseElement'
| 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.
|
| unique_params(self, _ClauseElement__optionaldict: 'Optional[Dict[str, Any]]' = None, **kwargs: 'Any') -> 'Self'
| Return a copy with :func:`_expression.bindparam` elements
| replaced.
|
| Same functionality as :meth:`_expression.ClauseElement.params`,
| except adds `unique=True`
| to affected bind parameters so that multiple statements can be
| used.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.elements.ClauseElement:
|
| is_clause_element = True
|
| is_selectable = False
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.cache_key.HasCacheKey:
|
| inherit_cache = None
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_instancemethod(fn: '_F') -> '_F'
| Decorate a method memoize its return value.
|
| :meta private:
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_attribute = <class 'sqlalchemy.util.langhelpers.HasMemoized.m...
| A read-only @property that is only evaluated once.
|
| :meta private:
|
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.visitors.HasTraverseInternals:
|
| get_children(self, *, omit_attrs: 'Tuple[str, ...]' = (), **kw: 'Any') -> 'Iterable[HasTraverseInternals]'
| Return immediate child :class:`.visitors.HasTraverseInternals`
| elements of this :class:`.visitors.HasTraverseInternals`.
|
| This is used for visit traversal.
|
| \**kw may contain flags that change the collection that is
| returned, for example to return a subset of items in order to
| cut down on larger traversals, or to return child items from a
| different context (such as schema-level collections instead of
| clause-level).
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.elements.CompilerElement:
|
| __str__(self) -> 'str'
| Return str(self).
|
| compile(self, bind: 'Optional[_HasDialect]' = None, dialect: 'Optional[Dialect]' = None, **kw: 'Any') -> 'Compiled'
| Compile this SQL expression.
|
| The return value is a :class:`~.Compiled` object.
| Calling ``str()`` or ``unicode()`` on the returned value will yield a
| string representation of the result. The
| :class:`~.Compiled` object also can return a
| dictionary of bind parameter names and values
| using the ``params`` accessor.
|
| :param bind: An :class:`.Connection` or :class:`.Engine` which
| can provide a :class:`.Dialect` in order to generate a
| :class:`.Compiled` object. If the ``bind`` and
| ``dialect`` parameters are both omitted, a default SQL compiler
| is used.
|
| :param column_keys: Used for INSERT and UPDATE statements, a list of
| column names which should be present in the VALUES clause of the
| compiled statement. If ``None``, all columns from the target table
| object are rendered.
|
| :param dialect: A :class:`.Dialect` instance which can generate
| a :class:`.Compiled` object. This argument takes precedence over
| the ``bind`` argument.
|
| :param compile_kwargs: optional dictionary of additional parameters
| that will be passed through to the compiler within all "visit"
| methods. This allows any custom flag to be passed through to
| a custom compilation construct, for example. It is also used
| for the case of passing the ``literal_binds`` flag through::
|
| from sqlalchemy.sql import table, column, select
|
| t = table("t", column("x"))
|
| s = select(t).where(t.c.x == 5)
|
| print(s.compile(compile_kwargs={"literal_binds": True}))
|
| .. seealso::
|
| :ref:`faq_sql_expression_string`
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.elements.CompilerElement:
|
| stringify_dialect = 'default'
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.visitors.Visitable:
|
| __class_getitem__(key: 'Any') -> 'Any'
|
| __init_subclass__() -> 'None'
| This method is called when a class is subclassed.
|
| The default implementation does nothing. It may be
| overridden to extend subclasses.
sqlalchemy.DDLElement
Python Library Documentation: class ExecutableDDLElement in module sqlalchemy.sql.ddl
class ExecutableDDLElement(sqlalchemy.sql.roles.DDLRole, sqlalchemy.sql.base.Executable, BaseDDLElement)
| Base class for standalone executable DDL expression constructs.
|
| This class is the base for the general purpose :class:`.DDL` class,
| as well as the various create/drop clause constructs such as
| :class:`.CreateTable`, :class:`.DropTable`, :class:`.AddConstraint`,
| etc.
|
| .. versionchanged:: 2.0 :class:`.ExecutableDDLElement` is renamed from
| :class:`.DDLElement`, which still exists for backwards compatibility.
|
| :class:`.ExecutableDDLElement` integrates closely with SQLAlchemy events,
| introduced in :ref:`event_toplevel`. An instance of one is
| itself an event receiving callable::
|
| event.listen(
| users,
| "after_create",
| AddConstraint(constraint).execute_if(dialect="postgresql"),
| )
|
| .. seealso::
|
| :class:`.DDL`
|
| :class:`.DDLEvents`
|
| :ref:`event_toplevel`
|
| :ref:`schema_ddl_sequences`
|
| Method resolution order:
| ExecutableDDLElement
| sqlalchemy.sql.roles.DDLRole
| sqlalchemy.sql.base.Executable
| sqlalchemy.sql.roles.StatementRole
| sqlalchemy.sql.roles.SQLRole
| BaseDDLElement
| sqlalchemy.sql.elements.ClauseElement
| sqlalchemy.sql.annotation.SupportsWrappingAnnotations
| sqlalchemy.sql.annotation.SupportsAnnotations
| sqlalchemy.sql.cache_key.MemoizedHasCacheKey
| sqlalchemy.sql.cache_key.HasCacheKey
| sqlalchemy.util.langhelpers.HasMemoized
| sqlalchemy.sql.traversals.HasCopyInternals
| sqlalchemy.sql.visitors.ExternallyTraversible
| sqlalchemy.sql.visitors.HasTraverseInternals
| sqlalchemy.sql.elements.CompilerElement
| sqlalchemy.sql.visitors.Visitable
| builtins.object
|
| Methods defined here:
|
| __call__(self, target, bind, **kw)
| Execute the DDL as a ddl_listener.
|
| against(self, target: 'SchemaItem') -> 'Self'
| Return a copy of this :class:`_schema.ExecutableDDLElement` which
| will include the given target.
|
| This essentially applies the given item to the ``.target`` attribute of
| the returned :class:`_schema.ExecutableDDLElement` object. This target
| is then usable by event handlers and compilation routines in order to
| provide services such as tokenization of a DDL string in terms of a
| particular :class:`_schema.Table`.
|
| When a :class:`_schema.ExecutableDDLElement` object is established as
| an event handler for the :meth:`_events.DDLEvents.before_create` or
| :meth:`_events.DDLEvents.after_create` events, and the event then
| occurs for a given target such as a :class:`_schema.Constraint` or
| :class:`_schema.Table`, that target is established with a copy of the
| :class:`_schema.ExecutableDDLElement` object using this method, which
| then proceeds to the :meth:`_schema.ExecutableDDLElement.execute`
| method in order to invoke the actual DDL instruction.
|
| :param target: a :class:`_schema.SchemaItem` that will be the subject
| of a DDL operation.
|
| :return: a copy of this :class:`_schema.ExecutableDDLElement` with the
| ``.target`` attribute assigned to the given
| :class:`_schema.SchemaItem`.
|
| .. seealso::
|
| :class:`_schema.DDL` - uses tokenization against the "target" when
| processing the DDL string.
|
| execute_if(self, dialect: 'Optional[str]' = None, callable_: 'Optional[DDLIfCallable]' = None, state: 'Optional[Any]' = None) -> 'Self'
| Return a callable that will execute this
| :class:`_ddl.ExecutableDDLElement` conditionally within an event
| handler.
|
| Used to provide a wrapper for event listening::
|
| event.listen(
| metadata,
| "before_create",
| DDL("my_ddl").execute_if(dialect="postgresql"),
| )
|
| :param dialect: May be a string or tuple of strings.
| If a string, it will be compared to the name of the
| executing database dialect::
|
| DDL("something").execute_if(dialect="postgresql")
|
| If a tuple, specifies multiple dialect names::
|
| DDL("something").execute_if(dialect=("postgresql", "mysql"))
|
| :param callable\_: A callable, which will be invoked with
| three positional arguments as well as optional keyword
| arguments:
|
| :ddl:
| This DDL element.
|
| :target:
| The :class:`_schema.Table` or :class:`_schema.MetaData`
| object which is the
| target of this event. May be None if the DDL is executed
| explicitly.
|
| :bind:
| The :class:`_engine.Connection` being used for DDL execution.
| May be None if this construct is being created inline within
| a table, in which case ``compiler`` will be present.
|
| :tables:
| Optional keyword argument - a list of Table objects which are to
| be created/ dropped within a MetaData.create_all() or drop_all()
| method call.
|
| :dialect: keyword argument, but always present - the
| :class:`.Dialect` involved in the operation.
|
| :compiler: keyword argument. Will be ``None`` for an engine
| level DDL invocation, but will refer to a :class:`.DDLCompiler`
| if this DDL element is being created inline within a table.
|
| :state:
| Optional keyword argument - will be the ``state`` argument
| passed to this function.
|
| :checkfirst:
| Keyword argument, will be True if the 'checkfirst' flag was
| set during the call to ``create()``, ``create_all()``,
| ``drop()``, ``drop_all()``.
|
| If the callable returns a True value, the DDL statement will be
| executed.
|
| :param state: any value which will be passed to the callable\_
| as the ``state`` keyword argument.
|
| .. seealso::
|
| :meth:`.SchemaItem.ddl_if`
|
| :class:`.DDLEvents`
|
| :ref:`event_toplevel`
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'_ddl_if': 'Optional[DDLIf]', 'target': 'Union[Sche...
|
| target = None
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.base.Executable:
|
| execution_options(self, **kw: 'Any') -> 'Self'
| Set non-SQL options for the statement which take effect during
| execution.
|
| Execution options can be set at many scopes, including per-statement,
| per-connection, or per execution, using methods such as
| :meth:`_engine.Connection.execution_options` and parameters which
| accept a dictionary of options such as
| :paramref:`_engine.Connection.execute.execution_options` and
| :paramref:`_orm.Session.execute.execution_options`.
|
| The primary characteristic of an execution option, as opposed to
| other kinds of options such as ORM loader options, is that
| **execution options never affect the compiled SQL of a query, only
| things that affect how the SQL statement itself is invoked or how
| results are fetched**. That is, execution options are not part of
| what's accommodated by SQL compilation nor are they considered part of
| the cached state of a statement.
|
| The :meth:`_sql.Executable.execution_options` method is
| :term:`generative`, as
| is the case for the method as applied to the :class:`_engine.Engine`
| and :class:`_orm.Query` objects, which means when the method is called,
| a copy of the object is returned, which applies the given parameters to
| that new copy, but leaves the original unchanged::
|
| statement = select(table.c.x, table.c.y)
| new_statement = statement.execution_options(my_option=True)
|
| An exception to this behavior is the :class:`_engine.Connection`
| object, where the :meth:`_engine.Connection.execution_options` method
| is explicitly **not** generative.
|
| The kinds of options that may be passed to
| :meth:`_sql.Executable.execution_options` and other related methods and
| parameter dictionaries include parameters that are explicitly consumed
| by SQLAlchemy Core or ORM, as well as arbitrary keyword arguments not
| defined by SQLAlchemy, which means the methods and/or parameter
| dictionaries may be used for user-defined parameters that interact with
| custom code, which may access the parameters using methods such as
| :meth:`_sql.Executable.get_execution_options` and
| :meth:`_engine.Connection.get_execution_options`, or within selected
| event hooks using a dedicated ``execution_options`` event parameter
| such as
| :paramref:`_events.ConnectionEvents.before_execute.execution_options`
| or :attr:`_orm.ORMExecuteState.execution_options`, e.g.::
|
| from sqlalchemy import event
|
|
| @event.listens_for(some_engine, "before_execute")
| def _process_opt(conn, statement, multiparams, params, execution_options):
| "run a SQL function before invoking a statement"
|
| if execution_options.get("do_special_thing", False):
| conn.exec_driver_sql("run_special_function()")
|
| Within the scope of options that are explicitly recognized by
| SQLAlchemy, most apply to specific classes of objects and not others.
| The most common execution options include:
|
| * :paramref:`_engine.Connection.execution_options.isolation_level` -
| sets the isolation level for a connection or a class of connections
| via an :class:`_engine.Engine`. This option is accepted only
| by :class:`_engine.Connection` or :class:`_engine.Engine`.
|
| * :paramref:`_engine.Connection.execution_options.stream_results` -
| indicates results should be fetched using a server side cursor;
| this option is accepted by :class:`_engine.Connection`, by the
| :paramref:`_engine.Connection.execute.execution_options` parameter
| on :meth:`_engine.Connection.execute`, and additionally by
| :meth:`_sql.Executable.execution_options` on a SQL statement object,
| as well as by ORM constructs like :meth:`_orm.Session.execute`.
|
| * :paramref:`_engine.Connection.execution_options.compiled_cache` -
| indicates a dictionary that will serve as the
| :ref:`SQL compilation cache <sql_caching>`
| for a :class:`_engine.Connection` or :class:`_engine.Engine`, as
| well as for ORM methods like :meth:`_orm.Session.execute`.
| Can be passed as ``None`` to disable caching for statements.
| This option is not accepted by
| :meth:`_sql.Executable.execution_options` as it is inadvisable to
| carry along a compilation cache within a statement object.
|
| * :paramref:`_engine.Connection.execution_options.schema_translate_map`
| - a mapping of schema names used by the
| :ref:`Schema Translate Map <schema_translating>` feature, accepted
| by :class:`_engine.Connection`, :class:`_engine.Engine`,
| :class:`_sql.Executable`, as well as by ORM constructs
| like :meth:`_orm.Session.execute`.
|
| .. seealso::
|
| :meth:`_engine.Connection.execution_options`
|
| :paramref:`_engine.Connection.execute.execution_options`
|
| :paramref:`_orm.Session.execute.execution_options`
|
| :ref:`orm_queryguide_execution_options` - documentation on all
| ORM-specific execution options
|
| get_execution_options(self) -> '_ExecuteOptions'
| Get the non-SQL options which will take effect during execution.
|
| .. versionadded:: 1.3
|
| .. seealso::
|
| :meth:`.Executable.execution_options`
|
| options(self, *options: 'ExecutableOption') -> 'Self'
| Apply options to this statement.
|
| In the general sense, options are any kind of Python object
| that can be interpreted by the SQL compiler for the statement.
| These options can be consumed by specific dialects or specific kinds
| of compilers.
|
| The most commonly known kind of option are the ORM level options
| that apply "eager load" and other loading behaviors to an ORM
| query. However, options can theoretically be used for many other
| purposes.
|
| For background on specific kinds of options for specific kinds of
| statements, refer to the documentation for those option objects.
|
| .. versionchanged:: 1.4 - added :meth:`.Executable.options` to
| Core statement objects towards the goal of allowing unified
| Core / ORM querying capabilities.
|
| .. seealso::
|
| :ref:`loading_columns` - refers to options specific to the usage
| of ORM queries
|
| :ref:`relationship_loader_options` - refers to options specific
| to the usage of ORM queries
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.base.Executable:
|
| is_delete = False
|
| is_dml = False
|
| is_from_statement = False
|
| is_insert = False
|
| is_select = False
|
| is_text = False
|
| is_update = False
|
| supports_execution = True
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.SQLRole:
|
| allows_lambda = False
|
| uses_inspection = False
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.elements.ClauseElement:
|
| __bool__(self)
|
| __getstate__(self)
| Helper for pickle.
|
| __invert__(self)
|
| __repr__(self)
| Return repr(self).
|
| compare(self, other: 'ClauseElement', **kw: 'Any') -> 'bool'
| Compare this :class:`_expression.ClauseElement` to
| the given :class:`_expression.ClauseElement`.
|
| Subclasses should override the default behavior, which is a
| straight identity comparison.
|
| \**kw are arguments consumed by subclass ``compare()`` methods and
| may be used to modify the criteria for comparison
| (see :class:`_expression.ColumnElement`).
|
| description(...)
|
| entity_namespace(...)
|
| params(self, _ClauseElement__optionaldict: 'Optional[Mapping[str, Any]]' = None, **kwargs: 'Any') -> 'Self'
| Return a copy with :func:`_expression.bindparam` elements
| replaced.
|
| Returns a copy of this ClauseElement with
| :func:`_expression.bindparam`
| elements replaced with values taken from the given dictionary::
|
| >>> clause = column("x") + bindparam("foo")
| >>> print(clause.compile().params)
| {'foo':None}
| >>> print(clause.params({"foo": 7}).compile().params)
| {'foo':7}
|
| self_group(self, against: 'Optional[OperatorType]' = None) -> 'ClauseElement'
| 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.
|
| unique_params(self, _ClauseElement__optionaldict: 'Optional[Dict[str, Any]]' = None, **kwargs: 'Any') -> 'Self'
| Return a copy with :func:`_expression.bindparam` elements
| replaced.
|
| Same functionality as :meth:`_expression.ClauseElement.params`,
| except adds `unique=True`
| to affected bind parameters so that multiple statements can be
| used.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.elements.ClauseElement:
|
| __visit_name__ = 'clause'
|
| is_clause_element = True
|
| is_selectable = False
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.cache_key.HasCacheKey:
|
| inherit_cache = None
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_instancemethod(fn: '_F') -> '_F'
| Decorate a method memoize its return value.
|
| :meta private:
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_attribute = <class 'sqlalchemy.util.langhelpers.HasMemoized.m...
| A read-only @property that is only evaluated once.
|
| :meta private:
|
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.visitors.HasTraverseInternals:
|
| get_children(self, *, omit_attrs: 'Tuple[str, ...]' = (), **kw: 'Any') -> 'Iterable[HasTraverseInternals]'
| Return immediate child :class:`.visitors.HasTraverseInternals`
| elements of this :class:`.visitors.HasTraverseInternals`.
|
| This is used for visit traversal.
|
| \**kw may contain flags that change the collection that is
| returned, for example to return a subset of items in order to
| cut down on larger traversals, or to return child items from a
| different context (such as schema-level collections instead of
| clause-level).
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.elements.CompilerElement:
|
| __str__(self) -> 'str'
| Return str(self).
|
| compile(self, bind: 'Optional[_HasDialect]' = None, dialect: 'Optional[Dialect]' = None, **kw: 'Any') -> 'Compiled'
| Compile this SQL expression.
|
| The return value is a :class:`~.Compiled` object.
| Calling ``str()`` or ``unicode()`` on the returned value will yield a
| string representation of the result. The
| :class:`~.Compiled` object also can return a
| dictionary of bind parameter names and values
| using the ``params`` accessor.
|
| :param bind: An :class:`.Connection` or :class:`.Engine` which
| can provide a :class:`.Dialect` in order to generate a
| :class:`.Compiled` object. If the ``bind`` and
| ``dialect`` parameters are both omitted, a default SQL compiler
| is used.
|
| :param column_keys: Used for INSERT and UPDATE statements, a list of
| column names which should be present in the VALUES clause of the
| compiled statement. If ``None``, all columns from the target table
| object are rendered.
|
| :param dialect: A :class:`.Dialect` instance which can generate
| a :class:`.Compiled` object. This argument takes precedence over
| the ``bind`` argument.
|
| :param compile_kwargs: optional dictionary of additional parameters
| that will be passed through to the compiler within all "visit"
| methods. This allows any custom flag to be passed through to
| a custom compilation construct, for example. It is also used
| for the case of passing the ``literal_binds`` flag through::
|
| from sqlalchemy.sql import table, column, select
|
| t = table("t", column("x"))
|
| s = select(t).where(t.c.x == 5)
|
| print(s.compile(compile_kwargs={"literal_binds": True}))
|
| .. seealso::
|
| :ref:`faq_sql_expression_string`
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.elements.CompilerElement:
|
| stringify_dialect = 'default'
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.visitors.Visitable:
|
| __class_getitem__(key: 'Any') -> 'Any'
|
| __init_subclass__() -> 'None'
| This method is called when a class is subclassed.
|
| The default implementation does nothing. It may be
| overridden to extend subclasses.
sqlalchemy.DECIMAL
Python Library Documentation: class DECIMAL in module sqlalchemy.sql.sqltypes
class DECIMAL(Numeric)
| DECIMAL(precision: 'Optional[int]' = None, scale: 'Optional[int]' = None, decimal_return_scale: 'Optional[int]' = None, asdecimal: 'bool' = True)
|
| The SQL DECIMAL type.
|
| .. seealso::
|
| :class:`_types.Numeric` - documentation for the base type.
|
| Method resolution order:
| DECIMAL
| Numeric
| HasExpressionLookup
| sqlalchemy.sql.type_api.TypeEngineMixin
| sqlalchemy.sql.type_api.TypeEngine
| sqlalchemy.sql.visitors.Visitable
| typing.Generic
| builtins.object
|
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| __parameters__ = ()
|
| __visit_name__ = 'DECIMAL'
|
| ----------------------------------------------------------------------
| Methods inherited from Numeric:
|
| __init__(self, precision: 'Optional[int]' = None, scale: 'Optional[int]' = None, decimal_return_scale: 'Optional[int]' = None, asdecimal: 'bool' = True)
| Construct a Numeric.
|
| :param precision: the numeric precision for use in DDL ``CREATE
| TABLE``.
|
| :param scale: the numeric scale for use in DDL ``CREATE TABLE``.
|
| :param asdecimal: default True. Return whether or not
| values should be sent as Python Decimal objects, or
| as floats. Different DBAPIs send one or the other based on
| datatypes - the Numeric type will ensure that return values
| are one or the other across DBAPIs consistently.
|
| :param decimal_return_scale: Default scale to use when converting
| from floats to Python decimals. Floating point values will typically
| be much longer due to decimal inaccuracy, and most floating point
| database types don't have a notion of "scale", so by default the
| float type looks for the first ten decimal places when converting.
| Specifying this value will override that length. Types which
| do include an explicit ".scale" value, such as the base
| :class:`.Numeric` as well as the MySQL float types, will use the
| value of ".scale" as the default for decimal_return_scale, if not
| otherwise specified.
|
| When using the ``Numeric`` type, care should be taken to ensure
| that the asdecimal setting is appropriate for the DBAPI in use -
| when Numeric applies a conversion from Decimal->float or float->
| Decimal, this conversion incurs an additional performance overhead
| for all result columns received.
|
| DBAPIs that return Decimal natively (e.g. psycopg2) will have
| better accuracy and higher performance with a setting of ``True``,
| as the native translation to Decimal reduces the amount of floating-
| point issues at play, and the Numeric type itself doesn't need
| to apply any further conversions. However, another DBAPI which
| returns floats natively *will* incur an additional conversion
| overhead, and is still subject to floating point data loss - in
| which case ``asdecimal=False`` will at least remove the extra
| conversion overhead.
|
| bind_processor(self, dialect)
| Return a conversion function for processing bind values.
|
| Returns a callable which will receive a bind parameter value
| as the sole positional argument and will return a value to
| send to the DB-API.
|
| If processing is not necessary, the method should return ``None``.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.bind_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.bind_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_bind_param`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
|
| :param dialect: Dialect instance in use.
|
| get_dbapi_type(self, dbapi)
| Return the corresponding type object from the underlying DB-API, if
| any.
|
| This can be useful for calling ``setinputsizes()``, for example.
|
| literal_processor(self, dialect)
| Return a conversion function for processing literal values that are
| to be rendered directly without using binds.
|
| This function is used when the compiler makes use of the
| "literal_binds" flag, typically used in DDL generation as well
| as in certain scenarios where backends don't accept bound parameters.
|
| Returns a callable which will receive a literal Python value
| as the sole positional argument and will return a string representation
| to be rendered in a SQL statement.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.literal_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.literal_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_literal_param`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| result_processor(self, dialect, coltype)
| Return a conversion function for processing result row values.
|
| Returns a callable which will receive a result row column
| value as the sole positional argument and will return a value
| to return to the user.
|
| If processing is not necessary, the method should return ``None``.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.result_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.result_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_result_value`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| :param dialect: Dialect instance in use.
|
| :param coltype: DBAPI coltype argument received in cursor.description.
|
| ----------------------------------------------------------------------
| Readonly properties inherited from Numeric:
|
| python_type
| Return the Python type object expected to be returned
| by instances of this type, if known.
|
| Basically, for those types which enforce a return type,
| or are known across the board to do such for all common
| DBAPIs (like ``int`` for example), will return that type.
|
| If a return type is not defined, raises
| ``NotImplementedError``.
|
| Note that any type also accommodates NULL in SQL which
| means you can also get back ``None`` from any type
| in practice.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from HasExpressionLookup:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from HasExpressionLookup:
|
| Comparator = <class 'sqlalchemy.sql.sqltypes.HasExpressionLookup.Compa...
|
| comparator_factory = <class 'sqlalchemy.sql.sqltypes.HasExpressionLook...
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.type_api.TypeEngine:
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| __str__(self) -> 'str'
| Return str(self).
|
| adapt(self, cls: 'Type[Union[TypeEngine[Any], TypeEngineMixin]]', **kw: 'Any') -> 'TypeEngine[Any]'
| Produce an "adapted" form of this type, given an "impl" class
| to work with.
|
| This method is used internally to associate generic
| types with "implementation" types that are specific to a particular
| dialect.
|
| as_generic(self, allow_nulltype: 'bool' = False) -> 'TypeEngine[_T]'
| Return an instance of the generic type corresponding to this type
| using heuristic rule. The method may be overridden if this
| heuristic rule is not sufficient.
|
| >>> from sqlalchemy.dialects.mysql import INTEGER
| >>> INTEGER(display_width=4).as_generic()
| Integer()
|
| >>> from sqlalchemy.dialects.mysql import NVARCHAR
| >>> NVARCHAR(length=100).as_generic()
| Unicode(length=100)
|
| .. versionadded:: 1.4.0b2
|
|
| .. seealso::
|
| :ref:`metadata_reflection_dbagnostic_types` - describes the
| use of :meth:`_types.TypeEngine.as_generic` in conjunction with
| the :meth:`_sql.DDLEvents.column_reflect` event, which is its
| intended use.
|
| bind_expression(self, bindvalue: 'BindParameter[_T]') -> 'Optional[ColumnElement[_T]]'
| Given a bind value (i.e. a :class:`.BindParameter` instance),
| return a SQL expression in its place.
|
| This is typically a SQL function that wraps the existing bound
| parameter within the statement. It is used for special data types
| that require literals being wrapped in some special database function
| in order to coerce an application-level value into a database-specific
| format. It is the SQL analogue of the
| :meth:`.TypeEngine.bind_processor` method.
|
| This method is called during the **SQL compilation** phase of a
| statement, when rendering a SQL string. It is **not** called
| against specific values.
|
| Note that this method, when implemented, should always return
| the exact same structure, without any conditional logic, as it
| may be used in an executemany() call against an arbitrary number
| of bound parameter sets.
|
| .. note::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.bind_expression`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.bind_expression`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.bind_expression`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| .. seealso::
|
| :ref:`types_sql_value_processing`
|
| coerce_compared_value(self, op: 'Optional[OperatorType]', value: 'Any') -> 'TypeEngine[Any]'
| Suggest a type for a 'coerced' Python value in an expression.
|
| Given an operator and value, gives the type a chance
| to return a type which the value should be coerced into.
|
| The default behavior here is conservative; if the right-hand
| side is already coerced into a SQL type based on its
| Python type, it is usually left alone.
|
| End-user functionality extension here should generally be via
| :class:`.TypeDecorator`, which provides more liberal behavior in that
| it defaults to coercing the other side of the expression into this
| type, thus applying special Python conversions above and beyond those
| needed by the DBAPI to both ides. It also provides the public method
| :meth:`.TypeDecorator.coerce_compared_value` which is intended for
| end-user customization of this behavior.
|
| column_expression(self, colexpr: 'ColumnElement[_T]') -> 'Optional[ColumnElement[_T]]'
| Given a SELECT column expression, return a wrapping SQL expression.
|
| This is typically a SQL function that wraps a column expression
| as rendered in the columns clause of a SELECT statement.
| It is used for special data types that require
| columns to be wrapped in some special database function in order
| to coerce the value before being sent back to the application.
| It is the SQL analogue of the :meth:`.TypeEngine.result_processor`
| method.
|
| .. note:: The :func:`.TypeEngine.column_expression` method is applied
| only to the **outermost columns clause** of a SELECT statement, that
| is, the columns that are to be delivered directly into the returned
| result rows. It does **not** apply to the columns clause inside
| of subqueries. This necessarily avoids double conversions against
| the column and only runs the conversion when ready to be returned
| to the client.
|
| This method is called during the **SQL compilation** phase of a
| statement, when rendering a SQL string. It is **not** called
| against specific values.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.column_expression`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.column_expression`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.column_expression`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
|
| .. seealso::
|
| :ref:`types_sql_value_processing`
|
| compare_values(self, x: 'Any', y: 'Any') -> 'bool'
| Compare two values for equality.
|
| compile(self, dialect: 'Optional[Dialect]' = None) -> 'str'
| Produce a string-compiled form of this :class:`.TypeEngine`.
|
| When called with no arguments, uses a "default" dialect
| to produce a string result.
|
| :param dialect: a :class:`.Dialect` instance.
|
| copy(self, **kw: 'Any') -> 'Self'
|
| copy_value(self, value: 'Any') -> 'Any'
|
| dialect_impl(self, dialect: 'Dialect') -> 'TypeEngine[_T]'
| Return a dialect-specific implementation for this
| :class:`.TypeEngine`.
|
| evaluates_none(self) -> 'Self'
| Return a copy of this type which has the
| :attr:`.should_evaluate_none` flag set to True.
|
| E.g.::
|
| Table(
| "some_table",
| metadata,
| Column(
| String(50).evaluates_none(),
| nullable=True,
| server_default="no value",
| ),
| )
|
| The ORM uses this flag to indicate that a positive value of ``None``
| is passed to the column in an INSERT statement, rather than omitting
| the column from the INSERT statement which has the effect of firing
| off column-level defaults. It also allows for types which have
| special behavior associated with the Python None value to indicate
| that the value doesn't necessarily translate into SQL NULL; a
| prime example of this is a JSON type which may wish to persist the
| JSON value ``'null'``.
|
| In all cases, the actual NULL SQL value can be always be
| persisted in any column by using
| the :obj:`_expression.null` SQL construct in an INSERT statement
| or associated with an ORM-mapped attribute.
|
| .. note::
|
| The "evaluates none" flag does **not** apply to a value
| of ``None`` passed to :paramref:`_schema.Column.default` or
| :paramref:`_schema.Column.server_default`; in these cases,
| ``None``
| still means "no default".
|
| .. seealso::
|
| :ref:`session_forcing_null` - in the ORM documentation
|
| :paramref:`.postgresql.JSON.none_as_null` - PostgreSQL JSON
| interaction with this flag.
|
| :attr:`.TypeEngine.should_evaluate_none` - class-level flag
|
| with_variant(self, type_: '_TypeEngineArgument[Any]', *dialect_names: 'str') -> 'Self'
| Produce a copy of this type object that will utilize the given
| type when applied to the dialect of the given name.
|
| e.g.::
|
| from sqlalchemy.types import String
| from sqlalchemy.dialects import mysql
|
| string_type = String()
|
| string_type = string_type.with_variant(
| mysql.VARCHAR(collation="foo"), "mysql", "mariadb"
| )
|
| The variant mapping indicates that when this type is
| interpreted by a specific dialect, it will instead be
| transmuted into the given type, rather than using the
| primary type.
|
| .. versionchanged:: 2.0 the :meth:`_types.TypeEngine.with_variant`
| method now works with a :class:`_types.TypeEngine` object "in
| place", returning a copy of the original type rather than returning
| a wrapping object; the ``Variant`` class is no longer used.
|
| :param type\_: a :class:`.TypeEngine` that will be selected
| as a variant from the originating type, when a dialect
| of the given name is in use.
| :param \*dialect_names: one or more base names of the dialect which
| uses this type. (i.e. ``'postgresql'``, ``'mysql'``, etc.)
|
| .. versionchanged:: 2.0 multiple dialect names can be specified
| for one variant.
|
| .. seealso::
|
| :ref:`types_with_variant` - illustrates the use of
| :meth:`_types.TypeEngine.with_variant`.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.type_api.TypeEngine:
|
| __orig_bases__ = (<class 'sqlalchemy.sql.visitors.Visitable'>, typing....
|
| hashable = True
|
| render_bind_cast = False
|
| render_literal_cast = False
|
| should_evaluate_none = False
|
| sort_key_function = None
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.visitors.Visitable:
|
| __class_getitem__(key: 'Any') -> 'Any'
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__() -> 'None'
| This method is called when a class is subclassed.
|
| The default implementation does nothing. It may be
| overridden to extend subclasses.
sqlalchemy.DOUBLE
Python Library Documentation: class DOUBLE in module sqlalchemy.sql.sqltypes
class DOUBLE(Double)
| DOUBLE(precision: 'Optional[int]' = None, asdecimal: 'bool' = False, decimal_return_scale: 'Optional[int]' = None)
|
| The SQL DOUBLE type.
|
| .. versionadded:: 2.0
|
| .. seealso::
|
| :class:`_types.Double` - documentation for the base type.
|
| Method resolution order:
| DOUBLE
| Double
| Float
| Numeric
| HasExpressionLookup
| sqlalchemy.sql.type_api.TypeEngineMixin
| sqlalchemy.sql.type_api.TypeEngine
| sqlalchemy.sql.visitors.Visitable
| typing.Generic
| builtins.object
|
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| __parameters__ = ()
|
| __visit_name__ = 'DOUBLE'
|
| ----------------------------------------------------------------------
| Methods inherited from Float:
|
| __init__(self: 'Float[_N]', precision: 'Optional[int]' = None, asdecimal: 'bool' = False, decimal_return_scale: 'Optional[int]' = None)
| Construct a Float.
|
| :param precision: the numeric precision for use in DDL ``CREATE
| TABLE``. Backends **should** attempt to ensure this precision
| indicates a number of digits for the generic
| :class:`_sqltypes.Float` datatype.
|
| .. note:: For the Oracle Database backend, the
| :paramref:`_sqltypes.Float.precision` parameter is not accepted
| when rendering DDL, as Oracle Database does not support float precision
| specified as a number of decimal places. Instead, use the
| Oracle Database-specific :class:`_oracle.FLOAT` datatype and specify the
| :paramref:`_oracle.FLOAT.binary_precision` parameter. This is new
| in version 2.0 of SQLAlchemy.
|
| To create a database agnostic :class:`_types.Float` that
| separately specifies binary precision for Oracle Database, use
| :meth:`_types.TypeEngine.with_variant` as follows::
|
| from sqlalchemy import Column
| from sqlalchemy import Float
| from sqlalchemy.dialects import oracle
|
| Column(
| "float_data",
| Float(5).with_variant(oracle.FLOAT(binary_precision=16), "oracle"),
| )
|
| :param asdecimal: the same flag as that of :class:`.Numeric`, but
| defaults to ``False``. Note that setting this flag to ``True``
| results in floating point conversion.
|
| :param decimal_return_scale: Default scale to use when converting
| from floats to Python decimals. Floating point values will typically
| be much longer due to decimal inaccuracy, and most floating point
| database types don't have a notion of "scale", so by default the
| float type looks for the first ten decimal places when converting.
| Specifying this value will override that length. Note that the
| MySQL float types, which do include "scale", will use "scale"
| as the default for decimal_return_scale, if not otherwise specified.
|
| result_processor(self, dialect, coltype)
| Return a conversion function for processing result row values.
|
| Returns a callable which will receive a result row column
| value as the sole positional argument and will return a value
| to return to the user.
|
| If processing is not necessary, the method should return ``None``.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.result_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.result_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_result_value`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| :param dialect: Dialect instance in use.
|
| :param coltype: DBAPI coltype argument received in cursor.description.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from Float:
|
| scale = None
|
| ----------------------------------------------------------------------
| Methods inherited from Numeric:
|
| bind_processor(self, dialect)
| Return a conversion function for processing bind values.
|
| Returns a callable which will receive a bind parameter value
| as the sole positional argument and will return a value to
| send to the DB-API.
|
| If processing is not necessary, the method should return ``None``.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.bind_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.bind_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_bind_param`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
|
| :param dialect: Dialect instance in use.
|
| get_dbapi_type(self, dbapi)
| Return the corresponding type object from the underlying DB-API, if
| any.
|
| This can be useful for calling ``setinputsizes()``, for example.
|
| literal_processor(self, dialect)
| Return a conversion function for processing literal values that are
| to be rendered directly without using binds.
|
| This function is used when the compiler makes use of the
| "literal_binds" flag, typically used in DDL generation as well
| as in certain scenarios where backends don't accept bound parameters.
|
| Returns a callable which will receive a literal Python value
| as the sole positional argument and will return a string representation
| to be rendered in a SQL statement.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.literal_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.literal_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_literal_param`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| ----------------------------------------------------------------------
| Readonly properties inherited from Numeric:
|
| python_type
| Return the Python type object expected to be returned
| by instances of this type, if known.
|
| Basically, for those types which enforce a return type,
| or are known across the board to do such for all common
| DBAPIs (like ``int`` for example), will return that type.
|
| If a return type is not defined, raises
| ``NotImplementedError``.
|
| Note that any type also accommodates NULL in SQL which
| means you can also get back ``None`` from any type
| in practice.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from HasExpressionLookup:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from HasExpressionLookup:
|
| Comparator = <class 'sqlalchemy.sql.sqltypes.HasExpressionLookup.Compa...
|
| comparator_factory = <class 'sqlalchemy.sql.sqltypes.HasExpressionLook...
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.type_api.TypeEngine:
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| __str__(self) -> 'str'
| Return str(self).
|
| adapt(self, cls: 'Type[Union[TypeEngine[Any], TypeEngineMixin]]', **kw: 'Any') -> 'TypeEngine[Any]'
| Produce an "adapted" form of this type, given an "impl" class
| to work with.
|
| This method is used internally to associate generic
| types with "implementation" types that are specific to a particular
| dialect.
|
| as_generic(self, allow_nulltype: 'bool' = False) -> 'TypeEngine[_T]'
| Return an instance of the generic type corresponding to this type
| using heuristic rule. The method may be overridden if this
| heuristic rule is not sufficient.
|
| >>> from sqlalchemy.dialects.mysql import INTEGER
| >>> INTEGER(display_width=4).as_generic()
| Integer()
|
| >>> from sqlalchemy.dialects.mysql import NVARCHAR
| >>> NVARCHAR(length=100).as_generic()
| Unicode(length=100)
|
| .. versionadded:: 1.4.0b2
|
|
| .. seealso::
|
| :ref:`metadata_reflection_dbagnostic_types` - describes the
| use of :meth:`_types.TypeEngine.as_generic` in conjunction with
| the :meth:`_sql.DDLEvents.column_reflect` event, which is its
| intended use.
|
| bind_expression(self, bindvalue: 'BindParameter[_T]') -> 'Optional[ColumnElement[_T]]'
| Given a bind value (i.e. a :class:`.BindParameter` instance),
| return a SQL expression in its place.
|
| This is typically a SQL function that wraps the existing bound
| parameter within the statement. It is used for special data types
| that require literals being wrapped in some special database function
| in order to coerce an application-level value into a database-specific
| format. It is the SQL analogue of the
| :meth:`.TypeEngine.bind_processor` method.
|
| This method is called during the **SQL compilation** phase of a
| statement, when rendering a SQL string. It is **not** called
| against specific values.
|
| Note that this method, when implemented, should always return
| the exact same structure, without any conditional logic, as it
| may be used in an executemany() call against an arbitrary number
| of bound parameter sets.
|
| .. note::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.bind_expression`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.bind_expression`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.bind_expression`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| .. seealso::
|
| :ref:`types_sql_value_processing`
|
| coerce_compared_value(self, op: 'Optional[OperatorType]', value: 'Any') -> 'TypeEngine[Any]'
| Suggest a type for a 'coerced' Python value in an expression.
|
| Given an operator and value, gives the type a chance
| to return a type which the value should be coerced into.
|
| The default behavior here is conservative; if the right-hand
| side is already coerced into a SQL type based on its
| Python type, it is usually left alone.
|
| End-user functionality extension here should generally be via
| :class:`.TypeDecorator`, which provides more liberal behavior in that
| it defaults to coercing the other side of the expression into this
| type, thus applying special Python conversions above and beyond those
| needed by the DBAPI to both ides. It also provides the public method
| :meth:`.TypeDecorator.coerce_compared_value` which is intended for
| end-user customization of this behavior.
|
| column_expression(self, colexpr: 'ColumnElement[_T]') -> 'Optional[ColumnElement[_T]]'
| Given a SELECT column expression, return a wrapping SQL expression.
|
| This is typically a SQL function that wraps a column expression
| as rendered in the columns clause of a SELECT statement.
| It is used for special data types that require
| columns to be wrapped in some special database function in order
| to coerce the value before being sent back to the application.
| It is the SQL analogue of the :meth:`.TypeEngine.result_processor`
| method.
|
| .. note:: The :func:`.TypeEngine.column_expression` method is applied
| only to the **outermost columns clause** of a SELECT statement, that
| is, the columns that are to be delivered directly into the returned
| result rows. It does **not** apply to the columns clause inside
| of subqueries. This necessarily avoids double conversions against
| the column and only runs the conversion when ready to be returned
| to the client.
|
| This method is called during the **SQL compilation** phase of a
| statement, when rendering a SQL string. It is **not** called
| against specific values.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.column_expression`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.column_expression`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.column_expression`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
|
| .. seealso::
|
| :ref:`types_sql_value_processing`
|
| compare_values(self, x: 'Any', y: 'Any') -> 'bool'
| Compare two values for equality.
|
| compile(self, dialect: 'Optional[Dialect]' = None) -> 'str'
| Produce a string-compiled form of this :class:`.TypeEngine`.
|
| When called with no arguments, uses a "default" dialect
| to produce a string result.
|
| :param dialect: a :class:`.Dialect` instance.
|
| copy(self, **kw: 'Any') -> 'Self'
|
| copy_value(self, value: 'Any') -> 'Any'
|
| dialect_impl(self, dialect: 'Dialect') -> 'TypeEngine[_T]'
| Return a dialect-specific implementation for this
| :class:`.TypeEngine`.
|
| evaluates_none(self) -> 'Self'
| Return a copy of this type which has the
| :attr:`.should_evaluate_none` flag set to True.
|
| E.g.::
|
| Table(
| "some_table",
| metadata,
| Column(
| String(50).evaluates_none(),
| nullable=True,
| server_default="no value",
| ),
| )
|
| The ORM uses this flag to indicate that a positive value of ``None``
| is passed to the column in an INSERT statement, rather than omitting
| the column from the INSERT statement which has the effect of firing
| off column-level defaults. It also allows for types which have
| special behavior associated with the Python None value to indicate
| that the value doesn't necessarily translate into SQL NULL; a
| prime example of this is a JSON type which may wish to persist the
| JSON value ``'null'``.
|
| In all cases, the actual NULL SQL value can be always be
| persisted in any column by using
| the :obj:`_expression.null` SQL construct in an INSERT statement
| or associated with an ORM-mapped attribute.
|
| .. note::
|
| The "evaluates none" flag does **not** apply to a value
| of ``None`` passed to :paramref:`_schema.Column.default` or
| :paramref:`_schema.Column.server_default`; in these cases,
| ``None``
| still means "no default".
|
| .. seealso::
|
| :ref:`session_forcing_null` - in the ORM documentation
|
| :paramref:`.postgresql.JSON.none_as_null` - PostgreSQL JSON
| interaction with this flag.
|
| :attr:`.TypeEngine.should_evaluate_none` - class-level flag
|
| with_variant(self, type_: '_TypeEngineArgument[Any]', *dialect_names: 'str') -> 'Self'
| Produce a copy of this type object that will utilize the given
| type when applied to the dialect of the given name.
|
| e.g.::
|
| from sqlalchemy.types import String
| from sqlalchemy.dialects import mysql
|
| string_type = String()
|
| string_type = string_type.with_variant(
| mysql.VARCHAR(collation="foo"), "mysql", "mariadb"
| )
|
| The variant mapping indicates that when this type is
| interpreted by a specific dialect, it will instead be
| transmuted into the given type, rather than using the
| primary type.
|
| .. versionchanged:: 2.0 the :meth:`_types.TypeEngine.with_variant`
| method now works with a :class:`_types.TypeEngine` object "in
| place", returning a copy of the original type rather than returning
| a wrapping object; the ``Variant`` class is no longer used.
|
| :param type\_: a :class:`.TypeEngine` that will be selected
| as a variant from the originating type, when a dialect
| of the given name is in use.
| :param \*dialect_names: one or more base names of the dialect which
| uses this type. (i.e. ``'postgresql'``, ``'mysql'``, etc.)
|
| .. versionchanged:: 2.0 multiple dialect names can be specified
| for one variant.
|
| .. seealso::
|
| :ref:`types_with_variant` - illustrates the use of
| :meth:`_types.TypeEngine.with_variant`.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.type_api.TypeEngine:
|
| __orig_bases__ = (<class 'sqlalchemy.sql.visitors.Visitable'>, typing....
|
| hashable = True
|
| render_bind_cast = False
|
| render_literal_cast = False
|
| should_evaluate_none = False
|
| sort_key_function = None
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.visitors.Visitable:
|
| __class_getitem__(key: 'Any') -> 'Any'
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__() -> 'None'
| This method is called when a class is subclassed.
|
| The default implementation does nothing. It may be
| overridden to extend subclasses.
sqlalchemy.DOUBLE_PRECISION
Python Library Documentation: class DOUBLE_PRECISION in module sqlalchemy.sql.sqltypes
class DOUBLE_PRECISION(Double)
| DOUBLE_PRECISION(precision: 'Optional[int]' = None, asdecimal: 'bool' = False, decimal_return_scale: 'Optional[int]' = None)
|
| The SQL DOUBLE PRECISION type.
|
| .. versionadded:: 2.0
|
| .. seealso::
|
| :class:`_types.Double` - documentation for the base type.
|
| Method resolution order:
| DOUBLE_PRECISION
| Double
| Float
| Numeric
| HasExpressionLookup
| sqlalchemy.sql.type_api.TypeEngineMixin
| sqlalchemy.sql.type_api.TypeEngine
| sqlalchemy.sql.visitors.Visitable
| typing.Generic
| builtins.object
|
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| __parameters__ = ()
|
| __visit_name__ = 'DOUBLE_PRECISION'
|
| ----------------------------------------------------------------------
| Methods inherited from Float:
|
| __init__(self: 'Float[_N]', precision: 'Optional[int]' = None, asdecimal: 'bool' = False, decimal_return_scale: 'Optional[int]' = None)
| Construct a Float.
|
| :param precision: the numeric precision for use in DDL ``CREATE
| TABLE``. Backends **should** attempt to ensure this precision
| indicates a number of digits for the generic
| :class:`_sqltypes.Float` datatype.
|
| .. note:: For the Oracle Database backend, the
| :paramref:`_sqltypes.Float.precision` parameter is not accepted
| when rendering DDL, as Oracle Database does not support float precision
| specified as a number of decimal places. Instead, use the
| Oracle Database-specific :class:`_oracle.FLOAT` datatype and specify the
| :paramref:`_oracle.FLOAT.binary_precision` parameter. This is new
| in version 2.0 of SQLAlchemy.
|
| To create a database agnostic :class:`_types.Float` that
| separately specifies binary precision for Oracle Database, use
| :meth:`_types.TypeEngine.with_variant` as follows::
|
| from sqlalchemy import Column
| from sqlalchemy import Float
| from sqlalchemy.dialects import oracle
|
| Column(
| "float_data",
| Float(5).with_variant(oracle.FLOAT(binary_precision=16), "oracle"),
| )
|
| :param asdecimal: the same flag as that of :class:`.Numeric`, but
| defaults to ``False``. Note that setting this flag to ``True``
| results in floating point conversion.
|
| :param decimal_return_scale: Default scale to use when converting
| from floats to Python decimals. Floating point values will typically
| be much longer due to decimal inaccuracy, and most floating point
| database types don't have a notion of "scale", so by default the
| float type looks for the first ten decimal places when converting.
| Specifying this value will override that length. Note that the
| MySQL float types, which do include "scale", will use "scale"
| as the default for decimal_return_scale, if not otherwise specified.
|
| result_processor(self, dialect, coltype)
| Return a conversion function for processing result row values.
|
| Returns a callable which will receive a result row column
| value as the sole positional argument and will return a value
| to return to the user.
|
| If processing is not necessary, the method should return ``None``.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.result_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.result_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_result_value`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| :param dialect: Dialect instance in use.
|
| :param coltype: DBAPI coltype argument received in cursor.description.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from Float:
|
| scale = None
|
| ----------------------------------------------------------------------
| Methods inherited from Numeric:
|
| bind_processor(self, dialect)
| Return a conversion function for processing bind values.
|
| Returns a callable which will receive a bind parameter value
| as the sole positional argument and will return a value to
| send to the DB-API.
|
| If processing is not necessary, the method should return ``None``.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.bind_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.bind_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_bind_param`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
|
| :param dialect: Dialect instance in use.
|
| get_dbapi_type(self, dbapi)
| Return the corresponding type object from the underlying DB-API, if
| any.
|
| This can be useful for calling ``setinputsizes()``, for example.
|
| literal_processor(self, dialect)
| Return a conversion function for processing literal values that are
| to be rendered directly without using binds.
|
| This function is used when the compiler makes use of the
| "literal_binds" flag, typically used in DDL generation as well
| as in certain scenarios where backends don't accept bound parameters.
|
| Returns a callable which will receive a literal Python value
| as the sole positional argument and will return a string representation
| to be rendered in a SQL statement.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.literal_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.literal_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_literal_param`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| ----------------------------------------------------------------------
| Readonly properties inherited from Numeric:
|
| python_type
| Return the Python type object expected to be returned
| by instances of this type, if known.
|
| Basically, for those types which enforce a return type,
| or are known across the board to do such for all common
| DBAPIs (like ``int`` for example), will return that type.
|
| If a return type is not defined, raises
| ``NotImplementedError``.
|
| Note that any type also accommodates NULL in SQL which
| means you can also get back ``None`` from any type
| in practice.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from HasExpressionLookup:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from HasExpressionLookup:
|
| Comparator = <class 'sqlalchemy.sql.sqltypes.HasExpressionLookup.Compa...
|
| comparator_factory = <class 'sqlalchemy.sql.sqltypes.HasExpressionLook...
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.type_api.TypeEngine:
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| __str__(self) -> 'str'
| Return str(self).
|
| adapt(self, cls: 'Type[Union[TypeEngine[Any], TypeEngineMixin]]', **kw: 'Any') -> 'TypeEngine[Any]'
| Produce an "adapted" form of this type, given an "impl" class
| to work with.
|
| This method is used internally to associate generic
| types with "implementation" types that are specific to a particular
| dialect.
|
| as_generic(self, allow_nulltype: 'bool' = False) -> 'TypeEngine[_T]'
| Return an instance of the generic type corresponding to this type
| using heuristic rule. The method may be overridden if this
| heuristic rule is not sufficient.
|
| >>> from sqlalchemy.dialects.mysql import INTEGER
| >>> INTEGER(display_width=4).as_generic()
| Integer()
|
| >>> from sqlalchemy.dialects.mysql import NVARCHAR
| >>> NVARCHAR(length=100).as_generic()
| Unicode(length=100)
|
| .. versionadded:: 1.4.0b2
|
|
| .. seealso::
|
| :ref:`metadata_reflection_dbagnostic_types` - describes the
| use of :meth:`_types.TypeEngine.as_generic` in conjunction with
| the :meth:`_sql.DDLEvents.column_reflect` event, which is its
| intended use.
|
| bind_expression(self, bindvalue: 'BindParameter[_T]') -> 'Optional[ColumnElement[_T]]'
| Given a bind value (i.e. a :class:`.BindParameter` instance),
| return a SQL expression in its place.
|
| This is typically a SQL function that wraps the existing bound
| parameter within the statement. It is used for special data types
| that require literals being wrapped in some special database function
| in order to coerce an application-level value into a database-specific
| format. It is the SQL analogue of the
| :meth:`.TypeEngine.bind_processor` method.
|
| This method is called during the **SQL compilation** phase of a
| statement, when rendering a SQL string. It is **not** called
| against specific values.
|
| Note that this method, when implemented, should always return
| the exact same structure, without any conditional logic, as it
| may be used in an executemany() call against an arbitrary number
| of bound parameter sets.
|
| .. note::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.bind_expression`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.bind_expression`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.bind_expression`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| .. seealso::
|
| :ref:`types_sql_value_processing`
|
| coerce_compared_value(self, op: 'Optional[OperatorType]', value: 'Any') -> 'TypeEngine[Any]'
| Suggest a type for a 'coerced' Python value in an expression.
|
| Given an operator and value, gives the type a chance
| to return a type which the value should be coerced into.
|
| The default behavior here is conservative; if the right-hand
| side is already coerced into a SQL type based on its
| Python type, it is usually left alone.
|
| End-user functionality extension here should generally be via
| :class:`.TypeDecorator`, which provides more liberal behavior in that
| it defaults to coercing the other side of the expression into this
| type, thus applying special Python conversions above and beyond those
| needed by the DBAPI to both ides. It also provides the public method
| :meth:`.TypeDecorator.coerce_compared_value` which is intended for
| end-user customization of this behavior.
|
| column_expression(self, colexpr: 'ColumnElement[_T]') -> 'Optional[ColumnElement[_T]]'
| Given a SELECT column expression, return a wrapping SQL expression.
|
| This is typically a SQL function that wraps a column expression
| as rendered in the columns clause of a SELECT statement.
| It is used for special data types that require
| columns to be wrapped in some special database function in order
| to coerce the value before being sent back to the application.
| It is the SQL analogue of the :meth:`.TypeEngine.result_processor`
| method.
|
| .. note:: The :func:`.TypeEngine.column_expression` method is applied
| only to the **outermost columns clause** of a SELECT statement, that
| is, the columns that are to be delivered directly into the returned
| result rows. It does **not** apply to the columns clause inside
| of subqueries. This necessarily avoids double conversions against
| the column and only runs the conversion when ready to be returned
| to the client.
|
| This method is called during the **SQL compilation** phase of a
| statement, when rendering a SQL string. It is **not** called
| against specific values.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.column_expression`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.column_expression`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.column_expression`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
|
| .. seealso::
|
| :ref:`types_sql_value_processing`
|
| compare_values(self, x: 'Any', y: 'Any') -> 'bool'
| Compare two values for equality.
|
| compile(self, dialect: 'Optional[Dialect]' = None) -> 'str'
| Produce a string-compiled form of this :class:`.TypeEngine`.
|
| When called with no arguments, uses a "default" dialect
| to produce a string result.
|
| :param dialect: a :class:`.Dialect` instance.
|
| copy(self, **kw: 'Any') -> 'Self'
|
| copy_value(self, value: 'Any') -> 'Any'
|
| dialect_impl(self, dialect: 'Dialect') -> 'TypeEngine[_T]'
| Return a dialect-specific implementation for this
| :class:`.TypeEngine`.
|
| evaluates_none(self) -> 'Self'
| Return a copy of this type which has the
| :attr:`.should_evaluate_none` flag set to True.
|
| E.g.::
|
| Table(
| "some_table",
| metadata,
| Column(
| String(50).evaluates_none(),
| nullable=True,
| server_default="no value",
| ),
| )
|
| The ORM uses this flag to indicate that a positive value of ``None``
| is passed to the column in an INSERT statement, rather than omitting
| the column from the INSERT statement which has the effect of firing
| off column-level defaults. It also allows for types which have
| special behavior associated with the Python None value to indicate
| that the value doesn't necessarily translate into SQL NULL; a
| prime example of this is a JSON type which may wish to persist the
| JSON value ``'null'``.
|
| In all cases, the actual NULL SQL value can be always be
| persisted in any column by using
| the :obj:`_expression.null` SQL construct in an INSERT statement
| or associated with an ORM-mapped attribute.
|
| .. note::
|
| The "evaluates none" flag does **not** apply to a value
| of ``None`` passed to :paramref:`_schema.Column.default` or
| :paramref:`_schema.Column.server_default`; in these cases,
| ``None``
| still means "no default".
|
| .. seealso::
|
| :ref:`session_forcing_null` - in the ORM documentation
|
| :paramref:`.postgresql.JSON.none_as_null` - PostgreSQL JSON
| interaction with this flag.
|
| :attr:`.TypeEngine.should_evaluate_none` - class-level flag
|
| with_variant(self, type_: '_TypeEngineArgument[Any]', *dialect_names: 'str') -> 'Self'
| Produce a copy of this type object that will utilize the given
| type when applied to the dialect of the given name.
|
| e.g.::
|
| from sqlalchemy.types import String
| from sqlalchemy.dialects import mysql
|
| string_type = String()
|
| string_type = string_type.with_variant(
| mysql.VARCHAR(collation="foo"), "mysql", "mariadb"
| )
|
| The variant mapping indicates that when this type is
| interpreted by a specific dialect, it will instead be
| transmuted into the given type, rather than using the
| primary type.
|
| .. versionchanged:: 2.0 the :meth:`_types.TypeEngine.with_variant`
| method now works with a :class:`_types.TypeEngine` object "in
| place", returning a copy of the original type rather than returning
| a wrapping object; the ``Variant`` class is no longer used.
|
| :param type\_: a :class:`.TypeEngine` that will be selected
| as a variant from the originating type, when a dialect
| of the given name is in use.
| :param \*dialect_names: one or more base names of the dialect which
| uses this type. (i.e. ``'postgresql'``, ``'mysql'``, etc.)
|
| .. versionchanged:: 2.0 multiple dialect names can be specified
| for one variant.
|
| .. seealso::
|
| :ref:`types_with_variant` - illustrates the use of
| :meth:`_types.TypeEngine.with_variant`.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.type_api.TypeEngine:
|
| __orig_bases__ = (<class 'sqlalchemy.sql.visitors.Visitable'>, typing....
|
| hashable = True
|
| render_bind_cast = False
|
| render_literal_cast = False
|
| should_evaluate_none = False
|
| sort_key_function = None
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.visitors.Visitable:
|
| __class_getitem__(key: 'Any') -> 'Any'
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__() -> 'None'
| This method is called when a class is subclassed.
|
| The default implementation does nothing. It may be
| overridden to extend subclasses.
sqlalchemy.Date
Python Library Documentation: class Date in module sqlalchemy.sql.sqltypes
class Date(_RenderISO8601NoT, HasExpressionLookup, sqlalchemy.sql.type_api.TypeEngine)
| A type for ``datetime.date()`` objects.
|
| Method resolution order:
| Date
| _RenderISO8601NoT
| HasExpressionLookup
| sqlalchemy.sql.type_api.TypeEngineMixin
| sqlalchemy.sql.type_api.TypeEngine
| sqlalchemy.sql.visitors.Visitable
| typing.Generic
| builtins.object
|
| Methods defined here:
|
| get_dbapi_type(self, dbapi)
| Return the corresponding type object from the underlying DB-API, if
| any.
|
| This can be useful for calling ``setinputsizes()``, for example.
|
| literal_processor(self, dialect)
| Return a conversion function for processing literal values that are
| to be rendered directly without using binds.
|
| This function is used when the compiler makes use of the
| "literal_binds" flag, typically used in DDL generation as well
| as in certain scenarios where backends don't accept bound parameters.
|
| Returns a callable which will receive a literal Python value
| as the sole positional argument and will return a string representation
| to be rendered in a SQL statement.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.literal_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.literal_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_literal_param`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| ----------------------------------------------------------------------
| Readonly properties defined here:
|
| python_type
| Return the Python type object expected to be returned
| by instances of this type, if known.
|
| Basically, for those types which enforce a return type,
| or are known across the board to do such for all common
| DBAPIs (like ``int`` for example), will return that type.
|
| If a return type is not defined, raises
| ``NotImplementedError``.
|
| Note that any type also accommodates NULL in SQL which
| means you can also get back ``None`` from any type
| in practice.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| __parameters__ = ()
|
| __visit_name__ = 'date'
|
| ----------------------------------------------------------------------
| Data descriptors inherited from _RenderISO8601NoT:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from HasExpressionLookup:
|
| Comparator = <class 'sqlalchemy.sql.sqltypes.HasExpressionLookup.Compa...
|
| comparator_factory = <class 'sqlalchemy.sql.sqltypes.HasExpressionLook...
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.type_api.TypeEngine:
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| __str__(self) -> 'str'
| Return str(self).
|
| adapt(self, cls: 'Type[Union[TypeEngine[Any], TypeEngineMixin]]', **kw: 'Any') -> 'TypeEngine[Any]'
| Produce an "adapted" form of this type, given an "impl" class
| to work with.
|
| This method is used internally to associate generic
| types with "implementation" types that are specific to a particular
| dialect.
|
| as_generic(self, allow_nulltype: 'bool' = False) -> 'TypeEngine[_T]'
| Return an instance of the generic type corresponding to this type
| using heuristic rule. The method may be overridden if this
| heuristic rule is not sufficient.
|
| >>> from sqlalchemy.dialects.mysql import INTEGER
| >>> INTEGER(display_width=4).as_generic()
| Integer()
|
| >>> from sqlalchemy.dialects.mysql import NVARCHAR
| >>> NVARCHAR(length=100).as_generic()
| Unicode(length=100)
|
| .. versionadded:: 1.4.0b2
|
|
| .. seealso::
|
| :ref:`metadata_reflection_dbagnostic_types` - describes the
| use of :meth:`_types.TypeEngine.as_generic` in conjunction with
| the :meth:`_sql.DDLEvents.column_reflect` event, which is its
| intended use.
|
| bind_expression(self, bindvalue: 'BindParameter[_T]') -> 'Optional[ColumnElement[_T]]'
| Given a bind value (i.e. a :class:`.BindParameter` instance),
| return a SQL expression in its place.
|
| This is typically a SQL function that wraps the existing bound
| parameter within the statement. It is used for special data types
| that require literals being wrapped in some special database function
| in order to coerce an application-level value into a database-specific
| format. It is the SQL analogue of the
| :meth:`.TypeEngine.bind_processor` method.
|
| This method is called during the **SQL compilation** phase of a
| statement, when rendering a SQL string. It is **not** called
| against specific values.
|
| Note that this method, when implemented, should always return
| the exact same structure, without any conditional logic, as it
| may be used in an executemany() call against an arbitrary number
| of bound parameter sets.
|
| .. note::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.bind_expression`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.bind_expression`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.bind_expression`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| .. seealso::
|
| :ref:`types_sql_value_processing`
|
| bind_processor(self, dialect: 'Dialect') -> 'Optional[_BindProcessorType[_T]]'
| Return a conversion function for processing bind values.
|
| Returns a callable which will receive a bind parameter value
| as the sole positional argument and will return a value to
| send to the DB-API.
|
| If processing is not necessary, the method should return ``None``.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.bind_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.bind_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_bind_param`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
|
| :param dialect: Dialect instance in use.
|
| coerce_compared_value(self, op: 'Optional[OperatorType]', value: 'Any') -> 'TypeEngine[Any]'
| Suggest a type for a 'coerced' Python value in an expression.
|
| Given an operator and value, gives the type a chance
| to return a type which the value should be coerced into.
|
| The default behavior here is conservative; if the right-hand
| side is already coerced into a SQL type based on its
| Python type, it is usually left alone.
|
| End-user functionality extension here should generally be via
| :class:`.TypeDecorator`, which provides more liberal behavior in that
| it defaults to coercing the other side of the expression into this
| type, thus applying special Python conversions above and beyond those
| needed by the DBAPI to both ides. It also provides the public method
| :meth:`.TypeDecorator.coerce_compared_value` which is intended for
| end-user customization of this behavior.
|
| column_expression(self, colexpr: 'ColumnElement[_T]') -> 'Optional[ColumnElement[_T]]'
| Given a SELECT column expression, return a wrapping SQL expression.
|
| This is typically a SQL function that wraps a column expression
| as rendered in the columns clause of a SELECT statement.
| It is used for special data types that require
| columns to be wrapped in some special database function in order
| to coerce the value before being sent back to the application.
| It is the SQL analogue of the :meth:`.TypeEngine.result_processor`
| method.
|
| .. note:: The :func:`.TypeEngine.column_expression` method is applied
| only to the **outermost columns clause** of a SELECT statement, that
| is, the columns that are to be delivered directly into the returned
| result rows. It does **not** apply to the columns clause inside
| of subqueries. This necessarily avoids double conversions against
| the column and only runs the conversion when ready to be returned
| to the client.
|
| This method is called during the **SQL compilation** phase of a
| statement, when rendering a SQL string. It is **not** called
| against specific values.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.column_expression`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.column_expression`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.column_expression`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
|
| .. seealso::
|
| :ref:`types_sql_value_processing`
|
| compare_values(self, x: 'Any', y: 'Any') -> 'bool'
| Compare two values for equality.
|
| compile(self, dialect: 'Optional[Dialect]' = None) -> 'str'
| Produce a string-compiled form of this :class:`.TypeEngine`.
|
| When called with no arguments, uses a "default" dialect
| to produce a string result.
|
| :param dialect: a :class:`.Dialect` instance.
|
| copy(self, **kw: 'Any') -> 'Self'
|
| copy_value(self, value: 'Any') -> 'Any'
|
| dialect_impl(self, dialect: 'Dialect') -> 'TypeEngine[_T]'
| Return a dialect-specific implementation for this
| :class:`.TypeEngine`.
|
| evaluates_none(self) -> 'Self'
| Return a copy of this type which has the
| :attr:`.should_evaluate_none` flag set to True.
|
| E.g.::
|
| Table(
| "some_table",
| metadata,
| Column(
| String(50).evaluates_none(),
| nullable=True,
| server_default="no value",
| ),
| )
|
| The ORM uses this flag to indicate that a positive value of ``None``
| is passed to the column in an INSERT statement, rather than omitting
| the column from the INSERT statement which has the effect of firing
| off column-level defaults. It also allows for types which have
| special behavior associated with the Python None value to indicate
| that the value doesn't necessarily translate into SQL NULL; a
| prime example of this is a JSON type which may wish to persist the
| JSON value ``'null'``.
|
| In all cases, the actual NULL SQL value can be always be
| persisted in any column by using
| the :obj:`_expression.null` SQL construct in an INSERT statement
| or associated with an ORM-mapped attribute.
|
| .. note::
|
| The "evaluates none" flag does **not** apply to a value
| of ``None`` passed to :paramref:`_schema.Column.default` or
| :paramref:`_schema.Column.server_default`; in these cases,
| ``None``
| still means "no default".
|
| .. seealso::
|
| :ref:`session_forcing_null` - in the ORM documentation
|
| :paramref:`.postgresql.JSON.none_as_null` - PostgreSQL JSON
| interaction with this flag.
|
| :attr:`.TypeEngine.should_evaluate_none` - class-level flag
|
| result_processor(self, dialect: 'Dialect', coltype: 'object') -> 'Optional[_ResultProcessorType[_T]]'
| Return a conversion function for processing result row values.
|
| Returns a callable which will receive a result row column
| value as the sole positional argument and will return a value
| to return to the user.
|
| If processing is not necessary, the method should return ``None``.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.result_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.result_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_result_value`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| :param dialect: Dialect instance in use.
|
| :param coltype: DBAPI coltype argument received in cursor.description.
|
| with_variant(self, type_: '_TypeEngineArgument[Any]', *dialect_names: 'str') -> 'Self'
| Produce a copy of this type object that will utilize the given
| type when applied to the dialect of the given name.
|
| e.g.::
|
| from sqlalchemy.types import String
| from sqlalchemy.dialects import mysql
|
| string_type = String()
|
| string_type = string_type.with_variant(
| mysql.VARCHAR(collation="foo"), "mysql", "mariadb"
| )
|
| The variant mapping indicates that when this type is
| interpreted by a specific dialect, it will instead be
| transmuted into the given type, rather than using the
| primary type.
|
| .. versionchanged:: 2.0 the :meth:`_types.TypeEngine.with_variant`
| method now works with a :class:`_types.TypeEngine` object "in
| place", returning a copy of the original type rather than returning
| a wrapping object; the ``Variant`` class is no longer used.
|
| :param type\_: a :class:`.TypeEngine` that will be selected
| as a variant from the originating type, when a dialect
| of the given name is in use.
| :param \*dialect_names: one or more base names of the dialect which
| uses this type. (i.e. ``'postgresql'``, ``'mysql'``, etc.)
|
| .. versionchanged:: 2.0 multiple dialect names can be specified
| for one variant.
|
| .. seealso::
|
| :ref:`types_with_variant` - illustrates the use of
| :meth:`_types.TypeEngine.with_variant`.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.type_api.TypeEngine:
|
| __orig_bases__ = (<class 'sqlalchemy.sql.visitors.Visitable'>, typing....
|
| hashable = True
|
| render_bind_cast = False
|
| render_literal_cast = False
|
| should_evaluate_none = False
|
| sort_key_function = None
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.visitors.Visitable:
|
| __class_getitem__(key: 'Any') -> 'Any'
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__() -> 'None'
| This method is called when a class is subclassed.
|
| The default implementation does nothing. It may be
| overridden to extend subclasses.
sqlalchemy.DateTime
Python Library Documentation: class DateTime in module sqlalchemy.sql.sqltypes
class DateTime(_RenderISO8601NoT, HasExpressionLookup, sqlalchemy.sql.type_api.TypeEngine)
| DateTime(timezone: 'bool' = False)
|
| A type for ``datetime.datetime()`` objects.
|
| Date and time types return objects from the Python ``datetime``
| module. Most DBAPIs have built in support for the datetime
| module, with the noted exception of SQLite. In the case of
| SQLite, date and time types are stored as strings which are then
| converted back to datetime objects when rows are returned.
|
| For the time representation within the datetime type, some
| backends include additional options, such as timezone support and
| fractional seconds support. For fractional seconds, use the
| dialect-specific datatype, such as :class:`.mysql.TIME`. For
| timezone support, use at least the :class:`_types.TIMESTAMP` datatype,
| if not the dialect-specific datatype object.
|
| Method resolution order:
| DateTime
| _RenderISO8601NoT
| HasExpressionLookup
| sqlalchemy.sql.type_api.TypeEngineMixin
| sqlalchemy.sql.type_api.TypeEngine
| sqlalchemy.sql.visitors.Visitable
| typing.Generic
| builtins.object
|
| Methods defined here:
|
| __init__(self, timezone: 'bool' = False)
| Construct a new :class:`.DateTime`.
|
| :param timezone: boolean. Indicates that the datetime type should
| enable timezone support, if available on the
| **base date/time-holding type only**. It is recommended
| to make use of the :class:`_types.TIMESTAMP` datatype directly when
| using this flag, as some databases include separate generic
| date/time-holding types distinct from the timezone-capable
| TIMESTAMP datatype, such as Oracle Database.
|
| get_dbapi_type(self, dbapi)
| Return the corresponding type object from the underlying DB-API, if
| any.
|
| This can be useful for calling ``setinputsizes()``, for example.
|
| literal_processor(self, dialect)
| Return a conversion function for processing literal values that are
| to be rendered directly without using binds.
|
| This function is used when the compiler makes use of the
| "literal_binds" flag, typically used in DDL generation as well
| as in certain scenarios where backends don't accept bound parameters.
|
| Returns a callable which will receive a literal Python value
| as the sole positional argument and will return a string representation
| to be rendered in a SQL statement.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.literal_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.literal_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_literal_param`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| ----------------------------------------------------------------------
| Readonly properties defined here:
|
| python_type
| Return the Python type object expected to be returned
| by instances of this type, if known.
|
| Basically, for those types which enforce a return type,
| or are known across the board to do such for all common
| DBAPIs (like ``int`` for example), will return that type.
|
| If a return type is not defined, raises
| ``NotImplementedError``.
|
| Note that any type also accommodates NULL in SQL which
| means you can also get back ``None`` from any type
| in practice.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| __parameters__ = ()
|
| __visit_name__ = 'datetime'
|
| ----------------------------------------------------------------------
| Data descriptors inherited from _RenderISO8601NoT:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from HasExpressionLookup:
|
| Comparator = <class 'sqlalchemy.sql.sqltypes.HasExpressionLookup.Compa...
|
| comparator_factory = <class 'sqlalchemy.sql.sqltypes.HasExpressionLook...
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.type_api.TypeEngine:
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| __str__(self) -> 'str'
| Return str(self).
|
| adapt(self, cls: 'Type[Union[TypeEngine[Any], TypeEngineMixin]]', **kw: 'Any') -> 'TypeEngine[Any]'
| Produce an "adapted" form of this type, given an "impl" class
| to work with.
|
| This method is used internally to associate generic
| types with "implementation" types that are specific to a particular
| dialect.
|
| as_generic(self, allow_nulltype: 'bool' = False) -> 'TypeEngine[_T]'
| Return an instance of the generic type corresponding to this type
| using heuristic rule. The method may be overridden if this
| heuristic rule is not sufficient.
|
| >>> from sqlalchemy.dialects.mysql import INTEGER
| >>> INTEGER(display_width=4).as_generic()
| Integer()
|
| >>> from sqlalchemy.dialects.mysql import NVARCHAR
| >>> NVARCHAR(length=100).as_generic()
| Unicode(length=100)
|
| .. versionadded:: 1.4.0b2
|
|
| .. seealso::
|
| :ref:`metadata_reflection_dbagnostic_types` - describes the
| use of :meth:`_types.TypeEngine.as_generic` in conjunction with
| the :meth:`_sql.DDLEvents.column_reflect` event, which is its
| intended use.
|
| bind_expression(self, bindvalue: 'BindParameter[_T]') -> 'Optional[ColumnElement[_T]]'
| Given a bind value (i.e. a :class:`.BindParameter` instance),
| return a SQL expression in its place.
|
| This is typically a SQL function that wraps the existing bound
| parameter within the statement. It is used for special data types
| that require literals being wrapped in some special database function
| in order to coerce an application-level value into a database-specific
| format. It is the SQL analogue of the
| :meth:`.TypeEngine.bind_processor` method.
|
| This method is called during the **SQL compilation** phase of a
| statement, when rendering a SQL string. It is **not** called
| against specific values.
|
| Note that this method, when implemented, should always return
| the exact same structure, without any conditional logic, as it
| may be used in an executemany() call against an arbitrary number
| of bound parameter sets.
|
| .. note::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.bind_expression`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.bind_expression`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.bind_expression`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| .. seealso::
|
| :ref:`types_sql_value_processing`
|
| bind_processor(self, dialect: 'Dialect') -> 'Optional[_BindProcessorType[_T]]'
| Return a conversion function for processing bind values.
|
| Returns a callable which will receive a bind parameter value
| as the sole positional argument and will return a value to
| send to the DB-API.
|
| If processing is not necessary, the method should return ``None``.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.bind_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.bind_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_bind_param`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
|
| :param dialect: Dialect instance in use.
|
| coerce_compared_value(self, op: 'Optional[OperatorType]', value: 'Any') -> 'TypeEngine[Any]'
| Suggest a type for a 'coerced' Python value in an expression.
|
| Given an operator and value, gives the type a chance
| to return a type which the value should be coerced into.
|
| The default behavior here is conservative; if the right-hand
| side is already coerced into a SQL type based on its
| Python type, it is usually left alone.
|
| End-user functionality extension here should generally be via
| :class:`.TypeDecorator`, which provides more liberal behavior in that
| it defaults to coercing the other side of the expression into this
| type, thus applying special Python conversions above and beyond those
| needed by the DBAPI to both ides. It also provides the public method
| :meth:`.TypeDecorator.coerce_compared_value` which is intended for
| end-user customization of this behavior.
|
| column_expression(self, colexpr: 'ColumnElement[_T]') -> 'Optional[ColumnElement[_T]]'
| Given a SELECT column expression, return a wrapping SQL expression.
|
| This is typically a SQL function that wraps a column expression
| as rendered in the columns clause of a SELECT statement.
| It is used for special data types that require
| columns to be wrapped in some special database function in order
| to coerce the value before being sent back to the application.
| It is the SQL analogue of the :meth:`.TypeEngine.result_processor`
| method.
|
| .. note:: The :func:`.TypeEngine.column_expression` method is applied
| only to the **outermost columns clause** of a SELECT statement, that
| is, the columns that are to be delivered directly into the returned
| result rows. It does **not** apply to the columns clause inside
| of subqueries. This necessarily avoids double conversions against
| the column and only runs the conversion when ready to be returned
| to the client.
|
| This method is called during the **SQL compilation** phase of a
| statement, when rendering a SQL string. It is **not** called
| against specific values.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.column_expression`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.column_expression`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.column_expression`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
|
| .. seealso::
|
| :ref:`types_sql_value_processing`
|
| compare_values(self, x: 'Any', y: 'Any') -> 'bool'
| Compare two values for equality.
|
| compile(self, dialect: 'Optional[Dialect]' = None) -> 'str'
| Produce a string-compiled form of this :class:`.TypeEngine`.
|
| When called with no arguments, uses a "default" dialect
| to produce a string result.
|
| :param dialect: a :class:`.Dialect` instance.
|
| copy(self, **kw: 'Any') -> 'Self'
|
| copy_value(self, value: 'Any') -> 'Any'
|
| dialect_impl(self, dialect: 'Dialect') -> 'TypeEngine[_T]'
| Return a dialect-specific implementation for this
| :class:`.TypeEngine`.
|
| evaluates_none(self) -> 'Self'
| Return a copy of this type which has the
| :attr:`.should_evaluate_none` flag set to True.
|
| E.g.::
|
| Table(
| "some_table",
| metadata,
| Column(
| String(50).evaluates_none(),
| nullable=True,
| server_default="no value",
| ),
| )
|
| The ORM uses this flag to indicate that a positive value of ``None``
| is passed to the column in an INSERT statement, rather than omitting
| the column from the INSERT statement which has the effect of firing
| off column-level defaults. It also allows for types which have
| special behavior associated with the Python None value to indicate
| that the value doesn't necessarily translate into SQL NULL; a
| prime example of this is a JSON type which may wish to persist the
| JSON value ``'null'``.
|
| In all cases, the actual NULL SQL value can be always be
| persisted in any column by using
| the :obj:`_expression.null` SQL construct in an INSERT statement
| or associated with an ORM-mapped attribute.
|
| .. note::
|
| The "evaluates none" flag does **not** apply to a value
| of ``None`` passed to :paramref:`_schema.Column.default` or
| :paramref:`_schema.Column.server_default`; in these cases,
| ``None``
| still means "no default".
|
| .. seealso::
|
| :ref:`session_forcing_null` - in the ORM documentation
|
| :paramref:`.postgresql.JSON.none_as_null` - PostgreSQL JSON
| interaction with this flag.
|
| :attr:`.TypeEngine.should_evaluate_none` - class-level flag
|
| result_processor(self, dialect: 'Dialect', coltype: 'object') -> 'Optional[_ResultProcessorType[_T]]'
| Return a conversion function for processing result row values.
|
| Returns a callable which will receive a result row column
| value as the sole positional argument and will return a value
| to return to the user.
|
| If processing is not necessary, the method should return ``None``.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.result_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.result_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_result_value`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| :param dialect: Dialect instance in use.
|
| :param coltype: DBAPI coltype argument received in cursor.description.
|
| with_variant(self, type_: '_TypeEngineArgument[Any]', *dialect_names: 'str') -> 'Self'
| Produce a copy of this type object that will utilize the given
| type when applied to the dialect of the given name.
|
| e.g.::
|
| from sqlalchemy.types import String
| from sqlalchemy.dialects import mysql
|
| string_type = String()
|
| string_type = string_type.with_variant(
| mysql.VARCHAR(collation="foo"), "mysql", "mariadb"
| )
|
| The variant mapping indicates that when this type is
| interpreted by a specific dialect, it will instead be
| transmuted into the given type, rather than using the
| primary type.
|
| .. versionchanged:: 2.0 the :meth:`_types.TypeEngine.with_variant`
| method now works with a :class:`_types.TypeEngine` object "in
| place", returning a copy of the original type rather than returning
| a wrapping object; the ``Variant`` class is no longer used.
|
| :param type\_: a :class:`.TypeEngine` that will be selected
| as a variant from the originating type, when a dialect
| of the given name is in use.
| :param \*dialect_names: one or more base names of the dialect which
| uses this type. (i.e. ``'postgresql'``, ``'mysql'``, etc.)
|
| .. versionchanged:: 2.0 multiple dialect names can be specified
| for one variant.
|
| .. seealso::
|
| :ref:`types_with_variant` - illustrates the use of
| :meth:`_types.TypeEngine.with_variant`.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.type_api.TypeEngine:
|
| __orig_bases__ = (<class 'sqlalchemy.sql.visitors.Visitable'>, typing....
|
| hashable = True
|
| render_bind_cast = False
|
| render_literal_cast = False
|
| should_evaluate_none = False
|
| sort_key_function = None
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.visitors.Visitable:
|
| __class_getitem__(key: 'Any') -> 'Any'
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__() -> 'None'
| This method is called when a class is subclassed.
|
| The default implementation does nothing. It may be
| overridden to extend subclasses.
sqlalchemy.DefaultClause
Python Library Documentation: class DefaultClause in module sqlalchemy.sql.schema
class DefaultClause(FetchedValue)
| DefaultClause(arg: 'Union[str, ClauseElement, TextClause]', for_update: 'bool' = False, _reflected: 'bool' = False) -> 'None'
|
| A DDL-specified DEFAULT column value.
|
| :class:`.DefaultClause` is a :class:`.FetchedValue`
| that also generates a "DEFAULT" clause when
| "CREATE TABLE" is emitted.
|
| :class:`.DefaultClause` is generated automatically
| whenever the ``server_default``, ``server_onupdate`` arguments of
| :class:`_schema.Column` are used. A :class:`.DefaultClause`
| can be passed positionally as well.
|
| For example, the following::
|
| Column("foo", Integer, server_default="50")
|
| Is equivalent to::
|
| Column("foo", Integer, DefaultClause("50"))
|
| Method resolution order:
| DefaultClause
| FetchedValue
| sqlalchemy.sql.base.SchemaEventTarget
| sqlalchemy.event.registry.EventTarget
| builtins.object
|
| Methods defined here:
|
| __init__(self, arg: 'Union[str, ClauseElement, TextClause]', for_update: 'bool' = False, _reflected: 'bool' = False) -> 'None'
| Initialize self. See help(type(self)) for accurate signature.
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| has_argument = True
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from FetchedValue:
|
| is_clause_element = False
|
| is_identity = False
|
| is_server_default = True
|
| reflected = False
|
| ----------------------------------------------------------------------
| Data descriptors inherited from sqlalchemy.sql.base.SchemaEventTarget:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.base.SchemaEventTarget:
|
| dispatch = <sqlalchemy.event.base.DDLEventsDispatch object>
sqlalchemy.Delete
Python Library Documentation: class Delete in module sqlalchemy.sql.dml
class Delete(DMLWhereBase, UpdateBase)
| Delete(table: '_DMLTableArgument')
|
| Represent a DELETE construct.
|
| The :class:`_expression.Delete` object is created using the
| :func:`_expression.delete()` function.
|
| Method resolution order:
| Delete
| DMLWhereBase
| UpdateBase
| sqlalchemy.sql.roles.DMLRole
| sqlalchemy.sql.selectable.HasCTE
| sqlalchemy.sql.roles.HasCTERole
| sqlalchemy.sql.selectable.SelectsRows
| sqlalchemy.sql.base.HasCompileState
| sqlalchemy.sql.base.DialectKWArgs
| sqlalchemy.sql.selectable.HasPrefixes
| sqlalchemy.sql.base.Generative
| sqlalchemy.sql.selectable.ExecutableReturnsRows
| sqlalchemy.sql.base.Executable
| sqlalchemy.sql.roles.StatementRole
| sqlalchemy.sql.selectable.ReturnsRows
| sqlalchemy.sql.roles.ReturnsRowsRole
| sqlalchemy.sql.roles.SQLRole
| sqlalchemy.sql.elements.DQLDMLClauseElement
| sqlalchemy.sql.elements.ClauseElement
| sqlalchemy.sql.annotation.SupportsWrappingAnnotations
| sqlalchemy.sql.annotation.SupportsAnnotations
| sqlalchemy.sql.cache_key.MemoizedHasCacheKey
| sqlalchemy.sql.cache_key.HasCacheKey
| sqlalchemy.util.langhelpers.HasMemoized
| sqlalchemy.sql.traversals.HasCopyInternals
| sqlalchemy.sql.visitors.ExternallyTraversible
| sqlalchemy.sql.visitors.HasTraverseInternals
| sqlalchemy.sql.elements.CompilerElement
| sqlalchemy.sql.visitors.Visitable
| builtins.object
|
| Methods defined here:
|
| __init__(self, table: '_DMLTableArgument')
| Initialize self. See help(type(self)) for accurate signature.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| __visit_name__ = 'delete'
|
| is_delete = True
|
| ----------------------------------------------------------------------
| Methods inherited from DMLWhereBase:
|
| filter(self, *criteria: 'roles.ExpressionElementRole[Any]') -> 'Self'
| A synonym for the :meth:`_dml.DMLWhereBase.where` method.
|
| .. versionadded:: 1.4
|
| filter_by(self, **kwargs: 'Any') -> 'Self'
| apply the given filtering criterion as a WHERE clause
| to this select.
|
| where(self, *whereclause: '_ColumnExpressionArgument[bool]') -> 'Self'
| Return a new construct with the given expression(s) added to
| its WHERE clause, joined to the existing clause via AND, if any.
|
| Both :meth:`_dml.Update.where` and :meth:`_dml.Delete.where`
| support multiple-table forms, including database-specific
| ``UPDATE...FROM`` as well as ``DELETE..USING``. For backends that
| don't have multiple-table support, a backend agnostic approach
| to using multiple tables is to make use of correlated subqueries.
| See the linked tutorial sections below for examples.
|
| .. seealso::
|
| :ref:`tutorial_correlated_updates`
|
| :ref:`tutorial_update_from`
|
| :ref:`tutorial_multi_table_deletes`
|
| ----------------------------------------------------------------------
| Readonly properties inherited from DMLWhereBase:
|
| whereclause
| Return the completed WHERE clause for this :class:`.DMLWhereBase`
| statement.
|
| This assembles the current collection of WHERE criteria
| into a single :class:`_expression.BooleanClauseList` construct.
|
|
| .. versionadded:: 1.4
|
| ----------------------------------------------------------------------
| Data descriptors inherited from DMLWhereBase:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Methods inherited from UpdateBase:
|
| corresponding_column(self, column: 'KeyedColumnElement[Any]', require_embedded: 'bool' = False) -> 'Optional[ColumnElement[Any]]'
|
| exported_columns(...)
| Return the RETURNING columns as a column collection for this
| statement.
|
| .. versionadded:: 1.4
|
| is_derived_from(self, fromclause: 'Optional[FromClause]') -> 'bool'
| Return ``True`` if this :class:`.ReturnsRows` is
| 'derived' from the given :class:`.FromClause`.
|
| Since these are DMLs, we dont want such statements ever being adapted
| so we return False for derives.
|
| params(self, *arg: 'Any', **kw: 'Any') -> 'NoReturn'
| Set the parameters for the statement.
|
| This method raises ``NotImplementedError`` on the base class,
| and is overridden by :class:`.ValuesBase` to provide the
| SET/VALUES clause of UPDATE and INSERT.
|
| return_defaults(self, *cols: '_DMLColumnArgument', supplemental_cols: 'Optional[Iterable[_DMLColumnArgument]]' = None, sort_by_parameter_order: 'bool' = False) -> 'Self'
| Make use of a :term:`RETURNING` clause for the purpose
| of fetching server-side expressions and defaults, for supporting
| backends only.
|
| .. deepalchemy::
|
| The :meth:`.UpdateBase.return_defaults` method is used by the ORM
| for its internal work in fetching newly generated primary key
| and server default values, in particular to provide the underlying
| implementation of the :paramref:`_orm.Mapper.eager_defaults`
| ORM feature as well as to allow RETURNING support with bulk
| ORM inserts. Its behavior is fairly idiosyncratic
| and is not really intended for general use. End users should
| stick with using :meth:`.UpdateBase.returning` in order to
| add RETURNING clauses to their INSERT, UPDATE and DELETE
| statements.
|
| Normally, a single row INSERT statement will automatically populate the
| :attr:`.CursorResult.inserted_primary_key` attribute when executed,
| which stores the primary key of the row that was just inserted in the
| form of a :class:`.Row` object with column names as named tuple keys
| (and the :attr:`.Row._mapping` view fully populated as well). The
| dialect in use chooses the strategy to use in order to populate this
| data; if it was generated using server-side defaults and / or SQL
| expressions, dialect-specific approaches such as ``cursor.lastrowid``
| or ``RETURNING`` are typically used to acquire the new primary key
| value.
|
| However, when the statement is modified by calling
| :meth:`.UpdateBase.return_defaults` before executing the statement,
| additional behaviors take place **only** for backends that support
| RETURNING and for :class:`.Table` objects that maintain the
| :paramref:`.Table.implicit_returning` parameter at its default value of
| ``True``. In these cases, when the :class:`.CursorResult` is returned
| from the statement's execution, not only will
| :attr:`.CursorResult.inserted_primary_key` be populated as always, the
| :attr:`.CursorResult.returned_defaults` attribute will also be
| populated with a :class:`.Row` named-tuple representing the full range
| of server generated
| values from that single row, including values for any columns that
| specify :paramref:`_schema.Column.server_default` or which make use of
| :paramref:`_schema.Column.default` using a SQL expression.
|
| When invoking INSERT statements with multiple rows using
| :ref:`insertmanyvalues <engine_insertmanyvalues>`, the
| :meth:`.UpdateBase.return_defaults` modifier will have the effect of
| the :attr:`_engine.CursorResult.inserted_primary_key_rows` and
| :attr:`_engine.CursorResult.returned_defaults_rows` attributes being
| fully populated with lists of :class:`.Row` objects representing newly
| inserted primary key values as well as newly inserted server generated
| values for each row inserted. The
| :attr:`.CursorResult.inserted_primary_key` and
| :attr:`.CursorResult.returned_defaults` attributes will also continue
| to be populated with the first row of these two collections.
|
| If the backend does not support RETURNING or the :class:`.Table` in use
| has disabled :paramref:`.Table.implicit_returning`, then no RETURNING
| clause is added and no additional data is fetched, however the
| INSERT, UPDATE or DELETE statement proceeds normally.
|
| E.g.::
|
| stmt = table.insert().values(data="newdata").return_defaults()
|
| result = connection.execute(stmt)
|
| server_created_at = result.returned_defaults["created_at"]
|
| When used against an UPDATE statement
| :meth:`.UpdateBase.return_defaults` instead looks for columns that
| include :paramref:`_schema.Column.onupdate` or
| :paramref:`_schema.Column.server_onupdate` parameters assigned, when
| constructing the columns that will be included in the RETURNING clause
| by default if explicit columns were not specified. When used against a
| DELETE statement, no columns are included in RETURNING by default, they
| instead must be specified explicitly as there are no columns that
| normally change values when a DELETE statement proceeds.
|
| .. versionadded:: 2.0 :meth:`.UpdateBase.return_defaults` is supported
| for DELETE statements also and has been moved from
| :class:`.ValuesBase` to :class:`.UpdateBase`.
|
| The :meth:`.UpdateBase.return_defaults` method is mutually exclusive
| against the :meth:`.UpdateBase.returning` method and errors will be
| raised during the SQL compilation process if both are used at the same
| time on one statement. The RETURNING clause of the INSERT, UPDATE or
| DELETE statement is therefore controlled by only one of these methods
| at a time.
|
| The :meth:`.UpdateBase.return_defaults` method differs from
| :meth:`.UpdateBase.returning` in these ways:
|
| 1. :meth:`.UpdateBase.return_defaults` method causes the
| :attr:`.CursorResult.returned_defaults` collection to be populated
| with the first row from the RETURNING result. This attribute is not
| populated when using :meth:`.UpdateBase.returning`.
|
| 2. :meth:`.UpdateBase.return_defaults` is compatible with existing
| logic used to fetch auto-generated primary key values that are then
| populated into the :attr:`.CursorResult.inserted_primary_key`
| attribute. By contrast, using :meth:`.UpdateBase.returning` will
| have the effect of the :attr:`.CursorResult.inserted_primary_key`
| attribute being left unpopulated.
|
| 3. :meth:`.UpdateBase.return_defaults` can be called against any
| backend. Backends that don't support RETURNING will skip the usage
| of the feature, rather than raising an exception, *unless*
| ``supplemental_cols`` is passed. The return value
| of :attr:`_engine.CursorResult.returned_defaults` will be ``None``
| for backends that don't support RETURNING or for which the target
| :class:`.Table` sets :paramref:`.Table.implicit_returning` to
| ``False``.
|
| 4. An INSERT statement invoked with executemany() is supported if the
| backend database driver supports the
| :ref:`insertmanyvalues <engine_insertmanyvalues>`
| feature which is now supported by most SQLAlchemy-included backends.
| When executemany is used, the
| :attr:`_engine.CursorResult.returned_defaults_rows` and
| :attr:`_engine.CursorResult.inserted_primary_key_rows` accessors
| will return the inserted defaults and primary keys.
|
| .. versionadded:: 1.4 Added
| :attr:`_engine.CursorResult.returned_defaults_rows` and
| :attr:`_engine.CursorResult.inserted_primary_key_rows` accessors.
| In version 2.0, the underlying implementation which fetches and
| populates the data for these attributes was generalized to be
| supported by most backends, whereas in 1.4 they were only
| supported by the ``psycopg2`` driver.
|
|
| :param cols: optional list of column key names or
| :class:`_schema.Column` that acts as a filter for those columns that
| will be fetched.
| :param supplemental_cols: optional list of RETURNING expressions,
| in the same form as one would pass to the
| :meth:`.UpdateBase.returning` method. When present, the additional
| columns will be included in the RETURNING clause, and the
| :class:`.CursorResult` object will be "rewound" when returned, so
| that methods like :meth:`.CursorResult.all` will return new rows
| mostly as though the statement used :meth:`.UpdateBase.returning`
| directly. However, unlike when using :meth:`.UpdateBase.returning`
| directly, the **order of the columns is undefined**, so can only be
| targeted using names or :attr:`.Row._mapping` keys; they cannot
| reliably be targeted positionally.
|
| .. versionadded:: 2.0
|
| :param sort_by_parameter_order: for a batch INSERT that is being
| executed against multiple parameter sets, organize the results of
| RETURNING so that the returned rows correspond to the order of
| parameter sets passed in. This applies only to an :term:`executemany`
| execution for supporting dialects and typically makes use of the
| :term:`insertmanyvalues` feature.
|
| .. versionadded:: 2.0.10
|
| .. seealso::
|
| :ref:`engine_insertmanyvalues_returning_order` - background on
| sorting of RETURNING rows for bulk INSERT
|
| .. seealso::
|
| :meth:`.UpdateBase.returning`
|
| :attr:`_engine.CursorResult.returned_defaults`
|
| :attr:`_engine.CursorResult.returned_defaults_rows`
|
| :attr:`_engine.CursorResult.inserted_primary_key`
|
| :attr:`_engine.CursorResult.inserted_primary_key_rows`
|
| returning(self, *cols: '_ColumnsClauseArgument[Any]', sort_by_parameter_order: 'bool' = False, **_UpdateBase__kw: 'Any') -> 'UpdateBase'
| Add a :term:`RETURNING` or equivalent clause to this statement.
|
| e.g.:
|
| .. sourcecode:: pycon+sql
|
| >>> stmt = (
| ... table.update()
| ... .where(table.c.data == "value")
| ... .values(status="X")
| ... .returning(table.c.server_flag, table.c.updated_timestamp)
| ... )
| >>> print(stmt)
| {printsql}UPDATE some_table SET status=:status
| WHERE some_table.data = :data_1
| RETURNING some_table.server_flag, some_table.updated_timestamp
|
| The method may be invoked multiple times to add new entries to the
| list of expressions to be returned.
|
| .. versionadded:: 1.4.0b2 The method may be invoked multiple times to
| add new entries to the list of expressions to be returned.
|
| The given collection of column expressions should be derived from the
| table that is the target of the INSERT, UPDATE, or DELETE. While
| :class:`_schema.Column` objects are typical, the elements can also be
| expressions:
|
| .. sourcecode:: pycon+sql
|
| >>> stmt = table.insert().returning(
| ... (table.c.first_name + " " + table.c.last_name).label("fullname")
| ... )
| >>> print(stmt)
| {printsql}INSERT INTO some_table (first_name, last_name)
| VALUES (:first_name, :last_name)
| RETURNING some_table.first_name || :first_name_1 || some_table.last_name AS fullname
|
| Upon compilation, a RETURNING clause, or database equivalent,
| will be rendered within the statement. For INSERT and UPDATE,
| the values are the newly inserted/updated values. For DELETE,
| the values are those of the rows which were deleted.
|
| Upon execution, the values of the columns to be returned are made
| available via the result set and can be iterated using
| :meth:`_engine.CursorResult.fetchone` and similar.
| For DBAPIs which do not
| natively support returning values (i.e. cx_oracle), SQLAlchemy will
| approximate this behavior at the result level so that a reasonable
| amount of behavioral neutrality is provided.
|
| Note that not all databases/DBAPIs
| support RETURNING. For those backends with no support,
| an exception is raised upon compilation and/or execution.
| For those who do support it, the functionality across backends
| varies greatly, including restrictions on executemany()
| and other statements which return multiple rows. Please
| read the documentation notes for the database in use in
| order to determine the availability of RETURNING.
|
| :param \*cols: series of columns, SQL expressions, or whole tables
| entities to be returned.
| :param sort_by_parameter_order: for a batch INSERT that is being
| executed against multiple parameter sets, organize the results of
| RETURNING so that the returned rows correspond to the order of
| parameter sets passed in. This applies only to an :term:`executemany`
| execution for supporting dialects and typically makes use of the
| :term:`insertmanyvalues` feature.
|
| .. versionadded:: 2.0.10
|
| .. seealso::
|
| :ref:`engine_insertmanyvalues_returning_order` - background on
| sorting of RETURNING rows for bulk INSERT (Core level discussion)
|
| :ref:`orm_queryguide_bulk_insert_returning_ordered` - example of
| use with :ref:`orm_queryguide_bulk_insert` (ORM level discussion)
|
| .. seealso::
|
| :meth:`.UpdateBase.return_defaults` - an alternative method tailored
| towards efficient fetching of server-side defaults and triggers
| for single-row INSERTs or UPDATEs.
|
| :ref:`tutorial_insert_returning` - in the :ref:`unified_tutorial`
|
| with_dialect_options(self, **opt: 'Any') -> 'Self'
| Add dialect options to this INSERT/UPDATE/DELETE object.
|
| e.g.::
|
| upd = table.update().dialect_options(mysql_limit=10)
|
| .. versionadded: 1.4 - this method supersedes the dialect options
| associated with the constructor.
|
| with_hint(self, text: 'str', selectable: 'Optional[_DMLTableArgument]' = None, dialect_name: 'str' = '*') -> 'Self'
| Add a table hint for a single table to this
| INSERT/UPDATE/DELETE statement.
|
| .. note::
|
| :meth:`.UpdateBase.with_hint` currently applies only to
| Microsoft SQL Server. For MySQL INSERT/UPDATE/DELETE hints, use
| :meth:`.UpdateBase.prefix_with`.
|
| The text of the hint is rendered in the appropriate
| location for the database backend in use, relative
| to the :class:`_schema.Table` that is the subject of this
| statement, or optionally to that of the given
| :class:`_schema.Table` passed as the ``selectable`` argument.
|
| The ``dialect_name`` option will limit the rendering of a particular
| hint to a particular backend. Such as, to add a hint
| that only takes effect for SQL Server::
|
| mytable.insert().with_hint("WITH (PAGLOCK)", dialect_name="mssql")
|
| :param text: Text of the hint.
| :param selectable: optional :class:`_schema.Table` that specifies
| an element of the FROM clause within an UPDATE or DELETE
| to be the subject of the hint - applies only to certain backends.
| :param dialect_name: defaults to ``*``, if specified as the name
| of a particular dialect, will apply these hints only when
| that dialect is in use.
|
| ----------------------------------------------------------------------
| Readonly properties inherited from UpdateBase:
|
| entity_description
| Return a :term:`plugin-enabled` description of the table and/or
| entity which this DML construct is operating against.
|
| This attribute is generally useful when using the ORM, as an
| extended structure which includes information about mapped
| entities is returned. The section :ref:`queryguide_inspection`
| contains more background.
|
| For a Core statement, the structure returned by this accessor
| is derived from the :attr:`.UpdateBase.table` attribute, and
| refers to the :class:`.Table` being inserted, updated, or deleted::
|
| >>> stmt = insert(user_table)
| >>> stmt.entity_description
| {
| "name": "user_table",
| "table": Table("user_table", ...)
| }
|
| .. versionadded:: 1.4.33
|
| .. seealso::
|
| :attr:`.UpdateBase.returning_column_descriptions`
|
| :attr:`.Select.column_descriptions` - entity information for
| a :func:`.select` construct
|
| :ref:`queryguide_inspection` - ORM background
|
| returning_column_descriptions
| Return a :term:`plugin-enabled` description of the columns
| which this DML construct is RETURNING against, in other words
| the expressions established as part of :meth:`.UpdateBase.returning`.
|
| This attribute is generally useful when using the ORM, as an
| extended structure which includes information about mapped
| entities is returned. The section :ref:`queryguide_inspection`
| contains more background.
|
| For a Core statement, the structure returned by this accessor is
| derived from the same objects that are returned by the
| :attr:`.UpdateBase.exported_columns` accessor::
|
| >>> stmt = insert(user_table).returning(user_table.c.id, user_table.c.name)
| >>> stmt.entity_description
| [
| {
| "name": "id",
| "type": Integer,
| "expr": Column("id", Integer(), table=<user>, ...)
| },
| {
| "name": "name",
| "type": String(),
| "expr": Column("name", String(), table=<user>, ...)
| },
| ]
|
| .. versionadded:: 1.4.33
|
| .. seealso::
|
| :attr:`.UpdateBase.entity_description`
|
| :attr:`.Select.column_descriptions` - entity information for
| a :func:`.select` construct
|
| :ref:`queryguide_inspection` - ORM background
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from UpdateBase:
|
| is_dml = True
|
| named_with_column = False
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.selectable.HasCTE:
|
| add_cte(self, *ctes: 'CTE', nest_here: 'bool' = False) -> 'Self'
| Add one or more :class:`_sql.CTE` constructs to this statement.
|
| This method will associate the given :class:`_sql.CTE` constructs with
| the parent statement such that they will each be unconditionally
| rendered in the WITH clause of the final statement, even if not
| referenced elsewhere within the statement or any sub-selects.
|
| The optional :paramref:`.HasCTE.add_cte.nest_here` parameter when set
| to True will have the effect that each given :class:`_sql.CTE` will
| render in a WITH clause rendered directly along with this statement,
| rather than being moved to the top of the ultimate rendered statement,
| even if this statement is rendered as a subquery within a larger
| statement.
|
| This method has two general uses. One is to embed CTE statements that
| serve some purpose without being referenced explicitly, such as the use
| case of embedding a DML statement such as an INSERT or UPDATE as a CTE
| inline with a primary statement that may draw from its results
| indirectly. The other is to provide control over the exact placement
| of a particular series of CTE constructs that should remain rendered
| directly in terms of a particular statement that may be nested in a
| larger statement.
|
| E.g.::
|
| from sqlalchemy import table, column, select
|
| t = table("t", column("c1"), column("c2"))
|
| ins = t.insert().values({"c1": "x", "c2": "y"}).cte()
|
| stmt = select(t).add_cte(ins)
|
| Would render:
|
| .. sourcecode:: sql
|
| WITH anon_1 AS (
| INSERT INTO t (c1, c2) VALUES (:param_1, :param_2)
| )
| SELECT t.c1, t.c2
| FROM t
|
| Above, the "anon_1" CTE is not referenced in the SELECT
| statement, however still accomplishes the task of running an INSERT
| statement.
|
| Similarly in a DML-related context, using the PostgreSQL
| :class:`_postgresql.Insert` construct to generate an "upsert"::
|
| from sqlalchemy import table, column
| from sqlalchemy.dialects.postgresql import insert
|
| t = table("t", column("c1"), column("c2"))
|
| delete_statement_cte = t.delete().where(t.c.c1 < 1).cte("deletions")
|
| insert_stmt = insert(t).values({"c1": 1, "c2": 2})
| update_statement = insert_stmt.on_conflict_do_update(
| index_elements=[t.c.c1],
| set_={
| "c1": insert_stmt.excluded.c1,
| "c2": insert_stmt.excluded.c2,
| },
| ).add_cte(delete_statement_cte)
|
| print(update_statement)
|
| The above statement renders as:
|
| .. sourcecode:: sql
|
| WITH deletions AS (
| DELETE FROM t WHERE t.c1 < %(c1_1)s
| )
| INSERT INTO t (c1, c2) VALUES (%(c1)s, %(c2)s)
| ON CONFLICT (c1) DO UPDATE SET c1 = excluded.c1, c2 = excluded.c2
|
| .. versionadded:: 1.4.21
|
| :param \*ctes: zero or more :class:`.CTE` constructs.
|
| .. versionchanged:: 2.0 Multiple CTE instances are accepted
|
| :param nest_here: if True, the given CTE or CTEs will be rendered
| as though they specified the :paramref:`.HasCTE.cte.nesting` flag
| to ``True`` when they were added to this :class:`.HasCTE`.
| Assuming the given CTEs are not referenced in an outer-enclosing
| statement as well, the CTEs given should render at the level of
| this statement when this flag is given.
|
| .. versionadded:: 2.0
|
| .. seealso::
|
| :paramref:`.HasCTE.cte.nesting`
|
| cte(self, name: 'Optional[str]' = None, recursive: 'bool' = False, nesting: 'bool' = False) -> 'CTE'
| Return a new :class:`_expression.CTE`,
| or Common Table Expression instance.
|
| Common table expressions are a SQL standard whereby SELECT
| statements can draw upon secondary statements specified along
| with the primary statement, using a clause called "WITH".
| Special semantics regarding UNION can also be employed to
| allow "recursive" queries, where a SELECT statement can draw
| upon the set of rows that have previously been selected.
|
| CTEs can also be applied to DML constructs UPDATE, INSERT
| and DELETE on some databases, both as a source of CTE rows
| when combined with RETURNING, as well as a consumer of
| CTE rows.
|
| SQLAlchemy detects :class:`_expression.CTE` objects, which are treated
| similarly to :class:`_expression.Alias` objects, as special elements
| to be delivered to the FROM clause of the statement as well
| as to a WITH clause at the top of the statement.
|
| For special prefixes such as PostgreSQL "MATERIALIZED" and
| "NOT MATERIALIZED", the :meth:`_expression.CTE.prefix_with`
| method may be
| used to establish these.
|
| .. versionchanged:: 1.3.13 Added support for prefixes.
| In particular - MATERIALIZED and NOT MATERIALIZED.
|
| :param name: name given to the common table expression. Like
| :meth:`_expression.FromClause.alias`, the name can be left as
| ``None`` in which case an anonymous symbol will be used at query
| compile time.
| :param recursive: if ``True``, will render ``WITH RECURSIVE``.
| A recursive common table expression is intended to be used in
| conjunction with UNION ALL in order to derive rows
| from those already selected.
| :param nesting: if ``True``, will render the CTE locally to the
| statement in which it is referenced. For more complex scenarios,
| the :meth:`.HasCTE.add_cte` method using the
| :paramref:`.HasCTE.add_cte.nest_here`
| parameter may also be used to more carefully
| control the exact placement of a particular CTE.
|
| .. versionadded:: 1.4.24
|
| .. seealso::
|
| :meth:`.HasCTE.add_cte`
|
| The following examples include two from PostgreSQL's documentation at
| https://www.postgresql.org/docs/current/static/queries-with.html,
| as well as additional examples.
|
| Example 1, non recursive::
|
| from sqlalchemy import (
| Table,
| Column,
| String,
| Integer,
| MetaData,
| select,
| func,
| )
|
| metadata = MetaData()
|
| orders = Table(
| "orders",
| metadata,
| Column("region", String),
| Column("amount", Integer),
| Column("product", String),
| Column("quantity", Integer),
| )
|
| regional_sales = (
| select(orders.c.region, func.sum(orders.c.amount).label("total_sales"))
| .group_by(orders.c.region)
| .cte("regional_sales")
| )
|
|
| top_regions = (
| select(regional_sales.c.region)
| .where(
| regional_sales.c.total_sales
| > select(func.sum(regional_sales.c.total_sales) / 10)
| )
| .cte("top_regions")
| )
|
| statement = (
| select(
| orders.c.region,
| orders.c.product,
| func.sum(orders.c.quantity).label("product_units"),
| func.sum(orders.c.amount).label("product_sales"),
| )
| .where(orders.c.region.in_(select(top_regions.c.region)))
| .group_by(orders.c.region, orders.c.product)
| )
|
| result = conn.execute(statement).fetchall()
|
| Example 2, WITH RECURSIVE::
|
| from sqlalchemy import (
| Table,
| Column,
| String,
| Integer,
| MetaData,
| select,
| func,
| )
|
| metadata = MetaData()
|
| parts = Table(
| "parts",
| metadata,
| Column("part", String),
| Column("sub_part", String),
| Column("quantity", Integer),
| )
|
| included_parts = (
| select(parts.c.sub_part, parts.c.part, parts.c.quantity)
| .where(parts.c.part == "our part")
| .cte(recursive=True)
| )
|
|
| incl_alias = included_parts.alias()
| parts_alias = parts.alias()
| included_parts = included_parts.union_all(
| select(
| parts_alias.c.sub_part, parts_alias.c.part, parts_alias.c.quantity
| ).where(parts_alias.c.part == incl_alias.c.sub_part)
| )
|
| statement = select(
| included_parts.c.sub_part,
| func.sum(included_parts.c.quantity).label("total_quantity"),
| ).group_by(included_parts.c.sub_part)
|
| result = conn.execute(statement).fetchall()
|
| Example 3, an upsert using UPDATE and INSERT with CTEs::
|
| from datetime import date
| from sqlalchemy import (
| MetaData,
| Table,
| Column,
| Integer,
| Date,
| select,
| literal,
| and_,
| exists,
| )
|
| metadata = MetaData()
|
| visitors = Table(
| "visitors",
| metadata,
| Column("product_id", Integer, primary_key=True),
| Column("date", Date, primary_key=True),
| Column("count", Integer),
| )
|
| # add 5 visitors for the product_id == 1
| product_id = 1
| day = date.today()
| count = 5
|
| update_cte = (
| visitors.update()
| .where(
| and_(visitors.c.product_id == product_id, visitors.c.date == day)
| )
| .values(count=visitors.c.count + count)
| .returning(literal(1))
| .cte("update_cte")
| )
|
| upsert = visitors.insert().from_select(
| [visitors.c.product_id, visitors.c.date, visitors.c.count],
| select(literal(product_id), literal(day), literal(count)).where(
| ~exists(update_cte.select())
| ),
| )
|
| connection.execute(upsert)
|
| Example 4, Nesting CTE (SQLAlchemy 1.4.24 and above)::
|
| value_a = select(literal("root").label("n")).cte("value_a")
|
| # A nested CTE with the same name as the root one
| value_a_nested = select(literal("nesting").label("n")).cte(
| "value_a", nesting=True
| )
|
| # Nesting CTEs takes ascendency locally
| # over the CTEs at a higher level
| value_b = select(value_a_nested.c.n).cte("value_b")
|
| value_ab = select(value_a.c.n.label("a"), value_b.c.n.label("b"))
|
| The above query will render the second CTE nested inside the first,
| shown with inline parameters below as:
|
| .. sourcecode:: sql
|
| WITH
| value_a AS
| (SELECT 'root' AS n),
| value_b AS
| (WITH value_a AS
| (SELECT 'nesting' AS n)
| SELECT value_a.n AS n FROM value_a)
| SELECT value_a.n AS a, value_b.n AS b
| FROM value_a, value_b
|
| The same CTE can be set up using the :meth:`.HasCTE.add_cte` method
| as follows (SQLAlchemy 2.0 and above)::
|
| value_a = select(literal("root").label("n")).cte("value_a")
|
| # A nested CTE with the same name as the root one
| value_a_nested = select(literal("nesting").label("n")).cte("value_a")
|
| # Nesting CTEs takes ascendency locally
| # over the CTEs at a higher level
| value_b = (
| select(value_a_nested.c.n)
| .add_cte(value_a_nested, nest_here=True)
| .cte("value_b")
| )
|
| value_ab = select(value_a.c.n.label("a"), value_b.c.n.label("b"))
|
| Example 5, Non-Linear CTE (SQLAlchemy 1.4.28 and above)::
|
| edge = Table(
| "edge",
| metadata,
| Column("id", Integer, primary_key=True),
| Column("left", Integer),
| Column("right", Integer),
| )
|
| root_node = select(literal(1).label("node")).cte("nodes", recursive=True)
|
| left_edge = select(edge.c.left).join(
| root_node, edge.c.right == root_node.c.node
| )
| right_edge = select(edge.c.right).join(
| root_node, edge.c.left == root_node.c.node
| )
|
| subgraph_cte = root_node.union(left_edge, right_edge)
|
| subgraph = select(subgraph_cte)
|
| The above query will render 2 UNIONs inside the recursive CTE:
|
| .. sourcecode:: sql
|
| WITH RECURSIVE nodes(node) AS (
| SELECT 1 AS node
| UNION
| SELECT edge."left" AS "left"
| FROM edge JOIN nodes ON edge."right" = nodes.node
| UNION
| SELECT edge."right" AS "right"
| FROM edge JOIN nodes ON edge."left" = nodes.node
| )
| SELECT nodes.node FROM nodes
|
| .. seealso::
|
| :meth:`_orm.Query.cte` - ORM version of
| :meth:`_expression.HasCTE.cte`.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.selectable.HasCTE:
|
| name_cte_columns = False
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.base.DialectKWArgs:
|
| dialect_options(...)
| A collection of keyword arguments specified as dialect-specific
| options to this construct.
|
| This is a two-level nested registry, keyed to ``<dialect_name>``
| and ``<argument_name>``. For example, the ``postgresql_where``
| argument would be locatable as::
|
| arg = my_object.dialect_options["postgresql"]["where"]
|
| .. versionadded:: 0.9.2
|
| .. seealso::
|
| :attr:`.DialectKWArgs.dialect_kwargs` - flat dictionary form
|
| get_dialect_option(self, dialect: 'Dialect', argument_name: 'str', *, else_: 'Any' = None, deprecated_fallback: 'Optional[str]' = None) -> 'Any'
| Return the value of a dialect-specific option, or *else_* if
| this dialect does not register the given argument.
|
| This is useful for DDL compilers that may be inherited by
| third-party dialects whose ``construct_arguments`` do not
| include the same set of keys as the parent dialect.
|
| :param dialect: The dialect for which to retrieve the option.
| :param argument_name: The name of the argument to retrieve.
| :param else\_: The value to return if the argument is not present.
| :param deprecated_fallback: Optional dialect name to fall back to
| if the argument is not present for the current dialect. If the
| argument is present for the fallback dialect but not the current
| dialect, a deprecation warning will be emitted.
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.base.DialectKWArgs:
|
| argument_for(dialect_name: 'str', argument_name: 'str', default: 'Any') -> 'None'
| Add a new kind of dialect-specific keyword argument for this class.
|
| E.g.::
|
| Index.argument_for("mydialect", "length", None)
|
| some_index = Index("a", "b", mydialect_length=5)
|
| The :meth:`.DialectKWArgs.argument_for` method is a per-argument
| way adding extra arguments to the
| :attr:`.DefaultDialect.construct_arguments` dictionary. This
| dictionary provides a list of argument names accepted by various
| schema-level constructs on behalf of a dialect.
|
| New dialects should typically specify this dictionary all at once as a
| data member of the dialect class. The use case for ad-hoc addition of
| argument names is typically for end-user code that is also using
| a custom compilation scheme which consumes the additional arguments.
|
| :param dialect_name: name of a dialect. The dialect must be
| locatable, else a :class:`.NoSuchModuleError` is raised. The
| dialect must also include an existing
| :attr:`.DefaultDialect.construct_arguments` collection, indicating
| that it participates in the keyword-argument validation and default
| system, else :class:`.ArgumentError` is raised. If the dialect does
| not include this collection, then any keyword argument can be
| specified on behalf of this dialect already. All dialects packaged
| within SQLAlchemy include this collection, however for third party
| dialects, support may vary.
|
| :param argument_name: name of the parameter.
|
| :param default: default value of the parameter.
|
| ----------------------------------------------------------------------
| Readonly properties inherited from sqlalchemy.sql.base.DialectKWArgs:
|
| dialect_kwargs
| A collection of keyword arguments specified as dialect-specific
| options to this construct.
|
| The arguments are present here in their original ``<dialect>_<kwarg>``
| format. Only arguments that were actually passed are included;
| unlike the :attr:`.DialectKWArgs.dialect_options` collection, which
| contains all options known by this dialect including defaults.
|
| The collection is also writable; keys are accepted of the
| form ``<dialect>_<kwarg>`` where the value will be assembled
| into the list of options.
|
| .. seealso::
|
| :attr:`.DialectKWArgs.dialect_options` - nested dictionary form
|
| kwargs
| A synonym for :attr:`.DialectKWArgs.dialect_kwargs`.
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.selectable.HasPrefixes:
|
| prefix_with(self, *prefixes: '_TextCoercedExpressionArgument[Any]', dialect: 'str' = '*') -> 'Self'
| 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.
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.base.Executable:
|
| execution_options(self, **kw: 'Any') -> 'Self'
| Set non-SQL options for the statement which take effect during
| execution.
|
| Execution options can be set at many scopes, including per-statement,
| per-connection, or per execution, using methods such as
| :meth:`_engine.Connection.execution_options` and parameters which
| accept a dictionary of options such as
| :paramref:`_engine.Connection.execute.execution_options` and
| :paramref:`_orm.Session.execute.execution_options`.
|
| The primary characteristic of an execution option, as opposed to
| other kinds of options such as ORM loader options, is that
| **execution options never affect the compiled SQL of a query, only
| things that affect how the SQL statement itself is invoked or how
| results are fetched**. That is, execution options are not part of
| what's accommodated by SQL compilation nor are they considered part of
| the cached state of a statement.
|
| The :meth:`_sql.Executable.execution_options` method is
| :term:`generative`, as
| is the case for the method as applied to the :class:`_engine.Engine`
| and :class:`_orm.Query` objects, which means when the method is called,
| a copy of the object is returned, which applies the given parameters to
| that new copy, but leaves the original unchanged::
|
| statement = select(table.c.x, table.c.y)
| new_statement = statement.execution_options(my_option=True)
|
| An exception to this behavior is the :class:`_engine.Connection`
| object, where the :meth:`_engine.Connection.execution_options` method
| is explicitly **not** generative.
|
| The kinds of options that may be passed to
| :meth:`_sql.Executable.execution_options` and other related methods and
| parameter dictionaries include parameters that are explicitly consumed
| by SQLAlchemy Core or ORM, as well as arbitrary keyword arguments not
| defined by SQLAlchemy, which means the methods and/or parameter
| dictionaries may be used for user-defined parameters that interact with
| custom code, which may access the parameters using methods such as
| :meth:`_sql.Executable.get_execution_options` and
| :meth:`_engine.Connection.get_execution_options`, or within selected
| event hooks using a dedicated ``execution_options`` event parameter
| such as
| :paramref:`_events.ConnectionEvents.before_execute.execution_options`
| or :attr:`_orm.ORMExecuteState.execution_options`, e.g.::
|
| from sqlalchemy import event
|
|
| @event.listens_for(some_engine, "before_execute")
| def _process_opt(conn, statement, multiparams, params, execution_options):
| "run a SQL function before invoking a statement"
|
| if execution_options.get("do_special_thing", False):
| conn.exec_driver_sql("run_special_function()")
|
| Within the scope of options that are explicitly recognized by
| SQLAlchemy, most apply to specific classes of objects and not others.
| The most common execution options include:
|
| * :paramref:`_engine.Connection.execution_options.isolation_level` -
| sets the isolation level for a connection or a class of connections
| via an :class:`_engine.Engine`. This option is accepted only
| by :class:`_engine.Connection` or :class:`_engine.Engine`.
|
| * :paramref:`_engine.Connection.execution_options.stream_results` -
| indicates results should be fetched using a server side cursor;
| this option is accepted by :class:`_engine.Connection`, by the
| :paramref:`_engine.Connection.execute.execution_options` parameter
| on :meth:`_engine.Connection.execute`, and additionally by
| :meth:`_sql.Executable.execution_options` on a SQL statement object,
| as well as by ORM constructs like :meth:`_orm.Session.execute`.
|
| * :paramref:`_engine.Connection.execution_options.compiled_cache` -
| indicates a dictionary that will serve as the
| :ref:`SQL compilation cache <sql_caching>`
| for a :class:`_engine.Connection` or :class:`_engine.Engine`, as
| well as for ORM methods like :meth:`_orm.Session.execute`.
| Can be passed as ``None`` to disable caching for statements.
| This option is not accepted by
| :meth:`_sql.Executable.execution_options` as it is inadvisable to
| carry along a compilation cache within a statement object.
|
| * :paramref:`_engine.Connection.execution_options.schema_translate_map`
| - a mapping of schema names used by the
| :ref:`Schema Translate Map <schema_translating>` feature, accepted
| by :class:`_engine.Connection`, :class:`_engine.Engine`,
| :class:`_sql.Executable`, as well as by ORM constructs
| like :meth:`_orm.Session.execute`.
|
| .. seealso::
|
| :meth:`_engine.Connection.execution_options`
|
| :paramref:`_engine.Connection.execute.execution_options`
|
| :paramref:`_orm.Session.execute.execution_options`
|
| :ref:`orm_queryguide_execution_options` - documentation on all
| ORM-specific execution options
|
| get_execution_options(self) -> '_ExecuteOptions'
| Get the non-SQL options which will take effect during execution.
|
| .. versionadded:: 1.3
|
| .. seealso::
|
| :meth:`.Executable.execution_options`
|
| options(self, *options: 'ExecutableOption') -> 'Self'
| Apply options to this statement.
|
| In the general sense, options are any kind of Python object
| that can be interpreted by the SQL compiler for the statement.
| These options can be consumed by specific dialects or specific kinds
| of compilers.
|
| The most commonly known kind of option are the ORM level options
| that apply "eager load" and other loading behaviors to an ORM
| query. However, options can theoretically be used for many other
| purposes.
|
| For background on specific kinds of options for specific kinds of
| statements, refer to the documentation for those option objects.
|
| .. versionchanged:: 1.4 - added :meth:`.Executable.options` to
| Core statement objects towards the goal of allowing unified
| Core / ORM querying capabilities.
|
| .. seealso::
|
| :ref:`loading_columns` - refers to options specific to the usage
| of ORM queries
|
| :ref:`relationship_loader_options` - refers to options specific
| to the usage of ORM queries
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.base.Executable:
|
| is_from_statement = False
|
| is_insert = False
|
| is_select = False
|
| is_text = False
|
| is_update = False
|
| supports_execution = True
|
| ----------------------------------------------------------------------
| Readonly properties inherited from sqlalchemy.sql.selectable.ReturnsRows:
|
| selectable
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.SQLRole:
|
| allows_lambda = False
|
| uses_inspection = False
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.elements.ClauseElement:
|
| __bool__(self)
|
| __getstate__(self)
| Helper for pickle.
|
| __invert__(self)
|
| __repr__(self)
| Return repr(self).
|
| compare(self, other: 'ClauseElement', **kw: 'Any') -> 'bool'
| Compare this :class:`_expression.ClauseElement` to
| the given :class:`_expression.ClauseElement`.
|
| Subclasses should override the default behavior, which is a
| straight identity comparison.
|
| \**kw are arguments consumed by subclass ``compare()`` methods and
| may be used to modify the criteria for comparison
| (see :class:`_expression.ColumnElement`).
|
| description(...)
|
| entity_namespace(...)
|
| self_group(self, against: 'Optional[OperatorType]' = None) -> 'ClauseElement'
| 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.
|
| unique_params(self, _ClauseElement__optionaldict: 'Optional[Dict[str, Any]]' = None, **kwargs: 'Any') -> 'Self'
| Return a copy with :func:`_expression.bindparam` elements
| replaced.
|
| Same functionality as :meth:`_expression.ClauseElement.params`,
| except adds `unique=True`
| to affected bind parameters so that multiple statements can be
| used.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.elements.ClauseElement:
|
| is_clause_element = True
|
| is_selectable = False
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.cache_key.HasCacheKey:
|
| inherit_cache = None
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_instancemethod(fn: '_F') -> '_F'
| Decorate a method memoize its return value.
|
| :meta private:
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_attribute = <class 'sqlalchemy.util.langhelpers.HasMemoized.m...
| A read-only @property that is only evaluated once.
|
| :meta private:
|
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.visitors.HasTraverseInternals:
|
| get_children(self, *, omit_attrs: 'Tuple[str, ...]' = (), **kw: 'Any') -> 'Iterable[HasTraverseInternals]'
| Return immediate child :class:`.visitors.HasTraverseInternals`
| elements of this :class:`.visitors.HasTraverseInternals`.
|
| This is used for visit traversal.
|
| \**kw may contain flags that change the collection that is
| returned, for example to return a subset of items in order to
| cut down on larger traversals, or to return child items from a
| different context (such as schema-level collections instead of
| clause-level).
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.elements.CompilerElement:
|
| __str__(self) -> 'str'
| Return str(self).
|
| compile(self, bind: 'Optional[_HasDialect]' = None, dialect: 'Optional[Dialect]' = None, **kw: 'Any') -> 'Compiled'
| Compile this SQL expression.
|
| The return value is a :class:`~.Compiled` object.
| Calling ``str()`` or ``unicode()`` on the returned value will yield a
| string representation of the result. The
| :class:`~.Compiled` object also can return a
| dictionary of bind parameter names and values
| using the ``params`` accessor.
|
| :param bind: An :class:`.Connection` or :class:`.Engine` which
| can provide a :class:`.Dialect` in order to generate a
| :class:`.Compiled` object. If the ``bind`` and
| ``dialect`` parameters are both omitted, a default SQL compiler
| is used.
|
| :param column_keys: Used for INSERT and UPDATE statements, a list of
| column names which should be present in the VALUES clause of the
| compiled statement. If ``None``, all columns from the target table
| object are rendered.
|
| :param dialect: A :class:`.Dialect` instance which can generate
| a :class:`.Compiled` object. This argument takes precedence over
| the ``bind`` argument.
|
| :param compile_kwargs: optional dictionary of additional parameters
| that will be passed through to the compiler within all "visit"
| methods. This allows any custom flag to be passed through to
| a custom compilation construct, for example. It is also used
| for the case of passing the ``literal_binds`` flag through::
|
| from sqlalchemy.sql import table, column, select
|
| t = table("t", column("x"))
|
| s = select(t).where(t.c.x == 5)
|
| print(s.compile(compile_kwargs={"literal_binds": True}))
|
| .. seealso::
|
| :ref:`faq_sql_expression_string`
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.elements.CompilerElement:
|
| stringify_dialect = 'default'
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.visitors.Visitable:
|
| __class_getitem__(key: 'Any') -> 'Any'
|
| __init_subclass__() -> 'None'
| This method is called when a class is subclassed.
|
| The default implementation does nothing. It may be
| overridden to extend subclasses.
sqlalchemy.Dialect
Python Library Documentation: class Dialect in module sqlalchemy.engine.interfaces
class Dialect(sqlalchemy.event.registry.EventTarget)
| Define the behavior of a specific database and DB-API combination.
|
| Any aspect of metadata definition, SQL query generation,
| execution, result-set handling, or anything else which varies
| between databases is defined under the general category of the
| Dialect. The Dialect acts as a factory for other
| database-specific object implementations including
| ExecutionContext, Compiled, DefaultGenerator, and TypeEngine.
|
| .. note:: Third party dialects should not subclass :class:`.Dialect`
| directly. Instead, subclass :class:`.default.DefaultDialect` or
| descendant class.
|
| Method resolution order:
| Dialect
| sqlalchemy.event.registry.EventTarget
| builtins.object
|
| Methods defined here:
|
| connect(self, *cargs: 'Any', **cparams: 'Any') -> 'DBAPIConnection'
| Establish a connection using this dialect's DBAPI.
|
| The default implementation of this method is::
|
| def connect(self, *cargs, **cparams):
| return self.dbapi.connect(*cargs, **cparams)
|
| The ``*cargs, **cparams`` parameters are generated directly
| from this dialect's :meth:`.Dialect.create_connect_args` method.
|
| This method may be used for dialects that need to perform programmatic
| per-connection steps when a new connection is procured from the
| DBAPI.
|
|
| :param \*cargs: positional parameters returned from the
| :meth:`.Dialect.create_connect_args` method
|
| :param \*\*cparams: keyword parameters returned from the
| :meth:`.Dialect.create_connect_args` method.
|
| :return: a DBAPI connection, typically from the :pep:`249` module
| level ``.connect()`` function.
|
| .. seealso::
|
| :meth:`.Dialect.create_connect_args`
|
| :meth:`.Dialect.on_connect`
|
| create_connect_args(self, url: 'URL') -> 'ConnectArgsType'
| Build DB-API compatible connection arguments.
|
| Given a :class:`.URL` object, returns a tuple
| consisting of a ``(*args, **kwargs)`` suitable to send directly
| to the dbapi's connect function. The arguments are sent to the
| :meth:`.Dialect.connect` method which then runs the DBAPI-level
| ``connect()`` function.
|
| The method typically makes use of the
| :meth:`.URL.translate_connect_args`
| method in order to generate a dictionary of options.
|
| The default implementation is::
|
| def create_connect_args(self, url):
| opts = url.translate_connect_args()
| opts.update(url.query)
| return ([], opts)
|
| :param url: a :class:`.URL` object
|
| :return: a tuple of ``(*args, **kwargs)`` which will be passed to the
| :meth:`.Dialect.connect` method.
|
| .. seealso::
|
| :meth:`.URL.translate_connect_args`
|
| create_xid(self) -> 'Any'
| Create a two-phase transaction ID.
|
| This id will be passed to do_begin_twophase(),
| do_rollback_twophase(), do_commit_twophase(). Its format is
| unspecified.
|
| denormalize_name(self, name: 'str') -> 'str'
| convert the given name to a case insensitive identifier
| for the backend if it is an all-lowercase name.
|
| This method is only used if the dialect defines
| requires_name_normalize=True.
|
| detect_autocommit_setting(self, dbapi_conn: 'DBAPIConnection') -> 'bool'
| Detect the current autocommit setting for a DBAPI connection.
|
| :param dbapi_connection: a DBAPI connection object
| :return: True if autocommit is enabled, False if disabled
| :rtype: bool
|
| This method inspects the given DBAPI connection to determine
| whether autocommit mode is currently enabled. The specific
| mechanism for detecting autocommit varies by database dialect
| and DBAPI driver, however it should be done **without** network
| round trips.
|
| .. note::
|
| Not all dialects support autocommit detection. Dialects
| that do not support this feature will raise
| :exc:`NotImplementedError`.
|
| do_begin(self, dbapi_connection: 'PoolProxiedConnection') -> 'None'
| Provide an implementation of ``connection.begin()``, given a
| DB-API connection.
|
| The DBAPI has no dedicated "begin" method and it is expected
| that transactions are implicit. This hook is provided for those
| DBAPIs that might need additional help in this area.
|
| :param dbapi_connection: a DBAPI connection, typically
| proxied within a :class:`.ConnectionFairy`.
|
| do_begin_twophase(self, connection: 'Connection', xid: 'Any') -> 'None'
| Begin a two phase transaction on the given connection.
|
| :param connection: a :class:`_engine.Connection`.
| :param xid: xid
|
| do_close(self, dbapi_connection: 'DBAPIConnection') -> 'None'
| Provide an implementation of ``connection.close()``, given a DBAPI
| connection.
|
| This hook is called by the :class:`_pool.Pool`
| when a connection has been
| detached from the pool, or is being returned beyond the normal
| capacity of the pool.
|
| do_commit(self, dbapi_connection: 'PoolProxiedConnection') -> 'None'
| Provide an implementation of ``connection.commit()``, given a
| DB-API connection.
|
| :param dbapi_connection: a DBAPI connection, typically
| proxied within a :class:`.ConnectionFairy`.
|
| do_commit_twophase(self, connection: 'Connection', xid: 'Any', is_prepared: 'bool' = True, recover: 'bool' = False) -> 'None'
| Commit a two phase transaction on the given connection.
|
|
| :param connection: a :class:`_engine.Connection`.
| :param xid: xid
| :param is_prepared: whether or not
| :meth:`.TwoPhaseTransaction.prepare` was called.
| :param recover: if the recover flag was passed.
|
| do_execute(self, cursor: 'DBAPICursor', statement: 'str', parameters: 'Optional[_DBAPISingleExecuteParams]', context: 'Optional[ExecutionContext]' = None) -> 'None'
| Provide an implementation of ``cursor.execute(statement,
| parameters)``.
|
| do_execute_no_params(self, cursor: 'DBAPICursor', statement: 'str', context: 'Optional[ExecutionContext]' = None) -> 'None'
| Provide an implementation of ``cursor.execute(statement)``.
|
| The parameter collection should not be sent.
|
| do_executemany(self, cursor: 'DBAPICursor', statement: 'str', parameters: '_DBAPIMultiExecuteParams', context: 'Optional[ExecutionContext]' = None) -> 'None'
| Provide an implementation of ``cursor.executemany(statement,
| parameters)``.
|
| do_ping(self, dbapi_connection: 'DBAPIConnection') -> 'bool'
| ping the DBAPI connection and return True if the connection is
| usable.
|
| do_prepare_twophase(self, connection: 'Connection', xid: 'Any') -> 'None'
| Prepare a two phase transaction on the given connection.
|
| :param connection: a :class:`_engine.Connection`.
| :param xid: xid
|
| do_recover_twophase(self, connection: 'Connection') -> 'List[Any]'
| Recover list of uncommitted prepared two phase transaction
| identifiers on the given connection.
|
| :param connection: a :class:`_engine.Connection`.
|
| do_release_savepoint(self, connection: 'Connection', name: 'str') -> 'None'
| Release the named savepoint on a connection.
|
| :param connection: a :class:`_engine.Connection`.
| :param name: savepoint name.
|
| do_rollback(self, dbapi_connection: 'PoolProxiedConnection') -> 'None'
| Provide an implementation of ``connection.rollback()``, given
| a DB-API connection.
|
| :param dbapi_connection: a DBAPI connection, typically
| proxied within a :class:`.ConnectionFairy`.
|
| do_rollback_to_savepoint(self, connection: 'Connection', name: 'str') -> 'None'
| Rollback a connection to the named savepoint.
|
| :param connection: a :class:`_engine.Connection`.
| :param name: savepoint name.
|
| do_rollback_twophase(self, connection: 'Connection', xid: 'Any', is_prepared: 'bool' = True, recover: 'bool' = False) -> 'None'
| Rollback a two phase transaction on the given connection.
|
| :param connection: a :class:`_engine.Connection`.
| :param xid: xid
| :param is_prepared: whether or not
| :meth:`.TwoPhaseTransaction.prepare` was called.
| :param recover: if the recover flag was passed.
|
| do_savepoint(self, connection: 'Connection', name: 'str') -> 'None'
| Create a savepoint with the given name.
|
| :param connection: a :class:`_engine.Connection`.
| :param name: savepoint name.
|
| do_set_input_sizes(self, cursor: 'DBAPICursor', list_of_tuples: '_GenericSetInputSizesType', context: 'ExecutionContext') -> 'Any'
| invoke the cursor.setinputsizes() method with appropriate arguments
|
| This hook is called if the :attr:`.Dialect.bind_typing` attribute is
| set to the
| :attr:`.BindTyping.SETINPUTSIZES` value.
| Parameter data is passed in a list of tuples (paramname, dbtype,
| sqltype), where ``paramname`` is the key of the parameter in the
| statement, ``dbtype`` is the DBAPI datatype and ``sqltype`` is the
| SQLAlchemy type. The order of tuples is in the correct parameter order.
|
| .. versionadded:: 1.4
|
| .. versionchanged:: 2.0 - setinputsizes mode is now enabled by
| setting :attr:`.Dialect.bind_typing` to
| :attr:`.BindTyping.SETINPUTSIZES`. Dialects which accept
| a ``use_setinputsizes`` parameter should set this value
| appropriately.
|
| do_terminate(self, dbapi_connection: 'DBAPIConnection') -> 'None'
| Provide an implementation of ``connection.close()`` that tries as
| much as possible to not block, given a DBAPI
| connection.
|
| In the vast majority of cases this just calls .close(), however
| for some asyncio dialects may call upon different API features.
|
| This hook is called by the :class:`_pool.Pool`
| when a connection is being recycled or has been invalidated.
|
| .. versionadded:: 1.4.41
|
| get_check_constraints(self, connection: 'Connection', table_name: 'str', schema: 'Optional[str]' = None, **kw: 'Any') -> 'List[ReflectedCheckConstraint]'
| Return information about check constraints in ``table_name``.
|
| Given a string ``table_name`` and an optional string ``schema``, return
| check constraint information as a list of dicts corresponding
| to the :class:`.ReflectedCheckConstraint` dictionary.
|
| This is an internal dialect method. Applications should use
| :meth:`.Inspector.get_check_constraints`.
|
| get_columns(self, connection: 'Connection', table_name: 'str', schema: 'Optional[str]' = None, **kw: 'Any') -> 'List[ReflectedColumn]'
| Return information about columns in ``table_name``.
|
| Given a :class:`_engine.Connection`, a string
| ``table_name``, and an optional string ``schema``, return column
| information as a list of dictionaries
| corresponding to the :class:`.ReflectedColumn` dictionary.
|
| This is an internal dialect method. Applications should use
| :meth:`.Inspector.get_columns`.
|
| get_default_isolation_level(self, dbapi_conn: 'DBAPIConnection') -> 'IsolationLevel'
| Given a DBAPI connection, return its isolation level, or
| a default isolation level if one cannot be retrieved.
|
| This method may only raise NotImplementedError and
| **must not raise any other exception**, as it is used implicitly upon
| first connect.
|
| The method **must return a value** for a dialect that supports
| isolation level settings, as this level is what will be reverted
| towards when a per-connection isolation level change is made.
|
| The method defaults to using the :meth:`.Dialect.get_isolation_level`
| method unless overridden by a dialect.
|
| .. versionadded:: 1.3.22
|
| get_dialect_pool_class(self, url: 'URL') -> 'Type[Pool]'
| return a Pool class to use for a given URL
|
| get_driver_connection(self, connection: 'DBAPIConnection') -> 'Any'
| Returns the connection object as returned by the external driver
| package.
|
| For normal dialects that use a DBAPI compliant driver this call
| will just return the ``connection`` passed as argument.
| For dialects that instead adapt a non DBAPI compliant driver, like
| when adapting an asyncio driver, this call will return the
| connection-like object as returned by the driver.
|
| .. versionadded:: 1.4.24
|
| get_foreign_keys(self, connection: 'Connection', table_name: 'str', schema: 'Optional[str]' = None, **kw: 'Any') -> 'List[ReflectedForeignKeyConstraint]'
| Return information about foreign_keys in ``table_name``.
|
| Given a :class:`_engine.Connection`, a string
| ``table_name``, and an optional string ``schema``, return foreign
| key information as a list of dicts corresponding to the
| :class:`.ReflectedForeignKeyConstraint` dictionary.
|
| This is an internal dialect method. Applications should use
| :meth:`_engine.Inspector.get_foreign_keys`.
|
| get_indexes(self, connection: 'Connection', table_name: 'str', schema: 'Optional[str]' = None, **kw: 'Any') -> 'List[ReflectedIndex]'
| Return information about indexes in ``table_name``.
|
| Given a :class:`_engine.Connection`, a string
| ``table_name`` and an optional string ``schema``, return index
| information as a list of dictionaries corresponding to the
| :class:`.ReflectedIndex` dictionary.
|
| This is an internal dialect method. Applications should use
| :meth:`.Inspector.get_indexes`.
|
| get_isolation_level(self, dbapi_connection: 'DBAPIConnection') -> 'IsolationLevel'
| Given a DBAPI connection, return its isolation level.
|
| When working with a :class:`_engine.Connection` object,
| the corresponding
| DBAPI connection may be procured using the
| :attr:`_engine.Connection.connection` accessor.
|
| Note that this is a dialect-level method which is used as part
| of the implementation of the :class:`_engine.Connection` and
| :class:`_engine.Engine` isolation level facilities;
| these APIs should be preferred for most typical use cases.
|
|
| .. seealso::
|
| :meth:`_engine.Connection.get_isolation_level`
| - view current level
|
| :attr:`_engine.Connection.default_isolation_level`
| - view default level
|
| :paramref:`.Connection.execution_options.isolation_level` -
| set per :class:`_engine.Connection` isolation level
|
| :paramref:`_sa.create_engine.isolation_level` -
| set per :class:`_engine.Engine` isolation level
|
| get_isolation_level_values(self, dbapi_conn: 'DBAPIConnection') -> 'Sequence[IsolationLevel]'
| return a sequence of string isolation level names that are accepted
| by this dialect.
|
| The available names should use the following conventions:
|
| * use UPPERCASE names. isolation level methods will accept lowercase
| names but these are normalized into UPPERCASE before being passed
| along to the dialect.
| * separate words should be separated by spaces, not underscores, e.g.
| ``REPEATABLE READ``. isolation level names will have underscores
| converted to spaces before being passed along to the dialect.
| * The names for the four standard isolation names to the extent that
| they are supported by the backend should be ``READ UNCOMMITTED``,
| ``READ COMMITTED``, ``REPEATABLE READ``, ``SERIALIZABLE``
| * if the dialect supports an autocommit option it should be provided
| using the isolation level name ``AUTOCOMMIT``.
| * Other isolation modes may also be present, provided that they
| are named in UPPERCASE and use spaces not underscores.
|
| This function is used so that the default dialect can check that
| a given isolation level parameter is valid, else raises an
| :class:`_exc.ArgumentError`.
|
| A DBAPI connection is passed to the method, in the unlikely event that
| the dialect needs to interrogate the connection itself to determine
| this list, however it is expected that most backends will return
| a hardcoded list of values. If the dialect supports "AUTOCOMMIT",
| that value should also be present in the sequence returned.
|
| The method raises ``NotImplementedError`` by default. If a dialect
| does not implement this method, then the default dialect will not
| perform any checking on a given isolation level value before passing
| it onto the :meth:`.Dialect.set_isolation_level` method. This is
| to allow backwards-compatibility with third party dialects that may
| not yet be implementing this method.
|
| .. versionadded:: 2.0
|
| get_materialized_view_names(self, connection: 'Connection', schema: 'Optional[str]' = None, **kw: 'Any') -> 'List[str]'
| Return a list of all materialized view names available in the
| database.
|
| This is an internal dialect method. Applications should use
| :meth:`_engine.Inspector.get_materialized_view_names`.
|
| :param schema: schema name to query, if not the default schema.
|
| .. versionadded:: 2.0
|
| get_multi_check_constraints(self, connection: 'Connection', *, schema: 'Optional[str]' = None, filter_names: 'Optional[Collection[str]]' = None, **kw: 'Any') -> 'Iterable[Tuple[TableKey, List[ReflectedCheckConstraint]]]'
| Return information about check constraints in all tables
| in the given ``schema``.
|
| This is an internal dialect method. Applications should use
| :meth:`.Inspector.get_multi_check_constraints`.
|
| .. note:: The :class:`_engine.DefaultDialect` provides a default
| implementation that will call the single table method for
| each object returned by :meth:`Dialect.get_table_names`,
| :meth:`Dialect.get_view_names` or
| :meth:`Dialect.get_materialized_view_names` depending on the
| provided ``kind``. Dialects that want to support a faster
| implementation should implement this method.
|
| .. versionadded:: 2.0
|
| get_multi_columns(self, connection: 'Connection', *, schema: 'Optional[str]' = None, filter_names: 'Optional[Collection[str]]' = None, **kw: 'Any') -> 'Iterable[Tuple[TableKey, List[ReflectedColumn]]]'
| Return information about columns in all tables in the
| given ``schema``.
|
| This is an internal dialect method. Applications should use
| :meth:`.Inspector.get_multi_columns`.
|
| .. note:: The :class:`_engine.DefaultDialect` provides a default
| implementation that will call the single table method for
| each object returned by :meth:`Dialect.get_table_names`,
| :meth:`Dialect.get_view_names` or
| :meth:`Dialect.get_materialized_view_names` depending on the
| provided ``kind``. Dialects that want to support a faster
| implementation should implement this method.
|
| .. versionadded:: 2.0
|
| get_multi_foreign_keys(self, connection: 'Connection', *, schema: 'Optional[str]' = None, filter_names: 'Optional[Collection[str]]' = None, **kw: 'Any') -> 'Iterable[Tuple[TableKey, List[ReflectedForeignKeyConstraint]]]'
| Return information about foreign_keys in all tables
| in the given ``schema``.
|
| This is an internal dialect method. Applications should use
| :meth:`_engine.Inspector.get_multi_foreign_keys`.
|
| .. note:: The :class:`_engine.DefaultDialect` provides a default
| implementation that will call the single table method for
| each object returned by :meth:`Dialect.get_table_names`,
| :meth:`Dialect.get_view_names` or
| :meth:`Dialect.get_materialized_view_names` depending on the
| provided ``kind``. Dialects that want to support a faster
| implementation should implement this method.
|
| .. versionadded:: 2.0
|
| get_multi_indexes(self, connection: 'Connection', *, schema: 'Optional[str]' = None, filter_names: 'Optional[Collection[str]]' = None, **kw: 'Any') -> 'Iterable[Tuple[TableKey, List[ReflectedIndex]]]'
| Return information about indexes in in all tables
| in the given ``schema``.
|
| This is an internal dialect method. Applications should use
| :meth:`.Inspector.get_multi_indexes`.
|
| .. note:: The :class:`_engine.DefaultDialect` provides a default
| implementation that will call the single table method for
| each object returned by :meth:`Dialect.get_table_names`,
| :meth:`Dialect.get_view_names` or
| :meth:`Dialect.get_materialized_view_names` depending on the
| provided ``kind``. Dialects that want to support a faster
| implementation should implement this method.
|
| .. versionadded:: 2.0
|
| get_multi_pk_constraint(self, connection: 'Connection', *, schema: 'Optional[str]' = None, filter_names: 'Optional[Collection[str]]' = None, **kw: 'Any') -> 'Iterable[Tuple[TableKey, ReflectedPrimaryKeyConstraint]]'
| Return information about primary key constraints in
| all tables in the given ``schema``.
|
| This is an internal dialect method. Applications should use
| :meth:`.Inspector.get_multi_pk_constraint`.
|
| .. note:: The :class:`_engine.DefaultDialect` provides a default
| implementation that will call the single table method for
| each object returned by :meth:`Dialect.get_table_names`,
| :meth:`Dialect.get_view_names` or
| :meth:`Dialect.get_materialized_view_names` depending on the
| provided ``kind``. Dialects that want to support a faster
| implementation should implement this method.
|
| .. versionadded:: 2.0
|
| get_multi_table_comment(self, connection: 'Connection', *, schema: 'Optional[str]' = None, filter_names: 'Optional[Collection[str]]' = None, **kw: 'Any') -> 'Iterable[Tuple[TableKey, ReflectedTableComment]]'
| Return information about the table comment in all tables
| in the given ``schema``.
|
| This is an internal dialect method. Applications should use
| :meth:`_engine.Inspector.get_multi_table_comment`.
|
| .. note:: The :class:`_engine.DefaultDialect` provides a default
| implementation that will call the single table method for
| each object returned by :meth:`Dialect.get_table_names`,
| :meth:`Dialect.get_view_names` or
| :meth:`Dialect.get_materialized_view_names` depending on the
| provided ``kind``. Dialects that want to support a faster
| implementation should implement this method.
|
| .. versionadded:: 2.0
|
| get_multi_table_options(self, connection: 'Connection', *, schema: 'Optional[str]' = None, filter_names: 'Optional[Collection[str]]' = None, **kw: 'Any') -> 'Iterable[Tuple[TableKey, Dict[str, Any]]]'
| Return a dictionary of options specified when the tables in the
| given schema were created.
|
| This is an internal dialect method. Applications should use
| :meth:`_engine.Inspector.get_multi_table_options`.
|
| .. note:: The :class:`_engine.DefaultDialect` provides a default
| implementation that will call the single table method for
| each object returned by :meth:`Dialect.get_table_names`,
| :meth:`Dialect.get_view_names` or
| :meth:`Dialect.get_materialized_view_names` depending on the
| provided ``kind``. Dialects that want to support a faster
| implementation should implement this method.
|
| .. versionadded:: 2.0
|
| get_multi_unique_constraints(self, connection: 'Connection', *, schema: 'Optional[str]' = None, filter_names: 'Optional[Collection[str]]' = None, **kw: 'Any') -> 'Iterable[Tuple[TableKey, List[ReflectedUniqueConstraint]]]'
| Return information about unique constraints in all tables
| in the given ``schema``.
|
| This is an internal dialect method. Applications should use
| :meth:`.Inspector.get_multi_unique_constraints`.
|
| .. note:: The :class:`_engine.DefaultDialect` provides a default
| implementation that will call the single table method for
| each object returned by :meth:`Dialect.get_table_names`,
| :meth:`Dialect.get_view_names` or
| :meth:`Dialect.get_materialized_view_names` depending on the
| provided ``kind``. Dialects that want to support a faster
| implementation should implement this method.
|
| .. versionadded:: 2.0
|
| get_pk_constraint(self, connection: 'Connection', table_name: 'str', schema: 'Optional[str]' = None, **kw: 'Any') -> 'ReflectedPrimaryKeyConstraint'
| Return information about the primary key constraint on
| table_name`.
|
| Given a :class:`_engine.Connection`, a string
| ``table_name``, and an optional string ``schema``, return primary
| key information as a dictionary corresponding to the
| :class:`.ReflectedPrimaryKeyConstraint` dictionary.
|
| This is an internal dialect method. Applications should use
| :meth:`.Inspector.get_pk_constraint`.
|
| get_schema_names(self, connection: 'Connection', **kw: 'Any') -> 'List[str]'
| Return a list of all schema names available in the database.
|
| This is an internal dialect method. Applications should use
| :meth:`_engine.Inspector.get_schema_names`.
|
| get_sequence_names(self, connection: 'Connection', schema: 'Optional[str]' = None, **kw: 'Any') -> 'List[str]'
| Return a list of all sequence names available in the database.
|
| This is an internal dialect method. Applications should use
| :meth:`_engine.Inspector.get_sequence_names`.
|
| :param schema: schema name to query, if not the default schema.
|
| .. versionadded:: 1.4
|
| get_table_comment(self, connection: 'Connection', table_name: 'str', schema: 'Optional[str]' = None, **kw: 'Any') -> 'ReflectedTableComment'
| Return the "comment" for the table identified by ``table_name``.
|
| Given a string ``table_name`` and an optional string ``schema``, return
| table comment information as a dictionary corresponding to the
| :class:`.ReflectedTableComment` dictionary.
|
| This is an internal dialect method. Applications should use
| :meth:`.Inspector.get_table_comment`.
|
| :raise: ``NotImplementedError`` for dialects that don't support
| comments.
|
| .. versionadded:: 1.2
|
| get_table_names(self, connection: 'Connection', schema: 'Optional[str]' = None, **kw: 'Any') -> 'List[str]'
| Return a list of table names for ``schema``.
|
| This is an internal dialect method. Applications should use
| :meth:`_engine.Inspector.get_table_names`.
|
| get_table_options(self, connection: 'Connection', table_name: 'str', schema: 'Optional[str]' = None, **kw: 'Any') -> 'Dict[str, Any]'
| Return a dictionary of options specified when ``table_name``
| was created.
|
| This is an internal dialect method. Applications should use
| :meth:`_engine.Inspector.get_table_options`.
|
| get_temp_table_names(self, connection: 'Connection', schema: 'Optional[str]' = None, **kw: 'Any') -> 'List[str]'
| Return a list of temporary table names on the given connection,
| if supported by the underlying backend.
|
| This is an internal dialect method. Applications should use
| :meth:`_engine.Inspector.get_temp_table_names`.
|
| get_temp_view_names(self, connection: 'Connection', schema: 'Optional[str]' = None, **kw: 'Any') -> 'List[str]'
| Return a list of temporary view names on the given connection,
| if supported by the underlying backend.
|
| This is an internal dialect method. Applications should use
| :meth:`_engine.Inspector.get_temp_view_names`.
|
| get_unique_constraints(self, connection: 'Connection', table_name: 'str', schema: 'Optional[str]' = None, **kw: 'Any') -> 'List[ReflectedUniqueConstraint]'
| Return information about unique constraints in ``table_name``.
|
| Given a string ``table_name`` and an optional string ``schema``, return
| unique constraint information as a list of dicts corresponding
| to the :class:`.ReflectedUniqueConstraint` dictionary.
|
| This is an internal dialect method. Applications should use
| :meth:`.Inspector.get_unique_constraints`.
|
| get_view_definition(self, connection: 'Connection', view_name: 'str', schema: 'Optional[str]' = None, **kw: 'Any') -> 'str'
| Return plain or materialized view definition.
|
| This is an internal dialect method. Applications should use
| :meth:`_engine.Inspector.get_view_definition`.
|
| Given a :class:`_engine.Connection`, a string
| ``view_name``, and an optional string ``schema``, return the view
| definition.
|
| get_view_names(self, connection: 'Connection', schema: 'Optional[str]' = None, **kw: 'Any') -> 'List[str]'
| Return a list of all non-materialized view names available in the
| database.
|
| This is an internal dialect method. Applications should use
| :meth:`_engine.Inspector.get_view_names`.
|
| :param schema: schema name to query, if not the default schema.
|
| has_index(self, connection: 'Connection', table_name: 'str', index_name: 'str', schema: 'Optional[str]' = None, **kw: 'Any') -> 'bool'
| Check the existence of a particular index name in the database.
|
| Given a :class:`_engine.Connection` object, a string
| ``table_name`` and string index name, return ``True`` if an index of
| the given name on the given table exists, ``False`` otherwise.
|
| The :class:`.DefaultDialect` implements this in terms of the
| :meth:`.Dialect.has_table` and :meth:`.Dialect.get_indexes` methods,
| however dialects can implement a more performant version.
|
| This is an internal dialect method. Applications should use
| :meth:`_engine.Inspector.has_index`.
|
| .. versionadded:: 1.4
|
| has_schema(self, connection: 'Connection', schema_name: 'str', **kw: 'Any') -> 'bool'
| Check the existence of a particular schema name in the database.
|
| Given a :class:`_engine.Connection` object, a string
| ``schema_name``, return ``True`` if a schema of the
| given exists, ``False`` otherwise.
|
| The :class:`.DefaultDialect` implements this by checking
| the presence of ``schema_name`` among the schemas returned by
| :meth:`.Dialect.get_schema_names`,
| however dialects can implement a more performant version.
|
| This is an internal dialect method. Applications should use
| :meth:`_engine.Inspector.has_schema`.
|
| .. versionadded:: 2.0
|
| has_sequence(self, connection: 'Connection', sequence_name: 'str', schema: 'Optional[str]' = None, **kw: 'Any') -> 'bool'
| Check the existence of a particular sequence in the database.
|
| Given a :class:`_engine.Connection` object and a string
| `sequence_name`, return ``True`` if the given sequence exists in
| the database, ``False`` otherwise.
|
| This is an internal dialect method. Applications should use
| :meth:`_engine.Inspector.has_sequence`.
|
| has_table(self, connection: 'Connection', table_name: 'str', schema: 'Optional[str]' = None, **kw: 'Any') -> 'bool'
| For internal dialect use, check the existence of a particular table
| or view in the database.
|
| Given a :class:`_engine.Connection` object, a string table_name and
| optional schema name, return True if the given table exists in the
| database, False otherwise.
|
| This method serves as the underlying implementation of the
| public facing :meth:`.Inspector.has_table` method, and is also used
| internally to implement the "checkfirst" behavior for methods like
| :meth:`_schema.Table.create` and :meth:`_schema.MetaData.create_all`.
|
| .. note:: This method is used internally by SQLAlchemy, and is
| published so that third-party dialects may provide an
| implementation. It is **not** the public API for checking for table
| presence. Please use the :meth:`.Inspector.has_table` method.
|
| .. versionchanged:: 2.0:: :meth:`_engine.Dialect.has_table` now
| formally supports checking for additional table-like objects:
|
| * any type of views (plain or materialized)
| * temporary tables of any kind
|
| Previously, these two checks were not formally specified and
| different dialects would vary in their behavior. The dialect
| testing suite now includes tests for all of these object types,
| and dialects to the degree that the backing database supports views
| or temporary tables should seek to support locating these objects
| for full compliance.
|
| initialize(self, connection: 'Connection') -> 'None'
| Called during strategized creation of the dialect with a
| connection.
|
| Allows dialects to configure options based on server version info or
| other properties.
|
| The connection passed here is a SQLAlchemy Connection object,
| with full capabilities.
|
| The initialize() method of the base dialect should be called via
| super().
|
| .. note:: as of SQLAlchemy 1.4, this method is called **before**
| any :meth:`_engine.Dialect.on_connect` hooks are called.
|
| is_disconnect(self, e: 'DBAPIModule.Error', connection: 'Optional[Union[PoolProxiedConnection, DBAPIConnection]]', cursor: 'Optional[DBAPICursor]') -> 'bool'
| Return True if the given DB-API error indicates an invalid
| connection
|
| loaded_dbapi(...)
| same as .dbapi, but is never None; will raise an error if no
| DBAPI was set up.
|
| .. versionadded:: 2.0
|
| normalize_name(self, name: 'str') -> 'str'
| convert the given name to lowercase if it is detected as
| case insensitive.
|
| This method is only used if the dialect defines
| requires_name_normalize=True.
|
| on_connect(self) -> 'Optional[Callable[[Any], None]]'
| return a callable which sets up a newly created DBAPI connection.
|
| The callable should accept a single argument "conn" which is the
| DBAPI connection itself. The inner callable has no
| return value.
|
| E.g.::
|
| class MyDialect(default.DefaultDialect):
| # ...
|
| def on_connect(self):
| def do_on_connect(connection):
| connection.execute("SET SPECIAL FLAGS etc")
|
| return do_on_connect
|
| This is used to set dialect-wide per-connection options such as
| isolation modes, Unicode modes, etc.
|
| The "do_on_connect" callable is invoked by using the
| :meth:`_events.PoolEvents.connect` event
| hook, then unwrapping the DBAPI connection and passing it into the
| callable.
|
| .. versionchanged:: 1.4 the on_connect hook is no longer called twice
| for the first connection of a dialect. The on_connect hook is still
| called before the :meth:`_engine.Dialect.initialize` method however.
|
| .. versionchanged:: 1.4.3 the on_connect hook is invoked from a new
| method on_connect_url that passes the URL that was used to create
| the connect args. Dialects can implement on_connect_url instead
| of on_connect if they need the URL object that was used for the
| connection in order to get additional context.
|
| If None is returned, no event listener is generated.
|
| :return: a callable that accepts a single DBAPI connection as an
| argument, or None.
|
| .. seealso::
|
| :meth:`.Dialect.connect` - allows the DBAPI ``connect()`` sequence
| itself to be controlled.
|
| :meth:`.Dialect.on_connect_url` - supersedes
| :meth:`.Dialect.on_connect` to also receive the
| :class:`_engine.URL` object in context.
|
| on_connect_url(self, url: 'URL') -> 'Optional[Callable[[Any], Any]]'
| return a callable which sets up a newly created DBAPI connection.
|
| This method is a new hook that supersedes the
| :meth:`_engine.Dialect.on_connect` method when implemented by a
| dialect. When not implemented by a dialect, it invokes the
| :meth:`_engine.Dialect.on_connect` method directly to maintain
| compatibility with existing dialects. There is no deprecation
| for :meth:`_engine.Dialect.on_connect` expected.
|
| The callable should accept a single argument "conn" which is the
| DBAPI connection itself. The inner callable has no
| return value.
|
| E.g.::
|
| class MyDialect(default.DefaultDialect):
| # ...
|
| def on_connect_url(self, url):
| def do_on_connect(connection):
| connection.execute("SET SPECIAL FLAGS etc")
|
| return do_on_connect
|
| This is used to set dialect-wide per-connection options such as
| isolation modes, Unicode modes, etc.
|
| This method differs from :meth:`_engine.Dialect.on_connect` in that
| it is passed the :class:`_engine.URL` object that's relevant to the
| connect args. Normally the only way to get this is from the
| :meth:`_engine.Dialect.on_connect` hook is to look on the
| :class:`_engine.Engine` itself, however this URL object may have been
| replaced by plugins.
|
| .. note::
|
| The default implementation of
| :meth:`_engine.Dialect.on_connect_url` is to invoke the
| :meth:`_engine.Dialect.on_connect` method. Therefore if a dialect
| implements this method, the :meth:`_engine.Dialect.on_connect`
| method **will not be called** unless the overriding dialect calls
| it directly from here.
|
| .. versionadded:: 1.4.3 added :meth:`_engine.Dialect.on_connect_url`
| which normally calls into :meth:`_engine.Dialect.on_connect`.
|
| :param url: a :class:`_engine.URL` object representing the
| :class:`_engine.URL` that was passed to the
| :meth:`_engine.Dialect.create_connect_args` method.
|
| :return: a callable that accepts a single DBAPI connection as an
| argument, or None.
|
| .. seealso::
|
| :meth:`_engine.Dialect.on_connect`
|
| reset_isolation_level(self, dbapi_connection: 'DBAPIConnection') -> 'None'
| Given a DBAPI connection, revert its isolation to the default.
|
| Note that this is a dialect-level method which is used as part
| of the implementation of the :class:`_engine.Connection` and
| :class:`_engine.Engine`
| isolation level facilities; these APIs should be preferred for
| most typical use cases.
|
| .. seealso::
|
| :meth:`_engine.Connection.get_isolation_level`
| - view current level
|
| :attr:`_engine.Connection.default_isolation_level`
| - view default level
|
| :paramref:`.Connection.execution_options.isolation_level` -
| set per :class:`_engine.Connection` isolation level
|
| :paramref:`_sa.create_engine.isolation_level` -
| set per :class:`_engine.Engine` isolation level
|
| set_connection_execution_options(self, connection: 'Connection', opts: 'CoreExecuteOptionsParameter') -> 'None'
| Establish execution options for a given connection.
|
| This is implemented by :class:`.DefaultDialect` in order to implement
| the :paramref:`_engine.Connection.execution_options.isolation_level`
| execution option. Dialects can intercept various execution options
| which may need to modify state on a particular DBAPI connection.
|
| .. versionadded:: 1.4
|
| set_engine_execution_options(self, engine: 'Engine', opts: 'CoreExecuteOptionsParameter') -> 'None'
| Establish execution options for a given engine.
|
| This is implemented by :class:`.DefaultDialect` to establish
| event hooks for new :class:`.Connection` instances created
| by the given :class:`.Engine` which will then invoke the
| :meth:`.Dialect.set_connection_execution_options` method for that
| connection.
|
| set_isolation_level(self, dbapi_connection: 'DBAPIConnection', level: 'IsolationLevel') -> 'None'
| Given a DBAPI connection, set its isolation level.
|
| Note that this is a dialect-level method which is used as part
| of the implementation of the :class:`_engine.Connection` and
| :class:`_engine.Engine`
| isolation level facilities; these APIs should be preferred for
| most typical use cases.
|
| If the dialect also implements the
| :meth:`.Dialect.get_isolation_level_values` method, then the given
| level is guaranteed to be one of the string names within that sequence,
| and the method will not need to anticipate a lookup failure.
|
| .. seealso::
|
| :meth:`_engine.Connection.get_isolation_level`
| - view current level
|
| :attr:`_engine.Connection.default_isolation_level`
| - view default level
|
| :paramref:`.Connection.execution_options.isolation_level` -
| set per :class:`_engine.Connection` isolation level
|
| :paramref:`_sa.create_engine.isolation_level` -
| set per :class:`_engine.Engine` isolation level
|
| type_descriptor(self, typeobj: 'TypeEngine[_T]') -> 'TypeEngine[_T]'
| Transform a generic type to a dialect-specific type.
|
| Dialect classes will usually use the
| :func:`_types.adapt_type` function in the types module to
| accomplish this.
|
| The returned result is cached *per dialect class* so can
| contain no dialect-instance state.
|
| validate_identifier(self, ident: 'str') -> 'None'
| Validates an identifier name, raising an exception if invalid
|
| ----------------------------------------------------------------------
| Class methods defined here:
|
| engine_created(engine: 'Engine') -> 'None'
| A convenience hook called before returning the final
| :class:`_engine.Engine`.
|
| If the dialect returned a different class from the
| :meth:`.get_dialect_cls`
| method, then the hook is called on both classes, first on
| the dialect class returned by the :meth:`.get_dialect_cls` method and
| then on the class on which the method was called.
|
| The hook should be used by dialects and/or wrappers to apply special
| events to the engine or its components. In particular, it allows
| a dialect-wrapping class to apply dialect-level events.
|
| get_async_dialect_cls(url: 'URL') -> 'Type[Dialect]'
| Given a URL, return the :class:`.Dialect` that will be used by
| an async engine.
|
| By default this is an alias of :meth:`.Dialect.get_dialect_cls` and
| just returns the cls. It may be used if a dialect provides
| both a sync and async version under the same name, like the
| ``psycopg`` driver.
|
| .. versionadded:: 2
|
| .. seealso::
|
| :meth:`.Dialect.get_dialect_cls`
|
| get_dialect_cls(url: 'URL') -> 'Type[Dialect]'
| Given a URL, return the :class:`.Dialect` that will be used.
|
| This is a hook that allows an external plugin to provide functionality
| around an existing dialect, by allowing the plugin to be loaded
| from the url based on an entrypoint, and then the plugin returns
| the actual dialect to be used.
|
| By default this just returns the cls.
|
| import_dbapi() -> 'DBAPIModule'
| Import the DBAPI module that is used by this dialect.
|
| The Python module object returned here will be assigned as an
| instance variable to a constructed dialect under the name
| ``.dbapi``.
|
| .. versionchanged:: 2.0 The :meth:`.Dialect.import_dbapi` class
| method is renamed from the previous method ``.Dialect.dbapi()``,
| which would be replaced at dialect instantiation time by the
| DBAPI module itself, thus using the same name in two different ways.
| If a ``.Dialect.dbapi()`` classmethod is present on a third-party
| dialect, it will be used and a deprecation warning will be emitted.
|
| load_provisioning() -> 'None'
| set up the provision.py module for this dialect.
|
| For dialects that include a provision.py module that sets up
| provisioning followers, this method should initiate that process.
|
| A typical implementation would be::
|
| @classmethod
| def load_provisioning(cls):
| __import__("mydialect.provision")
|
| The default method assumes a module named ``provision.py`` inside
| the owning package of the current dialect, based on the ``__module__``
| attribute::
|
| @classmethod
| def load_provisioning(cls):
| package = ".".join(cls.__module__.split(".")[0:-1])
| try:
| __import__(package + ".provision")
| except ImportError:
| pass
|
| .. versionadded:: 1.3.14
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| CACHE_HIT = <CacheStats.CACHE_HIT: 0>
|
| CACHE_MISS = <CacheStats.CACHE_MISS: 1>
|
| CACHING_DISABLED = <CacheStats.CACHING_DISABLED: 2>
|
| NO_CACHE_KEY = <CacheStats.NO_CACHE_KEY: 3>
|
| NO_DIALECT_SUPPORT = <CacheStats.NO_DIALECT_SUPPORT: 4>
|
| __annotations__ = {'_bind_typing_render_casts': 'bool', '_on_connect_i...
|
| bind_typing = <BindTyping.NONE: 1>
|
| construct_arguments = None
|
| dbapi_exception_translation_map = immutabledict({})
|
| default_metavalue_token = 'DEFAULT'
|
| dispatch = <sqlalchemy.event.base.DialectEventsDispatch object>
|
| reflection_options = ()
|
| supports_statement_cache = True
sqlalchemy.Double
Python Library Documentation: class Double in module sqlalchemy.sql.sqltypes
class Double(Float)
| Double(precision: 'Optional[int]' = None, asdecimal: 'bool' = False, decimal_return_scale: 'Optional[int]' = None)
|
| A type for double ``FLOAT`` floating point types.
|
| Typically generates a ``DOUBLE`` or ``DOUBLE_PRECISION`` in DDL,
| and otherwise acts like a normal :class:`.Float` on the Python
| side.
|
| .. versionadded:: 2.0
|
| Method resolution order:
| Double
| Float
| Numeric
| HasExpressionLookup
| sqlalchemy.sql.type_api.TypeEngineMixin
| sqlalchemy.sql.type_api.TypeEngine
| sqlalchemy.sql.visitors.Visitable
| typing.Generic
| builtins.object
|
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| __parameters__ = ()
|
| __visit_name__ = 'double'
|
| ----------------------------------------------------------------------
| Methods inherited from Float:
|
| __init__(self: 'Float[_N]', precision: 'Optional[int]' = None, asdecimal: 'bool' = False, decimal_return_scale: 'Optional[int]' = None)
| Construct a Float.
|
| :param precision: the numeric precision for use in DDL ``CREATE
| TABLE``. Backends **should** attempt to ensure this precision
| indicates a number of digits for the generic
| :class:`_sqltypes.Float` datatype.
|
| .. note:: For the Oracle Database backend, the
| :paramref:`_sqltypes.Float.precision` parameter is not accepted
| when rendering DDL, as Oracle Database does not support float precision
| specified as a number of decimal places. Instead, use the
| Oracle Database-specific :class:`_oracle.FLOAT` datatype and specify the
| :paramref:`_oracle.FLOAT.binary_precision` parameter. This is new
| in version 2.0 of SQLAlchemy.
|
| To create a database agnostic :class:`_types.Float` that
| separately specifies binary precision for Oracle Database, use
| :meth:`_types.TypeEngine.with_variant` as follows::
|
| from sqlalchemy import Column
| from sqlalchemy import Float
| from sqlalchemy.dialects import oracle
|
| Column(
| "float_data",
| Float(5).with_variant(oracle.FLOAT(binary_precision=16), "oracle"),
| )
|
| :param asdecimal: the same flag as that of :class:`.Numeric`, but
| defaults to ``False``. Note that setting this flag to ``True``
| results in floating point conversion.
|
| :param decimal_return_scale: Default scale to use when converting
| from floats to Python decimals. Floating point values will typically
| be much longer due to decimal inaccuracy, and most floating point
| database types don't have a notion of "scale", so by default the
| float type looks for the first ten decimal places when converting.
| Specifying this value will override that length. Note that the
| MySQL float types, which do include "scale", will use "scale"
| as the default for decimal_return_scale, if not otherwise specified.
|
| result_processor(self, dialect, coltype)
| Return a conversion function for processing result row values.
|
| Returns a callable which will receive a result row column
| value as the sole positional argument and will return a value
| to return to the user.
|
| If processing is not necessary, the method should return ``None``.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.result_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.result_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_result_value`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| :param dialect: Dialect instance in use.
|
| :param coltype: DBAPI coltype argument received in cursor.description.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from Float:
|
| scale = None
|
| ----------------------------------------------------------------------
| Methods inherited from Numeric:
|
| bind_processor(self, dialect)
| Return a conversion function for processing bind values.
|
| Returns a callable which will receive a bind parameter value
| as the sole positional argument and will return a value to
| send to the DB-API.
|
| If processing is not necessary, the method should return ``None``.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.bind_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.bind_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_bind_param`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
|
| :param dialect: Dialect instance in use.
|
| get_dbapi_type(self, dbapi)
| Return the corresponding type object from the underlying DB-API, if
| any.
|
| This can be useful for calling ``setinputsizes()``, for example.
|
| literal_processor(self, dialect)
| Return a conversion function for processing literal values that are
| to be rendered directly without using binds.
|
| This function is used when the compiler makes use of the
| "literal_binds" flag, typically used in DDL generation as well
| as in certain scenarios where backends don't accept bound parameters.
|
| Returns a callable which will receive a literal Python value
| as the sole positional argument and will return a string representation
| to be rendered in a SQL statement.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.literal_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.literal_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_literal_param`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| ----------------------------------------------------------------------
| Readonly properties inherited from Numeric:
|
| python_type
| Return the Python type object expected to be returned
| by instances of this type, if known.
|
| Basically, for those types which enforce a return type,
| or are known across the board to do such for all common
| DBAPIs (like ``int`` for example), will return that type.
|
| If a return type is not defined, raises
| ``NotImplementedError``.
|
| Note that any type also accommodates NULL in SQL which
| means you can also get back ``None`` from any type
| in practice.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from HasExpressionLookup:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from HasExpressionLookup:
|
| Comparator = <class 'sqlalchemy.sql.sqltypes.HasExpressionLookup.Compa...
|
| comparator_factory = <class 'sqlalchemy.sql.sqltypes.HasExpressionLook...
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.type_api.TypeEngine:
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| __str__(self) -> 'str'
| Return str(self).
|
| adapt(self, cls: 'Type[Union[TypeEngine[Any], TypeEngineMixin]]', **kw: 'Any') -> 'TypeEngine[Any]'
| Produce an "adapted" form of this type, given an "impl" class
| to work with.
|
| This method is used internally to associate generic
| types with "implementation" types that are specific to a particular
| dialect.
|
| as_generic(self, allow_nulltype: 'bool' = False) -> 'TypeEngine[_T]'
| Return an instance of the generic type corresponding to this type
| using heuristic rule. The method may be overridden if this
| heuristic rule is not sufficient.
|
| >>> from sqlalchemy.dialects.mysql import INTEGER
| >>> INTEGER(display_width=4).as_generic()
| Integer()
|
| >>> from sqlalchemy.dialects.mysql import NVARCHAR
| >>> NVARCHAR(length=100).as_generic()
| Unicode(length=100)
|
| .. versionadded:: 1.4.0b2
|
|
| .. seealso::
|
| :ref:`metadata_reflection_dbagnostic_types` - describes the
| use of :meth:`_types.TypeEngine.as_generic` in conjunction with
| the :meth:`_sql.DDLEvents.column_reflect` event, which is its
| intended use.
|
| bind_expression(self, bindvalue: 'BindParameter[_T]') -> 'Optional[ColumnElement[_T]]'
| Given a bind value (i.e. a :class:`.BindParameter` instance),
| return a SQL expression in its place.
|
| This is typically a SQL function that wraps the existing bound
| parameter within the statement. It is used for special data types
| that require literals being wrapped in some special database function
| in order to coerce an application-level value into a database-specific
| format. It is the SQL analogue of the
| :meth:`.TypeEngine.bind_processor` method.
|
| This method is called during the **SQL compilation** phase of a
| statement, when rendering a SQL string. It is **not** called
| against specific values.
|
| Note that this method, when implemented, should always return
| the exact same structure, without any conditional logic, as it
| may be used in an executemany() call against an arbitrary number
| of bound parameter sets.
|
| .. note::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.bind_expression`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.bind_expression`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.bind_expression`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| .. seealso::
|
| :ref:`types_sql_value_processing`
|
| coerce_compared_value(self, op: 'Optional[OperatorType]', value: 'Any') -> 'TypeEngine[Any]'
| Suggest a type for a 'coerced' Python value in an expression.
|
| Given an operator and value, gives the type a chance
| to return a type which the value should be coerced into.
|
| The default behavior here is conservative; if the right-hand
| side is already coerced into a SQL type based on its
| Python type, it is usually left alone.
|
| End-user functionality extension here should generally be via
| :class:`.TypeDecorator`, which provides more liberal behavior in that
| it defaults to coercing the other side of the expression into this
| type, thus applying special Python conversions above and beyond those
| needed by the DBAPI to both ides. It also provides the public method
| :meth:`.TypeDecorator.coerce_compared_value` which is intended for
| end-user customization of this behavior.
|
| column_expression(self, colexpr: 'ColumnElement[_T]') -> 'Optional[ColumnElement[_T]]'
| Given a SELECT column expression, return a wrapping SQL expression.
|
| This is typically a SQL function that wraps a column expression
| as rendered in the columns clause of a SELECT statement.
| It is used for special data types that require
| columns to be wrapped in some special database function in order
| to coerce the value before being sent back to the application.
| It is the SQL analogue of the :meth:`.TypeEngine.result_processor`
| method.
|
| .. note:: The :func:`.TypeEngine.column_expression` method is applied
| only to the **outermost columns clause** of a SELECT statement, that
| is, the columns that are to be delivered directly into the returned
| result rows. It does **not** apply to the columns clause inside
| of subqueries. This necessarily avoids double conversions against
| the column and only runs the conversion when ready to be returned
| to the client.
|
| This method is called during the **SQL compilation** phase of a
| statement, when rendering a SQL string. It is **not** called
| against specific values.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.column_expression`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.column_expression`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.column_expression`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
|
| .. seealso::
|
| :ref:`types_sql_value_processing`
|
| compare_values(self, x: 'Any', y: 'Any') -> 'bool'
| Compare two values for equality.
|
| compile(self, dialect: 'Optional[Dialect]' = None) -> 'str'
| Produce a string-compiled form of this :class:`.TypeEngine`.
|
| When called with no arguments, uses a "default" dialect
| to produce a string result.
|
| :param dialect: a :class:`.Dialect` instance.
|
| copy(self, **kw: 'Any') -> 'Self'
|
| copy_value(self, value: 'Any') -> 'Any'
|
| dialect_impl(self, dialect: 'Dialect') -> 'TypeEngine[_T]'
| Return a dialect-specific implementation for this
| :class:`.TypeEngine`.
|
| evaluates_none(self) -> 'Self'
| Return a copy of this type which has the
| :attr:`.should_evaluate_none` flag set to True.
|
| E.g.::
|
| Table(
| "some_table",
| metadata,
| Column(
| String(50).evaluates_none(),
| nullable=True,
| server_default="no value",
| ),
| )
|
| The ORM uses this flag to indicate that a positive value of ``None``
| is passed to the column in an INSERT statement, rather than omitting
| the column from the INSERT statement which has the effect of firing
| off column-level defaults. It also allows for types which have
| special behavior associated with the Python None value to indicate
| that the value doesn't necessarily translate into SQL NULL; a
| prime example of this is a JSON type which may wish to persist the
| JSON value ``'null'``.
|
| In all cases, the actual NULL SQL value can be always be
| persisted in any column by using
| the :obj:`_expression.null` SQL construct in an INSERT statement
| or associated with an ORM-mapped attribute.
|
| .. note::
|
| The "evaluates none" flag does **not** apply to a value
| of ``None`` passed to :paramref:`_schema.Column.default` or
| :paramref:`_schema.Column.server_default`; in these cases,
| ``None``
| still means "no default".
|
| .. seealso::
|
| :ref:`session_forcing_null` - in the ORM documentation
|
| :paramref:`.postgresql.JSON.none_as_null` - PostgreSQL JSON
| interaction with this flag.
|
| :attr:`.TypeEngine.should_evaluate_none` - class-level flag
|
| with_variant(self, type_: '_TypeEngineArgument[Any]', *dialect_names: 'str') -> 'Self'
| Produce a copy of this type object that will utilize the given
| type when applied to the dialect of the given name.
|
| e.g.::
|
| from sqlalchemy.types import String
| from sqlalchemy.dialects import mysql
|
| string_type = String()
|
| string_type = string_type.with_variant(
| mysql.VARCHAR(collation="foo"), "mysql", "mariadb"
| )
|
| The variant mapping indicates that when this type is
| interpreted by a specific dialect, it will instead be
| transmuted into the given type, rather than using the
| primary type.
|
| .. versionchanged:: 2.0 the :meth:`_types.TypeEngine.with_variant`
| method now works with a :class:`_types.TypeEngine` object "in
| place", returning a copy of the original type rather than returning
| a wrapping object; the ``Variant`` class is no longer used.
|
| :param type\_: a :class:`.TypeEngine` that will be selected
| as a variant from the originating type, when a dialect
| of the given name is in use.
| :param \*dialect_names: one or more base names of the dialect which
| uses this type. (i.e. ``'postgresql'``, ``'mysql'``, etc.)
|
| .. versionchanged:: 2.0 multiple dialect names can be specified
| for one variant.
|
| .. seealso::
|
| :ref:`types_with_variant` - illustrates the use of
| :meth:`_types.TypeEngine.with_variant`.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.type_api.TypeEngine:
|
| __orig_bases__ = (<class 'sqlalchemy.sql.visitors.Visitable'>, typing....
|
| hashable = True
|
| render_bind_cast = False
|
| render_literal_cast = False
|
| should_evaluate_none = False
|
| sort_key_function = None
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.visitors.Visitable:
|
| __class_getitem__(key: 'Any') -> 'Any'
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__() -> 'None'
| This method is called when a class is subclassed.
|
| The default implementation does nothing. It may be
| overridden to extend subclasses.
sqlalchemy.Engine
Python Library Documentation: class Engine in module sqlalchemy.engine.base
class Engine(sqlalchemy.engine.interfaces.ConnectionEventsTarget, sqlalchemy.log.Identified, sqlalchemy.inspection.Inspectable)
| Engine(pool: 'Pool', dialect: 'Dialect', url: 'URL', logging_name: 'Optional[str]' = None, echo: 'Optional[_EchoFlagType]' = None, query_cache_size: 'int' = 500, execution_options: 'Optional[Mapping[str, Any]]' = None, hide_parameters: 'bool' = False)
|
| Connects a :class:`~sqlalchemy.pool.Pool` and
| :class:`~sqlalchemy.engine.interfaces.Dialect` together to provide a
| source of database connectivity and behavior.
|
| An :class:`_engine.Engine` object is instantiated publicly using the
| :func:`~sqlalchemy.create_engine` function.
|
| .. seealso::
|
| :doc:`/core/engines`
|
| :ref:`connections_toplevel`
|
| Method resolution order:
| Engine
| sqlalchemy.engine.interfaces.ConnectionEventsTarget
| sqlalchemy.event.registry.EventTarget
| sqlalchemy.log.Identified
| sqlalchemy.inspection.Inspectable
| typing.Generic
| builtins.object
|
| Methods defined here:
|
| __init__(self, pool: 'Pool', dialect: 'Dialect', url: 'URL', logging_name: 'Optional[str]' = None, echo: 'Optional[_EchoFlagType]' = None, query_cache_size: 'int' = 500, execution_options: 'Optional[Mapping[str, Any]]' = None, hide_parameters: 'bool' = False)
| Initialize self. See help(type(self)) for accurate signature.
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| begin(self) -> 'Iterator[Connection]'
| Return a context manager delivering a :class:`_engine.Connection`
| with a :class:`.Transaction` established.
|
| E.g.::
|
| with engine.begin() as conn:
| conn.execute(text("insert into table (x, y, z) values (1, 2, 3)"))
| conn.execute(text("my_special_procedure(5)"))
|
| Upon successful operation, the :class:`.Transaction`
| is committed. If an error is raised, the :class:`.Transaction`
| is rolled back.
|
| .. seealso::
|
| :meth:`_engine.Engine.connect` - procure a
| :class:`_engine.Connection` from
| an :class:`_engine.Engine`.
|
| :meth:`_engine.Connection.begin` - start a :class:`.Transaction`
| for a particular :class:`_engine.Connection`.
|
| clear_compiled_cache(self) -> 'None'
| Clear the compiled cache associated with the dialect.
|
| This applies **only** to the built-in cache that is established
| via the :paramref:`_engine.create_engine.query_cache_size` parameter.
| It will not impact any dictionary caches that were passed via the
| :paramref:`.Connection.execution_options.compiled_cache` parameter.
|
| .. versionadded:: 1.4
|
| connect(self) -> 'Connection'
| Return a new :class:`_engine.Connection` object.
|
| The :class:`_engine.Connection` acts as a Python context manager, so
| the typical use of this method looks like::
|
| with engine.connect() as connection:
| connection.execute(text("insert into table values ('foo')"))
| connection.commit()
|
| Where above, after the block is completed, the connection is "closed"
| and its underlying DBAPI resources are returned to the connection pool.
| This also has the effect of rolling back any transaction that
| was explicitly begun or was begun via autobegin, and will
| emit the :meth:`_events.ConnectionEvents.rollback` event if one was
| started and is still in progress.
|
| .. seealso::
|
| :meth:`_engine.Engine.begin`
|
| dispose(self, close: 'bool' = True) -> 'None'
| Dispose of the connection pool used by this
| :class:`_engine.Engine`.
|
| A new connection pool is created immediately after the old one has been
| disposed. The previous connection pool is disposed either actively, by
| closing out all currently checked-in connections in that pool, or
| passively, by losing references to it but otherwise not closing any
| connections. The latter strategy is more appropriate for an initializer
| in a forked Python process.
|
| Event listeners associated with the old pool via :class:`.PoolEvents`
| are **transferred to the new pool**; this is to support the pattern
| by which :class:`.PoolEvents` are set up in terms of the owning
| :class:`.Engine` without the need to refer to the :class:`.Pool`
| directly.
|
| :param close: if left at its default of ``True``, has the
| effect of fully closing all **currently checked in**
| database connections. Connections that are still checked out
| will **not** be closed, however they will no longer be associated
| with this :class:`_engine.Engine`,
| so when they are closed individually, eventually the
| :class:`_pool.Pool` which they are associated with will
| be garbage collected and they will be closed out fully, if
| not already closed on checkin.
|
| If set to ``False``, the previous connection pool is de-referenced,
| and otherwise not touched in any way.
|
| .. versionadded:: 1.4.33 Added the :paramref:`.Engine.dispose.close`
| parameter to allow the replacement of a connection pool in a child
| process without interfering with the connections used by the parent
| process.
|
|
| .. seealso::
|
| :ref:`engine_disposal`
|
| :ref:`pooling_multiprocessing`
|
| :meth:`.ConnectionEvents.engine_disposed`
|
| execution_options(self, **opt: 'Any') -> 'OptionEngine'
| Return a new :class:`_engine.Engine` that will provide
| :class:`_engine.Connection` objects with the given execution options.
|
| The returned :class:`_engine.Engine` remains related to the original
| :class:`_engine.Engine` in that it shares the same connection pool and
| other state:
|
| * The :class:`_pool.Pool` used by the new :class:`_engine.Engine`
| is the
| same instance. The :meth:`_engine.Engine.dispose`
| method will replace
| the connection pool instance for the parent engine as well
| as this one.
| * Event listeners are "cascaded" - meaning, the new
| :class:`_engine.Engine`
| inherits the events of the parent, and new events can be associated
| with the new :class:`_engine.Engine` individually.
| * The logging configuration and logging_name is copied from the parent
| :class:`_engine.Engine`.
|
| The intent of the :meth:`_engine.Engine.execution_options` method is
| to implement schemes where multiple :class:`_engine.Engine`
| objects refer to the same connection pool, but are differentiated
| by options that affect some execution-level behavior for each
| engine. One such example is breaking into separate "reader" and
| "writer" :class:`_engine.Engine` instances, where one
| :class:`_engine.Engine`
| has a lower :term:`isolation level` setting configured or is even
| transaction-disabled using "autocommit". An example of this
| configuration is at :ref:`dbapi_autocommit_multiple`.
|
| Another example is one that
| uses a custom option ``shard_id`` which is consumed by an event
| to change the current schema on a database connection::
|
| from sqlalchemy import event
| from sqlalchemy.engine import Engine
|
| primary_engine = create_engine("mysql+mysqldb://")
| shard1 = primary_engine.execution_options(shard_id="shard1")
| shard2 = primary_engine.execution_options(shard_id="shard2")
|
| shards = {"default": "base", "shard_1": "db1", "shard_2": "db2"}
|
|
| @event.listens_for(Engine, "before_cursor_execute")
| def _switch_shard(conn, cursor, stmt, params, context, executemany):
| shard_id = conn.get_execution_options().get("shard_id", "default")
| current_shard = conn.info.get("current_shard", None)
|
| if current_shard != shard_id:
| cursor.execute("use %s" % shards[shard_id])
| conn.info["current_shard"] = shard_id
|
| The above recipe illustrates two :class:`_engine.Engine` objects that
| will each serve as factories for :class:`_engine.Connection` objects
| that have pre-established "shard_id" execution options present. A
| :meth:`_events.ConnectionEvents.before_cursor_execute` event handler
| then interprets this execution option to emit a MySQL ``use`` statement
| to switch databases before a statement execution, while at the same
| time keeping track of which database we've established using the
| :attr:`_engine.Connection.info` dictionary.
|
| .. seealso::
|
| :meth:`_engine.Connection.execution_options`
| - update execution options
| on a :class:`_engine.Connection` object.
|
| :meth:`_engine.Engine.update_execution_options`
| - update the execution
| options for a given :class:`_engine.Engine` in place.
|
| :meth:`_engine.Engine.get_execution_options`
|
| get_execution_options(self) -> '_ExecuteOptions'
| Get the non-SQL options which will take effect during execution.
|
| .. versionadded: 1.3
|
| .. seealso::
|
| :meth:`_engine.Engine.execution_options`
|
| raw_connection(self) -> 'PoolProxiedConnection'
| Return a "raw" DBAPI connection from the connection pool.
|
| The returned object is a proxied version of the DBAPI
| connection object used by the underlying driver in use.
| The object will have all the same behavior as the real DBAPI
| connection, except that its ``close()`` method will result in the
| connection being returned to the pool, rather than being closed
| for real.
|
| This method provides direct DBAPI connection access for
| special situations when the API provided by
| :class:`_engine.Connection`
| is not needed. When a :class:`_engine.Connection` object is already
| present, the DBAPI connection is available using
| the :attr:`_engine.Connection.connection` accessor.
|
| .. seealso::
|
| :ref:`dbapi_connections`
|
| update_execution_options(self, **opt: 'Any') -> 'None'
| Update the default execution_options dictionary
| of this :class:`_engine.Engine`.
|
| The given keys/values in \**opt are added to the
| default execution options that will be used for
| all connections. The initial contents of this dictionary
| can be sent via the ``execution_options`` parameter
| to :func:`_sa.create_engine`.
|
| .. seealso::
|
| :meth:`_engine.Connection.execution_options`
|
| :meth:`_engine.Engine.execution_options`
|
| ----------------------------------------------------------------------
| Readonly properties defined here:
|
| driver
| Driver name of the :class:`~sqlalchemy.engine.interfaces.Dialect`
| in use by this :class:`Engine`.
|
| engine
| Returns this :class:`.Engine`.
|
| Used for legacy schemes that accept :class:`.Connection` /
| :class:`.Engine` objects within the same variable.
|
| name
| String name of the :class:`~sqlalchemy.engine.interfaces.Dialect`
| in use by this :class:`Engine`.
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| echo
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'_compiled_cache': 'Optional[CompiledCacheType]', '...
|
| __orig_bases__ = (<class 'sqlalchemy.engine.interfaces.ConnectionEvent...
|
| __parameters__ = ()
|
| ----------------------------------------------------------------------
| Data descriptors inherited from sqlalchemy.engine.interfaces.ConnectionEventsTarget:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.engine.interfaces.ConnectionEventsTarget:
|
| dispatch = <sqlalchemy.event.base.ConnectionEventsDispatch object>
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.log.Identified:
|
| logging_name = None
|
| ----------------------------------------------------------------------
| Class methods inherited from typing.Generic:
|
| __class_getitem__(...)
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__(...)
| Function to initialize subclasses.
sqlalchemy.Enum
Python Library Documentation: class Enum in module sqlalchemy.sql.sqltypes
class Enum(String, SchemaType, sqlalchemy.sql.type_api.Emulated, sqlalchemy.sql.type_api.TypeEngine)
| Enum(*enums: 'Union[str, Type[enum.Enum]]', **kw: 'Any') -> 'None'
|
| Generic Enum Type.
|
| The :class:`.Enum` type provides a set of possible string values
| which the column is constrained towards.
|
| The :class:`.Enum` type will make use of the backend's native "ENUM"
| type if one is available; otherwise, it uses a VARCHAR datatype.
| An option also exists to automatically produce a CHECK constraint
| when the VARCHAR (so called "non-native") variant is produced;
| see the :paramref:`.Enum.create_constraint` flag.
|
| The :class:`.Enum` type also provides in-Python validation of string
| values during both read and write operations. When reading a value
| from the database in a result set, the string value is always checked
| against the list of possible values and a ``LookupError`` is raised
| if no match is found. When passing a value to the database as a
| plain string within a SQL statement, if the
| :paramref:`.Enum.validate_strings` parameter is
| set to True, a ``LookupError`` is raised for any string value that's
| not located in the given list of possible values; note that this
| impacts usage of LIKE expressions with enumerated values (an unusual
| use case).
|
| The source of enumerated values may be a list of string values, or
| alternatively a PEP-435-compliant enumerated class. For the purposes
| of the :class:`.Enum` datatype, this class need only provide a
| ``__members__`` method.
|
| When using an enumerated class, the enumerated objects are used
| both for input and output, rather than strings as is the case with
| a plain-string enumerated type::
|
| import enum
| from sqlalchemy import Enum
|
|
| class MyEnum(enum.Enum):
| one = 1
| two = 2
| three = 3
|
|
| t = Table("data", MetaData(), Column("value", Enum(MyEnum)))
|
| connection.execute(t.insert(), {"value": MyEnum.two})
| assert connection.scalar(t.select()) is MyEnum.two
|
| Above, the string names of each element, e.g. "one", "two", "three",
| are persisted to the database; the values of the Python Enum, here
| indicated as integers, are **not** used; the value of each enum can
| therefore be any kind of Python object whether or not it is persistable.
|
| In order to persist the values and not the names, the
| :paramref:`.Enum.values_callable` parameter may be used. The value of
| this parameter is a user-supplied callable, which is intended to be used
| with a PEP-435-compliant enumerated class and returns a list of string
| values to be persisted. For a simple enumeration that uses string values,
| a callable such as ``lambda x: [e.value for e in x]`` is sufficient.
|
| .. seealso::
|
| :ref:`orm_declarative_mapped_column_enums` - background on using
| the :class:`_sqltypes.Enum` datatype with the ORM's
| :ref:`ORM Annotated Declarative <orm_declarative_mapped_column>`
| feature.
|
| :class:`_postgresql.ENUM` - PostgreSQL-specific type,
| which has additional functionality.
|
| :class:`.mysql.ENUM` - MySQL-specific type
|
| Method resolution order:
| Enum
| String
| Concatenable
| SchemaType
| sqlalchemy.sql.base.SchemaEventTarget
| sqlalchemy.event.registry.EventTarget
| sqlalchemy.sql.type_api.Emulated
| sqlalchemy.sql.type_api.TypeEngineMixin
| sqlalchemy.sql.type_api.TypeEngine
| sqlalchemy.sql.visitors.Visitable
| typing.Generic
| builtins.object
|
| Methods defined here:
|
| __init__(self, *enums: 'Union[str, Type[enum.Enum]]', **kw: 'Any') -> 'None'
| Construct an enum.
|
| Keyword arguments which don't apply to a specific backend are ignored
| by that backend.
|
| :param \*enums: either exactly one PEP-435 compliant enumerated type
| or one or more string labels.
|
| :param create_constraint: defaults to False. When creating a
| non-native enumerated type, also build a CHECK constraint on the
| database against the valid values.
|
| .. note:: it is strongly recommended that the CHECK constraint
| have an explicit name in order to support schema-management
| concerns. This can be established either by setting the
| :paramref:`.Enum.name` parameter or by setting up an
| appropriate naming convention; see
| :ref:`constraint_naming_conventions` for background.
|
| .. versionchanged:: 1.4 - this flag now defaults to False, meaning
| no CHECK constraint is generated for a non-native enumerated
| type.
|
| :param metadata: Associate this type directly with a ``MetaData``
| object. For types that exist on the target database as an
| independent schema construct (PostgreSQL), this type will be
| created and dropped within ``create_all()`` and ``drop_all()``
| operations. If the type is not associated with any ``MetaData``
| object, it will associate itself with each ``Table`` in which it is
| used, and will be created when any of those individual tables are
| created, after a check is performed for its existence. The type is
| only dropped when ``drop_all()`` is called for that ``Table``
| object's metadata, however.
|
| The value of the :paramref:`_schema.MetaData.schema` parameter of
| the :class:`_schema.MetaData` object, if set, will be used as the
| default value of the :paramref:`_types.Enum.schema` on this object
| if an explicit value is not otherwise supplied.
|
| .. versionchanged:: 1.4.12 :class:`_types.Enum` inherits the
| :paramref:`_schema.MetaData.schema` parameter of the
| :class:`_schema.MetaData` object if present, when passed using
| the :paramref:`_types.Enum.metadata` parameter.
|
| :param name: The name of this type. This is required for PostgreSQL
| and any future supported database which requires an explicitly
| named type, or an explicitly named constraint in order to generate
| the type and/or a table that uses it. If a PEP-435 enumerated
| class was used, its name (converted to lower case) is used by
| default.
|
| :param native_enum: Use the database's native ENUM type when
| available. Defaults to True. When False, uses VARCHAR + check
| constraint for all backends. When False, the VARCHAR length can be
| controlled with :paramref:`.Enum.length`; currently "length" is
| ignored if native_enum=True.
|
| :param length: Allows specifying a custom length for the VARCHAR
| when a non-native enumeration datatype is used. By default it uses
| the length of the longest value.
|
| .. versionchanged:: 2.0.0 The :paramref:`.Enum.length` parameter
| is used unconditionally for ``VARCHAR`` rendering regardless of
| the :paramref:`.Enum.native_enum` parameter, for those backends
| where ``VARCHAR`` is used for enumerated datatypes.
|
|
| :param schema: Schema name of this type. For types that exist on the
| target database as an independent schema construct (PostgreSQL),
| this parameter specifies the named schema in which the type is
| present.
|
| If not present, the schema name will be taken from the
| :class:`_schema.MetaData` collection if passed as
| :paramref:`_types.Enum.metadata`, for a :class:`_schema.MetaData`
| that includes the :paramref:`_schema.MetaData.schema` parameter.
|
| .. versionchanged:: 1.4.12 :class:`_types.Enum` inherits the
| :paramref:`_schema.MetaData.schema` parameter of the
| :class:`_schema.MetaData` object if present, when passed using
| the :paramref:`_types.Enum.metadata` parameter.
|
| Otherwise, if the :paramref:`_types.Enum.inherit_schema` flag is set
| to ``True``, the schema will be inherited from the associated
| :class:`_schema.Table` object if any; when
| :paramref:`_types.Enum.inherit_schema` is at its default of
| ``False``, the owning table's schema is **not** used.
|
|
| :param quote: Set explicit quoting preferences for the type's name.
|
| :param inherit_schema: When ``True``, the "schema" from the owning
| :class:`_schema.Table`
| will be copied to the "schema" attribute of this
| :class:`.Enum`, replacing whatever value was passed for the
| ``schema`` attribute. This also takes effect when using the
| :meth:`_schema.Table.to_metadata` operation.
|
| :param validate_strings: when True, string values that are being
| passed to the database in a SQL statement will be checked
| for validity against the list of enumerated values. Unrecognized
| values will result in a ``LookupError`` being raised.
|
| :param values_callable: A callable which will be passed the PEP-435
| compliant enumerated type, which should then return a list of string
| values to be persisted. This allows for alternate usages such as
| using the string value of an enum to be persisted to the database
| instead of its name. The callable must return the values to be
| persisted in the same order as iterating through the Enum's
| ``__member__`` attribute. For example
| ``lambda x: [i.value for i in x]``.
|
| .. versionadded:: 1.2.3
|
| :param sort_key_function: a Python callable which may be used as the
| "key" argument in the Python ``sorted()`` built-in. The SQLAlchemy
| ORM requires that primary key columns which are mapped must
| be sortable in some way. When using an unsortable enumeration
| object such as a Python 3 ``Enum`` object, this parameter may be
| used to set a default sort key function for the objects. By
| default, the database value of the enumeration is used as the
| sorting function.
|
| .. versionadded:: 1.3.8
|
| :param omit_aliases: A boolean that when true will remove aliases from
| pep 435 enums. defaults to ``True``.
|
| .. versionchanged:: 2.0 This parameter now defaults to True.
|
| __repr__(self)
| Return repr(self).
|
| adapt(self, cls, **kw)
| Produce an "adapted" form of this type, given an "impl" class
| to work with.
|
| This method is used internally to associate generic
| types with "implementation" types that are specific to a particular
| dialect.
|
| adapt_to_emulated(self, impltype, **kw)
| Given an impl class, adapt this type to the impl assuming
| "emulated".
|
| The impl should also be an "emulated" version of this type,
| most likely the same class as this type itself.
|
| e.g.: sqltypes.Enum adapts to the Enum class.
|
| as_generic(self, allow_nulltype=False)
| Return an instance of the generic type corresponding to this type
| using heuristic rule. The method may be overridden if this
| heuristic rule is not sufficient.
|
| >>> from sqlalchemy.dialects.mysql import INTEGER
| >>> INTEGER(display_width=4).as_generic()
| Integer()
|
| >>> from sqlalchemy.dialects.mysql import NVARCHAR
| >>> NVARCHAR(length=100).as_generic()
| Unicode(length=100)
|
| .. versionadded:: 1.4.0b2
|
|
| .. seealso::
|
| :ref:`metadata_reflection_dbagnostic_types` - describes the
| use of :meth:`_types.TypeEngine.as_generic` in conjunction with
| the :meth:`_sql.DDLEvents.column_reflect` event, which is its
| intended use.
|
| bind_processor(self, dialect)
| Return a conversion function for processing bind values.
|
| Returns a callable which will receive a bind parameter value
| as the sole positional argument and will return a value to
| send to the DB-API.
|
| If processing is not necessary, the method should return ``None``.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.bind_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.bind_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_bind_param`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
|
| :param dialect: Dialect instance in use.
|
| copy(self, **kw)
|
| literal_processor(self, dialect)
| Return a conversion function for processing literal values that are
| to be rendered directly without using binds.
|
| This function is used when the compiler makes use of the
| "literal_binds" flag, typically used in DDL generation as well
| as in certain scenarios where backends don't accept bound parameters.
|
| Returns a callable which will receive a literal Python value
| as the sole positional argument and will return a string representation
| to be rendered in a SQL statement.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.literal_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.literal_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_literal_param`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| result_processor(self, dialect, coltype)
| Return a conversion function for processing result row values.
|
| Returns a callable which will receive a result row column
| value as the sole positional argument and will return a value
| to return to the user.
|
| If processing is not necessary, the method should return ``None``.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.result_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.result_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_result_value`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| :param dialect: Dialect instance in use.
|
| :param coltype: DBAPI coltype argument received in cursor.description.
|
| ----------------------------------------------------------------------
| Readonly properties defined here:
|
| native
|
| python_type
| Return the Python type object expected to be returned
| by instances of this type, if known.
|
| Basically, for those types which enforce a return type,
| or are known across the board to do such for all common
| DBAPIs (like ``int`` for example), will return that type.
|
| If a return type is not defined, raises
| ``NotImplementedError``.
|
| Note that any type also accommodates NULL in SQL which
| means you can also get back ``None`` from any type
| in practice.
|
| sort_key_function
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| Comparator = <class 'sqlalchemy.sql.sqltypes.Enum.Comparator'>
|
| __annotations__ = {'_object_lookup': 'Dict[Optional[str], Union[enum.E...
|
| __parameters__ = ()
|
| __visit_name__ = 'enum'
|
| comparator_factory = <class 'sqlalchemy.sql.sqltypes.Enum.Comparator'>
|
| ----------------------------------------------------------------------
| Methods inherited from String:
|
| get_dbapi_type(self, dbapi)
| Return the corresponding type object from the underlying DB-API, if
| any.
|
| This can be useful for calling ``setinputsizes()``, for example.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from Concatenable:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Methods inherited from SchemaType:
|
| create(self, bind: '_CreateDropBind', checkfirst: 'bool' = False) -> 'None'
| Issue CREATE DDL for this type, if applicable.
|
| drop(self, bind: '_CreateDropBind', checkfirst: 'bool' = False) -> 'None'
| Issue DROP DDL for this type, if applicable.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.base.SchemaEventTarget:
|
| dispatch = <sqlalchemy.event.base.DDLEventsDispatch object>
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.type_api.TypeEngine:
|
| __str__(self) -> 'str'
| Return str(self).
|
| bind_expression(self, bindvalue: 'BindParameter[_T]') -> 'Optional[ColumnElement[_T]]'
| Given a bind value (i.e. a :class:`.BindParameter` instance),
| return a SQL expression in its place.
|
| This is typically a SQL function that wraps the existing bound
| parameter within the statement. It is used for special data types
| that require literals being wrapped in some special database function
| in order to coerce an application-level value into a database-specific
| format. It is the SQL analogue of the
| :meth:`.TypeEngine.bind_processor` method.
|
| This method is called during the **SQL compilation** phase of a
| statement, when rendering a SQL string. It is **not** called
| against specific values.
|
| Note that this method, when implemented, should always return
| the exact same structure, without any conditional logic, as it
| may be used in an executemany() call against an arbitrary number
| of bound parameter sets.
|
| .. note::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.bind_expression`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.bind_expression`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.bind_expression`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| .. seealso::
|
| :ref:`types_sql_value_processing`
|
| coerce_compared_value(self, op: 'Optional[OperatorType]', value: 'Any') -> 'TypeEngine[Any]'
| Suggest a type for a 'coerced' Python value in an expression.
|
| Given an operator and value, gives the type a chance
| to return a type which the value should be coerced into.
|
| The default behavior here is conservative; if the right-hand
| side is already coerced into a SQL type based on its
| Python type, it is usually left alone.
|
| End-user functionality extension here should generally be via
| :class:`.TypeDecorator`, which provides more liberal behavior in that
| it defaults to coercing the other side of the expression into this
| type, thus applying special Python conversions above and beyond those
| needed by the DBAPI to both ides. It also provides the public method
| :meth:`.TypeDecorator.coerce_compared_value` which is intended for
| end-user customization of this behavior.
|
| column_expression(self, colexpr: 'ColumnElement[_T]') -> 'Optional[ColumnElement[_T]]'
| Given a SELECT column expression, return a wrapping SQL expression.
|
| This is typically a SQL function that wraps a column expression
| as rendered in the columns clause of a SELECT statement.
| It is used for special data types that require
| columns to be wrapped in some special database function in order
| to coerce the value before being sent back to the application.
| It is the SQL analogue of the :meth:`.TypeEngine.result_processor`
| method.
|
| .. note:: The :func:`.TypeEngine.column_expression` method is applied
| only to the **outermost columns clause** of a SELECT statement, that
| is, the columns that are to be delivered directly into the returned
| result rows. It does **not** apply to the columns clause inside
| of subqueries. This necessarily avoids double conversions against
| the column and only runs the conversion when ready to be returned
| to the client.
|
| This method is called during the **SQL compilation** phase of a
| statement, when rendering a SQL string. It is **not** called
| against specific values.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.column_expression`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.column_expression`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.column_expression`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
|
| .. seealso::
|
| :ref:`types_sql_value_processing`
|
| compare_values(self, x: 'Any', y: 'Any') -> 'bool'
| Compare two values for equality.
|
| compile(self, dialect: 'Optional[Dialect]' = None) -> 'str'
| Produce a string-compiled form of this :class:`.TypeEngine`.
|
| When called with no arguments, uses a "default" dialect
| to produce a string result.
|
| :param dialect: a :class:`.Dialect` instance.
|
| copy_value(self, value: 'Any') -> 'Any'
|
| dialect_impl(self, dialect: 'Dialect') -> 'TypeEngine[_T]'
| Return a dialect-specific implementation for this
| :class:`.TypeEngine`.
|
| evaluates_none(self) -> 'Self'
| Return a copy of this type which has the
| :attr:`.should_evaluate_none` flag set to True.
|
| E.g.::
|
| Table(
| "some_table",
| metadata,
| Column(
| String(50).evaluates_none(),
| nullable=True,
| server_default="no value",
| ),
| )
|
| The ORM uses this flag to indicate that a positive value of ``None``
| is passed to the column in an INSERT statement, rather than omitting
| the column from the INSERT statement which has the effect of firing
| off column-level defaults. It also allows for types which have
| special behavior associated with the Python None value to indicate
| that the value doesn't necessarily translate into SQL NULL; a
| prime example of this is a JSON type which may wish to persist the
| JSON value ``'null'``.
|
| In all cases, the actual NULL SQL value can be always be
| persisted in any column by using
| the :obj:`_expression.null` SQL construct in an INSERT statement
| or associated with an ORM-mapped attribute.
|
| .. note::
|
| The "evaluates none" flag does **not** apply to a value
| of ``None`` passed to :paramref:`_schema.Column.default` or
| :paramref:`_schema.Column.server_default`; in these cases,
| ``None``
| still means "no default".
|
| .. seealso::
|
| :ref:`session_forcing_null` - in the ORM documentation
|
| :paramref:`.postgresql.JSON.none_as_null` - PostgreSQL JSON
| interaction with this flag.
|
| :attr:`.TypeEngine.should_evaluate_none` - class-level flag
|
| with_variant(self, type_: '_TypeEngineArgument[Any]', *dialect_names: 'str') -> 'Self'
| Produce a copy of this type object that will utilize the given
| type when applied to the dialect of the given name.
|
| e.g.::
|
| from sqlalchemy.types import String
| from sqlalchemy.dialects import mysql
|
| string_type = String()
|
| string_type = string_type.with_variant(
| mysql.VARCHAR(collation="foo"), "mysql", "mariadb"
| )
|
| The variant mapping indicates that when this type is
| interpreted by a specific dialect, it will instead be
| transmuted into the given type, rather than using the
| primary type.
|
| .. versionchanged:: 2.0 the :meth:`_types.TypeEngine.with_variant`
| method now works with a :class:`_types.TypeEngine` object "in
| place", returning a copy of the original type rather than returning
| a wrapping object; the ``Variant`` class is no longer used.
|
| :param type\_: a :class:`.TypeEngine` that will be selected
| as a variant from the originating type, when a dialect
| of the given name is in use.
| :param \*dialect_names: one or more base names of the dialect which
| uses this type. (i.e. ``'postgresql'``, ``'mysql'``, etc.)
|
| .. versionchanged:: 2.0 multiple dialect names can be specified
| for one variant.
|
| .. seealso::
|
| :ref:`types_with_variant` - illustrates the use of
| :meth:`_types.TypeEngine.with_variant`.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.type_api.TypeEngine:
|
| __orig_bases__ = (<class 'sqlalchemy.sql.visitors.Visitable'>, typing....
|
| hashable = True
|
| render_bind_cast = False
|
| render_literal_cast = False
|
| should_evaluate_none = False
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.visitors.Visitable:
|
| __class_getitem__(key: 'Any') -> 'Any'
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__() -> 'None'
| This method is called when a class is subclassed.
|
| The default implementation does nothing. It may be
| overridden to extend subclasses.
sqlalchemy.ExceptionContext
Python Library Documentation: class ExceptionContext in module sqlalchemy.engine.interfaces
class ExceptionContext(builtins.object)
| Encapsulate information about an error condition in progress.
|
| This object exists solely to be passed to the
| :meth:`_events.DialectEvents.handle_error` event,
| supporting an interface that
| can be extended without backwards-incompatibility.
|
| Data and other attributes defined here:
|
| __annotations__ = {'chained_exception': 'Optional[BaseException]', 'co...
sqlalchemy.Executable
Python Library Documentation: class Executable in module sqlalchemy.sql.base
class Executable(sqlalchemy.sql.roles.StatementRole)
| Mark a :class:`_expression.ClauseElement` as supporting execution.
|
| :class:`.Executable` is a superclass for all "statement" types
| of objects, including :func:`select`, :func:`delete`, :func:`update`,
| :func:`insert`, :func:`text`.
|
| Method resolution order:
| Executable
| sqlalchemy.sql.roles.StatementRole
| sqlalchemy.sql.roles.SQLRole
| builtins.object
|
| Methods defined here:
|
| execution_options(self, **kw: 'Any') -> 'Self'
| Set non-SQL options for the statement which take effect during
| execution.
|
| Execution options can be set at many scopes, including per-statement,
| per-connection, or per execution, using methods such as
| :meth:`_engine.Connection.execution_options` and parameters which
| accept a dictionary of options such as
| :paramref:`_engine.Connection.execute.execution_options` and
| :paramref:`_orm.Session.execute.execution_options`.
|
| The primary characteristic of an execution option, as opposed to
| other kinds of options such as ORM loader options, is that
| **execution options never affect the compiled SQL of a query, only
| things that affect how the SQL statement itself is invoked or how
| results are fetched**. That is, execution options are not part of
| what's accommodated by SQL compilation nor are they considered part of
| the cached state of a statement.
|
| The :meth:`_sql.Executable.execution_options` method is
| :term:`generative`, as
| is the case for the method as applied to the :class:`_engine.Engine`
| and :class:`_orm.Query` objects, which means when the method is called,
| a copy of the object is returned, which applies the given parameters to
| that new copy, but leaves the original unchanged::
|
| statement = select(table.c.x, table.c.y)
| new_statement = statement.execution_options(my_option=True)
|
| An exception to this behavior is the :class:`_engine.Connection`
| object, where the :meth:`_engine.Connection.execution_options` method
| is explicitly **not** generative.
|
| The kinds of options that may be passed to
| :meth:`_sql.Executable.execution_options` and other related methods and
| parameter dictionaries include parameters that are explicitly consumed
| by SQLAlchemy Core or ORM, as well as arbitrary keyword arguments not
| defined by SQLAlchemy, which means the methods and/or parameter
| dictionaries may be used for user-defined parameters that interact with
| custom code, which may access the parameters using methods such as
| :meth:`_sql.Executable.get_execution_options` and
| :meth:`_engine.Connection.get_execution_options`, or within selected
| event hooks using a dedicated ``execution_options`` event parameter
| such as
| :paramref:`_events.ConnectionEvents.before_execute.execution_options`
| or :attr:`_orm.ORMExecuteState.execution_options`, e.g.::
|
| from sqlalchemy import event
|
|
| @event.listens_for(some_engine, "before_execute")
| def _process_opt(conn, statement, multiparams, params, execution_options):
| "run a SQL function before invoking a statement"
|
| if execution_options.get("do_special_thing", False):
| conn.exec_driver_sql("run_special_function()")
|
| Within the scope of options that are explicitly recognized by
| SQLAlchemy, most apply to specific classes of objects and not others.
| The most common execution options include:
|
| * :paramref:`_engine.Connection.execution_options.isolation_level` -
| sets the isolation level for a connection or a class of connections
| via an :class:`_engine.Engine`. This option is accepted only
| by :class:`_engine.Connection` or :class:`_engine.Engine`.
|
| * :paramref:`_engine.Connection.execution_options.stream_results` -
| indicates results should be fetched using a server side cursor;
| this option is accepted by :class:`_engine.Connection`, by the
| :paramref:`_engine.Connection.execute.execution_options` parameter
| on :meth:`_engine.Connection.execute`, and additionally by
| :meth:`_sql.Executable.execution_options` on a SQL statement object,
| as well as by ORM constructs like :meth:`_orm.Session.execute`.
|
| * :paramref:`_engine.Connection.execution_options.compiled_cache` -
| indicates a dictionary that will serve as the
| :ref:`SQL compilation cache <sql_caching>`
| for a :class:`_engine.Connection` or :class:`_engine.Engine`, as
| well as for ORM methods like :meth:`_orm.Session.execute`.
| Can be passed as ``None`` to disable caching for statements.
| This option is not accepted by
| :meth:`_sql.Executable.execution_options` as it is inadvisable to
| carry along a compilation cache within a statement object.
|
| * :paramref:`_engine.Connection.execution_options.schema_translate_map`
| - a mapping of schema names used by the
| :ref:`Schema Translate Map <schema_translating>` feature, accepted
| by :class:`_engine.Connection`, :class:`_engine.Engine`,
| :class:`_sql.Executable`, as well as by ORM constructs
| like :meth:`_orm.Session.execute`.
|
| .. seealso::
|
| :meth:`_engine.Connection.execution_options`
|
| :paramref:`_engine.Connection.execute.execution_options`
|
| :paramref:`_orm.Session.execute.execution_options`
|
| :ref:`orm_queryguide_execution_options` - documentation on all
| ORM-specific execution options
|
| get_execution_options(self) -> '_ExecuteOptions'
| Get the non-SQL options which will take effect during execution.
|
| .. versionadded:: 1.3
|
| .. seealso::
|
| :meth:`.Executable.execution_options`
|
| options(self, *options: 'ExecutableOption') -> 'Self'
| Apply options to this statement.
|
| In the general sense, options are any kind of Python object
| that can be interpreted by the SQL compiler for the statement.
| These options can be consumed by specific dialects or specific kinds
| of compilers.
|
| The most commonly known kind of option are the ORM level options
| that apply "eager load" and other loading behaviors to an ORM
| query. However, options can theoretically be used for many other
| purposes.
|
| For background on specific kinds of options for specific kinds of
| statements, refer to the documentation for those option objects.
|
| .. versionchanged:: 1.4 - added :meth:`.Executable.options` to
| Core statement objects towards the goal of allowing unified
| Core / ORM querying capabilities.
|
| .. seealso::
|
| :ref:`loading_columns` - refers to options specific to the usage
| of ORM queries
|
| :ref:`relationship_loader_options` - refers to options specific
| to the usage of ORM queries
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'_compile_options': 'Optional[Union[Type[CacheableO...
|
| is_delete = False
|
| is_dml = False
|
| is_from_statement = False
|
| is_insert = False
|
| is_select = False
|
| is_text = False
|
| is_update = False
|
| supports_execution = True
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.SQLRole:
|
| allows_lambda = False
|
| uses_inspection = False
sqlalchemy.ExecutableDDLElement
Python Library Documentation: class ExecutableDDLElement in module sqlalchemy.sql.ddl
class ExecutableDDLElement(sqlalchemy.sql.roles.DDLRole, sqlalchemy.sql.base.Executable, BaseDDLElement)
| Base class for standalone executable DDL expression constructs.
|
| This class is the base for the general purpose :class:`.DDL` class,
| as well as the various create/drop clause constructs such as
| :class:`.CreateTable`, :class:`.DropTable`, :class:`.AddConstraint`,
| etc.
|
| .. versionchanged:: 2.0 :class:`.ExecutableDDLElement` is renamed from
| :class:`.DDLElement`, which still exists for backwards compatibility.
|
| :class:`.ExecutableDDLElement` integrates closely with SQLAlchemy events,
| introduced in :ref:`event_toplevel`. An instance of one is
| itself an event receiving callable::
|
| event.listen(
| users,
| "after_create",
| AddConstraint(constraint).execute_if(dialect="postgresql"),
| )
|
| .. seealso::
|
| :class:`.DDL`
|
| :class:`.DDLEvents`
|
| :ref:`event_toplevel`
|
| :ref:`schema_ddl_sequences`
|
| Method resolution order:
| ExecutableDDLElement
| sqlalchemy.sql.roles.DDLRole
| sqlalchemy.sql.base.Executable
| sqlalchemy.sql.roles.StatementRole
| sqlalchemy.sql.roles.SQLRole
| BaseDDLElement
| sqlalchemy.sql.elements.ClauseElement
| sqlalchemy.sql.annotation.SupportsWrappingAnnotations
| sqlalchemy.sql.annotation.SupportsAnnotations
| sqlalchemy.sql.cache_key.MemoizedHasCacheKey
| sqlalchemy.sql.cache_key.HasCacheKey
| sqlalchemy.util.langhelpers.HasMemoized
| sqlalchemy.sql.traversals.HasCopyInternals
| sqlalchemy.sql.visitors.ExternallyTraversible
| sqlalchemy.sql.visitors.HasTraverseInternals
| sqlalchemy.sql.elements.CompilerElement
| sqlalchemy.sql.visitors.Visitable
| builtins.object
|
| Methods defined here:
|
| __call__(self, target, bind, **kw)
| Execute the DDL as a ddl_listener.
|
| against(self, target: 'SchemaItem') -> 'Self'
| Return a copy of this :class:`_schema.ExecutableDDLElement` which
| will include the given target.
|
| This essentially applies the given item to the ``.target`` attribute of
| the returned :class:`_schema.ExecutableDDLElement` object. This target
| is then usable by event handlers and compilation routines in order to
| provide services such as tokenization of a DDL string in terms of a
| particular :class:`_schema.Table`.
|
| When a :class:`_schema.ExecutableDDLElement` object is established as
| an event handler for the :meth:`_events.DDLEvents.before_create` or
| :meth:`_events.DDLEvents.after_create` events, and the event then
| occurs for a given target such as a :class:`_schema.Constraint` or
| :class:`_schema.Table`, that target is established with a copy of the
| :class:`_schema.ExecutableDDLElement` object using this method, which
| then proceeds to the :meth:`_schema.ExecutableDDLElement.execute`
| method in order to invoke the actual DDL instruction.
|
| :param target: a :class:`_schema.SchemaItem` that will be the subject
| of a DDL operation.
|
| :return: a copy of this :class:`_schema.ExecutableDDLElement` with the
| ``.target`` attribute assigned to the given
| :class:`_schema.SchemaItem`.
|
| .. seealso::
|
| :class:`_schema.DDL` - uses tokenization against the "target" when
| processing the DDL string.
|
| execute_if(self, dialect: 'Optional[str]' = None, callable_: 'Optional[DDLIfCallable]' = None, state: 'Optional[Any]' = None) -> 'Self'
| Return a callable that will execute this
| :class:`_ddl.ExecutableDDLElement` conditionally within an event
| handler.
|
| Used to provide a wrapper for event listening::
|
| event.listen(
| metadata,
| "before_create",
| DDL("my_ddl").execute_if(dialect="postgresql"),
| )
|
| :param dialect: May be a string or tuple of strings.
| If a string, it will be compared to the name of the
| executing database dialect::
|
| DDL("something").execute_if(dialect="postgresql")
|
| If a tuple, specifies multiple dialect names::
|
| DDL("something").execute_if(dialect=("postgresql", "mysql"))
|
| :param callable\_: A callable, which will be invoked with
| three positional arguments as well as optional keyword
| arguments:
|
| :ddl:
| This DDL element.
|
| :target:
| The :class:`_schema.Table` or :class:`_schema.MetaData`
| object which is the
| target of this event. May be None if the DDL is executed
| explicitly.
|
| :bind:
| The :class:`_engine.Connection` being used for DDL execution.
| May be None if this construct is being created inline within
| a table, in which case ``compiler`` will be present.
|
| :tables:
| Optional keyword argument - a list of Table objects which are to
| be created/ dropped within a MetaData.create_all() or drop_all()
| method call.
|
| :dialect: keyword argument, but always present - the
| :class:`.Dialect` involved in the operation.
|
| :compiler: keyword argument. Will be ``None`` for an engine
| level DDL invocation, but will refer to a :class:`.DDLCompiler`
| if this DDL element is being created inline within a table.
|
| :state:
| Optional keyword argument - will be the ``state`` argument
| passed to this function.
|
| :checkfirst:
| Keyword argument, will be True if the 'checkfirst' flag was
| set during the call to ``create()``, ``create_all()``,
| ``drop()``, ``drop_all()``.
|
| If the callable returns a True value, the DDL statement will be
| executed.
|
| :param state: any value which will be passed to the callable\_
| as the ``state`` keyword argument.
|
| .. seealso::
|
| :meth:`.SchemaItem.ddl_if`
|
| :class:`.DDLEvents`
|
| :ref:`event_toplevel`
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'_ddl_if': 'Optional[DDLIf]', 'target': 'Union[Sche...
|
| target = None
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.base.Executable:
|
| execution_options(self, **kw: 'Any') -> 'Self'
| Set non-SQL options for the statement which take effect during
| execution.
|
| Execution options can be set at many scopes, including per-statement,
| per-connection, or per execution, using methods such as
| :meth:`_engine.Connection.execution_options` and parameters which
| accept a dictionary of options such as
| :paramref:`_engine.Connection.execute.execution_options` and
| :paramref:`_orm.Session.execute.execution_options`.
|
| The primary characteristic of an execution option, as opposed to
| other kinds of options such as ORM loader options, is that
| **execution options never affect the compiled SQL of a query, only
| things that affect how the SQL statement itself is invoked or how
| results are fetched**. That is, execution options are not part of
| what's accommodated by SQL compilation nor are they considered part of
| the cached state of a statement.
|
| The :meth:`_sql.Executable.execution_options` method is
| :term:`generative`, as
| is the case for the method as applied to the :class:`_engine.Engine`
| and :class:`_orm.Query` objects, which means when the method is called,
| a copy of the object is returned, which applies the given parameters to
| that new copy, but leaves the original unchanged::
|
| statement = select(table.c.x, table.c.y)
| new_statement = statement.execution_options(my_option=True)
|
| An exception to this behavior is the :class:`_engine.Connection`
| object, where the :meth:`_engine.Connection.execution_options` method
| is explicitly **not** generative.
|
| The kinds of options that may be passed to
| :meth:`_sql.Executable.execution_options` and other related methods and
| parameter dictionaries include parameters that are explicitly consumed
| by SQLAlchemy Core or ORM, as well as arbitrary keyword arguments not
| defined by SQLAlchemy, which means the methods and/or parameter
| dictionaries may be used for user-defined parameters that interact with
| custom code, which may access the parameters using methods such as
| :meth:`_sql.Executable.get_execution_options` and
| :meth:`_engine.Connection.get_execution_options`, or within selected
| event hooks using a dedicated ``execution_options`` event parameter
| such as
| :paramref:`_events.ConnectionEvents.before_execute.execution_options`
| or :attr:`_orm.ORMExecuteState.execution_options`, e.g.::
|
| from sqlalchemy import event
|
|
| @event.listens_for(some_engine, "before_execute")
| def _process_opt(conn, statement, multiparams, params, execution_options):
| "run a SQL function before invoking a statement"
|
| if execution_options.get("do_special_thing", False):
| conn.exec_driver_sql("run_special_function()")
|
| Within the scope of options that are explicitly recognized by
| SQLAlchemy, most apply to specific classes of objects and not others.
| The most common execution options include:
|
| * :paramref:`_engine.Connection.execution_options.isolation_level` -
| sets the isolation level for a connection or a class of connections
| via an :class:`_engine.Engine`. This option is accepted only
| by :class:`_engine.Connection` or :class:`_engine.Engine`.
|
| * :paramref:`_engine.Connection.execution_options.stream_results` -
| indicates results should be fetched using a server side cursor;
| this option is accepted by :class:`_engine.Connection`, by the
| :paramref:`_engine.Connection.execute.execution_options` parameter
| on :meth:`_engine.Connection.execute`, and additionally by
| :meth:`_sql.Executable.execution_options` on a SQL statement object,
| as well as by ORM constructs like :meth:`_orm.Session.execute`.
|
| * :paramref:`_engine.Connection.execution_options.compiled_cache` -
| indicates a dictionary that will serve as the
| :ref:`SQL compilation cache <sql_caching>`
| for a :class:`_engine.Connection` or :class:`_engine.Engine`, as
| well as for ORM methods like :meth:`_orm.Session.execute`.
| Can be passed as ``None`` to disable caching for statements.
| This option is not accepted by
| :meth:`_sql.Executable.execution_options` as it is inadvisable to
| carry along a compilation cache within a statement object.
|
| * :paramref:`_engine.Connection.execution_options.schema_translate_map`
| - a mapping of schema names used by the
| :ref:`Schema Translate Map <schema_translating>` feature, accepted
| by :class:`_engine.Connection`, :class:`_engine.Engine`,
| :class:`_sql.Executable`, as well as by ORM constructs
| like :meth:`_orm.Session.execute`.
|
| .. seealso::
|
| :meth:`_engine.Connection.execution_options`
|
| :paramref:`_engine.Connection.execute.execution_options`
|
| :paramref:`_orm.Session.execute.execution_options`
|
| :ref:`orm_queryguide_execution_options` - documentation on all
| ORM-specific execution options
|
| get_execution_options(self) -> '_ExecuteOptions'
| Get the non-SQL options which will take effect during execution.
|
| .. versionadded:: 1.3
|
| .. seealso::
|
| :meth:`.Executable.execution_options`
|
| options(self, *options: 'ExecutableOption') -> 'Self'
| Apply options to this statement.
|
| In the general sense, options are any kind of Python object
| that can be interpreted by the SQL compiler for the statement.
| These options can be consumed by specific dialects or specific kinds
| of compilers.
|
| The most commonly known kind of option are the ORM level options
| that apply "eager load" and other loading behaviors to an ORM
| query. However, options can theoretically be used for many other
| purposes.
|
| For background on specific kinds of options for specific kinds of
| statements, refer to the documentation for those option objects.
|
| .. versionchanged:: 1.4 - added :meth:`.Executable.options` to
| Core statement objects towards the goal of allowing unified
| Core / ORM querying capabilities.
|
| .. seealso::
|
| :ref:`loading_columns` - refers to options specific to the usage
| of ORM queries
|
| :ref:`relationship_loader_options` - refers to options specific
| to the usage of ORM queries
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.base.Executable:
|
| is_delete = False
|
| is_dml = False
|
| is_from_statement = False
|
| is_insert = False
|
| is_select = False
|
| is_text = False
|
| is_update = False
|
| supports_execution = True
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.SQLRole:
|
| allows_lambda = False
|
| uses_inspection = False
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.elements.ClauseElement:
|
| __bool__(self)
|
| __getstate__(self)
| Helper for pickle.
|
| __invert__(self)
|
| __repr__(self)
| Return repr(self).
|
| compare(self, other: 'ClauseElement', **kw: 'Any') -> 'bool'
| Compare this :class:`_expression.ClauseElement` to
| the given :class:`_expression.ClauseElement`.
|
| Subclasses should override the default behavior, which is a
| straight identity comparison.
|
| \**kw are arguments consumed by subclass ``compare()`` methods and
| may be used to modify the criteria for comparison
| (see :class:`_expression.ColumnElement`).
|
| description(...)
|
| entity_namespace(...)
|
| params(self, _ClauseElement__optionaldict: 'Optional[Mapping[str, Any]]' = None, **kwargs: 'Any') -> 'Self'
| Return a copy with :func:`_expression.bindparam` elements
| replaced.
|
| Returns a copy of this ClauseElement with
| :func:`_expression.bindparam`
| elements replaced with values taken from the given dictionary::
|
| >>> clause = column("x") + bindparam("foo")
| >>> print(clause.compile().params)
| {'foo':None}
| >>> print(clause.params({"foo": 7}).compile().params)
| {'foo':7}
|
| self_group(self, against: 'Optional[OperatorType]' = None) -> 'ClauseElement'
| 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.
|
| unique_params(self, _ClauseElement__optionaldict: 'Optional[Dict[str, Any]]' = None, **kwargs: 'Any') -> 'Self'
| Return a copy with :func:`_expression.bindparam` elements
| replaced.
|
| Same functionality as :meth:`_expression.ClauseElement.params`,
| except adds `unique=True`
| to affected bind parameters so that multiple statements can be
| used.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.elements.ClauseElement:
|
| __visit_name__ = 'clause'
|
| is_clause_element = True
|
| is_selectable = False
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.cache_key.HasCacheKey:
|
| inherit_cache = None
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_instancemethod(fn: '_F') -> '_F'
| Decorate a method memoize its return value.
|
| :meta private:
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_attribute = <class 'sqlalchemy.util.langhelpers.HasMemoized.m...
| A read-only @property that is only evaluated once.
|
| :meta private:
|
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.visitors.HasTraverseInternals:
|
| get_children(self, *, omit_attrs: 'Tuple[str, ...]' = (), **kw: 'Any') -> 'Iterable[HasTraverseInternals]'
| Return immediate child :class:`.visitors.HasTraverseInternals`
| elements of this :class:`.visitors.HasTraverseInternals`.
|
| This is used for visit traversal.
|
| \**kw may contain flags that change the collection that is
| returned, for example to return a subset of items in order to
| cut down on larger traversals, or to return child items from a
| different context (such as schema-level collections instead of
| clause-level).
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.elements.CompilerElement:
|
| __str__(self) -> 'str'
| Return str(self).
|
| compile(self, bind: 'Optional[_HasDialect]' = None, dialect: 'Optional[Dialect]' = None, **kw: 'Any') -> 'Compiled'
| Compile this SQL expression.
|
| The return value is a :class:`~.Compiled` object.
| Calling ``str()`` or ``unicode()`` on the returned value will yield a
| string representation of the result. The
| :class:`~.Compiled` object also can return a
| dictionary of bind parameter names and values
| using the ``params`` accessor.
|
| :param bind: An :class:`.Connection` or :class:`.Engine` which
| can provide a :class:`.Dialect` in order to generate a
| :class:`.Compiled` object. If the ``bind`` and
| ``dialect`` parameters are both omitted, a default SQL compiler
| is used.
|
| :param column_keys: Used for INSERT and UPDATE statements, a list of
| column names which should be present in the VALUES clause of the
| compiled statement. If ``None``, all columns from the target table
| object are rendered.
|
| :param dialect: A :class:`.Dialect` instance which can generate
| a :class:`.Compiled` object. This argument takes precedence over
| the ``bind`` argument.
|
| :param compile_kwargs: optional dictionary of additional parameters
| that will be passed through to the compiler within all "visit"
| methods. This allows any custom flag to be passed through to
| a custom compilation construct, for example. It is also used
| for the case of passing the ``literal_binds`` flag through::
|
| from sqlalchemy.sql import table, column, select
|
| t = table("t", column("x"))
|
| s = select(t).where(t.c.x == 5)
|
| print(s.compile(compile_kwargs={"literal_binds": True}))
|
| .. seealso::
|
| :ref:`faq_sql_expression_string`
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.elements.CompilerElement:
|
| stringify_dialect = 'default'
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.visitors.Visitable:
|
| __class_getitem__(key: 'Any') -> 'Any'
|
| __init_subclass__() -> 'None'
| This method is called when a class is subclassed.
|
| The default implementation does nothing. It may be
| overridden to extend subclasses.
sqlalchemy.ExecutionContext
Python Library Documentation: class ExecutionContext in module sqlalchemy.engine.interfaces
class ExecutionContext(builtins.object)
| A messenger object for a Dialect that corresponds to a single
| execution.
|
| Methods defined here:
|
| create_cursor(self) -> 'DBAPICursor'
| Return a new cursor generated from this ExecutionContext's
| connection.
|
| Some dialects may wish to change the behavior of
| connection.cursor(), such as postgresql which may return a PG
| "server side" cursor.
|
| fetchall_for_returning(self, cursor: 'DBAPICursor') -> 'Sequence[Any]'
| For a RETURNING result, deliver cursor.fetchall() from the
| DBAPI cursor.
|
| This is a dialect-specific hook for dialects that have special
| considerations when calling upon the rows delivered for a
| "RETURNING" statement. Default implementation is
| ``cursor.fetchall()``.
|
| This hook is currently used only by the :term:`insertmanyvalues`
| feature. Dialects that don't set ``use_insertmanyvalues=True``
| don't need to consider this hook.
|
| .. versionadded:: 2.0.10
|
| fire_sequence(self, seq: 'Sequence_SchemaItem', type_: 'Integer') -> 'int'
| given a :class:`.Sequence`, invoke it and return the next int
| value
|
| get_out_parameter_values(self, out_param_names: 'Sequence[str]') -> 'Sequence[Any]'
| Return a sequence of OUT parameter values from a cursor.
|
| For dialects that support OUT parameters, this method will be called
| when there is a :class:`.SQLCompiler` object which has the
| :attr:`.SQLCompiler.has_out_parameters` flag set. This flag in turn
| will be set to True if the statement itself has :class:`.BindParameter`
| objects that have the ``.isoutparam`` flag set which are consumed by
| the :meth:`.SQLCompiler.visit_bindparam` method. If the dialect
| compiler produces :class:`.BindParameter` objects with ``.isoutparam``
| set which are not handled by :meth:`.SQLCompiler.visit_bindparam`, it
| should set this flag explicitly.
|
| The list of names that were rendered for each bound parameter
| is passed to the method. The method should then return a sequence of
| values corresponding to the list of parameter objects. Unlike in
| previous SQLAlchemy versions, the values can be the **raw values** from
| the DBAPI; the execution context will apply the appropriate type
| handler based on what's present in self.compiled.binds and update the
| values. The processed dictionary will then be made available via the
| ``.out_parameters`` collection on the result object. Note that
| SQLAlchemy 1.4 has multiple kinds of result object as part of the 2.0
| transition.
|
| .. versionadded:: 1.4 - added
| :meth:`.ExecutionContext.get_out_parameter_values`, which is invoked
| automatically by the :class:`.DefaultExecutionContext` when there
| are :class:`.BindParameter` objects with the ``.isoutparam`` flag
| set. This replaces the practice of setting out parameters within
| the now-removed ``get_result_proxy()`` method.
|
| get_rowcount(self) -> 'Optional[int]'
| Return the DBAPI ``cursor.rowcount`` value, or in some
| cases an interpreted value.
|
| See :attr:`_engine.CursorResult.rowcount` for details on this.
|
| handle_dbapi_exception(self, e: 'BaseException') -> 'None'
| Receive a DBAPI exception which occurred upon execute, result
| fetch, etc.
|
| lastrow_has_defaults(self) -> 'bool'
| Return True if the last INSERT or UPDATE row contained
| inlined or database-side defaults.
|
| post_exec(self) -> 'None'
| Called after the execution of a compiled statement.
|
| If a compiled statement was passed to this ExecutionContext,
| the `last_insert_ids`, `last_inserted_params`, etc.
| datamembers should be available after this method completes.
|
| pre_exec(self) -> 'None'
| Called before an execution of a compiled statement.
|
| If a compiled statement was passed to this ExecutionContext,
| the `statement` and `parameters` datamembers must be
| initialized after this statement is complete.
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'compiled': 'Optional[Compiled]', 'connection': 'Co...
sqlalchemy.Exists
Python Library Documentation: class Exists in module sqlalchemy.sql.selectable
class Exists(sqlalchemy.sql.elements.UnaryExpression)
| Exists(_Exists__argument: 'Optional[Union[_ColumnsClauseArgument[Any], SelectBase, ScalarSelect[Any]]]' = None)
|
| Represent an ``EXISTS`` clause.
|
| See :func:`_sql.exists` for a description of usage.
|
| An ``EXISTS`` clause can also be constructed from a :func:`_sql.select`
| instance by calling :meth:`_sql.SelectBase.exists`.
|
| Method resolution order:
| Exists
| sqlalchemy.sql.elements.UnaryExpression
| sqlalchemy.sql.elements.ColumnElement
| sqlalchemy.sql.roles.ColumnArgumentOrKeyRole
| sqlalchemy.sql.roles.ColumnArgumentRole
| sqlalchemy.sql.roles.StatementOptionRole
| sqlalchemy.sql.roles.WhereHavingRole
| sqlalchemy.sql.roles.OnClauseRole
| sqlalchemy.sql.roles.BinaryElementRole
| sqlalchemy.sql.roles.OrderByRole
| sqlalchemy.sql.roles.ColumnsClauseRole
| sqlalchemy.sql.roles.AllowsLambdaRole
| sqlalchemy.sql.roles.ByOfRole
| sqlalchemy.sql.roles.UsesInspection
| sqlalchemy.sql.roles.ColumnListRole
| sqlalchemy.sql.roles.LimitOffsetRole
| sqlalchemy.sql.roles.DMLColumnRole
| sqlalchemy.sql.roles.DDLConstraintColumnRole
| sqlalchemy.sql.roles.DDLExpressionRole
| sqlalchemy.sql.roles.StructuralRole
| sqlalchemy.sql.elements.SQLColumnExpression
| sqlalchemy.sql.elements.SQLCoreOperations
| sqlalchemy.sql.roles.ExpressionElementRole
| sqlalchemy.sql.roles.TypedColumnsClauseRole
| typing.Generic
| sqlalchemy.sql.operators.ColumnOperators
| sqlalchemy.sql.operators.Operators
| sqlalchemy.util.langhelpers.TypingOnly
| sqlalchemy.sql.roles.SQLRole
| sqlalchemy.sql.elements.DQLDMLClauseElement
| sqlalchemy.sql.elements.ClauseElement
| sqlalchemy.sql.annotation.SupportsWrappingAnnotations
| sqlalchemy.sql.annotation.SupportsAnnotations
| sqlalchemy.sql.cache_key.MemoizedHasCacheKey
| sqlalchemy.sql.cache_key.HasCacheKey
| sqlalchemy.util.langhelpers.HasMemoized
| sqlalchemy.sql.traversals.HasCopyInternals
| sqlalchemy.sql.visitors.ExternallyTraversible
| sqlalchemy.sql.visitors.HasTraverseInternals
| sqlalchemy.sql.elements.CompilerElement
| sqlalchemy.sql.visitors.Visitable
| builtins.object
|
| Methods defined here:
|
| __init__(self, _Exists__argument: 'Optional[Union[_ColumnsClauseArgument[Any], SelectBase, ScalarSelect[Any]]]' = None)
| Initialize self. See help(type(self)) for accurate signature.
|
| correlate(self, *fromclauses: 'Union[Literal[None, False], _FromClauseArgument]') -> 'Self'
| Apply correlation to the subquery noted by this
| :class:`_sql.Exists`.
|
| .. seealso::
|
| :meth:`_sql.ScalarSelect.correlate`
|
| correlate_except(self, *fromclauses: 'Union[Literal[None, False], _FromClauseArgument]') -> 'Self'
| Apply correlation to the subquery noted by this
| :class:`_sql.Exists`.
|
| .. seealso::
|
| :meth:`_sql.ScalarSelect.correlate_except`
|
| select(self) -> 'Select[Tuple[bool]]'
| Return a SELECT of this :class:`_expression.Exists`.
|
| e.g.::
|
| stmt = exists(some_table.c.id).where(some_table.c.id == 5).select()
|
| This will produce a statement resembling:
|
| .. sourcecode:: sql
|
| SELECT EXISTS (SELECT id FROM some_table WHERE some_table = :param) AS anon_1
|
| .. seealso::
|
| :func:`_expression.select` - general purpose
| method which allows for arbitrary column lists.
|
| select_from(self, *froms: '_FromClauseArgument') -> 'Self'
| Return a new :class:`_expression.Exists` construct,
| applying the given
| expression to the :meth:`_expression.Select.select_from`
| method of the select
| statement contained.
|
| .. note:: it is typically preferable to build a :class:`_sql.Select`
| statement first, including the desired WHERE clause, then use the
| :meth:`_sql.SelectBase.exists` method to produce an
| :class:`_sql.Exists` object at once.
|
| where(self, *clause: '_ColumnExpressionArgument[bool]') -> 'Self'
| Return a new :func:`_expression.exists` construct with the
| given expression added to
| its WHERE clause, joined to the existing clause via AND, if any.
|
|
| .. note:: it is typically preferable to build a :class:`_sql.Select`
| statement first, including the desired WHERE clause, then use the
| :meth:`_sql.SelectBase.exists` method to produce an
| :class:`_sql.Exists` object at once.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| __orig_bases__ = (sqlalchemy.sql.elements.UnaryExpression[bool],)
|
| __parameters__ = ()
|
| inherit_cache = True
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.elements.UnaryExpression:
|
| self_group(self, against: 'Optional[OperatorType]' = None) -> 'Union[Self, Grouping[_T]]'
| 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.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.elements.UnaryExpression:
|
| __visit_name__ = 'unary'
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.elements.ColumnElement:
|
| __getattr__(self, key: 'str') -> 'Any'
|
| __setstate__(self, state)
|
| base_columns(...)
|
| cast(self, type_: '_TypeEngineArgument[_OPT]') -> 'Cast[_OPT]'
| Produce a type cast, i.e. ``CAST(<expression> AS <type>)``.
|
| This is a shortcut to the :func:`_expression.cast` function.
|
| .. seealso::
|
| :ref:`tutorial_casts`
|
| :func:`_expression.cast`
|
| :func:`_expression.type_coerce`
|
| comparator(...)
|
| label(self, name: 'Optional[str]') -> 'Label[_T]'
| Produce a column label, i.e. ``<columnname> AS <name>``.
|
| This is a shortcut to the :func:`_expression.label` function.
|
| If 'name' is ``None``, an anonymous label name will be generated.
|
| operate(self, op: 'operators.OperatorType', *other: 'Any', **kwargs: 'Any') -> 'ColumnElement[Any]'
| Operate on an argument.
|
| This is the lowest level of operation, raises
| :class:`NotImplementedError` by default.
|
| Overriding this on a subclass can allow common
| behavior to be applied to all operations.
| For example, overriding :class:`.ColumnOperators`
| to apply ``func.lower()`` to the left and right
| side::
|
| class MyComparator(ColumnOperators):
| def operate(self, op, other, **kwargs):
| return op(func.lower(self), func.lower(other), **kwargs)
|
| :param op: Operator callable.
| :param \*other: the 'other' side of the operation. Will
| be a single scalar for most operations.
| :param \**kwargs: modifiers. These may be passed by special
| operators such as :meth:`ColumnOperators.contains`.
|
| proxy_set(...)
| set of all columns we are proxying
|
| as of 2.0 this is explicitly deannotated columns. previously it was
| effectively deannotated columns but wasn't enforced. annotated
| columns should basically not go into sets if at all possible because
| their hashing behavior is very non-performant.
|
| reverse_operate(self, op: 'operators.OperatorType', other: 'Any', **kwargs: 'Any') -> 'ColumnElement[Any]'
| Reverse operate on an argument.
|
| Usage is the same as :meth:`operate`.
|
| shares_lineage(self, othercolumn: 'ColumnElement[Any]') -> 'bool'
| Return True if the given :class:`_expression.ColumnElement`
| has a common ancestor to this :class:`_expression.ColumnElement`.
|
| type(...)
|
| ----------------------------------------------------------------------
| Readonly properties inherited from sqlalchemy.sql.elements.ColumnElement:
|
| anon_key_label
| .. deprecated:: 1.4 The :attr:`_expression.ColumnElement.anon_key_label` attribute is now private, and the public accessor is deprecated.
|
| anon_label
| .. deprecated:: 1.4 The :attr:`_expression.ColumnElement.anon_label` attribute is now private, and the public accessor is deprecated.
|
| expression
| Return a column expression.
|
| Part of the inspection interface; returns self.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from sqlalchemy.sql.elements.ColumnElement:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.elements.ColumnElement:
|
| foreign_keys = frozenset()
|
| key = None
|
| primary_key = False
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.AllowsLambdaRole:
|
| allows_lambda = True
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.UsesInspection:
|
| uses_inspection = True
|
| ----------------------------------------------------------------------
| Class methods inherited from typing.Generic:
|
| __class_getitem__(...)
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__(...)
| Function to initialize subclasses.
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.operators.ColumnOperators:
|
| __add__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``+`` operator.
|
| In a column context, produces the clause ``a + b``
| if the parent object has non-string affinity.
| If the parent object has a string affinity,
| produces the concatenation operator, ``a || b`` -
| see :meth:`.ColumnOperators.concat`.
|
| __contains__(self, other: 'Any') -> 'ColumnOperators'
|
| __eq__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``==`` operator.
|
| In a column context, produces the clause ``a = b``.
| If the target is ``None``, produces ``a IS NULL``.
|
| __floordiv__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``//`` operator.
|
| In a column context, produces the clause ``a / b``,
| which is the same as "truediv", but considers the result
| type to be integer.
|
| .. versionadded:: 2.0
|
| __ge__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``>=`` operator.
|
| In a column context, produces the clause ``a >= b``.
|
| __getitem__(self, index: 'Any') -> 'ColumnOperators'
| Implement the [] operator.
|
| This can be used by some database-specific types
| such as PostgreSQL ARRAY and HSTORE.
|
| __gt__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``>`` operator.
|
| In a column context, produces the clause ``a > b``.
|
| __hash__(self, /) from builtins.object
| Return hash(self).
|
| __le__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``<=`` operator.
|
| In a column context, produces the clause ``a <= b``.
|
| __lshift__(self, other: 'Any') -> 'ColumnOperators'
| implement the << operator.
|
| Not used by SQLAlchemy core, this is provided
| for custom operator systems which want to use
| << as an extension point.
|
| __lt__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``<`` operator.
|
| In a column context, produces the clause ``a < b``.
|
| __mod__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``%`` operator.
|
| In a column context, produces the clause ``a % b``.
|
| __mul__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``*`` operator.
|
| In a column context, produces the clause ``a * b``.
|
| __ne__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``!=`` operator.
|
| In a column context, produces the clause ``a != b``.
| If the target is ``None``, produces ``a IS NOT NULL``.
|
| __neg__(self) -> 'ColumnOperators'
| Implement the ``-`` operator.
|
| In a column context, produces the clause ``-a``.
|
| __radd__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``+`` operator in reverse.
|
| See :meth:`.ColumnOperators.__add__`.
|
| __rfloordiv__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``//`` operator in reverse.
|
| See :meth:`.ColumnOperators.__floordiv__`.
|
| __rmod__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``%`` operator in reverse.
|
| See :meth:`.ColumnOperators.__mod__`.
|
| __rmul__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``*`` operator in reverse.
|
| See :meth:`.ColumnOperators.__mul__`.
|
| __rshift__(self, other: 'Any') -> 'ColumnOperators'
| implement the >> operator.
|
| Not used by SQLAlchemy core, this is provided
| for custom operator systems which want to use
| >> as an extension point.
|
| __rsub__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``-`` operator in reverse.
|
| See :meth:`.ColumnOperators.__sub__`.
|
| __rtruediv__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``/`` operator in reverse.
|
| See :meth:`.ColumnOperators.__truediv__`.
|
| __sub__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``-`` operator.
|
| In a column context, produces the clause ``a - b``.
|
| __truediv__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``/`` operator.
|
| In a column context, produces the clause ``a / b``, and
| considers the result type to be numeric.
|
| .. versionchanged:: 2.0 The truediv operator against two integers
| is now considered to return a numeric value. Behavior on specific
| backends may vary.
|
| all_(self) -> 'ColumnOperators'
| Produce an :func:`_expression.all_` clause against the
| parent object.
|
| See the documentation for :func:`_sql.all_` for examples.
|
| .. note:: be sure to not confuse the newer
| :meth:`_sql.ColumnOperators.all_` method with the **legacy**
| version of this method, the :meth:`_types.ARRAY.Comparator.all`
| method that's specific to :class:`_types.ARRAY`, which uses a
| different calling style.
|
| any_(self) -> 'ColumnOperators'
| Produce an :func:`_expression.any_` clause against the
| parent object.
|
| See the documentation for :func:`_sql.any_` for examples.
|
| .. note:: be sure to not confuse the newer
| :meth:`_sql.ColumnOperators.any_` method with the **legacy**
| version of this method, the :meth:`_types.ARRAY.Comparator.any`
| method that's specific to :class:`_types.ARRAY`, which uses a
| different calling style.
|
| asc(self) -> 'ColumnOperators'
| Produce a :func:`_expression.asc` clause against the
| parent object.
|
| between(self, cleft: 'Any', cright: 'Any', symmetric: 'bool' = False) -> 'ColumnOperators'
| Produce a :func:`_expression.between` clause against
| the parent object, given the lower and upper range.
|
| bitwise_and(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise AND operation, typically via the ``&``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_lshift(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise LSHIFT operation, typically via the ``<<``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_not(self) -> 'ColumnOperators'
| Produce a bitwise NOT operation, typically via the ``~``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_or(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise OR operation, typically via the ``|``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_rshift(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise RSHIFT operation, typically via the ``>>``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_xor(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise XOR operation, typically via the ``^``
| operator, or ``#`` for PostgreSQL.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| collate(self, collation: 'str') -> 'ColumnOperators'
| Produce a :func:`_expression.collate` clause against
| the parent object, given the collation string.
|
| .. seealso::
|
| :func:`_expression.collate`
|
| concat(self, other: 'Any') -> 'ColumnOperators'
| Implement the 'concat' operator.
|
| In a column context, produces the clause ``a || b``,
| or uses the ``concat()`` operator on MySQL.
|
| contains(self, other: 'Any', **kw: 'Any') -> 'ColumnOperators'
| Implement the 'contains' operator.
|
| Produces a LIKE expression that tests against a match for the middle
| of a string value:
|
| .. sourcecode:: sql
|
| column LIKE '%' || <other> || '%'
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.contains("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.contains.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.contains.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.contains.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.contains("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE '%' || :param || '%' ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.contains("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE '%' || :param || '%' ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.contains.autoescape`::
|
| somecolumn.contains("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.startswith`
|
| :meth:`.ColumnOperators.endswith`
|
| :meth:`.ColumnOperators.like`
|
| desc(self) -> 'ColumnOperators'
| Produce a :func:`_expression.desc` clause against the
| parent object.
|
| distinct(self) -> 'ColumnOperators'
| Produce a :func:`_expression.distinct` clause against the
| parent object.
|
| endswith(self, other: 'Any', escape: 'Optional[str]' = None, autoescape: 'bool' = False) -> 'ColumnOperators'
| Implement the 'endswith' operator.
|
| Produces a LIKE expression that tests against a match for the end
| of a string value:
|
| .. sourcecode:: sql
|
| column LIKE '%' || <other>
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.endswith("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.endswith.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.endswith.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.endswith.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.endswith("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE '%' || :param ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.endswith("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE '%' || :param ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.endswith.autoescape`::
|
| somecolumn.endswith("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.startswith`
|
| :meth:`.ColumnOperators.contains`
|
| :meth:`.ColumnOperators.like`
|
| icontains(self, other: 'Any', **kw: 'Any') -> 'ColumnOperators'
| Implement the ``icontains`` operator, e.g. case insensitive
| version of :meth:`.ColumnOperators.contains`.
|
| Produces a LIKE expression that tests against an insensitive match
| for the middle of a string value:
|
| .. sourcecode:: sql
|
| lower(column) LIKE '%' || lower(<other>) || '%'
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.icontains("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.icontains.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.icontains.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.icontains.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.icontains("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE '%' || lower(:param) || '%' ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.icontains("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE '%' || lower(:param) || '%' ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.contains.autoescape`::
|
| somecolumn.icontains("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.contains`
|
| iendswith(self, other: 'Any', escape: 'Optional[str]' = None, autoescape: 'bool' = False) -> 'ColumnOperators'
| Implement the ``iendswith`` operator, e.g. case insensitive
| version of :meth:`.ColumnOperators.endswith`.
|
| Produces a LIKE expression that tests against an insensitive match
| for the end of a string value:
|
| .. sourcecode:: sql
|
| lower(column) LIKE '%' || lower(<other>)
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.iendswith("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.iendswith.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.iendswith.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.iendswith.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.iendswith("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE '%' || lower(:param) ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.iendswith("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE '%' || lower(:param) ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.iendswith.autoescape`::
|
| somecolumn.endswith("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.endswith`
|
| ilike(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
| Implement the ``ilike`` operator, e.g. case insensitive LIKE.
|
| In a column context, produces an expression either of the form:
|
| .. sourcecode:: sql
|
| lower(a) LIKE lower(other)
|
| Or on backends that support the ILIKE operator:
|
| .. sourcecode:: sql
|
| a ILIKE other
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.ilike("%foobar%"))
|
| :param other: expression to be compared
| :param escape: optional escape character, renders the ``ESCAPE``
| keyword, e.g.::
|
| somecolumn.ilike("foo/%bar", escape="/")
|
| .. seealso::
|
| :meth:`.ColumnOperators.like`
|
| in_(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``in`` operator.
|
| In a column context, produces the clause ``column IN <other>``.
|
| The given parameter ``other`` may be:
|
| * A list of literal values,
| e.g.::
|
| stmt.where(column.in_([1, 2, 3]))
|
| In this calling form, the list of items is converted to a set of
| bound parameters the same length as the list given:
|
| .. sourcecode:: sql
|
| WHERE COL IN (?, ?, ?)
|
| * A list of tuples may be provided if the comparison is against a
| :func:`.tuple_` containing multiple expressions::
|
| from sqlalchemy import tuple_
|
| stmt.where(tuple_(col1, col2).in_([(1, 10), (2, 20), (3, 30)]))
|
| * An empty list,
| e.g.::
|
| stmt.where(column.in_([]))
|
| In this calling form, the expression renders an "empty set"
| expression. These expressions are tailored to individual backends
| and are generally trying to get an empty SELECT statement as a
| subquery. Such as on SQLite, the expression is:
|
| .. sourcecode:: sql
|
| WHERE col IN (SELECT 1 FROM (SELECT 1) WHERE 1!=1)
|
| .. versionchanged:: 1.4 empty IN expressions now use an
| execution-time generated SELECT subquery in all cases.
|
| * A bound parameter, e.g. :func:`.bindparam`, may be used if it
| includes the :paramref:`.bindparam.expanding` flag::
|
| stmt.where(column.in_(bindparam("value", expanding=True)))
|
| In this calling form, the expression renders a special non-SQL
| placeholder expression that looks like:
|
| .. sourcecode:: sql
|
| WHERE COL IN ([EXPANDING_value])
|
| This placeholder expression is intercepted at statement execution
| time to be converted into the variable number of bound parameter
| form illustrated earlier. If the statement were executed as::
|
| connection.execute(stmt, {"value": [1, 2, 3]})
|
| The database would be passed a bound parameter for each value:
|
| .. sourcecode:: sql
|
| WHERE COL IN (?, ?, ?)
|
| .. versionadded:: 1.2 added "expanding" bound parameters
|
| If an empty list is passed, a special "empty list" expression,
| which is specific to the database in use, is rendered. On
| SQLite this would be:
|
| .. sourcecode:: sql
|
| WHERE COL IN (SELECT 1 FROM (SELECT 1) WHERE 1!=1)
|
| .. versionadded:: 1.3 "expanding" bound parameters now support
| empty lists
|
| * a :func:`_expression.select` construct, which is usually a
| correlated scalar select::
|
| stmt.where(
| column.in_(select(othertable.c.y).where(table.c.x == othertable.c.x))
| )
|
| In this calling form, :meth:`.ColumnOperators.in_` renders as given:
|
| .. sourcecode:: sql
|
| WHERE COL IN (SELECT othertable.y
| FROM othertable WHERE othertable.x = table.x)
|
| :param other: a list of literals, a :func:`_expression.select`
| construct, or a :func:`.bindparam` construct that includes the
| :paramref:`.bindparam.expanding` flag set to True.
|
| is_(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``IS`` operator.
|
| Normally, ``IS`` is generated automatically when comparing to a
| value of ``None``, which resolves to ``NULL``. However, explicit
| usage of ``IS`` may be desirable if comparing to boolean values
| on certain platforms.
|
| .. seealso:: :meth:`.ColumnOperators.is_not`
|
| is_distinct_from(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``IS DISTINCT FROM`` operator.
|
| Renders "a IS DISTINCT FROM b" on most platforms;
| on some such as SQLite may render "a IS NOT b".
|
| is_not(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``IS NOT`` operator.
|
| Normally, ``IS NOT`` is generated automatically when comparing to a
| value of ``None``, which resolves to ``NULL``. However, explicit
| usage of ``IS NOT`` may be desirable if comparing to boolean values
| on certain platforms.
|
| .. versionchanged:: 1.4 The ``is_not()`` operator is renamed from
| ``isnot()`` in previous releases. The previous name remains
| available for backwards compatibility.
|
| .. seealso:: :meth:`.ColumnOperators.is_`
|
| is_not_distinct_from(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``IS NOT DISTINCT FROM`` operator.
|
| Renders "a IS NOT DISTINCT FROM b" on most platforms;
| on some such as SQLite may render "a IS b".
|
| .. versionchanged:: 1.4 The ``is_not_distinct_from()`` operator is
| renamed from ``isnot_distinct_from()`` in previous releases.
| The previous name remains available for backwards compatibility.
|
| isnot = is_not(self, other: 'Any') -> 'ColumnOperators'
|
| isnot_distinct_from = is_not_distinct_from(self, other: 'Any') -> 'ColumnOperators'
|
| istartswith(self, other: 'Any', escape: 'Optional[str]' = None, autoescape: 'bool' = False) -> 'ColumnOperators'
| Implement the ``istartswith`` operator, e.g. case insensitive
| version of :meth:`.ColumnOperators.startswith`.
|
| Produces a LIKE expression that tests against an insensitive
| match for the start of a string value:
|
| .. sourcecode:: sql
|
| lower(column) LIKE lower(<other>) || '%'
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.istartswith("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.istartswith.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.istartswith.escape` parameter will
| establish a given character as an escape character which can be of
| use when the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.istartswith.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.istartswith("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE lower(:param) || '%' ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.istartswith("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE lower(:param) || '%' ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.istartswith.autoescape`::
|
| somecolumn.istartswith("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.startswith`
|
| like(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
| Implement the ``like`` operator.
|
| In a column context, produces the expression:
|
| .. sourcecode:: sql
|
| a LIKE other
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.like("%foobar%"))
|
| :param other: expression to be compared
| :param escape: optional escape character, renders the ``ESCAPE``
| keyword, e.g.::
|
| somecolumn.like("foo/%bar", escape="/")
|
| .. seealso::
|
| :meth:`.ColumnOperators.ilike`
|
| match(self, other: 'Any', **kwargs: 'Any') -> 'ColumnOperators'
| Implements a database-specific 'match' operator.
|
| :meth:`_sql.ColumnOperators.match` attempts to resolve to
| a MATCH-like function or operator provided by the backend.
| Examples include:
|
| * PostgreSQL - renders ``x @@ plainto_tsquery(y)``
|
| .. versionchanged:: 2.0 ``plainto_tsquery()`` is used instead
| of ``to_tsquery()`` for PostgreSQL now; for compatibility with
| other forms, see :ref:`postgresql_match`.
|
|
| * MySQL - renders ``MATCH (x) AGAINST (y IN BOOLEAN MODE)``
|
| .. seealso::
|
| :class:`_mysql.match` - MySQL specific construct with
| additional features.
|
| * Oracle Database - renders ``CONTAINS(x, y)``
| * other backends may provide special implementations.
| * Backends without any special implementation will emit
| the operator as "MATCH". This is compatible with SQLite, for
| example.
|
| not_ilike(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
| implement the ``NOT ILIKE`` operator.
|
| This is equivalent to using negation with
| :meth:`.ColumnOperators.ilike`, i.e. ``~x.ilike(y)``.
|
| .. versionchanged:: 1.4 The ``not_ilike()`` operator is renamed from
| ``notilike()`` in previous releases. The previous name remains
| available for backwards compatibility.
|
| .. seealso::
|
| :meth:`.ColumnOperators.ilike`
|
| not_in(self, other: 'Any') -> 'ColumnOperators'
| implement the ``NOT IN`` operator.
|
| This is equivalent to using negation with
| :meth:`.ColumnOperators.in_`, i.e. ``~x.in_(y)``.
|
| In the case that ``other`` is an empty sequence, the compiler
| produces an "empty not in" expression. This defaults to the
| expression "1 = 1" to produce true in all cases. The
| :paramref:`_sa.create_engine.empty_in_strategy` may be used to
| alter this behavior.
|
| .. versionchanged:: 1.4 The ``not_in()`` operator is renamed from
| ``notin_()`` in previous releases. The previous name remains
| available for backwards compatibility.
|
| .. versionchanged:: 1.2 The :meth:`.ColumnOperators.in_` and
| :meth:`.ColumnOperators.not_in` operators
| now produce a "static" expression for an empty IN sequence
| by default.
|
| .. seealso::
|
| :meth:`.ColumnOperators.in_`
|
| not_like(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
| implement the ``NOT LIKE`` operator.
|
| This is equivalent to using negation with
| :meth:`.ColumnOperators.like`, i.e. ``~x.like(y)``.
|
| .. versionchanged:: 1.4 The ``not_like()`` operator is renamed from
| ``notlike()`` in previous releases. The previous name remains
| available for backwards compatibility.
|
| .. seealso::
|
| :meth:`.ColumnOperators.like`
|
| notilike = not_ilike(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
|
| notin_ = not_in(self, other: 'Any') -> 'ColumnOperators'
|
| notlike = not_like(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
|
| nulls_first(self) -> 'ColumnOperators'
| Produce a :func:`_expression.nulls_first` clause against the
| parent object.
|
| .. versionchanged:: 1.4 The ``nulls_first()`` operator is
| renamed from ``nullsfirst()`` in previous releases.
| The previous name remains available for backwards compatibility.
|
| nulls_last(self) -> 'ColumnOperators'
| Produce a :func:`_expression.nulls_last` clause against the
| parent object.
|
| .. versionchanged:: 1.4 The ``nulls_last()`` operator is
| renamed from ``nullslast()`` in previous releases.
| The previous name remains available for backwards compatibility.
|
| nullsfirst = nulls_first(self) -> 'ColumnOperators'
|
| nullslast = nulls_last(self) -> 'ColumnOperators'
|
| regexp_match(self, pattern: 'Any', flags: 'Optional[str]' = None) -> 'ColumnOperators'
| Implements a database-specific 'regexp match' operator.
|
| E.g.::
|
| stmt = select(table.c.some_column).where(
| table.c.some_column.regexp_match("^(b|c)")
| )
|
| :meth:`_sql.ColumnOperators.regexp_match` attempts to resolve to
| a REGEXP-like function or operator provided by the backend, however
| the specific regular expression syntax and flags available are
| **not backend agnostic**.
|
| Examples include:
|
| * PostgreSQL - renders ``x ~ y`` or ``x !~ y`` when negated.
| * Oracle Database - renders ``REGEXP_LIKE(x, y)``
| * SQLite - uses SQLite's ``REGEXP`` placeholder operator and calls into
| the Python ``re.match()`` builtin.
| * other backends may provide special implementations.
| * Backends without any special implementation will emit
| the operator as "REGEXP" or "NOT REGEXP". This is compatible with
| SQLite and MySQL, for example.
|
| Regular expression support is currently implemented for Oracle
| Database, PostgreSQL, MySQL and MariaDB. Partial support is available
| for SQLite. Support among third-party dialects may vary.
|
| :param pattern: The regular expression pattern string or column
| clause.
| :param flags: Any regular expression string flags to apply, passed as
| plain Python string only. These flags are backend specific.
| Some backends, like PostgreSQL and MariaDB, may alternatively
| specify the flags as part of the pattern.
| When using the ignore case flag 'i' in PostgreSQL, the ignore case
| regexp match operator ``~*`` or ``!~*`` will be used.
|
| .. versionadded:: 1.4
|
| .. versionchanged:: 1.4.48, 2.0.18 Note that due to an implementation
| error, the "flags" parameter previously accepted SQL expression
| objects such as column expressions in addition to plain Python
| strings. This implementation did not work correctly with caching
| and was removed; strings only should be passed for the "flags"
| parameter, as these flags are rendered as literal inline values
| within SQL expressions.
|
| .. seealso::
|
| :meth:`_sql.ColumnOperators.regexp_replace`
|
| regexp_replace(self, pattern: 'Any', replacement: 'Any', flags: 'Optional[str]' = None) -> 'ColumnOperators'
| Implements a database-specific 'regexp replace' operator.
|
| E.g.::
|
| stmt = select(
| table.c.some_column.regexp_replace("b(..)", "XY", flags="g")
| )
|
| :meth:`_sql.ColumnOperators.regexp_replace` attempts to resolve to
| a REGEXP_REPLACE-like function provided by the backend, that
| usually emit the function ``REGEXP_REPLACE()``. However,
| the specific regular expression syntax and flags available are
| **not backend agnostic**.
|
| Regular expression replacement support is currently implemented for
| Oracle Database, PostgreSQL, MySQL 8 or greater and MariaDB. Support
| among third-party dialects may vary.
|
| :param pattern: The regular expression pattern string or column
| clause.
| :param pattern: The replacement string or column clause.
| :param flags: Any regular expression string flags to apply, passed as
| plain Python string only. These flags are backend specific.
| Some backends, like PostgreSQL and MariaDB, may alternatively
| specify the flags as part of the pattern.
|
| .. versionadded:: 1.4
|
| .. versionchanged:: 1.4.48, 2.0.18 Note that due to an implementation
| error, the "flags" parameter previously accepted SQL expression
| objects such as column expressions in addition to plain Python
| strings. This implementation did not work correctly with caching
| and was removed; strings only should be passed for the "flags"
| parameter, as these flags are rendered as literal inline values
| within SQL expressions.
|
|
| .. seealso::
|
| :meth:`_sql.ColumnOperators.regexp_match`
|
| startswith(self, other: 'Any', escape: 'Optional[str]' = None, autoescape: 'bool' = False) -> 'ColumnOperators'
| Implement the ``startswith`` operator.
|
| Produces a LIKE expression that tests against a match for the start
| of a string value:
|
| .. sourcecode:: sql
|
| column LIKE <other> || '%'
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.startswith("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.startswith.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.startswith.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.startswith.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.startswith("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE :param || '%' ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.startswith("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE :param || '%' ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.startswith.autoescape`::
|
| somecolumn.startswith("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.endswith`
|
| :meth:`.ColumnOperators.contains`
|
| :meth:`.ColumnOperators.like`
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.operators.ColumnOperators:
|
| timetuple = None
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.operators.Operators:
|
| __and__(self, other: 'Any') -> 'Operators'
| Implement the ``&`` operator.
|
| When used with SQL expressions, results in an
| AND operation, equivalent to
| :func:`_expression.and_`, that is::
|
| a & b
|
| is equivalent to::
|
| from sqlalchemy import and_
|
| and_(a, b)
|
| Care should be taken when using ``&`` regarding
| operator precedence; the ``&`` operator has the highest precedence.
| The operands should be enclosed in parenthesis if they contain
| further sub expressions::
|
| (a == 2) & (b == 4)
|
| __invert__(self) -> 'Operators'
| Implement the ``~`` operator.
|
| When used with SQL expressions, results in a
| NOT operation, equivalent to
| :func:`_expression.not_`, that is::
|
| ~a
|
| is equivalent to::
|
| from sqlalchemy import not_
|
| not_(a)
|
| __or__(self, other: 'Any') -> 'Operators'
| Implement the ``|`` operator.
|
| When used with SQL expressions, results in an
| OR operation, equivalent to
| :func:`_expression.or_`, that is::
|
| a | b
|
| is equivalent to::
|
| from sqlalchemy import or_
|
| or_(a, b)
|
| Care should be taken when using ``|`` regarding
| operator precedence; the ``|`` operator has the highest precedence.
| The operands should be enclosed in parenthesis if they contain
| further sub expressions::
|
| (a == 2) | (b == 4)
|
| __sa_operate__ = operate(self, op: 'OperatorType', *other: 'Any', **kwargs: 'Any') -> 'Operators'
| Operate on an argument.
|
| This is the lowest level of operation, raises
| :class:`NotImplementedError` by default.
|
| Overriding this on a subclass can allow common
| behavior to be applied to all operations.
| For example, overriding :class:`.ColumnOperators`
| to apply ``func.lower()`` to the left and right
| side::
|
| class MyComparator(ColumnOperators):
| def operate(self, op, other, **kwargs):
| return op(func.lower(self), func.lower(other), **kwargs)
|
| :param op: Operator callable.
| :param \*other: the 'other' side of the operation. Will
| be a single scalar for most operations.
| :param \**kwargs: modifiers. These may be passed by special
| operators such as :meth:`ColumnOperators.contains`.
|
| bool_op(self, opstring: 'str', precedence: 'int' = 0, python_impl: 'Optional[Callable[..., Any]]' = None) -> 'Callable[[Any], Operators]'
| Return a custom boolean operator.
|
| This method is shorthand for calling
| :meth:`.Operators.op` and passing the
| :paramref:`.Operators.op.is_comparison`
| flag with True. A key advantage to using :meth:`.Operators.bool_op`
| is that when using column constructs, the "boolean" nature of the
| returned expression will be present for :pep:`484` purposes.
|
| .. seealso::
|
| :meth:`.Operators.op`
|
| op(self, opstring: 'str', precedence: 'int' = 0, is_comparison: 'bool' = False, return_type: 'Optional[Union[Type[TypeEngine[Any]], TypeEngine[Any]]]' = None, python_impl: 'Optional[Callable[..., Any]]' = None) -> 'Callable[[Any], Operators]'
| Produce a generic operator function.
|
| e.g.::
|
| somecolumn.op("*")(5)
|
| produces::
|
| somecolumn * 5
|
| This function can also be used to make bitwise operators explicit. For
| example::
|
| somecolumn.op("&")(0xFF)
|
| is a bitwise AND of the value in ``somecolumn``.
|
| :param opstring: a string which will be output as the infix operator
| between this element and the expression passed to the
| generated function.
|
| :param precedence: precedence which the database is expected to apply
| to the operator in SQL expressions. This integer value acts as a hint
| for the SQL compiler to know when explicit parenthesis should be
| rendered around a particular operation. A lower number will cause the
| expression to be parenthesized when applied against another operator
| with higher precedence. The default value of ``0`` is lower than all
| operators except for the comma (``,``) and ``AS`` operators. A value
| of 100 will be higher or equal to all operators, and -100 will be
| lower than or equal to all operators.
|
| .. seealso::
|
| :ref:`faq_sql_expression_op_parenthesis` - detailed description
| of how the SQLAlchemy SQL compiler renders parenthesis
|
| :param is_comparison: legacy; if True, the operator will be considered
| as a "comparison" operator, that is which evaluates to a boolean
| true/false value, like ``==``, ``>``, etc. This flag is provided
| so that ORM relationships can establish that the operator is a
| comparison operator when used in a custom join condition.
|
| Using the ``is_comparison`` parameter is superseded by using the
| :meth:`.Operators.bool_op` method instead; this more succinct
| operator sets this parameter automatically, but also provides
| correct :pep:`484` typing support as the returned object will
| express a "boolean" datatype, i.e. ``BinaryExpression[bool]``.
|
| :param return_type: a :class:`.TypeEngine` class or object that will
| force the return type of an expression produced by this operator
| to be of that type. By default, operators that specify
| :paramref:`.Operators.op.is_comparison` will resolve to
| :class:`.Boolean`, and those that do not will be of the same
| type as the left-hand operand.
|
| :param python_impl: an optional Python function that can evaluate
| two Python values in the same way as this operator works when
| run on the database server. Useful for in-Python SQL expression
| evaluation functions, such as for ORM hybrid attributes, and the
| ORM "evaluator" used to match objects in a session after a multi-row
| update or delete.
|
| e.g.::
|
| >>> expr = column("x").op("+", python_impl=lambda a, b: a + b)("y")
|
| The operator for the above expression will also work for non-SQL
| left and right objects::
|
| >>> expr.operator(5, 10)
| 15
|
| .. versionadded:: 2.0
|
|
| .. seealso::
|
| :meth:`.Operators.bool_op`
|
| :ref:`types_operators`
|
| :ref:`relationship_custom_operator`
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.elements.ClauseElement:
|
| __bool__(self)
|
| __getstate__(self)
| Helper for pickle.
|
| __repr__(self)
| Return repr(self).
|
| compare(self, other: 'ClauseElement', **kw: 'Any') -> 'bool'
| Compare this :class:`_expression.ClauseElement` to
| the given :class:`_expression.ClauseElement`.
|
| Subclasses should override the default behavior, which is a
| straight identity comparison.
|
| \**kw are arguments consumed by subclass ``compare()`` methods and
| may be used to modify the criteria for comparison
| (see :class:`_expression.ColumnElement`).
|
| description(...)
|
| entity_namespace(...)
|
| params(self, _ClauseElement__optionaldict: 'Optional[Mapping[str, Any]]' = None, **kwargs: 'Any') -> 'Self'
| Return a copy with :func:`_expression.bindparam` elements
| replaced.
|
| Returns a copy of this ClauseElement with
| :func:`_expression.bindparam`
| elements replaced with values taken from the given dictionary::
|
| >>> clause = column("x") + bindparam("foo")
| >>> print(clause.compile().params)
| {'foo':None}
| >>> print(clause.params({"foo": 7}).compile().params)
| {'foo':7}
|
| unique_params(self, _ClauseElement__optionaldict: 'Optional[Dict[str, Any]]' = None, **kwargs: 'Any') -> 'Self'
| Return a copy with :func:`_expression.bindparam` elements
| replaced.
|
| Same functionality as :meth:`_expression.ClauseElement.params`,
| except adds `unique=True`
| to affected bind parameters so that multiple statements can be
| used.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.elements.ClauseElement:
|
| is_clause_element = True
|
| is_dml = False
|
| is_selectable = False
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_instancemethod(fn: '_F') -> '_F'
| Decorate a method memoize its return value.
|
| :meta private:
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_attribute = <class 'sqlalchemy.util.langhelpers.HasMemoized.m...
| A read-only @property that is only evaluated once.
|
| :meta private:
|
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.visitors.HasTraverseInternals:
|
| get_children(self, *, omit_attrs: 'Tuple[str, ...]' = (), **kw: 'Any') -> 'Iterable[HasTraverseInternals]'
| Return immediate child :class:`.visitors.HasTraverseInternals`
| elements of this :class:`.visitors.HasTraverseInternals`.
|
| This is used for visit traversal.
|
| \**kw may contain flags that change the collection that is
| returned, for example to return a subset of items in order to
| cut down on larger traversals, or to return child items from a
| different context (such as schema-level collections instead of
| clause-level).
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.elements.CompilerElement:
|
| __str__(self) -> 'str'
| Return str(self).
|
| compile(self, bind: 'Optional[_HasDialect]' = None, dialect: 'Optional[Dialect]' = None, **kw: 'Any') -> 'Compiled'
| Compile this SQL expression.
|
| The return value is a :class:`~.Compiled` object.
| Calling ``str()`` or ``unicode()`` on the returned value will yield a
| string representation of the result. The
| :class:`~.Compiled` object also can return a
| dictionary of bind parameter names and values
| using the ``params`` accessor.
|
| :param bind: An :class:`.Connection` or :class:`.Engine` which
| can provide a :class:`.Dialect` in order to generate a
| :class:`.Compiled` object. If the ``bind`` and
| ``dialect`` parameters are both omitted, a default SQL compiler
| is used.
|
| :param column_keys: Used for INSERT and UPDATE statements, a list of
| column names which should be present in the VALUES clause of the
| compiled statement. If ``None``, all columns from the target table
| object are rendered.
|
| :param dialect: A :class:`.Dialect` instance which can generate
| a :class:`.Compiled` object. This argument takes precedence over
| the ``bind`` argument.
|
| :param compile_kwargs: optional dictionary of additional parameters
| that will be passed through to the compiler within all "visit"
| methods. This allows any custom flag to be passed through to
| a custom compilation construct, for example. It is also used
| for the case of passing the ``literal_binds`` flag through::
|
| from sqlalchemy.sql import table, column, select
|
| t = table("t", column("x"))
|
| s = select(t).where(t.c.x == 5)
|
| print(s.compile(compile_kwargs={"literal_binds": True}))
|
| .. seealso::
|
| :ref:`faq_sql_expression_string`
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.elements.CompilerElement:
|
| stringify_dialect = 'default'
|
| supports_execution = False
sqlalchemy.Extract
Python Library Documentation: class Extract in module sqlalchemy.sql.elements
class Extract(ColumnElement)
| Extract(field: 'str', expr: '_ColumnExpressionArgument[Any]')
|
| Represent a SQL EXTRACT clause, ``extract(field FROM expr)``.
|
| Method resolution order:
| Extract
| ColumnElement
| sqlalchemy.sql.roles.ColumnArgumentOrKeyRole
| sqlalchemy.sql.roles.ColumnArgumentRole
| sqlalchemy.sql.roles.StatementOptionRole
| sqlalchemy.sql.roles.WhereHavingRole
| sqlalchemy.sql.roles.OnClauseRole
| sqlalchemy.sql.roles.BinaryElementRole
| sqlalchemy.sql.roles.OrderByRole
| sqlalchemy.sql.roles.ColumnsClauseRole
| sqlalchemy.sql.roles.AllowsLambdaRole
| sqlalchemy.sql.roles.ByOfRole
| sqlalchemy.sql.roles.UsesInspection
| sqlalchemy.sql.roles.ColumnListRole
| sqlalchemy.sql.roles.LimitOffsetRole
| sqlalchemy.sql.roles.DMLColumnRole
| sqlalchemy.sql.roles.DDLConstraintColumnRole
| sqlalchemy.sql.roles.DDLExpressionRole
| sqlalchemy.sql.roles.StructuralRole
| SQLColumnExpression
| SQLCoreOperations
| sqlalchemy.sql.roles.ExpressionElementRole
| sqlalchemy.sql.roles.TypedColumnsClauseRole
| typing.Generic
| sqlalchemy.sql.operators.ColumnOperators
| sqlalchemy.sql.operators.Operators
| sqlalchemy.util.langhelpers.TypingOnly
| sqlalchemy.sql.roles.SQLRole
| DQLDMLClauseElement
| ClauseElement
| sqlalchemy.sql.annotation.SupportsWrappingAnnotations
| sqlalchemy.sql.annotation.SupportsAnnotations
| sqlalchemy.sql.cache_key.MemoizedHasCacheKey
| sqlalchemy.sql.cache_key.HasCacheKey
| sqlalchemy.util.langhelpers.HasMemoized
| sqlalchemy.sql.traversals.HasCopyInternals
| sqlalchemy.sql.visitors.ExternallyTraversible
| sqlalchemy.sql.visitors.HasTraverseInternals
| CompilerElement
| sqlalchemy.sql.visitors.Visitable
| builtins.object
|
| Methods defined here:
|
| __init__(self, field: 'str', expr: '_ColumnExpressionArgument[Any]')
| Initialize self. See help(type(self)) for accurate signature.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'_traverse_internals': '_TraverseInternalsType', 'e...
|
| __orig_bases__ = (sqlalchemy.sql.elements.ColumnElement[int],)
|
| __parameters__ = ()
|
| __visit_name__ = 'extract'
|
| ----------------------------------------------------------------------
| Methods inherited from ColumnElement:
|
| __getattr__(self, key: 'str') -> 'Any'
|
| __setstate__(self, state)
|
| base_columns(...)
|
| cast(self, type_: '_TypeEngineArgument[_OPT]') -> 'Cast[_OPT]'
| Produce a type cast, i.e. ``CAST(<expression> AS <type>)``.
|
| This is a shortcut to the :func:`_expression.cast` function.
|
| .. seealso::
|
| :ref:`tutorial_casts`
|
| :func:`_expression.cast`
|
| :func:`_expression.type_coerce`
|
| comparator(...)
|
| label(self, name: 'Optional[str]') -> 'Label[_T]'
| Produce a column label, i.e. ``<columnname> AS <name>``.
|
| This is a shortcut to the :func:`_expression.label` function.
|
| If 'name' is ``None``, an anonymous label name will be generated.
|
| operate(self, op: 'operators.OperatorType', *other: 'Any', **kwargs: 'Any') -> 'ColumnElement[Any]'
| Operate on an argument.
|
| This is the lowest level of operation, raises
| :class:`NotImplementedError` by default.
|
| Overriding this on a subclass can allow common
| behavior to be applied to all operations.
| For example, overriding :class:`.ColumnOperators`
| to apply ``func.lower()`` to the left and right
| side::
|
| class MyComparator(ColumnOperators):
| def operate(self, op, other, **kwargs):
| return op(func.lower(self), func.lower(other), **kwargs)
|
| :param op: Operator callable.
| :param \*other: the 'other' side of the operation. Will
| be a single scalar for most operations.
| :param \**kwargs: modifiers. These may be passed by special
| operators such as :meth:`ColumnOperators.contains`.
|
| proxy_set(...)
| set of all columns we are proxying
|
| as of 2.0 this is explicitly deannotated columns. previously it was
| effectively deannotated columns but wasn't enforced. annotated
| columns should basically not go into sets if at all possible because
| their hashing behavior is very non-performant.
|
| reverse_operate(self, op: 'operators.OperatorType', other: 'Any', **kwargs: 'Any') -> 'ColumnElement[Any]'
| Reverse operate on an argument.
|
| Usage is the same as :meth:`operate`.
|
| self_group(self, against: 'Optional[OperatorType]' = None) -> 'ColumnElement[Any]'
| 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.
|
| shares_lineage(self, othercolumn: 'ColumnElement[Any]') -> 'bool'
| Return True if the given :class:`_expression.ColumnElement`
| has a common ancestor to this :class:`_expression.ColumnElement`.
|
| type(...)
|
| ----------------------------------------------------------------------
| Readonly properties inherited from ColumnElement:
|
| anon_key_label
| .. deprecated:: 1.4 The :attr:`_expression.ColumnElement.anon_key_label` attribute is now private, and the public accessor is deprecated.
|
| anon_label
| .. deprecated:: 1.4 The :attr:`_expression.ColumnElement.anon_label` attribute is now private, and the public accessor is deprecated.
|
| expression
| Return a column expression.
|
| Part of the inspection interface; returns self.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from ColumnElement:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from ColumnElement:
|
| foreign_keys = frozenset()
|
| key = None
|
| primary_key = False
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.AllowsLambdaRole:
|
| allows_lambda = True
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.UsesInspection:
|
| uses_inspection = True
|
| ----------------------------------------------------------------------
| Class methods inherited from typing.Generic:
|
| __class_getitem__(...)
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__(...)
| Function to initialize subclasses.
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.operators.ColumnOperators:
|
| __add__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``+`` operator.
|
| In a column context, produces the clause ``a + b``
| if the parent object has non-string affinity.
| If the parent object has a string affinity,
| produces the concatenation operator, ``a || b`` -
| see :meth:`.ColumnOperators.concat`.
|
| __contains__(self, other: 'Any') -> 'ColumnOperators'
|
| __eq__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``==`` operator.
|
| In a column context, produces the clause ``a = b``.
| If the target is ``None``, produces ``a IS NULL``.
|
| __floordiv__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``//`` operator.
|
| In a column context, produces the clause ``a / b``,
| which is the same as "truediv", but considers the result
| type to be integer.
|
| .. versionadded:: 2.0
|
| __ge__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``>=`` operator.
|
| In a column context, produces the clause ``a >= b``.
|
| __getitem__(self, index: 'Any') -> 'ColumnOperators'
| Implement the [] operator.
|
| This can be used by some database-specific types
| such as PostgreSQL ARRAY and HSTORE.
|
| __gt__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``>`` operator.
|
| In a column context, produces the clause ``a > b``.
|
| __hash__(self, /) from builtins.object
| Return hash(self).
|
| __le__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``<=`` operator.
|
| In a column context, produces the clause ``a <= b``.
|
| __lshift__(self, other: 'Any') -> 'ColumnOperators'
| implement the << operator.
|
| Not used by SQLAlchemy core, this is provided
| for custom operator systems which want to use
| << as an extension point.
|
| __lt__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``<`` operator.
|
| In a column context, produces the clause ``a < b``.
|
| __mod__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``%`` operator.
|
| In a column context, produces the clause ``a % b``.
|
| __mul__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``*`` operator.
|
| In a column context, produces the clause ``a * b``.
|
| __ne__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``!=`` operator.
|
| In a column context, produces the clause ``a != b``.
| If the target is ``None``, produces ``a IS NOT NULL``.
|
| __neg__(self) -> 'ColumnOperators'
| Implement the ``-`` operator.
|
| In a column context, produces the clause ``-a``.
|
| __radd__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``+`` operator in reverse.
|
| See :meth:`.ColumnOperators.__add__`.
|
| __rfloordiv__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``//`` operator in reverse.
|
| See :meth:`.ColumnOperators.__floordiv__`.
|
| __rmod__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``%`` operator in reverse.
|
| See :meth:`.ColumnOperators.__mod__`.
|
| __rmul__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``*`` operator in reverse.
|
| See :meth:`.ColumnOperators.__mul__`.
|
| __rshift__(self, other: 'Any') -> 'ColumnOperators'
| implement the >> operator.
|
| Not used by SQLAlchemy core, this is provided
| for custom operator systems which want to use
| >> as an extension point.
|
| __rsub__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``-`` operator in reverse.
|
| See :meth:`.ColumnOperators.__sub__`.
|
| __rtruediv__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``/`` operator in reverse.
|
| See :meth:`.ColumnOperators.__truediv__`.
|
| __sub__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``-`` operator.
|
| In a column context, produces the clause ``a - b``.
|
| __truediv__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``/`` operator.
|
| In a column context, produces the clause ``a / b``, and
| considers the result type to be numeric.
|
| .. versionchanged:: 2.0 The truediv operator against two integers
| is now considered to return a numeric value. Behavior on specific
| backends may vary.
|
| all_(self) -> 'ColumnOperators'
| Produce an :func:`_expression.all_` clause against the
| parent object.
|
| See the documentation for :func:`_sql.all_` for examples.
|
| .. note:: be sure to not confuse the newer
| :meth:`_sql.ColumnOperators.all_` method with the **legacy**
| version of this method, the :meth:`_types.ARRAY.Comparator.all`
| method that's specific to :class:`_types.ARRAY`, which uses a
| different calling style.
|
| any_(self) -> 'ColumnOperators'
| Produce an :func:`_expression.any_` clause against the
| parent object.
|
| See the documentation for :func:`_sql.any_` for examples.
|
| .. note:: be sure to not confuse the newer
| :meth:`_sql.ColumnOperators.any_` method with the **legacy**
| version of this method, the :meth:`_types.ARRAY.Comparator.any`
| method that's specific to :class:`_types.ARRAY`, which uses a
| different calling style.
|
| asc(self) -> 'ColumnOperators'
| Produce a :func:`_expression.asc` clause against the
| parent object.
|
| between(self, cleft: 'Any', cright: 'Any', symmetric: 'bool' = False) -> 'ColumnOperators'
| Produce a :func:`_expression.between` clause against
| the parent object, given the lower and upper range.
|
| bitwise_and(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise AND operation, typically via the ``&``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_lshift(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise LSHIFT operation, typically via the ``<<``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_not(self) -> 'ColumnOperators'
| Produce a bitwise NOT operation, typically via the ``~``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_or(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise OR operation, typically via the ``|``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_rshift(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise RSHIFT operation, typically via the ``>>``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_xor(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise XOR operation, typically via the ``^``
| operator, or ``#`` for PostgreSQL.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| collate(self, collation: 'str') -> 'ColumnOperators'
| Produce a :func:`_expression.collate` clause against
| the parent object, given the collation string.
|
| .. seealso::
|
| :func:`_expression.collate`
|
| concat(self, other: 'Any') -> 'ColumnOperators'
| Implement the 'concat' operator.
|
| In a column context, produces the clause ``a || b``,
| or uses the ``concat()`` operator on MySQL.
|
| contains(self, other: 'Any', **kw: 'Any') -> 'ColumnOperators'
| Implement the 'contains' operator.
|
| Produces a LIKE expression that tests against a match for the middle
| of a string value:
|
| .. sourcecode:: sql
|
| column LIKE '%' || <other> || '%'
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.contains("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.contains.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.contains.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.contains.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.contains("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE '%' || :param || '%' ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.contains("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE '%' || :param || '%' ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.contains.autoescape`::
|
| somecolumn.contains("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.startswith`
|
| :meth:`.ColumnOperators.endswith`
|
| :meth:`.ColumnOperators.like`
|
| desc(self) -> 'ColumnOperators'
| Produce a :func:`_expression.desc` clause against the
| parent object.
|
| distinct(self) -> 'ColumnOperators'
| Produce a :func:`_expression.distinct` clause against the
| parent object.
|
| endswith(self, other: 'Any', escape: 'Optional[str]' = None, autoescape: 'bool' = False) -> 'ColumnOperators'
| Implement the 'endswith' operator.
|
| Produces a LIKE expression that tests against a match for the end
| of a string value:
|
| .. sourcecode:: sql
|
| column LIKE '%' || <other>
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.endswith("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.endswith.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.endswith.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.endswith.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.endswith("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE '%' || :param ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.endswith("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE '%' || :param ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.endswith.autoescape`::
|
| somecolumn.endswith("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.startswith`
|
| :meth:`.ColumnOperators.contains`
|
| :meth:`.ColumnOperators.like`
|
| icontains(self, other: 'Any', **kw: 'Any') -> 'ColumnOperators'
| Implement the ``icontains`` operator, e.g. case insensitive
| version of :meth:`.ColumnOperators.contains`.
|
| Produces a LIKE expression that tests against an insensitive match
| for the middle of a string value:
|
| .. sourcecode:: sql
|
| lower(column) LIKE '%' || lower(<other>) || '%'
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.icontains("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.icontains.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.icontains.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.icontains.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.icontains("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE '%' || lower(:param) || '%' ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.icontains("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE '%' || lower(:param) || '%' ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.contains.autoescape`::
|
| somecolumn.icontains("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.contains`
|
| iendswith(self, other: 'Any', escape: 'Optional[str]' = None, autoescape: 'bool' = False) -> 'ColumnOperators'
| Implement the ``iendswith`` operator, e.g. case insensitive
| version of :meth:`.ColumnOperators.endswith`.
|
| Produces a LIKE expression that tests against an insensitive match
| for the end of a string value:
|
| .. sourcecode:: sql
|
| lower(column) LIKE '%' || lower(<other>)
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.iendswith("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.iendswith.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.iendswith.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.iendswith.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.iendswith("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE '%' || lower(:param) ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.iendswith("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE '%' || lower(:param) ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.iendswith.autoescape`::
|
| somecolumn.endswith("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.endswith`
|
| ilike(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
| Implement the ``ilike`` operator, e.g. case insensitive LIKE.
|
| In a column context, produces an expression either of the form:
|
| .. sourcecode:: sql
|
| lower(a) LIKE lower(other)
|
| Or on backends that support the ILIKE operator:
|
| .. sourcecode:: sql
|
| a ILIKE other
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.ilike("%foobar%"))
|
| :param other: expression to be compared
| :param escape: optional escape character, renders the ``ESCAPE``
| keyword, e.g.::
|
| somecolumn.ilike("foo/%bar", escape="/")
|
| .. seealso::
|
| :meth:`.ColumnOperators.like`
|
| in_(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``in`` operator.
|
| In a column context, produces the clause ``column IN <other>``.
|
| The given parameter ``other`` may be:
|
| * A list of literal values,
| e.g.::
|
| stmt.where(column.in_([1, 2, 3]))
|
| In this calling form, the list of items is converted to a set of
| bound parameters the same length as the list given:
|
| .. sourcecode:: sql
|
| WHERE COL IN (?, ?, ?)
|
| * A list of tuples may be provided if the comparison is against a
| :func:`.tuple_` containing multiple expressions::
|
| from sqlalchemy import tuple_
|
| stmt.where(tuple_(col1, col2).in_([(1, 10), (2, 20), (3, 30)]))
|
| * An empty list,
| e.g.::
|
| stmt.where(column.in_([]))
|
| In this calling form, the expression renders an "empty set"
| expression. These expressions are tailored to individual backends
| and are generally trying to get an empty SELECT statement as a
| subquery. Such as on SQLite, the expression is:
|
| .. sourcecode:: sql
|
| WHERE col IN (SELECT 1 FROM (SELECT 1) WHERE 1!=1)
|
| .. versionchanged:: 1.4 empty IN expressions now use an
| execution-time generated SELECT subquery in all cases.
|
| * A bound parameter, e.g. :func:`.bindparam`, may be used if it
| includes the :paramref:`.bindparam.expanding` flag::
|
| stmt.where(column.in_(bindparam("value", expanding=True)))
|
| In this calling form, the expression renders a special non-SQL
| placeholder expression that looks like:
|
| .. sourcecode:: sql
|
| WHERE COL IN ([EXPANDING_value])
|
| This placeholder expression is intercepted at statement execution
| time to be converted into the variable number of bound parameter
| form illustrated earlier. If the statement were executed as::
|
| connection.execute(stmt, {"value": [1, 2, 3]})
|
| The database would be passed a bound parameter for each value:
|
| .. sourcecode:: sql
|
| WHERE COL IN (?, ?, ?)
|
| .. versionadded:: 1.2 added "expanding" bound parameters
|
| If an empty list is passed, a special "empty list" expression,
| which is specific to the database in use, is rendered. On
| SQLite this would be:
|
| .. sourcecode:: sql
|
| WHERE COL IN (SELECT 1 FROM (SELECT 1) WHERE 1!=1)
|
| .. versionadded:: 1.3 "expanding" bound parameters now support
| empty lists
|
| * a :func:`_expression.select` construct, which is usually a
| correlated scalar select::
|
| stmt.where(
| column.in_(select(othertable.c.y).where(table.c.x == othertable.c.x))
| )
|
| In this calling form, :meth:`.ColumnOperators.in_` renders as given:
|
| .. sourcecode:: sql
|
| WHERE COL IN (SELECT othertable.y
| FROM othertable WHERE othertable.x = table.x)
|
| :param other: a list of literals, a :func:`_expression.select`
| construct, or a :func:`.bindparam` construct that includes the
| :paramref:`.bindparam.expanding` flag set to True.
|
| is_(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``IS`` operator.
|
| Normally, ``IS`` is generated automatically when comparing to a
| value of ``None``, which resolves to ``NULL``. However, explicit
| usage of ``IS`` may be desirable if comparing to boolean values
| on certain platforms.
|
| .. seealso:: :meth:`.ColumnOperators.is_not`
|
| is_distinct_from(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``IS DISTINCT FROM`` operator.
|
| Renders "a IS DISTINCT FROM b" on most platforms;
| on some such as SQLite may render "a IS NOT b".
|
| is_not(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``IS NOT`` operator.
|
| Normally, ``IS NOT`` is generated automatically when comparing to a
| value of ``None``, which resolves to ``NULL``. However, explicit
| usage of ``IS NOT`` may be desirable if comparing to boolean values
| on certain platforms.
|
| .. versionchanged:: 1.4 The ``is_not()`` operator is renamed from
| ``isnot()`` in previous releases. The previous name remains
| available for backwards compatibility.
|
| .. seealso:: :meth:`.ColumnOperators.is_`
|
| is_not_distinct_from(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``IS NOT DISTINCT FROM`` operator.
|
| Renders "a IS NOT DISTINCT FROM b" on most platforms;
| on some such as SQLite may render "a IS b".
|
| .. versionchanged:: 1.4 The ``is_not_distinct_from()`` operator is
| renamed from ``isnot_distinct_from()`` in previous releases.
| The previous name remains available for backwards compatibility.
|
| isnot = is_not(self, other: 'Any') -> 'ColumnOperators'
|
| isnot_distinct_from = is_not_distinct_from(self, other: 'Any') -> 'ColumnOperators'
|
| istartswith(self, other: 'Any', escape: 'Optional[str]' = None, autoescape: 'bool' = False) -> 'ColumnOperators'
| Implement the ``istartswith`` operator, e.g. case insensitive
| version of :meth:`.ColumnOperators.startswith`.
|
| Produces a LIKE expression that tests against an insensitive
| match for the start of a string value:
|
| .. sourcecode:: sql
|
| lower(column) LIKE lower(<other>) || '%'
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.istartswith("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.istartswith.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.istartswith.escape` parameter will
| establish a given character as an escape character which can be of
| use when the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.istartswith.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.istartswith("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE lower(:param) || '%' ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.istartswith("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE lower(:param) || '%' ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.istartswith.autoescape`::
|
| somecolumn.istartswith("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.startswith`
|
| like(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
| Implement the ``like`` operator.
|
| In a column context, produces the expression:
|
| .. sourcecode:: sql
|
| a LIKE other
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.like("%foobar%"))
|
| :param other: expression to be compared
| :param escape: optional escape character, renders the ``ESCAPE``
| keyword, e.g.::
|
| somecolumn.like("foo/%bar", escape="/")
|
| .. seealso::
|
| :meth:`.ColumnOperators.ilike`
|
| match(self, other: 'Any', **kwargs: 'Any') -> 'ColumnOperators'
| Implements a database-specific 'match' operator.
|
| :meth:`_sql.ColumnOperators.match` attempts to resolve to
| a MATCH-like function or operator provided by the backend.
| Examples include:
|
| * PostgreSQL - renders ``x @@ plainto_tsquery(y)``
|
| .. versionchanged:: 2.0 ``plainto_tsquery()`` is used instead
| of ``to_tsquery()`` for PostgreSQL now; for compatibility with
| other forms, see :ref:`postgresql_match`.
|
|
| * MySQL - renders ``MATCH (x) AGAINST (y IN BOOLEAN MODE)``
|
| .. seealso::
|
| :class:`_mysql.match` - MySQL specific construct with
| additional features.
|
| * Oracle Database - renders ``CONTAINS(x, y)``
| * other backends may provide special implementations.
| * Backends without any special implementation will emit
| the operator as "MATCH". This is compatible with SQLite, for
| example.
|
| not_ilike(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
| implement the ``NOT ILIKE`` operator.
|
| This is equivalent to using negation with
| :meth:`.ColumnOperators.ilike`, i.e. ``~x.ilike(y)``.
|
| .. versionchanged:: 1.4 The ``not_ilike()`` operator is renamed from
| ``notilike()`` in previous releases. The previous name remains
| available for backwards compatibility.
|
| .. seealso::
|
| :meth:`.ColumnOperators.ilike`
|
| not_in(self, other: 'Any') -> 'ColumnOperators'
| implement the ``NOT IN`` operator.
|
| This is equivalent to using negation with
| :meth:`.ColumnOperators.in_`, i.e. ``~x.in_(y)``.
|
| In the case that ``other`` is an empty sequence, the compiler
| produces an "empty not in" expression. This defaults to the
| expression "1 = 1" to produce true in all cases. The
| :paramref:`_sa.create_engine.empty_in_strategy` may be used to
| alter this behavior.
|
| .. versionchanged:: 1.4 The ``not_in()`` operator is renamed from
| ``notin_()`` in previous releases. The previous name remains
| available for backwards compatibility.
|
| .. versionchanged:: 1.2 The :meth:`.ColumnOperators.in_` and
| :meth:`.ColumnOperators.not_in` operators
| now produce a "static" expression for an empty IN sequence
| by default.
|
| .. seealso::
|
| :meth:`.ColumnOperators.in_`
|
| not_like(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
| implement the ``NOT LIKE`` operator.
|
| This is equivalent to using negation with
| :meth:`.ColumnOperators.like`, i.e. ``~x.like(y)``.
|
| .. versionchanged:: 1.4 The ``not_like()`` operator is renamed from
| ``notlike()`` in previous releases. The previous name remains
| available for backwards compatibility.
|
| .. seealso::
|
| :meth:`.ColumnOperators.like`
|
| notilike = not_ilike(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
|
| notin_ = not_in(self, other: 'Any') -> 'ColumnOperators'
|
| notlike = not_like(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
|
| nulls_first(self) -> 'ColumnOperators'
| Produce a :func:`_expression.nulls_first` clause against the
| parent object.
|
| .. versionchanged:: 1.4 The ``nulls_first()`` operator is
| renamed from ``nullsfirst()`` in previous releases.
| The previous name remains available for backwards compatibility.
|
| nulls_last(self) -> 'ColumnOperators'
| Produce a :func:`_expression.nulls_last` clause against the
| parent object.
|
| .. versionchanged:: 1.4 The ``nulls_last()`` operator is
| renamed from ``nullslast()`` in previous releases.
| The previous name remains available for backwards compatibility.
|
| nullsfirst = nulls_first(self) -> 'ColumnOperators'
|
| nullslast = nulls_last(self) -> 'ColumnOperators'
|
| regexp_match(self, pattern: 'Any', flags: 'Optional[str]' = None) -> 'ColumnOperators'
| Implements a database-specific 'regexp match' operator.
|
| E.g.::
|
| stmt = select(table.c.some_column).where(
| table.c.some_column.regexp_match("^(b|c)")
| )
|
| :meth:`_sql.ColumnOperators.regexp_match` attempts to resolve to
| a REGEXP-like function or operator provided by the backend, however
| the specific regular expression syntax and flags available are
| **not backend agnostic**.
|
| Examples include:
|
| * PostgreSQL - renders ``x ~ y`` or ``x !~ y`` when negated.
| * Oracle Database - renders ``REGEXP_LIKE(x, y)``
| * SQLite - uses SQLite's ``REGEXP`` placeholder operator and calls into
| the Python ``re.match()`` builtin.
| * other backends may provide special implementations.
| * Backends without any special implementation will emit
| the operator as "REGEXP" or "NOT REGEXP". This is compatible with
| SQLite and MySQL, for example.
|
| Regular expression support is currently implemented for Oracle
| Database, PostgreSQL, MySQL and MariaDB. Partial support is available
| for SQLite. Support among third-party dialects may vary.
|
| :param pattern: The regular expression pattern string or column
| clause.
| :param flags: Any regular expression string flags to apply, passed as
| plain Python string only. These flags are backend specific.
| Some backends, like PostgreSQL and MariaDB, may alternatively
| specify the flags as part of the pattern.
| When using the ignore case flag 'i' in PostgreSQL, the ignore case
| regexp match operator ``~*`` or ``!~*`` will be used.
|
| .. versionadded:: 1.4
|
| .. versionchanged:: 1.4.48, 2.0.18 Note that due to an implementation
| error, the "flags" parameter previously accepted SQL expression
| objects such as column expressions in addition to plain Python
| strings. This implementation did not work correctly with caching
| and was removed; strings only should be passed for the "flags"
| parameter, as these flags are rendered as literal inline values
| within SQL expressions.
|
| .. seealso::
|
| :meth:`_sql.ColumnOperators.regexp_replace`
|
| regexp_replace(self, pattern: 'Any', replacement: 'Any', flags: 'Optional[str]' = None) -> 'ColumnOperators'
| Implements a database-specific 'regexp replace' operator.
|
| E.g.::
|
| stmt = select(
| table.c.some_column.regexp_replace("b(..)", "XY", flags="g")
| )
|
| :meth:`_sql.ColumnOperators.regexp_replace` attempts to resolve to
| a REGEXP_REPLACE-like function provided by the backend, that
| usually emit the function ``REGEXP_REPLACE()``. However,
| the specific regular expression syntax and flags available are
| **not backend agnostic**.
|
| Regular expression replacement support is currently implemented for
| Oracle Database, PostgreSQL, MySQL 8 or greater and MariaDB. Support
| among third-party dialects may vary.
|
| :param pattern: The regular expression pattern string or column
| clause.
| :param pattern: The replacement string or column clause.
| :param flags: Any regular expression string flags to apply, passed as
| plain Python string only. These flags are backend specific.
| Some backends, like PostgreSQL and MariaDB, may alternatively
| specify the flags as part of the pattern.
|
| .. versionadded:: 1.4
|
| .. versionchanged:: 1.4.48, 2.0.18 Note that due to an implementation
| error, the "flags" parameter previously accepted SQL expression
| objects such as column expressions in addition to plain Python
| strings. This implementation did not work correctly with caching
| and was removed; strings only should be passed for the "flags"
| parameter, as these flags are rendered as literal inline values
| within SQL expressions.
|
|
| .. seealso::
|
| :meth:`_sql.ColumnOperators.regexp_match`
|
| startswith(self, other: 'Any', escape: 'Optional[str]' = None, autoescape: 'bool' = False) -> 'ColumnOperators'
| Implement the ``startswith`` operator.
|
| Produces a LIKE expression that tests against a match for the start
| of a string value:
|
| .. sourcecode:: sql
|
| column LIKE <other> || '%'
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.startswith("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.startswith.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.startswith.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.startswith.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.startswith("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE :param || '%' ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.startswith("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE :param || '%' ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.startswith.autoescape`::
|
| somecolumn.startswith("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.endswith`
|
| :meth:`.ColumnOperators.contains`
|
| :meth:`.ColumnOperators.like`
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.operators.ColumnOperators:
|
| timetuple = None
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.operators.Operators:
|
| __and__(self, other: 'Any') -> 'Operators'
| Implement the ``&`` operator.
|
| When used with SQL expressions, results in an
| AND operation, equivalent to
| :func:`_expression.and_`, that is::
|
| a & b
|
| is equivalent to::
|
| from sqlalchemy import and_
|
| and_(a, b)
|
| Care should be taken when using ``&`` regarding
| operator precedence; the ``&`` operator has the highest precedence.
| The operands should be enclosed in parenthesis if they contain
| further sub expressions::
|
| (a == 2) & (b == 4)
|
| __invert__(self) -> 'Operators'
| Implement the ``~`` operator.
|
| When used with SQL expressions, results in a
| NOT operation, equivalent to
| :func:`_expression.not_`, that is::
|
| ~a
|
| is equivalent to::
|
| from sqlalchemy import not_
|
| not_(a)
|
| __or__(self, other: 'Any') -> 'Operators'
| Implement the ``|`` operator.
|
| When used with SQL expressions, results in an
| OR operation, equivalent to
| :func:`_expression.or_`, that is::
|
| a | b
|
| is equivalent to::
|
| from sqlalchemy import or_
|
| or_(a, b)
|
| Care should be taken when using ``|`` regarding
| operator precedence; the ``|`` operator has the highest precedence.
| The operands should be enclosed in parenthesis if they contain
| further sub expressions::
|
| (a == 2) | (b == 4)
|
| __sa_operate__ = operate(self, op: 'OperatorType', *other: 'Any', **kwargs: 'Any') -> 'Operators'
| Operate on an argument.
|
| This is the lowest level of operation, raises
| :class:`NotImplementedError` by default.
|
| Overriding this on a subclass can allow common
| behavior to be applied to all operations.
| For example, overriding :class:`.ColumnOperators`
| to apply ``func.lower()`` to the left and right
| side::
|
| class MyComparator(ColumnOperators):
| def operate(self, op, other, **kwargs):
| return op(func.lower(self), func.lower(other), **kwargs)
|
| :param op: Operator callable.
| :param \*other: the 'other' side of the operation. Will
| be a single scalar for most operations.
| :param \**kwargs: modifiers. These may be passed by special
| operators such as :meth:`ColumnOperators.contains`.
|
| bool_op(self, opstring: 'str', precedence: 'int' = 0, python_impl: 'Optional[Callable[..., Any]]' = None) -> 'Callable[[Any], Operators]'
| Return a custom boolean operator.
|
| This method is shorthand for calling
| :meth:`.Operators.op` and passing the
| :paramref:`.Operators.op.is_comparison`
| flag with True. A key advantage to using :meth:`.Operators.bool_op`
| is that when using column constructs, the "boolean" nature of the
| returned expression will be present for :pep:`484` purposes.
|
| .. seealso::
|
| :meth:`.Operators.op`
|
| op(self, opstring: 'str', precedence: 'int' = 0, is_comparison: 'bool' = False, return_type: 'Optional[Union[Type[TypeEngine[Any]], TypeEngine[Any]]]' = None, python_impl: 'Optional[Callable[..., Any]]' = None) -> 'Callable[[Any], Operators]'
| Produce a generic operator function.
|
| e.g.::
|
| somecolumn.op("*")(5)
|
| produces::
|
| somecolumn * 5
|
| This function can also be used to make bitwise operators explicit. For
| example::
|
| somecolumn.op("&")(0xFF)
|
| is a bitwise AND of the value in ``somecolumn``.
|
| :param opstring: a string which will be output as the infix operator
| between this element and the expression passed to the
| generated function.
|
| :param precedence: precedence which the database is expected to apply
| to the operator in SQL expressions. This integer value acts as a hint
| for the SQL compiler to know when explicit parenthesis should be
| rendered around a particular operation. A lower number will cause the
| expression to be parenthesized when applied against another operator
| with higher precedence. The default value of ``0`` is lower than all
| operators except for the comma (``,``) and ``AS`` operators. A value
| of 100 will be higher or equal to all operators, and -100 will be
| lower than or equal to all operators.
|
| .. seealso::
|
| :ref:`faq_sql_expression_op_parenthesis` - detailed description
| of how the SQLAlchemy SQL compiler renders parenthesis
|
| :param is_comparison: legacy; if True, the operator will be considered
| as a "comparison" operator, that is which evaluates to a boolean
| true/false value, like ``==``, ``>``, etc. This flag is provided
| so that ORM relationships can establish that the operator is a
| comparison operator when used in a custom join condition.
|
| Using the ``is_comparison`` parameter is superseded by using the
| :meth:`.Operators.bool_op` method instead; this more succinct
| operator sets this parameter automatically, but also provides
| correct :pep:`484` typing support as the returned object will
| express a "boolean" datatype, i.e. ``BinaryExpression[bool]``.
|
| :param return_type: a :class:`.TypeEngine` class or object that will
| force the return type of an expression produced by this operator
| to be of that type. By default, operators that specify
| :paramref:`.Operators.op.is_comparison` will resolve to
| :class:`.Boolean`, and those that do not will be of the same
| type as the left-hand operand.
|
| :param python_impl: an optional Python function that can evaluate
| two Python values in the same way as this operator works when
| run on the database server. Useful for in-Python SQL expression
| evaluation functions, such as for ORM hybrid attributes, and the
| ORM "evaluator" used to match objects in a session after a multi-row
| update or delete.
|
| e.g.::
|
| >>> expr = column("x").op("+", python_impl=lambda a, b: a + b)("y")
|
| The operator for the above expression will also work for non-SQL
| left and right objects::
|
| >>> expr.operator(5, 10)
| 15
|
| .. versionadded:: 2.0
|
|
| .. seealso::
|
| :meth:`.Operators.bool_op`
|
| :ref:`types_operators`
|
| :ref:`relationship_custom_operator`
|
| ----------------------------------------------------------------------
| Methods inherited from ClauseElement:
|
| __bool__(self)
|
| __getstate__(self)
| Helper for pickle.
|
| __repr__(self)
| Return repr(self).
|
| compare(self, other: 'ClauseElement', **kw: 'Any') -> 'bool'
| Compare this :class:`_expression.ClauseElement` to
| the given :class:`_expression.ClauseElement`.
|
| Subclasses should override the default behavior, which is a
| straight identity comparison.
|
| \**kw are arguments consumed by subclass ``compare()`` methods and
| may be used to modify the criteria for comparison
| (see :class:`_expression.ColumnElement`).
|
| description(...)
|
| entity_namespace(...)
|
| params(self, _ClauseElement__optionaldict: 'Optional[Mapping[str, Any]]' = None, **kwargs: 'Any') -> 'Self'
| Return a copy with :func:`_expression.bindparam` elements
| replaced.
|
| Returns a copy of this ClauseElement with
| :func:`_expression.bindparam`
| elements replaced with values taken from the given dictionary::
|
| >>> clause = column("x") + bindparam("foo")
| >>> print(clause.compile().params)
| {'foo':None}
| >>> print(clause.params({"foo": 7}).compile().params)
| {'foo':7}
|
| unique_params(self, _ClauseElement__optionaldict: 'Optional[Dict[str, Any]]' = None, **kwargs: 'Any') -> 'Self'
| Return a copy with :func:`_expression.bindparam` elements
| replaced.
|
| Same functionality as :meth:`_expression.ClauseElement.params`,
| except adds `unique=True`
| to affected bind parameters so that multiple statements can be
| used.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from ClauseElement:
|
| is_clause_element = True
|
| is_dml = False
|
| is_selectable = False
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.cache_key.HasCacheKey:
|
| inherit_cache = None
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_instancemethod(fn: '_F') -> '_F'
| Decorate a method memoize its return value.
|
| :meta private:
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_attribute = <class 'sqlalchemy.util.langhelpers.HasMemoized.m...
| A read-only @property that is only evaluated once.
|
| :meta private:
|
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.visitors.HasTraverseInternals:
|
| get_children(self, *, omit_attrs: 'Tuple[str, ...]' = (), **kw: 'Any') -> 'Iterable[HasTraverseInternals]'
| Return immediate child :class:`.visitors.HasTraverseInternals`
| elements of this :class:`.visitors.HasTraverseInternals`.
|
| This is used for visit traversal.
|
| \**kw may contain flags that change the collection that is
| returned, for example to return a subset of items in order to
| cut down on larger traversals, or to return child items from a
| different context (such as schema-level collections instead of
| clause-level).
|
| ----------------------------------------------------------------------
| Methods inherited from CompilerElement:
|
| __str__(self) -> 'str'
| Return str(self).
|
| compile(self, bind: 'Optional[_HasDialect]' = None, dialect: 'Optional[Dialect]' = None, **kw: 'Any') -> 'Compiled'
| Compile this SQL expression.
|
| The return value is a :class:`~.Compiled` object.
| Calling ``str()`` or ``unicode()`` on the returned value will yield a
| string representation of the result. The
| :class:`~.Compiled` object also can return a
| dictionary of bind parameter names and values
| using the ``params`` accessor.
|
| :param bind: An :class:`.Connection` or :class:`.Engine` which
| can provide a :class:`.Dialect` in order to generate a
| :class:`.Compiled` object. If the ``bind`` and
| ``dialect`` parameters are both omitted, a default SQL compiler
| is used.
|
| :param column_keys: Used for INSERT and UPDATE statements, a list of
| column names which should be present in the VALUES clause of the
| compiled statement. If ``None``, all columns from the target table
| object are rendered.
|
| :param dialect: A :class:`.Dialect` instance which can generate
| a :class:`.Compiled` object. This argument takes precedence over
| the ``bind`` argument.
|
| :param compile_kwargs: optional dictionary of additional parameters
| that will be passed through to the compiler within all "visit"
| methods. This allows any custom flag to be passed through to
| a custom compilation construct, for example. It is also used
| for the case of passing the ``literal_binds`` flag through::
|
| from sqlalchemy.sql import table, column, select
|
| t = table("t", column("x"))
|
| s = select(t).where(t.c.x == 5)
|
| print(s.compile(compile_kwargs={"literal_binds": True}))
|
| .. seealso::
|
| :ref:`faq_sql_expression_string`
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from CompilerElement:
|
| stringify_dialect = 'default'
|
| supports_execution = False
sqlalchemy.FLOAT
Python Library Documentation: class FLOAT in module sqlalchemy.sql.sqltypes
class FLOAT(Float)
| FLOAT(precision: 'Optional[int]' = None, asdecimal: 'bool' = False, decimal_return_scale: 'Optional[int]' = None)
|
| The SQL FLOAT type.
|
| .. seealso::
|
| :class:`_types.Float` - documentation for the base type.
|
| Method resolution order:
| FLOAT
| Float
| Numeric
| HasExpressionLookup
| sqlalchemy.sql.type_api.TypeEngineMixin
| sqlalchemy.sql.type_api.TypeEngine
| sqlalchemy.sql.visitors.Visitable
| typing.Generic
| builtins.object
|
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| __parameters__ = ()
|
| __visit_name__ = 'FLOAT'
|
| ----------------------------------------------------------------------
| Methods inherited from Float:
|
| __init__(self: 'Float[_N]', precision: 'Optional[int]' = None, asdecimal: 'bool' = False, decimal_return_scale: 'Optional[int]' = None)
| Construct a Float.
|
| :param precision: the numeric precision for use in DDL ``CREATE
| TABLE``. Backends **should** attempt to ensure this precision
| indicates a number of digits for the generic
| :class:`_sqltypes.Float` datatype.
|
| .. note:: For the Oracle Database backend, the
| :paramref:`_sqltypes.Float.precision` parameter is not accepted
| when rendering DDL, as Oracle Database does not support float precision
| specified as a number of decimal places. Instead, use the
| Oracle Database-specific :class:`_oracle.FLOAT` datatype and specify the
| :paramref:`_oracle.FLOAT.binary_precision` parameter. This is new
| in version 2.0 of SQLAlchemy.
|
| To create a database agnostic :class:`_types.Float` that
| separately specifies binary precision for Oracle Database, use
| :meth:`_types.TypeEngine.with_variant` as follows::
|
| from sqlalchemy import Column
| from sqlalchemy import Float
| from sqlalchemy.dialects import oracle
|
| Column(
| "float_data",
| Float(5).with_variant(oracle.FLOAT(binary_precision=16), "oracle"),
| )
|
| :param asdecimal: the same flag as that of :class:`.Numeric`, but
| defaults to ``False``. Note that setting this flag to ``True``
| results in floating point conversion.
|
| :param decimal_return_scale: Default scale to use when converting
| from floats to Python decimals. Floating point values will typically
| be much longer due to decimal inaccuracy, and most floating point
| database types don't have a notion of "scale", so by default the
| float type looks for the first ten decimal places when converting.
| Specifying this value will override that length. Note that the
| MySQL float types, which do include "scale", will use "scale"
| as the default for decimal_return_scale, if not otherwise specified.
|
| result_processor(self, dialect, coltype)
| Return a conversion function for processing result row values.
|
| Returns a callable which will receive a result row column
| value as the sole positional argument and will return a value
| to return to the user.
|
| If processing is not necessary, the method should return ``None``.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.result_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.result_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_result_value`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| :param dialect: Dialect instance in use.
|
| :param coltype: DBAPI coltype argument received in cursor.description.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from Float:
|
| scale = None
|
| ----------------------------------------------------------------------
| Methods inherited from Numeric:
|
| bind_processor(self, dialect)
| Return a conversion function for processing bind values.
|
| Returns a callable which will receive a bind parameter value
| as the sole positional argument and will return a value to
| send to the DB-API.
|
| If processing is not necessary, the method should return ``None``.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.bind_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.bind_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_bind_param`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
|
| :param dialect: Dialect instance in use.
|
| get_dbapi_type(self, dbapi)
| Return the corresponding type object from the underlying DB-API, if
| any.
|
| This can be useful for calling ``setinputsizes()``, for example.
|
| literal_processor(self, dialect)
| Return a conversion function for processing literal values that are
| to be rendered directly without using binds.
|
| This function is used when the compiler makes use of the
| "literal_binds" flag, typically used in DDL generation as well
| as in certain scenarios where backends don't accept bound parameters.
|
| Returns a callable which will receive a literal Python value
| as the sole positional argument and will return a string representation
| to be rendered in a SQL statement.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.literal_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.literal_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_literal_param`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| ----------------------------------------------------------------------
| Readonly properties inherited from Numeric:
|
| python_type
| Return the Python type object expected to be returned
| by instances of this type, if known.
|
| Basically, for those types which enforce a return type,
| or are known across the board to do such for all common
| DBAPIs (like ``int`` for example), will return that type.
|
| If a return type is not defined, raises
| ``NotImplementedError``.
|
| Note that any type also accommodates NULL in SQL which
| means you can also get back ``None`` from any type
| in practice.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from HasExpressionLookup:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from HasExpressionLookup:
|
| Comparator = <class 'sqlalchemy.sql.sqltypes.HasExpressionLookup.Compa...
|
| comparator_factory = <class 'sqlalchemy.sql.sqltypes.HasExpressionLook...
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.type_api.TypeEngine:
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| __str__(self) -> 'str'
| Return str(self).
|
| adapt(self, cls: 'Type[Union[TypeEngine[Any], TypeEngineMixin]]', **kw: 'Any') -> 'TypeEngine[Any]'
| Produce an "adapted" form of this type, given an "impl" class
| to work with.
|
| This method is used internally to associate generic
| types with "implementation" types that are specific to a particular
| dialect.
|
| as_generic(self, allow_nulltype: 'bool' = False) -> 'TypeEngine[_T]'
| Return an instance of the generic type corresponding to this type
| using heuristic rule. The method may be overridden if this
| heuristic rule is not sufficient.
|
| >>> from sqlalchemy.dialects.mysql import INTEGER
| >>> INTEGER(display_width=4).as_generic()
| Integer()
|
| >>> from sqlalchemy.dialects.mysql import NVARCHAR
| >>> NVARCHAR(length=100).as_generic()
| Unicode(length=100)
|
| .. versionadded:: 1.4.0b2
|
|
| .. seealso::
|
| :ref:`metadata_reflection_dbagnostic_types` - describes the
| use of :meth:`_types.TypeEngine.as_generic` in conjunction with
| the :meth:`_sql.DDLEvents.column_reflect` event, which is its
| intended use.
|
| bind_expression(self, bindvalue: 'BindParameter[_T]') -> 'Optional[ColumnElement[_T]]'
| Given a bind value (i.e. a :class:`.BindParameter` instance),
| return a SQL expression in its place.
|
| This is typically a SQL function that wraps the existing bound
| parameter within the statement. It is used for special data types
| that require literals being wrapped in some special database function
| in order to coerce an application-level value into a database-specific
| format. It is the SQL analogue of the
| :meth:`.TypeEngine.bind_processor` method.
|
| This method is called during the **SQL compilation** phase of a
| statement, when rendering a SQL string. It is **not** called
| against specific values.
|
| Note that this method, when implemented, should always return
| the exact same structure, without any conditional logic, as it
| may be used in an executemany() call against an arbitrary number
| of bound parameter sets.
|
| .. note::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.bind_expression`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.bind_expression`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.bind_expression`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| .. seealso::
|
| :ref:`types_sql_value_processing`
|
| coerce_compared_value(self, op: 'Optional[OperatorType]', value: 'Any') -> 'TypeEngine[Any]'
| Suggest a type for a 'coerced' Python value in an expression.
|
| Given an operator and value, gives the type a chance
| to return a type which the value should be coerced into.
|
| The default behavior here is conservative; if the right-hand
| side is already coerced into a SQL type based on its
| Python type, it is usually left alone.
|
| End-user functionality extension here should generally be via
| :class:`.TypeDecorator`, which provides more liberal behavior in that
| it defaults to coercing the other side of the expression into this
| type, thus applying special Python conversions above and beyond those
| needed by the DBAPI to both ides. It also provides the public method
| :meth:`.TypeDecorator.coerce_compared_value` which is intended for
| end-user customization of this behavior.
|
| column_expression(self, colexpr: 'ColumnElement[_T]') -> 'Optional[ColumnElement[_T]]'
| Given a SELECT column expression, return a wrapping SQL expression.
|
| This is typically a SQL function that wraps a column expression
| as rendered in the columns clause of a SELECT statement.
| It is used for special data types that require
| columns to be wrapped in some special database function in order
| to coerce the value before being sent back to the application.
| It is the SQL analogue of the :meth:`.TypeEngine.result_processor`
| method.
|
| .. note:: The :func:`.TypeEngine.column_expression` method is applied
| only to the **outermost columns clause** of a SELECT statement, that
| is, the columns that are to be delivered directly into the returned
| result rows. It does **not** apply to the columns clause inside
| of subqueries. This necessarily avoids double conversions against
| the column and only runs the conversion when ready to be returned
| to the client.
|
| This method is called during the **SQL compilation** phase of a
| statement, when rendering a SQL string. It is **not** called
| against specific values.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.column_expression`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.column_expression`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.column_expression`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
|
| .. seealso::
|
| :ref:`types_sql_value_processing`
|
| compare_values(self, x: 'Any', y: 'Any') -> 'bool'
| Compare two values for equality.
|
| compile(self, dialect: 'Optional[Dialect]' = None) -> 'str'
| Produce a string-compiled form of this :class:`.TypeEngine`.
|
| When called with no arguments, uses a "default" dialect
| to produce a string result.
|
| :param dialect: a :class:`.Dialect` instance.
|
| copy(self, **kw: 'Any') -> 'Self'
|
| copy_value(self, value: 'Any') -> 'Any'
|
| dialect_impl(self, dialect: 'Dialect') -> 'TypeEngine[_T]'
| Return a dialect-specific implementation for this
| :class:`.TypeEngine`.
|
| evaluates_none(self) -> 'Self'
| Return a copy of this type which has the
| :attr:`.should_evaluate_none` flag set to True.
|
| E.g.::
|
| Table(
| "some_table",
| metadata,
| Column(
| String(50).evaluates_none(),
| nullable=True,
| server_default="no value",
| ),
| )
|
| The ORM uses this flag to indicate that a positive value of ``None``
| is passed to the column in an INSERT statement, rather than omitting
| the column from the INSERT statement which has the effect of firing
| off column-level defaults. It also allows for types which have
| special behavior associated with the Python None value to indicate
| that the value doesn't necessarily translate into SQL NULL; a
| prime example of this is a JSON type which may wish to persist the
| JSON value ``'null'``.
|
| In all cases, the actual NULL SQL value can be always be
| persisted in any column by using
| the :obj:`_expression.null` SQL construct in an INSERT statement
| or associated with an ORM-mapped attribute.
|
| .. note::
|
| The "evaluates none" flag does **not** apply to a value
| of ``None`` passed to :paramref:`_schema.Column.default` or
| :paramref:`_schema.Column.server_default`; in these cases,
| ``None``
| still means "no default".
|
| .. seealso::
|
| :ref:`session_forcing_null` - in the ORM documentation
|
| :paramref:`.postgresql.JSON.none_as_null` - PostgreSQL JSON
| interaction with this flag.
|
| :attr:`.TypeEngine.should_evaluate_none` - class-level flag
|
| with_variant(self, type_: '_TypeEngineArgument[Any]', *dialect_names: 'str') -> 'Self'
| Produce a copy of this type object that will utilize the given
| type when applied to the dialect of the given name.
|
| e.g.::
|
| from sqlalchemy.types import String
| from sqlalchemy.dialects import mysql
|
| string_type = String()
|
| string_type = string_type.with_variant(
| mysql.VARCHAR(collation="foo"), "mysql", "mariadb"
| )
|
| The variant mapping indicates that when this type is
| interpreted by a specific dialect, it will instead be
| transmuted into the given type, rather than using the
| primary type.
|
| .. versionchanged:: 2.0 the :meth:`_types.TypeEngine.with_variant`
| method now works with a :class:`_types.TypeEngine` object "in
| place", returning a copy of the original type rather than returning
| a wrapping object; the ``Variant`` class is no longer used.
|
| :param type\_: a :class:`.TypeEngine` that will be selected
| as a variant from the originating type, when a dialect
| of the given name is in use.
| :param \*dialect_names: one or more base names of the dialect which
| uses this type. (i.e. ``'postgresql'``, ``'mysql'``, etc.)
|
| .. versionchanged:: 2.0 multiple dialect names can be specified
| for one variant.
|
| .. seealso::
|
| :ref:`types_with_variant` - illustrates the use of
| :meth:`_types.TypeEngine.with_variant`.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.type_api.TypeEngine:
|
| __orig_bases__ = (<class 'sqlalchemy.sql.visitors.Visitable'>, typing....
|
| hashable = True
|
| render_bind_cast = False
|
| render_literal_cast = False
|
| should_evaluate_none = False
|
| sort_key_function = None
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.visitors.Visitable:
|
| __class_getitem__(key: 'Any') -> 'Any'
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__() -> 'None'
| This method is called when a class is subclassed.
|
| The default implementation does nothing. It may be
| overridden to extend subclasses.
sqlalchemy.FallbackAsyncAdaptedQueuePool
Python Library Documentation: class FallbackAsyncAdaptedQueuePool in module sqlalchemy.pool.impl
class FallbackAsyncAdaptedQueuePool(AsyncAdaptedQueuePool)
| FallbackAsyncAdaptedQueuePool(creator: 'Union[_CreatorFnType, _CreatorWRecFnType]', pool_size: 'int' = 5, max_overflow: 'int' = 10, timeout: 'float' = 30.0, use_lifo: 'bool' = False, **kw: 'Any')
|
| Method resolution order:
| FallbackAsyncAdaptedQueuePool
| AsyncAdaptedQueuePool
| QueuePool
| sqlalchemy.pool.base.Pool
| sqlalchemy.log.Identified
| sqlalchemy.event.registry.EventTarget
| builtins.object
|
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| ----------------------------------------------------------------------
| Methods inherited from QueuePool:
|
| __init__(self, creator: 'Union[_CreatorFnType, _CreatorWRecFnType]', pool_size: 'int' = 5, max_overflow: 'int' = 10, timeout: 'float' = 30.0, use_lifo: 'bool' = False, **kw: 'Any')
| Construct a QueuePool.
|
| :param creator: a callable function that returns a DB-API
| connection object, same as that of :paramref:`_pool.Pool.creator`.
|
| :param pool_size: The size of the pool to be maintained,
| defaults to 5. This is the largest number of connections that
| will be kept persistently in the pool. Note that the pool
| begins with no connections; once this number of connections
| is requested, that number of connections will remain.
| ``pool_size`` can be set to 0 to indicate no size limit; to
| disable pooling, use a :class:`~sqlalchemy.pool.NullPool`
| instead.
|
| :param max_overflow: The maximum overflow size of the
| pool. When the number of checked-out connections reaches the
| size set in pool_size, additional connections will be
| returned up to this limit. When those additional connections
| are returned to the pool, they are disconnected and
| discarded. It follows then that the total number of
| simultaneous connections the pool will allow is pool_size +
| `max_overflow`, and the total number of "sleeping"
| connections the pool will allow is pool_size. `max_overflow`
| can be set to -1 to indicate no overflow limit; no limit
| will be placed on the total number of concurrent
| connections. Defaults to 10.
|
| :param timeout: The number of seconds to wait before giving up
| on returning a connection. Defaults to 30.0. This can be a float
| but is subject to the limitations of Python time functions which
| may not be reliable in the tens of milliseconds.
|
| :param use_lifo: use LIFO (last-in-first-out) when retrieving
| connections instead of FIFO (first-in-first-out). Using LIFO, a
| server-side timeout scheme can reduce the number of connections used
| during non-peak periods of use. When planning for server-side
| timeouts, ensure that a recycle or pre-ping strategy is in use to
| gracefully handle stale connections.
|
| .. versionadded:: 1.3
|
| .. seealso::
|
| :ref:`pool_use_lifo`
|
| :ref:`pool_disconnects`
|
| :param \**kw: Other keyword arguments including
| :paramref:`_pool.Pool.recycle`, :paramref:`_pool.Pool.echo`,
| :paramref:`_pool.Pool.reset_on_return` and others are passed to the
| :class:`_pool.Pool` constructor.
|
| checkedin(self) -> 'int'
|
| checkedout(self) -> 'int'
|
| dispose(self) -> 'None'
| Dispose of this pool.
|
| This method leaves the possibility of checked-out connections
| remaining open, as it only affects connections that are
| idle in the pool.
|
| .. seealso::
|
| :meth:`Pool.recreate`
|
| overflow(self) -> 'int'
|
| recreate(self) -> 'QueuePool'
| Return a new :class:`_pool.Pool`, of the same class as this one
| and configured with identical creation arguments.
|
| This method is used in conjunction with :meth:`dispose`
| to close out an entire :class:`_pool.Pool` and create a new one in
| its place.
|
| size(self) -> 'int'
|
| status(self) -> 'str'
| Returns a brief description of the state of this pool.
|
| timeout(self) -> 'float'
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.pool.base.Pool:
|
| connect(self) -> 'PoolProxiedConnection'
| Return a DBAPI connection from the pool.
|
| The connection is instrumented such that when its
| ``close()`` method is called, the connection will be returned to
| the pool.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from sqlalchemy.pool.base.Pool:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.pool.base.Pool:
|
| dispatch = <sqlalchemy.event.base.PoolEventsDispatch object>
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.log.Identified:
|
| logging_name = None
sqlalchemy.False_
Python Library Documentation: class False_ in module sqlalchemy.sql.elements
class False_(sqlalchemy.sql.base.SingletonConstant, sqlalchemy.sql.roles.ConstExprRole, ColumnElement)
| False_(*arg: 'Any', **kw: 'Any') -> '_T'
|
| Represent the ``false`` keyword, or equivalent, in a SQL statement.
|
| :class:`.False_` is accessed as a constant via the
| :func:`.false` function.
|
| Method resolution order:
| False_
| sqlalchemy.sql.base.SingletonConstant
| sqlalchemy.sql.base.Immutable
| sqlalchemy.sql.roles.ConstExprRole
| ColumnElement
| sqlalchemy.sql.roles.ColumnArgumentOrKeyRole
| sqlalchemy.sql.roles.ColumnArgumentRole
| sqlalchemy.sql.roles.StatementOptionRole
| sqlalchemy.sql.roles.WhereHavingRole
| sqlalchemy.sql.roles.OnClauseRole
| sqlalchemy.sql.roles.BinaryElementRole
| sqlalchemy.sql.roles.OrderByRole
| sqlalchemy.sql.roles.ColumnsClauseRole
| sqlalchemy.sql.roles.AllowsLambdaRole
| sqlalchemy.sql.roles.ByOfRole
| sqlalchemy.sql.roles.UsesInspection
| sqlalchemy.sql.roles.ColumnListRole
| sqlalchemy.sql.roles.LimitOffsetRole
| sqlalchemy.sql.roles.DMLColumnRole
| sqlalchemy.sql.roles.DDLConstraintColumnRole
| sqlalchemy.sql.roles.DDLExpressionRole
| sqlalchemy.sql.roles.StructuralRole
| SQLColumnExpression
| SQLCoreOperations
| sqlalchemy.sql.roles.ExpressionElementRole
| sqlalchemy.sql.roles.TypedColumnsClauseRole
| typing.Generic
| sqlalchemy.sql.operators.ColumnOperators
| sqlalchemy.sql.operators.Operators
| sqlalchemy.util.langhelpers.TypingOnly
| sqlalchemy.sql.roles.SQLRole
| DQLDMLClauseElement
| ClauseElement
| sqlalchemy.sql.annotation.SupportsWrappingAnnotations
| sqlalchemy.sql.annotation.SupportsAnnotations
| sqlalchemy.sql.cache_key.MemoizedHasCacheKey
| sqlalchemy.sql.cache_key.HasCacheKey
| sqlalchemy.util.langhelpers.HasMemoized
| sqlalchemy.sql.traversals.HasCopyInternals
| sqlalchemy.sql.visitors.ExternallyTraversible
| sqlalchemy.sql.visitors.HasTraverseInternals
| CompilerElement
| sqlalchemy.sql.visitors.Visitable
| builtins.object
|
| Methods defined here:
|
| type(...)
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'_singleton': 'False_', '_traverse_internals': '_Tr...
|
| __orig_bases__ = (<class 'sqlalchemy.sql.base.SingletonConstant'>, sql...
|
| __parameters__ = ()
|
| __visit_name__ = 'false'
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.base.SingletonConstant:
|
| proxy_set(...)
|
| ----------------------------------------------------------------------
| Static methods inherited from sqlalchemy.sql.base.SingletonConstant:
|
| __new__(cls: '_T', *arg: 'Any', **kw: 'Any') -> '_T'
| Create and return a new object. See help(type) for accurate signature.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from sqlalchemy.sql.base.SingletonConstant:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.base.Immutable:
|
| params(self, *optionaldict: 'Any', **kwargs: 'Any') -> 'NoReturn'
|
| unique_params(self, *optionaldict: 'Any', **kwargs: 'Any') -> 'NoReturn'
|
| ----------------------------------------------------------------------
| Methods inherited from ColumnElement:
|
| __getattr__(self, key: 'str') -> 'Any'
|
| __setstate__(self, state)
|
| base_columns(...)
|
| cast(self, type_: '_TypeEngineArgument[_OPT]') -> 'Cast[_OPT]'
| Produce a type cast, i.e. ``CAST(<expression> AS <type>)``.
|
| This is a shortcut to the :func:`_expression.cast` function.
|
| .. seealso::
|
| :ref:`tutorial_casts`
|
| :func:`_expression.cast`
|
| :func:`_expression.type_coerce`
|
| comparator(...)
|
| label(self, name: 'Optional[str]') -> 'Label[_T]'
| Produce a column label, i.e. ``<columnname> AS <name>``.
|
| This is a shortcut to the :func:`_expression.label` function.
|
| If 'name' is ``None``, an anonymous label name will be generated.
|
| operate(self, op: 'operators.OperatorType', *other: 'Any', **kwargs: 'Any') -> 'ColumnElement[Any]'
| Operate on an argument.
|
| This is the lowest level of operation, raises
| :class:`NotImplementedError` by default.
|
| Overriding this on a subclass can allow common
| behavior to be applied to all operations.
| For example, overriding :class:`.ColumnOperators`
| to apply ``func.lower()`` to the left and right
| side::
|
| class MyComparator(ColumnOperators):
| def operate(self, op, other, **kwargs):
| return op(func.lower(self), func.lower(other), **kwargs)
|
| :param op: Operator callable.
| :param \*other: the 'other' side of the operation. Will
| be a single scalar for most operations.
| :param \**kwargs: modifiers. These may be passed by special
| operators such as :meth:`ColumnOperators.contains`.
|
| reverse_operate(self, op: 'operators.OperatorType', other: 'Any', **kwargs: 'Any') -> 'ColumnElement[Any]'
| Reverse operate on an argument.
|
| Usage is the same as :meth:`operate`.
|
| self_group(self, against: 'Optional[OperatorType]' = None) -> 'ColumnElement[Any]'
| 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.
|
| shares_lineage(self, othercolumn: 'ColumnElement[Any]') -> 'bool'
| Return True if the given :class:`_expression.ColumnElement`
| has a common ancestor to this :class:`_expression.ColumnElement`.
|
| ----------------------------------------------------------------------
| Readonly properties inherited from ColumnElement:
|
| anon_key_label
| .. deprecated:: 1.4 The :attr:`_expression.ColumnElement.anon_key_label` attribute is now private, and the public accessor is deprecated.
|
| anon_label
| .. deprecated:: 1.4 The :attr:`_expression.ColumnElement.anon_label` attribute is now private, and the public accessor is deprecated.
|
| expression
| Return a column expression.
|
| Part of the inspection interface; returns self.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from ColumnElement:
|
| foreign_keys = frozenset()
|
| key = None
|
| primary_key = False
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.AllowsLambdaRole:
|
| allows_lambda = True
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.UsesInspection:
|
| uses_inspection = True
|
| ----------------------------------------------------------------------
| Class methods inherited from typing.Generic:
|
| __class_getitem__(...)
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__(...)
| Function to initialize subclasses.
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.operators.ColumnOperators:
|
| __add__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``+`` operator.
|
| In a column context, produces the clause ``a + b``
| if the parent object has non-string affinity.
| If the parent object has a string affinity,
| produces the concatenation operator, ``a || b`` -
| see :meth:`.ColumnOperators.concat`.
|
| __contains__(self, other: 'Any') -> 'ColumnOperators'
|
| __eq__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``==`` operator.
|
| In a column context, produces the clause ``a = b``.
| If the target is ``None``, produces ``a IS NULL``.
|
| __floordiv__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``//`` operator.
|
| In a column context, produces the clause ``a / b``,
| which is the same as "truediv", but considers the result
| type to be integer.
|
| .. versionadded:: 2.0
|
| __ge__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``>=`` operator.
|
| In a column context, produces the clause ``a >= b``.
|
| __getitem__(self, index: 'Any') -> 'ColumnOperators'
| Implement the [] operator.
|
| This can be used by some database-specific types
| such as PostgreSQL ARRAY and HSTORE.
|
| __gt__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``>`` operator.
|
| In a column context, produces the clause ``a > b``.
|
| __hash__(self, /) from builtins.object
| Return hash(self).
|
| __le__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``<=`` operator.
|
| In a column context, produces the clause ``a <= b``.
|
| __lshift__(self, other: 'Any') -> 'ColumnOperators'
| implement the << operator.
|
| Not used by SQLAlchemy core, this is provided
| for custom operator systems which want to use
| << as an extension point.
|
| __lt__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``<`` operator.
|
| In a column context, produces the clause ``a < b``.
|
| __mod__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``%`` operator.
|
| In a column context, produces the clause ``a % b``.
|
| __mul__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``*`` operator.
|
| In a column context, produces the clause ``a * b``.
|
| __ne__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``!=`` operator.
|
| In a column context, produces the clause ``a != b``.
| If the target is ``None``, produces ``a IS NOT NULL``.
|
| __neg__(self) -> 'ColumnOperators'
| Implement the ``-`` operator.
|
| In a column context, produces the clause ``-a``.
|
| __radd__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``+`` operator in reverse.
|
| See :meth:`.ColumnOperators.__add__`.
|
| __rfloordiv__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``//`` operator in reverse.
|
| See :meth:`.ColumnOperators.__floordiv__`.
|
| __rmod__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``%`` operator in reverse.
|
| See :meth:`.ColumnOperators.__mod__`.
|
| __rmul__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``*`` operator in reverse.
|
| See :meth:`.ColumnOperators.__mul__`.
|
| __rshift__(self, other: 'Any') -> 'ColumnOperators'
| implement the >> operator.
|
| Not used by SQLAlchemy core, this is provided
| for custom operator systems which want to use
| >> as an extension point.
|
| __rsub__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``-`` operator in reverse.
|
| See :meth:`.ColumnOperators.__sub__`.
|
| __rtruediv__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``/`` operator in reverse.
|
| See :meth:`.ColumnOperators.__truediv__`.
|
| __sub__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``-`` operator.
|
| In a column context, produces the clause ``a - b``.
|
| __truediv__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``/`` operator.
|
| In a column context, produces the clause ``a / b``, and
| considers the result type to be numeric.
|
| .. versionchanged:: 2.0 The truediv operator against two integers
| is now considered to return a numeric value. Behavior on specific
| backends may vary.
|
| all_(self) -> 'ColumnOperators'
| Produce an :func:`_expression.all_` clause against the
| parent object.
|
| See the documentation for :func:`_sql.all_` for examples.
|
| .. note:: be sure to not confuse the newer
| :meth:`_sql.ColumnOperators.all_` method with the **legacy**
| version of this method, the :meth:`_types.ARRAY.Comparator.all`
| method that's specific to :class:`_types.ARRAY`, which uses a
| different calling style.
|
| any_(self) -> 'ColumnOperators'
| Produce an :func:`_expression.any_` clause against the
| parent object.
|
| See the documentation for :func:`_sql.any_` for examples.
|
| .. note:: be sure to not confuse the newer
| :meth:`_sql.ColumnOperators.any_` method with the **legacy**
| version of this method, the :meth:`_types.ARRAY.Comparator.any`
| method that's specific to :class:`_types.ARRAY`, which uses a
| different calling style.
|
| asc(self) -> 'ColumnOperators'
| Produce a :func:`_expression.asc` clause against the
| parent object.
|
| between(self, cleft: 'Any', cright: 'Any', symmetric: 'bool' = False) -> 'ColumnOperators'
| Produce a :func:`_expression.between` clause against
| the parent object, given the lower and upper range.
|
| bitwise_and(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise AND operation, typically via the ``&``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_lshift(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise LSHIFT operation, typically via the ``<<``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_not(self) -> 'ColumnOperators'
| Produce a bitwise NOT operation, typically via the ``~``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_or(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise OR operation, typically via the ``|``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_rshift(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise RSHIFT operation, typically via the ``>>``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_xor(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise XOR operation, typically via the ``^``
| operator, or ``#`` for PostgreSQL.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| collate(self, collation: 'str') -> 'ColumnOperators'
| Produce a :func:`_expression.collate` clause against
| the parent object, given the collation string.
|
| .. seealso::
|
| :func:`_expression.collate`
|
| concat(self, other: 'Any') -> 'ColumnOperators'
| Implement the 'concat' operator.
|
| In a column context, produces the clause ``a || b``,
| or uses the ``concat()`` operator on MySQL.
|
| contains(self, other: 'Any', **kw: 'Any') -> 'ColumnOperators'
| Implement the 'contains' operator.
|
| Produces a LIKE expression that tests against a match for the middle
| of a string value:
|
| .. sourcecode:: sql
|
| column LIKE '%' || <other> || '%'
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.contains("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.contains.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.contains.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.contains.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.contains("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE '%' || :param || '%' ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.contains("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE '%' || :param || '%' ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.contains.autoescape`::
|
| somecolumn.contains("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.startswith`
|
| :meth:`.ColumnOperators.endswith`
|
| :meth:`.ColumnOperators.like`
|
| desc(self) -> 'ColumnOperators'
| Produce a :func:`_expression.desc` clause against the
| parent object.
|
| distinct(self) -> 'ColumnOperators'
| Produce a :func:`_expression.distinct` clause against the
| parent object.
|
| endswith(self, other: 'Any', escape: 'Optional[str]' = None, autoescape: 'bool' = False) -> 'ColumnOperators'
| Implement the 'endswith' operator.
|
| Produces a LIKE expression that tests against a match for the end
| of a string value:
|
| .. sourcecode:: sql
|
| column LIKE '%' || <other>
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.endswith("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.endswith.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.endswith.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.endswith.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.endswith("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE '%' || :param ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.endswith("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE '%' || :param ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.endswith.autoescape`::
|
| somecolumn.endswith("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.startswith`
|
| :meth:`.ColumnOperators.contains`
|
| :meth:`.ColumnOperators.like`
|
| icontains(self, other: 'Any', **kw: 'Any') -> 'ColumnOperators'
| Implement the ``icontains`` operator, e.g. case insensitive
| version of :meth:`.ColumnOperators.contains`.
|
| Produces a LIKE expression that tests against an insensitive match
| for the middle of a string value:
|
| .. sourcecode:: sql
|
| lower(column) LIKE '%' || lower(<other>) || '%'
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.icontains("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.icontains.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.icontains.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.icontains.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.icontains("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE '%' || lower(:param) || '%' ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.icontains("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE '%' || lower(:param) || '%' ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.contains.autoescape`::
|
| somecolumn.icontains("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.contains`
|
| iendswith(self, other: 'Any', escape: 'Optional[str]' = None, autoescape: 'bool' = False) -> 'ColumnOperators'
| Implement the ``iendswith`` operator, e.g. case insensitive
| version of :meth:`.ColumnOperators.endswith`.
|
| Produces a LIKE expression that tests against an insensitive match
| for the end of a string value:
|
| .. sourcecode:: sql
|
| lower(column) LIKE '%' || lower(<other>)
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.iendswith("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.iendswith.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.iendswith.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.iendswith.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.iendswith("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE '%' || lower(:param) ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.iendswith("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE '%' || lower(:param) ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.iendswith.autoescape`::
|
| somecolumn.endswith("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.endswith`
|
| ilike(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
| Implement the ``ilike`` operator, e.g. case insensitive LIKE.
|
| In a column context, produces an expression either of the form:
|
| .. sourcecode:: sql
|
| lower(a) LIKE lower(other)
|
| Or on backends that support the ILIKE operator:
|
| .. sourcecode:: sql
|
| a ILIKE other
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.ilike("%foobar%"))
|
| :param other: expression to be compared
| :param escape: optional escape character, renders the ``ESCAPE``
| keyword, e.g.::
|
| somecolumn.ilike("foo/%bar", escape="/")
|
| .. seealso::
|
| :meth:`.ColumnOperators.like`
|
| in_(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``in`` operator.
|
| In a column context, produces the clause ``column IN <other>``.
|
| The given parameter ``other`` may be:
|
| * A list of literal values,
| e.g.::
|
| stmt.where(column.in_([1, 2, 3]))
|
| In this calling form, the list of items is converted to a set of
| bound parameters the same length as the list given:
|
| .. sourcecode:: sql
|
| WHERE COL IN (?, ?, ?)
|
| * A list of tuples may be provided if the comparison is against a
| :func:`.tuple_` containing multiple expressions::
|
| from sqlalchemy import tuple_
|
| stmt.where(tuple_(col1, col2).in_([(1, 10), (2, 20), (3, 30)]))
|
| * An empty list,
| e.g.::
|
| stmt.where(column.in_([]))
|
| In this calling form, the expression renders an "empty set"
| expression. These expressions are tailored to individual backends
| and are generally trying to get an empty SELECT statement as a
| subquery. Such as on SQLite, the expression is:
|
| .. sourcecode:: sql
|
| WHERE col IN (SELECT 1 FROM (SELECT 1) WHERE 1!=1)
|
| .. versionchanged:: 1.4 empty IN expressions now use an
| execution-time generated SELECT subquery in all cases.
|
| * A bound parameter, e.g. :func:`.bindparam`, may be used if it
| includes the :paramref:`.bindparam.expanding` flag::
|
| stmt.where(column.in_(bindparam("value", expanding=True)))
|
| In this calling form, the expression renders a special non-SQL
| placeholder expression that looks like:
|
| .. sourcecode:: sql
|
| WHERE COL IN ([EXPANDING_value])
|
| This placeholder expression is intercepted at statement execution
| time to be converted into the variable number of bound parameter
| form illustrated earlier. If the statement were executed as::
|
| connection.execute(stmt, {"value": [1, 2, 3]})
|
| The database would be passed a bound parameter for each value:
|
| .. sourcecode:: sql
|
| WHERE COL IN (?, ?, ?)
|
| .. versionadded:: 1.2 added "expanding" bound parameters
|
| If an empty list is passed, a special "empty list" expression,
| which is specific to the database in use, is rendered. On
| SQLite this would be:
|
| .. sourcecode:: sql
|
| WHERE COL IN (SELECT 1 FROM (SELECT 1) WHERE 1!=1)
|
| .. versionadded:: 1.3 "expanding" bound parameters now support
| empty lists
|
| * a :func:`_expression.select` construct, which is usually a
| correlated scalar select::
|
| stmt.where(
| column.in_(select(othertable.c.y).where(table.c.x == othertable.c.x))
| )
|
| In this calling form, :meth:`.ColumnOperators.in_` renders as given:
|
| .. sourcecode:: sql
|
| WHERE COL IN (SELECT othertable.y
| FROM othertable WHERE othertable.x = table.x)
|
| :param other: a list of literals, a :func:`_expression.select`
| construct, or a :func:`.bindparam` construct that includes the
| :paramref:`.bindparam.expanding` flag set to True.
|
| is_(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``IS`` operator.
|
| Normally, ``IS`` is generated automatically when comparing to a
| value of ``None``, which resolves to ``NULL``. However, explicit
| usage of ``IS`` may be desirable if comparing to boolean values
| on certain platforms.
|
| .. seealso:: :meth:`.ColumnOperators.is_not`
|
| is_distinct_from(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``IS DISTINCT FROM`` operator.
|
| Renders "a IS DISTINCT FROM b" on most platforms;
| on some such as SQLite may render "a IS NOT b".
|
| is_not(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``IS NOT`` operator.
|
| Normally, ``IS NOT`` is generated automatically when comparing to a
| value of ``None``, which resolves to ``NULL``. However, explicit
| usage of ``IS NOT`` may be desirable if comparing to boolean values
| on certain platforms.
|
| .. versionchanged:: 1.4 The ``is_not()`` operator is renamed from
| ``isnot()`` in previous releases. The previous name remains
| available for backwards compatibility.
|
| .. seealso:: :meth:`.ColumnOperators.is_`
|
| is_not_distinct_from(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``IS NOT DISTINCT FROM`` operator.
|
| Renders "a IS NOT DISTINCT FROM b" on most platforms;
| on some such as SQLite may render "a IS b".
|
| .. versionchanged:: 1.4 The ``is_not_distinct_from()`` operator is
| renamed from ``isnot_distinct_from()`` in previous releases.
| The previous name remains available for backwards compatibility.
|
| isnot = is_not(self, other: 'Any') -> 'ColumnOperators'
|
| isnot_distinct_from = is_not_distinct_from(self, other: 'Any') -> 'ColumnOperators'
|
| istartswith(self, other: 'Any', escape: 'Optional[str]' = None, autoescape: 'bool' = False) -> 'ColumnOperators'
| Implement the ``istartswith`` operator, e.g. case insensitive
| version of :meth:`.ColumnOperators.startswith`.
|
| Produces a LIKE expression that tests against an insensitive
| match for the start of a string value:
|
| .. sourcecode:: sql
|
| lower(column) LIKE lower(<other>) || '%'
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.istartswith("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.istartswith.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.istartswith.escape` parameter will
| establish a given character as an escape character which can be of
| use when the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.istartswith.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.istartswith("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE lower(:param) || '%' ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.istartswith("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE lower(:param) || '%' ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.istartswith.autoescape`::
|
| somecolumn.istartswith("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.startswith`
|
| like(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
| Implement the ``like`` operator.
|
| In a column context, produces the expression:
|
| .. sourcecode:: sql
|
| a LIKE other
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.like("%foobar%"))
|
| :param other: expression to be compared
| :param escape: optional escape character, renders the ``ESCAPE``
| keyword, e.g.::
|
| somecolumn.like("foo/%bar", escape="/")
|
| .. seealso::
|
| :meth:`.ColumnOperators.ilike`
|
| match(self, other: 'Any', **kwargs: 'Any') -> 'ColumnOperators'
| Implements a database-specific 'match' operator.
|
| :meth:`_sql.ColumnOperators.match` attempts to resolve to
| a MATCH-like function or operator provided by the backend.
| Examples include:
|
| * PostgreSQL - renders ``x @@ plainto_tsquery(y)``
|
| .. versionchanged:: 2.0 ``plainto_tsquery()`` is used instead
| of ``to_tsquery()`` for PostgreSQL now; for compatibility with
| other forms, see :ref:`postgresql_match`.
|
|
| * MySQL - renders ``MATCH (x) AGAINST (y IN BOOLEAN MODE)``
|
| .. seealso::
|
| :class:`_mysql.match` - MySQL specific construct with
| additional features.
|
| * Oracle Database - renders ``CONTAINS(x, y)``
| * other backends may provide special implementations.
| * Backends without any special implementation will emit
| the operator as "MATCH". This is compatible with SQLite, for
| example.
|
| not_ilike(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
| implement the ``NOT ILIKE`` operator.
|
| This is equivalent to using negation with
| :meth:`.ColumnOperators.ilike`, i.e. ``~x.ilike(y)``.
|
| .. versionchanged:: 1.4 The ``not_ilike()`` operator is renamed from
| ``notilike()`` in previous releases. The previous name remains
| available for backwards compatibility.
|
| .. seealso::
|
| :meth:`.ColumnOperators.ilike`
|
| not_in(self, other: 'Any') -> 'ColumnOperators'
| implement the ``NOT IN`` operator.
|
| This is equivalent to using negation with
| :meth:`.ColumnOperators.in_`, i.e. ``~x.in_(y)``.
|
| In the case that ``other`` is an empty sequence, the compiler
| produces an "empty not in" expression. This defaults to the
| expression "1 = 1" to produce true in all cases. The
| :paramref:`_sa.create_engine.empty_in_strategy` may be used to
| alter this behavior.
|
| .. versionchanged:: 1.4 The ``not_in()`` operator is renamed from
| ``notin_()`` in previous releases. The previous name remains
| available for backwards compatibility.
|
| .. versionchanged:: 1.2 The :meth:`.ColumnOperators.in_` and
| :meth:`.ColumnOperators.not_in` operators
| now produce a "static" expression for an empty IN sequence
| by default.
|
| .. seealso::
|
| :meth:`.ColumnOperators.in_`
|
| not_like(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
| implement the ``NOT LIKE`` operator.
|
| This is equivalent to using negation with
| :meth:`.ColumnOperators.like`, i.e. ``~x.like(y)``.
|
| .. versionchanged:: 1.4 The ``not_like()`` operator is renamed from
| ``notlike()`` in previous releases. The previous name remains
| available for backwards compatibility.
|
| .. seealso::
|
| :meth:`.ColumnOperators.like`
|
| notilike = not_ilike(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
|
| notin_ = not_in(self, other: 'Any') -> 'ColumnOperators'
|
| notlike = not_like(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
|
| nulls_first(self) -> 'ColumnOperators'
| Produce a :func:`_expression.nulls_first` clause against the
| parent object.
|
| .. versionchanged:: 1.4 The ``nulls_first()`` operator is
| renamed from ``nullsfirst()`` in previous releases.
| The previous name remains available for backwards compatibility.
|
| nulls_last(self) -> 'ColumnOperators'
| Produce a :func:`_expression.nulls_last` clause against the
| parent object.
|
| .. versionchanged:: 1.4 The ``nulls_last()`` operator is
| renamed from ``nullslast()`` in previous releases.
| The previous name remains available for backwards compatibility.
|
| nullsfirst = nulls_first(self) -> 'ColumnOperators'
|
| nullslast = nulls_last(self) -> 'ColumnOperators'
|
| regexp_match(self, pattern: 'Any', flags: 'Optional[str]' = None) -> 'ColumnOperators'
| Implements a database-specific 'regexp match' operator.
|
| E.g.::
|
| stmt = select(table.c.some_column).where(
| table.c.some_column.regexp_match("^(b|c)")
| )
|
| :meth:`_sql.ColumnOperators.regexp_match` attempts to resolve to
| a REGEXP-like function or operator provided by the backend, however
| the specific regular expression syntax and flags available are
| **not backend agnostic**.
|
| Examples include:
|
| * PostgreSQL - renders ``x ~ y`` or ``x !~ y`` when negated.
| * Oracle Database - renders ``REGEXP_LIKE(x, y)``
| * SQLite - uses SQLite's ``REGEXP`` placeholder operator and calls into
| the Python ``re.match()`` builtin.
| * other backends may provide special implementations.
| * Backends without any special implementation will emit
| the operator as "REGEXP" or "NOT REGEXP". This is compatible with
| SQLite and MySQL, for example.
|
| Regular expression support is currently implemented for Oracle
| Database, PostgreSQL, MySQL and MariaDB. Partial support is available
| for SQLite. Support among third-party dialects may vary.
|
| :param pattern: The regular expression pattern string or column
| clause.
| :param flags: Any regular expression string flags to apply, passed as
| plain Python string only. These flags are backend specific.
| Some backends, like PostgreSQL and MariaDB, may alternatively
| specify the flags as part of the pattern.
| When using the ignore case flag 'i' in PostgreSQL, the ignore case
| regexp match operator ``~*`` or ``!~*`` will be used.
|
| .. versionadded:: 1.4
|
| .. versionchanged:: 1.4.48, 2.0.18 Note that due to an implementation
| error, the "flags" parameter previously accepted SQL expression
| objects such as column expressions in addition to plain Python
| strings. This implementation did not work correctly with caching
| and was removed; strings only should be passed for the "flags"
| parameter, as these flags are rendered as literal inline values
| within SQL expressions.
|
| .. seealso::
|
| :meth:`_sql.ColumnOperators.regexp_replace`
|
| regexp_replace(self, pattern: 'Any', replacement: 'Any', flags: 'Optional[str]' = None) -> 'ColumnOperators'
| Implements a database-specific 'regexp replace' operator.
|
| E.g.::
|
| stmt = select(
| table.c.some_column.regexp_replace("b(..)", "XY", flags="g")
| )
|
| :meth:`_sql.ColumnOperators.regexp_replace` attempts to resolve to
| a REGEXP_REPLACE-like function provided by the backend, that
| usually emit the function ``REGEXP_REPLACE()``. However,
| the specific regular expression syntax and flags available are
| **not backend agnostic**.
|
| Regular expression replacement support is currently implemented for
| Oracle Database, PostgreSQL, MySQL 8 or greater and MariaDB. Support
| among third-party dialects may vary.
|
| :param pattern: The regular expression pattern string or column
| clause.
| :param pattern: The replacement string or column clause.
| :param flags: Any regular expression string flags to apply, passed as
| plain Python string only. These flags are backend specific.
| Some backends, like PostgreSQL and MariaDB, may alternatively
| specify the flags as part of the pattern.
|
| .. versionadded:: 1.4
|
| .. versionchanged:: 1.4.48, 2.0.18 Note that due to an implementation
| error, the "flags" parameter previously accepted SQL expression
| objects such as column expressions in addition to plain Python
| strings. This implementation did not work correctly with caching
| and was removed; strings only should be passed for the "flags"
| parameter, as these flags are rendered as literal inline values
| within SQL expressions.
|
|
| .. seealso::
|
| :meth:`_sql.ColumnOperators.regexp_match`
|
| startswith(self, other: 'Any', escape: 'Optional[str]' = None, autoescape: 'bool' = False) -> 'ColumnOperators'
| Implement the ``startswith`` operator.
|
| Produces a LIKE expression that tests against a match for the start
| of a string value:
|
| .. sourcecode:: sql
|
| column LIKE <other> || '%'
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.startswith("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.startswith.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.startswith.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.startswith.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.startswith("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE :param || '%' ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.startswith("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE :param || '%' ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.startswith.autoescape`::
|
| somecolumn.startswith("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.endswith`
|
| :meth:`.ColumnOperators.contains`
|
| :meth:`.ColumnOperators.like`
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.operators.ColumnOperators:
|
| timetuple = None
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.operators.Operators:
|
| __and__(self, other: 'Any') -> 'Operators'
| Implement the ``&`` operator.
|
| When used with SQL expressions, results in an
| AND operation, equivalent to
| :func:`_expression.and_`, that is::
|
| a & b
|
| is equivalent to::
|
| from sqlalchemy import and_
|
| and_(a, b)
|
| Care should be taken when using ``&`` regarding
| operator precedence; the ``&`` operator has the highest precedence.
| The operands should be enclosed in parenthesis if they contain
| further sub expressions::
|
| (a == 2) & (b == 4)
|
| __invert__(self) -> 'Operators'
| Implement the ``~`` operator.
|
| When used with SQL expressions, results in a
| NOT operation, equivalent to
| :func:`_expression.not_`, that is::
|
| ~a
|
| is equivalent to::
|
| from sqlalchemy import not_
|
| not_(a)
|
| __or__(self, other: 'Any') -> 'Operators'
| Implement the ``|`` operator.
|
| When used with SQL expressions, results in an
| OR operation, equivalent to
| :func:`_expression.or_`, that is::
|
| a | b
|
| is equivalent to::
|
| from sqlalchemy import or_
|
| or_(a, b)
|
| Care should be taken when using ``|`` regarding
| operator precedence; the ``|`` operator has the highest precedence.
| The operands should be enclosed in parenthesis if they contain
| further sub expressions::
|
| (a == 2) | (b == 4)
|
| __sa_operate__ = operate(self, op: 'OperatorType', *other: 'Any', **kwargs: 'Any') -> 'Operators'
| Operate on an argument.
|
| This is the lowest level of operation, raises
| :class:`NotImplementedError` by default.
|
| Overriding this on a subclass can allow common
| behavior to be applied to all operations.
| For example, overriding :class:`.ColumnOperators`
| to apply ``func.lower()`` to the left and right
| side::
|
| class MyComparator(ColumnOperators):
| def operate(self, op, other, **kwargs):
| return op(func.lower(self), func.lower(other), **kwargs)
|
| :param op: Operator callable.
| :param \*other: the 'other' side of the operation. Will
| be a single scalar for most operations.
| :param \**kwargs: modifiers. These may be passed by special
| operators such as :meth:`ColumnOperators.contains`.
|
| bool_op(self, opstring: 'str', precedence: 'int' = 0, python_impl: 'Optional[Callable[..., Any]]' = None) -> 'Callable[[Any], Operators]'
| Return a custom boolean operator.
|
| This method is shorthand for calling
| :meth:`.Operators.op` and passing the
| :paramref:`.Operators.op.is_comparison`
| flag with True. A key advantage to using :meth:`.Operators.bool_op`
| is that when using column constructs, the "boolean" nature of the
| returned expression will be present for :pep:`484` purposes.
|
| .. seealso::
|
| :meth:`.Operators.op`
|
| op(self, opstring: 'str', precedence: 'int' = 0, is_comparison: 'bool' = False, return_type: 'Optional[Union[Type[TypeEngine[Any]], TypeEngine[Any]]]' = None, python_impl: 'Optional[Callable[..., Any]]' = None) -> 'Callable[[Any], Operators]'
| Produce a generic operator function.
|
| e.g.::
|
| somecolumn.op("*")(5)
|
| produces::
|
| somecolumn * 5
|
| This function can also be used to make bitwise operators explicit. For
| example::
|
| somecolumn.op("&")(0xFF)
|
| is a bitwise AND of the value in ``somecolumn``.
|
| :param opstring: a string which will be output as the infix operator
| between this element and the expression passed to the
| generated function.
|
| :param precedence: precedence which the database is expected to apply
| to the operator in SQL expressions. This integer value acts as a hint
| for the SQL compiler to know when explicit parenthesis should be
| rendered around a particular operation. A lower number will cause the
| expression to be parenthesized when applied against another operator
| with higher precedence. The default value of ``0`` is lower than all
| operators except for the comma (``,``) and ``AS`` operators. A value
| of 100 will be higher or equal to all operators, and -100 will be
| lower than or equal to all operators.
|
| .. seealso::
|
| :ref:`faq_sql_expression_op_parenthesis` - detailed description
| of how the SQLAlchemy SQL compiler renders parenthesis
|
| :param is_comparison: legacy; if True, the operator will be considered
| as a "comparison" operator, that is which evaluates to a boolean
| true/false value, like ``==``, ``>``, etc. This flag is provided
| so that ORM relationships can establish that the operator is a
| comparison operator when used in a custom join condition.
|
| Using the ``is_comparison`` parameter is superseded by using the
| :meth:`.Operators.bool_op` method instead; this more succinct
| operator sets this parameter automatically, but also provides
| correct :pep:`484` typing support as the returned object will
| express a "boolean" datatype, i.e. ``BinaryExpression[bool]``.
|
| :param return_type: a :class:`.TypeEngine` class or object that will
| force the return type of an expression produced by this operator
| to be of that type. By default, operators that specify
| :paramref:`.Operators.op.is_comparison` will resolve to
| :class:`.Boolean`, and those that do not will be of the same
| type as the left-hand operand.
|
| :param python_impl: an optional Python function that can evaluate
| two Python values in the same way as this operator works when
| run on the database server. Useful for in-Python SQL expression
| evaluation functions, such as for ORM hybrid attributes, and the
| ORM "evaluator" used to match objects in a session after a multi-row
| update or delete.
|
| e.g.::
|
| >>> expr = column("x").op("+", python_impl=lambda a, b: a + b)("y")
|
| The operator for the above expression will also work for non-SQL
| left and right objects::
|
| >>> expr.operator(5, 10)
| 15
|
| .. versionadded:: 2.0
|
|
| .. seealso::
|
| :meth:`.Operators.bool_op`
|
| :ref:`types_operators`
|
| :ref:`relationship_custom_operator`
|
| ----------------------------------------------------------------------
| Methods inherited from ClauseElement:
|
| __bool__(self)
|
| __getstate__(self)
| Helper for pickle.
|
| __repr__(self)
| Return repr(self).
|
| compare(self, other: 'ClauseElement', **kw: 'Any') -> 'bool'
| Compare this :class:`_expression.ClauseElement` to
| the given :class:`_expression.ClauseElement`.
|
| Subclasses should override the default behavior, which is a
| straight identity comparison.
|
| \**kw are arguments consumed by subclass ``compare()`` methods and
| may be used to modify the criteria for comparison
| (see :class:`_expression.ColumnElement`).
|
| description(...)
|
| entity_namespace(...)
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from ClauseElement:
|
| is_clause_element = True
|
| is_dml = False
|
| is_selectable = False
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.cache_key.HasCacheKey:
|
| inherit_cache = None
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_instancemethod(fn: '_F') -> '_F'
| Decorate a method memoize its return value.
|
| :meta private:
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_attribute = <class 'sqlalchemy.util.langhelpers.HasMemoized.m...
| A read-only @property that is only evaluated once.
|
| :meta private:
|
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.visitors.HasTraverseInternals:
|
| get_children(self, *, omit_attrs: 'Tuple[str, ...]' = (), **kw: 'Any') -> 'Iterable[HasTraverseInternals]'
| Return immediate child :class:`.visitors.HasTraverseInternals`
| elements of this :class:`.visitors.HasTraverseInternals`.
|
| This is used for visit traversal.
|
| \**kw may contain flags that change the collection that is
| returned, for example to return a subset of items in order to
| cut down on larger traversals, or to return child items from a
| different context (such as schema-level collections instead of
| clause-level).
|
| ----------------------------------------------------------------------
| Methods inherited from CompilerElement:
|
| __str__(self) -> 'str'
| Return str(self).
|
| compile(self, bind: 'Optional[_HasDialect]' = None, dialect: 'Optional[Dialect]' = None, **kw: 'Any') -> 'Compiled'
| Compile this SQL expression.
|
| The return value is a :class:`~.Compiled` object.
| Calling ``str()`` or ``unicode()`` on the returned value will yield a
| string representation of the result. The
| :class:`~.Compiled` object also can return a
| dictionary of bind parameter names and values
| using the ``params`` accessor.
|
| :param bind: An :class:`.Connection` or :class:`.Engine` which
| can provide a :class:`.Dialect` in order to generate a
| :class:`.Compiled` object. If the ``bind`` and
| ``dialect`` parameters are both omitted, a default SQL compiler
| is used.
|
| :param column_keys: Used for INSERT and UPDATE statements, a list of
| column names which should be present in the VALUES clause of the
| compiled statement. If ``None``, all columns from the target table
| object are rendered.
|
| :param dialect: A :class:`.Dialect` instance which can generate
| a :class:`.Compiled` object. This argument takes precedence over
| the ``bind`` argument.
|
| :param compile_kwargs: optional dictionary of additional parameters
| that will be passed through to the compiler within all "visit"
| methods. This allows any custom flag to be passed through to
| a custom compilation construct, for example. It is also used
| for the case of passing the ``literal_binds`` flag through::
|
| from sqlalchemy.sql import table, column, select
|
| t = table("t", column("x"))
|
| s = select(t).where(t.c.x == 5)
|
| print(s.compile(compile_kwargs={"literal_binds": True}))
|
| .. seealso::
|
| :ref:`faq_sql_expression_string`
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from CompilerElement:
|
| stringify_dialect = 'default'
|
| supports_execution = False
sqlalchemy.FetchedValue
Python Library Documentation: class FetchedValue in module sqlalchemy.sql.schema
class FetchedValue(sqlalchemy.sql.base.SchemaEventTarget)
| FetchedValue(for_update: 'bool' = False) -> 'None'
|
| A marker for a transparent database-side default.
|
| Use :class:`.FetchedValue` when the database is configured
| to provide some automatic default for a column.
|
| E.g.::
|
| Column("foo", Integer, FetchedValue())
|
| Would indicate that some trigger or default generator
| will create a new value for the ``foo`` column during an
| INSERT.
|
| .. seealso::
|
| :ref:`triggered_columns`
|
| Method resolution order:
| FetchedValue
| sqlalchemy.sql.base.SchemaEventTarget
| sqlalchemy.event.registry.EventTarget
| builtins.object
|
| Methods defined here:
|
| __init__(self, for_update: 'bool' = False) -> 'None'
| Initialize self. See help(type(self)) for accurate signature.
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'column': 'Optional[Column[Any]]'}
|
| has_argument = False
|
| is_clause_element = False
|
| is_identity = False
|
| is_server_default = True
|
| reflected = False
|
| ----------------------------------------------------------------------
| Data descriptors inherited from sqlalchemy.sql.base.SchemaEventTarget:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.base.SchemaEventTarget:
|
| dispatch = <sqlalchemy.event.base.DDLEventsDispatch object>
sqlalchemy.Float
Python Library Documentation: class Float in module sqlalchemy.sql.sqltypes
class Float(Numeric)
| Float(precision: 'Optional[int]' = None, asdecimal: 'bool' = False, decimal_return_scale: 'Optional[int]' = None)
|
| Type representing floating point types, such as ``FLOAT`` or ``REAL``.
|
| This type returns Python ``float`` objects by default, unless the
| :paramref:`.Float.asdecimal` flag is set to ``True``, in which case they
| are coerced to ``decimal.Decimal`` objects.
|
| When a :paramref:`.Float.precision` is not provided in a
| :class:`_types.Float` type some backend may compile this type as
| an 8 bytes / 64 bit float datatype. To use a 4 bytes / 32 bit float
| datatype a precision <= 24 can usually be provided or the
| :class:`_types.REAL` type can be used.
| This is known to be the case in the PostgreSQL and MSSQL dialects
| that render the type as ``FLOAT`` that's in both an alias of
| ``DOUBLE PRECISION``. Other third party dialects may have similar
| behavior.
|
| Method resolution order:
| Float
| Numeric
| HasExpressionLookup
| sqlalchemy.sql.type_api.TypeEngineMixin
| sqlalchemy.sql.type_api.TypeEngine
| sqlalchemy.sql.visitors.Visitable
| typing.Generic
| builtins.object
|
| Methods defined here:
|
| __init__(self: 'Float[_N]', precision: 'Optional[int]' = None, asdecimal: 'bool' = False, decimal_return_scale: 'Optional[int]' = None)
| Construct a Float.
|
| :param precision: the numeric precision for use in DDL ``CREATE
| TABLE``. Backends **should** attempt to ensure this precision
| indicates a number of digits for the generic
| :class:`_sqltypes.Float` datatype.
|
| .. note:: For the Oracle Database backend, the
| :paramref:`_sqltypes.Float.precision` parameter is not accepted
| when rendering DDL, as Oracle Database does not support float precision
| specified as a number of decimal places. Instead, use the
| Oracle Database-specific :class:`_oracle.FLOAT` datatype and specify the
| :paramref:`_oracle.FLOAT.binary_precision` parameter. This is new
| in version 2.0 of SQLAlchemy.
|
| To create a database agnostic :class:`_types.Float` that
| separately specifies binary precision for Oracle Database, use
| :meth:`_types.TypeEngine.with_variant` as follows::
|
| from sqlalchemy import Column
| from sqlalchemy import Float
| from sqlalchemy.dialects import oracle
|
| Column(
| "float_data",
| Float(5).with_variant(oracle.FLOAT(binary_precision=16), "oracle"),
| )
|
| :param asdecimal: the same flag as that of :class:`.Numeric`, but
| defaults to ``False``. Note that setting this flag to ``True``
| results in floating point conversion.
|
| :param decimal_return_scale: Default scale to use when converting
| from floats to Python decimals. Floating point values will typically
| be much longer due to decimal inaccuracy, and most floating point
| database types don't have a notion of "scale", so by default the
| float type looks for the first ten decimal places when converting.
| Specifying this value will override that length. Note that the
| MySQL float types, which do include "scale", will use "scale"
| as the default for decimal_return_scale, if not otherwise specified.
|
| result_processor(self, dialect, coltype)
| Return a conversion function for processing result row values.
|
| Returns a callable which will receive a result row column
| value as the sole positional argument and will return a value
| to return to the user.
|
| If processing is not necessary, the method should return ``None``.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.result_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.result_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_result_value`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| :param dialect: Dialect instance in use.
|
| :param coltype: DBAPI coltype argument received in cursor.description.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| __parameters__ = ()
|
| __visit_name__ = 'float'
|
| scale = None
|
| ----------------------------------------------------------------------
| Methods inherited from Numeric:
|
| bind_processor(self, dialect)
| Return a conversion function for processing bind values.
|
| Returns a callable which will receive a bind parameter value
| as the sole positional argument and will return a value to
| send to the DB-API.
|
| If processing is not necessary, the method should return ``None``.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.bind_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.bind_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_bind_param`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
|
| :param dialect: Dialect instance in use.
|
| get_dbapi_type(self, dbapi)
| Return the corresponding type object from the underlying DB-API, if
| any.
|
| This can be useful for calling ``setinputsizes()``, for example.
|
| literal_processor(self, dialect)
| Return a conversion function for processing literal values that are
| to be rendered directly without using binds.
|
| This function is used when the compiler makes use of the
| "literal_binds" flag, typically used in DDL generation as well
| as in certain scenarios where backends don't accept bound parameters.
|
| Returns a callable which will receive a literal Python value
| as the sole positional argument and will return a string representation
| to be rendered in a SQL statement.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.literal_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.literal_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_literal_param`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| ----------------------------------------------------------------------
| Readonly properties inherited from Numeric:
|
| python_type
| Return the Python type object expected to be returned
| by instances of this type, if known.
|
| Basically, for those types which enforce a return type,
| or are known across the board to do such for all common
| DBAPIs (like ``int`` for example), will return that type.
|
| If a return type is not defined, raises
| ``NotImplementedError``.
|
| Note that any type also accommodates NULL in SQL which
| means you can also get back ``None`` from any type
| in practice.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from HasExpressionLookup:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from HasExpressionLookup:
|
| Comparator = <class 'sqlalchemy.sql.sqltypes.HasExpressionLookup.Compa...
|
| comparator_factory = <class 'sqlalchemy.sql.sqltypes.HasExpressionLook...
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.type_api.TypeEngine:
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| __str__(self) -> 'str'
| Return str(self).
|
| adapt(self, cls: 'Type[Union[TypeEngine[Any], TypeEngineMixin]]', **kw: 'Any') -> 'TypeEngine[Any]'
| Produce an "adapted" form of this type, given an "impl" class
| to work with.
|
| This method is used internally to associate generic
| types with "implementation" types that are specific to a particular
| dialect.
|
| as_generic(self, allow_nulltype: 'bool' = False) -> 'TypeEngine[_T]'
| Return an instance of the generic type corresponding to this type
| using heuristic rule. The method may be overridden if this
| heuristic rule is not sufficient.
|
| >>> from sqlalchemy.dialects.mysql import INTEGER
| >>> INTEGER(display_width=4).as_generic()
| Integer()
|
| >>> from sqlalchemy.dialects.mysql import NVARCHAR
| >>> NVARCHAR(length=100).as_generic()
| Unicode(length=100)
|
| .. versionadded:: 1.4.0b2
|
|
| .. seealso::
|
| :ref:`metadata_reflection_dbagnostic_types` - describes the
| use of :meth:`_types.TypeEngine.as_generic` in conjunction with
| the :meth:`_sql.DDLEvents.column_reflect` event, which is its
| intended use.
|
| bind_expression(self, bindvalue: 'BindParameter[_T]') -> 'Optional[ColumnElement[_T]]'
| Given a bind value (i.e. a :class:`.BindParameter` instance),
| return a SQL expression in its place.
|
| This is typically a SQL function that wraps the existing bound
| parameter within the statement. It is used for special data types
| that require literals being wrapped in some special database function
| in order to coerce an application-level value into a database-specific
| format. It is the SQL analogue of the
| :meth:`.TypeEngine.bind_processor` method.
|
| This method is called during the **SQL compilation** phase of a
| statement, when rendering a SQL string. It is **not** called
| against specific values.
|
| Note that this method, when implemented, should always return
| the exact same structure, without any conditional logic, as it
| may be used in an executemany() call against an arbitrary number
| of bound parameter sets.
|
| .. note::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.bind_expression`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.bind_expression`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.bind_expression`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| .. seealso::
|
| :ref:`types_sql_value_processing`
|
| coerce_compared_value(self, op: 'Optional[OperatorType]', value: 'Any') -> 'TypeEngine[Any]'
| Suggest a type for a 'coerced' Python value in an expression.
|
| Given an operator and value, gives the type a chance
| to return a type which the value should be coerced into.
|
| The default behavior here is conservative; if the right-hand
| side is already coerced into a SQL type based on its
| Python type, it is usually left alone.
|
| End-user functionality extension here should generally be via
| :class:`.TypeDecorator`, which provides more liberal behavior in that
| it defaults to coercing the other side of the expression into this
| type, thus applying special Python conversions above and beyond those
| needed by the DBAPI to both ides. It also provides the public method
| :meth:`.TypeDecorator.coerce_compared_value` which is intended for
| end-user customization of this behavior.
|
| column_expression(self, colexpr: 'ColumnElement[_T]') -> 'Optional[ColumnElement[_T]]'
| Given a SELECT column expression, return a wrapping SQL expression.
|
| This is typically a SQL function that wraps a column expression
| as rendered in the columns clause of a SELECT statement.
| It is used for special data types that require
| columns to be wrapped in some special database function in order
| to coerce the value before being sent back to the application.
| It is the SQL analogue of the :meth:`.TypeEngine.result_processor`
| method.
|
| .. note:: The :func:`.TypeEngine.column_expression` method is applied
| only to the **outermost columns clause** of a SELECT statement, that
| is, the columns that are to be delivered directly into the returned
| result rows. It does **not** apply to the columns clause inside
| of subqueries. This necessarily avoids double conversions against
| the column and only runs the conversion when ready to be returned
| to the client.
|
| This method is called during the **SQL compilation** phase of a
| statement, when rendering a SQL string. It is **not** called
| against specific values.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.column_expression`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.column_expression`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.column_expression`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
|
| .. seealso::
|
| :ref:`types_sql_value_processing`
|
| compare_values(self, x: 'Any', y: 'Any') -> 'bool'
| Compare two values for equality.
|
| compile(self, dialect: 'Optional[Dialect]' = None) -> 'str'
| Produce a string-compiled form of this :class:`.TypeEngine`.
|
| When called with no arguments, uses a "default" dialect
| to produce a string result.
|
| :param dialect: a :class:`.Dialect` instance.
|
| copy(self, **kw: 'Any') -> 'Self'
|
| copy_value(self, value: 'Any') -> 'Any'
|
| dialect_impl(self, dialect: 'Dialect') -> 'TypeEngine[_T]'
| Return a dialect-specific implementation for this
| :class:`.TypeEngine`.
|
| evaluates_none(self) -> 'Self'
| Return a copy of this type which has the
| :attr:`.should_evaluate_none` flag set to True.
|
| E.g.::
|
| Table(
| "some_table",
| metadata,
| Column(
| String(50).evaluates_none(),
| nullable=True,
| server_default="no value",
| ),
| )
|
| The ORM uses this flag to indicate that a positive value of ``None``
| is passed to the column in an INSERT statement, rather than omitting
| the column from the INSERT statement which has the effect of firing
| off column-level defaults. It also allows for types which have
| special behavior associated with the Python None value to indicate
| that the value doesn't necessarily translate into SQL NULL; a
| prime example of this is a JSON type which may wish to persist the
| JSON value ``'null'``.
|
| In all cases, the actual NULL SQL value can be always be
| persisted in any column by using
| the :obj:`_expression.null` SQL construct in an INSERT statement
| or associated with an ORM-mapped attribute.
|
| .. note::
|
| The "evaluates none" flag does **not** apply to a value
| of ``None`` passed to :paramref:`_schema.Column.default` or
| :paramref:`_schema.Column.server_default`; in these cases,
| ``None``
| still means "no default".
|
| .. seealso::
|
| :ref:`session_forcing_null` - in the ORM documentation
|
| :paramref:`.postgresql.JSON.none_as_null` - PostgreSQL JSON
| interaction with this flag.
|
| :attr:`.TypeEngine.should_evaluate_none` - class-level flag
|
| with_variant(self, type_: '_TypeEngineArgument[Any]', *dialect_names: 'str') -> 'Self'
| Produce a copy of this type object that will utilize the given
| type when applied to the dialect of the given name.
|
| e.g.::
|
| from sqlalchemy.types import String
| from sqlalchemy.dialects import mysql
|
| string_type = String()
|
| string_type = string_type.with_variant(
| mysql.VARCHAR(collation="foo"), "mysql", "mariadb"
| )
|
| The variant mapping indicates that when this type is
| interpreted by a specific dialect, it will instead be
| transmuted into the given type, rather than using the
| primary type.
|
| .. versionchanged:: 2.0 the :meth:`_types.TypeEngine.with_variant`
| method now works with a :class:`_types.TypeEngine` object "in
| place", returning a copy of the original type rather than returning
| a wrapping object; the ``Variant`` class is no longer used.
|
| :param type\_: a :class:`.TypeEngine` that will be selected
| as a variant from the originating type, when a dialect
| of the given name is in use.
| :param \*dialect_names: one or more base names of the dialect which
| uses this type. (i.e. ``'postgresql'``, ``'mysql'``, etc.)
|
| .. versionchanged:: 2.0 multiple dialect names can be specified
| for one variant.
|
| .. seealso::
|
| :ref:`types_with_variant` - illustrates the use of
| :meth:`_types.TypeEngine.with_variant`.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.type_api.TypeEngine:
|
| __orig_bases__ = (<class 'sqlalchemy.sql.visitors.Visitable'>, typing....
|
| hashable = True
|
| render_bind_cast = False
|
| render_literal_cast = False
|
| should_evaluate_none = False
|
| sort_key_function = None
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.visitors.Visitable:
|
| __class_getitem__(key: 'Any') -> 'Any'
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__() -> 'None'
| This method is called when a class is subclassed.
|
| The default implementation does nothing. It may be
| overridden to extend subclasses.
sqlalchemy.ForeignKey
Python Library Documentation: class ForeignKey in module sqlalchemy.sql.schema
class ForeignKey(sqlalchemy.sql.base.DialectKWArgs, SchemaItem)
| ForeignKey(column: '_DDLColumnArgument', _constraint: 'Optional[ForeignKeyConstraint]' = None, use_alter: 'bool' = False, name: '_ConstraintNameArgument' = None, onupdate: 'Optional[str]' = None, ondelete: 'Optional[str]' = None, deferrable: 'Optional[bool]' = None, initially: 'Optional[str]' = None, link_to_name: 'bool' = False, match: 'Optional[str]' = None, info: 'Optional[_InfoType]' = None, comment: 'Optional[str]' = None, _unresolvable: 'bool' = False, **dialect_kw: 'Any')
|
| Defines a dependency between two columns.
|
| ``ForeignKey`` is specified as an argument to a :class:`_schema.Column`
| object,
| e.g.::
|
| t = Table(
| "remote_table",
| metadata,
| Column("remote_id", ForeignKey("main_table.id")),
| )
|
| Note that ``ForeignKey`` is only a marker object that defines
| a dependency between two columns. The actual constraint
| is in all cases represented by the :class:`_schema.ForeignKeyConstraint`
| object. This object will be generated automatically when
| a ``ForeignKey`` is associated with a :class:`_schema.Column` which
| in turn is associated with a :class:`_schema.Table`. Conversely,
| when :class:`_schema.ForeignKeyConstraint` is applied to a
| :class:`_schema.Table`,
| ``ForeignKey`` markers are automatically generated to be
| present on each associated :class:`_schema.Column`, which are also
| associated with the constraint object.
|
| Note that you cannot define a "composite" foreign key constraint,
| that is a constraint between a grouping of multiple parent/child
| columns, using ``ForeignKey`` objects. To define this grouping,
| the :class:`_schema.ForeignKeyConstraint` object must be used, and applied
| to the :class:`_schema.Table`. The associated ``ForeignKey`` objects
| are created automatically.
|
| The ``ForeignKey`` objects associated with an individual
| :class:`_schema.Column`
| object are available in the `foreign_keys` collection
| of that column.
|
| Further examples of foreign key configuration are in
| :ref:`metadata_foreignkeys`.
|
| Method resolution order:
| ForeignKey
| sqlalchemy.sql.base.DialectKWArgs
| SchemaItem
| sqlalchemy.sql.base.SchemaVisitable
| sqlalchemy.sql.base.SchemaEventTarget
| sqlalchemy.event.registry.EventTarget
| sqlalchemy.sql.visitors.Visitable
| builtins.object
|
| Methods defined here:
|
| __init__(self, column: '_DDLColumnArgument', _constraint: 'Optional[ForeignKeyConstraint]' = None, use_alter: 'bool' = False, name: '_ConstraintNameArgument' = None, onupdate: 'Optional[str]' = None, ondelete: 'Optional[str]' = None, deferrable: 'Optional[bool]' = None, initially: 'Optional[str]' = None, link_to_name: 'bool' = False, match: 'Optional[str]' = None, info: 'Optional[_InfoType]' = None, comment: 'Optional[str]' = None, _unresolvable: 'bool' = False, **dialect_kw: 'Any')
| Construct a column-level FOREIGN KEY.
|
| The :class:`_schema.ForeignKey` object when constructed generates a
| :class:`_schema.ForeignKeyConstraint`
| which is associated with the parent
| :class:`_schema.Table` object's collection of constraints.
|
| :param column: A single target column for the key relationship. A
| :class:`_schema.Column` object or a column name as a string:
| ``tablename.columnkey`` or ``schema.tablename.columnkey``.
| ``columnkey`` is the ``key`` which has been assigned to the column
| (defaults to the column name itself), unless ``link_to_name`` is
| ``True`` in which case the rendered name of the column is used.
|
| :param name: Optional string. An in-database name for the key if
| `constraint` is not provided.
|
| :param onupdate: Optional string. If set, emit ON UPDATE <value> when
| issuing DDL for this constraint. Typical values include CASCADE,
| DELETE and RESTRICT.
|
| .. seealso::
|
| :ref:`on_update_on_delete`
|
| :param ondelete: Optional string. If set, emit ON DELETE <value> when
| issuing DDL for this constraint. Typical values include CASCADE,
| SET NULL and RESTRICT. Some dialects may allow for additional
| syntaxes.
|
| .. seealso::
|
| :ref:`on_update_on_delete`
|
| :param deferrable: Optional bool. If set, emit DEFERRABLE or NOT
| DEFERRABLE when issuing DDL for this constraint.
|
| :param initially: Optional string. If set, emit INITIALLY <value> when
| issuing DDL for this constraint.
|
| :param link_to_name: if True, the string name given in ``column`` is
| the rendered name of the referenced column, not its locally
| assigned ``key``.
|
| :param use_alter: passed to the underlying
| :class:`_schema.ForeignKeyConstraint`
| to indicate the constraint should
| be generated/dropped externally from the CREATE TABLE/ DROP TABLE
| statement. See :paramref:`_schema.ForeignKeyConstraint.use_alter`
| for further description.
|
| .. seealso::
|
| :paramref:`_schema.ForeignKeyConstraint.use_alter`
|
| :ref:`use_alter`
|
| :param match: Optional string. If set, emit MATCH <value> when issuing
| DDL for this constraint. Typical values include SIMPLE, PARTIAL
| and FULL.
|
| :param info: Optional data dictionary which will be populated into the
| :attr:`.SchemaItem.info` attribute of this object.
|
| :param comment: Optional string that will render an SQL comment on
| foreign key constraint creation.
|
| .. versionadded:: 2.0
|
| :param \**dialect_kw: Additional keyword arguments are dialect
| specific, and passed in the form ``<dialectname>_<argname>``. The
| arguments are ultimately handled by a corresponding
| :class:`_schema.ForeignKeyConstraint`.
| See the documentation regarding
| an individual dialect at :ref:`dialect_toplevel` for detail on
| documented arguments.
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| column(...)
| Return the target :class:`_schema.Column` referenced by this
| :class:`_schema.ForeignKey`.
|
| If no target column has been established, an exception
| is raised.
|
| copy(self, *, schema: 'Optional[str]' = None, **kw: 'Any') -> 'ForeignKey'
| .. deprecated:: 1.4 The :meth:`_schema.ForeignKey.copy` method is deprecated and will be removed in a future release.
|
| get_referent(self, table: 'FromClause') -> 'Optional[Column[Any]]'
| Return the :class:`_schema.Column` in the given
| :class:`_schema.Table` (or any :class:`.FromClause`)
| referenced by this :class:`_schema.ForeignKey`.
|
| Returns None if this :class:`_schema.ForeignKey`
| does not reference the given
| :class:`_schema.Table`.
|
| references(self, table: 'Table') -> 'bool'
| Return True if the given :class:`_schema.Table`
| is referenced by this
| :class:`_schema.ForeignKey`.
|
| ----------------------------------------------------------------------
| Readonly properties defined here:
|
| target_fullname
| Return a string based 'column specification' for this
| :class:`_schema.ForeignKey`.
|
| This is usually the equivalent of the string-based "tablename.colname"
| argument first passed to the object's constructor.
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'_table_column': 'Optional[Column[Any]]', 'parent':...
|
| __visit_name__ = 'foreign_key'
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.base.DialectKWArgs:
|
| dialect_options(...)
| A collection of keyword arguments specified as dialect-specific
| options to this construct.
|
| This is a two-level nested registry, keyed to ``<dialect_name>``
| and ``<argument_name>``. For example, the ``postgresql_where``
| argument would be locatable as::
|
| arg = my_object.dialect_options["postgresql"]["where"]
|
| .. versionadded:: 0.9.2
|
| .. seealso::
|
| :attr:`.DialectKWArgs.dialect_kwargs` - flat dictionary form
|
| get_dialect_option(self, dialect: 'Dialect', argument_name: 'str', *, else_: 'Any' = None, deprecated_fallback: 'Optional[str]' = None) -> 'Any'
| Return the value of a dialect-specific option, or *else_* if
| this dialect does not register the given argument.
|
| This is useful for DDL compilers that may be inherited by
| third-party dialects whose ``construct_arguments`` do not
| include the same set of keys as the parent dialect.
|
| :param dialect: The dialect for which to retrieve the option.
| :param argument_name: The name of the argument to retrieve.
| :param else\_: The value to return if the argument is not present.
| :param deprecated_fallback: Optional dialect name to fall back to
| if the argument is not present for the current dialect. If the
| argument is present for the fallback dialect but not the current
| dialect, a deprecation warning will be emitted.
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.base.DialectKWArgs:
|
| argument_for(dialect_name: 'str', argument_name: 'str', default: 'Any') -> 'None'
| Add a new kind of dialect-specific keyword argument for this class.
|
| E.g.::
|
| Index.argument_for("mydialect", "length", None)
|
| some_index = Index("a", "b", mydialect_length=5)
|
| The :meth:`.DialectKWArgs.argument_for` method is a per-argument
| way adding extra arguments to the
| :attr:`.DefaultDialect.construct_arguments` dictionary. This
| dictionary provides a list of argument names accepted by various
| schema-level constructs on behalf of a dialect.
|
| New dialects should typically specify this dictionary all at once as a
| data member of the dialect class. The use case for ad-hoc addition of
| argument names is typically for end-user code that is also using
| a custom compilation scheme which consumes the additional arguments.
|
| :param dialect_name: name of a dialect. The dialect must be
| locatable, else a :class:`.NoSuchModuleError` is raised. The
| dialect must also include an existing
| :attr:`.DefaultDialect.construct_arguments` collection, indicating
| that it participates in the keyword-argument validation and default
| system, else :class:`.ArgumentError` is raised. If the dialect does
| not include this collection, then any keyword argument can be
| specified on behalf of this dialect already. All dialects packaged
| within SQLAlchemy include this collection, however for third party
| dialects, support may vary.
|
| :param argument_name: name of the parameter.
|
| :param default: default value of the parameter.
|
| ----------------------------------------------------------------------
| Readonly properties inherited from sqlalchemy.sql.base.DialectKWArgs:
|
| dialect_kwargs
| A collection of keyword arguments specified as dialect-specific
| options to this construct.
|
| The arguments are present here in their original ``<dialect>_<kwarg>``
| format. Only arguments that were actually passed are included;
| unlike the :attr:`.DialectKWArgs.dialect_options` collection, which
| contains all options known by this dialect including defaults.
|
| The collection is also writable; keys are accepted of the
| form ``<dialect>_<kwarg>`` where the value will be assembled
| into the list of options.
|
| .. seealso::
|
| :attr:`.DialectKWArgs.dialect_options` - nested dictionary form
|
| kwargs
| A synonym for :attr:`.DialectKWArgs.dialect_kwargs`.
|
| ----------------------------------------------------------------------
| Methods inherited from SchemaItem:
|
| info(...)
| Info dictionary associated with the object, allowing user-defined
| data to be associated with this :class:`.SchemaItem`.
|
| The dictionary is automatically generated when first accessed.
| It can also be specified in the constructor of some objects,
| such as :class:`_schema.Table` and :class:`_schema.Column`.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from SchemaItem:
|
| create_drop_stringify_dialect = 'default'
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.base.SchemaEventTarget:
|
| dispatch = <sqlalchemy.event.base.DDLEventsDispatch object>
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.visitors.Visitable:
|
| __class_getitem__(key: 'Any') -> 'Any'
|
| __init_subclass__() -> 'None'
| This method is called when a class is subclassed.
|
| The default implementation does nothing. It may be
| overridden to extend subclasses.
sqlalchemy.ForeignKeyConstraint
Python Library Documentation: class ForeignKeyConstraint in module sqlalchemy.sql.schema
class ForeignKeyConstraint(ColumnCollectionConstraint)
| ForeignKeyConstraint(columns: '_typing_Sequence[_DDLColumnArgument]', refcolumns: '_typing_Sequence[_DDLColumnArgument]', name: '_ConstraintNameArgument' = None, onupdate: 'Optional[str]' = None, ondelete: 'Optional[str]' = None, deferrable: 'Optional[bool]' = None, initially: 'Optional[str]' = None, use_alter: 'bool' = False, link_to_name: 'bool' = False, match: 'Optional[str]' = None, table: 'Optional[Table]' = None, info: 'Optional[_InfoType]' = None, comment: 'Optional[str]' = None, **dialect_kw: 'Any') -> 'None'
|
| A table-level FOREIGN KEY constraint.
|
| Defines a single column or composite FOREIGN KEY ... REFERENCES
| constraint. For a no-frills, single column foreign key, adding a
| :class:`_schema.ForeignKey` to the definition of a :class:`_schema.Column`
| is a
| shorthand equivalent for an unnamed, single column
| :class:`_schema.ForeignKeyConstraint`.
|
| Examples of foreign key configuration are in :ref:`metadata_foreignkeys`.
|
| Method resolution order:
| ForeignKeyConstraint
| ColumnCollectionConstraint
| ColumnCollectionMixin
| Constraint
| sqlalchemy.sql.base.DialectKWArgs
| HasConditionalDDL
| SchemaItem
| sqlalchemy.sql.base.SchemaVisitable
| sqlalchemy.sql.base.SchemaEventTarget
| sqlalchemy.event.registry.EventTarget
| sqlalchemy.sql.visitors.Visitable
| builtins.object
|
| Methods defined here:
|
| __init__(self, columns: '_typing_Sequence[_DDLColumnArgument]', refcolumns: '_typing_Sequence[_DDLColumnArgument]', name: '_ConstraintNameArgument' = None, onupdate: 'Optional[str]' = None, ondelete: 'Optional[str]' = None, deferrable: 'Optional[bool]' = None, initially: 'Optional[str]' = None, use_alter: 'bool' = False, link_to_name: 'bool' = False, match: 'Optional[str]' = None, table: 'Optional[Table]' = None, info: 'Optional[_InfoType]' = None, comment: 'Optional[str]' = None, **dialect_kw: 'Any') -> 'None'
| Construct a composite-capable FOREIGN KEY.
|
| :param columns: A sequence of local column names. The named columns
| must be defined and present in the parent Table. The names should
| match the ``key`` given to each column (defaults to the name) unless
| ``link_to_name`` is True.
|
| :param refcolumns: A sequence of foreign column names or Column
| objects. The columns must all be located within the same Table.
|
| :param name: Optional, the in-database name of the key.
|
| :param onupdate: Optional string. If set, emit ON UPDATE <value> when
| issuing DDL for this constraint. Typical values include CASCADE,
| DELETE and RESTRICT.
|
| .. seealso::
|
| :ref:`on_update_on_delete`
|
| :param ondelete: Optional string. If set, emit ON DELETE <value> when
| issuing DDL for this constraint. Typical values include CASCADE,
| SET NULL and RESTRICT. Some dialects may allow for additional
| syntaxes.
|
| .. seealso::
|
| :ref:`on_update_on_delete`
|
| :param deferrable: Optional bool. If set, emit DEFERRABLE or NOT
| DEFERRABLE when issuing DDL for this constraint.
|
| :param initially: Optional string. If set, emit INITIALLY <value> when
| issuing DDL for this constraint.
|
| :param link_to_name: if True, the string name given in ``column`` is
| the rendered name of the referenced column, not its locally assigned
| ``key``.
|
| :param use_alter: If True, do not emit the DDL for this constraint as
| part of the CREATE TABLE definition. Instead, generate it via an
| ALTER TABLE statement issued after the full collection of tables
| have been created, and drop it via an ALTER TABLE statement before
| the full collection of tables are dropped.
|
| The use of :paramref:`_schema.ForeignKeyConstraint.use_alter` is
| particularly geared towards the case where two or more tables
| are established within a mutually-dependent foreign key constraint
| relationship; however, the :meth:`_schema.MetaData.create_all` and
| :meth:`_schema.MetaData.drop_all`
| methods will perform this resolution
| automatically, so the flag is normally not needed.
|
| .. seealso::
|
| :ref:`use_alter`
|
| :param match: Optional string. If set, emit MATCH <value> when issuing
| DDL for this constraint. Typical values include SIMPLE, PARTIAL
| and FULL.
|
| :param info: Optional data dictionary which will be populated into the
| :attr:`.SchemaItem.info` attribute of this object.
|
| :param comment: Optional string that will render an SQL comment on
| foreign key constraint creation.
|
| .. versionadded:: 2.0
|
| :param \**dialect_kw: Additional keyword arguments are dialect
| specific, and passed in the form ``<dialectname>_<argname>``. See
| the documentation regarding an individual dialect at
| :ref:`dialect_toplevel` for detail on documented arguments.
|
| copy(self, *, schema: 'Optional[str]' = None, target_table: 'Optional[Table]' = None, **kw: 'Any') -> 'ForeignKeyConstraint'
| .. deprecated:: 1.4 The :meth:`_schema.ForeignKeyConstraint.copy` method is deprecated and will be removed in a future release.
|
| ----------------------------------------------------------------------
| Readonly properties defined here:
|
| column_keys
| Return a list of string keys representing the local
| columns in this :class:`_schema.ForeignKeyConstraint`.
|
| This list is either the original string arguments sent
| to the constructor of the :class:`_schema.ForeignKeyConstraint`,
| or if the constraint has been initialized with :class:`_schema.Column`
| objects, is the string ``.key`` of each element.
|
| referred_table
| The :class:`_schema.Table` object to which this
| :class:`_schema.ForeignKeyConstraint` references.
|
| This is a dynamically calculated attribute which may not be available
| if the constraint and/or parent table is not yet associated with
| a metadata collection that contains the referred table.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'columns': 'ReadOnlyColumnCollection[str, Column[An...
|
| __visit_name__ = 'foreign_key_constraint'
|
| ----------------------------------------------------------------------
| Methods inherited from ColumnCollectionConstraint:
|
| __contains__(self, x: 'Any') -> 'bool'
|
| __iter__(self) -> 'Iterator[Column[Any]]'
|
| __len__(self) -> 'int'
|
| contains_column(self, col: 'Column[Any]') -> 'bool'
| Return True if this constraint contains the given column.
|
| Note that this object also contains an attribute ``.columns``
| which is a :class:`_expression.ColumnCollection` of
| :class:`_schema.Column` objects.
|
| ----------------------------------------------------------------------
| Methods inherited from ColumnCollectionMixin:
|
| c(...)
|
| columns(...)
|
| ----------------------------------------------------------------------
| Data descriptors inherited from ColumnCollectionMixin:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Readonly properties inherited from Constraint:
|
| table
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.base.DialectKWArgs:
|
| dialect_options(...)
| A collection of keyword arguments specified as dialect-specific
| options to this construct.
|
| This is a two-level nested registry, keyed to ``<dialect_name>``
| and ``<argument_name>``. For example, the ``postgresql_where``
| argument would be locatable as::
|
| arg = my_object.dialect_options["postgresql"]["where"]
|
| .. versionadded:: 0.9.2
|
| .. seealso::
|
| :attr:`.DialectKWArgs.dialect_kwargs` - flat dictionary form
|
| get_dialect_option(self, dialect: 'Dialect', argument_name: 'str', *, else_: 'Any' = None, deprecated_fallback: 'Optional[str]' = None) -> 'Any'
| Return the value of a dialect-specific option, or *else_* if
| this dialect does not register the given argument.
|
| This is useful for DDL compilers that may be inherited by
| third-party dialects whose ``construct_arguments`` do not
| include the same set of keys as the parent dialect.
|
| :param dialect: The dialect for which to retrieve the option.
| :param argument_name: The name of the argument to retrieve.
| :param else\_: The value to return if the argument is not present.
| :param deprecated_fallback: Optional dialect name to fall back to
| if the argument is not present for the current dialect. If the
| argument is present for the fallback dialect but not the current
| dialect, a deprecation warning will be emitted.
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.base.DialectKWArgs:
|
| argument_for(dialect_name: 'str', argument_name: 'str', default: 'Any') -> 'None'
| Add a new kind of dialect-specific keyword argument for this class.
|
| E.g.::
|
| Index.argument_for("mydialect", "length", None)
|
| some_index = Index("a", "b", mydialect_length=5)
|
| The :meth:`.DialectKWArgs.argument_for` method is a per-argument
| way adding extra arguments to the
| :attr:`.DefaultDialect.construct_arguments` dictionary. This
| dictionary provides a list of argument names accepted by various
| schema-level constructs on behalf of a dialect.
|
| New dialects should typically specify this dictionary all at once as a
| data member of the dialect class. The use case for ad-hoc addition of
| argument names is typically for end-user code that is also using
| a custom compilation scheme which consumes the additional arguments.
|
| :param dialect_name: name of a dialect. The dialect must be
| locatable, else a :class:`.NoSuchModuleError` is raised. The
| dialect must also include an existing
| :attr:`.DefaultDialect.construct_arguments` collection, indicating
| that it participates in the keyword-argument validation and default
| system, else :class:`.ArgumentError` is raised. If the dialect does
| not include this collection, then any keyword argument can be
| specified on behalf of this dialect already. All dialects packaged
| within SQLAlchemy include this collection, however for third party
| dialects, support may vary.
|
| :param argument_name: name of the parameter.
|
| :param default: default value of the parameter.
|
| ----------------------------------------------------------------------
| Readonly properties inherited from sqlalchemy.sql.base.DialectKWArgs:
|
| dialect_kwargs
| A collection of keyword arguments specified as dialect-specific
| options to this construct.
|
| The arguments are present here in their original ``<dialect>_<kwarg>``
| format. Only arguments that were actually passed are included;
| unlike the :attr:`.DialectKWArgs.dialect_options` collection, which
| contains all options known by this dialect including defaults.
|
| The collection is also writable; keys are accepted of the
| form ``<dialect>_<kwarg>`` where the value will be assembled
| into the list of options.
|
| .. seealso::
|
| :attr:`.DialectKWArgs.dialect_options` - nested dictionary form
|
| kwargs
| A synonym for :attr:`.DialectKWArgs.dialect_kwargs`.
|
| ----------------------------------------------------------------------
| Methods inherited from HasConditionalDDL:
|
| ddl_if(self, dialect: 'Optional[str]' = None, callable_: 'Optional[ddl.DDLIfCallable]' = None, state: 'Optional[Any]' = None) -> 'Self'
| apply a conditional DDL rule to this schema item.
|
| These rules work in a similar manner to the
| :meth:`.ExecutableDDLElement.execute_if` callable, with the added
| feature that the criteria may be checked within the DDL compilation
| phase for a construct such as :class:`.CreateTable`.
| :meth:`.HasConditionalDDL.ddl_if` currently applies towards the
| :class:`.Index` construct as well as all :class:`.Constraint`
| constructs.
|
| :param dialect: string name of a dialect, or a tuple of string names
| to indicate multiple dialect types.
|
| :param callable\_: a callable that is constructed using the same form
| as that described in
| :paramref:`.ExecutableDDLElement.execute_if.callable_`.
|
| :param state: any arbitrary object that will be passed to the
| callable, if present.
|
| .. versionadded:: 2.0
|
| .. seealso::
|
| :ref:`schema_ddl_ddl_if` - background and usage examples
|
| ----------------------------------------------------------------------
| Methods inherited from SchemaItem:
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| info(...)
| Info dictionary associated with the object, allowing user-defined
| data to be associated with this :class:`.SchemaItem`.
|
| The dictionary is automatically generated when first accessed.
| It can also be specified in the constructor of some objects,
| such as :class:`_schema.Table` and :class:`_schema.Column`.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from SchemaItem:
|
| create_drop_stringify_dialect = 'default'
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.base.SchemaEventTarget:
|
| dispatch = <sqlalchemy.event.base.DDLEventsDispatch object>
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.visitors.Visitable:
|
| __class_getitem__(key: 'Any') -> 'Any'
|
| __init_subclass__() -> 'None'
| This method is called when a class is subclassed.
|
| The default implementation does nothing. It may be
| overridden to extend subclasses.
sqlalchemy.FromClause
Python Library Documentation: class FromClause in module sqlalchemy.sql.selectable
class FromClause(sqlalchemy.sql.roles.AnonymizedFromClauseRole, 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`.
|
| Method resolution order:
| FromClause
| sqlalchemy.sql.roles.AnonymizedFromClauseRole
| sqlalchemy.sql.roles.StrictFromClauseRole
| sqlalchemy.sql.roles.FromClauseRole
| sqlalchemy.sql.roles.ColumnsClauseRole
| sqlalchemy.sql.roles.JoinTargetRole
| sqlalchemy.sql.roles.AllowsLambdaRole
| sqlalchemy.sql.roles.UsesInspection
| sqlalchemy.sql.roles.ColumnListRole
| sqlalchemy.sql.roles.StructuralRole
| Selectable
| ReturnsRows
| sqlalchemy.sql.roles.ReturnsRowsRole
| sqlalchemy.sql.roles.SQLRole
| sqlalchemy.sql.elements.DQLDMLClauseElement
| sqlalchemy.sql.elements.ClauseElement
| sqlalchemy.sql.annotation.SupportsWrappingAnnotations
| sqlalchemy.sql.annotation.SupportsAnnotations
| sqlalchemy.sql.cache_key.MemoizedHasCacheKey
| sqlalchemy.sql.cache_key.HasCacheKey
| sqlalchemy.util.langhelpers.HasMemoized
| sqlalchemy.sql.traversals.HasCopyInternals
| sqlalchemy.sql.visitors.ExternallyTraversible
| sqlalchemy.sql.visitors.HasTraverseInternals
| sqlalchemy.sql.elements.CompilerElement
| sqlalchemy.sql.visitors.Visitable
| builtins.object
|
| Methods defined here:
|
| alias(self, name: 'Optional[str]' = None, flat: 'bool' = False) -> 'NamedFromClause'
| 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`
|
| c(...)
| A synonym for :attr:`.FromClause.columns`
|
| :return: a :class:`.ColumnCollection`
|
| columns(...)
| 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.
|
| description(...)
| A brief description of this :class:`_expression.FromClause`.
|
| Used primarily for error message formatting.
|
| entity_namespace(...)
| 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.
|
| exported_columns(...)
| A :class:`_expression.ColumnCollection`
| that represents the "exported"
| columns of this :class:`_expression.Selectable`.
|
| 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`
|
| foreign_keys(...)
| Return the collection of :class:`_schema.ForeignKey` marker objects
| which this FromClause references.
|
| Each :class:`_schema.ForeignKey` is a member of a
| :class:`_schema.Table`-wide
| :class:`_schema.ForeignKeyConstraint`.
|
| .. seealso::
|
| :attr:`_schema.Table.foreign_key_constraints`
|
| 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.
|
| 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
|
| 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`
|
| primary_key(...)
| 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.
|
| select(self) -> 'Select[Any]'
| 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.
|
| 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
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'_columns': 'ColumnCollection[Any, Any]', '_is_clon...
|
| __visit_name__ = 'fromclause'
|
| is_selectable = True
|
| named_with_column = False
|
| schema = None
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.AllowsLambdaRole:
|
| allows_lambda = True
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.UsesInspection:
|
| uses_inspection = True
|
| ----------------------------------------------------------------------
| Methods inherited from Selectable:
|
| 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.
|
| 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.
|
| 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`.
|
| .. deprecated:: 1.4 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.
|
| ----------------------------------------------------------------------
| Readonly properties inherited from ReturnsRows:
|
| selectable
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.elements.ClauseElement:
|
| __bool__(self)
|
| __getstate__(self)
| Helper for pickle.
|
| __invert__(self)
|
| __repr__(self)
| Return repr(self).
|
| compare(self, other: 'ClauseElement', **kw: 'Any') -> 'bool'
| Compare this :class:`_expression.ClauseElement` to
| the given :class:`_expression.ClauseElement`.
|
| Subclasses should override the default behavior, which is a
| straight identity comparison.
|
| \**kw are arguments consumed by subclass ``compare()`` methods and
| may be used to modify the criteria for comparison
| (see :class:`_expression.ColumnElement`).
|
| params(self, _ClauseElement__optionaldict: 'Optional[Mapping[str, Any]]' = None, **kwargs: 'Any') -> 'Self'
| Return a copy with :func:`_expression.bindparam` elements
| replaced.
|
| Returns a copy of this ClauseElement with
| :func:`_expression.bindparam`
| elements replaced with values taken from the given dictionary::
|
| >>> clause = column("x") + bindparam("foo")
| >>> print(clause.compile().params)
| {'foo':None}
| >>> print(clause.params({"foo": 7}).compile().params)
| {'foo':7}
|
| self_group(self, against: 'Optional[OperatorType]' = None) -> 'ClauseElement'
| 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.
|
| unique_params(self, _ClauseElement__optionaldict: 'Optional[Dict[str, Any]]' = None, **kwargs: 'Any') -> 'Self'
| Return a copy with :func:`_expression.bindparam` elements
| replaced.
|
| Same functionality as :meth:`_expression.ClauseElement.params`,
| except adds `unique=True`
| to affected bind parameters so that multiple statements can be
| used.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.elements.ClauseElement:
|
| is_clause_element = True
|
| is_dml = False
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.cache_key.HasCacheKey:
|
| inherit_cache = None
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_instancemethod(fn: '_F') -> '_F'
| Decorate a method memoize its return value.
|
| :meta private:
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_attribute = <class 'sqlalchemy.util.langhelpers.HasMemoized.m...
| A read-only @property that is only evaluated once.
|
| :meta private:
|
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.visitors.HasTraverseInternals:
|
| get_children(self, *, omit_attrs: 'Tuple[str, ...]' = (), **kw: 'Any') -> 'Iterable[HasTraverseInternals]'
| Return immediate child :class:`.visitors.HasTraverseInternals`
| elements of this :class:`.visitors.HasTraverseInternals`.
|
| This is used for visit traversal.
|
| \**kw may contain flags that change the collection that is
| returned, for example to return a subset of items in order to
| cut down on larger traversals, or to return child items from a
| different context (such as schema-level collections instead of
| clause-level).
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.elements.CompilerElement:
|
| __str__(self) -> 'str'
| Return str(self).
|
| compile(self, bind: 'Optional[_HasDialect]' = None, dialect: 'Optional[Dialect]' = None, **kw: 'Any') -> 'Compiled'
| Compile this SQL expression.
|
| The return value is a :class:`~.Compiled` object.
| Calling ``str()`` or ``unicode()`` on the returned value will yield a
| string representation of the result. The
| :class:`~.Compiled` object also can return a
| dictionary of bind parameter names and values
| using the ``params`` accessor.
|
| :param bind: An :class:`.Connection` or :class:`.Engine` which
| can provide a :class:`.Dialect` in order to generate a
| :class:`.Compiled` object. If the ``bind`` and
| ``dialect`` parameters are both omitted, a default SQL compiler
| is used.
|
| :param column_keys: Used for INSERT and UPDATE statements, a list of
| column names which should be present in the VALUES clause of the
| compiled statement. If ``None``, all columns from the target table
| object are rendered.
|
| :param dialect: A :class:`.Dialect` instance which can generate
| a :class:`.Compiled` object. This argument takes precedence over
| the ``bind`` argument.
|
| :param compile_kwargs: optional dictionary of additional parameters
| that will be passed through to the compiler within all "visit"
| methods. This allows any custom flag to be passed through to
| a custom compilation construct, for example. It is also used
| for the case of passing the ``literal_binds`` flag through::
|
| from sqlalchemy.sql import table, column, select
|
| t = table("t", column("x"))
|
| s = select(t).where(t.c.x == 5)
|
| print(s.compile(compile_kwargs={"literal_binds": True}))
|
| .. seealso::
|
| :ref:`faq_sql_expression_string`
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.elements.CompilerElement:
|
| stringify_dialect = 'default'
|
| supports_execution = False
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.visitors.Visitable:
|
| __class_getitem__(key: 'Any') -> 'Any'
|
| __init_subclass__() -> 'None'
| This method is called when a class is subclassed.
|
| The default implementation does nothing. It may be
| overridden to extend subclasses.
sqlalchemy.FromGrouping
Python Library Documentation: class FromGrouping in module sqlalchemy.sql.selectable
class FromGrouping(sqlalchemy.sql.elements.GroupedElement, FromClause)
| FromGrouping(element: 'FromClause')
|
| Represent a grouping of a FROM clause
|
| Method resolution order:
| FromGrouping
| sqlalchemy.sql.elements.GroupedElement
| FromClause
| sqlalchemy.sql.roles.AnonymizedFromClauseRole
| sqlalchemy.sql.roles.StrictFromClauseRole
| sqlalchemy.sql.roles.FromClauseRole
| sqlalchemy.sql.roles.ColumnsClauseRole
| sqlalchemy.sql.roles.JoinTargetRole
| sqlalchemy.sql.roles.AllowsLambdaRole
| sqlalchemy.sql.roles.UsesInspection
| sqlalchemy.sql.roles.ColumnListRole
| sqlalchemy.sql.roles.StructuralRole
| Selectable
| ReturnsRows
| sqlalchemy.sql.roles.ReturnsRowsRole
| sqlalchemy.sql.roles.SQLRole
| sqlalchemy.sql.elements.DQLDMLClauseElement
| sqlalchemy.sql.elements.ClauseElement
| sqlalchemy.sql.annotation.SupportsWrappingAnnotations
| sqlalchemy.sql.annotation.SupportsAnnotations
| sqlalchemy.sql.cache_key.MemoizedHasCacheKey
| sqlalchemy.sql.cache_key.HasCacheKey
| sqlalchemy.util.langhelpers.HasMemoized
| sqlalchemy.sql.traversals.HasCopyInternals
| sqlalchemy.sql.visitors.ExternallyTraversible
| sqlalchemy.sql.visitors.HasTraverseInternals
| sqlalchemy.sql.elements.CompilerElement
| sqlalchemy.sql.visitors.Visitable
| builtins.object
|
| Methods defined here:
|
| __getstate__(self) -> 'Dict[str, FromClause]'
| Helper for pickle.
|
| __init__(self, element: 'FromClause')
| Initialize self. See help(type(self)) for accurate signature.
|
| __setstate__(self, state: 'Dict[str, FromClause]') -> 'None'
|
| alias(self, name: 'Optional[str]' = None, flat: 'bool' = False) -> 'NamedFromGrouping'
| 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`
|
| c(...)
|
| columns(...)
|
| 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.
|
| ----------------------------------------------------------------------
| Readonly properties defined here:
|
| foreign_keys
| Return the collection of :class:`_schema.ForeignKey` marker objects
| which this FromClause references.
|
| Each :class:`_schema.ForeignKey` is a member of a
| :class:`_schema.Table`-wide
| :class:`_schema.ForeignKeyConstraint`.
|
| .. seealso::
|
| :attr:`_schema.Table.foreign_key_constraints`
|
| primary_key
| 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.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'_traverse_internals': '_TraverseInternalsType', 'e...
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.elements.GroupedElement:
|
| self_group(self, against: 'Optional[OperatorType]' = None) -> 'Self'
| 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.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.elements.GroupedElement:
|
| __visit_name__ = 'grouping'
|
| ----------------------------------------------------------------------
| Methods inherited from FromClause:
|
| description(...)
| A brief description of this :class:`_expression.FromClause`.
|
| Used primarily for error message formatting.
|
| entity_namespace(...)
| 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.
|
| exported_columns(...)
| A :class:`_expression.ColumnCollection`
| that represents the "exported"
| columns of this :class:`_expression.Selectable`.
|
| 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`
|
| 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
|
| 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`
|
| select(self) -> 'Select[Any]'
| 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.
|
| 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
|
| ----------------------------------------------------------------------
| Data descriptors inherited from FromClause:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from FromClause:
|
| is_selectable = True
|
| named_with_column = False
|
| schema = None
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.AllowsLambdaRole:
|
| allows_lambda = True
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.UsesInspection:
|
| uses_inspection = True
|
| ----------------------------------------------------------------------
| Methods inherited from Selectable:
|
| 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.
|
| 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.
|
| 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`.
|
| .. deprecated:: 1.4 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.
|
| ----------------------------------------------------------------------
| Readonly properties inherited from ReturnsRows:
|
| selectable
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.elements.ClauseElement:
|
| __bool__(self)
|
| __invert__(self)
|
| __repr__(self)
| Return repr(self).
|
| compare(self, other: 'ClauseElement', **kw: 'Any') -> 'bool'
| Compare this :class:`_expression.ClauseElement` to
| the given :class:`_expression.ClauseElement`.
|
| Subclasses should override the default behavior, which is a
| straight identity comparison.
|
| \**kw are arguments consumed by subclass ``compare()`` methods and
| may be used to modify the criteria for comparison
| (see :class:`_expression.ColumnElement`).
|
| params(self, _ClauseElement__optionaldict: 'Optional[Mapping[str, Any]]' = None, **kwargs: 'Any') -> 'Self'
| Return a copy with :func:`_expression.bindparam` elements
| replaced.
|
| Returns a copy of this ClauseElement with
| :func:`_expression.bindparam`
| elements replaced with values taken from the given dictionary::
|
| >>> clause = column("x") + bindparam("foo")
| >>> print(clause.compile().params)
| {'foo':None}
| >>> print(clause.params({"foo": 7}).compile().params)
| {'foo':7}
|
| unique_params(self, _ClauseElement__optionaldict: 'Optional[Dict[str, Any]]' = None, **kwargs: 'Any') -> 'Self'
| Return a copy with :func:`_expression.bindparam` elements
| replaced.
|
| Same functionality as :meth:`_expression.ClauseElement.params`,
| except adds `unique=True`
| to affected bind parameters so that multiple statements can be
| used.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.elements.ClauseElement:
|
| is_clause_element = True
|
| is_dml = False
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.cache_key.HasCacheKey:
|
| inherit_cache = None
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_instancemethod(fn: '_F') -> '_F'
| Decorate a method memoize its return value.
|
| :meta private:
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_attribute = <class 'sqlalchemy.util.langhelpers.HasMemoized.m...
| A read-only @property that is only evaluated once.
|
| :meta private:
|
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.visitors.HasTraverseInternals:
|
| get_children(self, *, omit_attrs: 'Tuple[str, ...]' = (), **kw: 'Any') -> 'Iterable[HasTraverseInternals]'
| Return immediate child :class:`.visitors.HasTraverseInternals`
| elements of this :class:`.visitors.HasTraverseInternals`.
|
| This is used for visit traversal.
|
| \**kw may contain flags that change the collection that is
| returned, for example to return a subset of items in order to
| cut down on larger traversals, or to return child items from a
| different context (such as schema-level collections instead of
| clause-level).
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.elements.CompilerElement:
|
| __str__(self) -> 'str'
| Return str(self).
|
| compile(self, bind: 'Optional[_HasDialect]' = None, dialect: 'Optional[Dialect]' = None, **kw: 'Any') -> 'Compiled'
| Compile this SQL expression.
|
| The return value is a :class:`~.Compiled` object.
| Calling ``str()`` or ``unicode()`` on the returned value will yield a
| string representation of the result. The
| :class:`~.Compiled` object also can return a
| dictionary of bind parameter names and values
| using the ``params`` accessor.
|
| :param bind: An :class:`.Connection` or :class:`.Engine` which
| can provide a :class:`.Dialect` in order to generate a
| :class:`.Compiled` object. If the ``bind`` and
| ``dialect`` parameters are both omitted, a default SQL compiler
| is used.
|
| :param column_keys: Used for INSERT and UPDATE statements, a list of
| column names which should be present in the VALUES clause of the
| compiled statement. If ``None``, all columns from the target table
| object are rendered.
|
| :param dialect: A :class:`.Dialect` instance which can generate
| a :class:`.Compiled` object. This argument takes precedence over
| the ``bind`` argument.
|
| :param compile_kwargs: optional dictionary of additional parameters
| that will be passed through to the compiler within all "visit"
| methods. This allows any custom flag to be passed through to
| a custom compilation construct, for example. It is also used
| for the case of passing the ``literal_binds`` flag through::
|
| from sqlalchemy.sql import table, column, select
|
| t = table("t", column("x"))
|
| s = select(t).where(t.c.x == 5)
|
| print(s.compile(compile_kwargs={"literal_binds": True}))
|
| .. seealso::
|
| :ref:`faq_sql_expression_string`
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.elements.CompilerElement:
|
| stringify_dialect = 'default'
|
| supports_execution = False
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.visitors.Visitable:
|
| __class_getitem__(key: 'Any') -> 'Any'
|
| __init_subclass__() -> 'None'
| This method is called when a class is subclassed.
|
| The default implementation does nothing. It may be
| overridden to extend subclasses.
sqlalchemy.FrozenResult
Python Library Documentation: class FrozenResult in module sqlalchemy.engine.result
class FrozenResult(typing.Generic)
| FrozenResult(result: 'Result[_TP]')
|
| Represents a :class:`_engine.Result` object in a "frozen" state suitable
| for caching.
|
| The :class:`_engine.FrozenResult` object is returned from the
| :meth:`_engine.Result.freeze` method of any :class:`_engine.Result`
| object.
|
| A new iterable :class:`_engine.Result` object is generated from a fixed
| set of data each time the :class:`_engine.FrozenResult` is invoked as
| a callable::
|
|
| result = connection.execute(query)
|
| frozen = result.freeze()
|
| unfrozen_result_one = frozen()
|
| for row in unfrozen_result_one:
| print(row)
|
| unfrozen_result_two = frozen()
| rows = unfrozen_result_two.all()
|
| # ... etc
|
| .. versionadded:: 1.4
|
| .. seealso::
|
| :ref:`do_orm_execute_re_executing` - example usage within the
| ORM to implement a result-set cache.
|
| :func:`_orm.loading.merge_frozen_result` - ORM function to merge
| a frozen result back into a :class:`_orm.Session`.
|
| Method resolution order:
| FrozenResult
| typing.Generic
| builtins.object
|
| Methods defined here:
|
| __call__(self) -> 'Result[_TP]'
| Call self as a function.
|
| __init__(self, result: 'Result[_TP]')
| Initialize self. See help(type(self)) for accurate signature.
|
| rewrite_rows(self) -> 'Sequence[Sequence[Any]]'
|
| with_new_rows(self, tuple_data: 'Sequence[Row[_TP]]') -> 'FrozenResult[_TP]'
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'data': 'Sequence[Any]'}
|
| __orig_bases__ = (typing.Generic[~_TP],)
|
| __parameters__ = (~_TP,)
|
| ----------------------------------------------------------------------
| Class methods inherited from typing.Generic:
|
| __class_getitem__(...)
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__(...)
| Function to initialize subclasses.
sqlalchemy.Function
Python Library Documentation: class Function in module sqlalchemy.sql.functions
class Function(FunctionElement)
| Function(name: 'str', *clauses: '_ColumnExpressionOrLiteralArgument[Any]', type_: 'Optional[_TypeEngineArgument[_T]]' = None, packagenames: 'Optional[Tuple[str, ...]]' = None) -> 'None'
|
| Describe a named SQL function.
|
| The :class:`.Function` object is typically generated from the
| :data:`.func` generation object.
|
|
| :param \*clauses: list of column expressions that form the arguments
| of the SQL function call.
|
| :param type\_: optional :class:`.TypeEngine` datatype object that will be
| used as the return value of the column expression generated by this
| function call.
|
| :param packagenames: a string which indicates package prefix names
| to be prepended to the function name when the SQL is generated.
| The :data:`.func` generator creates these when it is called using
| dotted format, e.g.::
|
| func.mypackage.some_function(col1, col2)
|
| .. seealso::
|
| :ref:`tutorial_functions` - in the :ref:`unified_tutorial`
|
| :data:`.func` - namespace which produces registered or ad-hoc
| :class:`.Function` instances.
|
| :class:`.GenericFunction` - allows creation of registered function
| types.
|
| Method resolution order:
| Function
| FunctionElement
| sqlalchemy.sql.base.Executable
| sqlalchemy.sql.roles.StatementRole
| sqlalchemy.sql.elements.ColumnElement
| sqlalchemy.sql.roles.ColumnArgumentOrKeyRole
| sqlalchemy.sql.roles.ColumnArgumentRole
| sqlalchemy.sql.roles.StatementOptionRole
| sqlalchemy.sql.roles.WhereHavingRole
| sqlalchemy.sql.roles.OnClauseRole
| sqlalchemy.sql.roles.BinaryElementRole
| sqlalchemy.sql.roles.OrderByRole
| sqlalchemy.sql.selectable.FromClause
| sqlalchemy.sql.roles.AnonymizedFromClauseRole
| sqlalchemy.sql.roles.StrictFromClauseRole
| sqlalchemy.sql.roles.FromClauseRole
| sqlalchemy.sql.roles.ColumnsClauseRole
| sqlalchemy.sql.roles.JoinTargetRole
| sqlalchemy.sql.roles.AllowsLambdaRole
| sqlalchemy.sql.roles.ByOfRole
| sqlalchemy.sql.roles.UsesInspection
| sqlalchemy.sql.roles.ColumnListRole
| sqlalchemy.sql.roles.LimitOffsetRole
| sqlalchemy.sql.roles.DMLColumnRole
| sqlalchemy.sql.roles.DDLConstraintColumnRole
| sqlalchemy.sql.roles.DDLExpressionRole
| sqlalchemy.sql.roles.StructuralRole
| sqlalchemy.sql.elements.SQLColumnExpression
| sqlalchemy.sql.elements.SQLCoreOperations
| sqlalchemy.sql.roles.ExpressionElementRole
| sqlalchemy.sql.roles.TypedColumnsClauseRole
| typing.Generic
| sqlalchemy.sql.operators.ColumnOperators
| sqlalchemy.sql.operators.Operators
| sqlalchemy.util.langhelpers.TypingOnly
| sqlalchemy.sql.selectable.Selectable
| sqlalchemy.sql.selectable.ReturnsRows
| sqlalchemy.sql.roles.ReturnsRowsRole
| sqlalchemy.sql.roles.SQLRole
| sqlalchemy.sql.elements.DQLDMLClauseElement
| sqlalchemy.sql.elements.ClauseElement
| sqlalchemy.sql.annotation.SupportsWrappingAnnotations
| sqlalchemy.sql.annotation.SupportsAnnotations
| sqlalchemy.sql.cache_key.MemoizedHasCacheKey
| sqlalchemy.sql.cache_key.HasCacheKey
| sqlalchemy.sql.base.Generative
| sqlalchemy.util.langhelpers.HasMemoized
| sqlalchemy.sql.traversals.HasCopyInternals
| sqlalchemy.sql.visitors.ExternallyTraversible
| sqlalchemy.sql.visitors.HasTraverseInternals
| sqlalchemy.sql.elements.CompilerElement
| sqlalchemy.sql.visitors.Visitable
| builtins.object
|
| Methods defined here:
|
| __init__(self, name: 'str', *clauses: '_ColumnExpressionOrLiteralArgument[Any]', type_: 'Optional[_TypeEngineArgument[_T]]' = None, packagenames: 'Optional[Tuple[str, ...]]' = None) -> 'None'
| Construct a :class:`.Function`.
|
| The :data:`.func` construct is normally used to construct
| new :class:`.Function` instances.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'identifier': 'str', 'name': 'str', 'type': 'TypeEn...
|
| __orig_bases__ = (sqlalchemy.sql.functions.FunctionElement[~_T],)
|
| __parameters__ = (~_T,)
|
| __visit_name__ = 'function'
|
| ----------------------------------------------------------------------
| Methods inherited from FunctionElement:
|
| alias(self, name: 'Optional[str]' = None, joins_implicitly: 'bool' = False) -> 'TableValuedAlias'
| Produce a :class:`_expression.Alias` construct against this
| :class:`.FunctionElement`.
|
| .. tip::
|
| The :meth:`_functions.FunctionElement.alias` method is part of the
| mechanism by which "table valued" SQL functions are created.
| However, most use cases are covered by higher level methods on
| :class:`_functions.FunctionElement` including
| :meth:`_functions.FunctionElement.table_valued`, and
| :meth:`_functions.FunctionElement.column_valued`.
|
| This construct wraps the function in a named alias which
| is suitable for the FROM clause, in the style accepted for example
| by PostgreSQL. A column expression is also provided using the
| special ``.column`` attribute, which may
| be used to refer to the output of the function as a scalar value
| in the columns or where clause, for a backend such as PostgreSQL.
|
| For a full table-valued expression, use the
| :meth:`_functions.FunctionElement.table_valued` method first to
| establish named columns.
|
| e.g.:
|
| .. sourcecode:: pycon+sql
|
| >>> from sqlalchemy import func, select, column
| >>> data_view = func.unnest([1, 2, 3]).alias("data_view")
| >>> print(select(data_view.column))
| {printsql}SELECT data_view
| FROM unnest(:unnest_1) AS data_view
|
| The :meth:`_functions.FunctionElement.column_valued` method provides
| a shortcut for the above pattern:
|
| .. sourcecode:: pycon+sql
|
| >>> data_view = func.unnest([1, 2, 3]).column_valued("data_view")
| >>> print(select(data_view))
| {printsql}SELECT data_view
| FROM unnest(:unnest_1) AS data_view
|
| .. versionadded:: 1.4.0b2 Added the ``.column`` accessor
|
| :param name: alias name, will be rendered as ``AS <name>`` in the
| FROM clause
|
| :param joins_implicitly: when True, the table valued function may be
| used in the FROM clause without any explicit JOIN to other tables
| in the SQL query, and no "cartesian product" warning will be
| generated. May be useful for SQL functions such as
| ``func.json_each()``.
|
| .. versionadded:: 1.4.33
|
| .. seealso::
|
| :ref:`tutorial_functions_table_valued` -
| in the :ref:`unified_tutorial`
|
| :meth:`_functions.FunctionElement.table_valued`
|
| :meth:`_functions.FunctionElement.scalar_table_valued`
|
| :meth:`_functions.FunctionElement.column_valued`
|
| as_comparison(self, left_index: 'int', right_index: 'int') -> 'FunctionAsBinary'
| Interpret this expression as a boolean comparison between two
| values.
|
| This method is used for an ORM use case described at
| :ref:`relationship_custom_operator_sql_function`.
|
| A hypothetical SQL function "is_equal()" which compares to values
| for equality would be written in the Core expression language as::
|
| expr = func.is_equal("a", "b")
|
| If "is_equal()" above is comparing "a" and "b" for equality, the
| :meth:`.FunctionElement.as_comparison` method would be invoked as::
|
| expr = func.is_equal("a", "b").as_comparison(1, 2)
|
| Where above, the integer value "1" refers to the first argument of the
| "is_equal()" function and the integer value "2" refers to the second.
|
| This would create a :class:`.BinaryExpression` that is equivalent to::
|
| BinaryExpression("a", "b", operator=op.eq)
|
| However, at the SQL level it would still render as
| "is_equal('a', 'b')".
|
| The ORM, when it loads a related object or collection, needs to be able
| to manipulate the "left" and "right" sides of the ON clause of a JOIN
| expression. The purpose of this method is to provide a SQL function
| construct that can also supply this information to the ORM, when used
| with the :paramref:`_orm.relationship.primaryjoin` parameter. The
| return value is a containment object called :class:`.FunctionAsBinary`.
|
| An ORM example is as follows::
|
| class Venue(Base):
| __tablename__ = "venue"
| id = Column(Integer, primary_key=True)
| name = Column(String)
|
| descendants = relationship(
| "Venue",
| primaryjoin=func.instr(
| remote(foreign(name)), name + "/"
| ).as_comparison(1, 2)
| == 1,
| viewonly=True,
| order_by=name,
| )
|
| Above, the "Venue" class can load descendant "Venue" objects by
| determining if the name of the parent Venue is contained within the
| start of the hypothetical descendant value's name, e.g. "parent1" would
| match up to "parent1/child1", but not to "parent2/child1".
|
| Possible use cases include the "materialized path" example given above,
| as well as making use of special SQL functions such as geometric
| functions to create join conditions.
|
| :param left_index: the integer 1-based index of the function argument
| that serves as the "left" side of the expression.
| :param right_index: the integer 1-based index of the function argument
| that serves as the "right" side of the expression.
|
| .. versionadded:: 1.3
|
| .. seealso::
|
| :ref:`relationship_custom_operator_sql_function` -
| example use within the ORM
|
| c(...)
| synonym for :attr:`.FunctionElement.columns`.
|
| clauses(...)
| Return the underlying :class:`.ClauseList` which contains
| the arguments for this :class:`.FunctionElement`.
|
| column_valued(self, name: 'Optional[str]' = None, joins_implicitly: 'bool' = False) -> 'TableValuedColumn[_T]'
| Return this :class:`_functions.FunctionElement` as a column expression that
| selects from itself as a FROM clause.
|
| E.g.:
|
| .. sourcecode:: pycon+sql
|
| >>> from sqlalchemy import select, func
| >>> gs = func.generate_series(1, 5, -1).column_valued()
| >>> print(select(gs))
| {printsql}SELECT anon_1
| FROM generate_series(:generate_series_1, :generate_series_2, :generate_series_3) AS anon_1
|
| This is shorthand for::
|
| gs = func.generate_series(1, 5, -1).alias().column
|
| :param name: optional name to assign to the alias name that's generated.
| If omitted, a unique anonymizing name is used.
|
| :param joins_implicitly: when True, the "table" portion of the column
| valued function may be a member of the FROM clause without any
| explicit JOIN to other tables in the SQL query, and no "cartesian
| product" warning will be generated. May be useful for SQL functions
| such as ``func.json_array_elements()``.
|
| .. versionadded:: 1.4.46
|
| .. seealso::
|
| :ref:`tutorial_functions_column_valued` - in the :ref:`unified_tutorial`
|
| :ref:`postgresql_column_valued` - in the :ref:`postgresql_toplevel` documentation
|
| :meth:`_functions.FunctionElement.table_valued`
|
| columns(...)
| The set of columns exported by this :class:`.FunctionElement`.
|
| This is a placeholder collection that allows the function to be
| placed in the FROM clause of a statement:
|
| .. sourcecode:: pycon+sql
|
| >>> from sqlalchemy import column, select, func
| >>> stmt = select(column("x"), column("y")).select_from(func.myfunction())
| >>> print(stmt)
| {printsql}SELECT x, y FROM myfunction()
|
| The above form is a legacy feature that is now superseded by the
| fully capable :meth:`_functions.FunctionElement.table_valued`
| method; see that method for details.
|
| .. seealso::
|
| :meth:`_functions.FunctionElement.table_valued` - generates table-valued
| SQL function expressions.
|
| filter(self, *criterion: '_ColumnExpressionArgument[bool]') -> 'Union[Self, FunctionFilter[_T]]'
| Produce a FILTER clause against this function.
|
| Used against aggregate and window functions,
| for database backends that support the "FILTER" clause.
|
| The expression::
|
| func.count(1).filter(True)
|
| is shorthand for::
|
| from sqlalchemy import funcfilter
|
| funcfilter(func.count(1), True)
|
| .. seealso::
|
| :ref:`tutorial_functions_within_group` -
| in the :ref:`unified_tutorial`
|
| :class:`.FunctionFilter`
|
| :func:`.funcfilter`
|
| over(self, *, partition_by: 'Optional[_ByArgument]' = None, order_by: 'Optional[_ByArgument]' = None, rows: 'Optional[Tuple[Optional[int], Optional[int]]]' = None, range_: 'Optional[Tuple[Optional[int], Optional[int]]]' = None, groups: 'Optional[Tuple[Optional[int], Optional[int]]]' = None) -> 'Over[_T]'
| Produce an OVER clause against this function.
|
| Used against aggregate or so-called "window" functions,
| for database backends that support window functions.
|
| The expression::
|
| func.row_number().over(order_by="x")
|
| is shorthand for::
|
| from sqlalchemy import over
|
| over(func.row_number(), order_by="x")
|
| See :func:`_expression.over` for a full description.
|
| .. seealso::
|
| :func:`_expression.over`
|
| :ref:`tutorial_window_functions` - in the :ref:`unified_tutorial`
|
| scalar_table_valued(self, name: 'str', type_: 'Optional[_TypeEngineArgument[_T]]' = None) -> 'ScalarFunctionColumn[_T]'
| Return a column expression that's against this
| :class:`_functions.FunctionElement` as a scalar
| table-valued expression.
|
| The returned expression is similar to that returned by a single column
| accessed off of a :meth:`_functions.FunctionElement.table_valued`
| construct, except no FROM clause is generated; the function is rendered
| in the similar way as a scalar subquery.
|
| E.g.:
|
| .. sourcecode:: pycon+sql
|
| >>> from sqlalchemy import func, select
| >>> fn = func.jsonb_each("{'k', 'v'}").scalar_table_valued("key")
| >>> print(select(fn))
| {printsql}SELECT (jsonb_each(:jsonb_each_1)).key
|
| .. versionadded:: 1.4.0b2
|
| .. seealso::
|
| :meth:`_functions.FunctionElement.table_valued`
|
| :meth:`_functions.FunctionElement.alias`
|
| :meth:`_functions.FunctionElement.column_valued`
|
| select(self) -> 'Select[Tuple[_T]]'
| Produce a :func:`_expression.select` construct
| against this :class:`.FunctionElement`.
|
| This is shorthand for::
|
| s = select(function_element)
|
| self_group(self, against: 'Optional[OperatorType]' = None) -> 'ClauseElement'
| 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.
|
| table_valued(self, *expr: '_ColumnExpressionOrStrLabelArgument[Any]', **kw: 'Any') -> 'TableValuedAlias'
| Return a :class:`_sql.TableValuedAlias` representation of this
| :class:`_functions.FunctionElement` with table-valued expressions added.
|
| e.g. to use the SQLite form of ``generate_series()`` (including
| hidden columns "start", "stop", "step"):
|
| .. sourcecode:: pycon+sql
|
| >>> fn = func.generate_series(1, 5).table_valued(
| ... "value", "start", "stop", "step"
| ... )
|
| >>> print(select(fn))
| {printsql}SELECT anon_1.value, anon_1.start, anon_1.stop, anon_1.step
| FROM generate_series(:generate_series_1, :generate_series_2) AS anon_1{stop}
|
| >>> print(select(fn.c.value, fn.c.stop).where(fn.c.value > 2))
| {printsql}SELECT anon_1.value, anon_1.stop
| FROM generate_series(:generate_series_1, :generate_series_2) AS anon_1
| WHERE anon_1.value > :value_1{stop}
|
| Backends like PostgreSQL need the accessed columns to be explicitly
| named in "AS" clause. To achieve this, use
| :meth:`_sql.TableValuedAlias.render_derived`; be sure to consult the
| :ref:`PostgreSQL-specific documentation for table valued functions
| <postgresql_table_valued>` for additional examples:
|
| .. sourcecode:: pycon+sql
|
| >>> fn = func.generate_series(1, 5).table_valued("value").render_derived()
|
| >>> print(select(fn))
| {printsql}SELECT anon_1.value FROM
| generate_series(:generate_series_1, :generate_series_2) AS anon_1(value){stop}
|
| A WITH ORDINALITY expression may be generated by passing the keyword
| argument :paramref:`.FunctionElement.table_valued.with_ordinality`,
| illustrated below using PostgreSQL's syntax:
|
| .. sourcecode:: pycon+sql
|
| >>> fn = func.generate_series(4, 1, -1).table_valued(
| ... "gen", with_ordinality="ordinality"
| ... )
| >>> print(select(fn.render_derived()))
| {printsql}SELECT anon_1.gen, anon_1.ordinality
| FROM generate_series(:generate_series_1, :generate_series_2, :generate_series_3)
| WITH ORDINALITY AS anon_1(gen, ordinality)
|
| :param \*expr: A series of string column names that will be added to the
| ``.c`` collection of the resulting :class:`_sql.TableValuedAlias`
| construct as columns. :func:`_sql.column` objects with or without
| datatypes may also be used.
|
| :param name: optional name to assign to the alias name that's generated.
| If omitted, a unique anonymizing name is used.
|
| :param with_ordinality: string name that when present results in the
| ``WITH ORDINALITY`` clause being added to the alias, and the given
| string name will be added as a column to the .c collection
| of the resulting :class:`_sql.TableValuedAlias`.
|
| :param joins_implicitly: when True, the table valued function may be
| used in the FROM clause without any explicit JOIN to other tables
| in the SQL query, and no "cartesian product" warning will be generated.
| May be useful for SQL functions such as ``func.json_each()``.
|
| .. versionadded:: 1.4.33
|
| .. versionadded:: 1.4.0b2
|
|
| .. seealso::
|
| :ref:`tutorial_functions_table_valued` - in the :ref:`unified_tutorial`
|
| :ref:`Table-Valued Functions on PostgreSQL <postgresql_table_valued>` - in the :ref:`postgresql_toplevel` documentation
|
| :meth:`_functions.FunctionElement.scalar_table_valued` - variant of
| :meth:`_functions.FunctionElement.table_valued` which delivers the
| complete table valued expression as a scalar column expression
|
| :meth:`_functions.FunctionElement.column_valued`
|
| :meth:`_sql.TableValuedAlias.render_derived` - renders the alias
| using a derived column clause, e.g. ``AS name(col1, col2, ...)``
|
| within_group(self, *order_by: '_ColumnExpressionArgument[Any]') -> 'WithinGroup[_T]'
| Produce a WITHIN GROUP (ORDER BY expr) clause against this function.
|
| Used against so-called "ordered set aggregate" and "hypothetical
| set aggregate" functions, including :class:`.percentile_cont`,
| :class:`.rank`, :class:`.dense_rank`, etc.
|
| See :func:`_expression.within_group` for a full description.
|
| .. seealso::
|
| :ref:`tutorial_functions_within_group` -
| in the :ref:`unified_tutorial`
|
| within_group_type(self, within_group: 'WithinGroup[_S]') -> 'Optional[TypeEngine[_S]]'
| For types that define their return type as based on the criteria
| within a WITHIN GROUP (ORDER BY) expression, called by the
| :class:`.WithinGroup` construct.
|
| Returns None by default, in which case the function's normal ``.type``
| is used.
|
| ----------------------------------------------------------------------
| Readonly properties inherited from FunctionElement:
|
| entity_namespace
| overrides FromClause.entity_namespace as functions are generally
| column expressions and not FromClauses.
|
| exported_columns
| A :class:`_expression.ColumnCollection`
| that represents the "exported"
| columns of this :class:`_expression.Selectable`.
|
| 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`
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from FunctionElement:
|
| packagenames = ()
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.base.Executable:
|
| execution_options(self, **kw: 'Any') -> 'Self'
| Set non-SQL options for the statement which take effect during
| execution.
|
| Execution options can be set at many scopes, including per-statement,
| per-connection, or per execution, using methods such as
| :meth:`_engine.Connection.execution_options` and parameters which
| accept a dictionary of options such as
| :paramref:`_engine.Connection.execute.execution_options` and
| :paramref:`_orm.Session.execute.execution_options`.
|
| The primary characteristic of an execution option, as opposed to
| other kinds of options such as ORM loader options, is that
| **execution options never affect the compiled SQL of a query, only
| things that affect how the SQL statement itself is invoked or how
| results are fetched**. That is, execution options are not part of
| what's accommodated by SQL compilation nor are they considered part of
| the cached state of a statement.
|
| The :meth:`_sql.Executable.execution_options` method is
| :term:`generative`, as
| is the case for the method as applied to the :class:`_engine.Engine`
| and :class:`_orm.Query` objects, which means when the method is called,
| a copy of the object is returned, which applies the given parameters to
| that new copy, but leaves the original unchanged::
|
| statement = select(table.c.x, table.c.y)
| new_statement = statement.execution_options(my_option=True)
|
| An exception to this behavior is the :class:`_engine.Connection`
| object, where the :meth:`_engine.Connection.execution_options` method
| is explicitly **not** generative.
|
| The kinds of options that may be passed to
| :meth:`_sql.Executable.execution_options` and other related methods and
| parameter dictionaries include parameters that are explicitly consumed
| by SQLAlchemy Core or ORM, as well as arbitrary keyword arguments not
| defined by SQLAlchemy, which means the methods and/or parameter
| dictionaries may be used for user-defined parameters that interact with
| custom code, which may access the parameters using methods such as
| :meth:`_sql.Executable.get_execution_options` and
| :meth:`_engine.Connection.get_execution_options`, or within selected
| event hooks using a dedicated ``execution_options`` event parameter
| such as
| :paramref:`_events.ConnectionEvents.before_execute.execution_options`
| or :attr:`_orm.ORMExecuteState.execution_options`, e.g.::
|
| from sqlalchemy import event
|
|
| @event.listens_for(some_engine, "before_execute")
| def _process_opt(conn, statement, multiparams, params, execution_options):
| "run a SQL function before invoking a statement"
|
| if execution_options.get("do_special_thing", False):
| conn.exec_driver_sql("run_special_function()")
|
| Within the scope of options that are explicitly recognized by
| SQLAlchemy, most apply to specific classes of objects and not others.
| The most common execution options include:
|
| * :paramref:`_engine.Connection.execution_options.isolation_level` -
| sets the isolation level for a connection or a class of connections
| via an :class:`_engine.Engine`. This option is accepted only
| by :class:`_engine.Connection` or :class:`_engine.Engine`.
|
| * :paramref:`_engine.Connection.execution_options.stream_results` -
| indicates results should be fetched using a server side cursor;
| this option is accepted by :class:`_engine.Connection`, by the
| :paramref:`_engine.Connection.execute.execution_options` parameter
| on :meth:`_engine.Connection.execute`, and additionally by
| :meth:`_sql.Executable.execution_options` on a SQL statement object,
| as well as by ORM constructs like :meth:`_orm.Session.execute`.
|
| * :paramref:`_engine.Connection.execution_options.compiled_cache` -
| indicates a dictionary that will serve as the
| :ref:`SQL compilation cache <sql_caching>`
| for a :class:`_engine.Connection` or :class:`_engine.Engine`, as
| well as for ORM methods like :meth:`_orm.Session.execute`.
| Can be passed as ``None`` to disable caching for statements.
| This option is not accepted by
| :meth:`_sql.Executable.execution_options` as it is inadvisable to
| carry along a compilation cache within a statement object.
|
| * :paramref:`_engine.Connection.execution_options.schema_translate_map`
| - a mapping of schema names used by the
| :ref:`Schema Translate Map <schema_translating>` feature, accepted
| by :class:`_engine.Connection`, :class:`_engine.Engine`,
| :class:`_sql.Executable`, as well as by ORM constructs
| like :meth:`_orm.Session.execute`.
|
| .. seealso::
|
| :meth:`_engine.Connection.execution_options`
|
| :paramref:`_engine.Connection.execute.execution_options`
|
| :paramref:`_orm.Session.execute.execution_options`
|
| :ref:`orm_queryguide_execution_options` - documentation on all
| ORM-specific execution options
|
| get_execution_options(self) -> '_ExecuteOptions'
| Get the non-SQL options which will take effect during execution.
|
| .. versionadded:: 1.3
|
| .. seealso::
|
| :meth:`.Executable.execution_options`
|
| options(self, *options: 'ExecutableOption') -> 'Self'
| Apply options to this statement.
|
| In the general sense, options are any kind of Python object
| that can be interpreted by the SQL compiler for the statement.
| These options can be consumed by specific dialects or specific kinds
| of compilers.
|
| The most commonly known kind of option are the ORM level options
| that apply "eager load" and other loading behaviors to an ORM
| query. However, options can theoretically be used for many other
| purposes.
|
| For background on specific kinds of options for specific kinds of
| statements, refer to the documentation for those option objects.
|
| .. versionchanged:: 1.4 - added :meth:`.Executable.options` to
| Core statement objects towards the goal of allowing unified
| Core / ORM querying capabilities.
|
| .. seealso::
|
| :ref:`loading_columns` - refers to options specific to the usage
| of ORM queries
|
| :ref:`relationship_loader_options` - refers to options specific
| to the usage of ORM queries
|
| ----------------------------------------------------------------------
| Data descriptors inherited from sqlalchemy.sql.base.Executable:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.base.Executable:
|
| is_delete = False
|
| is_dml = False
|
| is_from_statement = False
|
| is_insert = False
|
| is_select = False
|
| is_text = False
|
| is_update = False
|
| supports_execution = True
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.elements.ColumnElement:
|
| __getattr__(self, key: 'str') -> 'Any'
|
| __setstate__(self, state)
|
| base_columns(...)
|
| cast(self, type_: '_TypeEngineArgument[_OPT]') -> 'Cast[_OPT]'
| Produce a type cast, i.e. ``CAST(<expression> AS <type>)``.
|
| This is a shortcut to the :func:`_expression.cast` function.
|
| .. seealso::
|
| :ref:`tutorial_casts`
|
| :func:`_expression.cast`
|
| :func:`_expression.type_coerce`
|
| comparator(...)
|
| label(self, name: 'Optional[str]') -> 'Label[_T]'
| Produce a column label, i.e. ``<columnname> AS <name>``.
|
| This is a shortcut to the :func:`_expression.label` function.
|
| If 'name' is ``None``, an anonymous label name will be generated.
|
| operate(self, op: 'operators.OperatorType', *other: 'Any', **kwargs: 'Any') -> 'ColumnElement[Any]'
| Operate on an argument.
|
| This is the lowest level of operation, raises
| :class:`NotImplementedError` by default.
|
| Overriding this on a subclass can allow common
| behavior to be applied to all operations.
| For example, overriding :class:`.ColumnOperators`
| to apply ``func.lower()`` to the left and right
| side::
|
| class MyComparator(ColumnOperators):
| def operate(self, op, other, **kwargs):
| return op(func.lower(self), func.lower(other), **kwargs)
|
| :param op: Operator callable.
| :param \*other: the 'other' side of the operation. Will
| be a single scalar for most operations.
| :param \**kwargs: modifiers. These may be passed by special
| operators such as :meth:`ColumnOperators.contains`.
|
| proxy_set(...)
| set of all columns we are proxying
|
| as of 2.0 this is explicitly deannotated columns. previously it was
| effectively deannotated columns but wasn't enforced. annotated
| columns should basically not go into sets if at all possible because
| their hashing behavior is very non-performant.
|
| reverse_operate(self, op: 'operators.OperatorType', other: 'Any', **kwargs: 'Any') -> 'ColumnElement[Any]'
| Reverse operate on an argument.
|
| Usage is the same as :meth:`operate`.
|
| shares_lineage(self, othercolumn: 'ColumnElement[Any]') -> 'bool'
| Return True if the given :class:`_expression.ColumnElement`
| has a common ancestor to this :class:`_expression.ColumnElement`.
|
| type(...)
|
| ----------------------------------------------------------------------
| Readonly properties inherited from sqlalchemy.sql.elements.ColumnElement:
|
| anon_key_label
| .. deprecated:: 1.4 The :attr:`_expression.ColumnElement.anon_key_label` attribute is now private, and the public accessor is deprecated.
|
| anon_label
| .. deprecated:: 1.4 The :attr:`_expression.ColumnElement.anon_label` attribute is now private, and the public accessor is deprecated.
|
| expression
| Return a column expression.
|
| Part of the inspection interface; returns self.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.elements.ColumnElement:
|
| foreign_keys = frozenset()
|
| key = None
|
| primary_key = False
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.selectable.FromClause:
|
| description(...)
| A brief description of this :class:`_expression.FromClause`.
|
| Used primarily for error message formatting.
|
| 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.
|
| 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
|
| 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`
|
| 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
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.selectable.FromClause:
|
| is_selectable = True
|
| named_with_column = False
|
| schema = None
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.AllowsLambdaRole:
|
| allows_lambda = True
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.UsesInspection:
|
| uses_inspection = True
|
| ----------------------------------------------------------------------
| Class methods inherited from typing.Generic:
|
| __class_getitem__(...)
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__(...)
| Function to initialize subclasses.
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.operators.ColumnOperators:
|
| __add__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``+`` operator.
|
| In a column context, produces the clause ``a + b``
| if the parent object has non-string affinity.
| If the parent object has a string affinity,
| produces the concatenation operator, ``a || b`` -
| see :meth:`.ColumnOperators.concat`.
|
| __contains__(self, other: 'Any') -> 'ColumnOperators'
|
| __eq__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``==`` operator.
|
| In a column context, produces the clause ``a = b``.
| If the target is ``None``, produces ``a IS NULL``.
|
| __floordiv__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``//`` operator.
|
| In a column context, produces the clause ``a / b``,
| which is the same as "truediv", but considers the result
| type to be integer.
|
| .. versionadded:: 2.0
|
| __ge__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``>=`` operator.
|
| In a column context, produces the clause ``a >= b``.
|
| __getitem__(self, index: 'Any') -> 'ColumnOperators'
| Implement the [] operator.
|
| This can be used by some database-specific types
| such as PostgreSQL ARRAY and HSTORE.
|
| __gt__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``>`` operator.
|
| In a column context, produces the clause ``a > b``.
|
| __hash__(self, /) from builtins.object
| Return hash(self).
|
| __le__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``<=`` operator.
|
| In a column context, produces the clause ``a <= b``.
|
| __lshift__(self, other: 'Any') -> 'ColumnOperators'
| implement the << operator.
|
| Not used by SQLAlchemy core, this is provided
| for custom operator systems which want to use
| << as an extension point.
|
| __lt__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``<`` operator.
|
| In a column context, produces the clause ``a < b``.
|
| __mod__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``%`` operator.
|
| In a column context, produces the clause ``a % b``.
|
| __mul__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``*`` operator.
|
| In a column context, produces the clause ``a * b``.
|
| __ne__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``!=`` operator.
|
| In a column context, produces the clause ``a != b``.
| If the target is ``None``, produces ``a IS NOT NULL``.
|
| __neg__(self) -> 'ColumnOperators'
| Implement the ``-`` operator.
|
| In a column context, produces the clause ``-a``.
|
| __radd__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``+`` operator in reverse.
|
| See :meth:`.ColumnOperators.__add__`.
|
| __rfloordiv__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``//`` operator in reverse.
|
| See :meth:`.ColumnOperators.__floordiv__`.
|
| __rmod__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``%`` operator in reverse.
|
| See :meth:`.ColumnOperators.__mod__`.
|
| __rmul__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``*`` operator in reverse.
|
| See :meth:`.ColumnOperators.__mul__`.
|
| __rshift__(self, other: 'Any') -> 'ColumnOperators'
| implement the >> operator.
|
| Not used by SQLAlchemy core, this is provided
| for custom operator systems which want to use
| >> as an extension point.
|
| __rsub__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``-`` operator in reverse.
|
| See :meth:`.ColumnOperators.__sub__`.
|
| __rtruediv__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``/`` operator in reverse.
|
| See :meth:`.ColumnOperators.__truediv__`.
|
| __sub__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``-`` operator.
|
| In a column context, produces the clause ``a - b``.
|
| __truediv__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``/`` operator.
|
| In a column context, produces the clause ``a / b``, and
| considers the result type to be numeric.
|
| .. versionchanged:: 2.0 The truediv operator against two integers
| is now considered to return a numeric value. Behavior on specific
| backends may vary.
|
| all_(self) -> 'ColumnOperators'
| Produce an :func:`_expression.all_` clause against the
| parent object.
|
| See the documentation for :func:`_sql.all_` for examples.
|
| .. note:: be sure to not confuse the newer
| :meth:`_sql.ColumnOperators.all_` method with the **legacy**
| version of this method, the :meth:`_types.ARRAY.Comparator.all`
| method that's specific to :class:`_types.ARRAY`, which uses a
| different calling style.
|
| any_(self) -> 'ColumnOperators'
| Produce an :func:`_expression.any_` clause against the
| parent object.
|
| See the documentation for :func:`_sql.any_` for examples.
|
| .. note:: be sure to not confuse the newer
| :meth:`_sql.ColumnOperators.any_` method with the **legacy**
| version of this method, the :meth:`_types.ARRAY.Comparator.any`
| method that's specific to :class:`_types.ARRAY`, which uses a
| different calling style.
|
| asc(self) -> 'ColumnOperators'
| Produce a :func:`_expression.asc` clause against the
| parent object.
|
| between(self, cleft: 'Any', cright: 'Any', symmetric: 'bool' = False) -> 'ColumnOperators'
| Produce a :func:`_expression.between` clause against
| the parent object, given the lower and upper range.
|
| bitwise_and(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise AND operation, typically via the ``&``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_lshift(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise LSHIFT operation, typically via the ``<<``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_not(self) -> 'ColumnOperators'
| Produce a bitwise NOT operation, typically via the ``~``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_or(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise OR operation, typically via the ``|``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_rshift(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise RSHIFT operation, typically via the ``>>``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_xor(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise XOR operation, typically via the ``^``
| operator, or ``#`` for PostgreSQL.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| collate(self, collation: 'str') -> 'ColumnOperators'
| Produce a :func:`_expression.collate` clause against
| the parent object, given the collation string.
|
| .. seealso::
|
| :func:`_expression.collate`
|
| concat(self, other: 'Any') -> 'ColumnOperators'
| Implement the 'concat' operator.
|
| In a column context, produces the clause ``a || b``,
| or uses the ``concat()`` operator on MySQL.
|
| contains(self, other: 'Any', **kw: 'Any') -> 'ColumnOperators'
| Implement the 'contains' operator.
|
| Produces a LIKE expression that tests against a match for the middle
| of a string value:
|
| .. sourcecode:: sql
|
| column LIKE '%' || <other> || '%'
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.contains("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.contains.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.contains.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.contains.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.contains("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE '%' || :param || '%' ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.contains("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE '%' || :param || '%' ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.contains.autoescape`::
|
| somecolumn.contains("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.startswith`
|
| :meth:`.ColumnOperators.endswith`
|
| :meth:`.ColumnOperators.like`
|
| desc(self) -> 'ColumnOperators'
| Produce a :func:`_expression.desc` clause against the
| parent object.
|
| distinct(self) -> 'ColumnOperators'
| Produce a :func:`_expression.distinct` clause against the
| parent object.
|
| endswith(self, other: 'Any', escape: 'Optional[str]' = None, autoescape: 'bool' = False) -> 'ColumnOperators'
| Implement the 'endswith' operator.
|
| Produces a LIKE expression that tests against a match for the end
| of a string value:
|
| .. sourcecode:: sql
|
| column LIKE '%' || <other>
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.endswith("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.endswith.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.endswith.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.endswith.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.endswith("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE '%' || :param ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.endswith("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE '%' || :param ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.endswith.autoescape`::
|
| somecolumn.endswith("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.startswith`
|
| :meth:`.ColumnOperators.contains`
|
| :meth:`.ColumnOperators.like`
|
| icontains(self, other: 'Any', **kw: 'Any') -> 'ColumnOperators'
| Implement the ``icontains`` operator, e.g. case insensitive
| version of :meth:`.ColumnOperators.contains`.
|
| Produces a LIKE expression that tests against an insensitive match
| for the middle of a string value:
|
| .. sourcecode:: sql
|
| lower(column) LIKE '%' || lower(<other>) || '%'
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.icontains("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.icontains.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.icontains.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.icontains.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.icontains("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE '%' || lower(:param) || '%' ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.icontains("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE '%' || lower(:param) || '%' ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.contains.autoescape`::
|
| somecolumn.icontains("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.contains`
|
| iendswith(self, other: 'Any', escape: 'Optional[str]' = None, autoescape: 'bool' = False) -> 'ColumnOperators'
| Implement the ``iendswith`` operator, e.g. case insensitive
| version of :meth:`.ColumnOperators.endswith`.
|
| Produces a LIKE expression that tests against an insensitive match
| for the end of a string value:
|
| .. sourcecode:: sql
|
| lower(column) LIKE '%' || lower(<other>)
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.iendswith("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.iendswith.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.iendswith.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.iendswith.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.iendswith("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE '%' || lower(:param) ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.iendswith("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE '%' || lower(:param) ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.iendswith.autoescape`::
|
| somecolumn.endswith("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.endswith`
|
| ilike(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
| Implement the ``ilike`` operator, e.g. case insensitive LIKE.
|
| In a column context, produces an expression either of the form:
|
| .. sourcecode:: sql
|
| lower(a) LIKE lower(other)
|
| Or on backends that support the ILIKE operator:
|
| .. sourcecode:: sql
|
| a ILIKE other
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.ilike("%foobar%"))
|
| :param other: expression to be compared
| :param escape: optional escape character, renders the ``ESCAPE``
| keyword, e.g.::
|
| somecolumn.ilike("foo/%bar", escape="/")
|
| .. seealso::
|
| :meth:`.ColumnOperators.like`
|
| in_(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``in`` operator.
|
| In a column context, produces the clause ``column IN <other>``.
|
| The given parameter ``other`` may be:
|
| * A list of literal values,
| e.g.::
|
| stmt.where(column.in_([1, 2, 3]))
|
| In this calling form, the list of items is converted to a set of
| bound parameters the same length as the list given:
|
| .. sourcecode:: sql
|
| WHERE COL IN (?, ?, ?)
|
| * A list of tuples may be provided if the comparison is against a
| :func:`.tuple_` containing multiple expressions::
|
| from sqlalchemy import tuple_
|
| stmt.where(tuple_(col1, col2).in_([(1, 10), (2, 20), (3, 30)]))
|
| * An empty list,
| e.g.::
|
| stmt.where(column.in_([]))
|
| In this calling form, the expression renders an "empty set"
| expression. These expressions are tailored to individual backends
| and are generally trying to get an empty SELECT statement as a
| subquery. Such as on SQLite, the expression is:
|
| .. sourcecode:: sql
|
| WHERE col IN (SELECT 1 FROM (SELECT 1) WHERE 1!=1)
|
| .. versionchanged:: 1.4 empty IN expressions now use an
| execution-time generated SELECT subquery in all cases.
|
| * A bound parameter, e.g. :func:`.bindparam`, may be used if it
| includes the :paramref:`.bindparam.expanding` flag::
|
| stmt.where(column.in_(bindparam("value", expanding=True)))
|
| In this calling form, the expression renders a special non-SQL
| placeholder expression that looks like:
|
| .. sourcecode:: sql
|
| WHERE COL IN ([EXPANDING_value])
|
| This placeholder expression is intercepted at statement execution
| time to be converted into the variable number of bound parameter
| form illustrated earlier. If the statement were executed as::
|
| connection.execute(stmt, {"value": [1, 2, 3]})
|
| The database would be passed a bound parameter for each value:
|
| .. sourcecode:: sql
|
| WHERE COL IN (?, ?, ?)
|
| .. versionadded:: 1.2 added "expanding" bound parameters
|
| If an empty list is passed, a special "empty list" expression,
| which is specific to the database in use, is rendered. On
| SQLite this would be:
|
| .. sourcecode:: sql
|
| WHERE COL IN (SELECT 1 FROM (SELECT 1) WHERE 1!=1)
|
| .. versionadded:: 1.3 "expanding" bound parameters now support
| empty lists
|
| * a :func:`_expression.select` construct, which is usually a
| correlated scalar select::
|
| stmt.where(
| column.in_(select(othertable.c.y).where(table.c.x == othertable.c.x))
| )
|
| In this calling form, :meth:`.ColumnOperators.in_` renders as given:
|
| .. sourcecode:: sql
|
| WHERE COL IN (SELECT othertable.y
| FROM othertable WHERE othertable.x = table.x)
|
| :param other: a list of literals, a :func:`_expression.select`
| construct, or a :func:`.bindparam` construct that includes the
| :paramref:`.bindparam.expanding` flag set to True.
|
| is_(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``IS`` operator.
|
| Normally, ``IS`` is generated automatically when comparing to a
| value of ``None``, which resolves to ``NULL``. However, explicit
| usage of ``IS`` may be desirable if comparing to boolean values
| on certain platforms.
|
| .. seealso:: :meth:`.ColumnOperators.is_not`
|
| is_distinct_from(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``IS DISTINCT FROM`` operator.
|
| Renders "a IS DISTINCT FROM b" on most platforms;
| on some such as SQLite may render "a IS NOT b".
|
| is_not(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``IS NOT`` operator.
|
| Normally, ``IS NOT`` is generated automatically when comparing to a
| value of ``None``, which resolves to ``NULL``. However, explicit
| usage of ``IS NOT`` may be desirable if comparing to boolean values
| on certain platforms.
|
| .. versionchanged:: 1.4 The ``is_not()`` operator is renamed from
| ``isnot()`` in previous releases. The previous name remains
| available for backwards compatibility.
|
| .. seealso:: :meth:`.ColumnOperators.is_`
|
| is_not_distinct_from(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``IS NOT DISTINCT FROM`` operator.
|
| Renders "a IS NOT DISTINCT FROM b" on most platforms;
| on some such as SQLite may render "a IS b".
|
| .. versionchanged:: 1.4 The ``is_not_distinct_from()`` operator is
| renamed from ``isnot_distinct_from()`` in previous releases.
| The previous name remains available for backwards compatibility.
|
| isnot = is_not(self, other: 'Any') -> 'ColumnOperators'
|
| isnot_distinct_from = is_not_distinct_from(self, other: 'Any') -> 'ColumnOperators'
|
| istartswith(self, other: 'Any', escape: 'Optional[str]' = None, autoescape: 'bool' = False) -> 'ColumnOperators'
| Implement the ``istartswith`` operator, e.g. case insensitive
| version of :meth:`.ColumnOperators.startswith`.
|
| Produces a LIKE expression that tests against an insensitive
| match for the start of a string value:
|
| .. sourcecode:: sql
|
| lower(column) LIKE lower(<other>) || '%'
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.istartswith("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.istartswith.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.istartswith.escape` parameter will
| establish a given character as an escape character which can be of
| use when the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.istartswith.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.istartswith("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE lower(:param) || '%' ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.istartswith("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE lower(:param) || '%' ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.istartswith.autoescape`::
|
| somecolumn.istartswith("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.startswith`
|
| like(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
| Implement the ``like`` operator.
|
| In a column context, produces the expression:
|
| .. sourcecode:: sql
|
| a LIKE other
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.like("%foobar%"))
|
| :param other: expression to be compared
| :param escape: optional escape character, renders the ``ESCAPE``
| keyword, e.g.::
|
| somecolumn.like("foo/%bar", escape="/")
|
| .. seealso::
|
| :meth:`.ColumnOperators.ilike`
|
| match(self, other: 'Any', **kwargs: 'Any') -> 'ColumnOperators'
| Implements a database-specific 'match' operator.
|
| :meth:`_sql.ColumnOperators.match` attempts to resolve to
| a MATCH-like function or operator provided by the backend.
| Examples include:
|
| * PostgreSQL - renders ``x @@ plainto_tsquery(y)``
|
| .. versionchanged:: 2.0 ``plainto_tsquery()`` is used instead
| of ``to_tsquery()`` for PostgreSQL now; for compatibility with
| other forms, see :ref:`postgresql_match`.
|
|
| * MySQL - renders ``MATCH (x) AGAINST (y IN BOOLEAN MODE)``
|
| .. seealso::
|
| :class:`_mysql.match` - MySQL specific construct with
| additional features.
|
| * Oracle Database - renders ``CONTAINS(x, y)``
| * other backends may provide special implementations.
| * Backends without any special implementation will emit
| the operator as "MATCH". This is compatible with SQLite, for
| example.
|
| not_ilike(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
| implement the ``NOT ILIKE`` operator.
|
| This is equivalent to using negation with
| :meth:`.ColumnOperators.ilike`, i.e. ``~x.ilike(y)``.
|
| .. versionchanged:: 1.4 The ``not_ilike()`` operator is renamed from
| ``notilike()`` in previous releases. The previous name remains
| available for backwards compatibility.
|
| .. seealso::
|
| :meth:`.ColumnOperators.ilike`
|
| not_in(self, other: 'Any') -> 'ColumnOperators'
| implement the ``NOT IN`` operator.
|
| This is equivalent to using negation with
| :meth:`.ColumnOperators.in_`, i.e. ``~x.in_(y)``.
|
| In the case that ``other`` is an empty sequence, the compiler
| produces an "empty not in" expression. This defaults to the
| expression "1 = 1" to produce true in all cases. The
| :paramref:`_sa.create_engine.empty_in_strategy` may be used to
| alter this behavior.
|
| .. versionchanged:: 1.4 The ``not_in()`` operator is renamed from
| ``notin_()`` in previous releases. The previous name remains
| available for backwards compatibility.
|
| .. versionchanged:: 1.2 The :meth:`.ColumnOperators.in_` and
| :meth:`.ColumnOperators.not_in` operators
| now produce a "static" expression for an empty IN sequence
| by default.
|
| .. seealso::
|
| :meth:`.ColumnOperators.in_`
|
| not_like(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
| implement the ``NOT LIKE`` operator.
|
| This is equivalent to using negation with
| :meth:`.ColumnOperators.like`, i.e. ``~x.like(y)``.
|
| .. versionchanged:: 1.4 The ``not_like()`` operator is renamed from
| ``notlike()`` in previous releases. The previous name remains
| available for backwards compatibility.
|
| .. seealso::
|
| :meth:`.ColumnOperators.like`
|
| notilike = not_ilike(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
|
| notin_ = not_in(self, other: 'Any') -> 'ColumnOperators'
|
| notlike = not_like(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
|
| nulls_first(self) -> 'ColumnOperators'
| Produce a :func:`_expression.nulls_first` clause against the
| parent object.
|
| .. versionchanged:: 1.4 The ``nulls_first()`` operator is
| renamed from ``nullsfirst()`` in previous releases.
| The previous name remains available for backwards compatibility.
|
| nulls_last(self) -> 'ColumnOperators'
| Produce a :func:`_expression.nulls_last` clause against the
| parent object.
|
| .. versionchanged:: 1.4 The ``nulls_last()`` operator is
| renamed from ``nullslast()`` in previous releases.
| The previous name remains available for backwards compatibility.
|
| nullsfirst = nulls_first(self) -> 'ColumnOperators'
|
| nullslast = nulls_last(self) -> 'ColumnOperators'
|
| regexp_match(self, pattern: 'Any', flags: 'Optional[str]' = None) -> 'ColumnOperators'
| Implements a database-specific 'regexp match' operator.
|
| E.g.::
|
| stmt = select(table.c.some_column).where(
| table.c.some_column.regexp_match("^(b|c)")
| )
|
| :meth:`_sql.ColumnOperators.regexp_match` attempts to resolve to
| a REGEXP-like function or operator provided by the backend, however
| the specific regular expression syntax and flags available are
| **not backend agnostic**.
|
| Examples include:
|
| * PostgreSQL - renders ``x ~ y`` or ``x !~ y`` when negated.
| * Oracle Database - renders ``REGEXP_LIKE(x, y)``
| * SQLite - uses SQLite's ``REGEXP`` placeholder operator and calls into
| the Python ``re.match()`` builtin.
| * other backends may provide special implementations.
| * Backends without any special implementation will emit
| the operator as "REGEXP" or "NOT REGEXP". This is compatible with
| SQLite and MySQL, for example.
|
| Regular expression support is currently implemented for Oracle
| Database, PostgreSQL, MySQL and MariaDB. Partial support is available
| for SQLite. Support among third-party dialects may vary.
|
| :param pattern: The regular expression pattern string or column
| clause.
| :param flags: Any regular expression string flags to apply, passed as
| plain Python string only. These flags are backend specific.
| Some backends, like PostgreSQL and MariaDB, may alternatively
| specify the flags as part of the pattern.
| When using the ignore case flag 'i' in PostgreSQL, the ignore case
| regexp match operator ``~*`` or ``!~*`` will be used.
|
| .. versionadded:: 1.4
|
| .. versionchanged:: 1.4.48, 2.0.18 Note that due to an implementation
| error, the "flags" parameter previously accepted SQL expression
| objects such as column expressions in addition to plain Python
| strings. This implementation did not work correctly with caching
| and was removed; strings only should be passed for the "flags"
| parameter, as these flags are rendered as literal inline values
| within SQL expressions.
|
| .. seealso::
|
| :meth:`_sql.ColumnOperators.regexp_replace`
|
| regexp_replace(self, pattern: 'Any', replacement: 'Any', flags: 'Optional[str]' = None) -> 'ColumnOperators'
| Implements a database-specific 'regexp replace' operator.
|
| E.g.::
|
| stmt = select(
| table.c.some_column.regexp_replace("b(..)", "XY", flags="g")
| )
|
| :meth:`_sql.ColumnOperators.regexp_replace` attempts to resolve to
| a REGEXP_REPLACE-like function provided by the backend, that
| usually emit the function ``REGEXP_REPLACE()``. However,
| the specific regular expression syntax and flags available are
| **not backend agnostic**.
|
| Regular expression replacement support is currently implemented for
| Oracle Database, PostgreSQL, MySQL 8 or greater and MariaDB. Support
| among third-party dialects may vary.
|
| :param pattern: The regular expression pattern string or column
| clause.
| :param pattern: The replacement string or column clause.
| :param flags: Any regular expression string flags to apply, passed as
| plain Python string only. These flags are backend specific.
| Some backends, like PostgreSQL and MariaDB, may alternatively
| specify the flags as part of the pattern.
|
| .. versionadded:: 1.4
|
| .. versionchanged:: 1.4.48, 2.0.18 Note that due to an implementation
| error, the "flags" parameter previously accepted SQL expression
| objects such as column expressions in addition to plain Python
| strings. This implementation did not work correctly with caching
| and was removed; strings only should be passed for the "flags"
| parameter, as these flags are rendered as literal inline values
| within SQL expressions.
|
|
| .. seealso::
|
| :meth:`_sql.ColumnOperators.regexp_match`
|
| startswith(self, other: 'Any', escape: 'Optional[str]' = None, autoescape: 'bool' = False) -> 'ColumnOperators'
| Implement the ``startswith`` operator.
|
| Produces a LIKE expression that tests against a match for the start
| of a string value:
|
| .. sourcecode:: sql
|
| column LIKE <other> || '%'
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.startswith("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.startswith.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.startswith.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.startswith.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.startswith("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE :param || '%' ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.startswith("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE :param || '%' ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.startswith.autoescape`::
|
| somecolumn.startswith("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.endswith`
|
| :meth:`.ColumnOperators.contains`
|
| :meth:`.ColumnOperators.like`
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.operators.ColumnOperators:
|
| timetuple = None
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.operators.Operators:
|
| __and__(self, other: 'Any') -> 'Operators'
| Implement the ``&`` operator.
|
| When used with SQL expressions, results in an
| AND operation, equivalent to
| :func:`_expression.and_`, that is::
|
| a & b
|
| is equivalent to::
|
| from sqlalchemy import and_
|
| and_(a, b)
|
| Care should be taken when using ``&`` regarding
| operator precedence; the ``&`` operator has the highest precedence.
| The operands should be enclosed in parenthesis if they contain
| further sub expressions::
|
| (a == 2) & (b == 4)
|
| __invert__(self) -> 'Operators'
| Implement the ``~`` operator.
|
| When used with SQL expressions, results in a
| NOT operation, equivalent to
| :func:`_expression.not_`, that is::
|
| ~a
|
| is equivalent to::
|
| from sqlalchemy import not_
|
| not_(a)
|
| __or__(self, other: 'Any') -> 'Operators'
| Implement the ``|`` operator.
|
| When used with SQL expressions, results in an
| OR operation, equivalent to
| :func:`_expression.or_`, that is::
|
| a | b
|
| is equivalent to::
|
| from sqlalchemy import or_
|
| or_(a, b)
|
| Care should be taken when using ``|`` regarding
| operator precedence; the ``|`` operator has the highest precedence.
| The operands should be enclosed in parenthesis if they contain
| further sub expressions::
|
| (a == 2) | (b == 4)
|
| __sa_operate__ = operate(self, op: 'OperatorType', *other: 'Any', **kwargs: 'Any') -> 'Operators'
| Operate on an argument.
|
| This is the lowest level of operation, raises
| :class:`NotImplementedError` by default.
|
| Overriding this on a subclass can allow common
| behavior to be applied to all operations.
| For example, overriding :class:`.ColumnOperators`
| to apply ``func.lower()`` to the left and right
| side::
|
| class MyComparator(ColumnOperators):
| def operate(self, op, other, **kwargs):
| return op(func.lower(self), func.lower(other), **kwargs)
|
| :param op: Operator callable.
| :param \*other: the 'other' side of the operation. Will
| be a single scalar for most operations.
| :param \**kwargs: modifiers. These may be passed by special
| operators such as :meth:`ColumnOperators.contains`.
|
| bool_op(self, opstring: 'str', precedence: 'int' = 0, python_impl: 'Optional[Callable[..., Any]]' = None) -> 'Callable[[Any], Operators]'
| Return a custom boolean operator.
|
| This method is shorthand for calling
| :meth:`.Operators.op` and passing the
| :paramref:`.Operators.op.is_comparison`
| flag with True. A key advantage to using :meth:`.Operators.bool_op`
| is that when using column constructs, the "boolean" nature of the
| returned expression will be present for :pep:`484` purposes.
|
| .. seealso::
|
| :meth:`.Operators.op`
|
| op(self, opstring: 'str', precedence: 'int' = 0, is_comparison: 'bool' = False, return_type: 'Optional[Union[Type[TypeEngine[Any]], TypeEngine[Any]]]' = None, python_impl: 'Optional[Callable[..., Any]]' = None) -> 'Callable[[Any], Operators]'
| Produce a generic operator function.
|
| e.g.::
|
| somecolumn.op("*")(5)
|
| produces::
|
| somecolumn * 5
|
| This function can also be used to make bitwise operators explicit. For
| example::
|
| somecolumn.op("&")(0xFF)
|
| is a bitwise AND of the value in ``somecolumn``.
|
| :param opstring: a string which will be output as the infix operator
| between this element and the expression passed to the
| generated function.
|
| :param precedence: precedence which the database is expected to apply
| to the operator in SQL expressions. This integer value acts as a hint
| for the SQL compiler to know when explicit parenthesis should be
| rendered around a particular operation. A lower number will cause the
| expression to be parenthesized when applied against another operator
| with higher precedence. The default value of ``0`` is lower than all
| operators except for the comma (``,``) and ``AS`` operators. A value
| of 100 will be higher or equal to all operators, and -100 will be
| lower than or equal to all operators.
|
| .. seealso::
|
| :ref:`faq_sql_expression_op_parenthesis` - detailed description
| of how the SQLAlchemy SQL compiler renders parenthesis
|
| :param is_comparison: legacy; if True, the operator will be considered
| as a "comparison" operator, that is which evaluates to a boolean
| true/false value, like ``==``, ``>``, etc. This flag is provided
| so that ORM relationships can establish that the operator is a
| comparison operator when used in a custom join condition.
|
| Using the ``is_comparison`` parameter is superseded by using the
| :meth:`.Operators.bool_op` method instead; this more succinct
| operator sets this parameter automatically, but also provides
| correct :pep:`484` typing support as the returned object will
| express a "boolean" datatype, i.e. ``BinaryExpression[bool]``.
|
| :param return_type: a :class:`.TypeEngine` class or object that will
| force the return type of an expression produced by this operator
| to be of that type. By default, operators that specify
| :paramref:`.Operators.op.is_comparison` will resolve to
| :class:`.Boolean`, and those that do not will be of the same
| type as the left-hand operand.
|
| :param python_impl: an optional Python function that can evaluate
| two Python values in the same way as this operator works when
| run on the database server. Useful for in-Python SQL expression
| evaluation functions, such as for ORM hybrid attributes, and the
| ORM "evaluator" used to match objects in a session after a multi-row
| update or delete.
|
| e.g.::
|
| >>> expr = column("x").op("+", python_impl=lambda a, b: a + b)("y")
|
| The operator for the above expression will also work for non-SQL
| left and right objects::
|
| >>> expr.operator(5, 10)
| 15
|
| .. versionadded:: 2.0
|
|
| .. seealso::
|
| :meth:`.Operators.bool_op`
|
| :ref:`types_operators`
|
| :ref:`relationship_custom_operator`
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.selectable.Selectable:
|
| 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.
|
| 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.
|
| 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`.
|
| .. deprecated:: 1.4 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.
|
| ----------------------------------------------------------------------
| Readonly properties inherited from sqlalchemy.sql.selectable.ReturnsRows:
|
| selectable
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.elements.ClauseElement:
|
| __bool__(self)
|
| __getstate__(self)
| Helper for pickle.
|
| __repr__(self)
| Return repr(self).
|
| compare(self, other: 'ClauseElement', **kw: 'Any') -> 'bool'
| Compare this :class:`_expression.ClauseElement` to
| the given :class:`_expression.ClauseElement`.
|
| Subclasses should override the default behavior, which is a
| straight identity comparison.
|
| \**kw are arguments consumed by subclass ``compare()`` methods and
| may be used to modify the criteria for comparison
| (see :class:`_expression.ColumnElement`).
|
| params(self, _ClauseElement__optionaldict: 'Optional[Mapping[str, Any]]' = None, **kwargs: 'Any') -> 'Self'
| Return a copy with :func:`_expression.bindparam` elements
| replaced.
|
| Returns a copy of this ClauseElement with
| :func:`_expression.bindparam`
| elements replaced with values taken from the given dictionary::
|
| >>> clause = column("x") + bindparam("foo")
| >>> print(clause.compile().params)
| {'foo':None}
| >>> print(clause.params({"foo": 7}).compile().params)
| {'foo':7}
|
| unique_params(self, _ClauseElement__optionaldict: 'Optional[Dict[str, Any]]' = None, **kwargs: 'Any') -> 'Self'
| Return a copy with :func:`_expression.bindparam` elements
| replaced.
|
| Same functionality as :meth:`_expression.ClauseElement.params`,
| except adds `unique=True`
| to affected bind parameters so that multiple statements can be
| used.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.elements.ClauseElement:
|
| is_clause_element = True
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.cache_key.HasCacheKey:
|
| inherit_cache = None
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_instancemethod(fn: '_F') -> '_F'
| Decorate a method memoize its return value.
|
| :meta private:
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_attribute = <class 'sqlalchemy.util.langhelpers.HasMemoized.m...
| A read-only @property that is only evaluated once.
|
| :meta private:
|
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.visitors.HasTraverseInternals:
|
| get_children(self, *, omit_attrs: 'Tuple[str, ...]' = (), **kw: 'Any') -> 'Iterable[HasTraverseInternals]'
| Return immediate child :class:`.visitors.HasTraverseInternals`
| elements of this :class:`.visitors.HasTraverseInternals`.
|
| This is used for visit traversal.
|
| \**kw may contain flags that change the collection that is
| returned, for example to return a subset of items in order to
| cut down on larger traversals, or to return child items from a
| different context (such as schema-level collections instead of
| clause-level).
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.elements.CompilerElement:
|
| __str__(self) -> 'str'
| Return str(self).
|
| compile(self, bind: 'Optional[_HasDialect]' = None, dialect: 'Optional[Dialect]' = None, **kw: 'Any') -> 'Compiled'
| Compile this SQL expression.
|
| The return value is a :class:`~.Compiled` object.
| Calling ``str()`` or ``unicode()`` on the returned value will yield a
| string representation of the result. The
| :class:`~.Compiled` object also can return a
| dictionary of bind parameter names and values
| using the ``params`` accessor.
|
| :param bind: An :class:`.Connection` or :class:`.Engine` which
| can provide a :class:`.Dialect` in order to generate a
| :class:`.Compiled` object. If the ``bind`` and
| ``dialect`` parameters are both omitted, a default SQL compiler
| is used.
|
| :param column_keys: Used for INSERT and UPDATE statements, a list of
| column names which should be present in the VALUES clause of the
| compiled statement. If ``None``, all columns from the target table
| object are rendered.
|
| :param dialect: A :class:`.Dialect` instance which can generate
| a :class:`.Compiled` object. This argument takes precedence over
| the ``bind`` argument.
|
| :param compile_kwargs: optional dictionary of additional parameters
| that will be passed through to the compiler within all "visit"
| methods. This allows any custom flag to be passed through to
| a custom compilation construct, for example. It is also used
| for the case of passing the ``literal_binds`` flag through::
|
| from sqlalchemy.sql import table, column, select
|
| t = table("t", column("x"))
|
| s = select(t).where(t.c.x == 5)
|
| print(s.compile(compile_kwargs={"literal_binds": True}))
|
| .. seealso::
|
| :ref:`faq_sql_expression_string`
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.elements.CompilerElement:
|
| stringify_dialect = 'default'
sqlalchemy.FunctionElement
Python Library Documentation: class FunctionElement in module sqlalchemy.sql.functions
class FunctionElement(sqlalchemy.sql.base.Executable, sqlalchemy.sql.elements.ColumnElement, sqlalchemy.sql.selectable.FromClause, sqlalchemy.sql.base.Generative)
| FunctionElement(*clauses: '_ColumnExpressionOrLiteralArgument[Any]') -> 'None'
|
| Base for SQL function-oriented constructs.
|
| This is a `generic type <https://peps.python.org/pep-0484/#generics>`_,
| meaning that type checkers and IDEs can be instructed on the types to
| expect in a :class:`_engine.Result` for this function. See
| :class:`.GenericFunction` for an example of how this is done.
|
| .. seealso::
|
| :ref:`tutorial_functions` - in the :ref:`unified_tutorial`
|
| :class:`.Function` - named SQL function.
|
| :data:`.func` - namespace which produces registered or ad-hoc
| :class:`.Function` instances.
|
| :class:`.GenericFunction` - allows creation of registered function
| types.
|
| Method resolution order:
| FunctionElement
| sqlalchemy.sql.base.Executable
| sqlalchemy.sql.roles.StatementRole
| sqlalchemy.sql.elements.ColumnElement
| sqlalchemy.sql.roles.ColumnArgumentOrKeyRole
| sqlalchemy.sql.roles.ColumnArgumentRole
| sqlalchemy.sql.roles.StatementOptionRole
| sqlalchemy.sql.roles.WhereHavingRole
| sqlalchemy.sql.roles.OnClauseRole
| sqlalchemy.sql.roles.BinaryElementRole
| sqlalchemy.sql.roles.OrderByRole
| sqlalchemy.sql.selectable.FromClause
| sqlalchemy.sql.roles.AnonymizedFromClauseRole
| sqlalchemy.sql.roles.StrictFromClauseRole
| sqlalchemy.sql.roles.FromClauseRole
| sqlalchemy.sql.roles.ColumnsClauseRole
| sqlalchemy.sql.roles.JoinTargetRole
| sqlalchemy.sql.roles.AllowsLambdaRole
| sqlalchemy.sql.roles.ByOfRole
| sqlalchemy.sql.roles.UsesInspection
| sqlalchemy.sql.roles.ColumnListRole
| sqlalchemy.sql.roles.LimitOffsetRole
| sqlalchemy.sql.roles.DMLColumnRole
| sqlalchemy.sql.roles.DDLConstraintColumnRole
| sqlalchemy.sql.roles.DDLExpressionRole
| sqlalchemy.sql.roles.StructuralRole
| sqlalchemy.sql.elements.SQLColumnExpression
| sqlalchemy.sql.elements.SQLCoreOperations
| sqlalchemy.sql.roles.ExpressionElementRole
| sqlalchemy.sql.roles.TypedColumnsClauseRole
| typing.Generic
| sqlalchemy.sql.operators.ColumnOperators
| sqlalchemy.sql.operators.Operators
| sqlalchemy.util.langhelpers.TypingOnly
| sqlalchemy.sql.selectable.Selectable
| sqlalchemy.sql.selectable.ReturnsRows
| sqlalchemy.sql.roles.ReturnsRowsRole
| sqlalchemy.sql.roles.SQLRole
| sqlalchemy.sql.elements.DQLDMLClauseElement
| sqlalchemy.sql.elements.ClauseElement
| sqlalchemy.sql.annotation.SupportsWrappingAnnotations
| sqlalchemy.sql.annotation.SupportsAnnotations
| sqlalchemy.sql.cache_key.MemoizedHasCacheKey
| sqlalchemy.sql.cache_key.HasCacheKey
| sqlalchemy.sql.base.Generative
| sqlalchemy.util.langhelpers.HasMemoized
| sqlalchemy.sql.traversals.HasCopyInternals
| sqlalchemy.sql.visitors.ExternallyTraversible
| sqlalchemy.sql.visitors.HasTraverseInternals
| sqlalchemy.sql.elements.CompilerElement
| sqlalchemy.sql.visitors.Visitable
| builtins.object
|
| Methods defined here:
|
| __init__(self, *clauses: '_ColumnExpressionOrLiteralArgument[Any]') -> 'None'
| Construct a :class:`.FunctionElement`.
|
| :param \*clauses: list of column expressions that form the arguments
| of the SQL function call.
|
| :param \**kwargs: additional kwargs are typically consumed by
| subclasses.
|
| .. seealso::
|
| :data:`.func`
|
| :class:`.Function`
|
| alias(self, name: 'Optional[str]' = None, joins_implicitly: 'bool' = False) -> 'TableValuedAlias'
| Produce a :class:`_expression.Alias` construct against this
| :class:`.FunctionElement`.
|
| .. tip::
|
| The :meth:`_functions.FunctionElement.alias` method is part of the
| mechanism by which "table valued" SQL functions are created.
| However, most use cases are covered by higher level methods on
| :class:`_functions.FunctionElement` including
| :meth:`_functions.FunctionElement.table_valued`, and
| :meth:`_functions.FunctionElement.column_valued`.
|
| This construct wraps the function in a named alias which
| is suitable for the FROM clause, in the style accepted for example
| by PostgreSQL. A column expression is also provided using the
| special ``.column`` attribute, which may
| be used to refer to the output of the function as a scalar value
| in the columns or where clause, for a backend such as PostgreSQL.
|
| For a full table-valued expression, use the
| :meth:`_functions.FunctionElement.table_valued` method first to
| establish named columns.
|
| e.g.:
|
| .. sourcecode:: pycon+sql
|
| >>> from sqlalchemy import func, select, column
| >>> data_view = func.unnest([1, 2, 3]).alias("data_view")
| >>> print(select(data_view.column))
| {printsql}SELECT data_view
| FROM unnest(:unnest_1) AS data_view
|
| The :meth:`_functions.FunctionElement.column_valued` method provides
| a shortcut for the above pattern:
|
| .. sourcecode:: pycon+sql
|
| >>> data_view = func.unnest([1, 2, 3]).column_valued("data_view")
| >>> print(select(data_view))
| {printsql}SELECT data_view
| FROM unnest(:unnest_1) AS data_view
|
| .. versionadded:: 1.4.0b2 Added the ``.column`` accessor
|
| :param name: alias name, will be rendered as ``AS <name>`` in the
| FROM clause
|
| :param joins_implicitly: when True, the table valued function may be
| used in the FROM clause without any explicit JOIN to other tables
| in the SQL query, and no "cartesian product" warning will be
| generated. May be useful for SQL functions such as
| ``func.json_each()``.
|
| .. versionadded:: 1.4.33
|
| .. seealso::
|
| :ref:`tutorial_functions_table_valued` -
| in the :ref:`unified_tutorial`
|
| :meth:`_functions.FunctionElement.table_valued`
|
| :meth:`_functions.FunctionElement.scalar_table_valued`
|
| :meth:`_functions.FunctionElement.column_valued`
|
| as_comparison(self, left_index: 'int', right_index: 'int') -> 'FunctionAsBinary'
| Interpret this expression as a boolean comparison between two
| values.
|
| This method is used for an ORM use case described at
| :ref:`relationship_custom_operator_sql_function`.
|
| A hypothetical SQL function "is_equal()" which compares to values
| for equality would be written in the Core expression language as::
|
| expr = func.is_equal("a", "b")
|
| If "is_equal()" above is comparing "a" and "b" for equality, the
| :meth:`.FunctionElement.as_comparison` method would be invoked as::
|
| expr = func.is_equal("a", "b").as_comparison(1, 2)
|
| Where above, the integer value "1" refers to the first argument of the
| "is_equal()" function and the integer value "2" refers to the second.
|
| This would create a :class:`.BinaryExpression` that is equivalent to::
|
| BinaryExpression("a", "b", operator=op.eq)
|
| However, at the SQL level it would still render as
| "is_equal('a', 'b')".
|
| The ORM, when it loads a related object or collection, needs to be able
| to manipulate the "left" and "right" sides of the ON clause of a JOIN
| expression. The purpose of this method is to provide a SQL function
| construct that can also supply this information to the ORM, when used
| with the :paramref:`_orm.relationship.primaryjoin` parameter. The
| return value is a containment object called :class:`.FunctionAsBinary`.
|
| An ORM example is as follows::
|
| class Venue(Base):
| __tablename__ = "venue"
| id = Column(Integer, primary_key=True)
| name = Column(String)
|
| descendants = relationship(
| "Venue",
| primaryjoin=func.instr(
| remote(foreign(name)), name + "/"
| ).as_comparison(1, 2)
| == 1,
| viewonly=True,
| order_by=name,
| )
|
| Above, the "Venue" class can load descendant "Venue" objects by
| determining if the name of the parent Venue is contained within the
| start of the hypothetical descendant value's name, e.g. "parent1" would
| match up to "parent1/child1", but not to "parent2/child1".
|
| Possible use cases include the "materialized path" example given above,
| as well as making use of special SQL functions such as geometric
| functions to create join conditions.
|
| :param left_index: the integer 1-based index of the function argument
| that serves as the "left" side of the expression.
| :param right_index: the integer 1-based index of the function argument
| that serves as the "right" side of the expression.
|
| .. versionadded:: 1.3
|
| .. seealso::
|
| :ref:`relationship_custom_operator_sql_function` -
| example use within the ORM
|
| c(...)
| synonym for :attr:`.FunctionElement.columns`.
|
| clauses(...)
| Return the underlying :class:`.ClauseList` which contains
| the arguments for this :class:`.FunctionElement`.
|
| column_valued(self, name: 'Optional[str]' = None, joins_implicitly: 'bool' = False) -> 'TableValuedColumn[_T]'
| Return this :class:`_functions.FunctionElement` as a column expression that
| selects from itself as a FROM clause.
|
| E.g.:
|
| .. sourcecode:: pycon+sql
|
| >>> from sqlalchemy import select, func
| >>> gs = func.generate_series(1, 5, -1).column_valued()
| >>> print(select(gs))
| {printsql}SELECT anon_1
| FROM generate_series(:generate_series_1, :generate_series_2, :generate_series_3) AS anon_1
|
| This is shorthand for::
|
| gs = func.generate_series(1, 5, -1).alias().column
|
| :param name: optional name to assign to the alias name that's generated.
| If omitted, a unique anonymizing name is used.
|
| :param joins_implicitly: when True, the "table" portion of the column
| valued function may be a member of the FROM clause without any
| explicit JOIN to other tables in the SQL query, and no "cartesian
| product" warning will be generated. May be useful for SQL functions
| such as ``func.json_array_elements()``.
|
| .. versionadded:: 1.4.46
|
| .. seealso::
|
| :ref:`tutorial_functions_column_valued` - in the :ref:`unified_tutorial`
|
| :ref:`postgresql_column_valued` - in the :ref:`postgresql_toplevel` documentation
|
| :meth:`_functions.FunctionElement.table_valued`
|
| columns(...)
| The set of columns exported by this :class:`.FunctionElement`.
|
| This is a placeholder collection that allows the function to be
| placed in the FROM clause of a statement:
|
| .. sourcecode:: pycon+sql
|
| >>> from sqlalchemy import column, select, func
| >>> stmt = select(column("x"), column("y")).select_from(func.myfunction())
| >>> print(stmt)
| {printsql}SELECT x, y FROM myfunction()
|
| The above form is a legacy feature that is now superseded by the
| fully capable :meth:`_functions.FunctionElement.table_valued`
| method; see that method for details.
|
| .. seealso::
|
| :meth:`_functions.FunctionElement.table_valued` - generates table-valued
| SQL function expressions.
|
| filter(self, *criterion: '_ColumnExpressionArgument[bool]') -> 'Union[Self, FunctionFilter[_T]]'
| Produce a FILTER clause against this function.
|
| Used against aggregate and window functions,
| for database backends that support the "FILTER" clause.
|
| The expression::
|
| func.count(1).filter(True)
|
| is shorthand for::
|
| from sqlalchemy import funcfilter
|
| funcfilter(func.count(1), True)
|
| .. seealso::
|
| :ref:`tutorial_functions_within_group` -
| in the :ref:`unified_tutorial`
|
| :class:`.FunctionFilter`
|
| :func:`.funcfilter`
|
| over(self, *, partition_by: 'Optional[_ByArgument]' = None, order_by: 'Optional[_ByArgument]' = None, rows: 'Optional[Tuple[Optional[int], Optional[int]]]' = None, range_: 'Optional[Tuple[Optional[int], Optional[int]]]' = None, groups: 'Optional[Tuple[Optional[int], Optional[int]]]' = None) -> 'Over[_T]'
| Produce an OVER clause against this function.
|
| Used against aggregate or so-called "window" functions,
| for database backends that support window functions.
|
| The expression::
|
| func.row_number().over(order_by="x")
|
| is shorthand for::
|
| from sqlalchemy import over
|
| over(func.row_number(), order_by="x")
|
| See :func:`_expression.over` for a full description.
|
| .. seealso::
|
| :func:`_expression.over`
|
| :ref:`tutorial_window_functions` - in the :ref:`unified_tutorial`
|
| scalar_table_valued(self, name: 'str', type_: 'Optional[_TypeEngineArgument[_T]]' = None) -> 'ScalarFunctionColumn[_T]'
| Return a column expression that's against this
| :class:`_functions.FunctionElement` as a scalar
| table-valued expression.
|
| The returned expression is similar to that returned by a single column
| accessed off of a :meth:`_functions.FunctionElement.table_valued`
| construct, except no FROM clause is generated; the function is rendered
| in the similar way as a scalar subquery.
|
| E.g.:
|
| .. sourcecode:: pycon+sql
|
| >>> from sqlalchemy import func, select
| >>> fn = func.jsonb_each("{'k', 'v'}").scalar_table_valued("key")
| >>> print(select(fn))
| {printsql}SELECT (jsonb_each(:jsonb_each_1)).key
|
| .. versionadded:: 1.4.0b2
|
| .. seealso::
|
| :meth:`_functions.FunctionElement.table_valued`
|
| :meth:`_functions.FunctionElement.alias`
|
| :meth:`_functions.FunctionElement.column_valued`
|
| select(self) -> 'Select[Tuple[_T]]'
| Produce a :func:`_expression.select` construct
| against this :class:`.FunctionElement`.
|
| This is shorthand for::
|
| s = select(function_element)
|
| self_group(self, against: 'Optional[OperatorType]' = None) -> 'ClauseElement'
| 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.
|
| table_valued(self, *expr: '_ColumnExpressionOrStrLabelArgument[Any]', **kw: 'Any') -> 'TableValuedAlias'
| Return a :class:`_sql.TableValuedAlias` representation of this
| :class:`_functions.FunctionElement` with table-valued expressions added.
|
| e.g. to use the SQLite form of ``generate_series()`` (including
| hidden columns "start", "stop", "step"):
|
| .. sourcecode:: pycon+sql
|
| >>> fn = func.generate_series(1, 5).table_valued(
| ... "value", "start", "stop", "step"
| ... )
|
| >>> print(select(fn))
| {printsql}SELECT anon_1.value, anon_1.start, anon_1.stop, anon_1.step
| FROM generate_series(:generate_series_1, :generate_series_2) AS anon_1{stop}
|
| >>> print(select(fn.c.value, fn.c.stop).where(fn.c.value > 2))
| {printsql}SELECT anon_1.value, anon_1.stop
| FROM generate_series(:generate_series_1, :generate_series_2) AS anon_1
| WHERE anon_1.value > :value_1{stop}
|
| Backends like PostgreSQL need the accessed columns to be explicitly
| named in "AS" clause. To achieve this, use
| :meth:`_sql.TableValuedAlias.render_derived`; be sure to consult the
| :ref:`PostgreSQL-specific documentation for table valued functions
| <postgresql_table_valued>` for additional examples:
|
| .. sourcecode:: pycon+sql
|
| >>> fn = func.generate_series(1, 5).table_valued("value").render_derived()
|
| >>> print(select(fn))
| {printsql}SELECT anon_1.value FROM
| generate_series(:generate_series_1, :generate_series_2) AS anon_1(value){stop}
|
| A WITH ORDINALITY expression may be generated by passing the keyword
| argument :paramref:`.FunctionElement.table_valued.with_ordinality`,
| illustrated below using PostgreSQL's syntax:
|
| .. sourcecode:: pycon+sql
|
| >>> fn = func.generate_series(4, 1, -1).table_valued(
| ... "gen", with_ordinality="ordinality"
| ... )
| >>> print(select(fn.render_derived()))
| {printsql}SELECT anon_1.gen, anon_1.ordinality
| FROM generate_series(:generate_series_1, :generate_series_2, :generate_series_3)
| WITH ORDINALITY AS anon_1(gen, ordinality)
|
| :param \*expr: A series of string column names that will be added to the
| ``.c`` collection of the resulting :class:`_sql.TableValuedAlias`
| construct as columns. :func:`_sql.column` objects with or without
| datatypes may also be used.
|
| :param name: optional name to assign to the alias name that's generated.
| If omitted, a unique anonymizing name is used.
|
| :param with_ordinality: string name that when present results in the
| ``WITH ORDINALITY`` clause being added to the alias, and the given
| string name will be added as a column to the .c collection
| of the resulting :class:`_sql.TableValuedAlias`.
|
| :param joins_implicitly: when True, the table valued function may be
| used in the FROM clause without any explicit JOIN to other tables
| in the SQL query, and no "cartesian product" warning will be generated.
| May be useful for SQL functions such as ``func.json_each()``.
|
| .. versionadded:: 1.4.33
|
| .. versionadded:: 1.4.0b2
|
|
| .. seealso::
|
| :ref:`tutorial_functions_table_valued` - in the :ref:`unified_tutorial`
|
| :ref:`Table-Valued Functions on PostgreSQL <postgresql_table_valued>` - in the :ref:`postgresql_toplevel` documentation
|
| :meth:`_functions.FunctionElement.scalar_table_valued` - variant of
| :meth:`_functions.FunctionElement.table_valued` which delivers the
| complete table valued expression as a scalar column expression
|
| :meth:`_functions.FunctionElement.column_valued`
|
| :meth:`_sql.TableValuedAlias.render_derived` - renders the alias
| using a derived column clause, e.g. ``AS name(col1, col2, ...)``
|
| within_group(self, *order_by: '_ColumnExpressionArgument[Any]') -> 'WithinGroup[_T]'
| Produce a WITHIN GROUP (ORDER BY expr) clause against this function.
|
| Used against so-called "ordered set aggregate" and "hypothetical
| set aggregate" functions, including :class:`.percentile_cont`,
| :class:`.rank`, :class:`.dense_rank`, etc.
|
| See :func:`_expression.within_group` for a full description.
|
| .. seealso::
|
| :ref:`tutorial_functions_within_group` -
| in the :ref:`unified_tutorial`
|
| within_group_type(self, within_group: 'WithinGroup[_S]') -> 'Optional[TypeEngine[_S]]'
| For types that define their return type as based on the criteria
| within a WITHIN GROUP (ORDER BY) expression, called by the
| :class:`.WithinGroup` construct.
|
| Returns None by default, in which case the function's normal ``.type``
| is used.
|
| ----------------------------------------------------------------------
| Readonly properties defined here:
|
| entity_namespace
| overrides FromClause.entity_namespace as functions are generally
| column expressions and not FromClauses.
|
| exported_columns
| A :class:`_expression.ColumnCollection`
| that represents the "exported"
| columns of this :class:`_expression.Selectable`.
|
| 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`
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'_is_clone_of': 'Any', '_table_value_type': 'Option...
|
| __orig_bases__ = (<class 'sqlalchemy.sql.base.Executable'>, sqlalchemy...
|
| __parameters__ = (~_T,)
|
| packagenames = ()
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.base.Executable:
|
| execution_options(self, **kw: 'Any') -> 'Self'
| Set non-SQL options for the statement which take effect during
| execution.
|
| Execution options can be set at many scopes, including per-statement,
| per-connection, or per execution, using methods such as
| :meth:`_engine.Connection.execution_options` and parameters which
| accept a dictionary of options such as
| :paramref:`_engine.Connection.execute.execution_options` and
| :paramref:`_orm.Session.execute.execution_options`.
|
| The primary characteristic of an execution option, as opposed to
| other kinds of options such as ORM loader options, is that
| **execution options never affect the compiled SQL of a query, only
| things that affect how the SQL statement itself is invoked or how
| results are fetched**. That is, execution options are not part of
| what's accommodated by SQL compilation nor are they considered part of
| the cached state of a statement.
|
| The :meth:`_sql.Executable.execution_options` method is
| :term:`generative`, as
| is the case for the method as applied to the :class:`_engine.Engine`
| and :class:`_orm.Query` objects, which means when the method is called,
| a copy of the object is returned, which applies the given parameters to
| that new copy, but leaves the original unchanged::
|
| statement = select(table.c.x, table.c.y)
| new_statement = statement.execution_options(my_option=True)
|
| An exception to this behavior is the :class:`_engine.Connection`
| object, where the :meth:`_engine.Connection.execution_options` method
| is explicitly **not** generative.
|
| The kinds of options that may be passed to
| :meth:`_sql.Executable.execution_options` and other related methods and
| parameter dictionaries include parameters that are explicitly consumed
| by SQLAlchemy Core or ORM, as well as arbitrary keyword arguments not
| defined by SQLAlchemy, which means the methods and/or parameter
| dictionaries may be used for user-defined parameters that interact with
| custom code, which may access the parameters using methods such as
| :meth:`_sql.Executable.get_execution_options` and
| :meth:`_engine.Connection.get_execution_options`, or within selected
| event hooks using a dedicated ``execution_options`` event parameter
| such as
| :paramref:`_events.ConnectionEvents.before_execute.execution_options`
| or :attr:`_orm.ORMExecuteState.execution_options`, e.g.::
|
| from sqlalchemy import event
|
|
| @event.listens_for(some_engine, "before_execute")
| def _process_opt(conn, statement, multiparams, params, execution_options):
| "run a SQL function before invoking a statement"
|
| if execution_options.get("do_special_thing", False):
| conn.exec_driver_sql("run_special_function()")
|
| Within the scope of options that are explicitly recognized by
| SQLAlchemy, most apply to specific classes of objects and not others.
| The most common execution options include:
|
| * :paramref:`_engine.Connection.execution_options.isolation_level` -
| sets the isolation level for a connection or a class of connections
| via an :class:`_engine.Engine`. This option is accepted only
| by :class:`_engine.Connection` or :class:`_engine.Engine`.
|
| * :paramref:`_engine.Connection.execution_options.stream_results` -
| indicates results should be fetched using a server side cursor;
| this option is accepted by :class:`_engine.Connection`, by the
| :paramref:`_engine.Connection.execute.execution_options` parameter
| on :meth:`_engine.Connection.execute`, and additionally by
| :meth:`_sql.Executable.execution_options` on a SQL statement object,
| as well as by ORM constructs like :meth:`_orm.Session.execute`.
|
| * :paramref:`_engine.Connection.execution_options.compiled_cache` -
| indicates a dictionary that will serve as the
| :ref:`SQL compilation cache <sql_caching>`
| for a :class:`_engine.Connection` or :class:`_engine.Engine`, as
| well as for ORM methods like :meth:`_orm.Session.execute`.
| Can be passed as ``None`` to disable caching for statements.
| This option is not accepted by
| :meth:`_sql.Executable.execution_options` as it is inadvisable to
| carry along a compilation cache within a statement object.
|
| * :paramref:`_engine.Connection.execution_options.schema_translate_map`
| - a mapping of schema names used by the
| :ref:`Schema Translate Map <schema_translating>` feature, accepted
| by :class:`_engine.Connection`, :class:`_engine.Engine`,
| :class:`_sql.Executable`, as well as by ORM constructs
| like :meth:`_orm.Session.execute`.
|
| .. seealso::
|
| :meth:`_engine.Connection.execution_options`
|
| :paramref:`_engine.Connection.execute.execution_options`
|
| :paramref:`_orm.Session.execute.execution_options`
|
| :ref:`orm_queryguide_execution_options` - documentation on all
| ORM-specific execution options
|
| get_execution_options(self) -> '_ExecuteOptions'
| Get the non-SQL options which will take effect during execution.
|
| .. versionadded:: 1.3
|
| .. seealso::
|
| :meth:`.Executable.execution_options`
|
| options(self, *options: 'ExecutableOption') -> 'Self'
| Apply options to this statement.
|
| In the general sense, options are any kind of Python object
| that can be interpreted by the SQL compiler for the statement.
| These options can be consumed by specific dialects or specific kinds
| of compilers.
|
| The most commonly known kind of option are the ORM level options
| that apply "eager load" and other loading behaviors to an ORM
| query. However, options can theoretically be used for many other
| purposes.
|
| For background on specific kinds of options for specific kinds of
| statements, refer to the documentation for those option objects.
|
| .. versionchanged:: 1.4 - added :meth:`.Executable.options` to
| Core statement objects towards the goal of allowing unified
| Core / ORM querying capabilities.
|
| .. seealso::
|
| :ref:`loading_columns` - refers to options specific to the usage
| of ORM queries
|
| :ref:`relationship_loader_options` - refers to options specific
| to the usage of ORM queries
|
| ----------------------------------------------------------------------
| Data descriptors inherited from sqlalchemy.sql.base.Executable:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.base.Executable:
|
| is_delete = False
|
| is_dml = False
|
| is_from_statement = False
|
| is_insert = False
|
| is_select = False
|
| is_text = False
|
| is_update = False
|
| supports_execution = True
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.elements.ColumnElement:
|
| __getattr__(self, key: 'str') -> 'Any'
|
| __setstate__(self, state)
|
| base_columns(...)
|
| cast(self, type_: '_TypeEngineArgument[_OPT]') -> 'Cast[_OPT]'
| Produce a type cast, i.e. ``CAST(<expression> AS <type>)``.
|
| This is a shortcut to the :func:`_expression.cast` function.
|
| .. seealso::
|
| :ref:`tutorial_casts`
|
| :func:`_expression.cast`
|
| :func:`_expression.type_coerce`
|
| comparator(...)
|
| label(self, name: 'Optional[str]') -> 'Label[_T]'
| Produce a column label, i.e. ``<columnname> AS <name>``.
|
| This is a shortcut to the :func:`_expression.label` function.
|
| If 'name' is ``None``, an anonymous label name will be generated.
|
| operate(self, op: 'operators.OperatorType', *other: 'Any', **kwargs: 'Any') -> 'ColumnElement[Any]'
| Operate on an argument.
|
| This is the lowest level of operation, raises
| :class:`NotImplementedError` by default.
|
| Overriding this on a subclass can allow common
| behavior to be applied to all operations.
| For example, overriding :class:`.ColumnOperators`
| to apply ``func.lower()`` to the left and right
| side::
|
| class MyComparator(ColumnOperators):
| def operate(self, op, other, **kwargs):
| return op(func.lower(self), func.lower(other), **kwargs)
|
| :param op: Operator callable.
| :param \*other: the 'other' side of the operation. Will
| be a single scalar for most operations.
| :param \**kwargs: modifiers. These may be passed by special
| operators such as :meth:`ColumnOperators.contains`.
|
| proxy_set(...)
| set of all columns we are proxying
|
| as of 2.0 this is explicitly deannotated columns. previously it was
| effectively deannotated columns but wasn't enforced. annotated
| columns should basically not go into sets if at all possible because
| their hashing behavior is very non-performant.
|
| reverse_operate(self, op: 'operators.OperatorType', other: 'Any', **kwargs: 'Any') -> 'ColumnElement[Any]'
| Reverse operate on an argument.
|
| Usage is the same as :meth:`operate`.
|
| shares_lineage(self, othercolumn: 'ColumnElement[Any]') -> 'bool'
| Return True if the given :class:`_expression.ColumnElement`
| has a common ancestor to this :class:`_expression.ColumnElement`.
|
| type(...)
|
| ----------------------------------------------------------------------
| Readonly properties inherited from sqlalchemy.sql.elements.ColumnElement:
|
| anon_key_label
| .. deprecated:: 1.4 The :attr:`_expression.ColumnElement.anon_key_label` attribute is now private, and the public accessor is deprecated.
|
| anon_label
| .. deprecated:: 1.4 The :attr:`_expression.ColumnElement.anon_label` attribute is now private, and the public accessor is deprecated.
|
| expression
| Return a column expression.
|
| Part of the inspection interface; returns self.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.elements.ColumnElement:
|
| __visit_name__ = 'column_element'
|
| foreign_keys = frozenset()
|
| key = None
|
| primary_key = False
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.selectable.FromClause:
|
| description(...)
| A brief description of this :class:`_expression.FromClause`.
|
| Used primarily for error message formatting.
|
| 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.
|
| 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
|
| 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`
|
| 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
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.selectable.FromClause:
|
| is_selectable = True
|
| named_with_column = False
|
| schema = None
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.AllowsLambdaRole:
|
| allows_lambda = True
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.UsesInspection:
|
| uses_inspection = True
|
| ----------------------------------------------------------------------
| Class methods inherited from typing.Generic:
|
| __class_getitem__(...)
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__(...)
| Function to initialize subclasses.
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.operators.ColumnOperators:
|
| __add__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``+`` operator.
|
| In a column context, produces the clause ``a + b``
| if the parent object has non-string affinity.
| If the parent object has a string affinity,
| produces the concatenation operator, ``a || b`` -
| see :meth:`.ColumnOperators.concat`.
|
| __contains__(self, other: 'Any') -> 'ColumnOperators'
|
| __eq__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``==`` operator.
|
| In a column context, produces the clause ``a = b``.
| If the target is ``None``, produces ``a IS NULL``.
|
| __floordiv__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``//`` operator.
|
| In a column context, produces the clause ``a / b``,
| which is the same as "truediv", but considers the result
| type to be integer.
|
| .. versionadded:: 2.0
|
| __ge__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``>=`` operator.
|
| In a column context, produces the clause ``a >= b``.
|
| __getitem__(self, index: 'Any') -> 'ColumnOperators'
| Implement the [] operator.
|
| This can be used by some database-specific types
| such as PostgreSQL ARRAY and HSTORE.
|
| __gt__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``>`` operator.
|
| In a column context, produces the clause ``a > b``.
|
| __hash__(self, /) from builtins.object
| Return hash(self).
|
| __le__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``<=`` operator.
|
| In a column context, produces the clause ``a <= b``.
|
| __lshift__(self, other: 'Any') -> 'ColumnOperators'
| implement the << operator.
|
| Not used by SQLAlchemy core, this is provided
| for custom operator systems which want to use
| << as an extension point.
|
| __lt__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``<`` operator.
|
| In a column context, produces the clause ``a < b``.
|
| __mod__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``%`` operator.
|
| In a column context, produces the clause ``a % b``.
|
| __mul__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``*`` operator.
|
| In a column context, produces the clause ``a * b``.
|
| __ne__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``!=`` operator.
|
| In a column context, produces the clause ``a != b``.
| If the target is ``None``, produces ``a IS NOT NULL``.
|
| __neg__(self) -> 'ColumnOperators'
| Implement the ``-`` operator.
|
| In a column context, produces the clause ``-a``.
|
| __radd__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``+`` operator in reverse.
|
| See :meth:`.ColumnOperators.__add__`.
|
| __rfloordiv__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``//`` operator in reverse.
|
| See :meth:`.ColumnOperators.__floordiv__`.
|
| __rmod__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``%`` operator in reverse.
|
| See :meth:`.ColumnOperators.__mod__`.
|
| __rmul__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``*`` operator in reverse.
|
| See :meth:`.ColumnOperators.__mul__`.
|
| __rshift__(self, other: 'Any') -> 'ColumnOperators'
| implement the >> operator.
|
| Not used by SQLAlchemy core, this is provided
| for custom operator systems which want to use
| >> as an extension point.
|
| __rsub__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``-`` operator in reverse.
|
| See :meth:`.ColumnOperators.__sub__`.
|
| __rtruediv__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``/`` operator in reverse.
|
| See :meth:`.ColumnOperators.__truediv__`.
|
| __sub__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``-`` operator.
|
| In a column context, produces the clause ``a - b``.
|
| __truediv__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``/`` operator.
|
| In a column context, produces the clause ``a / b``, and
| considers the result type to be numeric.
|
| .. versionchanged:: 2.0 The truediv operator against two integers
| is now considered to return a numeric value. Behavior on specific
| backends may vary.
|
| all_(self) -> 'ColumnOperators'
| Produce an :func:`_expression.all_` clause against the
| parent object.
|
| See the documentation for :func:`_sql.all_` for examples.
|
| .. note:: be sure to not confuse the newer
| :meth:`_sql.ColumnOperators.all_` method with the **legacy**
| version of this method, the :meth:`_types.ARRAY.Comparator.all`
| method that's specific to :class:`_types.ARRAY`, which uses a
| different calling style.
|
| any_(self) -> 'ColumnOperators'
| Produce an :func:`_expression.any_` clause against the
| parent object.
|
| See the documentation for :func:`_sql.any_` for examples.
|
| .. note:: be sure to not confuse the newer
| :meth:`_sql.ColumnOperators.any_` method with the **legacy**
| version of this method, the :meth:`_types.ARRAY.Comparator.any`
| method that's specific to :class:`_types.ARRAY`, which uses a
| different calling style.
|
| asc(self) -> 'ColumnOperators'
| Produce a :func:`_expression.asc` clause against the
| parent object.
|
| between(self, cleft: 'Any', cright: 'Any', symmetric: 'bool' = False) -> 'ColumnOperators'
| Produce a :func:`_expression.between` clause against
| the parent object, given the lower and upper range.
|
| bitwise_and(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise AND operation, typically via the ``&``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_lshift(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise LSHIFT operation, typically via the ``<<``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_not(self) -> 'ColumnOperators'
| Produce a bitwise NOT operation, typically via the ``~``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_or(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise OR operation, typically via the ``|``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_rshift(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise RSHIFT operation, typically via the ``>>``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_xor(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise XOR operation, typically via the ``^``
| operator, or ``#`` for PostgreSQL.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| collate(self, collation: 'str') -> 'ColumnOperators'
| Produce a :func:`_expression.collate` clause against
| the parent object, given the collation string.
|
| .. seealso::
|
| :func:`_expression.collate`
|
| concat(self, other: 'Any') -> 'ColumnOperators'
| Implement the 'concat' operator.
|
| In a column context, produces the clause ``a || b``,
| or uses the ``concat()`` operator on MySQL.
|
| contains(self, other: 'Any', **kw: 'Any') -> 'ColumnOperators'
| Implement the 'contains' operator.
|
| Produces a LIKE expression that tests against a match for the middle
| of a string value:
|
| .. sourcecode:: sql
|
| column LIKE '%' || <other> || '%'
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.contains("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.contains.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.contains.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.contains.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.contains("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE '%' || :param || '%' ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.contains("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE '%' || :param || '%' ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.contains.autoescape`::
|
| somecolumn.contains("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.startswith`
|
| :meth:`.ColumnOperators.endswith`
|
| :meth:`.ColumnOperators.like`
|
| desc(self) -> 'ColumnOperators'
| Produce a :func:`_expression.desc` clause against the
| parent object.
|
| distinct(self) -> 'ColumnOperators'
| Produce a :func:`_expression.distinct` clause against the
| parent object.
|
| endswith(self, other: 'Any', escape: 'Optional[str]' = None, autoescape: 'bool' = False) -> 'ColumnOperators'
| Implement the 'endswith' operator.
|
| Produces a LIKE expression that tests against a match for the end
| of a string value:
|
| .. sourcecode:: sql
|
| column LIKE '%' || <other>
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.endswith("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.endswith.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.endswith.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.endswith.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.endswith("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE '%' || :param ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.endswith("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE '%' || :param ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.endswith.autoescape`::
|
| somecolumn.endswith("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.startswith`
|
| :meth:`.ColumnOperators.contains`
|
| :meth:`.ColumnOperators.like`
|
| icontains(self, other: 'Any', **kw: 'Any') -> 'ColumnOperators'
| Implement the ``icontains`` operator, e.g. case insensitive
| version of :meth:`.ColumnOperators.contains`.
|
| Produces a LIKE expression that tests against an insensitive match
| for the middle of a string value:
|
| .. sourcecode:: sql
|
| lower(column) LIKE '%' || lower(<other>) || '%'
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.icontains("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.icontains.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.icontains.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.icontains.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.icontains("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE '%' || lower(:param) || '%' ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.icontains("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE '%' || lower(:param) || '%' ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.contains.autoescape`::
|
| somecolumn.icontains("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.contains`
|
| iendswith(self, other: 'Any', escape: 'Optional[str]' = None, autoescape: 'bool' = False) -> 'ColumnOperators'
| Implement the ``iendswith`` operator, e.g. case insensitive
| version of :meth:`.ColumnOperators.endswith`.
|
| Produces a LIKE expression that tests against an insensitive match
| for the end of a string value:
|
| .. sourcecode:: sql
|
| lower(column) LIKE '%' || lower(<other>)
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.iendswith("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.iendswith.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.iendswith.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.iendswith.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.iendswith("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE '%' || lower(:param) ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.iendswith("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE '%' || lower(:param) ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.iendswith.autoescape`::
|
| somecolumn.endswith("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.endswith`
|
| ilike(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
| Implement the ``ilike`` operator, e.g. case insensitive LIKE.
|
| In a column context, produces an expression either of the form:
|
| .. sourcecode:: sql
|
| lower(a) LIKE lower(other)
|
| Or on backends that support the ILIKE operator:
|
| .. sourcecode:: sql
|
| a ILIKE other
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.ilike("%foobar%"))
|
| :param other: expression to be compared
| :param escape: optional escape character, renders the ``ESCAPE``
| keyword, e.g.::
|
| somecolumn.ilike("foo/%bar", escape="/")
|
| .. seealso::
|
| :meth:`.ColumnOperators.like`
|
| in_(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``in`` operator.
|
| In a column context, produces the clause ``column IN <other>``.
|
| The given parameter ``other`` may be:
|
| * A list of literal values,
| e.g.::
|
| stmt.where(column.in_([1, 2, 3]))
|
| In this calling form, the list of items is converted to a set of
| bound parameters the same length as the list given:
|
| .. sourcecode:: sql
|
| WHERE COL IN (?, ?, ?)
|
| * A list of tuples may be provided if the comparison is against a
| :func:`.tuple_` containing multiple expressions::
|
| from sqlalchemy import tuple_
|
| stmt.where(tuple_(col1, col2).in_([(1, 10), (2, 20), (3, 30)]))
|
| * An empty list,
| e.g.::
|
| stmt.where(column.in_([]))
|
| In this calling form, the expression renders an "empty set"
| expression. These expressions are tailored to individual backends
| and are generally trying to get an empty SELECT statement as a
| subquery. Such as on SQLite, the expression is:
|
| .. sourcecode:: sql
|
| WHERE col IN (SELECT 1 FROM (SELECT 1) WHERE 1!=1)
|
| .. versionchanged:: 1.4 empty IN expressions now use an
| execution-time generated SELECT subquery in all cases.
|
| * A bound parameter, e.g. :func:`.bindparam`, may be used if it
| includes the :paramref:`.bindparam.expanding` flag::
|
| stmt.where(column.in_(bindparam("value", expanding=True)))
|
| In this calling form, the expression renders a special non-SQL
| placeholder expression that looks like:
|
| .. sourcecode:: sql
|
| WHERE COL IN ([EXPANDING_value])
|
| This placeholder expression is intercepted at statement execution
| time to be converted into the variable number of bound parameter
| form illustrated earlier. If the statement were executed as::
|
| connection.execute(stmt, {"value": [1, 2, 3]})
|
| The database would be passed a bound parameter for each value:
|
| .. sourcecode:: sql
|
| WHERE COL IN (?, ?, ?)
|
| .. versionadded:: 1.2 added "expanding" bound parameters
|
| If an empty list is passed, a special "empty list" expression,
| which is specific to the database in use, is rendered. On
| SQLite this would be:
|
| .. sourcecode:: sql
|
| WHERE COL IN (SELECT 1 FROM (SELECT 1) WHERE 1!=1)
|
| .. versionadded:: 1.3 "expanding" bound parameters now support
| empty lists
|
| * a :func:`_expression.select` construct, which is usually a
| correlated scalar select::
|
| stmt.where(
| column.in_(select(othertable.c.y).where(table.c.x == othertable.c.x))
| )
|
| In this calling form, :meth:`.ColumnOperators.in_` renders as given:
|
| .. sourcecode:: sql
|
| WHERE COL IN (SELECT othertable.y
| FROM othertable WHERE othertable.x = table.x)
|
| :param other: a list of literals, a :func:`_expression.select`
| construct, or a :func:`.bindparam` construct that includes the
| :paramref:`.bindparam.expanding` flag set to True.
|
| is_(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``IS`` operator.
|
| Normally, ``IS`` is generated automatically when comparing to a
| value of ``None``, which resolves to ``NULL``. However, explicit
| usage of ``IS`` may be desirable if comparing to boolean values
| on certain platforms.
|
| .. seealso:: :meth:`.ColumnOperators.is_not`
|
| is_distinct_from(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``IS DISTINCT FROM`` operator.
|
| Renders "a IS DISTINCT FROM b" on most platforms;
| on some such as SQLite may render "a IS NOT b".
|
| is_not(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``IS NOT`` operator.
|
| Normally, ``IS NOT`` is generated automatically when comparing to a
| value of ``None``, which resolves to ``NULL``. However, explicit
| usage of ``IS NOT`` may be desirable if comparing to boolean values
| on certain platforms.
|
| .. versionchanged:: 1.4 The ``is_not()`` operator is renamed from
| ``isnot()`` in previous releases. The previous name remains
| available for backwards compatibility.
|
| .. seealso:: :meth:`.ColumnOperators.is_`
|
| is_not_distinct_from(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``IS NOT DISTINCT FROM`` operator.
|
| Renders "a IS NOT DISTINCT FROM b" on most platforms;
| on some such as SQLite may render "a IS b".
|
| .. versionchanged:: 1.4 The ``is_not_distinct_from()`` operator is
| renamed from ``isnot_distinct_from()`` in previous releases.
| The previous name remains available for backwards compatibility.
|
| isnot = is_not(self, other: 'Any') -> 'ColumnOperators'
|
| isnot_distinct_from = is_not_distinct_from(self, other: 'Any') -> 'ColumnOperators'
|
| istartswith(self, other: 'Any', escape: 'Optional[str]' = None, autoescape: 'bool' = False) -> 'ColumnOperators'
| Implement the ``istartswith`` operator, e.g. case insensitive
| version of :meth:`.ColumnOperators.startswith`.
|
| Produces a LIKE expression that tests against an insensitive
| match for the start of a string value:
|
| .. sourcecode:: sql
|
| lower(column) LIKE lower(<other>) || '%'
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.istartswith("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.istartswith.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.istartswith.escape` parameter will
| establish a given character as an escape character which can be of
| use when the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.istartswith.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.istartswith("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE lower(:param) || '%' ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.istartswith("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE lower(:param) || '%' ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.istartswith.autoescape`::
|
| somecolumn.istartswith("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.startswith`
|
| like(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
| Implement the ``like`` operator.
|
| In a column context, produces the expression:
|
| .. sourcecode:: sql
|
| a LIKE other
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.like("%foobar%"))
|
| :param other: expression to be compared
| :param escape: optional escape character, renders the ``ESCAPE``
| keyword, e.g.::
|
| somecolumn.like("foo/%bar", escape="/")
|
| .. seealso::
|
| :meth:`.ColumnOperators.ilike`
|
| match(self, other: 'Any', **kwargs: 'Any') -> 'ColumnOperators'
| Implements a database-specific 'match' operator.
|
| :meth:`_sql.ColumnOperators.match` attempts to resolve to
| a MATCH-like function or operator provided by the backend.
| Examples include:
|
| * PostgreSQL - renders ``x @@ plainto_tsquery(y)``
|
| .. versionchanged:: 2.0 ``plainto_tsquery()`` is used instead
| of ``to_tsquery()`` for PostgreSQL now; for compatibility with
| other forms, see :ref:`postgresql_match`.
|
|
| * MySQL - renders ``MATCH (x) AGAINST (y IN BOOLEAN MODE)``
|
| .. seealso::
|
| :class:`_mysql.match` - MySQL specific construct with
| additional features.
|
| * Oracle Database - renders ``CONTAINS(x, y)``
| * other backends may provide special implementations.
| * Backends without any special implementation will emit
| the operator as "MATCH". This is compatible with SQLite, for
| example.
|
| not_ilike(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
| implement the ``NOT ILIKE`` operator.
|
| This is equivalent to using negation with
| :meth:`.ColumnOperators.ilike`, i.e. ``~x.ilike(y)``.
|
| .. versionchanged:: 1.4 The ``not_ilike()`` operator is renamed from
| ``notilike()`` in previous releases. The previous name remains
| available for backwards compatibility.
|
| .. seealso::
|
| :meth:`.ColumnOperators.ilike`
|
| not_in(self, other: 'Any') -> 'ColumnOperators'
| implement the ``NOT IN`` operator.
|
| This is equivalent to using negation with
| :meth:`.ColumnOperators.in_`, i.e. ``~x.in_(y)``.
|
| In the case that ``other`` is an empty sequence, the compiler
| produces an "empty not in" expression. This defaults to the
| expression "1 = 1" to produce true in all cases. The
| :paramref:`_sa.create_engine.empty_in_strategy` may be used to
| alter this behavior.
|
| .. versionchanged:: 1.4 The ``not_in()`` operator is renamed from
| ``notin_()`` in previous releases. The previous name remains
| available for backwards compatibility.
|
| .. versionchanged:: 1.2 The :meth:`.ColumnOperators.in_` and
| :meth:`.ColumnOperators.not_in` operators
| now produce a "static" expression for an empty IN sequence
| by default.
|
| .. seealso::
|
| :meth:`.ColumnOperators.in_`
|
| not_like(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
| implement the ``NOT LIKE`` operator.
|
| This is equivalent to using negation with
| :meth:`.ColumnOperators.like`, i.e. ``~x.like(y)``.
|
| .. versionchanged:: 1.4 The ``not_like()`` operator is renamed from
| ``notlike()`` in previous releases. The previous name remains
| available for backwards compatibility.
|
| .. seealso::
|
| :meth:`.ColumnOperators.like`
|
| notilike = not_ilike(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
|
| notin_ = not_in(self, other: 'Any') -> 'ColumnOperators'
|
| notlike = not_like(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
|
| nulls_first(self) -> 'ColumnOperators'
| Produce a :func:`_expression.nulls_first` clause against the
| parent object.
|
| .. versionchanged:: 1.4 The ``nulls_first()`` operator is
| renamed from ``nullsfirst()`` in previous releases.
| The previous name remains available for backwards compatibility.
|
| nulls_last(self) -> 'ColumnOperators'
| Produce a :func:`_expression.nulls_last` clause against the
| parent object.
|
| .. versionchanged:: 1.4 The ``nulls_last()`` operator is
| renamed from ``nullslast()`` in previous releases.
| The previous name remains available for backwards compatibility.
|
| nullsfirst = nulls_first(self) -> 'ColumnOperators'
|
| nullslast = nulls_last(self) -> 'ColumnOperators'
|
| regexp_match(self, pattern: 'Any', flags: 'Optional[str]' = None) -> 'ColumnOperators'
| Implements a database-specific 'regexp match' operator.
|
| E.g.::
|
| stmt = select(table.c.some_column).where(
| table.c.some_column.regexp_match("^(b|c)")
| )
|
| :meth:`_sql.ColumnOperators.regexp_match` attempts to resolve to
| a REGEXP-like function or operator provided by the backend, however
| the specific regular expression syntax and flags available are
| **not backend agnostic**.
|
| Examples include:
|
| * PostgreSQL - renders ``x ~ y`` or ``x !~ y`` when negated.
| * Oracle Database - renders ``REGEXP_LIKE(x, y)``
| * SQLite - uses SQLite's ``REGEXP`` placeholder operator and calls into
| the Python ``re.match()`` builtin.
| * other backends may provide special implementations.
| * Backends without any special implementation will emit
| the operator as "REGEXP" or "NOT REGEXP". This is compatible with
| SQLite and MySQL, for example.
|
| Regular expression support is currently implemented for Oracle
| Database, PostgreSQL, MySQL and MariaDB. Partial support is available
| for SQLite. Support among third-party dialects may vary.
|
| :param pattern: The regular expression pattern string or column
| clause.
| :param flags: Any regular expression string flags to apply, passed as
| plain Python string only. These flags are backend specific.
| Some backends, like PostgreSQL and MariaDB, may alternatively
| specify the flags as part of the pattern.
| When using the ignore case flag 'i' in PostgreSQL, the ignore case
| regexp match operator ``~*`` or ``!~*`` will be used.
|
| .. versionadded:: 1.4
|
| .. versionchanged:: 1.4.48, 2.0.18 Note that due to an implementation
| error, the "flags" parameter previously accepted SQL expression
| objects such as column expressions in addition to plain Python
| strings. This implementation did not work correctly with caching
| and was removed; strings only should be passed for the "flags"
| parameter, as these flags are rendered as literal inline values
| within SQL expressions.
|
| .. seealso::
|
| :meth:`_sql.ColumnOperators.regexp_replace`
|
| regexp_replace(self, pattern: 'Any', replacement: 'Any', flags: 'Optional[str]' = None) -> 'ColumnOperators'
| Implements a database-specific 'regexp replace' operator.
|
| E.g.::
|
| stmt = select(
| table.c.some_column.regexp_replace("b(..)", "XY", flags="g")
| )
|
| :meth:`_sql.ColumnOperators.regexp_replace` attempts to resolve to
| a REGEXP_REPLACE-like function provided by the backend, that
| usually emit the function ``REGEXP_REPLACE()``. However,
| the specific regular expression syntax and flags available are
| **not backend agnostic**.
|
| Regular expression replacement support is currently implemented for
| Oracle Database, PostgreSQL, MySQL 8 or greater and MariaDB. Support
| among third-party dialects may vary.
|
| :param pattern: The regular expression pattern string or column
| clause.
| :param pattern: The replacement string or column clause.
| :param flags: Any regular expression string flags to apply, passed as
| plain Python string only. These flags are backend specific.
| Some backends, like PostgreSQL and MariaDB, may alternatively
| specify the flags as part of the pattern.
|
| .. versionadded:: 1.4
|
| .. versionchanged:: 1.4.48, 2.0.18 Note that due to an implementation
| error, the "flags" parameter previously accepted SQL expression
| objects such as column expressions in addition to plain Python
| strings. This implementation did not work correctly with caching
| and was removed; strings only should be passed for the "flags"
| parameter, as these flags are rendered as literal inline values
| within SQL expressions.
|
|
| .. seealso::
|
| :meth:`_sql.ColumnOperators.regexp_match`
|
| startswith(self, other: 'Any', escape: 'Optional[str]' = None, autoescape: 'bool' = False) -> 'ColumnOperators'
| Implement the ``startswith`` operator.
|
| Produces a LIKE expression that tests against a match for the start
| of a string value:
|
| .. sourcecode:: sql
|
| column LIKE <other> || '%'
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.startswith("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.startswith.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.startswith.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.startswith.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.startswith("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE :param || '%' ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.startswith("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE :param || '%' ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.startswith.autoescape`::
|
| somecolumn.startswith("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.endswith`
|
| :meth:`.ColumnOperators.contains`
|
| :meth:`.ColumnOperators.like`
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.operators.ColumnOperators:
|
| timetuple = None
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.operators.Operators:
|
| __and__(self, other: 'Any') -> 'Operators'
| Implement the ``&`` operator.
|
| When used with SQL expressions, results in an
| AND operation, equivalent to
| :func:`_expression.and_`, that is::
|
| a & b
|
| is equivalent to::
|
| from sqlalchemy import and_
|
| and_(a, b)
|
| Care should be taken when using ``&`` regarding
| operator precedence; the ``&`` operator has the highest precedence.
| The operands should be enclosed in parenthesis if they contain
| further sub expressions::
|
| (a == 2) & (b == 4)
|
| __invert__(self) -> 'Operators'
| Implement the ``~`` operator.
|
| When used with SQL expressions, results in a
| NOT operation, equivalent to
| :func:`_expression.not_`, that is::
|
| ~a
|
| is equivalent to::
|
| from sqlalchemy import not_
|
| not_(a)
|
| __or__(self, other: 'Any') -> 'Operators'
| Implement the ``|`` operator.
|
| When used with SQL expressions, results in an
| OR operation, equivalent to
| :func:`_expression.or_`, that is::
|
| a | b
|
| is equivalent to::
|
| from sqlalchemy import or_
|
| or_(a, b)
|
| Care should be taken when using ``|`` regarding
| operator precedence; the ``|`` operator has the highest precedence.
| The operands should be enclosed in parenthesis if they contain
| further sub expressions::
|
| (a == 2) | (b == 4)
|
| __sa_operate__ = operate(self, op: 'OperatorType', *other: 'Any', **kwargs: 'Any') -> 'Operators'
| Operate on an argument.
|
| This is the lowest level of operation, raises
| :class:`NotImplementedError` by default.
|
| Overriding this on a subclass can allow common
| behavior to be applied to all operations.
| For example, overriding :class:`.ColumnOperators`
| to apply ``func.lower()`` to the left and right
| side::
|
| class MyComparator(ColumnOperators):
| def operate(self, op, other, **kwargs):
| return op(func.lower(self), func.lower(other), **kwargs)
|
| :param op: Operator callable.
| :param \*other: the 'other' side of the operation. Will
| be a single scalar for most operations.
| :param \**kwargs: modifiers. These may be passed by special
| operators such as :meth:`ColumnOperators.contains`.
|
| bool_op(self, opstring: 'str', precedence: 'int' = 0, python_impl: 'Optional[Callable[..., Any]]' = None) -> 'Callable[[Any], Operators]'
| Return a custom boolean operator.
|
| This method is shorthand for calling
| :meth:`.Operators.op` and passing the
| :paramref:`.Operators.op.is_comparison`
| flag with True. A key advantage to using :meth:`.Operators.bool_op`
| is that when using column constructs, the "boolean" nature of the
| returned expression will be present for :pep:`484` purposes.
|
| .. seealso::
|
| :meth:`.Operators.op`
|
| op(self, opstring: 'str', precedence: 'int' = 0, is_comparison: 'bool' = False, return_type: 'Optional[Union[Type[TypeEngine[Any]], TypeEngine[Any]]]' = None, python_impl: 'Optional[Callable[..., Any]]' = None) -> 'Callable[[Any], Operators]'
| Produce a generic operator function.
|
| e.g.::
|
| somecolumn.op("*")(5)
|
| produces::
|
| somecolumn * 5
|
| This function can also be used to make bitwise operators explicit. For
| example::
|
| somecolumn.op("&")(0xFF)
|
| is a bitwise AND of the value in ``somecolumn``.
|
| :param opstring: a string which will be output as the infix operator
| between this element and the expression passed to the
| generated function.
|
| :param precedence: precedence which the database is expected to apply
| to the operator in SQL expressions. This integer value acts as a hint
| for the SQL compiler to know when explicit parenthesis should be
| rendered around a particular operation. A lower number will cause the
| expression to be parenthesized when applied against another operator
| with higher precedence. The default value of ``0`` is lower than all
| operators except for the comma (``,``) and ``AS`` operators. A value
| of 100 will be higher or equal to all operators, and -100 will be
| lower than or equal to all operators.
|
| .. seealso::
|
| :ref:`faq_sql_expression_op_parenthesis` - detailed description
| of how the SQLAlchemy SQL compiler renders parenthesis
|
| :param is_comparison: legacy; if True, the operator will be considered
| as a "comparison" operator, that is which evaluates to a boolean
| true/false value, like ``==``, ``>``, etc. This flag is provided
| so that ORM relationships can establish that the operator is a
| comparison operator when used in a custom join condition.
|
| Using the ``is_comparison`` parameter is superseded by using the
| :meth:`.Operators.bool_op` method instead; this more succinct
| operator sets this parameter automatically, but also provides
| correct :pep:`484` typing support as the returned object will
| express a "boolean" datatype, i.e. ``BinaryExpression[bool]``.
|
| :param return_type: a :class:`.TypeEngine` class or object that will
| force the return type of an expression produced by this operator
| to be of that type. By default, operators that specify
| :paramref:`.Operators.op.is_comparison` will resolve to
| :class:`.Boolean`, and those that do not will be of the same
| type as the left-hand operand.
|
| :param python_impl: an optional Python function that can evaluate
| two Python values in the same way as this operator works when
| run on the database server. Useful for in-Python SQL expression
| evaluation functions, such as for ORM hybrid attributes, and the
| ORM "evaluator" used to match objects in a session after a multi-row
| update or delete.
|
| e.g.::
|
| >>> expr = column("x").op("+", python_impl=lambda a, b: a + b)("y")
|
| The operator for the above expression will also work for non-SQL
| left and right objects::
|
| >>> expr.operator(5, 10)
| 15
|
| .. versionadded:: 2.0
|
|
| .. seealso::
|
| :meth:`.Operators.bool_op`
|
| :ref:`types_operators`
|
| :ref:`relationship_custom_operator`
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.selectable.Selectable:
|
| 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.
|
| 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.
|
| 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`.
|
| .. deprecated:: 1.4 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.
|
| ----------------------------------------------------------------------
| Readonly properties inherited from sqlalchemy.sql.selectable.ReturnsRows:
|
| selectable
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.elements.ClauseElement:
|
| __bool__(self)
|
| __getstate__(self)
| Helper for pickle.
|
| __repr__(self)
| Return repr(self).
|
| compare(self, other: 'ClauseElement', **kw: 'Any') -> 'bool'
| Compare this :class:`_expression.ClauseElement` to
| the given :class:`_expression.ClauseElement`.
|
| Subclasses should override the default behavior, which is a
| straight identity comparison.
|
| \**kw are arguments consumed by subclass ``compare()`` methods and
| may be used to modify the criteria for comparison
| (see :class:`_expression.ColumnElement`).
|
| params(self, _ClauseElement__optionaldict: 'Optional[Mapping[str, Any]]' = None, **kwargs: 'Any') -> 'Self'
| Return a copy with :func:`_expression.bindparam` elements
| replaced.
|
| Returns a copy of this ClauseElement with
| :func:`_expression.bindparam`
| elements replaced with values taken from the given dictionary::
|
| >>> clause = column("x") + bindparam("foo")
| >>> print(clause.compile().params)
| {'foo':None}
| >>> print(clause.params({"foo": 7}).compile().params)
| {'foo':7}
|
| unique_params(self, _ClauseElement__optionaldict: 'Optional[Dict[str, Any]]' = None, **kwargs: 'Any') -> 'Self'
| Return a copy with :func:`_expression.bindparam` elements
| replaced.
|
| Same functionality as :meth:`_expression.ClauseElement.params`,
| except adds `unique=True`
| to affected bind parameters so that multiple statements can be
| used.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.elements.ClauseElement:
|
| is_clause_element = True
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.cache_key.HasCacheKey:
|
| inherit_cache = None
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_instancemethod(fn: '_F') -> '_F'
| Decorate a method memoize its return value.
|
| :meta private:
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_attribute = <class 'sqlalchemy.util.langhelpers.HasMemoized.m...
| A read-only @property that is only evaluated once.
|
| :meta private:
|
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.visitors.HasTraverseInternals:
|
| get_children(self, *, omit_attrs: 'Tuple[str, ...]' = (), **kw: 'Any') -> 'Iterable[HasTraverseInternals]'
| Return immediate child :class:`.visitors.HasTraverseInternals`
| elements of this :class:`.visitors.HasTraverseInternals`.
|
| This is used for visit traversal.
|
| \**kw may contain flags that change the collection that is
| returned, for example to return a subset of items in order to
| cut down on larger traversals, or to return child items from a
| different context (such as schema-level collections instead of
| clause-level).
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.elements.CompilerElement:
|
| __str__(self) -> 'str'
| Return str(self).
|
| compile(self, bind: 'Optional[_HasDialect]' = None, dialect: 'Optional[Dialect]' = None, **kw: 'Any') -> 'Compiled'
| Compile this SQL expression.
|
| The return value is a :class:`~.Compiled` object.
| Calling ``str()`` or ``unicode()`` on the returned value will yield a
| string representation of the result. The
| :class:`~.Compiled` object also can return a
| dictionary of bind parameter names and values
| using the ``params`` accessor.
|
| :param bind: An :class:`.Connection` or :class:`.Engine` which
| can provide a :class:`.Dialect` in order to generate a
| :class:`.Compiled` object. If the ``bind`` and
| ``dialect`` parameters are both omitted, a default SQL compiler
| is used.
|
| :param column_keys: Used for INSERT and UPDATE statements, a list of
| column names which should be present in the VALUES clause of the
| compiled statement. If ``None``, all columns from the target table
| object are rendered.
|
| :param dialect: A :class:`.Dialect` instance which can generate
| a :class:`.Compiled` object. This argument takes precedence over
| the ``bind`` argument.
|
| :param compile_kwargs: optional dictionary of additional parameters
| that will be passed through to the compiler within all "visit"
| methods. This allows any custom flag to be passed through to
| a custom compilation construct, for example. It is also used
| for the case of passing the ``literal_binds`` flag through::
|
| from sqlalchemy.sql import table, column, select
|
| t = table("t", column("x"))
|
| s = select(t).where(t.c.x == 5)
|
| print(s.compile(compile_kwargs={"literal_binds": True}))
|
| .. seealso::
|
| :ref:`faq_sql_expression_string`
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.elements.CompilerElement:
|
| stringify_dialect = 'default'
sqlalchemy.FunctionFilter
Python Library Documentation: class FunctionFilter in module sqlalchemy.sql.elements
class FunctionFilter(sqlalchemy.sql.base.Generative, ColumnElement)
| FunctionFilter(func: 'Union[FunctionElement[_T], WithinGroup[_T]]', *criterion: '_ColumnExpressionArgument[bool]')
|
| Represent a function FILTER clause.
|
| This is a special operator against aggregate and window functions,
| which controls which rows are passed to it.
| It's supported only by certain database backends.
|
| Invocation of :class:`.FunctionFilter` is via
| :meth:`.FunctionElement.filter`::
|
| func.count(1).filter(True)
|
| .. seealso::
|
| :meth:`.FunctionElement.filter`
|
| Method resolution order:
| FunctionFilter
| sqlalchemy.sql.base.Generative
| ColumnElement
| sqlalchemy.sql.roles.ColumnArgumentOrKeyRole
| sqlalchemy.sql.roles.ColumnArgumentRole
| sqlalchemy.sql.roles.StatementOptionRole
| sqlalchemy.sql.roles.WhereHavingRole
| sqlalchemy.sql.roles.OnClauseRole
| sqlalchemy.sql.roles.BinaryElementRole
| sqlalchemy.sql.roles.OrderByRole
| sqlalchemy.sql.roles.ColumnsClauseRole
| sqlalchemy.sql.roles.AllowsLambdaRole
| sqlalchemy.sql.roles.ByOfRole
| sqlalchemy.sql.roles.UsesInspection
| sqlalchemy.sql.roles.ColumnListRole
| sqlalchemy.sql.roles.LimitOffsetRole
| sqlalchemy.sql.roles.DMLColumnRole
| sqlalchemy.sql.roles.DDLConstraintColumnRole
| sqlalchemy.sql.roles.DDLExpressionRole
| sqlalchemy.sql.roles.StructuralRole
| SQLColumnExpression
| SQLCoreOperations
| sqlalchemy.sql.roles.ExpressionElementRole
| sqlalchemy.sql.roles.TypedColumnsClauseRole
| typing.Generic
| sqlalchemy.sql.operators.ColumnOperators
| sqlalchemy.sql.operators.Operators
| sqlalchemy.util.langhelpers.TypingOnly
| sqlalchemy.sql.roles.SQLRole
| DQLDMLClauseElement
| ClauseElement
| sqlalchemy.sql.annotation.SupportsWrappingAnnotations
| sqlalchemy.sql.annotation.SupportsAnnotations
| sqlalchemy.sql.cache_key.MemoizedHasCacheKey
| sqlalchemy.sql.cache_key.HasCacheKey
| sqlalchemy.util.langhelpers.HasMemoized
| sqlalchemy.sql.traversals.HasCopyInternals
| sqlalchemy.sql.visitors.ExternallyTraversible
| sqlalchemy.sql.visitors.HasTraverseInternals
| CompilerElement
| sqlalchemy.sql.visitors.Visitable
| builtins.object
|
| Methods defined here:
|
| __init__(self, func: 'Union[FunctionElement[_T], WithinGroup[_T]]', *criterion: '_ColumnExpressionArgument[bool]')
| Initialize self. See help(type(self)) for accurate signature.
|
| filter(self, *criterion: '_ColumnExpressionArgument[bool]') -> 'Self'
| Produce an additional FILTER against the function.
|
| This method adds additional criteria to the initial criteria
| set up by :meth:`.FunctionElement.filter`.
|
| Multiple criteria are joined together at SQL render time
| via ``AND``.
|
| over(self, partition_by: 'Optional[Union[Iterable[_ColumnExpressionArgument[Any]], _ColumnExpressionArgument[Any]]]' = None, order_by: 'Optional[Union[Iterable[_ColumnExpressionArgument[Any]], _ColumnExpressionArgument[Any]]]' = None, range_: 'Optional[typing_Tuple[Optional[int], Optional[int]]]' = None, rows: 'Optional[typing_Tuple[Optional[int], Optional[int]]]' = None, groups: 'Optional[typing_Tuple[Optional[int], Optional[int]]]' = None) -> 'Over[_T]'
| Produce an OVER clause against this filtered function.
|
| Used against aggregate or so-called "window" functions,
| for database backends that support window functions.
|
| The expression::
|
| func.rank().filter(MyClass.y > 5).over(order_by="x")
|
| is shorthand for::
|
| from sqlalchemy import over, funcfilter
|
| over(funcfilter(func.rank(), MyClass.y > 5), order_by="x")
|
| See :func:`_expression.over` for a full description.
|
| self_group(self, against: 'Optional[OperatorType]' = None) -> 'Union[Self, Grouping[_T]]'
| 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.
|
| type(...)
|
| within_group(self, *order_by: '_ColumnExpressionArgument[Any]') -> 'WithinGroup[_T]'
| Produce a WITHIN GROUP (ORDER BY expr) clause against
| this function.
|
| within_group_type(self, within_group: 'WithinGroup[_T]') -> 'Optional[TypeEngine[_T]]'
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'_traverse_internals': '_TraverseInternalsType', 'c...
|
| __orig_bases__ = (<class 'sqlalchemy.sql.base.Generative'>, sqlalchemy...
|
| __parameters__ = (~_T,)
|
| __visit_name__ = 'funcfilter'
|
| criterion = None
|
| ----------------------------------------------------------------------
| Data descriptors inherited from sqlalchemy.sql.base.Generative:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Methods inherited from ColumnElement:
|
| __getattr__(self, key: 'str') -> 'Any'
|
| __setstate__(self, state)
|
| base_columns(...)
|
| cast(self, type_: '_TypeEngineArgument[_OPT]') -> 'Cast[_OPT]'
| Produce a type cast, i.e. ``CAST(<expression> AS <type>)``.
|
| This is a shortcut to the :func:`_expression.cast` function.
|
| .. seealso::
|
| :ref:`tutorial_casts`
|
| :func:`_expression.cast`
|
| :func:`_expression.type_coerce`
|
| comparator(...)
|
| label(self, name: 'Optional[str]') -> 'Label[_T]'
| Produce a column label, i.e. ``<columnname> AS <name>``.
|
| This is a shortcut to the :func:`_expression.label` function.
|
| If 'name' is ``None``, an anonymous label name will be generated.
|
| operate(self, op: 'operators.OperatorType', *other: 'Any', **kwargs: 'Any') -> 'ColumnElement[Any]'
| Operate on an argument.
|
| This is the lowest level of operation, raises
| :class:`NotImplementedError` by default.
|
| Overriding this on a subclass can allow common
| behavior to be applied to all operations.
| For example, overriding :class:`.ColumnOperators`
| to apply ``func.lower()`` to the left and right
| side::
|
| class MyComparator(ColumnOperators):
| def operate(self, op, other, **kwargs):
| return op(func.lower(self), func.lower(other), **kwargs)
|
| :param op: Operator callable.
| :param \*other: the 'other' side of the operation. Will
| be a single scalar for most operations.
| :param \**kwargs: modifiers. These may be passed by special
| operators such as :meth:`ColumnOperators.contains`.
|
| proxy_set(...)
| set of all columns we are proxying
|
| as of 2.0 this is explicitly deannotated columns. previously it was
| effectively deannotated columns but wasn't enforced. annotated
| columns should basically not go into sets if at all possible because
| their hashing behavior is very non-performant.
|
| reverse_operate(self, op: 'operators.OperatorType', other: 'Any', **kwargs: 'Any') -> 'ColumnElement[Any]'
| Reverse operate on an argument.
|
| Usage is the same as :meth:`operate`.
|
| shares_lineage(self, othercolumn: 'ColumnElement[Any]') -> 'bool'
| Return True if the given :class:`_expression.ColumnElement`
| has a common ancestor to this :class:`_expression.ColumnElement`.
|
| ----------------------------------------------------------------------
| Readonly properties inherited from ColumnElement:
|
| anon_key_label
| .. deprecated:: 1.4 The :attr:`_expression.ColumnElement.anon_key_label` attribute is now private, and the public accessor is deprecated.
|
| anon_label
| .. deprecated:: 1.4 The :attr:`_expression.ColumnElement.anon_label` attribute is now private, and the public accessor is deprecated.
|
| expression
| Return a column expression.
|
| Part of the inspection interface; returns self.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from ColumnElement:
|
| foreign_keys = frozenset()
|
| key = None
|
| primary_key = False
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.AllowsLambdaRole:
|
| allows_lambda = True
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.UsesInspection:
|
| uses_inspection = True
|
| ----------------------------------------------------------------------
| Class methods inherited from typing.Generic:
|
| __class_getitem__(...)
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__(...)
| Function to initialize subclasses.
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.operators.ColumnOperators:
|
| __add__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``+`` operator.
|
| In a column context, produces the clause ``a + b``
| if the parent object has non-string affinity.
| If the parent object has a string affinity,
| produces the concatenation operator, ``a || b`` -
| see :meth:`.ColumnOperators.concat`.
|
| __contains__(self, other: 'Any') -> 'ColumnOperators'
|
| __eq__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``==`` operator.
|
| In a column context, produces the clause ``a = b``.
| If the target is ``None``, produces ``a IS NULL``.
|
| __floordiv__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``//`` operator.
|
| In a column context, produces the clause ``a / b``,
| which is the same as "truediv", but considers the result
| type to be integer.
|
| .. versionadded:: 2.0
|
| __ge__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``>=`` operator.
|
| In a column context, produces the clause ``a >= b``.
|
| __getitem__(self, index: 'Any') -> 'ColumnOperators'
| Implement the [] operator.
|
| This can be used by some database-specific types
| such as PostgreSQL ARRAY and HSTORE.
|
| __gt__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``>`` operator.
|
| In a column context, produces the clause ``a > b``.
|
| __hash__(self, /) from builtins.object
| Return hash(self).
|
| __le__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``<=`` operator.
|
| In a column context, produces the clause ``a <= b``.
|
| __lshift__(self, other: 'Any') -> 'ColumnOperators'
| implement the << operator.
|
| Not used by SQLAlchemy core, this is provided
| for custom operator systems which want to use
| << as an extension point.
|
| __lt__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``<`` operator.
|
| In a column context, produces the clause ``a < b``.
|
| __mod__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``%`` operator.
|
| In a column context, produces the clause ``a % b``.
|
| __mul__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``*`` operator.
|
| In a column context, produces the clause ``a * b``.
|
| __ne__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``!=`` operator.
|
| In a column context, produces the clause ``a != b``.
| If the target is ``None``, produces ``a IS NOT NULL``.
|
| __neg__(self) -> 'ColumnOperators'
| Implement the ``-`` operator.
|
| In a column context, produces the clause ``-a``.
|
| __radd__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``+`` operator in reverse.
|
| See :meth:`.ColumnOperators.__add__`.
|
| __rfloordiv__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``//`` operator in reverse.
|
| See :meth:`.ColumnOperators.__floordiv__`.
|
| __rmod__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``%`` operator in reverse.
|
| See :meth:`.ColumnOperators.__mod__`.
|
| __rmul__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``*`` operator in reverse.
|
| See :meth:`.ColumnOperators.__mul__`.
|
| __rshift__(self, other: 'Any') -> 'ColumnOperators'
| implement the >> operator.
|
| Not used by SQLAlchemy core, this is provided
| for custom operator systems which want to use
| >> as an extension point.
|
| __rsub__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``-`` operator in reverse.
|
| See :meth:`.ColumnOperators.__sub__`.
|
| __rtruediv__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``/`` operator in reverse.
|
| See :meth:`.ColumnOperators.__truediv__`.
|
| __sub__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``-`` operator.
|
| In a column context, produces the clause ``a - b``.
|
| __truediv__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``/`` operator.
|
| In a column context, produces the clause ``a / b``, and
| considers the result type to be numeric.
|
| .. versionchanged:: 2.0 The truediv operator against two integers
| is now considered to return a numeric value. Behavior on specific
| backends may vary.
|
| all_(self) -> 'ColumnOperators'
| Produce an :func:`_expression.all_` clause against the
| parent object.
|
| See the documentation for :func:`_sql.all_` for examples.
|
| .. note:: be sure to not confuse the newer
| :meth:`_sql.ColumnOperators.all_` method with the **legacy**
| version of this method, the :meth:`_types.ARRAY.Comparator.all`
| method that's specific to :class:`_types.ARRAY`, which uses a
| different calling style.
|
| any_(self) -> 'ColumnOperators'
| Produce an :func:`_expression.any_` clause against the
| parent object.
|
| See the documentation for :func:`_sql.any_` for examples.
|
| .. note:: be sure to not confuse the newer
| :meth:`_sql.ColumnOperators.any_` method with the **legacy**
| version of this method, the :meth:`_types.ARRAY.Comparator.any`
| method that's specific to :class:`_types.ARRAY`, which uses a
| different calling style.
|
| asc(self) -> 'ColumnOperators'
| Produce a :func:`_expression.asc` clause against the
| parent object.
|
| between(self, cleft: 'Any', cright: 'Any', symmetric: 'bool' = False) -> 'ColumnOperators'
| Produce a :func:`_expression.between` clause against
| the parent object, given the lower and upper range.
|
| bitwise_and(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise AND operation, typically via the ``&``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_lshift(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise LSHIFT operation, typically via the ``<<``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_not(self) -> 'ColumnOperators'
| Produce a bitwise NOT operation, typically via the ``~``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_or(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise OR operation, typically via the ``|``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_rshift(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise RSHIFT operation, typically via the ``>>``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_xor(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise XOR operation, typically via the ``^``
| operator, or ``#`` for PostgreSQL.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| collate(self, collation: 'str') -> 'ColumnOperators'
| Produce a :func:`_expression.collate` clause against
| the parent object, given the collation string.
|
| .. seealso::
|
| :func:`_expression.collate`
|
| concat(self, other: 'Any') -> 'ColumnOperators'
| Implement the 'concat' operator.
|
| In a column context, produces the clause ``a || b``,
| or uses the ``concat()`` operator on MySQL.
|
| contains(self, other: 'Any', **kw: 'Any') -> 'ColumnOperators'
| Implement the 'contains' operator.
|
| Produces a LIKE expression that tests against a match for the middle
| of a string value:
|
| .. sourcecode:: sql
|
| column LIKE '%' || <other> || '%'
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.contains("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.contains.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.contains.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.contains.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.contains("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE '%' || :param || '%' ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.contains("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE '%' || :param || '%' ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.contains.autoescape`::
|
| somecolumn.contains("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.startswith`
|
| :meth:`.ColumnOperators.endswith`
|
| :meth:`.ColumnOperators.like`
|
| desc(self) -> 'ColumnOperators'
| Produce a :func:`_expression.desc` clause against the
| parent object.
|
| distinct(self) -> 'ColumnOperators'
| Produce a :func:`_expression.distinct` clause against the
| parent object.
|
| endswith(self, other: 'Any', escape: 'Optional[str]' = None, autoescape: 'bool' = False) -> 'ColumnOperators'
| Implement the 'endswith' operator.
|
| Produces a LIKE expression that tests against a match for the end
| of a string value:
|
| .. sourcecode:: sql
|
| column LIKE '%' || <other>
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.endswith("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.endswith.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.endswith.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.endswith.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.endswith("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE '%' || :param ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.endswith("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE '%' || :param ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.endswith.autoescape`::
|
| somecolumn.endswith("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.startswith`
|
| :meth:`.ColumnOperators.contains`
|
| :meth:`.ColumnOperators.like`
|
| icontains(self, other: 'Any', **kw: 'Any') -> 'ColumnOperators'
| Implement the ``icontains`` operator, e.g. case insensitive
| version of :meth:`.ColumnOperators.contains`.
|
| Produces a LIKE expression that tests against an insensitive match
| for the middle of a string value:
|
| .. sourcecode:: sql
|
| lower(column) LIKE '%' || lower(<other>) || '%'
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.icontains("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.icontains.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.icontains.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.icontains.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.icontains("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE '%' || lower(:param) || '%' ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.icontains("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE '%' || lower(:param) || '%' ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.contains.autoescape`::
|
| somecolumn.icontains("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.contains`
|
| iendswith(self, other: 'Any', escape: 'Optional[str]' = None, autoescape: 'bool' = False) -> 'ColumnOperators'
| Implement the ``iendswith`` operator, e.g. case insensitive
| version of :meth:`.ColumnOperators.endswith`.
|
| Produces a LIKE expression that tests against an insensitive match
| for the end of a string value:
|
| .. sourcecode:: sql
|
| lower(column) LIKE '%' || lower(<other>)
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.iendswith("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.iendswith.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.iendswith.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.iendswith.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.iendswith("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE '%' || lower(:param) ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.iendswith("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE '%' || lower(:param) ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.iendswith.autoescape`::
|
| somecolumn.endswith("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.endswith`
|
| ilike(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
| Implement the ``ilike`` operator, e.g. case insensitive LIKE.
|
| In a column context, produces an expression either of the form:
|
| .. sourcecode:: sql
|
| lower(a) LIKE lower(other)
|
| Or on backends that support the ILIKE operator:
|
| .. sourcecode:: sql
|
| a ILIKE other
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.ilike("%foobar%"))
|
| :param other: expression to be compared
| :param escape: optional escape character, renders the ``ESCAPE``
| keyword, e.g.::
|
| somecolumn.ilike("foo/%bar", escape="/")
|
| .. seealso::
|
| :meth:`.ColumnOperators.like`
|
| in_(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``in`` operator.
|
| In a column context, produces the clause ``column IN <other>``.
|
| The given parameter ``other`` may be:
|
| * A list of literal values,
| e.g.::
|
| stmt.where(column.in_([1, 2, 3]))
|
| In this calling form, the list of items is converted to a set of
| bound parameters the same length as the list given:
|
| .. sourcecode:: sql
|
| WHERE COL IN (?, ?, ?)
|
| * A list of tuples may be provided if the comparison is against a
| :func:`.tuple_` containing multiple expressions::
|
| from sqlalchemy import tuple_
|
| stmt.where(tuple_(col1, col2).in_([(1, 10), (2, 20), (3, 30)]))
|
| * An empty list,
| e.g.::
|
| stmt.where(column.in_([]))
|
| In this calling form, the expression renders an "empty set"
| expression. These expressions are tailored to individual backends
| and are generally trying to get an empty SELECT statement as a
| subquery. Such as on SQLite, the expression is:
|
| .. sourcecode:: sql
|
| WHERE col IN (SELECT 1 FROM (SELECT 1) WHERE 1!=1)
|
| .. versionchanged:: 1.4 empty IN expressions now use an
| execution-time generated SELECT subquery in all cases.
|
| * A bound parameter, e.g. :func:`.bindparam`, may be used if it
| includes the :paramref:`.bindparam.expanding` flag::
|
| stmt.where(column.in_(bindparam("value", expanding=True)))
|
| In this calling form, the expression renders a special non-SQL
| placeholder expression that looks like:
|
| .. sourcecode:: sql
|
| WHERE COL IN ([EXPANDING_value])
|
| This placeholder expression is intercepted at statement execution
| time to be converted into the variable number of bound parameter
| form illustrated earlier. If the statement were executed as::
|
| connection.execute(stmt, {"value": [1, 2, 3]})
|
| The database would be passed a bound parameter for each value:
|
| .. sourcecode:: sql
|
| WHERE COL IN (?, ?, ?)
|
| .. versionadded:: 1.2 added "expanding" bound parameters
|
| If an empty list is passed, a special "empty list" expression,
| which is specific to the database in use, is rendered. On
| SQLite this would be:
|
| .. sourcecode:: sql
|
| WHERE COL IN (SELECT 1 FROM (SELECT 1) WHERE 1!=1)
|
| .. versionadded:: 1.3 "expanding" bound parameters now support
| empty lists
|
| * a :func:`_expression.select` construct, which is usually a
| correlated scalar select::
|
| stmt.where(
| column.in_(select(othertable.c.y).where(table.c.x == othertable.c.x))
| )
|
| In this calling form, :meth:`.ColumnOperators.in_` renders as given:
|
| .. sourcecode:: sql
|
| WHERE COL IN (SELECT othertable.y
| FROM othertable WHERE othertable.x = table.x)
|
| :param other: a list of literals, a :func:`_expression.select`
| construct, or a :func:`.bindparam` construct that includes the
| :paramref:`.bindparam.expanding` flag set to True.
|
| is_(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``IS`` operator.
|
| Normally, ``IS`` is generated automatically when comparing to a
| value of ``None``, which resolves to ``NULL``. However, explicit
| usage of ``IS`` may be desirable if comparing to boolean values
| on certain platforms.
|
| .. seealso:: :meth:`.ColumnOperators.is_not`
|
| is_distinct_from(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``IS DISTINCT FROM`` operator.
|
| Renders "a IS DISTINCT FROM b" on most platforms;
| on some such as SQLite may render "a IS NOT b".
|
| is_not(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``IS NOT`` operator.
|
| Normally, ``IS NOT`` is generated automatically when comparing to a
| value of ``None``, which resolves to ``NULL``. However, explicit
| usage of ``IS NOT`` may be desirable if comparing to boolean values
| on certain platforms.
|
| .. versionchanged:: 1.4 The ``is_not()`` operator is renamed from
| ``isnot()`` in previous releases. The previous name remains
| available for backwards compatibility.
|
| .. seealso:: :meth:`.ColumnOperators.is_`
|
| is_not_distinct_from(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``IS NOT DISTINCT FROM`` operator.
|
| Renders "a IS NOT DISTINCT FROM b" on most platforms;
| on some such as SQLite may render "a IS b".
|
| .. versionchanged:: 1.4 The ``is_not_distinct_from()`` operator is
| renamed from ``isnot_distinct_from()`` in previous releases.
| The previous name remains available for backwards compatibility.
|
| isnot = is_not(self, other: 'Any') -> 'ColumnOperators'
|
| isnot_distinct_from = is_not_distinct_from(self, other: 'Any') -> 'ColumnOperators'
|
| istartswith(self, other: 'Any', escape: 'Optional[str]' = None, autoescape: 'bool' = False) -> 'ColumnOperators'
| Implement the ``istartswith`` operator, e.g. case insensitive
| version of :meth:`.ColumnOperators.startswith`.
|
| Produces a LIKE expression that tests against an insensitive
| match for the start of a string value:
|
| .. sourcecode:: sql
|
| lower(column) LIKE lower(<other>) || '%'
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.istartswith("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.istartswith.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.istartswith.escape` parameter will
| establish a given character as an escape character which can be of
| use when the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.istartswith.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.istartswith("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE lower(:param) || '%' ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.istartswith("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE lower(:param) || '%' ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.istartswith.autoescape`::
|
| somecolumn.istartswith("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.startswith`
|
| like(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
| Implement the ``like`` operator.
|
| In a column context, produces the expression:
|
| .. sourcecode:: sql
|
| a LIKE other
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.like("%foobar%"))
|
| :param other: expression to be compared
| :param escape: optional escape character, renders the ``ESCAPE``
| keyword, e.g.::
|
| somecolumn.like("foo/%bar", escape="/")
|
| .. seealso::
|
| :meth:`.ColumnOperators.ilike`
|
| match(self, other: 'Any', **kwargs: 'Any') -> 'ColumnOperators'
| Implements a database-specific 'match' operator.
|
| :meth:`_sql.ColumnOperators.match` attempts to resolve to
| a MATCH-like function or operator provided by the backend.
| Examples include:
|
| * PostgreSQL - renders ``x @@ plainto_tsquery(y)``
|
| .. versionchanged:: 2.0 ``plainto_tsquery()`` is used instead
| of ``to_tsquery()`` for PostgreSQL now; for compatibility with
| other forms, see :ref:`postgresql_match`.
|
|
| * MySQL - renders ``MATCH (x) AGAINST (y IN BOOLEAN MODE)``
|
| .. seealso::
|
| :class:`_mysql.match` - MySQL specific construct with
| additional features.
|
| * Oracle Database - renders ``CONTAINS(x, y)``
| * other backends may provide special implementations.
| * Backends without any special implementation will emit
| the operator as "MATCH". This is compatible with SQLite, for
| example.
|
| not_ilike(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
| implement the ``NOT ILIKE`` operator.
|
| This is equivalent to using negation with
| :meth:`.ColumnOperators.ilike`, i.e. ``~x.ilike(y)``.
|
| .. versionchanged:: 1.4 The ``not_ilike()`` operator is renamed from
| ``notilike()`` in previous releases. The previous name remains
| available for backwards compatibility.
|
| .. seealso::
|
| :meth:`.ColumnOperators.ilike`
|
| not_in(self, other: 'Any') -> 'ColumnOperators'
| implement the ``NOT IN`` operator.
|
| This is equivalent to using negation with
| :meth:`.ColumnOperators.in_`, i.e. ``~x.in_(y)``.
|
| In the case that ``other`` is an empty sequence, the compiler
| produces an "empty not in" expression. This defaults to the
| expression "1 = 1" to produce true in all cases. The
| :paramref:`_sa.create_engine.empty_in_strategy` may be used to
| alter this behavior.
|
| .. versionchanged:: 1.4 The ``not_in()`` operator is renamed from
| ``notin_()`` in previous releases. The previous name remains
| available for backwards compatibility.
|
| .. versionchanged:: 1.2 The :meth:`.ColumnOperators.in_` and
| :meth:`.ColumnOperators.not_in` operators
| now produce a "static" expression for an empty IN sequence
| by default.
|
| .. seealso::
|
| :meth:`.ColumnOperators.in_`
|
| not_like(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
| implement the ``NOT LIKE`` operator.
|
| This is equivalent to using negation with
| :meth:`.ColumnOperators.like`, i.e. ``~x.like(y)``.
|
| .. versionchanged:: 1.4 The ``not_like()`` operator is renamed from
| ``notlike()`` in previous releases. The previous name remains
| available for backwards compatibility.
|
| .. seealso::
|
| :meth:`.ColumnOperators.like`
|
| notilike = not_ilike(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
|
| notin_ = not_in(self, other: 'Any') -> 'ColumnOperators'
|
| notlike = not_like(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
|
| nulls_first(self) -> 'ColumnOperators'
| Produce a :func:`_expression.nulls_first` clause against the
| parent object.
|
| .. versionchanged:: 1.4 The ``nulls_first()`` operator is
| renamed from ``nullsfirst()`` in previous releases.
| The previous name remains available for backwards compatibility.
|
| nulls_last(self) -> 'ColumnOperators'
| Produce a :func:`_expression.nulls_last` clause against the
| parent object.
|
| .. versionchanged:: 1.4 The ``nulls_last()`` operator is
| renamed from ``nullslast()`` in previous releases.
| The previous name remains available for backwards compatibility.
|
| nullsfirst = nulls_first(self) -> 'ColumnOperators'
|
| nullslast = nulls_last(self) -> 'ColumnOperators'
|
| regexp_match(self, pattern: 'Any', flags: 'Optional[str]' = None) -> 'ColumnOperators'
| Implements a database-specific 'regexp match' operator.
|
| E.g.::
|
| stmt = select(table.c.some_column).where(
| table.c.some_column.regexp_match("^(b|c)")
| )
|
| :meth:`_sql.ColumnOperators.regexp_match` attempts to resolve to
| a REGEXP-like function or operator provided by the backend, however
| the specific regular expression syntax and flags available are
| **not backend agnostic**.
|
| Examples include:
|
| * PostgreSQL - renders ``x ~ y`` or ``x !~ y`` when negated.
| * Oracle Database - renders ``REGEXP_LIKE(x, y)``
| * SQLite - uses SQLite's ``REGEXP`` placeholder operator and calls into
| the Python ``re.match()`` builtin.
| * other backends may provide special implementations.
| * Backends without any special implementation will emit
| the operator as "REGEXP" or "NOT REGEXP". This is compatible with
| SQLite and MySQL, for example.
|
| Regular expression support is currently implemented for Oracle
| Database, PostgreSQL, MySQL and MariaDB. Partial support is available
| for SQLite. Support among third-party dialects may vary.
|
| :param pattern: The regular expression pattern string or column
| clause.
| :param flags: Any regular expression string flags to apply, passed as
| plain Python string only. These flags are backend specific.
| Some backends, like PostgreSQL and MariaDB, may alternatively
| specify the flags as part of the pattern.
| When using the ignore case flag 'i' in PostgreSQL, the ignore case
| regexp match operator ``~*`` or ``!~*`` will be used.
|
| .. versionadded:: 1.4
|
| .. versionchanged:: 1.4.48, 2.0.18 Note that due to an implementation
| error, the "flags" parameter previously accepted SQL expression
| objects such as column expressions in addition to plain Python
| strings. This implementation did not work correctly with caching
| and was removed; strings only should be passed for the "flags"
| parameter, as these flags are rendered as literal inline values
| within SQL expressions.
|
| .. seealso::
|
| :meth:`_sql.ColumnOperators.regexp_replace`
|
| regexp_replace(self, pattern: 'Any', replacement: 'Any', flags: 'Optional[str]' = None) -> 'ColumnOperators'
| Implements a database-specific 'regexp replace' operator.
|
| E.g.::
|
| stmt = select(
| table.c.some_column.regexp_replace("b(..)", "XY", flags="g")
| )
|
| :meth:`_sql.ColumnOperators.regexp_replace` attempts to resolve to
| a REGEXP_REPLACE-like function provided by the backend, that
| usually emit the function ``REGEXP_REPLACE()``. However,
| the specific regular expression syntax and flags available are
| **not backend agnostic**.
|
| Regular expression replacement support is currently implemented for
| Oracle Database, PostgreSQL, MySQL 8 or greater and MariaDB. Support
| among third-party dialects may vary.
|
| :param pattern: The regular expression pattern string or column
| clause.
| :param pattern: The replacement string or column clause.
| :param flags: Any regular expression string flags to apply, passed as
| plain Python string only. These flags are backend specific.
| Some backends, like PostgreSQL and MariaDB, may alternatively
| specify the flags as part of the pattern.
|
| .. versionadded:: 1.4
|
| .. versionchanged:: 1.4.48, 2.0.18 Note that due to an implementation
| error, the "flags" parameter previously accepted SQL expression
| objects such as column expressions in addition to plain Python
| strings. This implementation did not work correctly with caching
| and was removed; strings only should be passed for the "flags"
| parameter, as these flags are rendered as literal inline values
| within SQL expressions.
|
|
| .. seealso::
|
| :meth:`_sql.ColumnOperators.regexp_match`
|
| startswith(self, other: 'Any', escape: 'Optional[str]' = None, autoescape: 'bool' = False) -> 'ColumnOperators'
| Implement the ``startswith`` operator.
|
| Produces a LIKE expression that tests against a match for the start
| of a string value:
|
| .. sourcecode:: sql
|
| column LIKE <other> || '%'
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.startswith("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.startswith.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.startswith.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.startswith.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.startswith("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE :param || '%' ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.startswith("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE :param || '%' ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.startswith.autoescape`::
|
| somecolumn.startswith("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.endswith`
|
| :meth:`.ColumnOperators.contains`
|
| :meth:`.ColumnOperators.like`
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.operators.ColumnOperators:
|
| timetuple = None
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.operators.Operators:
|
| __and__(self, other: 'Any') -> 'Operators'
| Implement the ``&`` operator.
|
| When used with SQL expressions, results in an
| AND operation, equivalent to
| :func:`_expression.and_`, that is::
|
| a & b
|
| is equivalent to::
|
| from sqlalchemy import and_
|
| and_(a, b)
|
| Care should be taken when using ``&`` regarding
| operator precedence; the ``&`` operator has the highest precedence.
| The operands should be enclosed in parenthesis if they contain
| further sub expressions::
|
| (a == 2) & (b == 4)
|
| __invert__(self) -> 'Operators'
| Implement the ``~`` operator.
|
| When used with SQL expressions, results in a
| NOT operation, equivalent to
| :func:`_expression.not_`, that is::
|
| ~a
|
| is equivalent to::
|
| from sqlalchemy import not_
|
| not_(a)
|
| __or__(self, other: 'Any') -> 'Operators'
| Implement the ``|`` operator.
|
| When used with SQL expressions, results in an
| OR operation, equivalent to
| :func:`_expression.or_`, that is::
|
| a | b
|
| is equivalent to::
|
| from sqlalchemy import or_
|
| or_(a, b)
|
| Care should be taken when using ``|`` regarding
| operator precedence; the ``|`` operator has the highest precedence.
| The operands should be enclosed in parenthesis if they contain
| further sub expressions::
|
| (a == 2) | (b == 4)
|
| __sa_operate__ = operate(self, op: 'OperatorType', *other: 'Any', **kwargs: 'Any') -> 'Operators'
| Operate on an argument.
|
| This is the lowest level of operation, raises
| :class:`NotImplementedError` by default.
|
| Overriding this on a subclass can allow common
| behavior to be applied to all operations.
| For example, overriding :class:`.ColumnOperators`
| to apply ``func.lower()`` to the left and right
| side::
|
| class MyComparator(ColumnOperators):
| def operate(self, op, other, **kwargs):
| return op(func.lower(self), func.lower(other), **kwargs)
|
| :param op: Operator callable.
| :param \*other: the 'other' side of the operation. Will
| be a single scalar for most operations.
| :param \**kwargs: modifiers. These may be passed by special
| operators such as :meth:`ColumnOperators.contains`.
|
| bool_op(self, opstring: 'str', precedence: 'int' = 0, python_impl: 'Optional[Callable[..., Any]]' = None) -> 'Callable[[Any], Operators]'
| Return a custom boolean operator.
|
| This method is shorthand for calling
| :meth:`.Operators.op` and passing the
| :paramref:`.Operators.op.is_comparison`
| flag with True. A key advantage to using :meth:`.Operators.bool_op`
| is that when using column constructs, the "boolean" nature of the
| returned expression will be present for :pep:`484` purposes.
|
| .. seealso::
|
| :meth:`.Operators.op`
|
| op(self, opstring: 'str', precedence: 'int' = 0, is_comparison: 'bool' = False, return_type: 'Optional[Union[Type[TypeEngine[Any]], TypeEngine[Any]]]' = None, python_impl: 'Optional[Callable[..., Any]]' = None) -> 'Callable[[Any], Operators]'
| Produce a generic operator function.
|
| e.g.::
|
| somecolumn.op("*")(5)
|
| produces::
|
| somecolumn * 5
|
| This function can also be used to make bitwise operators explicit. For
| example::
|
| somecolumn.op("&")(0xFF)
|
| is a bitwise AND of the value in ``somecolumn``.
|
| :param opstring: a string which will be output as the infix operator
| between this element and the expression passed to the
| generated function.
|
| :param precedence: precedence which the database is expected to apply
| to the operator in SQL expressions. This integer value acts as a hint
| for the SQL compiler to know when explicit parenthesis should be
| rendered around a particular operation. A lower number will cause the
| expression to be parenthesized when applied against another operator
| with higher precedence. The default value of ``0`` is lower than all
| operators except for the comma (``,``) and ``AS`` operators. A value
| of 100 will be higher or equal to all operators, and -100 will be
| lower than or equal to all operators.
|
| .. seealso::
|
| :ref:`faq_sql_expression_op_parenthesis` - detailed description
| of how the SQLAlchemy SQL compiler renders parenthesis
|
| :param is_comparison: legacy; if True, the operator will be considered
| as a "comparison" operator, that is which evaluates to a boolean
| true/false value, like ``==``, ``>``, etc. This flag is provided
| so that ORM relationships can establish that the operator is a
| comparison operator when used in a custom join condition.
|
| Using the ``is_comparison`` parameter is superseded by using the
| :meth:`.Operators.bool_op` method instead; this more succinct
| operator sets this parameter automatically, but also provides
| correct :pep:`484` typing support as the returned object will
| express a "boolean" datatype, i.e. ``BinaryExpression[bool]``.
|
| :param return_type: a :class:`.TypeEngine` class or object that will
| force the return type of an expression produced by this operator
| to be of that type. By default, operators that specify
| :paramref:`.Operators.op.is_comparison` will resolve to
| :class:`.Boolean`, and those that do not will be of the same
| type as the left-hand operand.
|
| :param python_impl: an optional Python function that can evaluate
| two Python values in the same way as this operator works when
| run on the database server. Useful for in-Python SQL expression
| evaluation functions, such as for ORM hybrid attributes, and the
| ORM "evaluator" used to match objects in a session after a multi-row
| update or delete.
|
| e.g.::
|
| >>> expr = column("x").op("+", python_impl=lambda a, b: a + b)("y")
|
| The operator for the above expression will also work for non-SQL
| left and right objects::
|
| >>> expr.operator(5, 10)
| 15
|
| .. versionadded:: 2.0
|
|
| .. seealso::
|
| :meth:`.Operators.bool_op`
|
| :ref:`types_operators`
|
| :ref:`relationship_custom_operator`
|
| ----------------------------------------------------------------------
| Methods inherited from ClauseElement:
|
| __bool__(self)
|
| __getstate__(self)
| Helper for pickle.
|
| __repr__(self)
| Return repr(self).
|
| compare(self, other: 'ClauseElement', **kw: 'Any') -> 'bool'
| Compare this :class:`_expression.ClauseElement` to
| the given :class:`_expression.ClauseElement`.
|
| Subclasses should override the default behavior, which is a
| straight identity comparison.
|
| \**kw are arguments consumed by subclass ``compare()`` methods and
| may be used to modify the criteria for comparison
| (see :class:`_expression.ColumnElement`).
|
| description(...)
|
| entity_namespace(...)
|
| params(self, _ClauseElement__optionaldict: 'Optional[Mapping[str, Any]]' = None, **kwargs: 'Any') -> 'Self'
| Return a copy with :func:`_expression.bindparam` elements
| replaced.
|
| Returns a copy of this ClauseElement with
| :func:`_expression.bindparam`
| elements replaced with values taken from the given dictionary::
|
| >>> clause = column("x") + bindparam("foo")
| >>> print(clause.compile().params)
| {'foo':None}
| >>> print(clause.params({"foo": 7}).compile().params)
| {'foo':7}
|
| unique_params(self, _ClauseElement__optionaldict: 'Optional[Dict[str, Any]]' = None, **kwargs: 'Any') -> 'Self'
| Return a copy with :func:`_expression.bindparam` elements
| replaced.
|
| Same functionality as :meth:`_expression.ClauseElement.params`,
| except adds `unique=True`
| to affected bind parameters so that multiple statements can be
| used.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from ClauseElement:
|
| is_clause_element = True
|
| is_dml = False
|
| is_selectable = False
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.cache_key.HasCacheKey:
|
| inherit_cache = None
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_instancemethod(fn: '_F') -> '_F'
| Decorate a method memoize its return value.
|
| :meta private:
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_attribute = <class 'sqlalchemy.util.langhelpers.HasMemoized.m...
| A read-only @property that is only evaluated once.
|
| :meta private:
|
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.visitors.HasTraverseInternals:
|
| get_children(self, *, omit_attrs: 'Tuple[str, ...]' = (), **kw: 'Any') -> 'Iterable[HasTraverseInternals]'
| Return immediate child :class:`.visitors.HasTraverseInternals`
| elements of this :class:`.visitors.HasTraverseInternals`.
|
| This is used for visit traversal.
|
| \**kw may contain flags that change the collection that is
| returned, for example to return a subset of items in order to
| cut down on larger traversals, or to return child items from a
| different context (such as schema-level collections instead of
| clause-level).
|
| ----------------------------------------------------------------------
| Methods inherited from CompilerElement:
|
| __str__(self) -> 'str'
| Return str(self).
|
| compile(self, bind: 'Optional[_HasDialect]' = None, dialect: 'Optional[Dialect]' = None, **kw: 'Any') -> 'Compiled'
| Compile this SQL expression.
|
| The return value is a :class:`~.Compiled` object.
| Calling ``str()`` or ``unicode()`` on the returned value will yield a
| string representation of the result. The
| :class:`~.Compiled` object also can return a
| dictionary of bind parameter names and values
| using the ``params`` accessor.
|
| :param bind: An :class:`.Connection` or :class:`.Engine` which
| can provide a :class:`.Dialect` in order to generate a
| :class:`.Compiled` object. If the ``bind`` and
| ``dialect`` parameters are both omitted, a default SQL compiler
| is used.
|
| :param column_keys: Used for INSERT and UPDATE statements, a list of
| column names which should be present in the VALUES clause of the
| compiled statement. If ``None``, all columns from the target table
| object are rendered.
|
| :param dialect: A :class:`.Dialect` instance which can generate
| a :class:`.Compiled` object. This argument takes precedence over
| the ``bind`` argument.
|
| :param compile_kwargs: optional dictionary of additional parameters
| that will be passed through to the compiler within all "visit"
| methods. This allows any custom flag to be passed through to
| a custom compilation construct, for example. It is also used
| for the case of passing the ``literal_binds`` flag through::
|
| from sqlalchemy.sql import table, column, select
|
| t = table("t", column("x"))
|
| s = select(t).where(t.c.x == 5)
|
| print(s.compile(compile_kwargs={"literal_binds": True}))
|
| .. seealso::
|
| :ref:`faq_sql_expression_string`
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from CompilerElement:
|
| stringify_dialect = 'default'
|
| supports_execution = False
sqlalchemy.GenerativeSelect
Python Library Documentation: class GenerativeSelect in module sqlalchemy.sql.selectable
class GenerativeSelect(sqlalchemy.sql.base.DialectKWArgs, SelectBase, sqlalchemy.sql.base.Generative)
| GenerativeSelect(_label_style: 'SelectLabelStyle' = <SelectLabelStyle.LABEL_STYLE_DISAMBIGUATE_ONLY: 2>)
|
| Base class for SELECT statements where additional elements can be
| added.
|
| This serves as the base for :class:`_expression.Select` and
| :class:`_expression.CompoundSelect`
| where elements such as ORDER BY, GROUP BY can be added and column
| rendering can be controlled. Compare to
| :class:`_expression.TextualSelect`, which,
| while it subclasses :class:`_expression.SelectBase`
| and is also a SELECT construct,
| represents a fixed textual string which cannot be altered at this level,
| only wrapped as a subquery.
|
| Method resolution order:
| GenerativeSelect
| sqlalchemy.sql.base.DialectKWArgs
| SelectBase
| sqlalchemy.sql.roles.SelectStatementRole
| sqlalchemy.sql.roles.StatementRole
| sqlalchemy.sql.roles.DMLSelectRole
| sqlalchemy.sql.roles.CompoundElementRole
| sqlalchemy.sql.roles.AllowsLambdaRole
| sqlalchemy.sql.roles.InElementRole
| HasCTE
| sqlalchemy.sql.roles.HasCTERole
| SelectsRows
| sqlalchemy.sql.annotation.SupportsCloneAnnotations
| Selectable
| ReturnsRows
| sqlalchemy.sql.roles.ReturnsRowsRole
| sqlalchemy.sql.roles.SQLRole
| sqlalchemy.sql.elements.DQLDMLClauseElement
| sqlalchemy.sql.elements.ClauseElement
| sqlalchemy.sql.annotation.SupportsWrappingAnnotations
| sqlalchemy.sql.annotation.SupportsAnnotations
| sqlalchemy.sql.cache_key.MemoizedHasCacheKey
| sqlalchemy.sql.cache_key.HasCacheKey
| sqlalchemy.sql.base.Generative
| sqlalchemy.util.langhelpers.HasMemoized
| sqlalchemy.sql.traversals.HasCopyInternals
| sqlalchemy.sql.visitors.ExternallyTraversible
| sqlalchemy.sql.visitors.HasTraverseInternals
| sqlalchemy.sql.elements.CompilerElement
| sqlalchemy.sql.visitors.Visitable
| builtins.object
|
| Methods defined here:
|
| __init__(self, _label_style: 'SelectLabelStyle' = <SelectLabelStyle.LABEL_STYLE_DISAMBIGUATE_ONLY: 2>)
| Initialize self. See help(type(self)) for accurate signature.
|
| fetch(self, count: '_LimitOffsetType', with_ties: 'bool' = False, percent: 'bool' = False, **dialect_kw: 'Any') -> 'Self'
| Return a new selectable with the given FETCH FIRST criterion
| applied.
|
| This is a numeric value which usually renders as ``FETCH {FIRST | NEXT}
| [ count ] {ROW | ROWS} {ONLY | WITH TIES}`` expression in the resulting
| select. This functionality is is currently implemented for Oracle
| Database, PostgreSQL, MSSQL.
|
| Use :meth:`_sql.GenerativeSelect.offset` to specify the offset.
|
| .. note::
|
| The :meth:`_sql.GenerativeSelect.fetch` method will replace
| any clause applied with :meth:`_sql.GenerativeSelect.limit`.
|
| .. versionadded:: 1.4
|
| :param count: an integer COUNT parameter, or a SQL expression
| that provides an integer result. When ``percent=True`` this will
| represent the percentage of rows to return, not the absolute value.
| Pass ``None`` to reset it.
|
| :param with_ties: When ``True``, the WITH TIES option is used
| to return any additional rows that tie for the last place in the
| result set according to the ``ORDER BY`` clause. The
| ``ORDER BY`` may be mandatory in this case. Defaults to ``False``
|
| :param percent: When ``True``, ``count`` represents the percentage
| of the total number of selected rows to return. Defaults to ``False``
|
| :param \**dialect_kw: Additional dialect-specific keyword arguments
| may be accepted by dialects.
|
| .. versionadded:: 2.0.41
|
| .. seealso::
|
| :meth:`_sql.GenerativeSelect.limit`
|
| :meth:`_sql.GenerativeSelect.offset`
|
| get_label_style(self) -> 'SelectLabelStyle'
| Retrieve the current label style.
|
| .. versionadded:: 1.4
|
| group_by(self, _GenerativeSelect__first: 'Union[Literal[None, _NoArg.NO_ARG], _ColumnExpressionOrStrLabelArgument[Any]]' = _NoArg.NO_ARG, *clauses: '_ColumnExpressionOrStrLabelArgument[Any]') -> 'Self'
| Return a new selectable with the given list of GROUP BY
| criterion applied.
|
| All existing GROUP BY settings can be suppressed by passing ``None``.
|
| e.g.::
|
| stmt = select(table.c.name, func.max(table.c.stat)).group_by(table.c.name)
|
| :param \*clauses: a series of :class:`_expression.ColumnElement`
| constructs which will be used to generate an GROUP BY clause.
|
| Alternatively, an individual entry may also be the string name of a
| label located elsewhere in the columns clause of the statement which
| will be matched and rendered in a backend-specific way based on
| context; see :ref:`tutorial_order_by_label` for background on string
| label matching in ORDER BY and GROUP BY expressions.
|
| .. seealso::
|
| :ref:`tutorial_group_by_w_aggregates` - in the
| :ref:`unified_tutorial`
|
| :ref:`tutorial_order_by_label` - in the :ref:`unified_tutorial`
|
| limit(self, limit: '_LimitOffsetType') -> 'Self'
| Return a new selectable with the given LIMIT criterion
| applied.
|
| This is a numerical value which usually renders as a ``LIMIT``
| expression in the resulting select. Backends that don't
| support ``LIMIT`` will attempt to provide similar
| functionality.
|
| .. note::
|
| The :meth:`_sql.GenerativeSelect.limit` method will replace
| any clause applied with :meth:`_sql.GenerativeSelect.fetch`.
|
| :param limit: an integer LIMIT parameter, or a SQL expression
| that provides an integer result. Pass ``None`` to reset it.
|
| .. seealso::
|
| :meth:`_sql.GenerativeSelect.fetch`
|
| :meth:`_sql.GenerativeSelect.offset`
|
| offset(self, offset: '_LimitOffsetType') -> 'Self'
| Return a new selectable with the given OFFSET criterion
| applied.
|
|
| This is a numeric value which usually renders as an ``OFFSET``
| expression in the resulting select. Backends that don't
| support ``OFFSET`` will attempt to provide similar
| functionality.
|
| :param offset: an integer OFFSET parameter, or a SQL expression
| that provides an integer result. Pass ``None`` to reset it.
|
| .. seealso::
|
| :meth:`_sql.GenerativeSelect.limit`
|
| :meth:`_sql.GenerativeSelect.fetch`
|
| order_by(self, _GenerativeSelect__first: 'Union[Literal[None, _NoArg.NO_ARG], _ColumnExpressionOrStrLabelArgument[Any]]' = _NoArg.NO_ARG, *clauses: '_ColumnExpressionOrStrLabelArgument[Any]') -> 'Self'
| Return a new selectable with the given list of ORDER BY
| criteria applied.
|
| e.g.::
|
| stmt = select(table).order_by(table.c.id, table.c.name)
|
| Calling this method multiple times is equivalent to calling it once
| with all the clauses concatenated. All existing ORDER BY criteria may
| be cancelled by passing ``None`` by itself. New ORDER BY criteria may
| then be added by invoking :meth:`_orm.Query.order_by` again, e.g.::
|
| # will erase all ORDER BY and ORDER BY new_col alone
| stmt = stmt.order_by(None).order_by(new_col)
|
| :param \*clauses: a series of :class:`_expression.ColumnElement`
| constructs which will be used to generate an ORDER BY clause.
|
| Alternatively, an individual entry may also be the string name of a
| label located elsewhere in the columns clause of the statement which
| will be matched and rendered in a backend-specific way based on
| context; see :ref:`tutorial_order_by_label` for background on string
| label matching in ORDER BY and GROUP BY expressions.
|
| .. seealso::
|
| :ref:`tutorial_order_by` - in the :ref:`unified_tutorial`
|
| :ref:`tutorial_order_by_label` - in the :ref:`unified_tutorial`
|
| set_label_style(self, style: 'SelectLabelStyle') -> 'Self'
| Return a new selectable with the specified label style.
|
| There are three "label styles" available,
| :attr:`_sql.SelectLabelStyle.LABEL_STYLE_DISAMBIGUATE_ONLY`,
| :attr:`_sql.SelectLabelStyle.LABEL_STYLE_TABLENAME_PLUS_COL`, and
| :attr:`_sql.SelectLabelStyle.LABEL_STYLE_NONE`. The default style is
| :attr:`_sql.SelectLabelStyle.LABEL_STYLE_DISAMBIGUATE_ONLY`.
|
| In modern SQLAlchemy, there is not generally a need to change the
| labeling style, as per-expression labels are more effectively used by
| making use of the :meth:`_sql.ColumnElement.label` method. In past
| versions, :data:`_sql.LABEL_STYLE_TABLENAME_PLUS_COL` was used to
| disambiguate same-named columns from different tables, aliases, or
| subqueries; the newer :data:`_sql.LABEL_STYLE_DISAMBIGUATE_ONLY` now
| applies labels only to names that conflict with an existing name so
| that the impact of this labeling is minimal.
|
| The rationale for disambiguation is mostly so that all column
| expressions are available from a given :attr:`_sql.FromClause.c`
| collection when a subquery is created.
|
| .. versionadded:: 1.4 - the
| :meth:`_sql.GenerativeSelect.set_label_style` method replaces the
| previous combination of ``.apply_labels()``, ``.with_labels()`` and
| ``use_labels=True`` methods and/or parameters.
|
| .. seealso::
|
| :data:`_sql.LABEL_STYLE_DISAMBIGUATE_ONLY`
|
| :data:`_sql.LABEL_STYLE_TABLENAME_PLUS_COL`
|
| :data:`_sql.LABEL_STYLE_NONE`
|
| :data:`_sql.LABEL_STYLE_DEFAULT`
|
| slice(self, start: 'int', stop: 'int') -> 'Self'
| Apply LIMIT / OFFSET to this statement based on a slice.
|
| The start and stop indices behave like the argument to Python's
| built-in :func:`range` function. This method provides an
| alternative to using ``LIMIT``/``OFFSET`` to get a slice of the
| query.
|
| For example, ::
|
| stmt = select(User).order_by(User.id).slice(1, 3)
|
| renders as
|
| .. sourcecode:: sql
|
| SELECT users.id AS users_id,
| users.name AS users_name
| FROM users ORDER BY users.id
| LIMIT ? OFFSET ?
| (2, 1)
|
| .. note::
|
| The :meth:`_sql.GenerativeSelect.slice` method will replace
| any clause applied with :meth:`_sql.GenerativeSelect.fetch`.
|
| .. versionadded:: 1.4 Added the :meth:`_sql.GenerativeSelect.slice`
| method generalized from the ORM.
|
| .. seealso::
|
| :meth:`_sql.GenerativeSelect.limit`
|
| :meth:`_sql.GenerativeSelect.offset`
|
| :meth:`_sql.GenerativeSelect.fetch`
|
| with_for_update(self, *, nowait: 'bool' = False, read: 'bool' = False, of: 'Optional[_ForUpdateOfArgument]' = None, skip_locked: 'bool' = False, key_share: 'bool' = False) -> 'Self'
| Specify a ``FOR UPDATE`` clause for this
| :class:`_expression.GenerativeSelect`.
|
| E.g.::
|
| stmt = select(table).with_for_update(nowait=True)
|
| On a database like PostgreSQL or Oracle Database, the above would
| render a statement like:
|
| .. sourcecode:: sql
|
| SELECT table.a, table.b FROM table FOR UPDATE NOWAIT
|
| on other backends, the ``nowait`` option is ignored and instead
| would produce:
|
| .. sourcecode:: sql
|
| SELECT table.a, table.b FROM table FOR UPDATE
|
| When called with no arguments, the statement will render with
| the suffix ``FOR UPDATE``. Additional arguments can then be
| provided which allow for common database-specific
| variants.
|
| :param nowait: boolean; will render ``FOR UPDATE NOWAIT`` on Oracle
| Database and PostgreSQL dialects.
|
| :param read: boolean; will render ``LOCK IN SHARE MODE`` on MySQL,
| ``FOR SHARE`` on PostgreSQL. On PostgreSQL, when combined with
| ``nowait``, will render ``FOR SHARE NOWAIT``.
|
| :param of: SQL expression or list of SQL expression elements,
| (typically :class:`_schema.Column` objects or a compatible expression,
| for some backends may also be a table expression) which will render
| into a ``FOR UPDATE OF`` clause; supported by PostgreSQL, Oracle
| Database, some MySQL versions and possibly others. May render as a
| table or as a column depending on backend.
|
| :param skip_locked: boolean, will render ``FOR UPDATE SKIP LOCKED`` on
| Oracle Database and PostgreSQL dialects or ``FOR SHARE SKIP LOCKED``
| if ``read=True`` is also specified.
|
| :param key_share: boolean, will render ``FOR NO KEY UPDATE``,
| or if combined with ``read=True`` will render ``FOR KEY SHARE``,
| on the PostgreSQL dialect.
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'_fetch_clause': 'Optional[ColumnElement[Any]]', '_...
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.base.DialectKWArgs:
|
| dialect_options(...)
| A collection of keyword arguments specified as dialect-specific
| options to this construct.
|
| This is a two-level nested registry, keyed to ``<dialect_name>``
| and ``<argument_name>``. For example, the ``postgresql_where``
| argument would be locatable as::
|
| arg = my_object.dialect_options["postgresql"]["where"]
|
| .. versionadded:: 0.9.2
|
| .. seealso::
|
| :attr:`.DialectKWArgs.dialect_kwargs` - flat dictionary form
|
| get_dialect_option(self, dialect: 'Dialect', argument_name: 'str', *, else_: 'Any' = None, deprecated_fallback: 'Optional[str]' = None) -> 'Any'
| Return the value of a dialect-specific option, or *else_* if
| this dialect does not register the given argument.
|
| This is useful for DDL compilers that may be inherited by
| third-party dialects whose ``construct_arguments`` do not
| include the same set of keys as the parent dialect.
|
| :param dialect: The dialect for which to retrieve the option.
| :param argument_name: The name of the argument to retrieve.
| :param else\_: The value to return if the argument is not present.
| :param deprecated_fallback: Optional dialect name to fall back to
| if the argument is not present for the current dialect. If the
| argument is present for the fallback dialect but not the current
| dialect, a deprecation warning will be emitted.
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.base.DialectKWArgs:
|
| argument_for(dialect_name: 'str', argument_name: 'str', default: 'Any') -> 'None'
| Add a new kind of dialect-specific keyword argument for this class.
|
| E.g.::
|
| Index.argument_for("mydialect", "length", None)
|
| some_index = Index("a", "b", mydialect_length=5)
|
| The :meth:`.DialectKWArgs.argument_for` method is a per-argument
| way adding extra arguments to the
| :attr:`.DefaultDialect.construct_arguments` dictionary. This
| dictionary provides a list of argument names accepted by various
| schema-level constructs on behalf of a dialect.
|
| New dialects should typically specify this dictionary all at once as a
| data member of the dialect class. The use case for ad-hoc addition of
| argument names is typically for end-user code that is also using
| a custom compilation scheme which consumes the additional arguments.
|
| :param dialect_name: name of a dialect. The dialect must be
| locatable, else a :class:`.NoSuchModuleError` is raised. The
| dialect must also include an existing
| :attr:`.DefaultDialect.construct_arguments` collection, indicating
| that it participates in the keyword-argument validation and default
| system, else :class:`.ArgumentError` is raised. If the dialect does
| not include this collection, then any keyword argument can be
| specified on behalf of this dialect already. All dialects packaged
| within SQLAlchemy include this collection, however for third party
| dialects, support may vary.
|
| :param argument_name: name of the parameter.
|
| :param default: default value of the parameter.
|
| ----------------------------------------------------------------------
| Readonly properties inherited from sqlalchemy.sql.base.DialectKWArgs:
|
| dialect_kwargs
| A collection of keyword arguments specified as dialect-specific
| options to this construct.
|
| The arguments are present here in their original ``<dialect>_<kwarg>``
| format. Only arguments that were actually passed are included;
| unlike the :attr:`.DialectKWArgs.dialect_options` collection, which
| contains all options known by this dialect including defaults.
|
| The collection is also writable; keys are accepted of the
| form ``<dialect>_<kwarg>`` where the value will be assembled
| into the list of options.
|
| .. seealso::
|
| :attr:`.DialectKWArgs.dialect_options` - nested dictionary form
|
| kwargs
| A synonym for :attr:`.DialectKWArgs.dialect_kwargs`.
|
| ----------------------------------------------------------------------
| Methods inherited from SelectBase:
|
| alias(self, name: 'Optional[str]' = None, flat: 'bool' = False) -> 'Subquery'
| 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.
|
| as_scalar(self) -> 'ScalarSelect[Any]'
| .. 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`.
|
| exists(self) -> 'Exists'
| 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
|
| label(self, name: 'Optional[str]') -> 'Label[Any]'
| Return a 'scalar' representation of this selectable, embedded as a
| subquery with a label.
|
| .. seealso::
|
| :meth:`_expression.SelectBase.scalar_subquery`.
|
| 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.
|
| scalar_subquery(self) -> 'ScalarSelect[Any]'
| 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
|
| select(self, *arg: 'Any', **kw: 'Any') -> 'Select[Any]'
| .. 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.
|
| selected_columns(...)
| 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
|
| subquery(self, name: 'Optional[str]' = None) -> '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:
|
| .. sourcecode:: sql
|
| 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:
|
| .. sourcecode:: sql
|
| 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
|
| ----------------------------------------------------------------------
| Readonly properties inherited from SelectBase:
|
| c
| .. 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.
|
| columns
|
| 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`
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from SelectBase:
|
| is_select = True
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.AllowsLambdaRole:
|
| allows_lambda = True
|
| ----------------------------------------------------------------------
| Methods inherited from HasCTE:
|
| add_cte(self, *ctes: 'CTE', nest_here: 'bool' = False) -> 'Self'
| Add one or more :class:`_sql.CTE` constructs to this statement.
|
| This method will associate the given :class:`_sql.CTE` constructs with
| the parent statement such that they will each be unconditionally
| rendered in the WITH clause of the final statement, even if not
| referenced elsewhere within the statement or any sub-selects.
|
| The optional :paramref:`.HasCTE.add_cte.nest_here` parameter when set
| to True will have the effect that each given :class:`_sql.CTE` will
| render in a WITH clause rendered directly along with this statement,
| rather than being moved to the top of the ultimate rendered statement,
| even if this statement is rendered as a subquery within a larger
| statement.
|
| This method has two general uses. One is to embed CTE statements that
| serve some purpose without being referenced explicitly, such as the use
| case of embedding a DML statement such as an INSERT or UPDATE as a CTE
| inline with a primary statement that may draw from its results
| indirectly. The other is to provide control over the exact placement
| of a particular series of CTE constructs that should remain rendered
| directly in terms of a particular statement that may be nested in a
| larger statement.
|
| E.g.::
|
| from sqlalchemy import table, column, select
|
| t = table("t", column("c1"), column("c2"))
|
| ins = t.insert().values({"c1": "x", "c2": "y"}).cte()
|
| stmt = select(t).add_cte(ins)
|
| Would render:
|
| .. sourcecode:: sql
|
| WITH anon_1 AS (
| INSERT INTO t (c1, c2) VALUES (:param_1, :param_2)
| )
| SELECT t.c1, t.c2
| FROM t
|
| Above, the "anon_1" CTE is not referenced in the SELECT
| statement, however still accomplishes the task of running an INSERT
| statement.
|
| Similarly in a DML-related context, using the PostgreSQL
| :class:`_postgresql.Insert` construct to generate an "upsert"::
|
| from sqlalchemy import table, column
| from sqlalchemy.dialects.postgresql import insert
|
| t = table("t", column("c1"), column("c2"))
|
| delete_statement_cte = t.delete().where(t.c.c1 < 1).cte("deletions")
|
| insert_stmt = insert(t).values({"c1": 1, "c2": 2})
| update_statement = insert_stmt.on_conflict_do_update(
| index_elements=[t.c.c1],
| set_={
| "c1": insert_stmt.excluded.c1,
| "c2": insert_stmt.excluded.c2,
| },
| ).add_cte(delete_statement_cte)
|
| print(update_statement)
|
| The above statement renders as:
|
| .. sourcecode:: sql
|
| WITH deletions AS (
| DELETE FROM t WHERE t.c1 < %(c1_1)s
| )
| INSERT INTO t (c1, c2) VALUES (%(c1)s, %(c2)s)
| ON CONFLICT (c1) DO UPDATE SET c1 = excluded.c1, c2 = excluded.c2
|
| .. versionadded:: 1.4.21
|
| :param \*ctes: zero or more :class:`.CTE` constructs.
|
| .. versionchanged:: 2.0 Multiple CTE instances are accepted
|
| :param nest_here: if True, the given CTE or CTEs will be rendered
| as though they specified the :paramref:`.HasCTE.cte.nesting` flag
| to ``True`` when they were added to this :class:`.HasCTE`.
| Assuming the given CTEs are not referenced in an outer-enclosing
| statement as well, the CTEs given should render at the level of
| this statement when this flag is given.
|
| .. versionadded:: 2.0
|
| .. seealso::
|
| :paramref:`.HasCTE.cte.nesting`
|
| cte(self, name: 'Optional[str]' = None, recursive: 'bool' = False, nesting: 'bool' = False) -> 'CTE'
| Return a new :class:`_expression.CTE`,
| or Common Table Expression instance.
|
| Common table expressions are a SQL standard whereby SELECT
| statements can draw upon secondary statements specified along
| with the primary statement, using a clause called "WITH".
| Special semantics regarding UNION can also be employed to
| allow "recursive" queries, where a SELECT statement can draw
| upon the set of rows that have previously been selected.
|
| CTEs can also be applied to DML constructs UPDATE, INSERT
| and DELETE on some databases, both as a source of CTE rows
| when combined with RETURNING, as well as a consumer of
| CTE rows.
|
| SQLAlchemy detects :class:`_expression.CTE` objects, which are treated
| similarly to :class:`_expression.Alias` objects, as special elements
| to be delivered to the FROM clause of the statement as well
| as to a WITH clause at the top of the statement.
|
| For special prefixes such as PostgreSQL "MATERIALIZED" and
| "NOT MATERIALIZED", the :meth:`_expression.CTE.prefix_with`
| method may be
| used to establish these.
|
| .. versionchanged:: 1.3.13 Added support for prefixes.
| In particular - MATERIALIZED and NOT MATERIALIZED.
|
| :param name: name given to the common table expression. Like
| :meth:`_expression.FromClause.alias`, the name can be left as
| ``None`` in which case an anonymous symbol will be used at query
| compile time.
| :param recursive: if ``True``, will render ``WITH RECURSIVE``.
| A recursive common table expression is intended to be used in
| conjunction with UNION ALL in order to derive rows
| from those already selected.
| :param nesting: if ``True``, will render the CTE locally to the
| statement in which it is referenced. For more complex scenarios,
| the :meth:`.HasCTE.add_cte` method using the
| :paramref:`.HasCTE.add_cte.nest_here`
| parameter may also be used to more carefully
| control the exact placement of a particular CTE.
|
| .. versionadded:: 1.4.24
|
| .. seealso::
|
| :meth:`.HasCTE.add_cte`
|
| The following examples include two from PostgreSQL's documentation at
| https://www.postgresql.org/docs/current/static/queries-with.html,
| as well as additional examples.
|
| Example 1, non recursive::
|
| from sqlalchemy import (
| Table,
| Column,
| String,
| Integer,
| MetaData,
| select,
| func,
| )
|
| metadata = MetaData()
|
| orders = Table(
| "orders",
| metadata,
| Column("region", String),
| Column("amount", Integer),
| Column("product", String),
| Column("quantity", Integer),
| )
|
| regional_sales = (
| select(orders.c.region, func.sum(orders.c.amount).label("total_sales"))
| .group_by(orders.c.region)
| .cte("regional_sales")
| )
|
|
| top_regions = (
| select(regional_sales.c.region)
| .where(
| regional_sales.c.total_sales
| > select(func.sum(regional_sales.c.total_sales) / 10)
| )
| .cte("top_regions")
| )
|
| statement = (
| select(
| orders.c.region,
| orders.c.product,
| func.sum(orders.c.quantity).label("product_units"),
| func.sum(orders.c.amount).label("product_sales"),
| )
| .where(orders.c.region.in_(select(top_regions.c.region)))
| .group_by(orders.c.region, orders.c.product)
| )
|
| result = conn.execute(statement).fetchall()
|
| Example 2, WITH RECURSIVE::
|
| from sqlalchemy import (
| Table,
| Column,
| String,
| Integer,
| MetaData,
| select,
| func,
| )
|
| metadata = MetaData()
|
| parts = Table(
| "parts",
| metadata,
| Column("part", String),
| Column("sub_part", String),
| Column("quantity", Integer),
| )
|
| included_parts = (
| select(parts.c.sub_part, parts.c.part, parts.c.quantity)
| .where(parts.c.part == "our part")
| .cte(recursive=True)
| )
|
|
| incl_alias = included_parts.alias()
| parts_alias = parts.alias()
| included_parts = included_parts.union_all(
| select(
| parts_alias.c.sub_part, parts_alias.c.part, parts_alias.c.quantity
| ).where(parts_alias.c.part == incl_alias.c.sub_part)
| )
|
| statement = select(
| included_parts.c.sub_part,
| func.sum(included_parts.c.quantity).label("total_quantity"),
| ).group_by(included_parts.c.sub_part)
|
| result = conn.execute(statement).fetchall()
|
| Example 3, an upsert using UPDATE and INSERT with CTEs::
|
| from datetime import date
| from sqlalchemy import (
| MetaData,
| Table,
| Column,
| Integer,
| Date,
| select,
| literal,
| and_,
| exists,
| )
|
| metadata = MetaData()
|
| visitors = Table(
| "visitors",
| metadata,
| Column("product_id", Integer, primary_key=True),
| Column("date", Date, primary_key=True),
| Column("count", Integer),
| )
|
| # add 5 visitors for the product_id == 1
| product_id = 1
| day = date.today()
| count = 5
|
| update_cte = (
| visitors.update()
| .where(
| and_(visitors.c.product_id == product_id, visitors.c.date == day)
| )
| .values(count=visitors.c.count + count)
| .returning(literal(1))
| .cte("update_cte")
| )
|
| upsert = visitors.insert().from_select(
| [visitors.c.product_id, visitors.c.date, visitors.c.count],
| select(literal(product_id), literal(day), literal(count)).where(
| ~exists(update_cte.select())
| ),
| )
|
| connection.execute(upsert)
|
| Example 4, Nesting CTE (SQLAlchemy 1.4.24 and above)::
|
| value_a = select(literal("root").label("n")).cte("value_a")
|
| # A nested CTE with the same name as the root one
| value_a_nested = select(literal("nesting").label("n")).cte(
| "value_a", nesting=True
| )
|
| # Nesting CTEs takes ascendency locally
| # over the CTEs at a higher level
| value_b = select(value_a_nested.c.n).cte("value_b")
|
| value_ab = select(value_a.c.n.label("a"), value_b.c.n.label("b"))
|
| The above query will render the second CTE nested inside the first,
| shown with inline parameters below as:
|
| .. sourcecode:: sql
|
| WITH
| value_a AS
| (SELECT 'root' AS n),
| value_b AS
| (WITH value_a AS
| (SELECT 'nesting' AS n)
| SELECT value_a.n AS n FROM value_a)
| SELECT value_a.n AS a, value_b.n AS b
| FROM value_a, value_b
|
| The same CTE can be set up using the :meth:`.HasCTE.add_cte` method
| as follows (SQLAlchemy 2.0 and above)::
|
| value_a = select(literal("root").label("n")).cte("value_a")
|
| # A nested CTE with the same name as the root one
| value_a_nested = select(literal("nesting").label("n")).cte("value_a")
|
| # Nesting CTEs takes ascendency locally
| # over the CTEs at a higher level
| value_b = (
| select(value_a_nested.c.n)
| .add_cte(value_a_nested, nest_here=True)
| .cte("value_b")
| )
|
| value_ab = select(value_a.c.n.label("a"), value_b.c.n.label("b"))
|
| Example 5, Non-Linear CTE (SQLAlchemy 1.4.28 and above)::
|
| edge = Table(
| "edge",
| metadata,
| Column("id", Integer, primary_key=True),
| Column("left", Integer),
| Column("right", Integer),
| )
|
| root_node = select(literal(1).label("node")).cte("nodes", recursive=True)
|
| left_edge = select(edge.c.left).join(
| root_node, edge.c.right == root_node.c.node
| )
| right_edge = select(edge.c.right).join(
| root_node, edge.c.left == root_node.c.node
| )
|
| subgraph_cte = root_node.union(left_edge, right_edge)
|
| subgraph = select(subgraph_cte)
|
| The above query will render 2 UNIONs inside the recursive CTE:
|
| .. sourcecode:: sql
|
| WITH RECURSIVE nodes(node) AS (
| SELECT 1 AS node
| UNION
| SELECT edge."left" AS "left"
| FROM edge JOIN nodes ON edge."right" = nodes.node
| UNION
| SELECT edge."right" AS "right"
| FROM edge JOIN nodes ON edge."left" = nodes.node
| )
| SELECT nodes.node FROM nodes
|
| .. seealso::
|
| :meth:`_orm.Query.cte` - ORM version of
| :meth:`_expression.HasCTE.cte`.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from HasCTE:
|
| name_cte_columns = False
|
| ----------------------------------------------------------------------
| Methods inherited from Selectable:
|
| 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.
|
| 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`.
|
| .. deprecated:: 1.4 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.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from Selectable:
|
| __visit_name__ = 'selectable'
|
| is_selectable = True
|
| ----------------------------------------------------------------------
| Methods inherited from ReturnsRows:
|
| 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.
|
| ----------------------------------------------------------------------
| Readonly properties inherited from ReturnsRows:
|
| selectable
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.SQLRole:
|
| uses_inspection = False
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.elements.ClauseElement:
|
| __bool__(self)
|
| __getstate__(self)
| Helper for pickle.
|
| __invert__(self)
|
| __repr__(self)
| Return repr(self).
|
| compare(self, other: 'ClauseElement', **kw: 'Any') -> 'bool'
| Compare this :class:`_expression.ClauseElement` to
| the given :class:`_expression.ClauseElement`.
|
| Subclasses should override the default behavior, which is a
| straight identity comparison.
|
| \**kw are arguments consumed by subclass ``compare()`` methods and
| may be used to modify the criteria for comparison
| (see :class:`_expression.ColumnElement`).
|
| description(...)
|
| entity_namespace(...)
|
| params(self, _ClauseElement__optionaldict: 'Optional[Mapping[str, Any]]' = None, **kwargs: 'Any') -> 'Self'
| Return a copy with :func:`_expression.bindparam` elements
| replaced.
|
| Returns a copy of this ClauseElement with
| :func:`_expression.bindparam`
| elements replaced with values taken from the given dictionary::
|
| >>> clause = column("x") + bindparam("foo")
| >>> print(clause.compile().params)
| {'foo':None}
| >>> print(clause.params({"foo": 7}).compile().params)
| {'foo':7}
|
| self_group(self, against: 'Optional[OperatorType]' = None) -> 'ClauseElement'
| 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.
|
| unique_params(self, _ClauseElement__optionaldict: 'Optional[Dict[str, Any]]' = None, **kwargs: 'Any') -> 'Self'
| Return a copy with :func:`_expression.bindparam` elements
| replaced.
|
| Same functionality as :meth:`_expression.ClauseElement.params`,
| except adds `unique=True`
| to affected bind parameters so that multiple statements can be
| used.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.elements.ClauseElement:
|
| is_clause_element = True
|
| is_dml = False
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.cache_key.HasCacheKey:
|
| inherit_cache = None
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_instancemethod(fn: '_F') -> '_F'
| Decorate a method memoize its return value.
|
| :meta private:
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_attribute = <class 'sqlalchemy.util.langhelpers.HasMemoized.m...
| A read-only @property that is only evaluated once.
|
| :meta private:
|
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.visitors.HasTraverseInternals:
|
| get_children(self, *, omit_attrs: 'Tuple[str, ...]' = (), **kw: 'Any') -> 'Iterable[HasTraverseInternals]'
| Return immediate child :class:`.visitors.HasTraverseInternals`
| elements of this :class:`.visitors.HasTraverseInternals`.
|
| This is used for visit traversal.
|
| \**kw may contain flags that change the collection that is
| returned, for example to return a subset of items in order to
| cut down on larger traversals, or to return child items from a
| different context (such as schema-level collections instead of
| clause-level).
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.elements.CompilerElement:
|
| __str__(self) -> 'str'
| Return str(self).
|
| compile(self, bind: 'Optional[_HasDialect]' = None, dialect: 'Optional[Dialect]' = None, **kw: 'Any') -> 'Compiled'
| Compile this SQL expression.
|
| The return value is a :class:`~.Compiled` object.
| Calling ``str()`` or ``unicode()`` on the returned value will yield a
| string representation of the result. The
| :class:`~.Compiled` object also can return a
| dictionary of bind parameter names and values
| using the ``params`` accessor.
|
| :param bind: An :class:`.Connection` or :class:`.Engine` which
| can provide a :class:`.Dialect` in order to generate a
| :class:`.Compiled` object. If the ``bind`` and
| ``dialect`` parameters are both omitted, a default SQL compiler
| is used.
|
| :param column_keys: Used for INSERT and UPDATE statements, a list of
| column names which should be present in the VALUES clause of the
| compiled statement. If ``None``, all columns from the target table
| object are rendered.
|
| :param dialect: A :class:`.Dialect` instance which can generate
| a :class:`.Compiled` object. This argument takes precedence over
| the ``bind`` argument.
|
| :param compile_kwargs: optional dictionary of additional parameters
| that will be passed through to the compiler within all "visit"
| methods. This allows any custom flag to be passed through to
| a custom compilation construct, for example. It is also used
| for the case of passing the ``literal_binds`` flag through::
|
| from sqlalchemy.sql import table, column, select
|
| t = table("t", column("x"))
|
| s = select(t).where(t.c.x == 5)
|
| print(s.compile(compile_kwargs={"literal_binds": True}))
|
| .. seealso::
|
| :ref:`faq_sql_expression_string`
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.elements.CompilerElement:
|
| stringify_dialect = 'default'
|
| supports_execution = False
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.visitors.Visitable:
|
| __class_getitem__(key: 'Any') -> 'Any'
|
| __init_subclass__() -> 'None'
| This method is called when a class is subclassed.
|
| The default implementation does nothing. It may be
| overridden to extend subclasses.
sqlalchemy.Grouping
Python Library Documentation: class Grouping in module sqlalchemy.sql.elements
class Grouping(GroupedElement, ColumnElement)
| Grouping(element: 'Union[TextClause, ClauseList, ColumnElement[_T]]')
|
| Represent a grouping within a column expression
|
| Method resolution order:
| Grouping
| GroupedElement
| ColumnElement
| sqlalchemy.sql.roles.ColumnArgumentOrKeyRole
| sqlalchemy.sql.roles.ColumnArgumentRole
| sqlalchemy.sql.roles.StatementOptionRole
| sqlalchemy.sql.roles.WhereHavingRole
| sqlalchemy.sql.roles.OnClauseRole
| sqlalchemy.sql.roles.BinaryElementRole
| sqlalchemy.sql.roles.OrderByRole
| sqlalchemy.sql.roles.ColumnsClauseRole
| sqlalchemy.sql.roles.AllowsLambdaRole
| sqlalchemy.sql.roles.ByOfRole
| sqlalchemy.sql.roles.UsesInspection
| sqlalchemy.sql.roles.ColumnListRole
| sqlalchemy.sql.roles.LimitOffsetRole
| sqlalchemy.sql.roles.DMLColumnRole
| sqlalchemy.sql.roles.DDLConstraintColumnRole
| sqlalchemy.sql.roles.DDLExpressionRole
| sqlalchemy.sql.roles.StructuralRole
| SQLColumnExpression
| SQLCoreOperations
| sqlalchemy.sql.roles.ExpressionElementRole
| sqlalchemy.sql.roles.TypedColumnsClauseRole
| typing.Generic
| sqlalchemy.sql.operators.ColumnOperators
| sqlalchemy.sql.operators.Operators
| sqlalchemy.util.langhelpers.TypingOnly
| sqlalchemy.sql.roles.SQLRole
| DQLDMLClauseElement
| ClauseElement
| sqlalchemy.sql.annotation.SupportsWrappingAnnotations
| sqlalchemy.sql.annotation.SupportsAnnotations
| sqlalchemy.sql.cache_key.MemoizedHasCacheKey
| sqlalchemy.sql.cache_key.HasCacheKey
| sqlalchemy.util.langhelpers.HasMemoized
| sqlalchemy.sql.traversals.HasCopyInternals
| sqlalchemy.sql.visitors.ExternallyTraversible
| sqlalchemy.sql.visitors.HasTraverseInternals
| CompilerElement
| sqlalchemy.sql.visitors.Visitable
| builtins.object
|
| Methods defined here:
|
| __getattr__(self, attr)
|
| __getstate__(self)
| Helper for pickle.
|
| __init__(self, element: 'Union[TextClause, ClauseList, ColumnElement[_T]]')
| Initialize self. See help(type(self)) for accurate signature.
|
| __setstate__(self, state)
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'_traverse_internals': '_TraverseInternalsType', 'e...
|
| __orig_bases__ = (<class 'sqlalchemy.sql.elements.GroupedElement'>, sq...
|
| __parameters__ = (~_T,)
|
| ----------------------------------------------------------------------
| Methods inherited from GroupedElement:
|
| self_group(self, against: 'Optional[OperatorType]' = None) -> 'Self'
| 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.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from GroupedElement:
|
| __visit_name__ = 'grouping'
|
| ----------------------------------------------------------------------
| Methods inherited from ColumnElement:
|
| base_columns(...)
|
| cast(self, type_: '_TypeEngineArgument[_OPT]') -> 'Cast[_OPT]'
| Produce a type cast, i.e. ``CAST(<expression> AS <type>)``.
|
| This is a shortcut to the :func:`_expression.cast` function.
|
| .. seealso::
|
| :ref:`tutorial_casts`
|
| :func:`_expression.cast`
|
| :func:`_expression.type_coerce`
|
| comparator(...)
|
| label(self, name: 'Optional[str]') -> 'Label[_T]'
| Produce a column label, i.e. ``<columnname> AS <name>``.
|
| This is a shortcut to the :func:`_expression.label` function.
|
| If 'name' is ``None``, an anonymous label name will be generated.
|
| operate(self, op: 'operators.OperatorType', *other: 'Any', **kwargs: 'Any') -> 'ColumnElement[Any]'
| Operate on an argument.
|
| This is the lowest level of operation, raises
| :class:`NotImplementedError` by default.
|
| Overriding this on a subclass can allow common
| behavior to be applied to all operations.
| For example, overriding :class:`.ColumnOperators`
| to apply ``func.lower()`` to the left and right
| side::
|
| class MyComparator(ColumnOperators):
| def operate(self, op, other, **kwargs):
| return op(func.lower(self), func.lower(other), **kwargs)
|
| :param op: Operator callable.
| :param \*other: the 'other' side of the operation. Will
| be a single scalar for most operations.
| :param \**kwargs: modifiers. These may be passed by special
| operators such as :meth:`ColumnOperators.contains`.
|
| proxy_set(...)
| set of all columns we are proxying
|
| as of 2.0 this is explicitly deannotated columns. previously it was
| effectively deannotated columns but wasn't enforced. annotated
| columns should basically not go into sets if at all possible because
| their hashing behavior is very non-performant.
|
| reverse_operate(self, op: 'operators.OperatorType', other: 'Any', **kwargs: 'Any') -> 'ColumnElement[Any]'
| Reverse operate on an argument.
|
| Usage is the same as :meth:`operate`.
|
| shares_lineage(self, othercolumn: 'ColumnElement[Any]') -> 'bool'
| Return True if the given :class:`_expression.ColumnElement`
| has a common ancestor to this :class:`_expression.ColumnElement`.
|
| type(...)
|
| ----------------------------------------------------------------------
| Readonly properties inherited from ColumnElement:
|
| anon_key_label
| .. deprecated:: 1.4 The :attr:`_expression.ColumnElement.anon_key_label` attribute is now private, and the public accessor is deprecated.
|
| anon_label
| .. deprecated:: 1.4 The :attr:`_expression.ColumnElement.anon_label` attribute is now private, and the public accessor is deprecated.
|
| expression
| Return a column expression.
|
| Part of the inspection interface; returns self.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from ColumnElement:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from ColumnElement:
|
| foreign_keys = frozenset()
|
| key = None
|
| primary_key = False
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.AllowsLambdaRole:
|
| allows_lambda = True
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.UsesInspection:
|
| uses_inspection = True
|
| ----------------------------------------------------------------------
| Class methods inherited from typing.Generic:
|
| __class_getitem__(...)
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__(...)
| Function to initialize subclasses.
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.operators.ColumnOperators:
|
| __add__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``+`` operator.
|
| In a column context, produces the clause ``a + b``
| if the parent object has non-string affinity.
| If the parent object has a string affinity,
| produces the concatenation operator, ``a || b`` -
| see :meth:`.ColumnOperators.concat`.
|
| __contains__(self, other: 'Any') -> 'ColumnOperators'
|
| __eq__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``==`` operator.
|
| In a column context, produces the clause ``a = b``.
| If the target is ``None``, produces ``a IS NULL``.
|
| __floordiv__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``//`` operator.
|
| In a column context, produces the clause ``a / b``,
| which is the same as "truediv", but considers the result
| type to be integer.
|
| .. versionadded:: 2.0
|
| __ge__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``>=`` operator.
|
| In a column context, produces the clause ``a >= b``.
|
| __getitem__(self, index: 'Any') -> 'ColumnOperators'
| Implement the [] operator.
|
| This can be used by some database-specific types
| such as PostgreSQL ARRAY and HSTORE.
|
| __gt__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``>`` operator.
|
| In a column context, produces the clause ``a > b``.
|
| __hash__(self, /) from builtins.object
| Return hash(self).
|
| __le__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``<=`` operator.
|
| In a column context, produces the clause ``a <= b``.
|
| __lshift__(self, other: 'Any') -> 'ColumnOperators'
| implement the << operator.
|
| Not used by SQLAlchemy core, this is provided
| for custom operator systems which want to use
| << as an extension point.
|
| __lt__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``<`` operator.
|
| In a column context, produces the clause ``a < b``.
|
| __mod__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``%`` operator.
|
| In a column context, produces the clause ``a % b``.
|
| __mul__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``*`` operator.
|
| In a column context, produces the clause ``a * b``.
|
| __ne__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``!=`` operator.
|
| In a column context, produces the clause ``a != b``.
| If the target is ``None``, produces ``a IS NOT NULL``.
|
| __neg__(self) -> 'ColumnOperators'
| Implement the ``-`` operator.
|
| In a column context, produces the clause ``-a``.
|
| __radd__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``+`` operator in reverse.
|
| See :meth:`.ColumnOperators.__add__`.
|
| __rfloordiv__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``//`` operator in reverse.
|
| See :meth:`.ColumnOperators.__floordiv__`.
|
| __rmod__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``%`` operator in reverse.
|
| See :meth:`.ColumnOperators.__mod__`.
|
| __rmul__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``*`` operator in reverse.
|
| See :meth:`.ColumnOperators.__mul__`.
|
| __rshift__(self, other: 'Any') -> 'ColumnOperators'
| implement the >> operator.
|
| Not used by SQLAlchemy core, this is provided
| for custom operator systems which want to use
| >> as an extension point.
|
| __rsub__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``-`` operator in reverse.
|
| See :meth:`.ColumnOperators.__sub__`.
|
| __rtruediv__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``/`` operator in reverse.
|
| See :meth:`.ColumnOperators.__truediv__`.
|
| __sub__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``-`` operator.
|
| In a column context, produces the clause ``a - b``.
|
| __truediv__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``/`` operator.
|
| In a column context, produces the clause ``a / b``, and
| considers the result type to be numeric.
|
| .. versionchanged:: 2.0 The truediv operator against two integers
| is now considered to return a numeric value. Behavior on specific
| backends may vary.
|
| all_(self) -> 'ColumnOperators'
| Produce an :func:`_expression.all_` clause against the
| parent object.
|
| See the documentation for :func:`_sql.all_` for examples.
|
| .. note:: be sure to not confuse the newer
| :meth:`_sql.ColumnOperators.all_` method with the **legacy**
| version of this method, the :meth:`_types.ARRAY.Comparator.all`
| method that's specific to :class:`_types.ARRAY`, which uses a
| different calling style.
|
| any_(self) -> 'ColumnOperators'
| Produce an :func:`_expression.any_` clause against the
| parent object.
|
| See the documentation for :func:`_sql.any_` for examples.
|
| .. note:: be sure to not confuse the newer
| :meth:`_sql.ColumnOperators.any_` method with the **legacy**
| version of this method, the :meth:`_types.ARRAY.Comparator.any`
| method that's specific to :class:`_types.ARRAY`, which uses a
| different calling style.
|
| asc(self) -> 'ColumnOperators'
| Produce a :func:`_expression.asc` clause against the
| parent object.
|
| between(self, cleft: 'Any', cright: 'Any', symmetric: 'bool' = False) -> 'ColumnOperators'
| Produce a :func:`_expression.between` clause against
| the parent object, given the lower and upper range.
|
| bitwise_and(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise AND operation, typically via the ``&``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_lshift(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise LSHIFT operation, typically via the ``<<``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_not(self) -> 'ColumnOperators'
| Produce a bitwise NOT operation, typically via the ``~``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_or(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise OR operation, typically via the ``|``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_rshift(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise RSHIFT operation, typically via the ``>>``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_xor(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise XOR operation, typically via the ``^``
| operator, or ``#`` for PostgreSQL.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| collate(self, collation: 'str') -> 'ColumnOperators'
| Produce a :func:`_expression.collate` clause against
| the parent object, given the collation string.
|
| .. seealso::
|
| :func:`_expression.collate`
|
| concat(self, other: 'Any') -> 'ColumnOperators'
| Implement the 'concat' operator.
|
| In a column context, produces the clause ``a || b``,
| or uses the ``concat()`` operator on MySQL.
|
| contains(self, other: 'Any', **kw: 'Any') -> 'ColumnOperators'
| Implement the 'contains' operator.
|
| Produces a LIKE expression that tests against a match for the middle
| of a string value:
|
| .. sourcecode:: sql
|
| column LIKE '%' || <other> || '%'
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.contains("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.contains.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.contains.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.contains.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.contains("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE '%' || :param || '%' ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.contains("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE '%' || :param || '%' ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.contains.autoescape`::
|
| somecolumn.contains("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.startswith`
|
| :meth:`.ColumnOperators.endswith`
|
| :meth:`.ColumnOperators.like`
|
| desc(self) -> 'ColumnOperators'
| Produce a :func:`_expression.desc` clause against the
| parent object.
|
| distinct(self) -> 'ColumnOperators'
| Produce a :func:`_expression.distinct` clause against the
| parent object.
|
| endswith(self, other: 'Any', escape: 'Optional[str]' = None, autoescape: 'bool' = False) -> 'ColumnOperators'
| Implement the 'endswith' operator.
|
| Produces a LIKE expression that tests against a match for the end
| of a string value:
|
| .. sourcecode:: sql
|
| column LIKE '%' || <other>
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.endswith("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.endswith.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.endswith.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.endswith.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.endswith("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE '%' || :param ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.endswith("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE '%' || :param ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.endswith.autoescape`::
|
| somecolumn.endswith("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.startswith`
|
| :meth:`.ColumnOperators.contains`
|
| :meth:`.ColumnOperators.like`
|
| icontains(self, other: 'Any', **kw: 'Any') -> 'ColumnOperators'
| Implement the ``icontains`` operator, e.g. case insensitive
| version of :meth:`.ColumnOperators.contains`.
|
| Produces a LIKE expression that tests against an insensitive match
| for the middle of a string value:
|
| .. sourcecode:: sql
|
| lower(column) LIKE '%' || lower(<other>) || '%'
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.icontains("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.icontains.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.icontains.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.icontains.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.icontains("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE '%' || lower(:param) || '%' ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.icontains("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE '%' || lower(:param) || '%' ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.contains.autoescape`::
|
| somecolumn.icontains("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.contains`
|
| iendswith(self, other: 'Any', escape: 'Optional[str]' = None, autoescape: 'bool' = False) -> 'ColumnOperators'
| Implement the ``iendswith`` operator, e.g. case insensitive
| version of :meth:`.ColumnOperators.endswith`.
|
| Produces a LIKE expression that tests against an insensitive match
| for the end of a string value:
|
| .. sourcecode:: sql
|
| lower(column) LIKE '%' || lower(<other>)
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.iendswith("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.iendswith.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.iendswith.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.iendswith.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.iendswith("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE '%' || lower(:param) ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.iendswith("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE '%' || lower(:param) ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.iendswith.autoescape`::
|
| somecolumn.endswith("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.endswith`
|
| ilike(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
| Implement the ``ilike`` operator, e.g. case insensitive LIKE.
|
| In a column context, produces an expression either of the form:
|
| .. sourcecode:: sql
|
| lower(a) LIKE lower(other)
|
| Or on backends that support the ILIKE operator:
|
| .. sourcecode:: sql
|
| a ILIKE other
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.ilike("%foobar%"))
|
| :param other: expression to be compared
| :param escape: optional escape character, renders the ``ESCAPE``
| keyword, e.g.::
|
| somecolumn.ilike("foo/%bar", escape="/")
|
| .. seealso::
|
| :meth:`.ColumnOperators.like`
|
| in_(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``in`` operator.
|
| In a column context, produces the clause ``column IN <other>``.
|
| The given parameter ``other`` may be:
|
| * A list of literal values,
| e.g.::
|
| stmt.where(column.in_([1, 2, 3]))
|
| In this calling form, the list of items is converted to a set of
| bound parameters the same length as the list given:
|
| .. sourcecode:: sql
|
| WHERE COL IN (?, ?, ?)
|
| * A list of tuples may be provided if the comparison is against a
| :func:`.tuple_` containing multiple expressions::
|
| from sqlalchemy import tuple_
|
| stmt.where(tuple_(col1, col2).in_([(1, 10), (2, 20), (3, 30)]))
|
| * An empty list,
| e.g.::
|
| stmt.where(column.in_([]))
|
| In this calling form, the expression renders an "empty set"
| expression. These expressions are tailored to individual backends
| and are generally trying to get an empty SELECT statement as a
| subquery. Such as on SQLite, the expression is:
|
| .. sourcecode:: sql
|
| WHERE col IN (SELECT 1 FROM (SELECT 1) WHERE 1!=1)
|
| .. versionchanged:: 1.4 empty IN expressions now use an
| execution-time generated SELECT subquery in all cases.
|
| * A bound parameter, e.g. :func:`.bindparam`, may be used if it
| includes the :paramref:`.bindparam.expanding` flag::
|
| stmt.where(column.in_(bindparam("value", expanding=True)))
|
| In this calling form, the expression renders a special non-SQL
| placeholder expression that looks like:
|
| .. sourcecode:: sql
|
| WHERE COL IN ([EXPANDING_value])
|
| This placeholder expression is intercepted at statement execution
| time to be converted into the variable number of bound parameter
| form illustrated earlier. If the statement were executed as::
|
| connection.execute(stmt, {"value": [1, 2, 3]})
|
| The database would be passed a bound parameter for each value:
|
| .. sourcecode:: sql
|
| WHERE COL IN (?, ?, ?)
|
| .. versionadded:: 1.2 added "expanding" bound parameters
|
| If an empty list is passed, a special "empty list" expression,
| which is specific to the database in use, is rendered. On
| SQLite this would be:
|
| .. sourcecode:: sql
|
| WHERE COL IN (SELECT 1 FROM (SELECT 1) WHERE 1!=1)
|
| .. versionadded:: 1.3 "expanding" bound parameters now support
| empty lists
|
| * a :func:`_expression.select` construct, which is usually a
| correlated scalar select::
|
| stmt.where(
| column.in_(select(othertable.c.y).where(table.c.x == othertable.c.x))
| )
|
| In this calling form, :meth:`.ColumnOperators.in_` renders as given:
|
| .. sourcecode:: sql
|
| WHERE COL IN (SELECT othertable.y
| FROM othertable WHERE othertable.x = table.x)
|
| :param other: a list of literals, a :func:`_expression.select`
| construct, or a :func:`.bindparam` construct that includes the
| :paramref:`.bindparam.expanding` flag set to True.
|
| is_(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``IS`` operator.
|
| Normally, ``IS`` is generated automatically when comparing to a
| value of ``None``, which resolves to ``NULL``. However, explicit
| usage of ``IS`` may be desirable if comparing to boolean values
| on certain platforms.
|
| .. seealso:: :meth:`.ColumnOperators.is_not`
|
| is_distinct_from(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``IS DISTINCT FROM`` operator.
|
| Renders "a IS DISTINCT FROM b" on most platforms;
| on some such as SQLite may render "a IS NOT b".
|
| is_not(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``IS NOT`` operator.
|
| Normally, ``IS NOT`` is generated automatically when comparing to a
| value of ``None``, which resolves to ``NULL``. However, explicit
| usage of ``IS NOT`` may be desirable if comparing to boolean values
| on certain platforms.
|
| .. versionchanged:: 1.4 The ``is_not()`` operator is renamed from
| ``isnot()`` in previous releases. The previous name remains
| available for backwards compatibility.
|
| .. seealso:: :meth:`.ColumnOperators.is_`
|
| is_not_distinct_from(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``IS NOT DISTINCT FROM`` operator.
|
| Renders "a IS NOT DISTINCT FROM b" on most platforms;
| on some such as SQLite may render "a IS b".
|
| .. versionchanged:: 1.4 The ``is_not_distinct_from()`` operator is
| renamed from ``isnot_distinct_from()`` in previous releases.
| The previous name remains available for backwards compatibility.
|
| isnot = is_not(self, other: 'Any') -> 'ColumnOperators'
|
| isnot_distinct_from = is_not_distinct_from(self, other: 'Any') -> 'ColumnOperators'
|
| istartswith(self, other: 'Any', escape: 'Optional[str]' = None, autoescape: 'bool' = False) -> 'ColumnOperators'
| Implement the ``istartswith`` operator, e.g. case insensitive
| version of :meth:`.ColumnOperators.startswith`.
|
| Produces a LIKE expression that tests against an insensitive
| match for the start of a string value:
|
| .. sourcecode:: sql
|
| lower(column) LIKE lower(<other>) || '%'
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.istartswith("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.istartswith.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.istartswith.escape` parameter will
| establish a given character as an escape character which can be of
| use when the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.istartswith.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.istartswith("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE lower(:param) || '%' ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.istartswith("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE lower(:param) || '%' ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.istartswith.autoescape`::
|
| somecolumn.istartswith("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.startswith`
|
| like(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
| Implement the ``like`` operator.
|
| In a column context, produces the expression:
|
| .. sourcecode:: sql
|
| a LIKE other
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.like("%foobar%"))
|
| :param other: expression to be compared
| :param escape: optional escape character, renders the ``ESCAPE``
| keyword, e.g.::
|
| somecolumn.like("foo/%bar", escape="/")
|
| .. seealso::
|
| :meth:`.ColumnOperators.ilike`
|
| match(self, other: 'Any', **kwargs: 'Any') -> 'ColumnOperators'
| Implements a database-specific 'match' operator.
|
| :meth:`_sql.ColumnOperators.match` attempts to resolve to
| a MATCH-like function or operator provided by the backend.
| Examples include:
|
| * PostgreSQL - renders ``x @@ plainto_tsquery(y)``
|
| .. versionchanged:: 2.0 ``plainto_tsquery()`` is used instead
| of ``to_tsquery()`` for PostgreSQL now; for compatibility with
| other forms, see :ref:`postgresql_match`.
|
|
| * MySQL - renders ``MATCH (x) AGAINST (y IN BOOLEAN MODE)``
|
| .. seealso::
|
| :class:`_mysql.match` - MySQL specific construct with
| additional features.
|
| * Oracle Database - renders ``CONTAINS(x, y)``
| * other backends may provide special implementations.
| * Backends without any special implementation will emit
| the operator as "MATCH". This is compatible with SQLite, for
| example.
|
| not_ilike(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
| implement the ``NOT ILIKE`` operator.
|
| This is equivalent to using negation with
| :meth:`.ColumnOperators.ilike`, i.e. ``~x.ilike(y)``.
|
| .. versionchanged:: 1.4 The ``not_ilike()`` operator is renamed from
| ``notilike()`` in previous releases. The previous name remains
| available for backwards compatibility.
|
| .. seealso::
|
| :meth:`.ColumnOperators.ilike`
|
| not_in(self, other: 'Any') -> 'ColumnOperators'
| implement the ``NOT IN`` operator.
|
| This is equivalent to using negation with
| :meth:`.ColumnOperators.in_`, i.e. ``~x.in_(y)``.
|
| In the case that ``other`` is an empty sequence, the compiler
| produces an "empty not in" expression. This defaults to the
| expression "1 = 1" to produce true in all cases. The
| :paramref:`_sa.create_engine.empty_in_strategy` may be used to
| alter this behavior.
|
| .. versionchanged:: 1.4 The ``not_in()`` operator is renamed from
| ``notin_()`` in previous releases. The previous name remains
| available for backwards compatibility.
|
| .. versionchanged:: 1.2 The :meth:`.ColumnOperators.in_` and
| :meth:`.ColumnOperators.not_in` operators
| now produce a "static" expression for an empty IN sequence
| by default.
|
| .. seealso::
|
| :meth:`.ColumnOperators.in_`
|
| not_like(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
| implement the ``NOT LIKE`` operator.
|
| This is equivalent to using negation with
| :meth:`.ColumnOperators.like`, i.e. ``~x.like(y)``.
|
| .. versionchanged:: 1.4 The ``not_like()`` operator is renamed from
| ``notlike()`` in previous releases. The previous name remains
| available for backwards compatibility.
|
| .. seealso::
|
| :meth:`.ColumnOperators.like`
|
| notilike = not_ilike(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
|
| notin_ = not_in(self, other: 'Any') -> 'ColumnOperators'
|
| notlike = not_like(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
|
| nulls_first(self) -> 'ColumnOperators'
| Produce a :func:`_expression.nulls_first` clause against the
| parent object.
|
| .. versionchanged:: 1.4 The ``nulls_first()`` operator is
| renamed from ``nullsfirst()`` in previous releases.
| The previous name remains available for backwards compatibility.
|
| nulls_last(self) -> 'ColumnOperators'
| Produce a :func:`_expression.nulls_last` clause against the
| parent object.
|
| .. versionchanged:: 1.4 The ``nulls_last()`` operator is
| renamed from ``nullslast()`` in previous releases.
| The previous name remains available for backwards compatibility.
|
| nullsfirst = nulls_first(self) -> 'ColumnOperators'
|
| nullslast = nulls_last(self) -> 'ColumnOperators'
|
| regexp_match(self, pattern: 'Any', flags: 'Optional[str]' = None) -> 'ColumnOperators'
| Implements a database-specific 'regexp match' operator.
|
| E.g.::
|
| stmt = select(table.c.some_column).where(
| table.c.some_column.regexp_match("^(b|c)")
| )
|
| :meth:`_sql.ColumnOperators.regexp_match` attempts to resolve to
| a REGEXP-like function or operator provided by the backend, however
| the specific regular expression syntax and flags available are
| **not backend agnostic**.
|
| Examples include:
|
| * PostgreSQL - renders ``x ~ y`` or ``x !~ y`` when negated.
| * Oracle Database - renders ``REGEXP_LIKE(x, y)``
| * SQLite - uses SQLite's ``REGEXP`` placeholder operator and calls into
| the Python ``re.match()`` builtin.
| * other backends may provide special implementations.
| * Backends without any special implementation will emit
| the operator as "REGEXP" or "NOT REGEXP". This is compatible with
| SQLite and MySQL, for example.
|
| Regular expression support is currently implemented for Oracle
| Database, PostgreSQL, MySQL and MariaDB. Partial support is available
| for SQLite. Support among third-party dialects may vary.
|
| :param pattern: The regular expression pattern string or column
| clause.
| :param flags: Any regular expression string flags to apply, passed as
| plain Python string only. These flags are backend specific.
| Some backends, like PostgreSQL and MariaDB, may alternatively
| specify the flags as part of the pattern.
| When using the ignore case flag 'i' in PostgreSQL, the ignore case
| regexp match operator ``~*`` or ``!~*`` will be used.
|
| .. versionadded:: 1.4
|
| .. versionchanged:: 1.4.48, 2.0.18 Note that due to an implementation
| error, the "flags" parameter previously accepted SQL expression
| objects such as column expressions in addition to plain Python
| strings. This implementation did not work correctly with caching
| and was removed; strings only should be passed for the "flags"
| parameter, as these flags are rendered as literal inline values
| within SQL expressions.
|
| .. seealso::
|
| :meth:`_sql.ColumnOperators.regexp_replace`
|
| regexp_replace(self, pattern: 'Any', replacement: 'Any', flags: 'Optional[str]' = None) -> 'ColumnOperators'
| Implements a database-specific 'regexp replace' operator.
|
| E.g.::
|
| stmt = select(
| table.c.some_column.regexp_replace("b(..)", "XY", flags="g")
| )
|
| :meth:`_sql.ColumnOperators.regexp_replace` attempts to resolve to
| a REGEXP_REPLACE-like function provided by the backend, that
| usually emit the function ``REGEXP_REPLACE()``. However,
| the specific regular expression syntax and flags available are
| **not backend agnostic**.
|
| Regular expression replacement support is currently implemented for
| Oracle Database, PostgreSQL, MySQL 8 or greater and MariaDB. Support
| among third-party dialects may vary.
|
| :param pattern: The regular expression pattern string or column
| clause.
| :param pattern: The replacement string or column clause.
| :param flags: Any regular expression string flags to apply, passed as
| plain Python string only. These flags are backend specific.
| Some backends, like PostgreSQL and MariaDB, may alternatively
| specify the flags as part of the pattern.
|
| .. versionadded:: 1.4
|
| .. versionchanged:: 1.4.48, 2.0.18 Note that due to an implementation
| error, the "flags" parameter previously accepted SQL expression
| objects such as column expressions in addition to plain Python
| strings. This implementation did not work correctly with caching
| and was removed; strings only should be passed for the "flags"
| parameter, as these flags are rendered as literal inline values
| within SQL expressions.
|
|
| .. seealso::
|
| :meth:`_sql.ColumnOperators.regexp_match`
|
| startswith(self, other: 'Any', escape: 'Optional[str]' = None, autoescape: 'bool' = False) -> 'ColumnOperators'
| Implement the ``startswith`` operator.
|
| Produces a LIKE expression that tests against a match for the start
| of a string value:
|
| .. sourcecode:: sql
|
| column LIKE <other> || '%'
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.startswith("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.startswith.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.startswith.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.startswith.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.startswith("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE :param || '%' ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.startswith("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE :param || '%' ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.startswith.autoescape`::
|
| somecolumn.startswith("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.endswith`
|
| :meth:`.ColumnOperators.contains`
|
| :meth:`.ColumnOperators.like`
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.operators.ColumnOperators:
|
| timetuple = None
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.operators.Operators:
|
| __and__(self, other: 'Any') -> 'Operators'
| Implement the ``&`` operator.
|
| When used with SQL expressions, results in an
| AND operation, equivalent to
| :func:`_expression.and_`, that is::
|
| a & b
|
| is equivalent to::
|
| from sqlalchemy import and_
|
| and_(a, b)
|
| Care should be taken when using ``&`` regarding
| operator precedence; the ``&`` operator has the highest precedence.
| The operands should be enclosed in parenthesis if they contain
| further sub expressions::
|
| (a == 2) & (b == 4)
|
| __invert__(self) -> 'Operators'
| Implement the ``~`` operator.
|
| When used with SQL expressions, results in a
| NOT operation, equivalent to
| :func:`_expression.not_`, that is::
|
| ~a
|
| is equivalent to::
|
| from sqlalchemy import not_
|
| not_(a)
|
| __or__(self, other: 'Any') -> 'Operators'
| Implement the ``|`` operator.
|
| When used with SQL expressions, results in an
| OR operation, equivalent to
| :func:`_expression.or_`, that is::
|
| a | b
|
| is equivalent to::
|
| from sqlalchemy import or_
|
| or_(a, b)
|
| Care should be taken when using ``|`` regarding
| operator precedence; the ``|`` operator has the highest precedence.
| The operands should be enclosed in parenthesis if they contain
| further sub expressions::
|
| (a == 2) | (b == 4)
|
| __sa_operate__ = operate(self, op: 'OperatorType', *other: 'Any', **kwargs: 'Any') -> 'Operators'
| Operate on an argument.
|
| This is the lowest level of operation, raises
| :class:`NotImplementedError` by default.
|
| Overriding this on a subclass can allow common
| behavior to be applied to all operations.
| For example, overriding :class:`.ColumnOperators`
| to apply ``func.lower()`` to the left and right
| side::
|
| class MyComparator(ColumnOperators):
| def operate(self, op, other, **kwargs):
| return op(func.lower(self), func.lower(other), **kwargs)
|
| :param op: Operator callable.
| :param \*other: the 'other' side of the operation. Will
| be a single scalar for most operations.
| :param \**kwargs: modifiers. These may be passed by special
| operators such as :meth:`ColumnOperators.contains`.
|
| bool_op(self, opstring: 'str', precedence: 'int' = 0, python_impl: 'Optional[Callable[..., Any]]' = None) -> 'Callable[[Any], Operators]'
| Return a custom boolean operator.
|
| This method is shorthand for calling
| :meth:`.Operators.op` and passing the
| :paramref:`.Operators.op.is_comparison`
| flag with True. A key advantage to using :meth:`.Operators.bool_op`
| is that when using column constructs, the "boolean" nature of the
| returned expression will be present for :pep:`484` purposes.
|
| .. seealso::
|
| :meth:`.Operators.op`
|
| op(self, opstring: 'str', precedence: 'int' = 0, is_comparison: 'bool' = False, return_type: 'Optional[Union[Type[TypeEngine[Any]], TypeEngine[Any]]]' = None, python_impl: 'Optional[Callable[..., Any]]' = None) -> 'Callable[[Any], Operators]'
| Produce a generic operator function.
|
| e.g.::
|
| somecolumn.op("*")(5)
|
| produces::
|
| somecolumn * 5
|
| This function can also be used to make bitwise operators explicit. For
| example::
|
| somecolumn.op("&")(0xFF)
|
| is a bitwise AND of the value in ``somecolumn``.
|
| :param opstring: a string which will be output as the infix operator
| between this element and the expression passed to the
| generated function.
|
| :param precedence: precedence which the database is expected to apply
| to the operator in SQL expressions. This integer value acts as a hint
| for the SQL compiler to know when explicit parenthesis should be
| rendered around a particular operation. A lower number will cause the
| expression to be parenthesized when applied against another operator
| with higher precedence. The default value of ``0`` is lower than all
| operators except for the comma (``,``) and ``AS`` operators. A value
| of 100 will be higher or equal to all operators, and -100 will be
| lower than or equal to all operators.
|
| .. seealso::
|
| :ref:`faq_sql_expression_op_parenthesis` - detailed description
| of how the SQLAlchemy SQL compiler renders parenthesis
|
| :param is_comparison: legacy; if True, the operator will be considered
| as a "comparison" operator, that is which evaluates to a boolean
| true/false value, like ``==``, ``>``, etc. This flag is provided
| so that ORM relationships can establish that the operator is a
| comparison operator when used in a custom join condition.
|
| Using the ``is_comparison`` parameter is superseded by using the
| :meth:`.Operators.bool_op` method instead; this more succinct
| operator sets this parameter automatically, but also provides
| correct :pep:`484` typing support as the returned object will
| express a "boolean" datatype, i.e. ``BinaryExpression[bool]``.
|
| :param return_type: a :class:`.TypeEngine` class or object that will
| force the return type of an expression produced by this operator
| to be of that type. By default, operators that specify
| :paramref:`.Operators.op.is_comparison` will resolve to
| :class:`.Boolean`, and those that do not will be of the same
| type as the left-hand operand.
|
| :param python_impl: an optional Python function that can evaluate
| two Python values in the same way as this operator works when
| run on the database server. Useful for in-Python SQL expression
| evaluation functions, such as for ORM hybrid attributes, and the
| ORM "evaluator" used to match objects in a session after a multi-row
| update or delete.
|
| e.g.::
|
| >>> expr = column("x").op("+", python_impl=lambda a, b: a + b)("y")
|
| The operator for the above expression will also work for non-SQL
| left and right objects::
|
| >>> expr.operator(5, 10)
| 15
|
| .. versionadded:: 2.0
|
|
| .. seealso::
|
| :meth:`.Operators.bool_op`
|
| :ref:`types_operators`
|
| :ref:`relationship_custom_operator`
|
| ----------------------------------------------------------------------
| Methods inherited from ClauseElement:
|
| __bool__(self)
|
| __repr__(self)
| Return repr(self).
|
| compare(self, other: 'ClauseElement', **kw: 'Any') -> 'bool'
| Compare this :class:`_expression.ClauseElement` to
| the given :class:`_expression.ClauseElement`.
|
| Subclasses should override the default behavior, which is a
| straight identity comparison.
|
| \**kw are arguments consumed by subclass ``compare()`` methods and
| may be used to modify the criteria for comparison
| (see :class:`_expression.ColumnElement`).
|
| description(...)
|
| entity_namespace(...)
|
| params(self, _ClauseElement__optionaldict: 'Optional[Mapping[str, Any]]' = None, **kwargs: 'Any') -> 'Self'
| Return a copy with :func:`_expression.bindparam` elements
| replaced.
|
| Returns a copy of this ClauseElement with
| :func:`_expression.bindparam`
| elements replaced with values taken from the given dictionary::
|
| >>> clause = column("x") + bindparam("foo")
| >>> print(clause.compile().params)
| {'foo':None}
| >>> print(clause.params({"foo": 7}).compile().params)
| {'foo':7}
|
| unique_params(self, _ClauseElement__optionaldict: 'Optional[Dict[str, Any]]' = None, **kwargs: 'Any') -> 'Self'
| Return a copy with :func:`_expression.bindparam` elements
| replaced.
|
| Same functionality as :meth:`_expression.ClauseElement.params`,
| except adds `unique=True`
| to affected bind parameters so that multiple statements can be
| used.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from ClauseElement:
|
| is_clause_element = True
|
| is_dml = False
|
| is_selectable = False
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.cache_key.HasCacheKey:
|
| inherit_cache = None
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_instancemethod(fn: '_F') -> '_F'
| Decorate a method memoize its return value.
|
| :meta private:
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_attribute = <class 'sqlalchemy.util.langhelpers.HasMemoized.m...
| A read-only @property that is only evaluated once.
|
| :meta private:
|
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.visitors.HasTraverseInternals:
|
| get_children(self, *, omit_attrs: 'Tuple[str, ...]' = (), **kw: 'Any') -> 'Iterable[HasTraverseInternals]'
| Return immediate child :class:`.visitors.HasTraverseInternals`
| elements of this :class:`.visitors.HasTraverseInternals`.
|
| This is used for visit traversal.
|
| \**kw may contain flags that change the collection that is
| returned, for example to return a subset of items in order to
| cut down on larger traversals, or to return child items from a
| different context (such as schema-level collections instead of
| clause-level).
|
| ----------------------------------------------------------------------
| Methods inherited from CompilerElement:
|
| __str__(self) -> 'str'
| Return str(self).
|
| compile(self, bind: 'Optional[_HasDialect]' = None, dialect: 'Optional[Dialect]' = None, **kw: 'Any') -> 'Compiled'
| Compile this SQL expression.
|
| The return value is a :class:`~.Compiled` object.
| Calling ``str()`` or ``unicode()`` on the returned value will yield a
| string representation of the result. The
| :class:`~.Compiled` object also can return a
| dictionary of bind parameter names and values
| using the ``params`` accessor.
|
| :param bind: An :class:`.Connection` or :class:`.Engine` which
| can provide a :class:`.Dialect` in order to generate a
| :class:`.Compiled` object. If the ``bind`` and
| ``dialect`` parameters are both omitted, a default SQL compiler
| is used.
|
| :param column_keys: Used for INSERT and UPDATE statements, a list of
| column names which should be present in the VALUES clause of the
| compiled statement. If ``None``, all columns from the target table
| object are rendered.
|
| :param dialect: A :class:`.Dialect` instance which can generate
| a :class:`.Compiled` object. This argument takes precedence over
| the ``bind`` argument.
|
| :param compile_kwargs: optional dictionary of additional parameters
| that will be passed through to the compiler within all "visit"
| methods. This allows any custom flag to be passed through to
| a custom compilation construct, for example. It is also used
| for the case of passing the ``literal_binds`` flag through::
|
| from sqlalchemy.sql import table, column, select
|
| t = table("t", column("x"))
|
| s = select(t).where(t.c.x == 5)
|
| print(s.compile(compile_kwargs={"literal_binds": True}))
|
| .. seealso::
|
| :ref:`faq_sql_expression_string`
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from CompilerElement:
|
| stringify_dialect = 'default'
|
| supports_execution = False
sqlalchemy.HasCTE
Python Library Documentation: class HasCTE in module sqlalchemy.sql.selectable
class HasCTE(sqlalchemy.sql.roles.HasCTERole, SelectsRows)
| Mixin that declares a class to include CTE support.
|
| Method resolution order:
| HasCTE
| sqlalchemy.sql.roles.HasCTERole
| SelectsRows
| ReturnsRows
| sqlalchemy.sql.roles.ReturnsRowsRole
| sqlalchemy.sql.roles.SQLRole
| sqlalchemy.sql.elements.DQLDMLClauseElement
| sqlalchemy.sql.elements.ClauseElement
| sqlalchemy.sql.annotation.SupportsWrappingAnnotations
| sqlalchemy.sql.annotation.SupportsAnnotations
| sqlalchemy.sql.cache_key.MemoizedHasCacheKey
| sqlalchemy.sql.cache_key.HasCacheKey
| sqlalchemy.util.langhelpers.HasMemoized
| sqlalchemy.sql.traversals.HasCopyInternals
| sqlalchemy.sql.visitors.ExternallyTraversible
| sqlalchemy.sql.visitors.HasTraverseInternals
| sqlalchemy.sql.elements.CompilerElement
| sqlalchemy.sql.visitors.Visitable
| builtins.object
|
| Methods defined here:
|
| add_cte(self, *ctes: 'CTE', nest_here: 'bool' = False) -> 'Self'
| Add one or more :class:`_sql.CTE` constructs to this statement.
|
| This method will associate the given :class:`_sql.CTE` constructs with
| the parent statement such that they will each be unconditionally
| rendered in the WITH clause of the final statement, even if not
| referenced elsewhere within the statement or any sub-selects.
|
| The optional :paramref:`.HasCTE.add_cte.nest_here` parameter when set
| to True will have the effect that each given :class:`_sql.CTE` will
| render in a WITH clause rendered directly along with this statement,
| rather than being moved to the top of the ultimate rendered statement,
| even if this statement is rendered as a subquery within a larger
| statement.
|
| This method has two general uses. One is to embed CTE statements that
| serve some purpose without being referenced explicitly, such as the use
| case of embedding a DML statement such as an INSERT or UPDATE as a CTE
| inline with a primary statement that may draw from its results
| indirectly. The other is to provide control over the exact placement
| of a particular series of CTE constructs that should remain rendered
| directly in terms of a particular statement that may be nested in a
| larger statement.
|
| E.g.::
|
| from sqlalchemy import table, column, select
|
| t = table("t", column("c1"), column("c2"))
|
| ins = t.insert().values({"c1": "x", "c2": "y"}).cte()
|
| stmt = select(t).add_cte(ins)
|
| Would render:
|
| .. sourcecode:: sql
|
| WITH anon_1 AS (
| INSERT INTO t (c1, c2) VALUES (:param_1, :param_2)
| )
| SELECT t.c1, t.c2
| FROM t
|
| Above, the "anon_1" CTE is not referenced in the SELECT
| statement, however still accomplishes the task of running an INSERT
| statement.
|
| Similarly in a DML-related context, using the PostgreSQL
| :class:`_postgresql.Insert` construct to generate an "upsert"::
|
| from sqlalchemy import table, column
| from sqlalchemy.dialects.postgresql import insert
|
| t = table("t", column("c1"), column("c2"))
|
| delete_statement_cte = t.delete().where(t.c.c1 < 1).cte("deletions")
|
| insert_stmt = insert(t).values({"c1": 1, "c2": 2})
| update_statement = insert_stmt.on_conflict_do_update(
| index_elements=[t.c.c1],
| set_={
| "c1": insert_stmt.excluded.c1,
| "c2": insert_stmt.excluded.c2,
| },
| ).add_cte(delete_statement_cte)
|
| print(update_statement)
|
| The above statement renders as:
|
| .. sourcecode:: sql
|
| WITH deletions AS (
| DELETE FROM t WHERE t.c1 < %(c1_1)s
| )
| INSERT INTO t (c1, c2) VALUES (%(c1)s, %(c2)s)
| ON CONFLICT (c1) DO UPDATE SET c1 = excluded.c1, c2 = excluded.c2
|
| .. versionadded:: 1.4.21
|
| :param \*ctes: zero or more :class:`.CTE` constructs.
|
| .. versionchanged:: 2.0 Multiple CTE instances are accepted
|
| :param nest_here: if True, the given CTE or CTEs will be rendered
| as though they specified the :paramref:`.HasCTE.cte.nesting` flag
| to ``True`` when they were added to this :class:`.HasCTE`.
| Assuming the given CTEs are not referenced in an outer-enclosing
| statement as well, the CTEs given should render at the level of
| this statement when this flag is given.
|
| .. versionadded:: 2.0
|
| .. seealso::
|
| :paramref:`.HasCTE.cte.nesting`
|
| cte(self, name: 'Optional[str]' = None, recursive: 'bool' = False, nesting: 'bool' = False) -> 'CTE'
| Return a new :class:`_expression.CTE`,
| or Common Table Expression instance.
|
| Common table expressions are a SQL standard whereby SELECT
| statements can draw upon secondary statements specified along
| with the primary statement, using a clause called "WITH".
| Special semantics regarding UNION can also be employed to
| allow "recursive" queries, where a SELECT statement can draw
| upon the set of rows that have previously been selected.
|
| CTEs can also be applied to DML constructs UPDATE, INSERT
| and DELETE on some databases, both as a source of CTE rows
| when combined with RETURNING, as well as a consumer of
| CTE rows.
|
| SQLAlchemy detects :class:`_expression.CTE` objects, which are treated
| similarly to :class:`_expression.Alias` objects, as special elements
| to be delivered to the FROM clause of the statement as well
| as to a WITH clause at the top of the statement.
|
| For special prefixes such as PostgreSQL "MATERIALIZED" and
| "NOT MATERIALIZED", the :meth:`_expression.CTE.prefix_with`
| method may be
| used to establish these.
|
| .. versionchanged:: 1.3.13 Added support for prefixes.
| In particular - MATERIALIZED and NOT MATERIALIZED.
|
| :param name: name given to the common table expression. Like
| :meth:`_expression.FromClause.alias`, the name can be left as
| ``None`` in which case an anonymous symbol will be used at query
| compile time.
| :param recursive: if ``True``, will render ``WITH RECURSIVE``.
| A recursive common table expression is intended to be used in
| conjunction with UNION ALL in order to derive rows
| from those already selected.
| :param nesting: if ``True``, will render the CTE locally to the
| statement in which it is referenced. For more complex scenarios,
| the :meth:`.HasCTE.add_cte` method using the
| :paramref:`.HasCTE.add_cte.nest_here`
| parameter may also be used to more carefully
| control the exact placement of a particular CTE.
|
| .. versionadded:: 1.4.24
|
| .. seealso::
|
| :meth:`.HasCTE.add_cte`
|
| The following examples include two from PostgreSQL's documentation at
| https://www.postgresql.org/docs/current/static/queries-with.html,
| as well as additional examples.
|
| Example 1, non recursive::
|
| from sqlalchemy import (
| Table,
| Column,
| String,
| Integer,
| MetaData,
| select,
| func,
| )
|
| metadata = MetaData()
|
| orders = Table(
| "orders",
| metadata,
| Column("region", String),
| Column("amount", Integer),
| Column("product", String),
| Column("quantity", Integer),
| )
|
| regional_sales = (
| select(orders.c.region, func.sum(orders.c.amount).label("total_sales"))
| .group_by(orders.c.region)
| .cte("regional_sales")
| )
|
|
| top_regions = (
| select(regional_sales.c.region)
| .where(
| regional_sales.c.total_sales
| > select(func.sum(regional_sales.c.total_sales) / 10)
| )
| .cte("top_regions")
| )
|
| statement = (
| select(
| orders.c.region,
| orders.c.product,
| func.sum(orders.c.quantity).label("product_units"),
| func.sum(orders.c.amount).label("product_sales"),
| )
| .where(orders.c.region.in_(select(top_regions.c.region)))
| .group_by(orders.c.region, orders.c.product)
| )
|
| result = conn.execute(statement).fetchall()
|
| Example 2, WITH RECURSIVE::
|
| from sqlalchemy import (
| Table,
| Column,
| String,
| Integer,
| MetaData,
| select,
| func,
| )
|
| metadata = MetaData()
|
| parts = Table(
| "parts",
| metadata,
| Column("part", String),
| Column("sub_part", String),
| Column("quantity", Integer),
| )
|
| included_parts = (
| select(parts.c.sub_part, parts.c.part, parts.c.quantity)
| .where(parts.c.part == "our part")
| .cte(recursive=True)
| )
|
|
| incl_alias = included_parts.alias()
| parts_alias = parts.alias()
| included_parts = included_parts.union_all(
| select(
| parts_alias.c.sub_part, parts_alias.c.part, parts_alias.c.quantity
| ).where(parts_alias.c.part == incl_alias.c.sub_part)
| )
|
| statement = select(
| included_parts.c.sub_part,
| func.sum(included_parts.c.quantity).label("total_quantity"),
| ).group_by(included_parts.c.sub_part)
|
| result = conn.execute(statement).fetchall()
|
| Example 3, an upsert using UPDATE and INSERT with CTEs::
|
| from datetime import date
| from sqlalchemy import (
| MetaData,
| Table,
| Column,
| Integer,
| Date,
| select,
| literal,
| and_,
| exists,
| )
|
| metadata = MetaData()
|
| visitors = Table(
| "visitors",
| metadata,
| Column("product_id", Integer, primary_key=True),
| Column("date", Date, primary_key=True),
| Column("count", Integer),
| )
|
| # add 5 visitors for the product_id == 1
| product_id = 1
| day = date.today()
| count = 5
|
| update_cte = (
| visitors.update()
| .where(
| and_(visitors.c.product_id == product_id, visitors.c.date == day)
| )
| .values(count=visitors.c.count + count)
| .returning(literal(1))
| .cte("update_cte")
| )
|
| upsert = visitors.insert().from_select(
| [visitors.c.product_id, visitors.c.date, visitors.c.count],
| select(literal(product_id), literal(day), literal(count)).where(
| ~exists(update_cte.select())
| ),
| )
|
| connection.execute(upsert)
|
| Example 4, Nesting CTE (SQLAlchemy 1.4.24 and above)::
|
| value_a = select(literal("root").label("n")).cte("value_a")
|
| # A nested CTE with the same name as the root one
| value_a_nested = select(literal("nesting").label("n")).cte(
| "value_a", nesting=True
| )
|
| # Nesting CTEs takes ascendency locally
| # over the CTEs at a higher level
| value_b = select(value_a_nested.c.n).cte("value_b")
|
| value_ab = select(value_a.c.n.label("a"), value_b.c.n.label("b"))
|
| The above query will render the second CTE nested inside the first,
| shown with inline parameters below as:
|
| .. sourcecode:: sql
|
| WITH
| value_a AS
| (SELECT 'root' AS n),
| value_b AS
| (WITH value_a AS
| (SELECT 'nesting' AS n)
| SELECT value_a.n AS n FROM value_a)
| SELECT value_a.n AS a, value_b.n AS b
| FROM value_a, value_b
|
| The same CTE can be set up using the :meth:`.HasCTE.add_cte` method
| as follows (SQLAlchemy 2.0 and above)::
|
| value_a = select(literal("root").label("n")).cte("value_a")
|
| # A nested CTE with the same name as the root one
| value_a_nested = select(literal("nesting").label("n")).cte("value_a")
|
| # Nesting CTEs takes ascendency locally
| # over the CTEs at a higher level
| value_b = (
| select(value_a_nested.c.n)
| .add_cte(value_a_nested, nest_here=True)
| .cte("value_b")
| )
|
| value_ab = select(value_a.c.n.label("a"), value_b.c.n.label("b"))
|
| Example 5, Non-Linear CTE (SQLAlchemy 1.4.28 and above)::
|
| edge = Table(
| "edge",
| metadata,
| Column("id", Integer, primary_key=True),
| Column("left", Integer),
| Column("right", Integer),
| )
|
| root_node = select(literal(1).label("node")).cte("nodes", recursive=True)
|
| left_edge = select(edge.c.left).join(
| root_node, edge.c.right == root_node.c.node
| )
| right_edge = select(edge.c.right).join(
| root_node, edge.c.left == root_node.c.node
| )
|
| subgraph_cte = root_node.union(left_edge, right_edge)
|
| subgraph = select(subgraph_cte)
|
| The above query will render 2 UNIONs inside the recursive CTE:
|
| .. sourcecode:: sql
|
| WITH RECURSIVE nodes(node) AS (
| SELECT 1 AS node
| UNION
| SELECT edge."left" AS "left"
| FROM edge JOIN nodes ON edge."right" = nodes.node
| UNION
| SELECT edge."right" AS "right"
| FROM edge JOIN nodes ON edge."left" = nodes.node
| )
| SELECT nodes.node FROM nodes
|
| .. seealso::
|
| :meth:`_orm.Query.cte` - ORM version of
| :meth:`_expression.HasCTE.cte`.
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'_has_ctes_traverse_internals': '_TraverseInternals...
|
| name_cte_columns = False
|
| ----------------------------------------------------------------------
| Methods inherited from ReturnsRows:
|
| 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.
|
| ----------------------------------------------------------------------
| Readonly properties inherited from ReturnsRows:
|
| exported_columns
| 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`
|
| selectable
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.SQLRole:
|
| allows_lambda = False
|
| uses_inspection = False
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.elements.ClauseElement:
|
| __bool__(self)
|
| __getstate__(self)
| Helper for pickle.
|
| __invert__(self)
|
| __repr__(self)
| Return repr(self).
|
| compare(self, other: 'ClauseElement', **kw: 'Any') -> 'bool'
| Compare this :class:`_expression.ClauseElement` to
| the given :class:`_expression.ClauseElement`.
|
| Subclasses should override the default behavior, which is a
| straight identity comparison.
|
| \**kw are arguments consumed by subclass ``compare()`` methods and
| may be used to modify the criteria for comparison
| (see :class:`_expression.ColumnElement`).
|
| description(...)
|
| entity_namespace(...)
|
| params(self, _ClauseElement__optionaldict: 'Optional[Mapping[str, Any]]' = None, **kwargs: 'Any') -> 'Self'
| Return a copy with :func:`_expression.bindparam` elements
| replaced.
|
| Returns a copy of this ClauseElement with
| :func:`_expression.bindparam`
| elements replaced with values taken from the given dictionary::
|
| >>> clause = column("x") + bindparam("foo")
| >>> print(clause.compile().params)
| {'foo':None}
| >>> print(clause.params({"foo": 7}).compile().params)
| {'foo':7}
|
| self_group(self, against: 'Optional[OperatorType]' = None) -> 'ClauseElement'
| 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.
|
| unique_params(self, _ClauseElement__optionaldict: 'Optional[Dict[str, Any]]' = None, **kwargs: 'Any') -> 'Self'
| Return a copy with :func:`_expression.bindparam` elements
| replaced.
|
| Same functionality as :meth:`_expression.ClauseElement.params`,
| except adds `unique=True`
| to affected bind parameters so that multiple statements can be
| used.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.elements.ClauseElement:
|
| __visit_name__ = 'clause'
|
| is_clause_element = True
|
| is_dml = False
|
| is_selectable = False
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.cache_key.HasCacheKey:
|
| inherit_cache = None
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_instancemethod(fn: '_F') -> '_F'
| Decorate a method memoize its return value.
|
| :meta private:
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_attribute = <class 'sqlalchemy.util.langhelpers.HasMemoized.m...
| A read-only @property that is only evaluated once.
|
| :meta private:
|
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.visitors.HasTraverseInternals:
|
| get_children(self, *, omit_attrs: 'Tuple[str, ...]' = (), **kw: 'Any') -> 'Iterable[HasTraverseInternals]'
| Return immediate child :class:`.visitors.HasTraverseInternals`
| elements of this :class:`.visitors.HasTraverseInternals`.
|
| This is used for visit traversal.
|
| \**kw may contain flags that change the collection that is
| returned, for example to return a subset of items in order to
| cut down on larger traversals, or to return child items from a
| different context (such as schema-level collections instead of
| clause-level).
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.elements.CompilerElement:
|
| __str__(self) -> 'str'
| Return str(self).
|
| compile(self, bind: 'Optional[_HasDialect]' = None, dialect: 'Optional[Dialect]' = None, **kw: 'Any') -> 'Compiled'
| Compile this SQL expression.
|
| The return value is a :class:`~.Compiled` object.
| Calling ``str()`` or ``unicode()`` on the returned value will yield a
| string representation of the result. The
| :class:`~.Compiled` object also can return a
| dictionary of bind parameter names and values
| using the ``params`` accessor.
|
| :param bind: An :class:`.Connection` or :class:`.Engine` which
| can provide a :class:`.Dialect` in order to generate a
| :class:`.Compiled` object. If the ``bind`` and
| ``dialect`` parameters are both omitted, a default SQL compiler
| is used.
|
| :param column_keys: Used for INSERT and UPDATE statements, a list of
| column names which should be present in the VALUES clause of the
| compiled statement. If ``None``, all columns from the target table
| object are rendered.
|
| :param dialect: A :class:`.Dialect` instance which can generate
| a :class:`.Compiled` object. This argument takes precedence over
| the ``bind`` argument.
|
| :param compile_kwargs: optional dictionary of additional parameters
| that will be passed through to the compiler within all "visit"
| methods. This allows any custom flag to be passed through to
| a custom compilation construct, for example. It is also used
| for the case of passing the ``literal_binds`` flag through::
|
| from sqlalchemy.sql import table, column, select
|
| t = table("t", column("x"))
|
| s = select(t).where(t.c.x == 5)
|
| print(s.compile(compile_kwargs={"literal_binds": True}))
|
| .. seealso::
|
| :ref:`faq_sql_expression_string`
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.elements.CompilerElement:
|
| stringify_dialect = 'default'
|
| supports_execution = False
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.visitors.Visitable:
|
| __class_getitem__(key: 'Any') -> 'Any'
|
| __init_subclass__() -> 'None'
| This method is called when a class is subclassed.
|
| The default implementation does nothing. It may be
| overridden to extend subclasses.
sqlalchemy.HasPrefixes
Python Library Documentation: class HasPrefixes in module sqlalchemy.sql.selectable
class HasPrefixes(builtins.object)
| Methods defined here:
|
| prefix_with(self, *prefixes: '_TextCoercedExpressionArgument[Any]', dialect: 'str' = '*') -> 'Self'
| 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.
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'_has_prefixes_traverse_internals': '_TraverseInter...
sqlalchemy.HasSuffixes
Python Library Documentation: class HasSuffixes in module sqlalchemy.sql.selectable
class HasSuffixes(builtins.object)
| Methods defined here:
|
| suffix_with(self, *suffixes: '_TextCoercedExpressionArgument[Any]', dialect: 'str' = '*') -> 'Self'
| 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.
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'_has_suffixes_traverse_internals': '_TraverseInter...
sqlalchemy.INT
Python Library Documentation: class INTEGER in module sqlalchemy.sql.sqltypes
class INTEGER(Integer)
| The SQL INT or INTEGER type.
|
| .. seealso::
|
| :class:`_types.Integer` - documentation for the base type.
|
| Method resolution order:
| INTEGER
| Integer
| HasExpressionLookup
| sqlalchemy.sql.type_api.TypeEngineMixin
| sqlalchemy.sql.type_api.TypeEngine
| sqlalchemy.sql.visitors.Visitable
| typing.Generic
| builtins.object
|
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| __parameters__ = ()
|
| __visit_name__ = 'INTEGER'
|
| ----------------------------------------------------------------------
| Methods inherited from Integer:
|
| get_dbapi_type(self, dbapi)
| Return the corresponding type object from the underlying DB-API, if
| any.
|
| This can be useful for calling ``setinputsizes()``, for example.
|
| literal_processor(self, dialect)
| Return a conversion function for processing literal values that are
| to be rendered directly without using binds.
|
| This function is used when the compiler makes use of the
| "literal_binds" flag, typically used in DDL generation as well
| as in certain scenarios where backends don't accept bound parameters.
|
| Returns a callable which will receive a literal Python value
| as the sole positional argument and will return a string representation
| to be rendered in a SQL statement.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.literal_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.literal_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_literal_param`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| ----------------------------------------------------------------------
| Readonly properties inherited from Integer:
|
| python_type
| Return the Python type object expected to be returned
| by instances of this type, if known.
|
| Basically, for those types which enforce a return type,
| or are known across the board to do such for all common
| DBAPIs (like ``int`` for example), will return that type.
|
| If a return type is not defined, raises
| ``NotImplementedError``.
|
| Note that any type also accommodates NULL in SQL which
| means you can also get back ``None`` from any type
| in practice.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from HasExpressionLookup:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from HasExpressionLookup:
|
| Comparator = <class 'sqlalchemy.sql.sqltypes.HasExpressionLookup.Compa...
|
| comparator_factory = <class 'sqlalchemy.sql.sqltypes.HasExpressionLook...
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.type_api.TypeEngine:
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| __str__(self) -> 'str'
| Return str(self).
|
| adapt(self, cls: 'Type[Union[TypeEngine[Any], TypeEngineMixin]]', **kw: 'Any') -> 'TypeEngine[Any]'
| Produce an "adapted" form of this type, given an "impl" class
| to work with.
|
| This method is used internally to associate generic
| types with "implementation" types that are specific to a particular
| dialect.
|
| as_generic(self, allow_nulltype: 'bool' = False) -> 'TypeEngine[_T]'
| Return an instance of the generic type corresponding to this type
| using heuristic rule. The method may be overridden if this
| heuristic rule is not sufficient.
|
| >>> from sqlalchemy.dialects.mysql import INTEGER
| >>> INTEGER(display_width=4).as_generic()
| Integer()
|
| >>> from sqlalchemy.dialects.mysql import NVARCHAR
| >>> NVARCHAR(length=100).as_generic()
| Unicode(length=100)
|
| .. versionadded:: 1.4.0b2
|
|
| .. seealso::
|
| :ref:`metadata_reflection_dbagnostic_types` - describes the
| use of :meth:`_types.TypeEngine.as_generic` in conjunction with
| the :meth:`_sql.DDLEvents.column_reflect` event, which is its
| intended use.
|
| bind_expression(self, bindvalue: 'BindParameter[_T]') -> 'Optional[ColumnElement[_T]]'
| Given a bind value (i.e. a :class:`.BindParameter` instance),
| return a SQL expression in its place.
|
| This is typically a SQL function that wraps the existing bound
| parameter within the statement. It is used for special data types
| that require literals being wrapped in some special database function
| in order to coerce an application-level value into a database-specific
| format. It is the SQL analogue of the
| :meth:`.TypeEngine.bind_processor` method.
|
| This method is called during the **SQL compilation** phase of a
| statement, when rendering a SQL string. It is **not** called
| against specific values.
|
| Note that this method, when implemented, should always return
| the exact same structure, without any conditional logic, as it
| may be used in an executemany() call against an arbitrary number
| of bound parameter sets.
|
| .. note::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.bind_expression`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.bind_expression`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.bind_expression`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| .. seealso::
|
| :ref:`types_sql_value_processing`
|
| bind_processor(self, dialect: 'Dialect') -> 'Optional[_BindProcessorType[_T]]'
| Return a conversion function for processing bind values.
|
| Returns a callable which will receive a bind parameter value
| as the sole positional argument and will return a value to
| send to the DB-API.
|
| If processing is not necessary, the method should return ``None``.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.bind_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.bind_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_bind_param`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
|
| :param dialect: Dialect instance in use.
|
| coerce_compared_value(self, op: 'Optional[OperatorType]', value: 'Any') -> 'TypeEngine[Any]'
| Suggest a type for a 'coerced' Python value in an expression.
|
| Given an operator and value, gives the type a chance
| to return a type which the value should be coerced into.
|
| The default behavior here is conservative; if the right-hand
| side is already coerced into a SQL type based on its
| Python type, it is usually left alone.
|
| End-user functionality extension here should generally be via
| :class:`.TypeDecorator`, which provides more liberal behavior in that
| it defaults to coercing the other side of the expression into this
| type, thus applying special Python conversions above and beyond those
| needed by the DBAPI to both ides. It also provides the public method
| :meth:`.TypeDecorator.coerce_compared_value` which is intended for
| end-user customization of this behavior.
|
| column_expression(self, colexpr: 'ColumnElement[_T]') -> 'Optional[ColumnElement[_T]]'
| Given a SELECT column expression, return a wrapping SQL expression.
|
| This is typically a SQL function that wraps a column expression
| as rendered in the columns clause of a SELECT statement.
| It is used for special data types that require
| columns to be wrapped in some special database function in order
| to coerce the value before being sent back to the application.
| It is the SQL analogue of the :meth:`.TypeEngine.result_processor`
| method.
|
| .. note:: The :func:`.TypeEngine.column_expression` method is applied
| only to the **outermost columns clause** of a SELECT statement, that
| is, the columns that are to be delivered directly into the returned
| result rows. It does **not** apply to the columns clause inside
| of subqueries. This necessarily avoids double conversions against
| the column and only runs the conversion when ready to be returned
| to the client.
|
| This method is called during the **SQL compilation** phase of a
| statement, when rendering a SQL string. It is **not** called
| against specific values.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.column_expression`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.column_expression`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.column_expression`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
|
| .. seealso::
|
| :ref:`types_sql_value_processing`
|
| compare_values(self, x: 'Any', y: 'Any') -> 'bool'
| Compare two values for equality.
|
| compile(self, dialect: 'Optional[Dialect]' = None) -> 'str'
| Produce a string-compiled form of this :class:`.TypeEngine`.
|
| When called with no arguments, uses a "default" dialect
| to produce a string result.
|
| :param dialect: a :class:`.Dialect` instance.
|
| copy(self, **kw: 'Any') -> 'Self'
|
| copy_value(self, value: 'Any') -> 'Any'
|
| dialect_impl(self, dialect: 'Dialect') -> 'TypeEngine[_T]'
| Return a dialect-specific implementation for this
| :class:`.TypeEngine`.
|
| evaluates_none(self) -> 'Self'
| Return a copy of this type which has the
| :attr:`.should_evaluate_none` flag set to True.
|
| E.g.::
|
| Table(
| "some_table",
| metadata,
| Column(
| String(50).evaluates_none(),
| nullable=True,
| server_default="no value",
| ),
| )
|
| The ORM uses this flag to indicate that a positive value of ``None``
| is passed to the column in an INSERT statement, rather than omitting
| the column from the INSERT statement which has the effect of firing
| off column-level defaults. It also allows for types which have
| special behavior associated with the Python None value to indicate
| that the value doesn't necessarily translate into SQL NULL; a
| prime example of this is a JSON type which may wish to persist the
| JSON value ``'null'``.
|
| In all cases, the actual NULL SQL value can be always be
| persisted in any column by using
| the :obj:`_expression.null` SQL construct in an INSERT statement
| or associated with an ORM-mapped attribute.
|
| .. note::
|
| The "evaluates none" flag does **not** apply to a value
| of ``None`` passed to :paramref:`_schema.Column.default` or
| :paramref:`_schema.Column.server_default`; in these cases,
| ``None``
| still means "no default".
|
| .. seealso::
|
| :ref:`session_forcing_null` - in the ORM documentation
|
| :paramref:`.postgresql.JSON.none_as_null` - PostgreSQL JSON
| interaction with this flag.
|
| :attr:`.TypeEngine.should_evaluate_none` - class-level flag
|
| result_processor(self, dialect: 'Dialect', coltype: 'object') -> 'Optional[_ResultProcessorType[_T]]'
| Return a conversion function for processing result row values.
|
| Returns a callable which will receive a result row column
| value as the sole positional argument and will return a value
| to return to the user.
|
| If processing is not necessary, the method should return ``None``.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.result_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.result_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_result_value`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| :param dialect: Dialect instance in use.
|
| :param coltype: DBAPI coltype argument received in cursor.description.
|
| with_variant(self, type_: '_TypeEngineArgument[Any]', *dialect_names: 'str') -> 'Self'
| Produce a copy of this type object that will utilize the given
| type when applied to the dialect of the given name.
|
| e.g.::
|
| from sqlalchemy.types import String
| from sqlalchemy.dialects import mysql
|
| string_type = String()
|
| string_type = string_type.with_variant(
| mysql.VARCHAR(collation="foo"), "mysql", "mariadb"
| )
|
| The variant mapping indicates that when this type is
| interpreted by a specific dialect, it will instead be
| transmuted into the given type, rather than using the
| primary type.
|
| .. versionchanged:: 2.0 the :meth:`_types.TypeEngine.with_variant`
| method now works with a :class:`_types.TypeEngine` object "in
| place", returning a copy of the original type rather than returning
| a wrapping object; the ``Variant`` class is no longer used.
|
| :param type\_: a :class:`.TypeEngine` that will be selected
| as a variant from the originating type, when a dialect
| of the given name is in use.
| :param \*dialect_names: one or more base names of the dialect which
| uses this type. (i.e. ``'postgresql'``, ``'mysql'``, etc.)
|
| .. versionchanged:: 2.0 multiple dialect names can be specified
| for one variant.
|
| .. seealso::
|
| :ref:`types_with_variant` - illustrates the use of
| :meth:`_types.TypeEngine.with_variant`.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.type_api.TypeEngine:
|
| __orig_bases__ = (<class 'sqlalchemy.sql.visitors.Visitable'>, typing....
|
| hashable = True
|
| render_bind_cast = False
|
| render_literal_cast = False
|
| should_evaluate_none = False
|
| sort_key_function = None
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.visitors.Visitable:
|
| __class_getitem__(key: 'Any') -> 'Any'
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__() -> 'None'
| This method is called when a class is subclassed.
|
| The default implementation does nothing. It may be
| overridden to extend subclasses.
sqlalchemy.INTEGER
Python Library Documentation: class INTEGER in module sqlalchemy.sql.sqltypes
class INTEGER(Integer)
| The SQL INT or INTEGER type.
|
| .. seealso::
|
| :class:`_types.Integer` - documentation for the base type.
|
| Method resolution order:
| INTEGER
| Integer
| HasExpressionLookup
| sqlalchemy.sql.type_api.TypeEngineMixin
| sqlalchemy.sql.type_api.TypeEngine
| sqlalchemy.sql.visitors.Visitable
| typing.Generic
| builtins.object
|
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| __parameters__ = ()
|
| __visit_name__ = 'INTEGER'
|
| ----------------------------------------------------------------------
| Methods inherited from Integer:
|
| get_dbapi_type(self, dbapi)
| Return the corresponding type object from the underlying DB-API, if
| any.
|
| This can be useful for calling ``setinputsizes()``, for example.
|
| literal_processor(self, dialect)
| Return a conversion function for processing literal values that are
| to be rendered directly without using binds.
|
| This function is used when the compiler makes use of the
| "literal_binds" flag, typically used in DDL generation as well
| as in certain scenarios where backends don't accept bound parameters.
|
| Returns a callable which will receive a literal Python value
| as the sole positional argument and will return a string representation
| to be rendered in a SQL statement.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.literal_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.literal_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_literal_param`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| ----------------------------------------------------------------------
| Readonly properties inherited from Integer:
|
| python_type
| Return the Python type object expected to be returned
| by instances of this type, if known.
|
| Basically, for those types which enforce a return type,
| or are known across the board to do such for all common
| DBAPIs (like ``int`` for example), will return that type.
|
| If a return type is not defined, raises
| ``NotImplementedError``.
|
| Note that any type also accommodates NULL in SQL which
| means you can also get back ``None`` from any type
| in practice.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from HasExpressionLookup:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from HasExpressionLookup:
|
| Comparator = <class 'sqlalchemy.sql.sqltypes.HasExpressionLookup.Compa...
|
| comparator_factory = <class 'sqlalchemy.sql.sqltypes.HasExpressionLook...
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.type_api.TypeEngine:
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| __str__(self) -> 'str'
| Return str(self).
|
| adapt(self, cls: 'Type[Union[TypeEngine[Any], TypeEngineMixin]]', **kw: 'Any') -> 'TypeEngine[Any]'
| Produce an "adapted" form of this type, given an "impl" class
| to work with.
|
| This method is used internally to associate generic
| types with "implementation" types that are specific to a particular
| dialect.
|
| as_generic(self, allow_nulltype: 'bool' = False) -> 'TypeEngine[_T]'
| Return an instance of the generic type corresponding to this type
| using heuristic rule. The method may be overridden if this
| heuristic rule is not sufficient.
|
| >>> from sqlalchemy.dialects.mysql import INTEGER
| >>> INTEGER(display_width=4).as_generic()
| Integer()
|
| >>> from sqlalchemy.dialects.mysql import NVARCHAR
| >>> NVARCHAR(length=100).as_generic()
| Unicode(length=100)
|
| .. versionadded:: 1.4.0b2
|
|
| .. seealso::
|
| :ref:`metadata_reflection_dbagnostic_types` - describes the
| use of :meth:`_types.TypeEngine.as_generic` in conjunction with
| the :meth:`_sql.DDLEvents.column_reflect` event, which is its
| intended use.
|
| bind_expression(self, bindvalue: 'BindParameter[_T]') -> 'Optional[ColumnElement[_T]]'
| Given a bind value (i.e. a :class:`.BindParameter` instance),
| return a SQL expression in its place.
|
| This is typically a SQL function that wraps the existing bound
| parameter within the statement. It is used for special data types
| that require literals being wrapped in some special database function
| in order to coerce an application-level value into a database-specific
| format. It is the SQL analogue of the
| :meth:`.TypeEngine.bind_processor` method.
|
| This method is called during the **SQL compilation** phase of a
| statement, when rendering a SQL string. It is **not** called
| against specific values.
|
| Note that this method, when implemented, should always return
| the exact same structure, without any conditional logic, as it
| may be used in an executemany() call against an arbitrary number
| of bound parameter sets.
|
| .. note::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.bind_expression`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.bind_expression`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.bind_expression`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| .. seealso::
|
| :ref:`types_sql_value_processing`
|
| bind_processor(self, dialect: 'Dialect') -> 'Optional[_BindProcessorType[_T]]'
| Return a conversion function for processing bind values.
|
| Returns a callable which will receive a bind parameter value
| as the sole positional argument and will return a value to
| send to the DB-API.
|
| If processing is not necessary, the method should return ``None``.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.bind_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.bind_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_bind_param`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
|
| :param dialect: Dialect instance in use.
|
| coerce_compared_value(self, op: 'Optional[OperatorType]', value: 'Any') -> 'TypeEngine[Any]'
| Suggest a type for a 'coerced' Python value in an expression.
|
| Given an operator and value, gives the type a chance
| to return a type which the value should be coerced into.
|
| The default behavior here is conservative; if the right-hand
| side is already coerced into a SQL type based on its
| Python type, it is usually left alone.
|
| End-user functionality extension here should generally be via
| :class:`.TypeDecorator`, which provides more liberal behavior in that
| it defaults to coercing the other side of the expression into this
| type, thus applying special Python conversions above and beyond those
| needed by the DBAPI to both ides. It also provides the public method
| :meth:`.TypeDecorator.coerce_compared_value` which is intended for
| end-user customization of this behavior.
|
| column_expression(self, colexpr: 'ColumnElement[_T]') -> 'Optional[ColumnElement[_T]]'
| Given a SELECT column expression, return a wrapping SQL expression.
|
| This is typically a SQL function that wraps a column expression
| as rendered in the columns clause of a SELECT statement.
| It is used for special data types that require
| columns to be wrapped in some special database function in order
| to coerce the value before being sent back to the application.
| It is the SQL analogue of the :meth:`.TypeEngine.result_processor`
| method.
|
| .. note:: The :func:`.TypeEngine.column_expression` method is applied
| only to the **outermost columns clause** of a SELECT statement, that
| is, the columns that are to be delivered directly into the returned
| result rows. It does **not** apply to the columns clause inside
| of subqueries. This necessarily avoids double conversions against
| the column and only runs the conversion when ready to be returned
| to the client.
|
| This method is called during the **SQL compilation** phase of a
| statement, when rendering a SQL string. It is **not** called
| against specific values.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.column_expression`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.column_expression`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.column_expression`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
|
| .. seealso::
|
| :ref:`types_sql_value_processing`
|
| compare_values(self, x: 'Any', y: 'Any') -> 'bool'
| Compare two values for equality.
|
| compile(self, dialect: 'Optional[Dialect]' = None) -> 'str'
| Produce a string-compiled form of this :class:`.TypeEngine`.
|
| When called with no arguments, uses a "default" dialect
| to produce a string result.
|
| :param dialect: a :class:`.Dialect` instance.
|
| copy(self, **kw: 'Any') -> 'Self'
|
| copy_value(self, value: 'Any') -> 'Any'
|
| dialect_impl(self, dialect: 'Dialect') -> 'TypeEngine[_T]'
| Return a dialect-specific implementation for this
| :class:`.TypeEngine`.
|
| evaluates_none(self) -> 'Self'
| Return a copy of this type which has the
| :attr:`.should_evaluate_none` flag set to True.
|
| E.g.::
|
| Table(
| "some_table",
| metadata,
| Column(
| String(50).evaluates_none(),
| nullable=True,
| server_default="no value",
| ),
| )
|
| The ORM uses this flag to indicate that a positive value of ``None``
| is passed to the column in an INSERT statement, rather than omitting
| the column from the INSERT statement which has the effect of firing
| off column-level defaults. It also allows for types which have
| special behavior associated with the Python None value to indicate
| that the value doesn't necessarily translate into SQL NULL; a
| prime example of this is a JSON type which may wish to persist the
| JSON value ``'null'``.
|
| In all cases, the actual NULL SQL value can be always be
| persisted in any column by using
| the :obj:`_expression.null` SQL construct in an INSERT statement
| or associated with an ORM-mapped attribute.
|
| .. note::
|
| The "evaluates none" flag does **not** apply to a value
| of ``None`` passed to :paramref:`_schema.Column.default` or
| :paramref:`_schema.Column.server_default`; in these cases,
| ``None``
| still means "no default".
|
| .. seealso::
|
| :ref:`session_forcing_null` - in the ORM documentation
|
| :paramref:`.postgresql.JSON.none_as_null` - PostgreSQL JSON
| interaction with this flag.
|
| :attr:`.TypeEngine.should_evaluate_none` - class-level flag
|
| result_processor(self, dialect: 'Dialect', coltype: 'object') -> 'Optional[_ResultProcessorType[_T]]'
| Return a conversion function for processing result row values.
|
| Returns a callable which will receive a result row column
| value as the sole positional argument and will return a value
| to return to the user.
|
| If processing is not necessary, the method should return ``None``.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.result_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.result_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_result_value`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| :param dialect: Dialect instance in use.
|
| :param coltype: DBAPI coltype argument received in cursor.description.
|
| with_variant(self, type_: '_TypeEngineArgument[Any]', *dialect_names: 'str') -> 'Self'
| Produce a copy of this type object that will utilize the given
| type when applied to the dialect of the given name.
|
| e.g.::
|
| from sqlalchemy.types import String
| from sqlalchemy.dialects import mysql
|
| string_type = String()
|
| string_type = string_type.with_variant(
| mysql.VARCHAR(collation="foo"), "mysql", "mariadb"
| )
|
| The variant mapping indicates that when this type is
| interpreted by a specific dialect, it will instead be
| transmuted into the given type, rather than using the
| primary type.
|
| .. versionchanged:: 2.0 the :meth:`_types.TypeEngine.with_variant`
| method now works with a :class:`_types.TypeEngine` object "in
| place", returning a copy of the original type rather than returning
| a wrapping object; the ``Variant`` class is no longer used.
|
| :param type\_: a :class:`.TypeEngine` that will be selected
| as a variant from the originating type, when a dialect
| of the given name is in use.
| :param \*dialect_names: one or more base names of the dialect which
| uses this type. (i.e. ``'postgresql'``, ``'mysql'``, etc.)
|
| .. versionchanged:: 2.0 multiple dialect names can be specified
| for one variant.
|
| .. seealso::
|
| :ref:`types_with_variant` - illustrates the use of
| :meth:`_types.TypeEngine.with_variant`.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.type_api.TypeEngine:
|
| __orig_bases__ = (<class 'sqlalchemy.sql.visitors.Visitable'>, typing....
|
| hashable = True
|
| render_bind_cast = False
|
| render_literal_cast = False
|
| should_evaluate_none = False
|
| sort_key_function = None
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.visitors.Visitable:
|
| __class_getitem__(key: 'Any') -> 'Any'
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__() -> 'None'
| This method is called when a class is subclassed.
|
| The default implementation does nothing. It may be
| overridden to extend subclasses.
sqlalchemy.Identity
Python Library Documentation: class Identity in module sqlalchemy.sql.schema
class Identity(IdentityOptions, FetchedValue, SchemaItem)
| Identity(always: 'bool' = False, on_null: 'Optional[bool]' = None, start: 'Optional[int]' = None, increment: 'Optional[int]' = None, minvalue: 'Optional[int]' = None, maxvalue: 'Optional[int]' = None, nominvalue: 'Optional[bool]' = None, nomaxvalue: 'Optional[bool]' = None, cycle: 'Optional[bool]' = None, cache: 'Optional[int]' = None, order: 'Optional[bool]' = None) -> 'None'
|
| Defines an identity column, i.e. "GENERATED { ALWAYS | BY DEFAULT }
| AS IDENTITY" syntax.
|
| The :class:`.Identity` construct is an inline construct added to the
| argument list of a :class:`_schema.Column` object::
|
| from sqlalchemy import Identity
|
| Table(
| "foo",
| metadata_obj,
| Column("id", Integer, Identity()),
| Column("description", Text),
| )
|
| See the linked documentation below for complete details.
|
| .. versionadded:: 1.4
|
| .. seealso::
|
| :ref:`identity_ddl`
|
| Method resolution order:
| Identity
| IdentityOptions
| FetchedValue
| SchemaItem
| sqlalchemy.sql.base.SchemaVisitable
| sqlalchemy.sql.base.SchemaEventTarget
| sqlalchemy.event.registry.EventTarget
| sqlalchemy.sql.visitors.Visitable
| builtins.object
|
| Methods defined here:
|
| __init__(self, always: 'bool' = False, on_null: 'Optional[bool]' = None, start: 'Optional[int]' = None, increment: 'Optional[int]' = None, minvalue: 'Optional[int]' = None, maxvalue: 'Optional[int]' = None, nominvalue: 'Optional[bool]' = None, nomaxvalue: 'Optional[bool]' = None, cycle: 'Optional[bool]' = None, cache: 'Optional[int]' = None, order: 'Optional[bool]' = None) -> 'None'
| Construct a GENERATED { ALWAYS | BY DEFAULT } AS IDENTITY DDL
| construct to accompany a :class:`_schema.Column`.
|
| See the :class:`.Sequence` documentation for a complete description
| of most parameters.
|
| .. note::
| MSSQL supports this construct as the preferred alternative to
| generate an IDENTITY on a column, but it uses non standard
| syntax that only support :paramref:`_schema.Identity.start`
| and :paramref:`_schema.Identity.increment`.
| All other parameters are ignored.
|
| :param always:
| A boolean, that indicates the type of identity column.
| If ``False`` is specified, the default, then the user-specified
| value takes precedence.
| If ``True`` is specified, a user-specified value is not accepted (
| on some backends, like PostgreSQL, OVERRIDING SYSTEM VALUE, or
| similar, may be specified in an INSERT to override the sequence
| value).
| Some backends also have a default value for this parameter,
| ``None`` can be used to omit rendering this part in the DDL. It
| will be treated as ``False`` if a backend does not have a default
| value.
|
| :param on_null:
| Set to ``True`` to specify ON NULL in conjunction with a
| ``always=False`` identity column. This option is only supported on
| some backends, like Oracle Database.
|
| :param start: the starting index of the sequence.
| :param increment: the increment value of the sequence.
| :param minvalue: the minimum value of the sequence.
| :param maxvalue: the maximum value of the sequence.
| :param nominvalue: no minimum value of the sequence.
| :param nomaxvalue: no maximum value of the sequence.
| :param cycle: allows the sequence to wrap around when the maxvalue
| or minvalue has been reached.
| :param cache: optional integer value; number of future values in the
| sequence which are calculated in advance.
| :param order: optional boolean value; if true, renders the
| ORDER keyword.
|
| copy(self, **kw: 'Any') -> 'Identity'
| .. deprecated:: 1.4 The :meth:`_schema.Identity.copy` method is deprecated and will be removed in a future release.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| __visit_name__ = 'identity_column'
|
| is_identity = True
|
| ----------------------------------------------------------------------
| Data descriptors inherited from IdentityOptions:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Methods inherited from FetchedValue:
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from FetchedValue:
|
| has_argument = False
|
| is_clause_element = False
|
| is_server_default = True
|
| reflected = False
|
| ----------------------------------------------------------------------
| Methods inherited from SchemaItem:
|
| info(...)
| Info dictionary associated with the object, allowing user-defined
| data to be associated with this :class:`.SchemaItem`.
|
| The dictionary is automatically generated when first accessed.
| It can also be specified in the constructor of some objects,
| such as :class:`_schema.Table` and :class:`_schema.Column`.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from SchemaItem:
|
| create_drop_stringify_dialect = 'default'
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.base.SchemaEventTarget:
|
| dispatch = <sqlalchemy.event.base.DDLEventsDispatch object>
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.visitors.Visitable:
|
| __class_getitem__(key: 'Any') -> 'Any'
|
| __init_subclass__() -> 'None'
| This method is called when a class is subclassed.
|
| The default implementation does nothing. It may be
| overridden to extend subclasses.
sqlalchemy.Index
Python Library Documentation: class Index in module sqlalchemy.sql.schema
class Index(sqlalchemy.sql.base.DialectKWArgs, ColumnCollectionMixin, HasConditionalDDL, SchemaItem)
| Index(name: 'Optional[str]', *expressions: '_DDLColumnArgument', unique: 'bool' = False, quote: 'Optional[bool]' = None, info: 'Optional[_InfoType]' = None, _table: 'Optional[Table]' = None, _column_flag: 'bool' = False, **dialect_kw: 'Any') -> 'None'
|
| A table-level INDEX.
|
| Defines a composite (one or more column) INDEX.
|
| E.g.::
|
| sometable = Table(
| "sometable",
| metadata,
| Column("name", String(50)),
| Column("address", String(100)),
| )
|
| Index("some_index", sometable.c.name)
|
| For a no-frills, single column index, adding
| :class:`_schema.Column` also supports ``index=True``::
|
| sometable = Table(
| "sometable", metadata, Column("name", String(50), index=True)
| )
|
| For a composite index, multiple columns can be specified::
|
| Index("some_index", sometable.c.name, sometable.c.address)
|
| Functional indexes are supported as well, typically by using the
| :data:`.func` construct in conjunction with table-bound
| :class:`_schema.Column` objects::
|
| Index("some_index", func.lower(sometable.c.name))
|
| An :class:`.Index` can also be manually associated with a
| :class:`_schema.Table`,
| either through inline declaration or using
| :meth:`_schema.Table.append_constraint`. When this approach is used,
| the names
| of the indexed columns can be specified as strings::
|
| Table(
| "sometable",
| metadata,
| Column("name", String(50)),
| Column("address", String(100)),
| Index("some_index", "name", "address"),
| )
|
| To support functional or expression-based indexes in this form, the
| :func:`_expression.text` construct may be used::
|
| from sqlalchemy import text
|
| Table(
| "sometable",
| metadata,
| Column("name", String(50)),
| Column("address", String(100)),
| Index("some_index", text("lower(name)")),
| )
|
| .. seealso::
|
| :ref:`schema_indexes` - General information on :class:`.Index`.
|
| :ref:`postgresql_indexes` - PostgreSQL-specific options available for
| the :class:`.Index` construct.
|
| :ref:`mysql_indexes` - MySQL-specific options available for the
| :class:`.Index` construct.
|
| :ref:`mssql_indexes` - MSSQL-specific options available for the
| :class:`.Index` construct.
|
| Method resolution order:
| Index
| sqlalchemy.sql.base.DialectKWArgs
| ColumnCollectionMixin
| HasConditionalDDL
| SchemaItem
| sqlalchemy.sql.base.SchemaVisitable
| sqlalchemy.sql.base.SchemaEventTarget
| sqlalchemy.event.registry.EventTarget
| sqlalchemy.sql.visitors.Visitable
| builtins.object
|
| Methods defined here:
|
| __init__(self, name: 'Optional[str]', *expressions: '_DDLColumnArgument', unique: 'bool' = False, quote: 'Optional[bool]' = None, info: 'Optional[_InfoType]' = None, _table: 'Optional[Table]' = None, _column_flag: 'bool' = False, **dialect_kw: 'Any') -> 'None'
| Construct an index object.
|
| :param name:
| The name of the index
|
| :param \*expressions:
| Column expressions to include in the index. The expressions
| are normally instances of :class:`_schema.Column`, but may also
| be arbitrary SQL expressions which ultimately refer to a
| :class:`_schema.Column`.
|
| :param unique=False:
| Keyword only argument; if True, create a unique index.
|
| :param quote=None:
| Keyword only argument; whether to apply quoting to the name of
| the index. Works in the same manner as that of
| :paramref:`_schema.Column.quote`.
|
| :param info=None: Optional data dictionary which will be populated
| into the :attr:`.SchemaItem.info` attribute of this object.
|
| :param \**dialect_kw: Additional keyword arguments not mentioned above
| are dialect specific, and passed in the form
| ``<dialectname>_<argname>``. See the documentation regarding an
| individual dialect at :ref:`dialect_toplevel` for detail on
| documented arguments.
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| create(self, bind: '_CreateDropBind', checkfirst: 'bool' = False) -> 'None'
| Issue a ``CREATE`` statement for this
| :class:`.Index`, using the given
| :class:`.Connection` or :class:`.Engine`` for connectivity.
|
| .. seealso::
|
| :meth:`_schema.MetaData.create_all`.
|
| drop(self, bind: '_CreateDropBind', checkfirst: 'bool' = False) -> 'None'
| Issue a ``DROP`` statement for this
| :class:`.Index`, using the given
| :class:`.Connection` or :class:`.Engine` for connectivity.
|
| .. seealso::
|
| :meth:`_schema.MetaData.drop_all`.
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'_table_bound_expressions': '_typing_Sequence[Colum...
|
| __visit_name__ = 'index'
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.base.DialectKWArgs:
|
| dialect_options(...)
| A collection of keyword arguments specified as dialect-specific
| options to this construct.
|
| This is a two-level nested registry, keyed to ``<dialect_name>``
| and ``<argument_name>``. For example, the ``postgresql_where``
| argument would be locatable as::
|
| arg = my_object.dialect_options["postgresql"]["where"]
|
| .. versionadded:: 0.9.2
|
| .. seealso::
|
| :attr:`.DialectKWArgs.dialect_kwargs` - flat dictionary form
|
| get_dialect_option(self, dialect: 'Dialect', argument_name: 'str', *, else_: 'Any' = None, deprecated_fallback: 'Optional[str]' = None) -> 'Any'
| Return the value of a dialect-specific option, or *else_* if
| this dialect does not register the given argument.
|
| This is useful for DDL compilers that may be inherited by
| third-party dialects whose ``construct_arguments`` do not
| include the same set of keys as the parent dialect.
|
| :param dialect: The dialect for which to retrieve the option.
| :param argument_name: The name of the argument to retrieve.
| :param else\_: The value to return if the argument is not present.
| :param deprecated_fallback: Optional dialect name to fall back to
| if the argument is not present for the current dialect. If the
| argument is present for the fallback dialect but not the current
| dialect, a deprecation warning will be emitted.
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.base.DialectKWArgs:
|
| argument_for(dialect_name: 'str', argument_name: 'str', default: 'Any') -> 'None'
| Add a new kind of dialect-specific keyword argument for this class.
|
| E.g.::
|
| Index.argument_for("mydialect", "length", None)
|
| some_index = Index("a", "b", mydialect_length=5)
|
| The :meth:`.DialectKWArgs.argument_for` method is a per-argument
| way adding extra arguments to the
| :attr:`.DefaultDialect.construct_arguments` dictionary. This
| dictionary provides a list of argument names accepted by various
| schema-level constructs on behalf of a dialect.
|
| New dialects should typically specify this dictionary all at once as a
| data member of the dialect class. The use case for ad-hoc addition of
| argument names is typically for end-user code that is also using
| a custom compilation scheme which consumes the additional arguments.
|
| :param dialect_name: name of a dialect. The dialect must be
| locatable, else a :class:`.NoSuchModuleError` is raised. The
| dialect must also include an existing
| :attr:`.DefaultDialect.construct_arguments` collection, indicating
| that it participates in the keyword-argument validation and default
| system, else :class:`.ArgumentError` is raised. If the dialect does
| not include this collection, then any keyword argument can be
| specified on behalf of this dialect already. All dialects packaged
| within SQLAlchemy include this collection, however for third party
| dialects, support may vary.
|
| :param argument_name: name of the parameter.
|
| :param default: default value of the parameter.
|
| ----------------------------------------------------------------------
| Readonly properties inherited from sqlalchemy.sql.base.DialectKWArgs:
|
| dialect_kwargs
| A collection of keyword arguments specified as dialect-specific
| options to this construct.
|
| The arguments are present here in their original ``<dialect>_<kwarg>``
| format. Only arguments that were actually passed are included;
| unlike the :attr:`.DialectKWArgs.dialect_options` collection, which
| contains all options known by this dialect including defaults.
|
| The collection is also writable; keys are accepted of the
| form ``<dialect>_<kwarg>`` where the value will be assembled
| into the list of options.
|
| .. seealso::
|
| :attr:`.DialectKWArgs.dialect_options` - nested dictionary form
|
| kwargs
| A synonym for :attr:`.DialectKWArgs.dialect_kwargs`.
|
| ----------------------------------------------------------------------
| Methods inherited from ColumnCollectionMixin:
|
| c(...)
|
| columns(...)
|
| ----------------------------------------------------------------------
| Methods inherited from HasConditionalDDL:
|
| ddl_if(self, dialect: 'Optional[str]' = None, callable_: 'Optional[ddl.DDLIfCallable]' = None, state: 'Optional[Any]' = None) -> 'Self'
| apply a conditional DDL rule to this schema item.
|
| These rules work in a similar manner to the
| :meth:`.ExecutableDDLElement.execute_if` callable, with the added
| feature that the criteria may be checked within the DDL compilation
| phase for a construct such as :class:`.CreateTable`.
| :meth:`.HasConditionalDDL.ddl_if` currently applies towards the
| :class:`.Index` construct as well as all :class:`.Constraint`
| constructs.
|
| :param dialect: string name of a dialect, or a tuple of string names
| to indicate multiple dialect types.
|
| :param callable\_: a callable that is constructed using the same form
| as that described in
| :paramref:`.ExecutableDDLElement.execute_if.callable_`.
|
| :param state: any arbitrary object that will be passed to the
| callable, if present.
|
| .. versionadded:: 2.0
|
| .. seealso::
|
| :ref:`schema_ddl_ddl_if` - background and usage examples
|
| ----------------------------------------------------------------------
| Methods inherited from SchemaItem:
|
| info(...)
| Info dictionary associated with the object, allowing user-defined
| data to be associated with this :class:`.SchemaItem`.
|
| The dictionary is automatically generated when first accessed.
| It can also be specified in the constructor of some objects,
| such as :class:`_schema.Table` and :class:`_schema.Column`.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from SchemaItem:
|
| create_drop_stringify_dialect = 'default'
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.base.SchemaEventTarget:
|
| dispatch = <sqlalchemy.event.base.DDLEventsDispatch object>
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.visitors.Visitable:
|
| __class_getitem__(key: 'Any') -> 'Any'
|
| __init_subclass__() -> 'None'
| This method is called when a class is subclassed.
|
| The default implementation does nothing. It may be
| overridden to extend subclasses.
sqlalchemy.Insert
Python Library Documentation: class Insert in module sqlalchemy.sql.dml
class Insert(ValuesBase)
| Insert(table: '_DMLTableArgument')
|
| Represent an INSERT construct.
|
| The :class:`_expression.Insert` object is created using the
| :func:`_expression.insert()` function.
|
| Method resolution order:
| Insert
| ValuesBase
| UpdateBase
| sqlalchemy.sql.roles.DMLRole
| sqlalchemy.sql.selectable.HasCTE
| sqlalchemy.sql.roles.HasCTERole
| sqlalchemy.sql.selectable.SelectsRows
| sqlalchemy.sql.base.HasCompileState
| sqlalchemy.sql.base.DialectKWArgs
| sqlalchemy.sql.selectable.HasPrefixes
| sqlalchemy.sql.base.Generative
| sqlalchemy.sql.selectable.ExecutableReturnsRows
| sqlalchemy.sql.base.Executable
| sqlalchemy.sql.roles.StatementRole
| sqlalchemy.sql.selectable.ReturnsRows
| sqlalchemy.sql.roles.ReturnsRowsRole
| sqlalchemy.sql.roles.SQLRole
| sqlalchemy.sql.elements.DQLDMLClauseElement
| sqlalchemy.sql.elements.ClauseElement
| sqlalchemy.sql.annotation.SupportsWrappingAnnotations
| sqlalchemy.sql.annotation.SupportsAnnotations
| sqlalchemy.sql.cache_key.MemoizedHasCacheKey
| sqlalchemy.sql.cache_key.HasCacheKey
| sqlalchemy.util.langhelpers.HasMemoized
| sqlalchemy.sql.traversals.HasCopyInternals
| sqlalchemy.sql.visitors.ExternallyTraversible
| sqlalchemy.sql.visitors.HasTraverseInternals
| sqlalchemy.sql.elements.CompilerElement
| sqlalchemy.sql.visitors.Visitable
| builtins.object
|
| Methods defined here:
|
| __init__(self, table: '_DMLTableArgument')
| Initialize self. See help(type(self)) for accurate signature.
|
| from_select(self, names: 'Sequence[_DMLColumnArgument]', select: 'Selectable', include_defaults: 'bool' = True) -> 'Self'
| Return a new :class:`_expression.Insert` construct which represents
| an ``INSERT...FROM SELECT`` statement.
|
| e.g.::
|
| sel = select(table1.c.a, table1.c.b).where(table1.c.c > 5)
| ins = table2.insert().from_select(["a", "b"], sel)
|
| :param names: a sequence of string column names or
| :class:`_schema.Column`
| objects representing the target columns.
| :param select: a :func:`_expression.select` construct,
| :class:`_expression.FromClause`
| or other construct which resolves into a
| :class:`_expression.FromClause`,
| such as an ORM :class:`_query.Query` object, etc. The order of
| columns returned from this FROM clause should correspond to the
| order of columns sent as the ``names`` parameter; while this
| is not checked before passing along to the database, the database
| would normally raise an exception if these column lists don't
| correspond.
| :param include_defaults: if True, non-server default values and
| SQL expressions as specified on :class:`_schema.Column` objects
| (as documented in :ref:`metadata_defaults_toplevel`) not
| otherwise specified in the list of names will be rendered
| into the INSERT and SELECT statements, so that these values are also
| included in the data to be inserted.
|
| .. note:: A Python-side default that uses a Python callable function
| will only be invoked **once** for the whole statement, and **not
| per row**.
|
| inline(self) -> 'Self'
| Make this :class:`_expression.Insert` construct "inline" .
|
| When set, no attempt will be made to retrieve the
| SQL-generated default values to be provided within the statement;
| in particular,
| this allows SQL expressions to be rendered 'inline' within the
| statement without the need to pre-execute them beforehand; for
| backends that support "returning", this turns off the "implicit
| returning" feature for the statement.
|
|
| .. versionchanged:: 1.4 the :paramref:`_expression.Insert.inline`
| parameter
| is now superseded by the :meth:`_expression.Insert.inline` method.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'_sort_by_parameter_order': 'bool', 'table': 'Table...
|
| __visit_name__ = 'insert'
|
| include_insert_from_select_defaults = False
|
| is_insert = True
|
| select = None
|
| ----------------------------------------------------------------------
| Methods inherited from ValuesBase:
|
| values(self, *args: 'Union[_DMLColumnKeyMapping[Any], Sequence[Any]]', **kwargs: 'Any') -> 'Self'
| Specify a fixed VALUES clause for an INSERT statement, or the SET
| clause for an UPDATE.
|
| Note that the :class:`_expression.Insert` and
| :class:`_expression.Update`
| constructs support
| per-execution time formatting of the VALUES and/or SET clauses,
| based on the arguments passed to :meth:`_engine.Connection.execute`.
| However, the :meth:`.ValuesBase.values` method can be used to "fix" a
| particular set of parameters into the statement.
|
| Multiple calls to :meth:`.ValuesBase.values` will produce a new
| construct, each one with the parameter list modified to include
| the new parameters sent. In the typical case of a single
| dictionary of parameters, the newly passed keys will replace
| the same keys in the previous construct. In the case of a list-based
| "multiple values" construct, each new list of values is extended
| onto the existing list of values.
|
| :param \**kwargs: key value pairs representing the string key
| of a :class:`_schema.Column`
| mapped to the value to be rendered into the
| VALUES or SET clause::
|
| users.insert().values(name="some name")
|
| users.update().where(users.c.id == 5).values(name="some name")
|
| :param \*args: As an alternative to passing key/value parameters,
| a dictionary, tuple, or list of dictionaries or tuples can be passed
| as a single positional argument in order to form the VALUES or
| SET clause of the statement. The forms that are accepted vary
| based on whether this is an :class:`_expression.Insert` or an
| :class:`_expression.Update` construct.
|
| For either an :class:`_expression.Insert` or
| :class:`_expression.Update`
| construct, a single dictionary can be passed, which works the same as
| that of the kwargs form::
|
| users.insert().values({"name": "some name"})
|
| users.update().values({"name": "some new name"})
|
| Also for either form but more typically for the
| :class:`_expression.Insert` construct, a tuple that contains an
| entry for every column in the table is also accepted::
|
| users.insert().values((5, "some name"))
|
| The :class:`_expression.Insert` construct also supports being
| passed a list of dictionaries or full-table-tuples, which on the
| server will render the less common SQL syntax of "multiple values" -
| this syntax is supported on backends such as SQLite, PostgreSQL,
| MySQL, but not necessarily others::
|
| users.insert().values(
| [
| {"name": "some name"},
| {"name": "some other name"},
| {"name": "yet another name"},
| ]
| )
|
| The above form would render a multiple VALUES statement similar to:
|
| .. sourcecode:: sql
|
| INSERT INTO users (name) VALUES
| (:name_1),
| (:name_2),
| (:name_3)
|
| It is essential to note that **passing multiple values is
| NOT the same as using traditional executemany() form**. The above
| syntax is a **special** syntax not typically used. To emit an
| INSERT statement against multiple rows, the normal method is
| to pass a multiple values list to the
| :meth:`_engine.Connection.execute`
| method, which is supported by all database backends and is generally
| more efficient for a very large number of parameters.
|
| .. seealso::
|
| :ref:`tutorial_multiple_parameters` - an introduction to
| the traditional Core method of multiple parameter set
| invocation for INSERTs and other statements.
|
| :ref:`tutorial_core_insert_values_clause` - Insert tutorial
| detailing alternatives to the multiple values syntax.
|
| The UPDATE construct also supports rendering the SET parameters
| in a specific order. For this feature refer to the
| :meth:`_expression.Update.ordered_values` method.
|
| .. seealso::
|
| :meth:`_expression.Update.ordered_values`
|
| ----------------------------------------------------------------------
| Methods inherited from UpdateBase:
|
| corresponding_column(self, column: 'KeyedColumnElement[Any]', require_embedded: 'bool' = False) -> 'Optional[ColumnElement[Any]]'
|
| exported_columns(...)
| Return the RETURNING columns as a column collection for this
| statement.
|
| .. versionadded:: 1.4
|
| is_derived_from(self, fromclause: 'Optional[FromClause]') -> 'bool'
| Return ``True`` if this :class:`.ReturnsRows` is
| 'derived' from the given :class:`.FromClause`.
|
| Since these are DMLs, we dont want such statements ever being adapted
| so we return False for derives.
|
| params(self, *arg: 'Any', **kw: 'Any') -> 'NoReturn'
| Set the parameters for the statement.
|
| This method raises ``NotImplementedError`` on the base class,
| and is overridden by :class:`.ValuesBase` to provide the
| SET/VALUES clause of UPDATE and INSERT.
|
| return_defaults(self, *cols: '_DMLColumnArgument', supplemental_cols: 'Optional[Iterable[_DMLColumnArgument]]' = None, sort_by_parameter_order: 'bool' = False) -> 'Self'
| Make use of a :term:`RETURNING` clause for the purpose
| of fetching server-side expressions and defaults, for supporting
| backends only.
|
| .. deepalchemy::
|
| The :meth:`.UpdateBase.return_defaults` method is used by the ORM
| for its internal work in fetching newly generated primary key
| and server default values, in particular to provide the underlying
| implementation of the :paramref:`_orm.Mapper.eager_defaults`
| ORM feature as well as to allow RETURNING support with bulk
| ORM inserts. Its behavior is fairly idiosyncratic
| and is not really intended for general use. End users should
| stick with using :meth:`.UpdateBase.returning` in order to
| add RETURNING clauses to their INSERT, UPDATE and DELETE
| statements.
|
| Normally, a single row INSERT statement will automatically populate the
| :attr:`.CursorResult.inserted_primary_key` attribute when executed,
| which stores the primary key of the row that was just inserted in the
| form of a :class:`.Row` object with column names as named tuple keys
| (and the :attr:`.Row._mapping` view fully populated as well). The
| dialect in use chooses the strategy to use in order to populate this
| data; if it was generated using server-side defaults and / or SQL
| expressions, dialect-specific approaches such as ``cursor.lastrowid``
| or ``RETURNING`` are typically used to acquire the new primary key
| value.
|
| However, when the statement is modified by calling
| :meth:`.UpdateBase.return_defaults` before executing the statement,
| additional behaviors take place **only** for backends that support
| RETURNING and for :class:`.Table` objects that maintain the
| :paramref:`.Table.implicit_returning` parameter at its default value of
| ``True``. In these cases, when the :class:`.CursorResult` is returned
| from the statement's execution, not only will
| :attr:`.CursorResult.inserted_primary_key` be populated as always, the
| :attr:`.CursorResult.returned_defaults` attribute will also be
| populated with a :class:`.Row` named-tuple representing the full range
| of server generated
| values from that single row, including values for any columns that
| specify :paramref:`_schema.Column.server_default` or which make use of
| :paramref:`_schema.Column.default` using a SQL expression.
|
| When invoking INSERT statements with multiple rows using
| :ref:`insertmanyvalues <engine_insertmanyvalues>`, the
| :meth:`.UpdateBase.return_defaults` modifier will have the effect of
| the :attr:`_engine.CursorResult.inserted_primary_key_rows` and
| :attr:`_engine.CursorResult.returned_defaults_rows` attributes being
| fully populated with lists of :class:`.Row` objects representing newly
| inserted primary key values as well as newly inserted server generated
| values for each row inserted. The
| :attr:`.CursorResult.inserted_primary_key` and
| :attr:`.CursorResult.returned_defaults` attributes will also continue
| to be populated with the first row of these two collections.
|
| If the backend does not support RETURNING or the :class:`.Table` in use
| has disabled :paramref:`.Table.implicit_returning`, then no RETURNING
| clause is added and no additional data is fetched, however the
| INSERT, UPDATE or DELETE statement proceeds normally.
|
| E.g.::
|
| stmt = table.insert().values(data="newdata").return_defaults()
|
| result = connection.execute(stmt)
|
| server_created_at = result.returned_defaults["created_at"]
|
| When used against an UPDATE statement
| :meth:`.UpdateBase.return_defaults` instead looks for columns that
| include :paramref:`_schema.Column.onupdate` or
| :paramref:`_schema.Column.server_onupdate` parameters assigned, when
| constructing the columns that will be included in the RETURNING clause
| by default if explicit columns were not specified. When used against a
| DELETE statement, no columns are included in RETURNING by default, they
| instead must be specified explicitly as there are no columns that
| normally change values when a DELETE statement proceeds.
|
| .. versionadded:: 2.0 :meth:`.UpdateBase.return_defaults` is supported
| for DELETE statements also and has been moved from
| :class:`.ValuesBase` to :class:`.UpdateBase`.
|
| The :meth:`.UpdateBase.return_defaults` method is mutually exclusive
| against the :meth:`.UpdateBase.returning` method and errors will be
| raised during the SQL compilation process if both are used at the same
| time on one statement. The RETURNING clause of the INSERT, UPDATE or
| DELETE statement is therefore controlled by only one of these methods
| at a time.
|
| The :meth:`.UpdateBase.return_defaults` method differs from
| :meth:`.UpdateBase.returning` in these ways:
|
| 1. :meth:`.UpdateBase.return_defaults` method causes the
| :attr:`.CursorResult.returned_defaults` collection to be populated
| with the first row from the RETURNING result. This attribute is not
| populated when using :meth:`.UpdateBase.returning`.
|
| 2. :meth:`.UpdateBase.return_defaults` is compatible with existing
| logic used to fetch auto-generated primary key values that are then
| populated into the :attr:`.CursorResult.inserted_primary_key`
| attribute. By contrast, using :meth:`.UpdateBase.returning` will
| have the effect of the :attr:`.CursorResult.inserted_primary_key`
| attribute being left unpopulated.
|
| 3. :meth:`.UpdateBase.return_defaults` can be called against any
| backend. Backends that don't support RETURNING will skip the usage
| of the feature, rather than raising an exception, *unless*
| ``supplemental_cols`` is passed. The return value
| of :attr:`_engine.CursorResult.returned_defaults` will be ``None``
| for backends that don't support RETURNING or for which the target
| :class:`.Table` sets :paramref:`.Table.implicit_returning` to
| ``False``.
|
| 4. An INSERT statement invoked with executemany() is supported if the
| backend database driver supports the
| :ref:`insertmanyvalues <engine_insertmanyvalues>`
| feature which is now supported by most SQLAlchemy-included backends.
| When executemany is used, the
| :attr:`_engine.CursorResult.returned_defaults_rows` and
| :attr:`_engine.CursorResult.inserted_primary_key_rows` accessors
| will return the inserted defaults and primary keys.
|
| .. versionadded:: 1.4 Added
| :attr:`_engine.CursorResult.returned_defaults_rows` and
| :attr:`_engine.CursorResult.inserted_primary_key_rows` accessors.
| In version 2.0, the underlying implementation which fetches and
| populates the data for these attributes was generalized to be
| supported by most backends, whereas in 1.4 they were only
| supported by the ``psycopg2`` driver.
|
|
| :param cols: optional list of column key names or
| :class:`_schema.Column` that acts as a filter for those columns that
| will be fetched.
| :param supplemental_cols: optional list of RETURNING expressions,
| in the same form as one would pass to the
| :meth:`.UpdateBase.returning` method. When present, the additional
| columns will be included in the RETURNING clause, and the
| :class:`.CursorResult` object will be "rewound" when returned, so
| that methods like :meth:`.CursorResult.all` will return new rows
| mostly as though the statement used :meth:`.UpdateBase.returning`
| directly. However, unlike when using :meth:`.UpdateBase.returning`
| directly, the **order of the columns is undefined**, so can only be
| targeted using names or :attr:`.Row._mapping` keys; they cannot
| reliably be targeted positionally.
|
| .. versionadded:: 2.0
|
| :param sort_by_parameter_order: for a batch INSERT that is being
| executed against multiple parameter sets, organize the results of
| RETURNING so that the returned rows correspond to the order of
| parameter sets passed in. This applies only to an :term:`executemany`
| execution for supporting dialects and typically makes use of the
| :term:`insertmanyvalues` feature.
|
| .. versionadded:: 2.0.10
|
| .. seealso::
|
| :ref:`engine_insertmanyvalues_returning_order` - background on
| sorting of RETURNING rows for bulk INSERT
|
| .. seealso::
|
| :meth:`.UpdateBase.returning`
|
| :attr:`_engine.CursorResult.returned_defaults`
|
| :attr:`_engine.CursorResult.returned_defaults_rows`
|
| :attr:`_engine.CursorResult.inserted_primary_key`
|
| :attr:`_engine.CursorResult.inserted_primary_key_rows`
|
| returning(self, *cols: '_ColumnsClauseArgument[Any]', sort_by_parameter_order: 'bool' = False, **_UpdateBase__kw: 'Any') -> 'UpdateBase'
| Add a :term:`RETURNING` or equivalent clause to this statement.
|
| e.g.:
|
| .. sourcecode:: pycon+sql
|
| >>> stmt = (
| ... table.update()
| ... .where(table.c.data == "value")
| ... .values(status="X")
| ... .returning(table.c.server_flag, table.c.updated_timestamp)
| ... )
| >>> print(stmt)
| {printsql}UPDATE some_table SET status=:status
| WHERE some_table.data = :data_1
| RETURNING some_table.server_flag, some_table.updated_timestamp
|
| The method may be invoked multiple times to add new entries to the
| list of expressions to be returned.
|
| .. versionadded:: 1.4.0b2 The method may be invoked multiple times to
| add new entries to the list of expressions to be returned.
|
| The given collection of column expressions should be derived from the
| table that is the target of the INSERT, UPDATE, or DELETE. While
| :class:`_schema.Column` objects are typical, the elements can also be
| expressions:
|
| .. sourcecode:: pycon+sql
|
| >>> stmt = table.insert().returning(
| ... (table.c.first_name + " " + table.c.last_name).label("fullname")
| ... )
| >>> print(stmt)
| {printsql}INSERT INTO some_table (first_name, last_name)
| VALUES (:first_name, :last_name)
| RETURNING some_table.first_name || :first_name_1 || some_table.last_name AS fullname
|
| Upon compilation, a RETURNING clause, or database equivalent,
| will be rendered within the statement. For INSERT and UPDATE,
| the values are the newly inserted/updated values. For DELETE,
| the values are those of the rows which were deleted.
|
| Upon execution, the values of the columns to be returned are made
| available via the result set and can be iterated using
| :meth:`_engine.CursorResult.fetchone` and similar.
| For DBAPIs which do not
| natively support returning values (i.e. cx_oracle), SQLAlchemy will
| approximate this behavior at the result level so that a reasonable
| amount of behavioral neutrality is provided.
|
| Note that not all databases/DBAPIs
| support RETURNING. For those backends with no support,
| an exception is raised upon compilation and/or execution.
| For those who do support it, the functionality across backends
| varies greatly, including restrictions on executemany()
| and other statements which return multiple rows. Please
| read the documentation notes for the database in use in
| order to determine the availability of RETURNING.
|
| :param \*cols: series of columns, SQL expressions, or whole tables
| entities to be returned.
| :param sort_by_parameter_order: for a batch INSERT that is being
| executed against multiple parameter sets, organize the results of
| RETURNING so that the returned rows correspond to the order of
| parameter sets passed in. This applies only to an :term:`executemany`
| execution for supporting dialects and typically makes use of the
| :term:`insertmanyvalues` feature.
|
| .. versionadded:: 2.0.10
|
| .. seealso::
|
| :ref:`engine_insertmanyvalues_returning_order` - background on
| sorting of RETURNING rows for bulk INSERT (Core level discussion)
|
| :ref:`orm_queryguide_bulk_insert_returning_ordered` - example of
| use with :ref:`orm_queryguide_bulk_insert` (ORM level discussion)
|
| .. seealso::
|
| :meth:`.UpdateBase.return_defaults` - an alternative method tailored
| towards efficient fetching of server-side defaults and triggers
| for single-row INSERTs or UPDATEs.
|
| :ref:`tutorial_insert_returning` - in the :ref:`unified_tutorial`
|
| with_dialect_options(self, **opt: 'Any') -> 'Self'
| Add dialect options to this INSERT/UPDATE/DELETE object.
|
| e.g.::
|
| upd = table.update().dialect_options(mysql_limit=10)
|
| .. versionadded: 1.4 - this method supersedes the dialect options
| associated with the constructor.
|
| with_hint(self, text: 'str', selectable: 'Optional[_DMLTableArgument]' = None, dialect_name: 'str' = '*') -> 'Self'
| Add a table hint for a single table to this
| INSERT/UPDATE/DELETE statement.
|
| .. note::
|
| :meth:`.UpdateBase.with_hint` currently applies only to
| Microsoft SQL Server. For MySQL INSERT/UPDATE/DELETE hints, use
| :meth:`.UpdateBase.prefix_with`.
|
| The text of the hint is rendered in the appropriate
| location for the database backend in use, relative
| to the :class:`_schema.Table` that is the subject of this
| statement, or optionally to that of the given
| :class:`_schema.Table` passed as the ``selectable`` argument.
|
| The ``dialect_name`` option will limit the rendering of a particular
| hint to a particular backend. Such as, to add a hint
| that only takes effect for SQL Server::
|
| mytable.insert().with_hint("WITH (PAGLOCK)", dialect_name="mssql")
|
| :param text: Text of the hint.
| :param selectable: optional :class:`_schema.Table` that specifies
| an element of the FROM clause within an UPDATE or DELETE
| to be the subject of the hint - applies only to certain backends.
| :param dialect_name: defaults to ``*``, if specified as the name
| of a particular dialect, will apply these hints only when
| that dialect is in use.
|
| ----------------------------------------------------------------------
| Readonly properties inherited from UpdateBase:
|
| entity_description
| Return a :term:`plugin-enabled` description of the table and/or
| entity which this DML construct is operating against.
|
| This attribute is generally useful when using the ORM, as an
| extended structure which includes information about mapped
| entities is returned. The section :ref:`queryguide_inspection`
| contains more background.
|
| For a Core statement, the structure returned by this accessor
| is derived from the :attr:`.UpdateBase.table` attribute, and
| refers to the :class:`.Table` being inserted, updated, or deleted::
|
| >>> stmt = insert(user_table)
| >>> stmt.entity_description
| {
| "name": "user_table",
| "table": Table("user_table", ...)
| }
|
| .. versionadded:: 1.4.33
|
| .. seealso::
|
| :attr:`.UpdateBase.returning_column_descriptions`
|
| :attr:`.Select.column_descriptions` - entity information for
| a :func:`.select` construct
|
| :ref:`queryguide_inspection` - ORM background
|
| returning_column_descriptions
| Return a :term:`plugin-enabled` description of the columns
| which this DML construct is RETURNING against, in other words
| the expressions established as part of :meth:`.UpdateBase.returning`.
|
| This attribute is generally useful when using the ORM, as an
| extended structure which includes information about mapped
| entities is returned. The section :ref:`queryguide_inspection`
| contains more background.
|
| For a Core statement, the structure returned by this accessor is
| derived from the same objects that are returned by the
| :attr:`.UpdateBase.exported_columns` accessor::
|
| >>> stmt = insert(user_table).returning(user_table.c.id, user_table.c.name)
| >>> stmt.entity_description
| [
| {
| "name": "id",
| "type": Integer,
| "expr": Column("id", Integer(), table=<user>, ...)
| },
| {
| "name": "name",
| "type": String(),
| "expr": Column("name", String(), table=<user>, ...)
| },
| ]
|
| .. versionadded:: 1.4.33
|
| .. seealso::
|
| :attr:`.UpdateBase.entity_description`
|
| :attr:`.Select.column_descriptions` - entity information for
| a :func:`.select` construct
|
| :ref:`queryguide_inspection` - ORM background
|
| ----------------------------------------------------------------------
| Data descriptors inherited from UpdateBase:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from UpdateBase:
|
| is_dml = True
|
| named_with_column = False
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.selectable.HasCTE:
|
| add_cte(self, *ctes: 'CTE', nest_here: 'bool' = False) -> 'Self'
| Add one or more :class:`_sql.CTE` constructs to this statement.
|
| This method will associate the given :class:`_sql.CTE` constructs with
| the parent statement such that they will each be unconditionally
| rendered in the WITH clause of the final statement, even if not
| referenced elsewhere within the statement or any sub-selects.
|
| The optional :paramref:`.HasCTE.add_cte.nest_here` parameter when set
| to True will have the effect that each given :class:`_sql.CTE` will
| render in a WITH clause rendered directly along with this statement,
| rather than being moved to the top of the ultimate rendered statement,
| even if this statement is rendered as a subquery within a larger
| statement.
|
| This method has two general uses. One is to embed CTE statements that
| serve some purpose without being referenced explicitly, such as the use
| case of embedding a DML statement such as an INSERT or UPDATE as a CTE
| inline with a primary statement that may draw from its results
| indirectly. The other is to provide control over the exact placement
| of a particular series of CTE constructs that should remain rendered
| directly in terms of a particular statement that may be nested in a
| larger statement.
|
| E.g.::
|
| from sqlalchemy import table, column, select
|
| t = table("t", column("c1"), column("c2"))
|
| ins = t.insert().values({"c1": "x", "c2": "y"}).cte()
|
| stmt = select(t).add_cte(ins)
|
| Would render:
|
| .. sourcecode:: sql
|
| WITH anon_1 AS (
| INSERT INTO t (c1, c2) VALUES (:param_1, :param_2)
| )
| SELECT t.c1, t.c2
| FROM t
|
| Above, the "anon_1" CTE is not referenced in the SELECT
| statement, however still accomplishes the task of running an INSERT
| statement.
|
| Similarly in a DML-related context, using the PostgreSQL
| :class:`_postgresql.Insert` construct to generate an "upsert"::
|
| from sqlalchemy import table, column
| from sqlalchemy.dialects.postgresql import insert
|
| t = table("t", column("c1"), column("c2"))
|
| delete_statement_cte = t.delete().where(t.c.c1 < 1).cte("deletions")
|
| insert_stmt = insert(t).values({"c1": 1, "c2": 2})
| update_statement = insert_stmt.on_conflict_do_update(
| index_elements=[t.c.c1],
| set_={
| "c1": insert_stmt.excluded.c1,
| "c2": insert_stmt.excluded.c2,
| },
| ).add_cte(delete_statement_cte)
|
| print(update_statement)
|
| The above statement renders as:
|
| .. sourcecode:: sql
|
| WITH deletions AS (
| DELETE FROM t WHERE t.c1 < %(c1_1)s
| )
| INSERT INTO t (c1, c2) VALUES (%(c1)s, %(c2)s)
| ON CONFLICT (c1) DO UPDATE SET c1 = excluded.c1, c2 = excluded.c2
|
| .. versionadded:: 1.4.21
|
| :param \*ctes: zero or more :class:`.CTE` constructs.
|
| .. versionchanged:: 2.0 Multiple CTE instances are accepted
|
| :param nest_here: if True, the given CTE or CTEs will be rendered
| as though they specified the :paramref:`.HasCTE.cte.nesting` flag
| to ``True`` when they were added to this :class:`.HasCTE`.
| Assuming the given CTEs are not referenced in an outer-enclosing
| statement as well, the CTEs given should render at the level of
| this statement when this flag is given.
|
| .. versionadded:: 2.0
|
| .. seealso::
|
| :paramref:`.HasCTE.cte.nesting`
|
| cte(self, name: 'Optional[str]' = None, recursive: 'bool' = False, nesting: 'bool' = False) -> 'CTE'
| Return a new :class:`_expression.CTE`,
| or Common Table Expression instance.
|
| Common table expressions are a SQL standard whereby SELECT
| statements can draw upon secondary statements specified along
| with the primary statement, using a clause called "WITH".
| Special semantics regarding UNION can also be employed to
| allow "recursive" queries, where a SELECT statement can draw
| upon the set of rows that have previously been selected.
|
| CTEs can also be applied to DML constructs UPDATE, INSERT
| and DELETE on some databases, both as a source of CTE rows
| when combined with RETURNING, as well as a consumer of
| CTE rows.
|
| SQLAlchemy detects :class:`_expression.CTE` objects, which are treated
| similarly to :class:`_expression.Alias` objects, as special elements
| to be delivered to the FROM clause of the statement as well
| as to a WITH clause at the top of the statement.
|
| For special prefixes such as PostgreSQL "MATERIALIZED" and
| "NOT MATERIALIZED", the :meth:`_expression.CTE.prefix_with`
| method may be
| used to establish these.
|
| .. versionchanged:: 1.3.13 Added support for prefixes.
| In particular - MATERIALIZED and NOT MATERIALIZED.
|
| :param name: name given to the common table expression. Like
| :meth:`_expression.FromClause.alias`, the name can be left as
| ``None`` in which case an anonymous symbol will be used at query
| compile time.
| :param recursive: if ``True``, will render ``WITH RECURSIVE``.
| A recursive common table expression is intended to be used in
| conjunction with UNION ALL in order to derive rows
| from those already selected.
| :param nesting: if ``True``, will render the CTE locally to the
| statement in which it is referenced. For more complex scenarios,
| the :meth:`.HasCTE.add_cte` method using the
| :paramref:`.HasCTE.add_cte.nest_here`
| parameter may also be used to more carefully
| control the exact placement of a particular CTE.
|
| .. versionadded:: 1.4.24
|
| .. seealso::
|
| :meth:`.HasCTE.add_cte`
|
| The following examples include two from PostgreSQL's documentation at
| https://www.postgresql.org/docs/current/static/queries-with.html,
| as well as additional examples.
|
| Example 1, non recursive::
|
| from sqlalchemy import (
| Table,
| Column,
| String,
| Integer,
| MetaData,
| select,
| func,
| )
|
| metadata = MetaData()
|
| orders = Table(
| "orders",
| metadata,
| Column("region", String),
| Column("amount", Integer),
| Column("product", String),
| Column("quantity", Integer),
| )
|
| regional_sales = (
| select(orders.c.region, func.sum(orders.c.amount).label("total_sales"))
| .group_by(orders.c.region)
| .cte("regional_sales")
| )
|
|
| top_regions = (
| select(regional_sales.c.region)
| .where(
| regional_sales.c.total_sales
| > select(func.sum(regional_sales.c.total_sales) / 10)
| )
| .cte("top_regions")
| )
|
| statement = (
| select(
| orders.c.region,
| orders.c.product,
| func.sum(orders.c.quantity).label("product_units"),
| func.sum(orders.c.amount).label("product_sales"),
| )
| .where(orders.c.region.in_(select(top_regions.c.region)))
| .group_by(orders.c.region, orders.c.product)
| )
|
| result = conn.execute(statement).fetchall()
|
| Example 2, WITH RECURSIVE::
|
| from sqlalchemy import (
| Table,
| Column,
| String,
| Integer,
| MetaData,
| select,
| func,
| )
|
| metadata = MetaData()
|
| parts = Table(
| "parts",
| metadata,
| Column("part", String),
| Column("sub_part", String),
| Column("quantity", Integer),
| )
|
| included_parts = (
| select(parts.c.sub_part, parts.c.part, parts.c.quantity)
| .where(parts.c.part == "our part")
| .cte(recursive=True)
| )
|
|
| incl_alias = included_parts.alias()
| parts_alias = parts.alias()
| included_parts = included_parts.union_all(
| select(
| parts_alias.c.sub_part, parts_alias.c.part, parts_alias.c.quantity
| ).where(parts_alias.c.part == incl_alias.c.sub_part)
| )
|
| statement = select(
| included_parts.c.sub_part,
| func.sum(included_parts.c.quantity).label("total_quantity"),
| ).group_by(included_parts.c.sub_part)
|
| result = conn.execute(statement).fetchall()
|
| Example 3, an upsert using UPDATE and INSERT with CTEs::
|
| from datetime import date
| from sqlalchemy import (
| MetaData,
| Table,
| Column,
| Integer,
| Date,
| select,
| literal,
| and_,
| exists,
| )
|
| metadata = MetaData()
|
| visitors = Table(
| "visitors",
| metadata,
| Column("product_id", Integer, primary_key=True),
| Column("date", Date, primary_key=True),
| Column("count", Integer),
| )
|
| # add 5 visitors for the product_id == 1
| product_id = 1
| day = date.today()
| count = 5
|
| update_cte = (
| visitors.update()
| .where(
| and_(visitors.c.product_id == product_id, visitors.c.date == day)
| )
| .values(count=visitors.c.count + count)
| .returning(literal(1))
| .cte("update_cte")
| )
|
| upsert = visitors.insert().from_select(
| [visitors.c.product_id, visitors.c.date, visitors.c.count],
| select(literal(product_id), literal(day), literal(count)).where(
| ~exists(update_cte.select())
| ),
| )
|
| connection.execute(upsert)
|
| Example 4, Nesting CTE (SQLAlchemy 1.4.24 and above)::
|
| value_a = select(literal("root").label("n")).cte("value_a")
|
| # A nested CTE with the same name as the root one
| value_a_nested = select(literal("nesting").label("n")).cte(
| "value_a", nesting=True
| )
|
| # Nesting CTEs takes ascendency locally
| # over the CTEs at a higher level
| value_b = select(value_a_nested.c.n).cte("value_b")
|
| value_ab = select(value_a.c.n.label("a"), value_b.c.n.label("b"))
|
| The above query will render the second CTE nested inside the first,
| shown with inline parameters below as:
|
| .. sourcecode:: sql
|
| WITH
| value_a AS
| (SELECT 'root' AS n),
| value_b AS
| (WITH value_a AS
| (SELECT 'nesting' AS n)
| SELECT value_a.n AS n FROM value_a)
| SELECT value_a.n AS a, value_b.n AS b
| FROM value_a, value_b
|
| The same CTE can be set up using the :meth:`.HasCTE.add_cte` method
| as follows (SQLAlchemy 2.0 and above)::
|
| value_a = select(literal("root").label("n")).cte("value_a")
|
| # A nested CTE with the same name as the root one
| value_a_nested = select(literal("nesting").label("n")).cte("value_a")
|
| # Nesting CTEs takes ascendency locally
| # over the CTEs at a higher level
| value_b = (
| select(value_a_nested.c.n)
| .add_cte(value_a_nested, nest_here=True)
| .cte("value_b")
| )
|
| value_ab = select(value_a.c.n.label("a"), value_b.c.n.label("b"))
|
| Example 5, Non-Linear CTE (SQLAlchemy 1.4.28 and above)::
|
| edge = Table(
| "edge",
| metadata,
| Column("id", Integer, primary_key=True),
| Column("left", Integer),
| Column("right", Integer),
| )
|
| root_node = select(literal(1).label("node")).cte("nodes", recursive=True)
|
| left_edge = select(edge.c.left).join(
| root_node, edge.c.right == root_node.c.node
| )
| right_edge = select(edge.c.right).join(
| root_node, edge.c.left == root_node.c.node
| )
|
| subgraph_cte = root_node.union(left_edge, right_edge)
|
| subgraph = select(subgraph_cte)
|
| The above query will render 2 UNIONs inside the recursive CTE:
|
| .. sourcecode:: sql
|
| WITH RECURSIVE nodes(node) AS (
| SELECT 1 AS node
| UNION
| SELECT edge."left" AS "left"
| FROM edge JOIN nodes ON edge."right" = nodes.node
| UNION
| SELECT edge."right" AS "right"
| FROM edge JOIN nodes ON edge."left" = nodes.node
| )
| SELECT nodes.node FROM nodes
|
| .. seealso::
|
| :meth:`_orm.Query.cte` - ORM version of
| :meth:`_expression.HasCTE.cte`.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.selectable.HasCTE:
|
| name_cte_columns = False
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.base.DialectKWArgs:
|
| dialect_options(...)
| A collection of keyword arguments specified as dialect-specific
| options to this construct.
|
| This is a two-level nested registry, keyed to ``<dialect_name>``
| and ``<argument_name>``. For example, the ``postgresql_where``
| argument would be locatable as::
|
| arg = my_object.dialect_options["postgresql"]["where"]
|
| .. versionadded:: 0.9.2
|
| .. seealso::
|
| :attr:`.DialectKWArgs.dialect_kwargs` - flat dictionary form
|
| get_dialect_option(self, dialect: 'Dialect', argument_name: 'str', *, else_: 'Any' = None, deprecated_fallback: 'Optional[str]' = None) -> 'Any'
| Return the value of a dialect-specific option, or *else_* if
| this dialect does not register the given argument.
|
| This is useful for DDL compilers that may be inherited by
| third-party dialects whose ``construct_arguments`` do not
| include the same set of keys as the parent dialect.
|
| :param dialect: The dialect for which to retrieve the option.
| :param argument_name: The name of the argument to retrieve.
| :param else\_: The value to return if the argument is not present.
| :param deprecated_fallback: Optional dialect name to fall back to
| if the argument is not present for the current dialect. If the
| argument is present for the fallback dialect but not the current
| dialect, a deprecation warning will be emitted.
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.base.DialectKWArgs:
|
| argument_for(dialect_name: 'str', argument_name: 'str', default: 'Any') -> 'None'
| Add a new kind of dialect-specific keyword argument for this class.
|
| E.g.::
|
| Index.argument_for("mydialect", "length", None)
|
| some_index = Index("a", "b", mydialect_length=5)
|
| The :meth:`.DialectKWArgs.argument_for` method is a per-argument
| way adding extra arguments to the
| :attr:`.DefaultDialect.construct_arguments` dictionary. This
| dictionary provides a list of argument names accepted by various
| schema-level constructs on behalf of a dialect.
|
| New dialects should typically specify this dictionary all at once as a
| data member of the dialect class. The use case for ad-hoc addition of
| argument names is typically for end-user code that is also using
| a custom compilation scheme which consumes the additional arguments.
|
| :param dialect_name: name of a dialect. The dialect must be
| locatable, else a :class:`.NoSuchModuleError` is raised. The
| dialect must also include an existing
| :attr:`.DefaultDialect.construct_arguments` collection, indicating
| that it participates in the keyword-argument validation and default
| system, else :class:`.ArgumentError` is raised. If the dialect does
| not include this collection, then any keyword argument can be
| specified on behalf of this dialect already. All dialects packaged
| within SQLAlchemy include this collection, however for third party
| dialects, support may vary.
|
| :param argument_name: name of the parameter.
|
| :param default: default value of the parameter.
|
| ----------------------------------------------------------------------
| Readonly properties inherited from sqlalchemy.sql.base.DialectKWArgs:
|
| dialect_kwargs
| A collection of keyword arguments specified as dialect-specific
| options to this construct.
|
| The arguments are present here in their original ``<dialect>_<kwarg>``
| format. Only arguments that were actually passed are included;
| unlike the :attr:`.DialectKWArgs.dialect_options` collection, which
| contains all options known by this dialect including defaults.
|
| The collection is also writable; keys are accepted of the
| form ``<dialect>_<kwarg>`` where the value will be assembled
| into the list of options.
|
| .. seealso::
|
| :attr:`.DialectKWArgs.dialect_options` - nested dictionary form
|
| kwargs
| A synonym for :attr:`.DialectKWArgs.dialect_kwargs`.
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.selectable.HasPrefixes:
|
| prefix_with(self, *prefixes: '_TextCoercedExpressionArgument[Any]', dialect: 'str' = '*') -> 'Self'
| 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.
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.base.Executable:
|
| execution_options(self, **kw: 'Any') -> 'Self'
| Set non-SQL options for the statement which take effect during
| execution.
|
| Execution options can be set at many scopes, including per-statement,
| per-connection, or per execution, using methods such as
| :meth:`_engine.Connection.execution_options` and parameters which
| accept a dictionary of options such as
| :paramref:`_engine.Connection.execute.execution_options` and
| :paramref:`_orm.Session.execute.execution_options`.
|
| The primary characteristic of an execution option, as opposed to
| other kinds of options such as ORM loader options, is that
| **execution options never affect the compiled SQL of a query, only
| things that affect how the SQL statement itself is invoked or how
| results are fetched**. That is, execution options are not part of
| what's accommodated by SQL compilation nor are they considered part of
| the cached state of a statement.
|
| The :meth:`_sql.Executable.execution_options` method is
| :term:`generative`, as
| is the case for the method as applied to the :class:`_engine.Engine`
| and :class:`_orm.Query` objects, which means when the method is called,
| a copy of the object is returned, which applies the given parameters to
| that new copy, but leaves the original unchanged::
|
| statement = select(table.c.x, table.c.y)
| new_statement = statement.execution_options(my_option=True)
|
| An exception to this behavior is the :class:`_engine.Connection`
| object, where the :meth:`_engine.Connection.execution_options` method
| is explicitly **not** generative.
|
| The kinds of options that may be passed to
| :meth:`_sql.Executable.execution_options` and other related methods and
| parameter dictionaries include parameters that are explicitly consumed
| by SQLAlchemy Core or ORM, as well as arbitrary keyword arguments not
| defined by SQLAlchemy, which means the methods and/or parameter
| dictionaries may be used for user-defined parameters that interact with
| custom code, which may access the parameters using methods such as
| :meth:`_sql.Executable.get_execution_options` and
| :meth:`_engine.Connection.get_execution_options`, or within selected
| event hooks using a dedicated ``execution_options`` event parameter
| such as
| :paramref:`_events.ConnectionEvents.before_execute.execution_options`
| or :attr:`_orm.ORMExecuteState.execution_options`, e.g.::
|
| from sqlalchemy import event
|
|
| @event.listens_for(some_engine, "before_execute")
| def _process_opt(conn, statement, multiparams, params, execution_options):
| "run a SQL function before invoking a statement"
|
| if execution_options.get("do_special_thing", False):
| conn.exec_driver_sql("run_special_function()")
|
| Within the scope of options that are explicitly recognized by
| SQLAlchemy, most apply to specific classes of objects and not others.
| The most common execution options include:
|
| * :paramref:`_engine.Connection.execution_options.isolation_level` -
| sets the isolation level for a connection or a class of connections
| via an :class:`_engine.Engine`. This option is accepted only
| by :class:`_engine.Connection` or :class:`_engine.Engine`.
|
| * :paramref:`_engine.Connection.execution_options.stream_results` -
| indicates results should be fetched using a server side cursor;
| this option is accepted by :class:`_engine.Connection`, by the
| :paramref:`_engine.Connection.execute.execution_options` parameter
| on :meth:`_engine.Connection.execute`, and additionally by
| :meth:`_sql.Executable.execution_options` on a SQL statement object,
| as well as by ORM constructs like :meth:`_orm.Session.execute`.
|
| * :paramref:`_engine.Connection.execution_options.compiled_cache` -
| indicates a dictionary that will serve as the
| :ref:`SQL compilation cache <sql_caching>`
| for a :class:`_engine.Connection` or :class:`_engine.Engine`, as
| well as for ORM methods like :meth:`_orm.Session.execute`.
| Can be passed as ``None`` to disable caching for statements.
| This option is not accepted by
| :meth:`_sql.Executable.execution_options` as it is inadvisable to
| carry along a compilation cache within a statement object.
|
| * :paramref:`_engine.Connection.execution_options.schema_translate_map`
| - a mapping of schema names used by the
| :ref:`Schema Translate Map <schema_translating>` feature, accepted
| by :class:`_engine.Connection`, :class:`_engine.Engine`,
| :class:`_sql.Executable`, as well as by ORM constructs
| like :meth:`_orm.Session.execute`.
|
| .. seealso::
|
| :meth:`_engine.Connection.execution_options`
|
| :paramref:`_engine.Connection.execute.execution_options`
|
| :paramref:`_orm.Session.execute.execution_options`
|
| :ref:`orm_queryguide_execution_options` - documentation on all
| ORM-specific execution options
|
| get_execution_options(self) -> '_ExecuteOptions'
| Get the non-SQL options which will take effect during execution.
|
| .. versionadded:: 1.3
|
| .. seealso::
|
| :meth:`.Executable.execution_options`
|
| options(self, *options: 'ExecutableOption') -> 'Self'
| Apply options to this statement.
|
| In the general sense, options are any kind of Python object
| that can be interpreted by the SQL compiler for the statement.
| These options can be consumed by specific dialects or specific kinds
| of compilers.
|
| The most commonly known kind of option are the ORM level options
| that apply "eager load" and other loading behaviors to an ORM
| query. However, options can theoretically be used for many other
| purposes.
|
| For background on specific kinds of options for specific kinds of
| statements, refer to the documentation for those option objects.
|
| .. versionchanged:: 1.4 - added :meth:`.Executable.options` to
| Core statement objects towards the goal of allowing unified
| Core / ORM querying capabilities.
|
| .. seealso::
|
| :ref:`loading_columns` - refers to options specific to the usage
| of ORM queries
|
| :ref:`relationship_loader_options` - refers to options specific
| to the usage of ORM queries
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.base.Executable:
|
| is_delete = False
|
| is_from_statement = False
|
| is_select = False
|
| is_text = False
|
| is_update = False
|
| supports_execution = True
|
| ----------------------------------------------------------------------
| Readonly properties inherited from sqlalchemy.sql.selectable.ReturnsRows:
|
| selectable
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.SQLRole:
|
| allows_lambda = False
|
| uses_inspection = False
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.elements.ClauseElement:
|
| __bool__(self)
|
| __getstate__(self)
| Helper for pickle.
|
| __invert__(self)
|
| __repr__(self)
| Return repr(self).
|
| compare(self, other: 'ClauseElement', **kw: 'Any') -> 'bool'
| Compare this :class:`_expression.ClauseElement` to
| the given :class:`_expression.ClauseElement`.
|
| Subclasses should override the default behavior, which is a
| straight identity comparison.
|
| \**kw are arguments consumed by subclass ``compare()`` methods and
| may be used to modify the criteria for comparison
| (see :class:`_expression.ColumnElement`).
|
| description(...)
|
| entity_namespace(...)
|
| self_group(self, against: 'Optional[OperatorType]' = None) -> 'ClauseElement'
| 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.
|
| unique_params(self, _ClauseElement__optionaldict: 'Optional[Dict[str, Any]]' = None, **kwargs: 'Any') -> 'Self'
| Return a copy with :func:`_expression.bindparam` elements
| replaced.
|
| Same functionality as :meth:`_expression.ClauseElement.params`,
| except adds `unique=True`
| to affected bind parameters so that multiple statements can be
| used.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.elements.ClauseElement:
|
| is_clause_element = True
|
| is_selectable = False
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.cache_key.HasCacheKey:
|
| inherit_cache = None
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_instancemethod(fn: '_F') -> '_F'
| Decorate a method memoize its return value.
|
| :meta private:
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_attribute = <class 'sqlalchemy.util.langhelpers.HasMemoized.m...
| A read-only @property that is only evaluated once.
|
| :meta private:
|
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.visitors.HasTraverseInternals:
|
| get_children(self, *, omit_attrs: 'Tuple[str, ...]' = (), **kw: 'Any') -> 'Iterable[HasTraverseInternals]'
| Return immediate child :class:`.visitors.HasTraverseInternals`
| elements of this :class:`.visitors.HasTraverseInternals`.
|
| This is used for visit traversal.
|
| \**kw may contain flags that change the collection that is
| returned, for example to return a subset of items in order to
| cut down on larger traversals, or to return child items from a
| different context (such as schema-level collections instead of
| clause-level).
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.elements.CompilerElement:
|
| __str__(self) -> 'str'
| Return str(self).
|
| compile(self, bind: 'Optional[_HasDialect]' = None, dialect: 'Optional[Dialect]' = None, **kw: 'Any') -> 'Compiled'
| Compile this SQL expression.
|
| The return value is a :class:`~.Compiled` object.
| Calling ``str()`` or ``unicode()`` on the returned value will yield a
| string representation of the result. The
| :class:`~.Compiled` object also can return a
| dictionary of bind parameter names and values
| using the ``params`` accessor.
|
| :param bind: An :class:`.Connection` or :class:`.Engine` which
| can provide a :class:`.Dialect` in order to generate a
| :class:`.Compiled` object. If the ``bind`` and
| ``dialect`` parameters are both omitted, a default SQL compiler
| is used.
|
| :param column_keys: Used for INSERT and UPDATE statements, a list of
| column names which should be present in the VALUES clause of the
| compiled statement. If ``None``, all columns from the target table
| object are rendered.
|
| :param dialect: A :class:`.Dialect` instance which can generate
| a :class:`.Compiled` object. This argument takes precedence over
| the ``bind`` argument.
|
| :param compile_kwargs: optional dictionary of additional parameters
| that will be passed through to the compiler within all "visit"
| methods. This allows any custom flag to be passed through to
| a custom compilation construct, for example. It is also used
| for the case of passing the ``literal_binds`` flag through::
|
| from sqlalchemy.sql import table, column, select
|
| t = table("t", column("x"))
|
| s = select(t).where(t.c.x == 5)
|
| print(s.compile(compile_kwargs={"literal_binds": True}))
|
| .. seealso::
|
| :ref:`faq_sql_expression_string`
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.elements.CompilerElement:
|
| stringify_dialect = 'default'
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.visitors.Visitable:
|
| __class_getitem__(key: 'Any') -> 'Any'
|
| __init_subclass__() -> 'None'
| This method is called when a class is subclassed.
|
| The default implementation does nothing. It may be
| overridden to extend subclasses.
sqlalchemy.Inspector
Python Library Documentation: class Inspector in module sqlalchemy.engine.reflection
class Inspector(sqlalchemy.inspection.Inspectable)
| Inspector(bind: 'Union[Engine, Connection]')
|
| Performs database schema inspection.
|
| The Inspector acts as a proxy to the reflection methods of the
| :class:`~sqlalchemy.engine.interfaces.Dialect`, providing a
| consistent interface as well as caching support for previously
| fetched metadata.
|
| A :class:`_reflection.Inspector` object is usually created via the
| :func:`_sa.inspect` function, which may be passed an
| :class:`_engine.Engine`
| or a :class:`_engine.Connection`::
|
| from sqlalchemy import inspect, create_engine
|
| engine = create_engine("...")
| insp = inspect(engine)
|
| Where above, the :class:`~sqlalchemy.engine.interfaces.Dialect` associated
| with the engine may opt to return an :class:`_reflection.Inspector`
| subclass that
| provides additional methods specific to the dialect's target database.
|
| Method resolution order:
| Inspector
| sqlalchemy.inspection.Inspectable
| typing.Generic
| builtins.object
|
| Methods defined here:
|
| __init__(self, bind: 'Union[Engine, Connection]')
| Initialize a new :class:`_reflection.Inspector`.
|
| .. deprecated:: 1.4 The __init__() method on :class:`_reflection.Inspector` is deprecated and will be removed in a future release. Please use the :func:`.sqlalchemy.inspect` function on an :class:`_engine.Engine` or :class:`_engine.Connection` in order to acquire an :class:`_reflection.Inspector`.
|
| :param bind: a :class:`~sqlalchemy.engine.Connection`,
| which is typically an instance of
| :class:`~sqlalchemy.engine.Engine` or
| :class:`~sqlalchemy.engine.Connection`.
|
| For a dialect-specific instance of :class:`_reflection.Inspector`, see
| :meth:`_reflection.Inspector.from_engine`
|
| clear_cache(self) -> 'None'
| reset the cache for this :class:`.Inspector`.
|
| Inspection methods that have data cached will emit SQL queries
| when next called to get new data.
|
| .. versionadded:: 2.0
|
| get_check_constraints(self, table_name: 'str', schema: 'Optional[str]' = None, **kw: 'Any') -> 'List[ReflectedCheckConstraint]'
| Return information about check constraints in ``table_name``.
|
| Given a string ``table_name`` and an optional string `schema`, return
| check constraint information as a list of
| :class:`.ReflectedCheckConstraint`.
|
| :param table_name: string name of the table. For special quoting,
| use :class:`.quoted_name`.
|
| :param schema: string schema name; if omitted, uses the default schema
| of the database connection. For special quoting,
| use :class:`.quoted_name`.
|
| :param \**kw: Additional keyword argument to pass to the dialect
| specific implementation. See the documentation of the dialect
| in use for more information.
|
| :return: a list of dictionaries, each representing the
| definition of a check constraints.
|
| .. seealso:: :meth:`Inspector.get_multi_check_constraints`
|
| get_columns(self, table_name: 'str', schema: 'Optional[str]' = None, **kw: 'Any') -> 'List[ReflectedColumn]'
| Return information about columns in ``table_name``.
|
| Given a string ``table_name`` and an optional string ``schema``,
| return column information as a list of :class:`.ReflectedColumn`.
|
| :param table_name: string name of the table. For special quoting,
| use :class:`.quoted_name`.
|
| :param schema: string schema name; if omitted, uses the default schema
| of the database connection. For special quoting,
| use :class:`.quoted_name`.
|
| :param \**kw: Additional keyword argument to pass to the dialect
| specific implementation. See the documentation of the dialect
| in use for more information.
|
| :return: list of dictionaries, each representing the definition of
| a database column.
|
| .. seealso:: :meth:`Inspector.get_multi_columns`.
|
| get_foreign_keys(self, table_name: 'str', schema: 'Optional[str]' = None, **kw: 'Any') -> 'List[ReflectedForeignKeyConstraint]'
| Return information about foreign_keys in ``table_name``.
|
| Given a string ``table_name``, and an optional string `schema`, return
| foreign key information as a list of
| :class:`.ReflectedForeignKeyConstraint`.
|
| :param table_name: string name of the table. For special quoting,
| use :class:`.quoted_name`.
|
| :param schema: string schema name; if omitted, uses the default schema
| of the database connection. For special quoting,
| use :class:`.quoted_name`.
|
| :param \**kw: Additional keyword argument to pass to the dialect
| specific implementation. See the documentation of the dialect
| in use for more information.
|
| :return: a list of dictionaries, each representing the
| a foreign key definition.
|
| .. seealso:: :meth:`Inspector.get_multi_foreign_keys`
|
| get_indexes(self, table_name: 'str', schema: 'Optional[str]' = None, **kw: 'Any') -> 'List[ReflectedIndex]'
| Return information about indexes in ``table_name``.
|
| Given a string ``table_name`` and an optional string `schema`, return
| index information as a list of :class:`.ReflectedIndex`.
|
| :param table_name: string name of the table. For special quoting,
| use :class:`.quoted_name`.
|
| :param schema: string schema name; if omitted, uses the default schema
| of the database connection. For special quoting,
| use :class:`.quoted_name`.
|
| :param \**kw: Additional keyword argument to pass to the dialect
| specific implementation. See the documentation of the dialect
| in use for more information.
|
| :return: a list of dictionaries, each representing the
| definition of an index.
|
| .. seealso:: :meth:`Inspector.get_multi_indexes`
|
| get_materialized_view_names(self, schema: 'Optional[str]' = None, **kw: 'Any') -> 'List[str]'
| Return all materialized view names in `schema`.
|
| :param schema: Optional, retrieve names from a non-default schema.
| For special quoting, use :class:`.quoted_name`.
| :param \**kw: Additional keyword argument to pass to the dialect
| specific implementation. See the documentation of the dialect
| in use for more information.
|
| .. versionadded:: 2.0
|
| .. seealso::
|
| :meth:`.Inspector.get_view_names`
|
| get_multi_check_constraints(self, schema: 'Optional[str]' = None, filter_names: 'Optional[Sequence[str]]' = None, kind: 'ObjectKind' = <ObjectKind.TABLE: 1>, scope: 'ObjectScope' = <ObjectScope.DEFAULT: 1>, **kw: 'Any') -> 'Dict[TableKey, List[ReflectedCheckConstraint]]'
| Return information about check constraints in all tables
| in the given schema.
|
| The tables can be filtered by passing the names to use to
| ``filter_names``.
|
| For each table the value is a list of
| :class:`.ReflectedCheckConstraint`.
|
| :param schema: string schema name; if omitted, uses the default schema
| of the database connection. For special quoting,
| use :class:`.quoted_name`.
|
| :param filter_names: optionally return information only for the
| objects listed here.
|
| :param kind: a :class:`.ObjectKind` that specifies the type of objects
| to reflect. Defaults to ``ObjectKind.TABLE``.
|
| :param scope: a :class:`.ObjectScope` that specifies if constraints of
| default, temporary or any tables should be reflected.
| Defaults to ``ObjectScope.DEFAULT``.
|
| :param \**kw: Additional keyword argument to pass to the dialect
| specific implementation. See the documentation of the dialect
| in use for more information.
|
| :return: a dictionary where the keys are two-tuple schema,table-name
| and the values are list of dictionaries, each representing the
| definition of a check constraints.
| The schema is ``None`` if no schema is provided.
|
| .. versionadded:: 2.0
|
| .. seealso:: :meth:`Inspector.get_check_constraints`
|
| get_multi_columns(self, schema: 'Optional[str]' = None, filter_names: 'Optional[Sequence[str]]' = None, kind: 'ObjectKind' = <ObjectKind.TABLE: 1>, scope: 'ObjectScope' = <ObjectScope.DEFAULT: 1>, **kw: 'Any') -> 'Dict[TableKey, List[ReflectedColumn]]'
| Return information about columns in all objects in the given
| schema.
|
| The objects can be filtered by passing the names to use to
| ``filter_names``.
|
| For each table the value is a list of :class:`.ReflectedColumn`.
|
| :param schema: string schema name; if omitted, uses the default schema
| of the database connection. For special quoting,
| use :class:`.quoted_name`.
|
| :param filter_names: optionally return information only for the
| objects listed here.
|
| :param kind: a :class:`.ObjectKind` that specifies the type of objects
| to reflect. Defaults to ``ObjectKind.TABLE``.
|
| :param scope: a :class:`.ObjectScope` that specifies if columns of
| default, temporary or any tables should be reflected.
| Defaults to ``ObjectScope.DEFAULT``.
|
| :param \**kw: Additional keyword argument to pass to the dialect
| specific implementation. See the documentation of the dialect
| in use for more information.
|
| :return: a dictionary where the keys are two-tuple schema,table-name
| and the values are list of dictionaries, each representing the
| definition of a database column.
| The schema is ``None`` if no schema is provided.
|
| .. versionadded:: 2.0
|
| .. seealso:: :meth:`Inspector.get_columns`
|
| get_multi_foreign_keys(self, schema: 'Optional[str]' = None, filter_names: 'Optional[Sequence[str]]' = None, kind: 'ObjectKind' = <ObjectKind.TABLE: 1>, scope: 'ObjectScope' = <ObjectScope.DEFAULT: 1>, **kw: 'Any') -> 'Dict[TableKey, List[ReflectedForeignKeyConstraint]]'
| Return information about foreign_keys in all tables
| in the given schema.
|
| The tables can be filtered by passing the names to use to
| ``filter_names``.
|
| For each table the value is a list of
| :class:`.ReflectedForeignKeyConstraint`.
|
| :param schema: string schema name; if omitted, uses the default schema
| of the database connection. For special quoting,
| use :class:`.quoted_name`.
|
| :param filter_names: optionally return information only for the
| objects listed here.
|
| :param kind: a :class:`.ObjectKind` that specifies the type of objects
| to reflect. Defaults to ``ObjectKind.TABLE``.
|
| :param scope: a :class:`.ObjectScope` that specifies if foreign keys of
| default, temporary or any tables should be reflected.
| Defaults to ``ObjectScope.DEFAULT``.
|
| :param \**kw: Additional keyword argument to pass to the dialect
| specific implementation. See the documentation of the dialect
| in use for more information.
|
| :return: a dictionary where the keys are two-tuple schema,table-name
| and the values are list of dictionaries, each representing
| a foreign key definition.
| The schema is ``None`` if no schema is provided.
|
| .. versionadded:: 2.0
|
| .. seealso:: :meth:`Inspector.get_foreign_keys`
|
| get_multi_indexes(self, schema: 'Optional[str]' = None, filter_names: 'Optional[Sequence[str]]' = None, kind: 'ObjectKind' = <ObjectKind.TABLE: 1>, scope: 'ObjectScope' = <ObjectScope.DEFAULT: 1>, **kw: 'Any') -> 'Dict[TableKey, List[ReflectedIndex]]'
| Return information about indexes in in all objects
| in the given schema.
|
| The objects can be filtered by passing the names to use to
| ``filter_names``.
|
| For each table the value is a list of :class:`.ReflectedIndex`.
|
| :param schema: string schema name; if omitted, uses the default schema
| of the database connection. For special quoting,
| use :class:`.quoted_name`.
|
| :param filter_names: optionally return information only for the
| objects listed here.
|
| :param kind: a :class:`.ObjectKind` that specifies the type of objects
| to reflect. Defaults to ``ObjectKind.TABLE``.
|
| :param scope: a :class:`.ObjectScope` that specifies if indexes of
| default, temporary or any tables should be reflected.
| Defaults to ``ObjectScope.DEFAULT``.
|
| :param \**kw: Additional keyword argument to pass to the dialect
| specific implementation. See the documentation of the dialect
| in use for more information.
|
| :return: a dictionary where the keys are two-tuple schema,table-name
| and the values are list of dictionaries, each representing the
| definition of an index.
| The schema is ``None`` if no schema is provided.
|
| .. versionadded:: 2.0
|
| .. seealso:: :meth:`Inspector.get_indexes`
|
| get_multi_pk_constraint(self, schema: 'Optional[str]' = None, filter_names: 'Optional[Sequence[str]]' = None, kind: 'ObjectKind' = <ObjectKind.TABLE: 1>, scope: 'ObjectScope' = <ObjectScope.DEFAULT: 1>, **kw: 'Any') -> 'Dict[TableKey, ReflectedPrimaryKeyConstraint]'
| Return information about primary key constraints in
| all tables in the given schema.
|
| The tables can be filtered by passing the names to use to
| ``filter_names``.
|
| For each table the value is a :class:`.ReflectedPrimaryKeyConstraint`.
|
| :param schema: string schema name; if omitted, uses the default schema
| of the database connection. For special quoting,
| use :class:`.quoted_name`.
|
| :param filter_names: optionally return information only for the
| objects listed here.
|
| :param kind: a :class:`.ObjectKind` that specifies the type of objects
| to reflect. Defaults to ``ObjectKind.TABLE``.
|
| :param scope: a :class:`.ObjectScope` that specifies if primary keys of
| default, temporary or any tables should be reflected.
| Defaults to ``ObjectScope.DEFAULT``.
|
| :param \**kw: Additional keyword argument to pass to the dialect
| specific implementation. See the documentation of the dialect
| in use for more information.
|
| :return: a dictionary where the keys are two-tuple schema,table-name
| and the values are dictionaries, each representing the
| definition of a primary key constraint.
| The schema is ``None`` if no schema is provided.
|
| .. versionadded:: 2.0
|
| .. seealso:: :meth:`Inspector.get_pk_constraint`
|
| get_multi_table_comment(self, schema: 'Optional[str]' = None, filter_names: 'Optional[Sequence[str]]' = None, kind: 'ObjectKind' = <ObjectKind.TABLE: 1>, scope: 'ObjectScope' = <ObjectScope.DEFAULT: 1>, **kw: 'Any') -> 'Dict[TableKey, ReflectedTableComment]'
| Return information about the table comment in all objects
| in the given schema.
|
| The objects can be filtered by passing the names to use to
| ``filter_names``.
|
| For each table the value is a :class:`.ReflectedTableComment`.
|
| Raises ``NotImplementedError`` for a dialect that does not support
| comments.
|
| :param schema: string schema name; if omitted, uses the default schema
| of the database connection. For special quoting,
| use :class:`.quoted_name`.
|
| :param filter_names: optionally return information only for the
| objects listed here.
|
| :param kind: a :class:`.ObjectKind` that specifies the type of objects
| to reflect. Defaults to ``ObjectKind.TABLE``.
|
| :param scope: a :class:`.ObjectScope` that specifies if comments of
| default, temporary or any tables should be reflected.
| Defaults to ``ObjectScope.DEFAULT``.
|
| :param \**kw: Additional keyword argument to pass to the dialect
| specific implementation. See the documentation of the dialect
| in use for more information.
|
| :return: a dictionary where the keys are two-tuple schema,table-name
| and the values are dictionaries, representing the
| table comments.
| The schema is ``None`` if no schema is provided.
|
| .. versionadded:: 2.0
|
| .. seealso:: :meth:`Inspector.get_table_comment`
|
| get_multi_table_options(self, schema: 'Optional[str]' = None, filter_names: 'Optional[Sequence[str]]' = None, kind: 'ObjectKind' = <ObjectKind.TABLE: 1>, scope: 'ObjectScope' = <ObjectScope.DEFAULT: 1>, **kw: 'Any') -> 'Dict[TableKey, Dict[str, Any]]'
| Return a dictionary of options specified when the tables in the
| given schema were created.
|
| The tables can be filtered by passing the names to use to
| ``filter_names``.
|
| This currently includes some options that apply to MySQL and Oracle
| tables.
|
| :param schema: string schema name; if omitted, uses the default schema
| of the database connection. For special quoting,
| use :class:`.quoted_name`.
|
| :param filter_names: optionally return information only for the
| objects listed here.
|
| :param kind: a :class:`.ObjectKind` that specifies the type of objects
| to reflect. Defaults to ``ObjectKind.TABLE``.
|
| :param scope: a :class:`.ObjectScope` that specifies if options of
| default, temporary or any tables should be reflected.
| Defaults to ``ObjectScope.DEFAULT``.
|
| :param \**kw: Additional keyword argument to pass to the dialect
| specific implementation. See the documentation of the dialect
| in use for more information.
|
| :return: a dictionary where the keys are two-tuple schema,table-name
| and the values are dictionaries with the table options.
| The returned keys in each dict depend on the
| dialect in use. Each one is prefixed with the dialect name.
| The schema is ``None`` if no schema is provided.
|
| .. versionadded:: 2.0
|
| .. seealso:: :meth:`Inspector.get_table_options`
|
| get_multi_unique_constraints(self, schema: 'Optional[str]' = None, filter_names: 'Optional[Sequence[str]]' = None, kind: 'ObjectKind' = <ObjectKind.TABLE: 1>, scope: 'ObjectScope' = <ObjectScope.DEFAULT: 1>, **kw: 'Any') -> 'Dict[TableKey, List[ReflectedUniqueConstraint]]'
| Return information about unique constraints in all tables
| in the given schema.
|
| The tables can be filtered by passing the names to use to
| ``filter_names``.
|
| For each table the value is a list of
| :class:`.ReflectedUniqueConstraint`.
|
| :param schema: string schema name; if omitted, uses the default schema
| of the database connection. For special quoting,
| use :class:`.quoted_name`.
|
| :param filter_names: optionally return information only for the
| objects listed here.
|
| :param kind: a :class:`.ObjectKind` that specifies the type of objects
| to reflect. Defaults to ``ObjectKind.TABLE``.
|
| :param scope: a :class:`.ObjectScope` that specifies if constraints of
| default, temporary or any tables should be reflected.
| Defaults to ``ObjectScope.DEFAULT``.
|
| :param \**kw: Additional keyword argument to pass to the dialect
| specific implementation. See the documentation of the dialect
| in use for more information.
|
| :return: a dictionary where the keys are two-tuple schema,table-name
| and the values are list of dictionaries, each representing the
| definition of an unique constraint.
| The schema is ``None`` if no schema is provided.
|
| .. versionadded:: 2.0
|
| .. seealso:: :meth:`Inspector.get_unique_constraints`
|
| get_pk_constraint(self, table_name: 'str', schema: 'Optional[str]' = None, **kw: 'Any') -> 'ReflectedPrimaryKeyConstraint'
| Return information about primary key constraint in ``table_name``.
|
| Given a string ``table_name``, and an optional string `schema`, return
| primary key information as a :class:`.ReflectedPrimaryKeyConstraint`.
|
| :param table_name: string name of the table. For special quoting,
| use :class:`.quoted_name`.
|
| :param schema: string schema name; if omitted, uses the default schema
| of the database connection. For special quoting,
| use :class:`.quoted_name`.
|
| :param \**kw: Additional keyword argument to pass to the dialect
| specific implementation. See the documentation of the dialect
| in use for more information.
|
| :return: a dictionary representing the definition of
| a primary key constraint.
|
| .. seealso:: :meth:`Inspector.get_multi_pk_constraint`
|
| get_schema_names(self, **kw: 'Any') -> 'List[str]'
| Return all schema names.
|
| :param \**kw: Additional keyword argument to pass to the dialect
| specific implementation. See the documentation of the dialect
| in use for more information.
|
| get_sequence_names(self, schema: 'Optional[str]' = None, **kw: 'Any') -> 'List[str]'
| Return all sequence names in `schema`.
|
| :param schema: Optional, retrieve names from a non-default schema.
| For special quoting, use :class:`.quoted_name`.
| :param \**kw: Additional keyword argument to pass to the dialect
| specific implementation. See the documentation of the dialect
| in use for more information.
|
| get_sorted_table_and_fkc_names(self, schema: 'Optional[str]' = None, **kw: 'Any') -> 'List[Tuple[Optional[str], List[Tuple[str, Optional[str]]]]]'
| Return dependency-sorted table and foreign key constraint names in
| referred to within a particular schema.
|
| This will yield 2-tuples of
| ``(tablename, [(tname, fkname), (tname, fkname), ...])``
| consisting of table names in CREATE order grouped with the foreign key
| constraint names that are not detected as belonging to a cycle.
| The final element
| will be ``(None, [(tname, fkname), (tname, fkname), ..])``
| which will consist of remaining
| foreign key constraint names that would require a separate CREATE
| step after-the-fact, based on dependencies between tables.
|
| :param schema: schema name to query, if not the default schema.
| :param \**kw: Additional keyword argument to pass to the dialect
| specific implementation. See the documentation of the dialect
| in use for more information.
|
| .. seealso::
|
| :meth:`_reflection.Inspector.get_table_names`
|
| :func:`.sort_tables_and_constraints` - similar method which works
| with an already-given :class:`_schema.MetaData`.
|
| get_table_comment(self, table_name: 'str', schema: 'Optional[str]' = None, **kw: 'Any') -> 'ReflectedTableComment'
| Return information about the table comment for ``table_name``.
|
| Given a string ``table_name`` and an optional string ``schema``,
| return table comment information as a :class:`.ReflectedTableComment`.
|
| Raises ``NotImplementedError`` for a dialect that does not support
| comments.
|
| :param table_name: string name of the table. For special quoting,
| use :class:`.quoted_name`.
|
| :param schema: string schema name; if omitted, uses the default schema
| of the database connection. For special quoting,
| use :class:`.quoted_name`.
|
| :param \**kw: Additional keyword argument to pass to the dialect
| specific implementation. See the documentation of the dialect
| in use for more information.
|
| :return: a dictionary, with the table comment.
|
| .. versionadded:: 1.2
|
| .. seealso:: :meth:`Inspector.get_multi_table_comment`
|
| get_table_names(self, schema: 'Optional[str]' = None, **kw: 'Any') -> 'List[str]'
| Return all table names within a particular schema.
|
| The names are expected to be real tables only, not views.
| Views are instead returned using the
| :meth:`_reflection.Inspector.get_view_names` and/or
| :meth:`_reflection.Inspector.get_materialized_view_names`
| methods.
|
| :param schema: Schema name. If ``schema`` is left at ``None``, the
| database's default schema is
| used, else the named schema is searched. If the database does not
| support named schemas, behavior is undefined if ``schema`` is not
| passed as ``None``. For special quoting, use :class:`.quoted_name`.
| :param \**kw: Additional keyword argument to pass to the dialect
| specific implementation. See the documentation of the dialect
| in use for more information.
|
| .. seealso::
|
| :meth:`_reflection.Inspector.get_sorted_table_and_fkc_names`
|
| :attr:`_schema.MetaData.sorted_tables`
|
| get_table_options(self, table_name: 'str', schema: 'Optional[str]' = None, **kw: 'Any') -> 'Dict[str, Any]'
| Return a dictionary of options specified when the table of the
| given name was created.
|
| This currently includes some options that apply to MySQL and Oracle
| Database tables.
|
| :param table_name: string name of the table. For special quoting,
| use :class:`.quoted_name`.
|
| :param schema: string schema name; if omitted, uses the default schema
| of the database connection. For special quoting,
| use :class:`.quoted_name`.
|
| :param \**kw: Additional keyword argument to pass to the dialect
| specific implementation. See the documentation of the dialect
| in use for more information.
|
| :return: a dict with the table options. The returned keys depend on the
| dialect in use. Each one is prefixed with the dialect name.
|
| .. seealso:: :meth:`Inspector.get_multi_table_options`
|
| get_temp_table_names(self, **kw: 'Any') -> 'List[str]'
| Return a list of temporary table names for the current bind.
|
| This method is unsupported by most dialects; currently
| only Oracle Database, PostgreSQL and SQLite implements it.
|
| :param \**kw: Additional keyword argument to pass to the dialect
| specific implementation. See the documentation of the dialect
| in use for more information.
|
| get_temp_view_names(self, **kw: 'Any') -> 'List[str]'
| Return a list of temporary view names for the current bind.
|
| This method is unsupported by most dialects; currently
| only PostgreSQL and SQLite implements it.
|
| :param \**kw: Additional keyword argument to pass to the dialect
| specific implementation. See the documentation of the dialect
| in use for more information.
|
| get_unique_constraints(self, table_name: 'str', schema: 'Optional[str]' = None, **kw: 'Any') -> 'List[ReflectedUniqueConstraint]'
| Return information about unique constraints in ``table_name``.
|
| Given a string ``table_name`` and an optional string `schema`, return
| unique constraint information as a list of
| :class:`.ReflectedUniqueConstraint`.
|
| :param table_name: string name of the table. For special quoting,
| use :class:`.quoted_name`.
|
| :param schema: string schema name; if omitted, uses the default schema
| of the database connection. For special quoting,
| use :class:`.quoted_name`.
|
| :param \**kw: Additional keyword argument to pass to the dialect
| specific implementation. See the documentation of the dialect
| in use for more information.
|
| :return: a list of dictionaries, each representing the
| definition of an unique constraint.
|
| .. seealso:: :meth:`Inspector.get_multi_unique_constraints`
|
| get_view_definition(self, view_name: 'str', schema: 'Optional[str]' = None, **kw: 'Any') -> 'str'
| Return definition for the plain or materialized view called
| ``view_name``.
|
| :param view_name: Name of the view.
| :param schema: Optional, retrieve names from a non-default schema.
| For special quoting, use :class:`.quoted_name`.
| :param \**kw: Additional keyword argument to pass to the dialect
| specific implementation. See the documentation of the dialect
| in use for more information.
|
| get_view_names(self, schema: 'Optional[str]' = None, **kw: 'Any') -> 'List[str]'
| Return all non-materialized view names in `schema`.
|
| :param schema: Optional, retrieve names from a non-default schema.
| For special quoting, use :class:`.quoted_name`.
| :param \**kw: Additional keyword argument to pass to the dialect
| specific implementation. See the documentation of the dialect
| in use for more information.
|
|
| .. versionchanged:: 2.0 For those dialects that previously included
| the names of materialized views in this list (currently PostgreSQL),
| this method no longer returns the names of materialized views.
| the :meth:`.Inspector.get_materialized_view_names` method should
| be used instead.
|
| .. seealso::
|
| :meth:`.Inspector.get_materialized_view_names`
|
| has_index(self, table_name: 'str', index_name: 'str', schema: 'Optional[str]' = None, **kw: 'Any') -> 'bool'
| Check the existence of a particular index name in the database.
|
| :param table_name: the name of the table the index belongs to
| :param index_name: the name of the index to check
| :param schema: schema name to query, if not the default schema.
| :param \**kw: Additional keyword argument to pass to the dialect
| specific implementation. See the documentation of the dialect
| in use for more information.
|
| .. versionadded:: 2.0
|
| has_schema(self, schema_name: 'str', **kw: 'Any') -> 'bool'
| Return True if the backend has a schema with the given name.
|
| :param schema_name: name of the schema to check
| :param \**kw: Additional keyword argument to pass to the dialect
| specific implementation. See the documentation of the dialect
| in use for more information.
|
| .. versionadded:: 2.0
|
| has_sequence(self, sequence_name: 'str', schema: 'Optional[str]' = None, **kw: 'Any') -> 'bool'
| Return True if the backend has a sequence with the given name.
|
| :param sequence_name: name of the sequence to check
| :param schema: schema name to query, if not the default schema.
| :param \**kw: Additional keyword argument to pass to the dialect
| specific implementation. See the documentation of the dialect
| in use for more information.
|
| .. versionadded:: 1.4
|
| has_table(self, table_name: 'str', schema: 'Optional[str]' = None, **kw: 'Any') -> 'bool'
| Return True if the backend has a table, view, or temporary
| table of the given name.
|
| :param table_name: name of the table to check
| :param schema: schema name to query, if not the default schema.
| :param \**kw: Additional keyword argument to pass to the dialect
| specific implementation. See the documentation of the dialect
| in use for more information.
|
| .. versionadded:: 1.4 - the :meth:`.Inspector.has_table` method
| replaces the :meth:`_engine.Engine.has_table` method.
|
| .. versionchanged:: 2.0:: :meth:`.Inspector.has_table` now formally
| supports checking for additional table-like objects:
|
| * any type of views (plain or materialized)
| * temporary tables of any kind
|
| Previously, these two checks were not formally specified and
| different dialects would vary in their behavior. The dialect
| testing suite now includes tests for all of these object types
| and should be supported by all SQLAlchemy-included dialects.
| Support among third party dialects may be lagging, however.
|
| reflect_table(self, table: 'sa_schema.Table', include_columns: 'Optional[Collection[str]]', exclude_columns: 'Collection[str]' = (), resolve_fks: 'bool' = True, _extend_on: 'Optional[Set[sa_schema.Table]]' = None, _reflect_info: 'Optional[_ReflectionInfo]' = None) -> 'None'
| Given a :class:`_schema.Table` object, load its internal
| constructs based on introspection.
|
| This is the underlying method used by most dialects to produce
| table reflection. Direct usage is like::
|
| from sqlalchemy import create_engine, MetaData, Table
| from sqlalchemy import inspect
|
| engine = create_engine("...")
| meta = MetaData()
| user_table = Table("user", meta)
| insp = inspect(engine)
| insp.reflect_table(user_table, None)
|
| .. versionchanged:: 1.4 Renamed from ``reflecttable`` to
| ``reflect_table``
|
| :param table: a :class:`~sqlalchemy.schema.Table` instance.
| :param include_columns: a list of string column names to include
| in the reflection process. If ``None``, all columns are reflected.
|
| sort_tables_on_foreign_key_dependency(self, consider_schemas: 'Collection[Optional[str]]' = (None,), **kw: 'Any') -> 'List[Tuple[Optional[Tuple[Optional[str], str]], List[Tuple[Tuple[Optional[str], str], Optional[str]]]]]'
| Return dependency-sorted table and foreign key constraint names
| referred to within multiple schemas.
|
| This method may be compared to
| :meth:`.Inspector.get_sorted_table_and_fkc_names`, which
| works on one schema at a time; here, the method is a generalization
| that will consider multiple schemas at once including that it will
| resolve for cross-schema foreign keys.
|
| .. versionadded:: 2.0
|
| ----------------------------------------------------------------------
| Class methods defined here:
|
| from_engine(bind: 'Engine') -> 'Inspector'
| Construct a new dialect-specific Inspector object from the given
| engine or connection.
|
| .. deprecated:: 1.4 The from_engine() method on :class:`_reflection.Inspector` is deprecated and will be removed in a future release. Please use the :func:`.sqlalchemy.inspect` function on an :class:`_engine.Engine` or :class:`_engine.Connection` in order to acquire an :class:`_reflection.Inspector`.
|
| :param bind: a :class:`~sqlalchemy.engine.Connection`
| or :class:`~sqlalchemy.engine.Engine`.
|
| This method differs from direct a direct constructor call of
| :class:`_reflection.Inspector` in that the
| :class:`~sqlalchemy.engine.interfaces.Dialect` is given a chance to
| provide a dialect-specific :class:`_reflection.Inspector` instance,
| which may
| provide additional methods.
|
| See the example at :class:`_reflection.Inspector`.
|
| ----------------------------------------------------------------------
| Readonly properties defined here:
|
| default_schema_name
| Return the default schema name presented by the dialect
| for the current engine's database user.
|
| E.g. this is typically ``public`` for PostgreSQL and ``dbo``
| for SQL Server.
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'_op_context_requires_connect': 'bool', 'bind': 'Un...
|
| __orig_bases__ = (sqlalchemy.inspection.Inspectable[ForwardRef('Inspec...
|
| __parameters__ = ()
|
| ----------------------------------------------------------------------
| Class methods inherited from typing.Generic:
|
| __class_getitem__(...)
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__(...)
| Function to initialize subclasses.
sqlalchemy.Integer
Python Library Documentation: class Integer in module sqlalchemy.sql.sqltypes
class Integer(HasExpressionLookup, sqlalchemy.sql.type_api.TypeEngine)
| A type for ``int`` integers.
|
| Method resolution order:
| Integer
| HasExpressionLookup
| sqlalchemy.sql.type_api.TypeEngineMixin
| sqlalchemy.sql.type_api.TypeEngine
| sqlalchemy.sql.visitors.Visitable
| typing.Generic
| builtins.object
|
| Methods defined here:
|
| get_dbapi_type(self, dbapi)
| Return the corresponding type object from the underlying DB-API, if
| any.
|
| This can be useful for calling ``setinputsizes()``, for example.
|
| literal_processor(self, dialect)
| Return a conversion function for processing literal values that are
| to be rendered directly without using binds.
|
| This function is used when the compiler makes use of the
| "literal_binds" flag, typically used in DDL generation as well
| as in certain scenarios where backends don't accept bound parameters.
|
| Returns a callable which will receive a literal Python value
| as the sole positional argument and will return a string representation
| to be rendered in a SQL statement.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.literal_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.literal_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_literal_param`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| ----------------------------------------------------------------------
| Readonly properties defined here:
|
| python_type
| Return the Python type object expected to be returned
| by instances of this type, if known.
|
| Basically, for those types which enforce a return type,
| or are known across the board to do such for all common
| DBAPIs (like ``int`` for example), will return that type.
|
| If a return type is not defined, raises
| ``NotImplementedError``.
|
| Note that any type also accommodates NULL in SQL which
| means you can also get back ``None`` from any type
| in practice.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| __parameters__ = ()
|
| __visit_name__ = 'integer'
|
| ----------------------------------------------------------------------
| Data descriptors inherited from HasExpressionLookup:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from HasExpressionLookup:
|
| Comparator = <class 'sqlalchemy.sql.sqltypes.HasExpressionLookup.Compa...
|
| comparator_factory = <class 'sqlalchemy.sql.sqltypes.HasExpressionLook...
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.type_api.TypeEngine:
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| __str__(self) -> 'str'
| Return str(self).
|
| adapt(self, cls: 'Type[Union[TypeEngine[Any], TypeEngineMixin]]', **kw: 'Any') -> 'TypeEngine[Any]'
| Produce an "adapted" form of this type, given an "impl" class
| to work with.
|
| This method is used internally to associate generic
| types with "implementation" types that are specific to a particular
| dialect.
|
| as_generic(self, allow_nulltype: 'bool' = False) -> 'TypeEngine[_T]'
| Return an instance of the generic type corresponding to this type
| using heuristic rule. The method may be overridden if this
| heuristic rule is not sufficient.
|
| >>> from sqlalchemy.dialects.mysql import INTEGER
| >>> INTEGER(display_width=4).as_generic()
| Integer()
|
| >>> from sqlalchemy.dialects.mysql import NVARCHAR
| >>> NVARCHAR(length=100).as_generic()
| Unicode(length=100)
|
| .. versionadded:: 1.4.0b2
|
|
| .. seealso::
|
| :ref:`metadata_reflection_dbagnostic_types` - describes the
| use of :meth:`_types.TypeEngine.as_generic` in conjunction with
| the :meth:`_sql.DDLEvents.column_reflect` event, which is its
| intended use.
|
| bind_expression(self, bindvalue: 'BindParameter[_T]') -> 'Optional[ColumnElement[_T]]'
| Given a bind value (i.e. a :class:`.BindParameter` instance),
| return a SQL expression in its place.
|
| This is typically a SQL function that wraps the existing bound
| parameter within the statement. It is used for special data types
| that require literals being wrapped in some special database function
| in order to coerce an application-level value into a database-specific
| format. It is the SQL analogue of the
| :meth:`.TypeEngine.bind_processor` method.
|
| This method is called during the **SQL compilation** phase of a
| statement, when rendering a SQL string. It is **not** called
| against specific values.
|
| Note that this method, when implemented, should always return
| the exact same structure, without any conditional logic, as it
| may be used in an executemany() call against an arbitrary number
| of bound parameter sets.
|
| .. note::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.bind_expression`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.bind_expression`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.bind_expression`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| .. seealso::
|
| :ref:`types_sql_value_processing`
|
| bind_processor(self, dialect: 'Dialect') -> 'Optional[_BindProcessorType[_T]]'
| Return a conversion function for processing bind values.
|
| Returns a callable which will receive a bind parameter value
| as the sole positional argument and will return a value to
| send to the DB-API.
|
| If processing is not necessary, the method should return ``None``.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.bind_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.bind_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_bind_param`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
|
| :param dialect: Dialect instance in use.
|
| coerce_compared_value(self, op: 'Optional[OperatorType]', value: 'Any') -> 'TypeEngine[Any]'
| Suggest a type for a 'coerced' Python value in an expression.
|
| Given an operator and value, gives the type a chance
| to return a type which the value should be coerced into.
|
| The default behavior here is conservative; if the right-hand
| side is already coerced into a SQL type based on its
| Python type, it is usually left alone.
|
| End-user functionality extension here should generally be via
| :class:`.TypeDecorator`, which provides more liberal behavior in that
| it defaults to coercing the other side of the expression into this
| type, thus applying special Python conversions above and beyond those
| needed by the DBAPI to both ides. It also provides the public method
| :meth:`.TypeDecorator.coerce_compared_value` which is intended for
| end-user customization of this behavior.
|
| column_expression(self, colexpr: 'ColumnElement[_T]') -> 'Optional[ColumnElement[_T]]'
| Given a SELECT column expression, return a wrapping SQL expression.
|
| This is typically a SQL function that wraps a column expression
| as rendered in the columns clause of a SELECT statement.
| It is used for special data types that require
| columns to be wrapped in some special database function in order
| to coerce the value before being sent back to the application.
| It is the SQL analogue of the :meth:`.TypeEngine.result_processor`
| method.
|
| .. note:: The :func:`.TypeEngine.column_expression` method is applied
| only to the **outermost columns clause** of a SELECT statement, that
| is, the columns that are to be delivered directly into the returned
| result rows. It does **not** apply to the columns clause inside
| of subqueries. This necessarily avoids double conversions against
| the column and only runs the conversion when ready to be returned
| to the client.
|
| This method is called during the **SQL compilation** phase of a
| statement, when rendering a SQL string. It is **not** called
| against specific values.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.column_expression`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.column_expression`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.column_expression`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
|
| .. seealso::
|
| :ref:`types_sql_value_processing`
|
| compare_values(self, x: 'Any', y: 'Any') -> 'bool'
| Compare two values for equality.
|
| compile(self, dialect: 'Optional[Dialect]' = None) -> 'str'
| Produce a string-compiled form of this :class:`.TypeEngine`.
|
| When called with no arguments, uses a "default" dialect
| to produce a string result.
|
| :param dialect: a :class:`.Dialect` instance.
|
| copy(self, **kw: 'Any') -> 'Self'
|
| copy_value(self, value: 'Any') -> 'Any'
|
| dialect_impl(self, dialect: 'Dialect') -> 'TypeEngine[_T]'
| Return a dialect-specific implementation for this
| :class:`.TypeEngine`.
|
| evaluates_none(self) -> 'Self'
| Return a copy of this type which has the
| :attr:`.should_evaluate_none` flag set to True.
|
| E.g.::
|
| Table(
| "some_table",
| metadata,
| Column(
| String(50).evaluates_none(),
| nullable=True,
| server_default="no value",
| ),
| )
|
| The ORM uses this flag to indicate that a positive value of ``None``
| is passed to the column in an INSERT statement, rather than omitting
| the column from the INSERT statement which has the effect of firing
| off column-level defaults. It also allows for types which have
| special behavior associated with the Python None value to indicate
| that the value doesn't necessarily translate into SQL NULL; a
| prime example of this is a JSON type which may wish to persist the
| JSON value ``'null'``.
|
| In all cases, the actual NULL SQL value can be always be
| persisted in any column by using
| the :obj:`_expression.null` SQL construct in an INSERT statement
| or associated with an ORM-mapped attribute.
|
| .. note::
|
| The "evaluates none" flag does **not** apply to a value
| of ``None`` passed to :paramref:`_schema.Column.default` or
| :paramref:`_schema.Column.server_default`; in these cases,
| ``None``
| still means "no default".
|
| .. seealso::
|
| :ref:`session_forcing_null` - in the ORM documentation
|
| :paramref:`.postgresql.JSON.none_as_null` - PostgreSQL JSON
| interaction with this flag.
|
| :attr:`.TypeEngine.should_evaluate_none` - class-level flag
|
| result_processor(self, dialect: 'Dialect', coltype: 'object') -> 'Optional[_ResultProcessorType[_T]]'
| Return a conversion function for processing result row values.
|
| Returns a callable which will receive a result row column
| value as the sole positional argument and will return a value
| to return to the user.
|
| If processing is not necessary, the method should return ``None``.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.result_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.result_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_result_value`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| :param dialect: Dialect instance in use.
|
| :param coltype: DBAPI coltype argument received in cursor.description.
|
| with_variant(self, type_: '_TypeEngineArgument[Any]', *dialect_names: 'str') -> 'Self'
| Produce a copy of this type object that will utilize the given
| type when applied to the dialect of the given name.
|
| e.g.::
|
| from sqlalchemy.types import String
| from sqlalchemy.dialects import mysql
|
| string_type = String()
|
| string_type = string_type.with_variant(
| mysql.VARCHAR(collation="foo"), "mysql", "mariadb"
| )
|
| The variant mapping indicates that when this type is
| interpreted by a specific dialect, it will instead be
| transmuted into the given type, rather than using the
| primary type.
|
| .. versionchanged:: 2.0 the :meth:`_types.TypeEngine.with_variant`
| method now works with a :class:`_types.TypeEngine` object "in
| place", returning a copy of the original type rather than returning
| a wrapping object; the ``Variant`` class is no longer used.
|
| :param type\_: a :class:`.TypeEngine` that will be selected
| as a variant from the originating type, when a dialect
| of the given name is in use.
| :param \*dialect_names: one or more base names of the dialect which
| uses this type. (i.e. ``'postgresql'``, ``'mysql'``, etc.)
|
| .. versionchanged:: 2.0 multiple dialect names can be specified
| for one variant.
|
| .. seealso::
|
| :ref:`types_with_variant` - illustrates the use of
| :meth:`_types.TypeEngine.with_variant`.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.type_api.TypeEngine:
|
| __orig_bases__ = (<class 'sqlalchemy.sql.visitors.Visitable'>, typing....
|
| hashable = True
|
| render_bind_cast = False
|
| render_literal_cast = False
|
| should_evaluate_none = False
|
| sort_key_function = None
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.visitors.Visitable:
|
| __class_getitem__(key: 'Any') -> 'Any'
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__() -> 'None'
| This method is called when a class is subclassed.
|
| The default implementation does nothing. It may be
| overridden to extend subclasses.
sqlalchemy.Interval
Python Library Documentation: class Interval in module sqlalchemy.sql.sqltypes
class Interval(sqlalchemy.sql.type_api.Emulated, _AbstractInterval, sqlalchemy.sql.type_api.TypeDecorator)
| Interval(native: 'bool' = True, second_precision: 'Optional[int]' = None, day_precision: 'Optional[int]' = None)
|
| A type for ``datetime.timedelta()`` objects.
|
| The Interval type deals with ``datetime.timedelta`` objects. In PostgreSQL
| and Oracle Database, the native ``INTERVAL`` type is used; for others, the
| value is stored as a date which is relative to the "epoch" (Jan. 1, 1970).
|
| Note that the ``Interval`` type does not currently provide date arithmetic
| operations on platforms which do not support interval types natively. Such
| operations usually require transformation of both sides of the expression
| (such as, conversion of both sides into integer epoch values first) which
| currently is a manual procedure (such as via
| :attr:`~sqlalchemy.sql.expression.func`).
|
| Method resolution order:
| Interval
| sqlalchemy.sql.type_api.Emulated
| _AbstractInterval
| HasExpressionLookup
| sqlalchemy.sql.type_api.TypeDecorator
| sqlalchemy.sql.base.SchemaEventTarget
| sqlalchemy.event.registry.EventTarget
| sqlalchemy.sql.type_api.ExternalType
| sqlalchemy.sql.type_api.TypeEngineMixin
| sqlalchemy.sql.type_api.TypeEngine
| sqlalchemy.sql.visitors.Visitable
| typing.Generic
| builtins.object
|
| Methods defined here:
|
| __init__(self, native: 'bool' = True, second_precision: 'Optional[int]' = None, day_precision: 'Optional[int]' = None)
| Construct an Interval object.
|
| :param native: when True, use the actual
| INTERVAL type provided by the database, if
| supported (currently PostgreSQL, Oracle Database).
| Otherwise, represent the interval data as
| an epoch value regardless.
|
| :param second_precision: For native interval types
| which support a "fractional seconds precision" parameter,
| i.e. Oracle Database and PostgreSQL
|
| :param day_precision: for native interval types which
| support a "day precision" parameter, i.e. Oracle Database.
|
| adapt_to_emulated(self, impltype, **kw)
| Given an impl class, adapt this type to the impl assuming
| "emulated".
|
| The impl should also be an "emulated" version of this type,
| most likely the same class as this type itself.
|
| e.g.: sqltypes.Enum adapts to the Enum class.
|
| bind_processor(self, dialect: 'Dialect') -> '_BindProcessorType[dt.timedelta]'
| Return a conversion function for processing bind values.
|
| Returns a callable which will receive a bind parameter value
| as the sole positional argument and will return a value to
| send to the DB-API.
|
| If processing is not necessary, the method should return ``None``.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.bind_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.bind_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_bind_param`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
|
| :param dialect: Dialect instance in use.
|
| coerce_compared_value(self, op, value)
| Suggest a type for a 'coerced' Python value in an expression.
|
| Given an operator and value, gives the type a chance
| to return a type which the value should be coerced into.
|
| The default behavior here is conservative; if the right-hand
| side is already coerced into a SQL type based on its
| Python type, it is usually left alone.
|
| End-user functionality extension here should generally be via
| :class:`.TypeDecorator`, which provides more liberal behavior in that
| it defaults to coercing the other side of the expression into this
| type, thus applying special Python conversions above and beyond those
| needed by the DBAPI to both ides. It also provides the public method
| :meth:`.TypeDecorator.coerce_compared_value` which is intended for
| end-user customization of this behavior.
|
| result_processor(self, dialect: 'Dialect', coltype: 'Any') -> '_ResultProcessorType[dt.timedelta]'
| Return a conversion function for processing result row values.
|
| Returns a callable which will receive a result row column
| value as the sole positional argument and will return a value
| to return to the user.
|
| If processing is not necessary, the method should return ``None``.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.result_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.result_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_result_value`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| :param dialect: Dialect instance in use.
|
| :param coltype: DBAPI coltype argument received in cursor.description.
|
| ----------------------------------------------------------------------
| Readonly properties defined here:
|
| python_type
| Return the Python type object expected to be returned
| by instances of this type, if known.
|
| Basically, for those types which enforce a return type,
| or are known across the board to do such for all common
| DBAPIs (like ``int`` for example), will return that type.
|
| If a return type is not defined, raises
| ``NotImplementedError``.
|
| Note that any type also accommodates NULL in SQL which
| means you can also get back ``None`` from any type
| in practice.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| Comparator = <class 'sqlalchemy.sql.sqltypes.Interval.Comparator'>
|
| __annotations__ = {}
|
| __parameters__ = ()
|
| cache_ok = True
|
| comparator_factory = <class 'sqlalchemy.sql.sqltypes.Interval.Comparat...
|
| epoch = datetime.datetime(1970, 1, 1, 0, 0)
|
| impl = <class 'sqlalchemy.sql.sqltypes.DateTime'>
| A type for ``datetime.datetime()`` objects.
|
| Date and time types return objects from the Python ``datetime``
| module. Most DBAPIs have built in support for the datetime
| module, with the noted exception of SQLite. In the case of
| SQLite, date and time types are stored as strings which are then
| converted back to datetime objects when rows are returned.
|
| For the time representation within the datetime type, some
| backends include additional options, such as timezone support and
| fractional seconds support. For fractional seconds, use the
| dialect-specific datatype, such as :class:`.mysql.TIME`. For
| timezone support, use at least the :class:`_types.TIMESTAMP` datatype,
| if not the dialect-specific datatype object.
|
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.type_api.Emulated:
|
| adapt(self, cls: 'Type[Union[TypeEngine[Any], TypeEngineMixin]]', **kw: 'Any') -> 'TypeEngine[Any]'
|
| ----------------------------------------------------------------------
| Data descriptors inherited from sqlalchemy.sql.type_api.Emulated:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.type_api.TypeDecorator:
|
| __getattr__(self, key: 'str') -> 'Any'
| Proxy all other undefined accessors to the underlying
| implementation.
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| bind_expression(self, bindparam: 'BindParameter[_T]') -> 'Optional[ColumnElement[_T]]'
| Given a bind value (i.e. a :class:`.BindParameter` instance),
| return a SQL expression which will typically wrap the given parameter.
|
| .. note::
|
| This method is called during the **SQL compilation** phase of a
| statement, when rendering a SQL string. It is **not** necessarily
| called against specific values, and should not be confused with the
| :meth:`_types.TypeDecorator.process_bind_param` method, which is
| the more typical method that processes the actual value passed to a
| particular parameter at statement execution time.
|
| Subclasses of :class:`_types.TypeDecorator` can override this method
| to provide custom bind expression behavior for the type. This
| implementation will **replace** that of the underlying implementation
| type.
|
| column_expression(self, column: 'ColumnElement[_T]') -> 'Optional[ColumnElement[_T]]'
| Given a SELECT column expression, return a wrapping SQL expression.
|
| .. note::
|
| This method is called during the **SQL compilation** phase of a
| statement, when rendering a SQL string. It is **not** called
| against specific values, and should not be confused with the
| :meth:`_types.TypeDecorator.process_result_value` method, which is
| the more typical method that processes the actual value returned
| in a result row subsequent to statement execution time.
|
| Subclasses of :class:`_types.TypeDecorator` can override this method
| to provide custom column expression behavior for the type. This
| implementation will **replace** that of the underlying implementation
| type.
|
| See the description of :meth:`_types.TypeEngine.column_expression`
| for a complete description of the method's use.
|
| compare_values(self, x: 'Any', y: 'Any') -> 'bool'
| Given two values, compare them for equality.
|
| By default this calls upon :meth:`.TypeEngine.compare_values`
| of the underlying "impl", which in turn usually
| uses the Python equals operator ``==``.
|
| This function is used by the ORM to compare
| an original-loaded value with an intercepted
| "changed" value, to determine if a net change
| has occurred.
|
| copy(self, **kw: 'Any') -> 'Self'
| Produce a copy of this :class:`.TypeDecorator` instance.
|
| This is a shallow copy and is provided to fulfill part of
| the :class:`.TypeEngine` contract. It usually does not
| need to be overridden unless the user-defined :class:`.TypeDecorator`
| has local state that should be deep-copied.
|
| get_dbapi_type(self, dbapi: 'DBAPIModule') -> 'Optional[Any]'
| Return the DBAPI type object represented by this
| :class:`.TypeDecorator`.
|
| By default this calls upon :meth:`.TypeEngine.get_dbapi_type` of the
| underlying "impl".
|
| impl_instance(...)
|
| literal_processor(self, dialect: 'Dialect') -> 'Optional[_LiteralProcessorType[_T]]'
| Provide a literal processing function for the given
| :class:`.Dialect`.
|
| This is the method that fulfills the :class:`.TypeEngine`
| contract for literal value conversion which normally occurs via
| the :meth:`_types.TypeEngine.literal_processor` method.
|
| .. note::
|
| User-defined subclasses of :class:`_types.TypeDecorator` should
| **not** implement this method, and should instead implement
| :meth:`_types.TypeDecorator.process_literal_param` so that the
| "inner" processing provided by the implementing type is maintained.
|
| load_dialect_impl(self, dialect: 'Dialect') -> 'TypeEngine[Any]'
| Return a :class:`.TypeEngine` object corresponding to a dialect.
|
| This is an end-user override hook that can be used to provide
| differing types depending on the given dialect. It is used
| by the :class:`.TypeDecorator` implementation of :meth:`type_engine`
| to help determine what type should ultimately be returned
| for a given :class:`.TypeDecorator`.
|
| By default returns ``self.impl``.
|
| process_bind_param(self, value: 'Optional[_T]', dialect: 'Dialect') -> 'Any'
| Receive a bound parameter value to be converted.
|
| Custom subclasses of :class:`_types.TypeDecorator` should override
| this method to provide custom behaviors for incoming data values.
| This method is called at **statement execution time** and is passed
| the literal Python data value which is to be associated with a bound
| parameter in the statement.
|
| The operation could be anything desired to perform custom
| behavior, such as transforming or serializing data.
| This could also be used as a hook for validating logic.
|
| :param value: Data to operate upon, of any type expected by
| this method in the subclass. Can be ``None``.
| :param dialect: the :class:`.Dialect` in use.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| :meth:`_types.TypeDecorator.process_result_value`
|
| process_literal_param(self, value: 'Optional[_T]', dialect: 'Dialect') -> 'str'
| Receive a literal parameter value to be rendered inline within
| a statement.
|
| .. note::
|
| This method is called during the **SQL compilation** phase of a
| statement, when rendering a SQL string. Unlike other SQL
| compilation methods, it is passed a specific Python value to be
| rendered as a string. However it should not be confused with the
| :meth:`_types.TypeDecorator.process_bind_param` method, which is
| the more typical method that processes the actual value passed to a
| particular parameter at statement execution time.
|
| Custom subclasses of :class:`_types.TypeDecorator` should override
| this method to provide custom behaviors for incoming data values
| that are in the special case of being rendered as literals.
|
| The returned string will be rendered into the output string.
|
| process_result_value(self, value: 'Optional[Any]', dialect: 'Dialect') -> 'Optional[_T]'
| Receive a result-row column value to be converted.
|
| Custom subclasses of :class:`_types.TypeDecorator` should override
| this method to provide custom behaviors for data values
| being received in result rows coming from the database.
| This method is called at **result fetching time** and is passed
| the literal Python data value that's extracted from a database result
| row.
|
| The operation could be anything desired to perform custom
| behavior, such as transforming or deserializing data.
|
| :param value: Data to operate upon, of any type expected by
| this method in the subclass. Can be ``None``.
| :param dialect: the :class:`.Dialect` in use.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| :meth:`_types.TypeDecorator.process_bind_param`
|
| type_engine(self, dialect: 'Dialect') -> 'TypeEngine[Any]'
| Return a dialect-specific :class:`.TypeEngine` instance
| for this :class:`.TypeDecorator`.
|
| In most cases this returns a dialect-adapted form of
| the :class:`.TypeEngine` type represented by ``self.impl``.
| Makes usage of :meth:`dialect_impl`.
| Behavior can be customized here by overriding
| :meth:`load_dialect_impl`.
|
| ----------------------------------------------------------------------
| Readonly properties inherited from sqlalchemy.sql.type_api.TypeDecorator:
|
| sort_key_function
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.type_api.TypeDecorator:
|
| __visit_name__ = 'type_decorator'
|
| coerce_to_is_types = (<class 'NoneType'>,)
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.base.SchemaEventTarget:
|
| dispatch = <sqlalchemy.event.base.DDLEventsDispatch object>
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.type_api.TypeEngine:
|
| __str__(self) -> 'str'
| Return str(self).
|
| as_generic(self, allow_nulltype: 'bool' = False) -> 'TypeEngine[_T]'
| Return an instance of the generic type corresponding to this type
| using heuristic rule. The method may be overridden if this
| heuristic rule is not sufficient.
|
| >>> from sqlalchemy.dialects.mysql import INTEGER
| >>> INTEGER(display_width=4).as_generic()
| Integer()
|
| >>> from sqlalchemy.dialects.mysql import NVARCHAR
| >>> NVARCHAR(length=100).as_generic()
| Unicode(length=100)
|
| .. versionadded:: 1.4.0b2
|
|
| .. seealso::
|
| :ref:`metadata_reflection_dbagnostic_types` - describes the
| use of :meth:`_types.TypeEngine.as_generic` in conjunction with
| the :meth:`_sql.DDLEvents.column_reflect` event, which is its
| intended use.
|
| compile(self, dialect: 'Optional[Dialect]' = None) -> 'str'
| Produce a string-compiled form of this :class:`.TypeEngine`.
|
| When called with no arguments, uses a "default" dialect
| to produce a string result.
|
| :param dialect: a :class:`.Dialect` instance.
|
| copy_value(self, value: 'Any') -> 'Any'
|
| dialect_impl(self, dialect: 'Dialect') -> 'TypeEngine[_T]'
| Return a dialect-specific implementation for this
| :class:`.TypeEngine`.
|
| evaluates_none(self) -> 'Self'
| Return a copy of this type which has the
| :attr:`.should_evaluate_none` flag set to True.
|
| E.g.::
|
| Table(
| "some_table",
| metadata,
| Column(
| String(50).evaluates_none(),
| nullable=True,
| server_default="no value",
| ),
| )
|
| The ORM uses this flag to indicate that a positive value of ``None``
| is passed to the column in an INSERT statement, rather than omitting
| the column from the INSERT statement which has the effect of firing
| off column-level defaults. It also allows for types which have
| special behavior associated with the Python None value to indicate
| that the value doesn't necessarily translate into SQL NULL; a
| prime example of this is a JSON type which may wish to persist the
| JSON value ``'null'``.
|
| In all cases, the actual NULL SQL value can be always be
| persisted in any column by using
| the :obj:`_expression.null` SQL construct in an INSERT statement
| or associated with an ORM-mapped attribute.
|
| .. note::
|
| The "evaluates none" flag does **not** apply to a value
| of ``None`` passed to :paramref:`_schema.Column.default` or
| :paramref:`_schema.Column.server_default`; in these cases,
| ``None``
| still means "no default".
|
| .. seealso::
|
| :ref:`session_forcing_null` - in the ORM documentation
|
| :paramref:`.postgresql.JSON.none_as_null` - PostgreSQL JSON
| interaction with this flag.
|
| :attr:`.TypeEngine.should_evaluate_none` - class-level flag
|
| with_variant(self, type_: '_TypeEngineArgument[Any]', *dialect_names: 'str') -> 'Self'
| Produce a copy of this type object that will utilize the given
| type when applied to the dialect of the given name.
|
| e.g.::
|
| from sqlalchemy.types import String
| from sqlalchemy.dialects import mysql
|
| string_type = String()
|
| string_type = string_type.with_variant(
| mysql.VARCHAR(collation="foo"), "mysql", "mariadb"
| )
|
| The variant mapping indicates that when this type is
| interpreted by a specific dialect, it will instead be
| transmuted into the given type, rather than using the
| primary type.
|
| .. versionchanged:: 2.0 the :meth:`_types.TypeEngine.with_variant`
| method now works with a :class:`_types.TypeEngine` object "in
| place", returning a copy of the original type rather than returning
| a wrapping object; the ``Variant`` class is no longer used.
|
| :param type\_: a :class:`.TypeEngine` that will be selected
| as a variant from the originating type, when a dialect
| of the given name is in use.
| :param \*dialect_names: one or more base names of the dialect which
| uses this type. (i.e. ``'postgresql'``, ``'mysql'``, etc.)
|
| .. versionchanged:: 2.0 multiple dialect names can be specified
| for one variant.
|
| .. seealso::
|
| :ref:`types_with_variant` - illustrates the use of
| :meth:`_types.TypeEngine.with_variant`.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.type_api.TypeEngine:
|
| __orig_bases__ = (<class 'sqlalchemy.sql.visitors.Visitable'>, typing....
|
| hashable = True
|
| render_bind_cast = False
|
| render_literal_cast = False
|
| should_evaluate_none = False
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.visitors.Visitable:
|
| __class_getitem__(key: 'Any') -> 'Any'
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__() -> 'None'
| This method is called when a class is subclassed.
|
| The default implementation does nothing. It may be
| overridden to extend subclasses.
sqlalchemy.IteratorResult
Python Library Documentation: class IteratorResult in module sqlalchemy.engine.result
class IteratorResult(Result)
| IteratorResult(cursor_metadata: 'ResultMetaData', iterator: 'Iterator[_InterimSupportsScalarsRowType]', raw: 'Optional[Result[Any]]' = None, _source_supports_scalars: 'bool' = False)
|
| A :class:`_engine.Result` that gets data from a Python iterator of
| :class:`_engine.Row` objects or similar row-like data.
|
| .. versionadded:: 1.4
|
| Method resolution order:
| IteratorResult
| Result
| _WithKeys
| ResultInternal
| sqlalchemy.sql.base.InPlaceGenerative
| sqlalchemy.util.langhelpers.HasMemoized
| typing.Generic
| builtins.object
|
| Methods defined here:
|
| __init__(self, cursor_metadata: 'ResultMetaData', iterator: 'Iterator[_InterimSupportsScalarsRowType]', raw: 'Optional[Result[Any]]' = None, _source_supports_scalars: 'bool' = False)
| Initialize self. See help(type(self)) for accurate signature.
|
| ----------------------------------------------------------------------
| Readonly properties defined here:
|
| closed
| Return ``True`` if this :class:`_engine.IteratorResult` was
| **hard closed** by explicitly calling the :meth:`_engine.Result.close`
| method.
|
| The attribute is **not** True if the :class:`_engine.Result` was only
| **soft closed**; a "soft close" is the style of close that takes place
| for example when the :class:`.CursorResult` is returned for a DML
| only statement without RETURNING, or when all result rows are fetched.
|
| .. seealso::
|
| :attr:`.CursorResult.returns_rows` - attribute specific to
| :class:`.CursorResult` which indicates if the result is one that
| may return zero or more rows
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| __orig_bases__ = (sqlalchemy.engine.result.Result[~_TP],)
|
| __parameters__ = (~_TP,)
|
| ----------------------------------------------------------------------
| Methods inherited from Result:
|
| __enter__(self) -> 'Self'
|
| __exit__(self, type_: 'Any', value: 'Any', traceback: 'Any') -> 'None'
|
| __iter__(self) -> 'Iterator[Row[_TP]]'
|
| __next__(self) -> 'Row[_TP]'
|
| all(self) -> 'Sequence[Row[_TP]]'
| Return all rows in a sequence.
|
| Closes the result set after invocation. Subsequent invocations
| will return an empty sequence.
|
| .. versionadded:: 1.4
|
| :return: a sequence of :class:`_engine.Row` objects.
|
| .. seealso::
|
| :ref:`engine_stream_results` - How to stream a large result set
| without loading it completely in python.
|
| close(self) -> 'None'
| Hard close this :class:`_engine.Result`.
|
| The behavior of this method is implementation specific, and is
| not implemented by default. The method should generally end
| the resources in use by the result object and also cause any
| subsequent iteration or row fetching to raise
| :class:`.ResourceClosedError`.
|
| .. versionadded:: 1.4.27 - ``.close()`` was previously not generally
| available for all :class:`_engine.Result` classes, instead only
| being available on the :class:`_engine.CursorResult` returned for
| Core statement executions. As most other result objects, namely the
| ones used by the ORM, are proxying a :class:`_engine.CursorResult`
| in any case, this allows the underlying cursor result to be closed
| from the outside facade for the case when the ORM query is using
| the ``yield_per`` execution option where it does not immediately
| exhaust and autoclose the database cursor.
|
| columns(self, *col_expressions: '_KeyIndexType') -> 'Self'
| Establish the columns that should be returned in each row.
|
| This method may be used to limit the columns returned as well
| as to reorder them. The given list of expressions are normally
| a series of integers or string key names. They may also be
| appropriate :class:`.ColumnElement` objects which correspond to
| a given statement construct.
|
| .. versionchanged:: 2.0 Due to a bug in 1.4, the
| :meth:`_engine.Result.columns` method had an incorrect behavior
| where calling upon the method with just one index would cause the
| :class:`_engine.Result` object to yield scalar values rather than
| :class:`_engine.Row` objects. In version 2.0, this behavior
| has been corrected such that calling upon
| :meth:`_engine.Result.columns` with a single index will
| produce a :class:`_engine.Result` object that continues
| to yield :class:`_engine.Row` objects, which include
| only a single column.
|
| E.g.::
|
| statement = select(table.c.x, table.c.y, table.c.z)
| result = connection.execute(statement)
|
| for z, y in result.columns("z", "y"):
| ...
|
| Example of using the column objects from the statement itself::
|
| for z, y in result.columns(
| statement.selected_columns.c.z, statement.selected_columns.c.y
| ):
| ...
|
| .. versionadded:: 1.4
|
| :param \*col_expressions: indicates columns to be returned. Elements
| may be integer row indexes, string column names, or appropriate
| :class:`.ColumnElement` objects corresponding to a select construct.
|
| :return: this :class:`_engine.Result` object with the modifications
| given.
|
| fetchall(self) -> 'Sequence[Row[_TP]]'
| A synonym for the :meth:`_engine.Result.all` method.
|
| fetchmany(self, size: 'Optional[int]' = None) -> 'Sequence[Row[_TP]]'
| Fetch many rows.
|
| When all rows are exhausted, returns an empty sequence.
|
| This method is provided for backwards compatibility with
| SQLAlchemy 1.x.x.
|
| To fetch rows in groups, use the :meth:`_engine.Result.partitions`
| method.
|
| :return: a sequence of :class:`_engine.Row` objects.
|
| .. seealso::
|
| :meth:`_engine.Result.partitions`
|
| fetchone(self) -> 'Optional[Row[_TP]]'
| Fetch one row.
|
| When all rows are exhausted, returns None.
|
| This method is provided for backwards compatibility with
| SQLAlchemy 1.x.x.
|
| To fetch the first row of a result only, use the
| :meth:`_engine.Result.first` method. To iterate through all
| rows, iterate the :class:`_engine.Result` object directly.
|
| :return: a :class:`_engine.Row` object if no filters are applied,
| or ``None`` if no rows remain.
|
| first(self) -> 'Optional[Row[_TP]]'
| Fetch the first row or ``None`` if no row is present.
|
| Closes the result set and discards remaining rows.
|
| .. note:: This method returns one **row**, e.g. tuple, by default.
| To return exactly one single scalar value, that is, the first
| column of the first row, use the
| :meth:`_engine.Result.scalar` method,
| or combine :meth:`_engine.Result.scalars` and
| :meth:`_engine.Result.first`.
|
| Additionally, in contrast to the behavior of the legacy ORM
| :meth:`_orm.Query.first` method, **no limit is applied** to the
| SQL query which was invoked to produce this
| :class:`_engine.Result`;
| for a DBAPI driver that buffers results in memory before yielding
| rows, all rows will be sent to the Python process and all but
| the first row will be discarded.
|
| .. seealso::
|
| :ref:`migration_20_unify_select`
|
| :return: a :class:`_engine.Row` object, or None
| if no rows remain.
|
| .. seealso::
|
| :meth:`_engine.Result.scalar`
|
| :meth:`_engine.Result.one`
|
| freeze(self) -> 'FrozenResult[_TP]'
| Return a callable object that will produce copies of this
| :class:`_engine.Result` when invoked.
|
| The callable object returned is an instance of
| :class:`_engine.FrozenResult`.
|
| This is used for result set caching. The method must be called
| on the result when it has been unconsumed, and calling the method
| will consume the result fully. When the :class:`_engine.FrozenResult`
| is retrieved from a cache, it can be called any number of times where
| it will produce a new :class:`_engine.Result` object each time
| against its stored set of rows.
|
| .. seealso::
|
| :ref:`do_orm_execute_re_executing` - example usage within the
| ORM to implement a result-set cache.
|
| mappings(self) -> 'MappingResult'
| Apply a mappings filter to returned rows, returning an instance of
| :class:`_engine.MappingResult`.
|
| When this filter is applied, fetching rows will return
| :class:`_engine.RowMapping` objects instead of :class:`_engine.Row`
| objects.
|
| .. versionadded:: 1.4
|
| :return: a new :class:`_engine.MappingResult` filtering object
| referring to this :class:`_engine.Result` object.
|
| merge(self, *others: 'Result[Any]') -> 'MergedResult[_TP]'
| Merge this :class:`_engine.Result` with other compatible result
| objects.
|
| The object returned is an instance of :class:`_engine.MergedResult`,
| which will be composed of iterators from the given result
| objects.
|
| The new result will use the metadata from this result object.
| The subsequent result objects must be against an identical
| set of result / cursor metadata, otherwise the behavior is
| undefined.
|
| one(self) -> 'Row[_TP]'
| Return exactly one row or raise an exception.
|
| Raises :class:`_exc.NoResultFound` if the result returns no
| rows, or :class:`_exc.MultipleResultsFound` if multiple rows
| would be returned.
|
| .. note:: This method returns one **row**, e.g. tuple, by default.
| To return exactly one single scalar value, that is, the first
| column of the first row, use the
| :meth:`_engine.Result.scalar_one` method, or combine
| :meth:`_engine.Result.scalars` and
| :meth:`_engine.Result.one`.
|
| .. versionadded:: 1.4
|
| :return: The first :class:`_engine.Row`.
|
| :raises: :class:`.MultipleResultsFound`, :class:`.NoResultFound`
|
| .. seealso::
|
| :meth:`_engine.Result.first`
|
| :meth:`_engine.Result.one_or_none`
|
| :meth:`_engine.Result.scalar_one`
|
| one_or_none(self) -> 'Optional[Row[_TP]]'
| Return at most one result or raise an exception.
|
| Returns ``None`` if the result has no rows.
| Raises :class:`.MultipleResultsFound`
| if multiple rows are returned.
|
| .. versionadded:: 1.4
|
| :return: The first :class:`_engine.Row` or ``None`` if no row
| is available.
|
| :raises: :class:`.MultipleResultsFound`
|
| .. seealso::
|
| :meth:`_engine.Result.first`
|
| :meth:`_engine.Result.one`
|
| partitions(self, size: 'Optional[int]' = None) -> 'Iterator[Sequence[Row[_TP]]]'
| Iterate through sub-lists of rows of the size given.
|
| Each list will be of the size given, excluding the last list to
| be yielded, which may have a small number of rows. No empty
| lists will be yielded.
|
| The result object is automatically closed when the iterator
| is fully consumed.
|
| Note that the backend driver will usually buffer the entire result
| ahead of time unless the
| :paramref:`.Connection.execution_options.stream_results` execution
| option is used indicating that the driver should not pre-buffer
| results, if possible. Not all drivers support this option and
| the option is silently ignored for those who do not.
|
| When using the ORM, the :meth:`_engine.Result.partitions` method
| is typically more effective from a memory perspective when it is
| combined with use of the
| :ref:`yield_per execution option <orm_queryguide_yield_per>`,
| which instructs both the DBAPI driver to use server side cursors,
| if available, as well as instructs the ORM loading internals to only
| build a certain amount of ORM objects from a result at a time before
| yielding them out.
|
| .. versionadded:: 1.4
|
| :param size: indicate the maximum number of rows to be present
| in each list yielded. If None, makes use of the value set by
| the :meth:`_engine.Result.yield_per`, method, if it were called,
| or the :paramref:`_engine.Connection.execution_options.yield_per`
| execution option, which is equivalent in this regard. If
| yield_per weren't set, it makes use of the
| :meth:`_engine.Result.fetchmany` default, which may be backend
| specific and not well defined.
|
| :return: iterator of lists
|
| .. seealso::
|
| :ref:`engine_stream_results`
|
| :ref:`orm_queryguide_yield_per` - in the :ref:`queryguide_toplevel`
|
| scalar(self) -> 'Any'
| Fetch the first column of the first row, and close the result set.
|
| Returns ``None`` if there are no rows to fetch.
|
| No validation is performed to test if additional rows remain.
|
| After calling this method, the object is fully closed,
| e.g. the :meth:`_engine.CursorResult.close`
| method will have been called.
|
| :return: a Python scalar value, or ``None`` if no rows remain.
|
| scalar_one(self) -> 'Any'
| Return exactly one scalar result or raise an exception.
|
| This is equivalent to calling :meth:`_engine.Result.scalars` and
| then :meth:`_engine.ScalarResult.one`.
|
| .. seealso::
|
| :meth:`_engine.ScalarResult.one`
|
| :meth:`_engine.Result.scalars`
|
| scalar_one_or_none(self) -> 'Optional[Any]'
| Return exactly one scalar result or ``None``.
|
| This is equivalent to calling :meth:`_engine.Result.scalars` and
| then :meth:`_engine.ScalarResult.one_or_none`.
|
| .. seealso::
|
| :meth:`_engine.ScalarResult.one_or_none`
|
| :meth:`_engine.Result.scalars`
|
| scalars(self, index: '_KeyIndexType' = 0) -> 'ScalarResult[Any]'
| Return a :class:`_engine.ScalarResult` filtering object which
| will return single elements rather than :class:`_row.Row` objects.
|
| E.g.::
|
| >>> result = conn.execute(text("select int_id from table"))
| >>> result.scalars().all()
| [1, 2, 3]
|
| When results are fetched from the :class:`_engine.ScalarResult`
| filtering object, the single column-row that would be returned by the
| :class:`_engine.Result` is instead returned as the column's value.
|
| .. versionadded:: 1.4
|
| :param index: integer or row key indicating the column to be fetched
| from each row, defaults to ``0`` indicating the first column.
|
| :return: a new :class:`_engine.ScalarResult` filtering object referring
| to this :class:`_engine.Result` object.
|
| tuples(self) -> 'TupleResult[_TP]'
| Apply a "typed tuple" typing filter to returned rows.
|
| This method returns the same :class:`_engine.Result` object
| at runtime,
| however annotates as returning a :class:`_engine.TupleResult` object
| that will indicate to :pep:`484` typing tools that plain typed
| ``Tuple`` instances are returned rather than rows. This allows
| tuple unpacking and ``__getitem__`` access of :class:`_engine.Row`
| objects to by typed, for those cases where the statement invoked
| itself included typing information.
|
| .. versionadded:: 2.0
|
| :return: the :class:`_engine.TupleResult` type at typing time.
|
| .. seealso::
|
| :attr:`_engine.Result.t` - shorter synonym
|
| :attr:`_engine.Row._t` - :class:`_engine.Row` version
|
| unique(self, strategy: 'Optional[_UniqueFilterType]' = None) -> 'Self'
| Apply unique filtering to the objects returned by this
| :class:`_engine.Result`.
|
| When this filter is applied with no arguments, the rows or objects
| returned will filtered such that each row is returned uniquely. The
| algorithm used to determine this uniqueness is by default the Python
| hashing identity of the whole tuple. In some cases a specialized
| per-entity hashing scheme may be used, such as when using the ORM, a
| scheme is applied which works against the primary key identity of
| returned objects.
|
| The unique filter is applied **after all other filters**, which means
| if the columns returned have been refined using a method such as the
| :meth:`_engine.Result.columns` or :meth:`_engine.Result.scalars`
| method, the uniquing is applied to **only the column or columns
| returned**. This occurs regardless of the order in which these
| methods have been called upon the :class:`_engine.Result` object.
|
| The unique filter also changes the calculus used for methods like
| :meth:`_engine.Result.fetchmany` and :meth:`_engine.Result.partitions`.
| When using :meth:`_engine.Result.unique`, these methods will continue
| to yield the number of rows or objects requested, after uniquing
| has been applied. However, this necessarily impacts the buffering
| behavior of the underlying cursor or datasource, such that multiple
| underlying calls to ``cursor.fetchmany()`` may be necessary in order
| to accumulate enough objects in order to provide a unique collection
| of the requested size.
|
| :param strategy: a callable that will be applied to rows or objects
| being iterated, which should return an object that represents the
| unique value of the row. A Python ``set()`` is used to store
| these identities. If not passed, a default uniqueness strategy
| is used which may have been assembled by the source of this
| :class:`_engine.Result` object.
|
| yield_per(self, num: 'int') -> 'Self'
| Configure the row-fetching strategy to fetch ``num`` rows at a time.
|
| This impacts the underlying behavior of the result when iterating over
| the result object, or otherwise making use of methods such as
| :meth:`_engine.Result.fetchone` that return one row at a time. Data
| from the underlying cursor or other data source will be buffered up to
| this many rows in memory, and the buffered collection will then be
| yielded out one row at a time or as many rows are requested. Each time
| the buffer clears, it will be refreshed to this many rows or as many
| rows remain if fewer remain.
|
| The :meth:`_engine.Result.yield_per` method is generally used in
| conjunction with the
| :paramref:`_engine.Connection.execution_options.stream_results`
| execution option, which will allow the database dialect in use to make
| use of a server side cursor, if the DBAPI supports a specific "server
| side cursor" mode separate from its default mode of operation.
|
| .. tip::
|
| Consider using the
| :paramref:`_engine.Connection.execution_options.yield_per`
| execution option, which will simultaneously set
| :paramref:`_engine.Connection.execution_options.stream_results`
| to ensure the use of server side cursors, as well as automatically
| invoke the :meth:`_engine.Result.yield_per` method to establish
| a fixed row buffer size at once.
|
| The :paramref:`_engine.Connection.execution_options.yield_per`
| execution option is available for ORM operations, with
| :class:`_orm.Session`-oriented use described at
| :ref:`orm_queryguide_yield_per`. The Core-only version which works
| with :class:`_engine.Connection` is new as of SQLAlchemy 1.4.40.
|
| .. versionadded:: 1.4
|
| :param num: number of rows to fetch each time the buffer is refilled.
| If set to a value below 1, fetches all rows for the next buffer.
|
| .. seealso::
|
| :ref:`engine_stream_results` - describes Core behavior for
| :meth:`_engine.Result.yield_per`
|
| :ref:`orm_queryguide_yield_per` - in the :ref:`queryguide_toplevel`
|
| ----------------------------------------------------------------------
| Readonly properties inherited from Result:
|
| t
| Apply a "typed tuple" typing filter to returned rows.
|
| The :attr:`_engine.Result.t` attribute is a synonym for
| calling the :meth:`_engine.Result.tuples` method.
|
| .. versionadded:: 2.0
|
| ----------------------------------------------------------------------
| Data descriptors inherited from Result:
|
| __dict__
| dictionary for instance variables
|
| ----------------------------------------------------------------------
| Methods inherited from _WithKeys:
|
| keys(self) -> 'RMKeyView'
| Return an iterable view which yields the string keys that would
| be represented by each :class:`_engine.Row`.
|
| The keys can represent the labels of the columns returned by a core
| statement or the names of the orm classes returned by an orm
| execution.
|
| The view also can be tested for key containment using the Python
| ``in`` operator, which will test both for the string keys represented
| in the view, as well as for alternate keys such as column objects.
|
| .. versionchanged:: 1.4 a key view object is returned rather than a
| plain list.
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_instancemethod(fn: '_F') -> '_F'
| Decorate a method memoize its return value.
|
| :meta private:
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_attribute = <class 'sqlalchemy.util.langhelpers.HasMemoized.m...
| A read-only @property that is only evaluated once.
|
| :meta private:
|
|
| ----------------------------------------------------------------------
| Class methods inherited from typing.Generic:
|
| __class_getitem__(...)
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__(...)
| Function to initialize subclasses.
sqlalchemy.JSON
Python Library Documentation: class JSON in module sqlalchemy.sql.sqltypes
class JSON(Indexable, sqlalchemy.sql.type_api.TypeEngine)
| JSON(none_as_null: 'bool' = False)
|
| Represent a SQL JSON type.
|
| .. note:: :class:`_types.JSON`
| is provided as a facade for vendor-specific
| JSON types. Since it supports JSON SQL operations, it only
| works on backends that have an actual JSON type, currently:
|
| * PostgreSQL - see :class:`sqlalchemy.dialects.postgresql.JSON` and
| :class:`sqlalchemy.dialects.postgresql.JSONB` for backend-specific
| notes
|
| * MySQL - see
| :class:`sqlalchemy.dialects.mysql.JSON` for backend-specific notes
|
| * SQLite as of version 3.9 - see
| :class:`sqlalchemy.dialects.sqlite.JSON` for backend-specific notes
|
| * Microsoft SQL Server 2016 and later - see
| :class:`sqlalchemy.dialects.mssql.JSON` for backend-specific notes
|
| :class:`_types.JSON` is part of the Core in support of the growing
| popularity of native JSON datatypes.
|
| The :class:`_types.JSON` type stores arbitrary JSON format data, e.g.::
|
| data_table = Table(
| "data_table",
| metadata,
| Column("id", Integer, primary_key=True),
| Column("data", JSON),
| )
|
| with engine.connect() as conn:
| conn.execute(
| data_table.insert(), {"data": {"key1": "value1", "key2": "value2"}}
| )
|
| **JSON-Specific Expression Operators**
|
| The :class:`_types.JSON`
| datatype provides these additional SQL operations:
|
| * Keyed index operations::
|
| data_table.c.data["some key"]
|
| * Integer index operations::
|
| data_table.c.data[3]
|
| * Path index operations::
|
| data_table.c.data[("key_1", "key_2", 5, ..., "key_n")]
|
| * Data casters for specific JSON element types, subsequent to an index
| or path operation being invoked::
|
| data_table.c.data["some key"].as_integer()
|
| .. versionadded:: 1.3.11
|
| Additional operations may be available from the dialect-specific versions
| of :class:`_types.JSON`, such as
| :class:`sqlalchemy.dialects.postgresql.JSON` and
| :class:`sqlalchemy.dialects.postgresql.JSONB` which both offer additional
| PostgreSQL-specific operations.
|
| **Casting JSON Elements to Other Types**
|
| Index operations, i.e. those invoked by calling upon the expression using
| the Python bracket operator as in ``some_column['some key']``, return an
| expression object whose type defaults to :class:`_types.JSON` by default,
| so that
| further JSON-oriented instructions may be called upon the result type.
| However, it is likely more common that an index operation is expected
| to return a specific scalar element, such as a string or integer. In
| order to provide access to these elements in a backend-agnostic way,
| a series of data casters are provided:
|
| * :meth:`.JSON.Comparator.as_string` - return the element as a string
|
| * :meth:`.JSON.Comparator.as_boolean` - return the element as a boolean
|
| * :meth:`.JSON.Comparator.as_float` - return the element as a float
|
| * :meth:`.JSON.Comparator.as_integer` - return the element as an integer
|
| These data casters are implemented by supporting dialects in order to
| assure that comparisons to the above types will work as expected, such as::
|
| # integer comparison
| data_table.c.data["some_integer_key"].as_integer() == 5
|
| # boolean comparison
| data_table.c.data["some_boolean"].as_boolean() == True
|
| .. versionadded:: 1.3.11 Added type-specific casters for the basic JSON
| data element types.
|
| .. note::
|
| The data caster functions are new in version 1.3.11, and supersede
| the previous documented approaches of using CAST; for reference,
| this looked like::
|
| from sqlalchemy import cast, type_coerce
| from sqlalchemy import String, JSON
|
| cast(data_table.c.data["some_key"], String) == type_coerce(55, JSON)
|
| The above case now works directly as::
|
| data_table.c.data["some_key"].as_integer() == 5
|
| For details on the previous comparison approach within the 1.3.x
| series, see the documentation for SQLAlchemy 1.2 or the included HTML
| files in the doc/ directory of the version's distribution.
|
| **Detecting Changes in JSON columns when using the ORM**
|
| The :class:`_types.JSON` type, when used with the SQLAlchemy ORM, does not
| detect in-place mutations to the structure. In order to detect these, the
| :mod:`sqlalchemy.ext.mutable` extension must be used, most typically
| using the :class:`.MutableDict` class. This extension will
| allow "in-place" changes to the datastructure to produce events which
| will be detected by the unit of work. See the example at :class:`.HSTORE`
| for a simple example involving a dictionary.
|
| Alternatively, assigning a JSON structure to an ORM element that
| replaces the old one will always trigger a change event.
|
| **Support for JSON null vs. SQL NULL**
|
| When working with NULL values, the :class:`_types.JSON` type recommends the
| use of two specific constants in order to differentiate between a column
| that evaluates to SQL NULL, e.g. no value, vs. the JSON-encoded string of
| ``"null"``. To insert or select against a value that is SQL NULL, use the
| constant :func:`.null`. This symbol may be passed as a parameter value
| specifically when using the :class:`_types.JSON` datatype, which contains
| special logic that interprets this symbol to mean that the column value
| should be SQL NULL as opposed to JSON ``"null"``::
|
| from sqlalchemy import null
|
| conn.execute(table.insert(), {"json_value": null()})
|
| To insert or select against a value that is JSON ``"null"``, use the
| constant :attr:`_types.JSON.NULL`::
|
| conn.execute(table.insert(), {"json_value": JSON.NULL})
|
| The :class:`_types.JSON` type supports a flag
| :paramref:`_types.JSON.none_as_null` which when set to True will result
| in the Python constant ``None`` evaluating to the value of SQL
| NULL, and when set to False results in the Python constant
| ``None`` evaluating to the value of JSON ``"null"``. The Python
| value ``None`` may be used in conjunction with either
| :attr:`_types.JSON.NULL` and :func:`.null` in order to indicate NULL
| values, but care must be taken as to the value of the
| :paramref:`_types.JSON.none_as_null` in these cases.
|
| **Customizing the JSON Serializer**
|
| The JSON serializer and deserializer used by :class:`_types.JSON`
| defaults to
| Python's ``json.dumps`` and ``json.loads`` functions; in the case of the
| psycopg2 dialect, psycopg2 may be using its own custom loader function.
|
| In order to affect the serializer / deserializer, they are currently
| configurable at the :func:`_sa.create_engine` level via the
| :paramref:`_sa.create_engine.json_serializer` and
| :paramref:`_sa.create_engine.json_deserializer` parameters. For example,
| to turn off ``ensure_ascii``::
|
| engine = create_engine(
| "sqlite://",
| json_serializer=lambda obj: json.dumps(obj, ensure_ascii=False),
| )
|
| .. versionchanged:: 1.3.7
|
| SQLite dialect's ``json_serializer`` and ``json_deserializer``
| parameters renamed from ``_json_serializer`` and
| ``_json_deserializer``.
|
| .. seealso::
|
| :class:`sqlalchemy.dialects.postgresql.JSON`
|
| :class:`sqlalchemy.dialects.postgresql.JSONB`
|
| :class:`sqlalchemy.dialects.mysql.JSON`
|
| :class:`sqlalchemy.dialects.sqlite.JSON`
|
| Method resolution order:
| JSON
| Indexable
| sqlalchemy.sql.type_api.TypeEngineMixin
| sqlalchemy.sql.type_api.TypeEngine
| sqlalchemy.sql.visitors.Visitable
| typing.Generic
| builtins.object
|
| Methods defined here:
|
| __init__(self, none_as_null: 'bool' = False)
| Construct a :class:`_types.JSON` type.
|
| :param none_as_null=False: if True, persist the value ``None`` as a
| SQL NULL value, not the JSON encoding of ``null``. Note that when this
| flag is False, the :func:`.null` construct can still be used to
| persist a NULL value, which may be passed directly as a parameter
| value that is specially interpreted by the :class:`_types.JSON` type
| as SQL NULL::
|
| from sqlalchemy import null
|
| conn.execute(table.insert(), {"data": null()})
|
| .. note::
|
| :paramref:`_types.JSON.none_as_null` does **not** apply to the
| values passed to :paramref:`_schema.Column.default` and
| :paramref:`_schema.Column.server_default`; a value of ``None``
| passed for these parameters means "no default present".
|
| Additionally, when used in SQL comparison expressions, the
| Python value ``None`` continues to refer to SQL null, and not
| JSON NULL. The :paramref:`_types.JSON.none_as_null` flag refers
| explicitly to the **persistence** of the value within an
| INSERT or UPDATE statement. The :attr:`_types.JSON.NULL`
| value should be used for SQL expressions that wish to compare to
| JSON null.
|
| .. seealso::
|
| :attr:`.types.JSON.NULL`
|
| bind_processor(self, dialect)
| Return a conversion function for processing bind values.
|
| Returns a callable which will receive a bind parameter value
| as the sole positional argument and will return a value to
| send to the DB-API.
|
| If processing is not necessary, the method should return ``None``.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.bind_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.bind_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_bind_param`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
|
| :param dialect: Dialect instance in use.
|
| result_processor(self, dialect, coltype)
| Return a conversion function for processing result row values.
|
| Returns a callable which will receive a result row column
| value as the sole positional argument and will return a value
| to return to the user.
|
| If processing is not necessary, the method should return ``None``.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.result_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.result_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_result_value`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| :param dialect: Dialect instance in use.
|
| :param coltype: DBAPI coltype argument received in cursor.description.
|
| ----------------------------------------------------------------------
| Readonly properties defined here:
|
| python_type
| Return the Python type object expected to be returned
| by instances of this type, if known.
|
| Basically, for those types which enforce a return type,
| or are known across the board to do such for all common
| DBAPIs (like ``int`` for example), will return that type.
|
| If a return type is not defined, raises
| ``NotImplementedError``.
|
| Note that any type also accommodates NULL in SQL which
| means you can also get back ``None`` from any type
| in practice.
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| should_evaluate_none
| Alias of :attr:`_types.JSON.none_as_null`
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| Comparator = <class 'sqlalchemy.sql.sqltypes.JSON.Comparator'>
| Define comparison operations for :class:`_types.JSON`.
|
|
| JSONElementType = <class 'sqlalchemy.sql.sqltypes.JSON.JSONElementType...
| Common function for index / path elements in a JSON expression.
|
|
| JSONIndexType = <class 'sqlalchemy.sql.sqltypes.JSON.JSONIndexType'>
| Placeholder for the datatype of a JSON index value.
|
| This allows execution-time processing of JSON index values
| for special syntaxes.
|
|
| JSONIntIndexType = <class 'sqlalchemy.sql.sqltypes.JSON.JSONIntIndexTy...
| Placeholder for the datatype of a JSON index value.
|
| This allows execution-time processing of JSON index values
| for special syntaxes.
|
|
| JSONPathType = <class 'sqlalchemy.sql.sqltypes.JSON.JSONPathType'>
| Placeholder type for JSON path operations.
|
| This allows execution-time processing of a path-based
| index value into a specific SQL syntax.
|
|
| JSONStrIndexType = <class 'sqlalchemy.sql.sqltypes.JSON.JSONStrIndexTy...
| Placeholder for the datatype of a JSON index value.
|
| This allows execution-time processing of JSON index values
| for special syntaxes.
|
|
| NULL = symbol('JSON_NULL')
|
| __annotations__ = {}
|
| __parameters__ = ()
|
| __visit_name__ = 'JSON'
|
| comparator_factory = <class 'sqlalchemy.sql.sqltypes.JSON.Comparator'>
| Define comparison operations for :class:`_types.JSON`.
|
|
| hashable = False
|
| ----------------------------------------------------------------------
| Data descriptors inherited from Indexable:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.type_api.TypeEngine:
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| __str__(self) -> 'str'
| Return str(self).
|
| adapt(self, cls: 'Type[Union[TypeEngine[Any], TypeEngineMixin]]', **kw: 'Any') -> 'TypeEngine[Any]'
| Produce an "adapted" form of this type, given an "impl" class
| to work with.
|
| This method is used internally to associate generic
| types with "implementation" types that are specific to a particular
| dialect.
|
| as_generic(self, allow_nulltype: 'bool' = False) -> 'TypeEngine[_T]'
| Return an instance of the generic type corresponding to this type
| using heuristic rule. The method may be overridden if this
| heuristic rule is not sufficient.
|
| >>> from sqlalchemy.dialects.mysql import INTEGER
| >>> INTEGER(display_width=4).as_generic()
| Integer()
|
| >>> from sqlalchemy.dialects.mysql import NVARCHAR
| >>> NVARCHAR(length=100).as_generic()
| Unicode(length=100)
|
| .. versionadded:: 1.4.0b2
|
|
| .. seealso::
|
| :ref:`metadata_reflection_dbagnostic_types` - describes the
| use of :meth:`_types.TypeEngine.as_generic` in conjunction with
| the :meth:`_sql.DDLEvents.column_reflect` event, which is its
| intended use.
|
| bind_expression(self, bindvalue: 'BindParameter[_T]') -> 'Optional[ColumnElement[_T]]'
| Given a bind value (i.e. a :class:`.BindParameter` instance),
| return a SQL expression in its place.
|
| This is typically a SQL function that wraps the existing bound
| parameter within the statement. It is used for special data types
| that require literals being wrapped in some special database function
| in order to coerce an application-level value into a database-specific
| format. It is the SQL analogue of the
| :meth:`.TypeEngine.bind_processor` method.
|
| This method is called during the **SQL compilation** phase of a
| statement, when rendering a SQL string. It is **not** called
| against specific values.
|
| Note that this method, when implemented, should always return
| the exact same structure, without any conditional logic, as it
| may be used in an executemany() call against an arbitrary number
| of bound parameter sets.
|
| .. note::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.bind_expression`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.bind_expression`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.bind_expression`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| .. seealso::
|
| :ref:`types_sql_value_processing`
|
| coerce_compared_value(self, op: 'Optional[OperatorType]', value: 'Any') -> 'TypeEngine[Any]'
| Suggest a type for a 'coerced' Python value in an expression.
|
| Given an operator and value, gives the type a chance
| to return a type which the value should be coerced into.
|
| The default behavior here is conservative; if the right-hand
| side is already coerced into a SQL type based on its
| Python type, it is usually left alone.
|
| End-user functionality extension here should generally be via
| :class:`.TypeDecorator`, which provides more liberal behavior in that
| it defaults to coercing the other side of the expression into this
| type, thus applying special Python conversions above and beyond those
| needed by the DBAPI to both ides. It also provides the public method
| :meth:`.TypeDecorator.coerce_compared_value` which is intended for
| end-user customization of this behavior.
|
| column_expression(self, colexpr: 'ColumnElement[_T]') -> 'Optional[ColumnElement[_T]]'
| Given a SELECT column expression, return a wrapping SQL expression.
|
| This is typically a SQL function that wraps a column expression
| as rendered in the columns clause of a SELECT statement.
| It is used for special data types that require
| columns to be wrapped in some special database function in order
| to coerce the value before being sent back to the application.
| It is the SQL analogue of the :meth:`.TypeEngine.result_processor`
| method.
|
| .. note:: The :func:`.TypeEngine.column_expression` method is applied
| only to the **outermost columns clause** of a SELECT statement, that
| is, the columns that are to be delivered directly into the returned
| result rows. It does **not** apply to the columns clause inside
| of subqueries. This necessarily avoids double conversions against
| the column and only runs the conversion when ready to be returned
| to the client.
|
| This method is called during the **SQL compilation** phase of a
| statement, when rendering a SQL string. It is **not** called
| against specific values.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.column_expression`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.column_expression`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.column_expression`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
|
| .. seealso::
|
| :ref:`types_sql_value_processing`
|
| compare_values(self, x: 'Any', y: 'Any') -> 'bool'
| Compare two values for equality.
|
| compile(self, dialect: 'Optional[Dialect]' = None) -> 'str'
| Produce a string-compiled form of this :class:`.TypeEngine`.
|
| When called with no arguments, uses a "default" dialect
| to produce a string result.
|
| :param dialect: a :class:`.Dialect` instance.
|
| copy(self, **kw: 'Any') -> 'Self'
|
| copy_value(self, value: 'Any') -> 'Any'
|
| dialect_impl(self, dialect: 'Dialect') -> 'TypeEngine[_T]'
| Return a dialect-specific implementation for this
| :class:`.TypeEngine`.
|
| evaluates_none(self) -> 'Self'
| Return a copy of this type which has the
| :attr:`.should_evaluate_none` flag set to True.
|
| E.g.::
|
| Table(
| "some_table",
| metadata,
| Column(
| String(50).evaluates_none(),
| nullable=True,
| server_default="no value",
| ),
| )
|
| The ORM uses this flag to indicate that a positive value of ``None``
| is passed to the column in an INSERT statement, rather than omitting
| the column from the INSERT statement which has the effect of firing
| off column-level defaults. It also allows for types which have
| special behavior associated with the Python None value to indicate
| that the value doesn't necessarily translate into SQL NULL; a
| prime example of this is a JSON type which may wish to persist the
| JSON value ``'null'``.
|
| In all cases, the actual NULL SQL value can be always be
| persisted in any column by using
| the :obj:`_expression.null` SQL construct in an INSERT statement
| or associated with an ORM-mapped attribute.
|
| .. note::
|
| The "evaluates none" flag does **not** apply to a value
| of ``None`` passed to :paramref:`_schema.Column.default` or
| :paramref:`_schema.Column.server_default`; in these cases,
| ``None``
| still means "no default".
|
| .. seealso::
|
| :ref:`session_forcing_null` - in the ORM documentation
|
| :paramref:`.postgresql.JSON.none_as_null` - PostgreSQL JSON
| interaction with this flag.
|
| :attr:`.TypeEngine.should_evaluate_none` - class-level flag
|
| get_dbapi_type(self, dbapi: 'DBAPIModule') -> 'Optional[Any]'
| Return the corresponding type object from the underlying DB-API, if
| any.
|
| This can be useful for calling ``setinputsizes()``, for example.
|
| literal_processor(self, dialect: 'Dialect') -> 'Optional[_LiteralProcessorType[_T]]'
| Return a conversion function for processing literal values that are
| to be rendered directly without using binds.
|
| This function is used when the compiler makes use of the
| "literal_binds" flag, typically used in DDL generation as well
| as in certain scenarios where backends don't accept bound parameters.
|
| Returns a callable which will receive a literal Python value
| as the sole positional argument and will return a string representation
| to be rendered in a SQL statement.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.literal_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.literal_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_literal_param`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| with_variant(self, type_: '_TypeEngineArgument[Any]', *dialect_names: 'str') -> 'Self'
| Produce a copy of this type object that will utilize the given
| type when applied to the dialect of the given name.
|
| e.g.::
|
| from sqlalchemy.types import String
| from sqlalchemy.dialects import mysql
|
| string_type = String()
|
| string_type = string_type.with_variant(
| mysql.VARCHAR(collation="foo"), "mysql", "mariadb"
| )
|
| The variant mapping indicates that when this type is
| interpreted by a specific dialect, it will instead be
| transmuted into the given type, rather than using the
| primary type.
|
| .. versionchanged:: 2.0 the :meth:`_types.TypeEngine.with_variant`
| method now works with a :class:`_types.TypeEngine` object "in
| place", returning a copy of the original type rather than returning
| a wrapping object; the ``Variant`` class is no longer used.
|
| :param type\_: a :class:`.TypeEngine` that will be selected
| as a variant from the originating type, when a dialect
| of the given name is in use.
| :param \*dialect_names: one or more base names of the dialect which
| uses this type. (i.e. ``'postgresql'``, ``'mysql'``, etc.)
|
| .. versionchanged:: 2.0 multiple dialect names can be specified
| for one variant.
|
| .. seealso::
|
| :ref:`types_with_variant` - illustrates the use of
| :meth:`_types.TypeEngine.with_variant`.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.type_api.TypeEngine:
|
| __orig_bases__ = (<class 'sqlalchemy.sql.visitors.Visitable'>, typing....
|
| render_bind_cast = False
|
| render_literal_cast = False
|
| sort_key_function = None
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.visitors.Visitable:
|
| __class_getitem__(key: 'Any') -> 'Any'
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__() -> 'None'
| This method is called when a class is subclassed.
|
| The default implementation does nothing. It may be
| overridden to extend subclasses.
sqlalchemy.Join
Python Library Documentation: class Join in module sqlalchemy.sql.selectable
class Join(sqlalchemy.sql.roles.DMLTableRole, FromClause)
| Join(left: '_FromClauseArgument', right: '_FromClauseArgument', onclause: 'Optional[_OnClauseArgument]' = None, isouter: 'bool' = False, full: 'bool' = False)
|
| Represent a ``JOIN`` construct between two
| :class:`_expression.FromClause`
| elements.
|
| The public constructor function for :class:`_expression.Join`
| is the module-level
| :func:`_expression.join()` function, as well as the
| :meth:`_expression.FromClause.join` method
| of any :class:`_expression.FromClause` (e.g. such as
| :class:`_schema.Table`).
|
| .. seealso::
|
| :func:`_expression.join`
|
| :meth:`_expression.FromClause.join`
|
| Method resolution order:
| Join
| sqlalchemy.sql.roles.DMLTableRole
| FromClause
| sqlalchemy.sql.roles.AnonymizedFromClauseRole
| sqlalchemy.sql.roles.StrictFromClauseRole
| sqlalchemy.sql.roles.FromClauseRole
| sqlalchemy.sql.roles.ColumnsClauseRole
| sqlalchemy.sql.roles.JoinTargetRole
| sqlalchemy.sql.roles.AllowsLambdaRole
| sqlalchemy.sql.roles.UsesInspection
| sqlalchemy.sql.roles.ColumnListRole
| sqlalchemy.sql.roles.StructuralRole
| Selectable
| ReturnsRows
| sqlalchemy.sql.roles.ReturnsRowsRole
| sqlalchemy.sql.roles.SQLRole
| sqlalchemy.sql.elements.DQLDMLClauseElement
| sqlalchemy.sql.elements.ClauseElement
| sqlalchemy.sql.annotation.SupportsWrappingAnnotations
| sqlalchemy.sql.annotation.SupportsAnnotations
| sqlalchemy.sql.cache_key.MemoizedHasCacheKey
| sqlalchemy.sql.cache_key.HasCacheKey
| sqlalchemy.util.langhelpers.HasMemoized
| sqlalchemy.sql.traversals.HasCopyInternals
| sqlalchemy.sql.visitors.ExternallyTraversible
| sqlalchemy.sql.visitors.HasTraverseInternals
| sqlalchemy.sql.elements.CompilerElement
| sqlalchemy.sql.visitors.Visitable
| builtins.object
|
| Methods defined here:
|
| __init__(self, left: '_FromClauseArgument', right: '_FromClauseArgument', onclause: 'Optional[_OnClauseArgument]' = None, isouter: 'bool' = False, full: 'bool' = False)
| Construct a new :class:`_expression.Join`.
|
| The usual entrypoint here is the :func:`_expression.join`
| function or the :meth:`_expression.FromClause.join` method of any
| :class:`_expression.FromClause` object.
|
| description(...)
|
| 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.
|
| select(self) -> 'Select[Any]'
| Create a :class:`_expression.Select` from this
| :class:`_expression.Join`.
|
| E.g.::
|
| stmt = table_a.join(table_b, table_a.c.id == table_b.c.a_id)
|
| stmt = stmt.select()
|
| The above will produce a SQL string resembling:
|
| .. sourcecode:: sql
|
| SELECT table_a.id, table_a.col, table_b.id, table_b.a_id
| FROM table_a JOIN table_b ON table_a.id = table_b.a_id
|
| self_group(self, against: 'Optional[OperatorType]' = None) -> 'FromGrouping'
| 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.
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'_traverse_internals': '_TraverseInternalsType', 'f...
|
| __visit_name__ = 'join'
|
| ----------------------------------------------------------------------
| Methods inherited from FromClause:
|
| alias(self, name: 'Optional[str]' = None, flat: 'bool' = False) -> 'NamedFromClause'
| 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`
|
| c(...)
| A synonym for :attr:`.FromClause.columns`
|
| :return: a :class:`.ColumnCollection`
|
| columns(...)
| 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.
|
| entity_namespace(...)
| 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.
|
| exported_columns(...)
| A :class:`_expression.ColumnCollection`
| that represents the "exported"
| columns of this :class:`_expression.Selectable`.
|
| 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`
|
| foreign_keys(...)
| Return the collection of :class:`_schema.ForeignKey` marker objects
| which this FromClause references.
|
| Each :class:`_schema.ForeignKey` is a member of a
| :class:`_schema.Table`-wide
| :class:`_schema.ForeignKeyConstraint`.
|
| .. seealso::
|
| :attr:`_schema.Table.foreign_key_constraints`
|
| 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
|
| 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`
|
| primary_key(...)
| 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.
|
| 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
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from FromClause:
|
| is_selectable = True
|
| named_with_column = False
|
| schema = None
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.AllowsLambdaRole:
|
| allows_lambda = True
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.UsesInspection:
|
| uses_inspection = True
|
| ----------------------------------------------------------------------
| Methods inherited from Selectable:
|
| 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.
|
| 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.
|
| 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`.
|
| .. deprecated:: 1.4 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.
|
| ----------------------------------------------------------------------
| Readonly properties inherited from ReturnsRows:
|
| selectable
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.elements.ClauseElement:
|
| __bool__(self)
|
| __getstate__(self)
| Helper for pickle.
|
| __invert__(self)
|
| __repr__(self)
| Return repr(self).
|
| compare(self, other: 'ClauseElement', **kw: 'Any') -> 'bool'
| Compare this :class:`_expression.ClauseElement` to
| the given :class:`_expression.ClauseElement`.
|
| Subclasses should override the default behavior, which is a
| straight identity comparison.
|
| \**kw are arguments consumed by subclass ``compare()`` methods and
| may be used to modify the criteria for comparison
| (see :class:`_expression.ColumnElement`).
|
| params(self, _ClauseElement__optionaldict: 'Optional[Mapping[str, Any]]' = None, **kwargs: 'Any') -> 'Self'
| Return a copy with :func:`_expression.bindparam` elements
| replaced.
|
| Returns a copy of this ClauseElement with
| :func:`_expression.bindparam`
| elements replaced with values taken from the given dictionary::
|
| >>> clause = column("x") + bindparam("foo")
| >>> print(clause.compile().params)
| {'foo':None}
| >>> print(clause.params({"foo": 7}).compile().params)
| {'foo':7}
|
| unique_params(self, _ClauseElement__optionaldict: 'Optional[Dict[str, Any]]' = None, **kwargs: 'Any') -> 'Self'
| Return a copy with :func:`_expression.bindparam` elements
| replaced.
|
| Same functionality as :meth:`_expression.ClauseElement.params`,
| except adds `unique=True`
| to affected bind parameters so that multiple statements can be
| used.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.elements.ClauseElement:
|
| is_clause_element = True
|
| is_dml = False
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.cache_key.HasCacheKey:
|
| inherit_cache = None
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_instancemethod(fn: '_F') -> '_F'
| Decorate a method memoize its return value.
|
| :meta private:
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_attribute = <class 'sqlalchemy.util.langhelpers.HasMemoized.m...
| A read-only @property that is only evaluated once.
|
| :meta private:
|
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.visitors.HasTraverseInternals:
|
| get_children(self, *, omit_attrs: 'Tuple[str, ...]' = (), **kw: 'Any') -> 'Iterable[HasTraverseInternals]'
| Return immediate child :class:`.visitors.HasTraverseInternals`
| elements of this :class:`.visitors.HasTraverseInternals`.
|
| This is used for visit traversal.
|
| \**kw may contain flags that change the collection that is
| returned, for example to return a subset of items in order to
| cut down on larger traversals, or to return child items from a
| different context (such as schema-level collections instead of
| clause-level).
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.elements.CompilerElement:
|
| __str__(self) -> 'str'
| Return str(self).
|
| compile(self, bind: 'Optional[_HasDialect]' = None, dialect: 'Optional[Dialect]' = None, **kw: 'Any') -> 'Compiled'
| Compile this SQL expression.
|
| The return value is a :class:`~.Compiled` object.
| Calling ``str()`` or ``unicode()`` on the returned value will yield a
| string representation of the result. The
| :class:`~.Compiled` object also can return a
| dictionary of bind parameter names and values
| using the ``params`` accessor.
|
| :param bind: An :class:`.Connection` or :class:`.Engine` which
| can provide a :class:`.Dialect` in order to generate a
| :class:`.Compiled` object. If the ``bind`` and
| ``dialect`` parameters are both omitted, a default SQL compiler
| is used.
|
| :param column_keys: Used for INSERT and UPDATE statements, a list of
| column names which should be present in the VALUES clause of the
| compiled statement. If ``None``, all columns from the target table
| object are rendered.
|
| :param dialect: A :class:`.Dialect` instance which can generate
| a :class:`.Compiled` object. This argument takes precedence over
| the ``bind`` argument.
|
| :param compile_kwargs: optional dictionary of additional parameters
| that will be passed through to the compiler within all "visit"
| methods. This allows any custom flag to be passed through to
| a custom compilation construct, for example. It is also used
| for the case of passing the ``literal_binds`` flag through::
|
| from sqlalchemy.sql import table, column, select
|
| t = table("t", column("x"))
|
| s = select(t).where(t.c.x == 5)
|
| print(s.compile(compile_kwargs={"literal_binds": True}))
|
| .. seealso::
|
| :ref:`faq_sql_expression_string`
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.elements.CompilerElement:
|
| stringify_dialect = 'default'
|
| supports_execution = False
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.visitors.Visitable:
|
| __class_getitem__(key: 'Any') -> 'Any'
|
| __init_subclass__() -> 'None'
| This method is called when a class is subclassed.
|
| The default implementation does nothing. It may be
| overridden to extend subclasses.
sqlalchemy.LABEL_STYLE_DEFAULT
Python Library Documentation: SelectLabelStyle in module sqlalchemy.sql.selectable object class SelectLabelStyle(enum.Enum) | SelectLabelStyle(*values) | | Label style constants that may be passed to | :meth:`_sql.Select.set_label_style`. | | Method resolution order: | SelectLabelStyle | enum.Enum | builtins.object | | Data and other attributes defined here: | | LABEL_STYLE_DISAMBIGUATE_ONLY = <SelectLabelStyle.LABEL_STYLE_DISAMBIG... | | LABEL_STYLE_LEGACY_ORM = <SelectLabelStyle.LABEL_STYLE_LEGACY_ORM: 3> | | LABEL_STYLE_NONE = <SelectLabelStyle.LABEL_STYLE_NONE: 0> | | LABEL_STYLE_TABLENAME_PLUS_COL = <SelectLabelStyle.LABEL_STYLE_TABLENA... | | ---------------------------------------------------------------------- | Data descriptors inherited from enum.Enum: | | name | The name of the Enum member. | | value | The value of the Enum member. | | ---------------------------------------------------------------------- | Static methods inherited from enum.EnumType: | | __contains__(value) | Return True if `value` is in `cls`. | | `value` is in `cls` if: | 1) `value` is a member of `cls`, or | 2) `value` is the value of one of the `cls`'s members. | | __getitem__(name) | Return the member matching `name`. | | __iter__() | Return members in definition order. | | __len__() | Return the number of members (no aliases) | | ---------------------------------------------------------------------- | Readonly properties inherited from enum.EnumType: | | __members__ | Returns a mapping of member name->value. | | This mapping lists all enum members, including aliases. Note that this | is a read-only view of the internal mapping.
sqlalchemy.LABEL_STYLE_DISAMBIGUATE_ONLY
Python Library Documentation: SelectLabelStyle in module sqlalchemy.sql.selectable object class SelectLabelStyle(enum.Enum) | SelectLabelStyle(*values) | | Label style constants that may be passed to | :meth:`_sql.Select.set_label_style`. | | Method resolution order: | SelectLabelStyle | enum.Enum | builtins.object | | Data and other attributes defined here: | | LABEL_STYLE_DISAMBIGUATE_ONLY = <SelectLabelStyle.LABEL_STYLE_DISAMBIG... | | LABEL_STYLE_LEGACY_ORM = <SelectLabelStyle.LABEL_STYLE_LEGACY_ORM: 3> | | LABEL_STYLE_NONE = <SelectLabelStyle.LABEL_STYLE_NONE: 0> | | LABEL_STYLE_TABLENAME_PLUS_COL = <SelectLabelStyle.LABEL_STYLE_TABLENA... | | ---------------------------------------------------------------------- | Data descriptors inherited from enum.Enum: | | name | The name of the Enum member. | | value | The value of the Enum member. | | ---------------------------------------------------------------------- | Static methods inherited from enum.EnumType: | | __contains__(value) | Return True if `value` is in `cls`. | | `value` is in `cls` if: | 1) `value` is a member of `cls`, or | 2) `value` is the value of one of the `cls`'s members. | | __getitem__(name) | Return the member matching `name`. | | __iter__() | Return members in definition order. | | __len__() | Return the number of members (no aliases) | | ---------------------------------------------------------------------- | Readonly properties inherited from enum.EnumType: | | __members__ | Returns a mapping of member name->value. | | This mapping lists all enum members, including aliases. Note that this | is a read-only view of the internal mapping.
sqlalchemy.LABEL_STYLE_NONE
Python Library Documentation: SelectLabelStyle in module sqlalchemy.sql.selectable object class SelectLabelStyle(enum.Enum) | SelectLabelStyle(*values) | | Label style constants that may be passed to | :meth:`_sql.Select.set_label_style`. | | Method resolution order: | SelectLabelStyle | enum.Enum | builtins.object | | Data and other attributes defined here: | | LABEL_STYLE_DISAMBIGUATE_ONLY = <SelectLabelStyle.LABEL_STYLE_DISAMBIG... | | LABEL_STYLE_LEGACY_ORM = <SelectLabelStyle.LABEL_STYLE_LEGACY_ORM: 3> | | LABEL_STYLE_NONE = <SelectLabelStyle.LABEL_STYLE_NONE: 0> | | LABEL_STYLE_TABLENAME_PLUS_COL = <SelectLabelStyle.LABEL_STYLE_TABLENA... | | ---------------------------------------------------------------------- | Data descriptors inherited from enum.Enum: | | name | The name of the Enum member. | | value | The value of the Enum member. | | ---------------------------------------------------------------------- | Static methods inherited from enum.EnumType: | | __contains__(value) | Return True if `value` is in `cls`. | | `value` is in `cls` if: | 1) `value` is a member of `cls`, or | 2) `value` is the value of one of the `cls`'s members. | | __getitem__(name) | Return the member matching `name`. | | __iter__() | Return members in definition order. | | __len__() | Return the number of members (no aliases) | | ---------------------------------------------------------------------- | Readonly properties inherited from enum.EnumType: | | __members__ | Returns a mapping of member name->value. | | This mapping lists all enum members, including aliases. Note that this | is a read-only view of the internal mapping.
sqlalchemy.LABEL_STYLE_TABLENAME_PLUS_COL
Python Library Documentation: SelectLabelStyle in module sqlalchemy.sql.selectable object class SelectLabelStyle(enum.Enum) | SelectLabelStyle(*values) | | Label style constants that may be passed to | :meth:`_sql.Select.set_label_style`. | | Method resolution order: | SelectLabelStyle | enum.Enum | builtins.object | | Data and other attributes defined here: | | LABEL_STYLE_DISAMBIGUATE_ONLY = <SelectLabelStyle.LABEL_STYLE_DISAMBIG... | | LABEL_STYLE_LEGACY_ORM = <SelectLabelStyle.LABEL_STYLE_LEGACY_ORM: 3> | | LABEL_STYLE_NONE = <SelectLabelStyle.LABEL_STYLE_NONE: 0> | | LABEL_STYLE_TABLENAME_PLUS_COL = <SelectLabelStyle.LABEL_STYLE_TABLENA... | | ---------------------------------------------------------------------- | Data descriptors inherited from enum.Enum: | | name | The name of the Enum member. | | value | The value of the Enum member. | | ---------------------------------------------------------------------- | Static methods inherited from enum.EnumType: | | __contains__(value) | Return True if `value` is in `cls`. | | `value` is in `cls` if: | 1) `value` is a member of `cls`, or | 2) `value` is the value of one of the `cls`'s members. | | __getitem__(name) | Return the member matching `name`. | | __iter__() | Return members in definition order. | | __len__() | Return the number of members (no aliases) | | ---------------------------------------------------------------------- | Readonly properties inherited from enum.EnumType: | | __members__ | Returns a mapping of member name->value. | | This mapping lists all enum members, including aliases. Note that this | is a read-only view of the internal mapping.
sqlalchemy.Label
Python Library Documentation: class Label in module sqlalchemy.sql.elements
class Label(sqlalchemy.sql.roles.LabeledColumnExprRole, NamedColumn)
| Label(name: 'Optional[str]', element: '_ColumnExpressionArgument[_T]', type_: 'Optional[_TypeEngineArgument[_T]]' = None)
|
| Represents a column label (AS).
|
| Represent a label, as typically applied to any column-level
| element using the ``AS`` sql keyword.
|
| Method resolution order:
| Label
| sqlalchemy.sql.roles.LabeledColumnExprRole
| NamedColumn
| KeyedColumnElement
| ColumnElement
| sqlalchemy.sql.roles.ColumnArgumentOrKeyRole
| sqlalchemy.sql.roles.ColumnArgumentRole
| sqlalchemy.sql.roles.StatementOptionRole
| sqlalchemy.sql.roles.WhereHavingRole
| sqlalchemy.sql.roles.OnClauseRole
| sqlalchemy.sql.roles.BinaryElementRole
| sqlalchemy.sql.roles.OrderByRole
| sqlalchemy.sql.roles.ColumnsClauseRole
| sqlalchemy.sql.roles.AllowsLambdaRole
| sqlalchemy.sql.roles.ByOfRole
| sqlalchemy.sql.roles.UsesInspection
| sqlalchemy.sql.roles.ColumnListRole
| sqlalchemy.sql.roles.LimitOffsetRole
| sqlalchemy.sql.roles.DMLColumnRole
| sqlalchemy.sql.roles.DDLConstraintColumnRole
| sqlalchemy.sql.roles.DDLExpressionRole
| sqlalchemy.sql.roles.StructuralRole
| SQLColumnExpression
| SQLCoreOperations
| sqlalchemy.sql.roles.ExpressionElementRole
| sqlalchemy.sql.roles.TypedColumnsClauseRole
| typing.Generic
| sqlalchemy.sql.operators.ColumnOperators
| sqlalchemy.sql.operators.Operators
| sqlalchemy.util.langhelpers.TypingOnly
| sqlalchemy.sql.roles.SQLRole
| DQLDMLClauseElement
| ClauseElement
| sqlalchemy.sql.annotation.SupportsWrappingAnnotations
| sqlalchemy.sql.annotation.SupportsAnnotations
| sqlalchemy.sql.cache_key.MemoizedHasCacheKey
| sqlalchemy.sql.cache_key.HasCacheKey
| sqlalchemy.util.langhelpers.HasMemoized
| sqlalchemy.sql.traversals.HasCopyInternals
| sqlalchemy.sql.visitors.ExternallyTraversible
| sqlalchemy.sql.visitors.HasTraverseInternals
| CompilerElement
| sqlalchemy.sql.visitors.Visitable
| builtins.object
|
| Methods defined here:
|
| __init__(self, name: 'Optional[str]', element: '_ColumnExpressionArgument[_T]', type_: 'Optional[_TypeEngineArgument[_T]]' = None)
| Initialize self. See help(type(self)) for accurate signature.
|
| __reduce__(self)
| Helper for pickle.
|
| element(...)
|
| self_group(self, against: 'Optional[OperatorType]' = None) -> 'Label[_T]'
| 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.
|
| ----------------------------------------------------------------------
| Readonly properties defined here:
|
| foreign_keys
|
| primary_key
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'_element': 'ColumnElement[_T]', '_traverse_interna...
|
| __orig_bases__ = (sqlalchemy.sql.roles.LabeledColumnExprRole[~_T], sql...
|
| __parameters__ = (~_T,)
|
| __visit_name__ = 'label'
|
| ----------------------------------------------------------------------
| Methods inherited from NamedColumn:
|
| description(...)
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from NamedColumn:
|
| is_literal = False
|
| table = None
|
| ----------------------------------------------------------------------
| Methods inherited from ColumnElement:
|
| __getattr__(self, key: 'str') -> 'Any'
|
| __setstate__(self, state)
|
| base_columns(...)
|
| cast(self, type_: '_TypeEngineArgument[_OPT]') -> 'Cast[_OPT]'
| Produce a type cast, i.e. ``CAST(<expression> AS <type>)``.
|
| This is a shortcut to the :func:`_expression.cast` function.
|
| .. seealso::
|
| :ref:`tutorial_casts`
|
| :func:`_expression.cast`
|
| :func:`_expression.type_coerce`
|
| comparator(...)
|
| label(self, name: 'Optional[str]') -> 'Label[_T]'
| Produce a column label, i.e. ``<columnname> AS <name>``.
|
| This is a shortcut to the :func:`_expression.label` function.
|
| If 'name' is ``None``, an anonymous label name will be generated.
|
| operate(self, op: 'operators.OperatorType', *other: 'Any', **kwargs: 'Any') -> 'ColumnElement[Any]'
| Operate on an argument.
|
| This is the lowest level of operation, raises
| :class:`NotImplementedError` by default.
|
| Overriding this on a subclass can allow common
| behavior to be applied to all operations.
| For example, overriding :class:`.ColumnOperators`
| to apply ``func.lower()`` to the left and right
| side::
|
| class MyComparator(ColumnOperators):
| def operate(self, op, other, **kwargs):
| return op(func.lower(self), func.lower(other), **kwargs)
|
| :param op: Operator callable.
| :param \*other: the 'other' side of the operation. Will
| be a single scalar for most operations.
| :param \**kwargs: modifiers. These may be passed by special
| operators such as :meth:`ColumnOperators.contains`.
|
| proxy_set(...)
| set of all columns we are proxying
|
| as of 2.0 this is explicitly deannotated columns. previously it was
| effectively deannotated columns but wasn't enforced. annotated
| columns should basically not go into sets if at all possible because
| their hashing behavior is very non-performant.
|
| reverse_operate(self, op: 'operators.OperatorType', other: 'Any', **kwargs: 'Any') -> 'ColumnElement[Any]'
| Reverse operate on an argument.
|
| Usage is the same as :meth:`operate`.
|
| shares_lineage(self, othercolumn: 'ColumnElement[Any]') -> 'bool'
| Return True if the given :class:`_expression.ColumnElement`
| has a common ancestor to this :class:`_expression.ColumnElement`.
|
| type(...)
|
| ----------------------------------------------------------------------
| Readonly properties inherited from ColumnElement:
|
| anon_key_label
| .. deprecated:: 1.4 The :attr:`_expression.ColumnElement.anon_key_label` attribute is now private, and the public accessor is deprecated.
|
| anon_label
| .. deprecated:: 1.4 The :attr:`_expression.ColumnElement.anon_label` attribute is now private, and the public accessor is deprecated.
|
| expression
| Return a column expression.
|
| Part of the inspection interface; returns self.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from ColumnElement:
|
| key = None
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.AllowsLambdaRole:
|
| allows_lambda = True
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.UsesInspection:
|
| uses_inspection = True
|
| ----------------------------------------------------------------------
| Class methods inherited from typing.Generic:
|
| __class_getitem__(...)
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__(...)
| Function to initialize subclasses.
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.operators.ColumnOperators:
|
| __add__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``+`` operator.
|
| In a column context, produces the clause ``a + b``
| if the parent object has non-string affinity.
| If the parent object has a string affinity,
| produces the concatenation operator, ``a || b`` -
| see :meth:`.ColumnOperators.concat`.
|
| __contains__(self, other: 'Any') -> 'ColumnOperators'
|
| __eq__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``==`` operator.
|
| In a column context, produces the clause ``a = b``.
| If the target is ``None``, produces ``a IS NULL``.
|
| __floordiv__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``//`` operator.
|
| In a column context, produces the clause ``a / b``,
| which is the same as "truediv", but considers the result
| type to be integer.
|
| .. versionadded:: 2.0
|
| __ge__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``>=`` operator.
|
| In a column context, produces the clause ``a >= b``.
|
| __getitem__(self, index: 'Any') -> 'ColumnOperators'
| Implement the [] operator.
|
| This can be used by some database-specific types
| such as PostgreSQL ARRAY and HSTORE.
|
| __gt__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``>`` operator.
|
| In a column context, produces the clause ``a > b``.
|
| __hash__(self, /) from builtins.object
| Return hash(self).
|
| __le__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``<=`` operator.
|
| In a column context, produces the clause ``a <= b``.
|
| __lshift__(self, other: 'Any') -> 'ColumnOperators'
| implement the << operator.
|
| Not used by SQLAlchemy core, this is provided
| for custom operator systems which want to use
| << as an extension point.
|
| __lt__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``<`` operator.
|
| In a column context, produces the clause ``a < b``.
|
| __mod__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``%`` operator.
|
| In a column context, produces the clause ``a % b``.
|
| __mul__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``*`` operator.
|
| In a column context, produces the clause ``a * b``.
|
| __ne__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``!=`` operator.
|
| In a column context, produces the clause ``a != b``.
| If the target is ``None``, produces ``a IS NOT NULL``.
|
| __neg__(self) -> 'ColumnOperators'
| Implement the ``-`` operator.
|
| In a column context, produces the clause ``-a``.
|
| __radd__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``+`` operator in reverse.
|
| See :meth:`.ColumnOperators.__add__`.
|
| __rfloordiv__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``//`` operator in reverse.
|
| See :meth:`.ColumnOperators.__floordiv__`.
|
| __rmod__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``%`` operator in reverse.
|
| See :meth:`.ColumnOperators.__mod__`.
|
| __rmul__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``*`` operator in reverse.
|
| See :meth:`.ColumnOperators.__mul__`.
|
| __rshift__(self, other: 'Any') -> 'ColumnOperators'
| implement the >> operator.
|
| Not used by SQLAlchemy core, this is provided
| for custom operator systems which want to use
| >> as an extension point.
|
| __rsub__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``-`` operator in reverse.
|
| See :meth:`.ColumnOperators.__sub__`.
|
| __rtruediv__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``/`` operator in reverse.
|
| See :meth:`.ColumnOperators.__truediv__`.
|
| __sub__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``-`` operator.
|
| In a column context, produces the clause ``a - b``.
|
| __truediv__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``/`` operator.
|
| In a column context, produces the clause ``a / b``, and
| considers the result type to be numeric.
|
| .. versionchanged:: 2.0 The truediv operator against two integers
| is now considered to return a numeric value. Behavior on specific
| backends may vary.
|
| all_(self) -> 'ColumnOperators'
| Produce an :func:`_expression.all_` clause against the
| parent object.
|
| See the documentation for :func:`_sql.all_` for examples.
|
| .. note:: be sure to not confuse the newer
| :meth:`_sql.ColumnOperators.all_` method with the **legacy**
| version of this method, the :meth:`_types.ARRAY.Comparator.all`
| method that's specific to :class:`_types.ARRAY`, which uses a
| different calling style.
|
| any_(self) -> 'ColumnOperators'
| Produce an :func:`_expression.any_` clause against the
| parent object.
|
| See the documentation for :func:`_sql.any_` for examples.
|
| .. note:: be sure to not confuse the newer
| :meth:`_sql.ColumnOperators.any_` method with the **legacy**
| version of this method, the :meth:`_types.ARRAY.Comparator.any`
| method that's specific to :class:`_types.ARRAY`, which uses a
| different calling style.
|
| asc(self) -> 'ColumnOperators'
| Produce a :func:`_expression.asc` clause against the
| parent object.
|
| between(self, cleft: 'Any', cright: 'Any', symmetric: 'bool' = False) -> 'ColumnOperators'
| Produce a :func:`_expression.between` clause against
| the parent object, given the lower and upper range.
|
| bitwise_and(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise AND operation, typically via the ``&``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_lshift(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise LSHIFT operation, typically via the ``<<``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_not(self) -> 'ColumnOperators'
| Produce a bitwise NOT operation, typically via the ``~``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_or(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise OR operation, typically via the ``|``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_rshift(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise RSHIFT operation, typically via the ``>>``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_xor(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise XOR operation, typically via the ``^``
| operator, or ``#`` for PostgreSQL.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| collate(self, collation: 'str') -> 'ColumnOperators'
| Produce a :func:`_expression.collate` clause against
| the parent object, given the collation string.
|
| .. seealso::
|
| :func:`_expression.collate`
|
| concat(self, other: 'Any') -> 'ColumnOperators'
| Implement the 'concat' operator.
|
| In a column context, produces the clause ``a || b``,
| or uses the ``concat()`` operator on MySQL.
|
| contains(self, other: 'Any', **kw: 'Any') -> 'ColumnOperators'
| Implement the 'contains' operator.
|
| Produces a LIKE expression that tests against a match for the middle
| of a string value:
|
| .. sourcecode:: sql
|
| column LIKE '%' || <other> || '%'
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.contains("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.contains.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.contains.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.contains.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.contains("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE '%' || :param || '%' ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.contains("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE '%' || :param || '%' ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.contains.autoescape`::
|
| somecolumn.contains("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.startswith`
|
| :meth:`.ColumnOperators.endswith`
|
| :meth:`.ColumnOperators.like`
|
| desc(self) -> 'ColumnOperators'
| Produce a :func:`_expression.desc` clause against the
| parent object.
|
| distinct(self) -> 'ColumnOperators'
| Produce a :func:`_expression.distinct` clause against the
| parent object.
|
| endswith(self, other: 'Any', escape: 'Optional[str]' = None, autoescape: 'bool' = False) -> 'ColumnOperators'
| Implement the 'endswith' operator.
|
| Produces a LIKE expression that tests against a match for the end
| of a string value:
|
| .. sourcecode:: sql
|
| column LIKE '%' || <other>
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.endswith("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.endswith.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.endswith.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.endswith.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.endswith("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE '%' || :param ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.endswith("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE '%' || :param ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.endswith.autoescape`::
|
| somecolumn.endswith("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.startswith`
|
| :meth:`.ColumnOperators.contains`
|
| :meth:`.ColumnOperators.like`
|
| icontains(self, other: 'Any', **kw: 'Any') -> 'ColumnOperators'
| Implement the ``icontains`` operator, e.g. case insensitive
| version of :meth:`.ColumnOperators.contains`.
|
| Produces a LIKE expression that tests against an insensitive match
| for the middle of a string value:
|
| .. sourcecode:: sql
|
| lower(column) LIKE '%' || lower(<other>) || '%'
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.icontains("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.icontains.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.icontains.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.icontains.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.icontains("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE '%' || lower(:param) || '%' ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.icontains("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE '%' || lower(:param) || '%' ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.contains.autoescape`::
|
| somecolumn.icontains("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.contains`
|
| iendswith(self, other: 'Any', escape: 'Optional[str]' = None, autoescape: 'bool' = False) -> 'ColumnOperators'
| Implement the ``iendswith`` operator, e.g. case insensitive
| version of :meth:`.ColumnOperators.endswith`.
|
| Produces a LIKE expression that tests against an insensitive match
| for the end of a string value:
|
| .. sourcecode:: sql
|
| lower(column) LIKE '%' || lower(<other>)
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.iendswith("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.iendswith.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.iendswith.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.iendswith.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.iendswith("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE '%' || lower(:param) ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.iendswith("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE '%' || lower(:param) ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.iendswith.autoescape`::
|
| somecolumn.endswith("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.endswith`
|
| ilike(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
| Implement the ``ilike`` operator, e.g. case insensitive LIKE.
|
| In a column context, produces an expression either of the form:
|
| .. sourcecode:: sql
|
| lower(a) LIKE lower(other)
|
| Or on backends that support the ILIKE operator:
|
| .. sourcecode:: sql
|
| a ILIKE other
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.ilike("%foobar%"))
|
| :param other: expression to be compared
| :param escape: optional escape character, renders the ``ESCAPE``
| keyword, e.g.::
|
| somecolumn.ilike("foo/%bar", escape="/")
|
| .. seealso::
|
| :meth:`.ColumnOperators.like`
|
| in_(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``in`` operator.
|
| In a column context, produces the clause ``column IN <other>``.
|
| The given parameter ``other`` may be:
|
| * A list of literal values,
| e.g.::
|
| stmt.where(column.in_([1, 2, 3]))
|
| In this calling form, the list of items is converted to a set of
| bound parameters the same length as the list given:
|
| .. sourcecode:: sql
|
| WHERE COL IN (?, ?, ?)
|
| * A list of tuples may be provided if the comparison is against a
| :func:`.tuple_` containing multiple expressions::
|
| from sqlalchemy import tuple_
|
| stmt.where(tuple_(col1, col2).in_([(1, 10), (2, 20), (3, 30)]))
|
| * An empty list,
| e.g.::
|
| stmt.where(column.in_([]))
|
| In this calling form, the expression renders an "empty set"
| expression. These expressions are tailored to individual backends
| and are generally trying to get an empty SELECT statement as a
| subquery. Such as on SQLite, the expression is:
|
| .. sourcecode:: sql
|
| WHERE col IN (SELECT 1 FROM (SELECT 1) WHERE 1!=1)
|
| .. versionchanged:: 1.4 empty IN expressions now use an
| execution-time generated SELECT subquery in all cases.
|
| * A bound parameter, e.g. :func:`.bindparam`, may be used if it
| includes the :paramref:`.bindparam.expanding` flag::
|
| stmt.where(column.in_(bindparam("value", expanding=True)))
|
| In this calling form, the expression renders a special non-SQL
| placeholder expression that looks like:
|
| .. sourcecode:: sql
|
| WHERE COL IN ([EXPANDING_value])
|
| This placeholder expression is intercepted at statement execution
| time to be converted into the variable number of bound parameter
| form illustrated earlier. If the statement were executed as::
|
| connection.execute(stmt, {"value": [1, 2, 3]})
|
| The database would be passed a bound parameter for each value:
|
| .. sourcecode:: sql
|
| WHERE COL IN (?, ?, ?)
|
| .. versionadded:: 1.2 added "expanding" bound parameters
|
| If an empty list is passed, a special "empty list" expression,
| which is specific to the database in use, is rendered. On
| SQLite this would be:
|
| .. sourcecode:: sql
|
| WHERE COL IN (SELECT 1 FROM (SELECT 1) WHERE 1!=1)
|
| .. versionadded:: 1.3 "expanding" bound parameters now support
| empty lists
|
| * a :func:`_expression.select` construct, which is usually a
| correlated scalar select::
|
| stmt.where(
| column.in_(select(othertable.c.y).where(table.c.x == othertable.c.x))
| )
|
| In this calling form, :meth:`.ColumnOperators.in_` renders as given:
|
| .. sourcecode:: sql
|
| WHERE COL IN (SELECT othertable.y
| FROM othertable WHERE othertable.x = table.x)
|
| :param other: a list of literals, a :func:`_expression.select`
| construct, or a :func:`.bindparam` construct that includes the
| :paramref:`.bindparam.expanding` flag set to True.
|
| is_(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``IS`` operator.
|
| Normally, ``IS`` is generated automatically when comparing to a
| value of ``None``, which resolves to ``NULL``. However, explicit
| usage of ``IS`` may be desirable if comparing to boolean values
| on certain platforms.
|
| .. seealso:: :meth:`.ColumnOperators.is_not`
|
| is_distinct_from(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``IS DISTINCT FROM`` operator.
|
| Renders "a IS DISTINCT FROM b" on most platforms;
| on some such as SQLite may render "a IS NOT b".
|
| is_not(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``IS NOT`` operator.
|
| Normally, ``IS NOT`` is generated automatically when comparing to a
| value of ``None``, which resolves to ``NULL``. However, explicit
| usage of ``IS NOT`` may be desirable if comparing to boolean values
| on certain platforms.
|
| .. versionchanged:: 1.4 The ``is_not()`` operator is renamed from
| ``isnot()`` in previous releases. The previous name remains
| available for backwards compatibility.
|
| .. seealso:: :meth:`.ColumnOperators.is_`
|
| is_not_distinct_from(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``IS NOT DISTINCT FROM`` operator.
|
| Renders "a IS NOT DISTINCT FROM b" on most platforms;
| on some such as SQLite may render "a IS b".
|
| .. versionchanged:: 1.4 The ``is_not_distinct_from()`` operator is
| renamed from ``isnot_distinct_from()`` in previous releases.
| The previous name remains available for backwards compatibility.
|
| isnot = is_not(self, other: 'Any') -> 'ColumnOperators'
|
| isnot_distinct_from = is_not_distinct_from(self, other: 'Any') -> 'ColumnOperators'
|
| istartswith(self, other: 'Any', escape: 'Optional[str]' = None, autoescape: 'bool' = False) -> 'ColumnOperators'
| Implement the ``istartswith`` operator, e.g. case insensitive
| version of :meth:`.ColumnOperators.startswith`.
|
| Produces a LIKE expression that tests against an insensitive
| match for the start of a string value:
|
| .. sourcecode:: sql
|
| lower(column) LIKE lower(<other>) || '%'
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.istartswith("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.istartswith.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.istartswith.escape` parameter will
| establish a given character as an escape character which can be of
| use when the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.istartswith.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.istartswith("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE lower(:param) || '%' ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.istartswith("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE lower(:param) || '%' ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.istartswith.autoescape`::
|
| somecolumn.istartswith("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.startswith`
|
| like(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
| Implement the ``like`` operator.
|
| In a column context, produces the expression:
|
| .. sourcecode:: sql
|
| a LIKE other
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.like("%foobar%"))
|
| :param other: expression to be compared
| :param escape: optional escape character, renders the ``ESCAPE``
| keyword, e.g.::
|
| somecolumn.like("foo/%bar", escape="/")
|
| .. seealso::
|
| :meth:`.ColumnOperators.ilike`
|
| match(self, other: 'Any', **kwargs: 'Any') -> 'ColumnOperators'
| Implements a database-specific 'match' operator.
|
| :meth:`_sql.ColumnOperators.match` attempts to resolve to
| a MATCH-like function or operator provided by the backend.
| Examples include:
|
| * PostgreSQL - renders ``x @@ plainto_tsquery(y)``
|
| .. versionchanged:: 2.0 ``plainto_tsquery()`` is used instead
| of ``to_tsquery()`` for PostgreSQL now; for compatibility with
| other forms, see :ref:`postgresql_match`.
|
|
| * MySQL - renders ``MATCH (x) AGAINST (y IN BOOLEAN MODE)``
|
| .. seealso::
|
| :class:`_mysql.match` - MySQL specific construct with
| additional features.
|
| * Oracle Database - renders ``CONTAINS(x, y)``
| * other backends may provide special implementations.
| * Backends without any special implementation will emit
| the operator as "MATCH". This is compatible with SQLite, for
| example.
|
| not_ilike(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
| implement the ``NOT ILIKE`` operator.
|
| This is equivalent to using negation with
| :meth:`.ColumnOperators.ilike`, i.e. ``~x.ilike(y)``.
|
| .. versionchanged:: 1.4 The ``not_ilike()`` operator is renamed from
| ``notilike()`` in previous releases. The previous name remains
| available for backwards compatibility.
|
| .. seealso::
|
| :meth:`.ColumnOperators.ilike`
|
| not_in(self, other: 'Any') -> 'ColumnOperators'
| implement the ``NOT IN`` operator.
|
| This is equivalent to using negation with
| :meth:`.ColumnOperators.in_`, i.e. ``~x.in_(y)``.
|
| In the case that ``other`` is an empty sequence, the compiler
| produces an "empty not in" expression. This defaults to the
| expression "1 = 1" to produce true in all cases. The
| :paramref:`_sa.create_engine.empty_in_strategy` may be used to
| alter this behavior.
|
| .. versionchanged:: 1.4 The ``not_in()`` operator is renamed from
| ``notin_()`` in previous releases. The previous name remains
| available for backwards compatibility.
|
| .. versionchanged:: 1.2 The :meth:`.ColumnOperators.in_` and
| :meth:`.ColumnOperators.not_in` operators
| now produce a "static" expression for an empty IN sequence
| by default.
|
| .. seealso::
|
| :meth:`.ColumnOperators.in_`
|
| not_like(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
| implement the ``NOT LIKE`` operator.
|
| This is equivalent to using negation with
| :meth:`.ColumnOperators.like`, i.e. ``~x.like(y)``.
|
| .. versionchanged:: 1.4 The ``not_like()`` operator is renamed from
| ``notlike()`` in previous releases. The previous name remains
| available for backwards compatibility.
|
| .. seealso::
|
| :meth:`.ColumnOperators.like`
|
| notilike = not_ilike(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
|
| notin_ = not_in(self, other: 'Any') -> 'ColumnOperators'
|
| notlike = not_like(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
|
| nulls_first(self) -> 'ColumnOperators'
| Produce a :func:`_expression.nulls_first` clause against the
| parent object.
|
| .. versionchanged:: 1.4 The ``nulls_first()`` operator is
| renamed from ``nullsfirst()`` in previous releases.
| The previous name remains available for backwards compatibility.
|
| nulls_last(self) -> 'ColumnOperators'
| Produce a :func:`_expression.nulls_last` clause against the
| parent object.
|
| .. versionchanged:: 1.4 The ``nulls_last()`` operator is
| renamed from ``nullslast()`` in previous releases.
| The previous name remains available for backwards compatibility.
|
| nullsfirst = nulls_first(self) -> 'ColumnOperators'
|
| nullslast = nulls_last(self) -> 'ColumnOperators'
|
| regexp_match(self, pattern: 'Any', flags: 'Optional[str]' = None) -> 'ColumnOperators'
| Implements a database-specific 'regexp match' operator.
|
| E.g.::
|
| stmt = select(table.c.some_column).where(
| table.c.some_column.regexp_match("^(b|c)")
| )
|
| :meth:`_sql.ColumnOperators.regexp_match` attempts to resolve to
| a REGEXP-like function or operator provided by the backend, however
| the specific regular expression syntax and flags available are
| **not backend agnostic**.
|
| Examples include:
|
| * PostgreSQL - renders ``x ~ y`` or ``x !~ y`` when negated.
| * Oracle Database - renders ``REGEXP_LIKE(x, y)``
| * SQLite - uses SQLite's ``REGEXP`` placeholder operator and calls into
| the Python ``re.match()`` builtin.
| * other backends may provide special implementations.
| * Backends without any special implementation will emit
| the operator as "REGEXP" or "NOT REGEXP". This is compatible with
| SQLite and MySQL, for example.
|
| Regular expression support is currently implemented for Oracle
| Database, PostgreSQL, MySQL and MariaDB. Partial support is available
| for SQLite. Support among third-party dialects may vary.
|
| :param pattern: The regular expression pattern string or column
| clause.
| :param flags: Any regular expression string flags to apply, passed as
| plain Python string only. These flags are backend specific.
| Some backends, like PostgreSQL and MariaDB, may alternatively
| specify the flags as part of the pattern.
| When using the ignore case flag 'i' in PostgreSQL, the ignore case
| regexp match operator ``~*`` or ``!~*`` will be used.
|
| .. versionadded:: 1.4
|
| .. versionchanged:: 1.4.48, 2.0.18 Note that due to an implementation
| error, the "flags" parameter previously accepted SQL expression
| objects such as column expressions in addition to plain Python
| strings. This implementation did not work correctly with caching
| and was removed; strings only should be passed for the "flags"
| parameter, as these flags are rendered as literal inline values
| within SQL expressions.
|
| .. seealso::
|
| :meth:`_sql.ColumnOperators.regexp_replace`
|
| regexp_replace(self, pattern: 'Any', replacement: 'Any', flags: 'Optional[str]' = None) -> 'ColumnOperators'
| Implements a database-specific 'regexp replace' operator.
|
| E.g.::
|
| stmt = select(
| table.c.some_column.regexp_replace("b(..)", "XY", flags="g")
| )
|
| :meth:`_sql.ColumnOperators.regexp_replace` attempts to resolve to
| a REGEXP_REPLACE-like function provided by the backend, that
| usually emit the function ``REGEXP_REPLACE()``. However,
| the specific regular expression syntax and flags available are
| **not backend agnostic**.
|
| Regular expression replacement support is currently implemented for
| Oracle Database, PostgreSQL, MySQL 8 or greater and MariaDB. Support
| among third-party dialects may vary.
|
| :param pattern: The regular expression pattern string or column
| clause.
| :param pattern: The replacement string or column clause.
| :param flags: Any regular expression string flags to apply, passed as
| plain Python string only. These flags are backend specific.
| Some backends, like PostgreSQL and MariaDB, may alternatively
| specify the flags as part of the pattern.
|
| .. versionadded:: 1.4
|
| .. versionchanged:: 1.4.48, 2.0.18 Note that due to an implementation
| error, the "flags" parameter previously accepted SQL expression
| objects such as column expressions in addition to plain Python
| strings. This implementation did not work correctly with caching
| and was removed; strings only should be passed for the "flags"
| parameter, as these flags are rendered as literal inline values
| within SQL expressions.
|
|
| .. seealso::
|
| :meth:`_sql.ColumnOperators.regexp_match`
|
| startswith(self, other: 'Any', escape: 'Optional[str]' = None, autoescape: 'bool' = False) -> 'ColumnOperators'
| Implement the ``startswith`` operator.
|
| Produces a LIKE expression that tests against a match for the start
| of a string value:
|
| .. sourcecode:: sql
|
| column LIKE <other> || '%'
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.startswith("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.startswith.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.startswith.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.startswith.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.startswith("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE :param || '%' ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.startswith("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE :param || '%' ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.startswith.autoescape`::
|
| somecolumn.startswith("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.endswith`
|
| :meth:`.ColumnOperators.contains`
|
| :meth:`.ColumnOperators.like`
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.operators.ColumnOperators:
|
| timetuple = None
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.operators.Operators:
|
| __and__(self, other: 'Any') -> 'Operators'
| Implement the ``&`` operator.
|
| When used with SQL expressions, results in an
| AND operation, equivalent to
| :func:`_expression.and_`, that is::
|
| a & b
|
| is equivalent to::
|
| from sqlalchemy import and_
|
| and_(a, b)
|
| Care should be taken when using ``&`` regarding
| operator precedence; the ``&`` operator has the highest precedence.
| The operands should be enclosed in parenthesis if they contain
| further sub expressions::
|
| (a == 2) & (b == 4)
|
| __invert__(self) -> 'Operators'
| Implement the ``~`` operator.
|
| When used with SQL expressions, results in a
| NOT operation, equivalent to
| :func:`_expression.not_`, that is::
|
| ~a
|
| is equivalent to::
|
| from sqlalchemy import not_
|
| not_(a)
|
| __or__(self, other: 'Any') -> 'Operators'
| Implement the ``|`` operator.
|
| When used with SQL expressions, results in an
| OR operation, equivalent to
| :func:`_expression.or_`, that is::
|
| a | b
|
| is equivalent to::
|
| from sqlalchemy import or_
|
| or_(a, b)
|
| Care should be taken when using ``|`` regarding
| operator precedence; the ``|`` operator has the highest precedence.
| The operands should be enclosed in parenthesis if they contain
| further sub expressions::
|
| (a == 2) | (b == 4)
|
| __sa_operate__ = operate(self, op: 'OperatorType', *other: 'Any', **kwargs: 'Any') -> 'Operators'
| Operate on an argument.
|
| This is the lowest level of operation, raises
| :class:`NotImplementedError` by default.
|
| Overriding this on a subclass can allow common
| behavior to be applied to all operations.
| For example, overriding :class:`.ColumnOperators`
| to apply ``func.lower()`` to the left and right
| side::
|
| class MyComparator(ColumnOperators):
| def operate(self, op, other, **kwargs):
| return op(func.lower(self), func.lower(other), **kwargs)
|
| :param op: Operator callable.
| :param \*other: the 'other' side of the operation. Will
| be a single scalar for most operations.
| :param \**kwargs: modifiers. These may be passed by special
| operators such as :meth:`ColumnOperators.contains`.
|
| bool_op(self, opstring: 'str', precedence: 'int' = 0, python_impl: 'Optional[Callable[..., Any]]' = None) -> 'Callable[[Any], Operators]'
| Return a custom boolean operator.
|
| This method is shorthand for calling
| :meth:`.Operators.op` and passing the
| :paramref:`.Operators.op.is_comparison`
| flag with True. A key advantage to using :meth:`.Operators.bool_op`
| is that when using column constructs, the "boolean" nature of the
| returned expression will be present for :pep:`484` purposes.
|
| .. seealso::
|
| :meth:`.Operators.op`
|
| op(self, opstring: 'str', precedence: 'int' = 0, is_comparison: 'bool' = False, return_type: 'Optional[Union[Type[TypeEngine[Any]], TypeEngine[Any]]]' = None, python_impl: 'Optional[Callable[..., Any]]' = None) -> 'Callable[[Any], Operators]'
| Produce a generic operator function.
|
| e.g.::
|
| somecolumn.op("*")(5)
|
| produces::
|
| somecolumn * 5
|
| This function can also be used to make bitwise operators explicit. For
| example::
|
| somecolumn.op("&")(0xFF)
|
| is a bitwise AND of the value in ``somecolumn``.
|
| :param opstring: a string which will be output as the infix operator
| between this element and the expression passed to the
| generated function.
|
| :param precedence: precedence which the database is expected to apply
| to the operator in SQL expressions. This integer value acts as a hint
| for the SQL compiler to know when explicit parenthesis should be
| rendered around a particular operation. A lower number will cause the
| expression to be parenthesized when applied against another operator
| with higher precedence. The default value of ``0`` is lower than all
| operators except for the comma (``,``) and ``AS`` operators. A value
| of 100 will be higher or equal to all operators, and -100 will be
| lower than or equal to all operators.
|
| .. seealso::
|
| :ref:`faq_sql_expression_op_parenthesis` - detailed description
| of how the SQLAlchemy SQL compiler renders parenthesis
|
| :param is_comparison: legacy; if True, the operator will be considered
| as a "comparison" operator, that is which evaluates to a boolean
| true/false value, like ``==``, ``>``, etc. This flag is provided
| so that ORM relationships can establish that the operator is a
| comparison operator when used in a custom join condition.
|
| Using the ``is_comparison`` parameter is superseded by using the
| :meth:`.Operators.bool_op` method instead; this more succinct
| operator sets this parameter automatically, but also provides
| correct :pep:`484` typing support as the returned object will
| express a "boolean" datatype, i.e. ``BinaryExpression[bool]``.
|
| :param return_type: a :class:`.TypeEngine` class or object that will
| force the return type of an expression produced by this operator
| to be of that type. By default, operators that specify
| :paramref:`.Operators.op.is_comparison` will resolve to
| :class:`.Boolean`, and those that do not will be of the same
| type as the left-hand operand.
|
| :param python_impl: an optional Python function that can evaluate
| two Python values in the same way as this operator works when
| run on the database server. Useful for in-Python SQL expression
| evaluation functions, such as for ORM hybrid attributes, and the
| ORM "evaluator" used to match objects in a session after a multi-row
| update or delete.
|
| e.g.::
|
| >>> expr = column("x").op("+", python_impl=lambda a, b: a + b)("y")
|
| The operator for the above expression will also work for non-SQL
| left and right objects::
|
| >>> expr.operator(5, 10)
| 15
|
| .. versionadded:: 2.0
|
|
| .. seealso::
|
| :meth:`.Operators.bool_op`
|
| :ref:`types_operators`
|
| :ref:`relationship_custom_operator`
|
| ----------------------------------------------------------------------
| Methods inherited from ClauseElement:
|
| __bool__(self)
|
| __getstate__(self)
| Helper for pickle.
|
| __repr__(self)
| Return repr(self).
|
| compare(self, other: 'ClauseElement', **kw: 'Any') -> 'bool'
| Compare this :class:`_expression.ClauseElement` to
| the given :class:`_expression.ClauseElement`.
|
| Subclasses should override the default behavior, which is a
| straight identity comparison.
|
| \**kw are arguments consumed by subclass ``compare()`` methods and
| may be used to modify the criteria for comparison
| (see :class:`_expression.ColumnElement`).
|
| entity_namespace(...)
|
| params(self, _ClauseElement__optionaldict: 'Optional[Mapping[str, Any]]' = None, **kwargs: 'Any') -> 'Self'
| Return a copy with :func:`_expression.bindparam` elements
| replaced.
|
| Returns a copy of this ClauseElement with
| :func:`_expression.bindparam`
| elements replaced with values taken from the given dictionary::
|
| >>> clause = column("x") + bindparam("foo")
| >>> print(clause.compile().params)
| {'foo':None}
| >>> print(clause.params({"foo": 7}).compile().params)
| {'foo':7}
|
| unique_params(self, _ClauseElement__optionaldict: 'Optional[Dict[str, Any]]' = None, **kwargs: 'Any') -> 'Self'
| Return a copy with :func:`_expression.bindparam` elements
| replaced.
|
| Same functionality as :meth:`_expression.ClauseElement.params`,
| except adds `unique=True`
| to affected bind parameters so that multiple statements can be
| used.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from ClauseElement:
|
| is_clause_element = True
|
| is_dml = False
|
| is_selectable = False
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.cache_key.HasCacheKey:
|
| inherit_cache = None
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_instancemethod(fn: '_F') -> '_F'
| Decorate a method memoize its return value.
|
| :meta private:
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_attribute = <class 'sqlalchemy.util.langhelpers.HasMemoized.m...
| A read-only @property that is only evaluated once.
|
| :meta private:
|
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.visitors.HasTraverseInternals:
|
| get_children(self, *, omit_attrs: 'Tuple[str, ...]' = (), **kw: 'Any') -> 'Iterable[HasTraverseInternals]'
| Return immediate child :class:`.visitors.HasTraverseInternals`
| elements of this :class:`.visitors.HasTraverseInternals`.
|
| This is used for visit traversal.
|
| \**kw may contain flags that change the collection that is
| returned, for example to return a subset of items in order to
| cut down on larger traversals, or to return child items from a
| different context (such as schema-level collections instead of
| clause-level).
|
| ----------------------------------------------------------------------
| Methods inherited from CompilerElement:
|
| __str__(self) -> 'str'
| Return str(self).
|
| compile(self, bind: 'Optional[_HasDialect]' = None, dialect: 'Optional[Dialect]' = None, **kw: 'Any') -> 'Compiled'
| Compile this SQL expression.
|
| The return value is a :class:`~.Compiled` object.
| Calling ``str()`` or ``unicode()`` on the returned value will yield a
| string representation of the result. The
| :class:`~.Compiled` object also can return a
| dictionary of bind parameter names and values
| using the ``params`` accessor.
|
| :param bind: An :class:`.Connection` or :class:`.Engine` which
| can provide a :class:`.Dialect` in order to generate a
| :class:`.Compiled` object. If the ``bind`` and
| ``dialect`` parameters are both omitted, a default SQL compiler
| is used.
|
| :param column_keys: Used for INSERT and UPDATE statements, a list of
| column names which should be present in the VALUES clause of the
| compiled statement. If ``None``, all columns from the target table
| object are rendered.
|
| :param dialect: A :class:`.Dialect` instance which can generate
| a :class:`.Compiled` object. This argument takes precedence over
| the ``bind`` argument.
|
| :param compile_kwargs: optional dictionary of additional parameters
| that will be passed through to the compiler within all "visit"
| methods. This allows any custom flag to be passed through to
| a custom compilation construct, for example. It is also used
| for the case of passing the ``literal_binds`` flag through::
|
| from sqlalchemy.sql import table, column, select
|
| t = table("t", column("x"))
|
| s = select(t).where(t.c.x == 5)
|
| print(s.compile(compile_kwargs={"literal_binds": True}))
|
| .. seealso::
|
| :ref:`faq_sql_expression_string`
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from CompilerElement:
|
| stringify_dialect = 'default'
|
| supports_execution = False
sqlalchemy.LambdaElement
Python Library Documentation: class LambdaElement in module sqlalchemy.sql.lambdas
class LambdaElement(sqlalchemy.sql.elements.ClauseElement)
| LambdaElement(fn: '_LambdaType', role: 'Type[SQLRole]', opts: 'Union[Type[LambdaOptions], LambdaOptions]' = <class 'sqlalchemy.sql.lambdas.LambdaOptions'>, apply_propagate_attrs: 'Optional[ClauseElement]' = None)
|
| A SQL construct where the state is stored as an un-invoked lambda.
|
| The :class:`_sql.LambdaElement` is produced transparently whenever
| passing lambda expressions into SQL constructs, such as::
|
| stmt = select(table).where(lambda: table.c.col == parameter)
|
| The :class:`_sql.LambdaElement` is the base of the
| :class:`_sql.StatementLambdaElement` which represents a full statement
| within a lambda.
|
| .. versionadded:: 1.4
|
| .. seealso::
|
| :ref:`engine_lambda_caching`
|
| Method resolution order:
| LambdaElement
| sqlalchemy.sql.elements.ClauseElement
| sqlalchemy.sql.annotation.SupportsWrappingAnnotations
| sqlalchemy.sql.annotation.SupportsAnnotations
| sqlalchemy.sql.cache_key.MemoizedHasCacheKey
| sqlalchemy.sql.cache_key.HasCacheKey
| sqlalchemy.util.langhelpers.HasMemoized
| sqlalchemy.sql.traversals.HasCopyInternals
| sqlalchemy.sql.visitors.ExternallyTraversible
| sqlalchemy.sql.visitors.HasTraverseInternals
| sqlalchemy.sql.elements.CompilerElement
| sqlalchemy.sql.visitors.Visitable
| builtins.object
|
| Methods defined here:
|
| __getattr__(self, key)
|
| __init__(self, fn: '_LambdaType', role: 'Type[SQLRole]', opts: 'Union[Type[LambdaOptions], LambdaOptions]' = <class 'sqlalchemy.sql.lambdas.LambdaOptions'>, apply_propagate_attrs: 'Optional[ClauseElement]' = None)
| Initialize self. See help(type(self)) for accurate signature.
|
| __repr__(self)
| Return repr(self).
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'_rec': 'Union[AnalyzedFunction, NonAnalyzedFunctio...
|
| __visit_name__ = 'lambda_element'
|
| parent_lambda = None
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.elements.ClauseElement:
|
| __bool__(self)
|
| __getstate__(self)
| Helper for pickle.
|
| __invert__(self)
|
| compare(self, other: 'ClauseElement', **kw: 'Any') -> 'bool'
| Compare this :class:`_expression.ClauseElement` to
| the given :class:`_expression.ClauseElement`.
|
| Subclasses should override the default behavior, which is a
| straight identity comparison.
|
| \**kw are arguments consumed by subclass ``compare()`` methods and
| may be used to modify the criteria for comparison
| (see :class:`_expression.ColumnElement`).
|
| description(...)
|
| entity_namespace(...)
|
| params(self, _ClauseElement__optionaldict: 'Optional[Mapping[str, Any]]' = None, **kwargs: 'Any') -> 'Self'
| Return a copy with :func:`_expression.bindparam` elements
| replaced.
|
| Returns a copy of this ClauseElement with
| :func:`_expression.bindparam`
| elements replaced with values taken from the given dictionary::
|
| >>> clause = column("x") + bindparam("foo")
| >>> print(clause.compile().params)
| {'foo':None}
| >>> print(clause.params({"foo": 7}).compile().params)
| {'foo':7}
|
| self_group(self, against: 'Optional[OperatorType]' = None) -> 'ClauseElement'
| 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.
|
| unique_params(self, _ClauseElement__optionaldict: 'Optional[Dict[str, Any]]' = None, **kwargs: 'Any') -> 'Self'
| Return a copy with :func:`_expression.bindparam` elements
| replaced.
|
| Same functionality as :meth:`_expression.ClauseElement.params`,
| except adds `unique=True`
| to affected bind parameters so that multiple statements can be
| used.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from sqlalchemy.sql.elements.ClauseElement:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.elements.ClauseElement:
|
| is_clause_element = True
|
| is_dml = False
|
| is_selectable = False
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.cache_key.HasCacheKey:
|
| inherit_cache = None
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_instancemethod(fn: '_F') -> '_F'
| Decorate a method memoize its return value.
|
| :meta private:
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_attribute = <class 'sqlalchemy.util.langhelpers.HasMemoized.m...
| A read-only @property that is only evaluated once.
|
| :meta private:
|
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.visitors.HasTraverseInternals:
|
| get_children(self, *, omit_attrs: 'Tuple[str, ...]' = (), **kw: 'Any') -> 'Iterable[HasTraverseInternals]'
| Return immediate child :class:`.visitors.HasTraverseInternals`
| elements of this :class:`.visitors.HasTraverseInternals`.
|
| This is used for visit traversal.
|
| \**kw may contain flags that change the collection that is
| returned, for example to return a subset of items in order to
| cut down on larger traversals, or to return child items from a
| different context (such as schema-level collections instead of
| clause-level).
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.elements.CompilerElement:
|
| __str__(self) -> 'str'
| Return str(self).
|
| compile(self, bind: 'Optional[_HasDialect]' = None, dialect: 'Optional[Dialect]' = None, **kw: 'Any') -> 'Compiled'
| Compile this SQL expression.
|
| The return value is a :class:`~.Compiled` object.
| Calling ``str()`` or ``unicode()`` on the returned value will yield a
| string representation of the result. The
| :class:`~.Compiled` object also can return a
| dictionary of bind parameter names and values
| using the ``params`` accessor.
|
| :param bind: An :class:`.Connection` or :class:`.Engine` which
| can provide a :class:`.Dialect` in order to generate a
| :class:`.Compiled` object. If the ``bind`` and
| ``dialect`` parameters are both omitted, a default SQL compiler
| is used.
|
| :param column_keys: Used for INSERT and UPDATE statements, a list of
| column names which should be present in the VALUES clause of the
| compiled statement. If ``None``, all columns from the target table
| object are rendered.
|
| :param dialect: A :class:`.Dialect` instance which can generate
| a :class:`.Compiled` object. This argument takes precedence over
| the ``bind`` argument.
|
| :param compile_kwargs: optional dictionary of additional parameters
| that will be passed through to the compiler within all "visit"
| methods. This allows any custom flag to be passed through to
| a custom compilation construct, for example. It is also used
| for the case of passing the ``literal_binds`` flag through::
|
| from sqlalchemy.sql import table, column, select
|
| t = table("t", column("x"))
|
| s = select(t).where(t.c.x == 5)
|
| print(s.compile(compile_kwargs={"literal_binds": True}))
|
| .. seealso::
|
| :ref:`faq_sql_expression_string`
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.elements.CompilerElement:
|
| stringify_dialect = 'default'
|
| supports_execution = False
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.visitors.Visitable:
|
| __class_getitem__(key: 'Any') -> 'Any'
|
| __init_subclass__() -> 'None'
| This method is called when a class is subclassed.
|
| The default implementation does nothing. It may be
| overridden to extend subclasses.
sqlalchemy.LargeBinary
Python Library Documentation: class LargeBinary in module sqlalchemy.sql.sqltypes
class LargeBinary(_Binary)
| LargeBinary(length: 'Optional[int]' = None)
|
| A type for large binary byte data.
|
| The :class:`.LargeBinary` type corresponds to a large and/or unlengthed
| binary type for the target platform, such as BLOB on MySQL and BYTEA for
| PostgreSQL. It also handles the necessary conversions for the DBAPI.
|
| Method resolution order:
| LargeBinary
| _Binary
| sqlalchemy.sql.type_api.TypeEngine
| sqlalchemy.sql.visitors.Visitable
| typing.Generic
| builtins.object
|
| Methods defined here:
|
| __init__(self, length: 'Optional[int]' = None)
| Construct a LargeBinary type.
|
| :param length: optional, a length for the column for use in
| DDL statements, for those binary types that accept a length,
| such as the MySQL BLOB type.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| __parameters__ = ()
|
| __visit_name__ = 'large_binary'
|
| ----------------------------------------------------------------------
| Methods inherited from _Binary:
|
| bind_processor(self, dialect)
| Return a conversion function for processing bind values.
|
| Returns a callable which will receive a bind parameter value
| as the sole positional argument and will return a value to
| send to the DB-API.
|
| If processing is not necessary, the method should return ``None``.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.bind_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.bind_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_bind_param`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
|
| :param dialect: Dialect instance in use.
|
| coerce_compared_value(self, op, value)
| See :meth:`.TypeEngine.coerce_compared_value` for a description.
|
| get_dbapi_type(self, dbapi)
| Return the corresponding type object from the underlying DB-API, if
| any.
|
| This can be useful for calling ``setinputsizes()``, for example.
|
| literal_processor(self, dialect)
| Return a conversion function for processing literal values that are
| to be rendered directly without using binds.
|
| This function is used when the compiler makes use of the
| "literal_binds" flag, typically used in DDL generation as well
| as in certain scenarios where backends don't accept bound parameters.
|
| Returns a callable which will receive a literal Python value
| as the sole positional argument and will return a string representation
| to be rendered in a SQL statement.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.literal_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.literal_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_literal_param`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| result_processor(self, dialect, coltype)
| Return a conversion function for processing result row values.
|
| Returns a callable which will receive a result row column
| value as the sole positional argument and will return a value
| to return to the user.
|
| If processing is not necessary, the method should return ``None``.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.result_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.result_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_result_value`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| :param dialect: Dialect instance in use.
|
| :param coltype: DBAPI coltype argument received in cursor.description.
|
| ----------------------------------------------------------------------
| Readonly properties inherited from _Binary:
|
| python_type
| Return the Python type object expected to be returned
| by instances of this type, if known.
|
| Basically, for those types which enforce a return type,
| or are known across the board to do such for all common
| DBAPIs (like ``int`` for example), will return that type.
|
| If a return type is not defined, raises
| ``NotImplementedError``.
|
| Note that any type also accommodates NULL in SQL which
| means you can also get back ``None`` from any type
| in practice.
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.type_api.TypeEngine:
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| __str__(self) -> 'str'
| Return str(self).
|
| adapt(self, cls: 'Type[Union[TypeEngine[Any], TypeEngineMixin]]', **kw: 'Any') -> 'TypeEngine[Any]'
| Produce an "adapted" form of this type, given an "impl" class
| to work with.
|
| This method is used internally to associate generic
| types with "implementation" types that are specific to a particular
| dialect.
|
| as_generic(self, allow_nulltype: 'bool' = False) -> 'TypeEngine[_T]'
| Return an instance of the generic type corresponding to this type
| using heuristic rule. The method may be overridden if this
| heuristic rule is not sufficient.
|
| >>> from sqlalchemy.dialects.mysql import INTEGER
| >>> INTEGER(display_width=4).as_generic()
| Integer()
|
| >>> from sqlalchemy.dialects.mysql import NVARCHAR
| >>> NVARCHAR(length=100).as_generic()
| Unicode(length=100)
|
| .. versionadded:: 1.4.0b2
|
|
| .. seealso::
|
| :ref:`metadata_reflection_dbagnostic_types` - describes the
| use of :meth:`_types.TypeEngine.as_generic` in conjunction with
| the :meth:`_sql.DDLEvents.column_reflect` event, which is its
| intended use.
|
| bind_expression(self, bindvalue: 'BindParameter[_T]') -> 'Optional[ColumnElement[_T]]'
| Given a bind value (i.e. a :class:`.BindParameter` instance),
| return a SQL expression in its place.
|
| This is typically a SQL function that wraps the existing bound
| parameter within the statement. It is used for special data types
| that require literals being wrapped in some special database function
| in order to coerce an application-level value into a database-specific
| format. It is the SQL analogue of the
| :meth:`.TypeEngine.bind_processor` method.
|
| This method is called during the **SQL compilation** phase of a
| statement, when rendering a SQL string. It is **not** called
| against specific values.
|
| Note that this method, when implemented, should always return
| the exact same structure, without any conditional logic, as it
| may be used in an executemany() call against an arbitrary number
| of bound parameter sets.
|
| .. note::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.bind_expression`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.bind_expression`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.bind_expression`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| .. seealso::
|
| :ref:`types_sql_value_processing`
|
| column_expression(self, colexpr: 'ColumnElement[_T]') -> 'Optional[ColumnElement[_T]]'
| Given a SELECT column expression, return a wrapping SQL expression.
|
| This is typically a SQL function that wraps a column expression
| as rendered in the columns clause of a SELECT statement.
| It is used for special data types that require
| columns to be wrapped in some special database function in order
| to coerce the value before being sent back to the application.
| It is the SQL analogue of the :meth:`.TypeEngine.result_processor`
| method.
|
| .. note:: The :func:`.TypeEngine.column_expression` method is applied
| only to the **outermost columns clause** of a SELECT statement, that
| is, the columns that are to be delivered directly into the returned
| result rows. It does **not** apply to the columns clause inside
| of subqueries. This necessarily avoids double conversions against
| the column and only runs the conversion when ready to be returned
| to the client.
|
| This method is called during the **SQL compilation** phase of a
| statement, when rendering a SQL string. It is **not** called
| against specific values.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.column_expression`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.column_expression`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.column_expression`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
|
| .. seealso::
|
| :ref:`types_sql_value_processing`
|
| compare_values(self, x: 'Any', y: 'Any') -> 'bool'
| Compare two values for equality.
|
| compile(self, dialect: 'Optional[Dialect]' = None) -> 'str'
| Produce a string-compiled form of this :class:`.TypeEngine`.
|
| When called with no arguments, uses a "default" dialect
| to produce a string result.
|
| :param dialect: a :class:`.Dialect` instance.
|
| copy(self, **kw: 'Any') -> 'Self'
|
| copy_value(self, value: 'Any') -> 'Any'
|
| dialect_impl(self, dialect: 'Dialect') -> 'TypeEngine[_T]'
| Return a dialect-specific implementation for this
| :class:`.TypeEngine`.
|
| evaluates_none(self) -> 'Self'
| Return a copy of this type which has the
| :attr:`.should_evaluate_none` flag set to True.
|
| E.g.::
|
| Table(
| "some_table",
| metadata,
| Column(
| String(50).evaluates_none(),
| nullable=True,
| server_default="no value",
| ),
| )
|
| The ORM uses this flag to indicate that a positive value of ``None``
| is passed to the column in an INSERT statement, rather than omitting
| the column from the INSERT statement which has the effect of firing
| off column-level defaults. It also allows for types which have
| special behavior associated with the Python None value to indicate
| that the value doesn't necessarily translate into SQL NULL; a
| prime example of this is a JSON type which may wish to persist the
| JSON value ``'null'``.
|
| In all cases, the actual NULL SQL value can be always be
| persisted in any column by using
| the :obj:`_expression.null` SQL construct in an INSERT statement
| or associated with an ORM-mapped attribute.
|
| .. note::
|
| The "evaluates none" flag does **not** apply to a value
| of ``None`` passed to :paramref:`_schema.Column.default` or
| :paramref:`_schema.Column.server_default`; in these cases,
| ``None``
| still means "no default".
|
| .. seealso::
|
| :ref:`session_forcing_null` - in the ORM documentation
|
| :paramref:`.postgresql.JSON.none_as_null` - PostgreSQL JSON
| interaction with this flag.
|
| :attr:`.TypeEngine.should_evaluate_none` - class-level flag
|
| with_variant(self, type_: '_TypeEngineArgument[Any]', *dialect_names: 'str') -> 'Self'
| Produce a copy of this type object that will utilize the given
| type when applied to the dialect of the given name.
|
| e.g.::
|
| from sqlalchemy.types import String
| from sqlalchemy.dialects import mysql
|
| string_type = String()
|
| string_type = string_type.with_variant(
| mysql.VARCHAR(collation="foo"), "mysql", "mariadb"
| )
|
| The variant mapping indicates that when this type is
| interpreted by a specific dialect, it will instead be
| transmuted into the given type, rather than using the
| primary type.
|
| .. versionchanged:: 2.0 the :meth:`_types.TypeEngine.with_variant`
| method now works with a :class:`_types.TypeEngine` object "in
| place", returning a copy of the original type rather than returning
| a wrapping object; the ``Variant`` class is no longer used.
|
| :param type\_: a :class:`.TypeEngine` that will be selected
| as a variant from the originating type, when a dialect
| of the given name is in use.
| :param \*dialect_names: one or more base names of the dialect which
| uses this type. (i.e. ``'postgresql'``, ``'mysql'``, etc.)
|
| .. versionchanged:: 2.0 multiple dialect names can be specified
| for one variant.
|
| .. seealso::
|
| :ref:`types_with_variant` - illustrates the use of
| :meth:`_types.TypeEngine.with_variant`.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from sqlalchemy.sql.type_api.TypeEngine:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.type_api.TypeEngine:
|
| Comparator = <class 'sqlalchemy.sql.type_api.TypeEngine.Comparator'>
| Base class for custom comparison operations defined at the
| type level. See :attr:`.TypeEngine.comparator_factory`.
|
|
| __orig_bases__ = (<class 'sqlalchemy.sql.visitors.Visitable'>, typing....
|
| comparator_factory = <class 'sqlalchemy.sql.type_api.TypeEngine.Compar...
| Base class for custom comparison operations defined at the
| type level. See :attr:`.TypeEngine.comparator_factory`.
|
|
| hashable = True
|
| render_bind_cast = False
|
| render_literal_cast = False
|
| should_evaluate_none = False
|
| sort_key_function = None
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.visitors.Visitable:
|
| __class_getitem__(key: 'Any') -> 'Any'
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__() -> 'None'
| Function to initialize subclasses.
sqlalchemy.Lateral
Python Library Documentation: class Lateral in module sqlalchemy.sql.selectable
class Lateral(FromClauseAlias, LateralFromClause)
| Lateral(*arg: 'Any', **kw: 'Any')
|
| Represent a LATERAL subquery.
|
| This object is constructed from the :func:`_expression.lateral` module
| level function as well as the :meth:`_expression.FromClause.lateral`
| method available
| on all :class:`_expression.FromClause` subclasses.
|
| While LATERAL is part of the SQL standard, currently only more recent
| PostgreSQL versions provide support for this keyword.
|
| .. seealso::
|
| :ref:`tutorial_lateral_correlation` - overview of usage.
|
| Method resolution order:
| Lateral
| FromClauseAlias
| AliasedReturnsRows
| NoInit
| LateralFromClause
| NamedFromClause
| FromClause
| sqlalchemy.sql.roles.AnonymizedFromClauseRole
| sqlalchemy.sql.roles.StrictFromClauseRole
| sqlalchemy.sql.roles.FromClauseRole
| sqlalchemy.sql.roles.ColumnsClauseRole
| sqlalchemy.sql.roles.JoinTargetRole
| sqlalchemy.sql.roles.AllowsLambdaRole
| sqlalchemy.sql.roles.UsesInspection
| sqlalchemy.sql.roles.ColumnListRole
| sqlalchemy.sql.roles.StructuralRole
| Selectable
| ReturnsRows
| sqlalchemy.sql.roles.ReturnsRowsRole
| sqlalchemy.sql.roles.SQLRole
| sqlalchemy.sql.elements.DQLDMLClauseElement
| sqlalchemy.sql.elements.ClauseElement
| sqlalchemy.sql.annotation.SupportsWrappingAnnotations
| sqlalchemy.sql.annotation.SupportsAnnotations
| sqlalchemy.sql.cache_key.MemoizedHasCacheKey
| sqlalchemy.sql.cache_key.HasCacheKey
| sqlalchemy.util.langhelpers.HasMemoized
| sqlalchemy.sql.traversals.HasCopyInternals
| sqlalchemy.sql.visitors.ExternallyTraversible
| sqlalchemy.sql.visitors.HasTraverseInternals
| sqlalchemy.sql.elements.CompilerElement
| sqlalchemy.sql.visitors.Visitable
| builtins.object
|
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| __visit_name__ = 'lateral'
|
| inherit_cache = True
|
| ----------------------------------------------------------------------
| Methods inherited from FromClauseAlias:
|
| description(...)
|
| ----------------------------------------------------------------------
| Methods inherited from AliasedReturnsRows:
|
| implicit_returning(...)
|
| 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.
|
| ----------------------------------------------------------------------
| Readonly properties inherited from AliasedReturnsRows:
|
| original
| Legacy for dialects that are referring to Alias.original.
|
| ----------------------------------------------------------------------
| Methods inherited from NoInit:
|
| __init__(self, *arg: 'Any', **kw: 'Any')
| Initialize self. See help(type(self)) for accurate signature.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from NoInit:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Methods inherited from NamedFromClause:
|
| table_valued(self) -> 'TableValuedColumn[Any]'
| Return a :class:`_sql.TableValuedColumn` object for this
| :class:`_expression.FromClause`.
|
| A :class:`_sql.TableValuedColumn` is a :class:`_sql.ColumnElement` that
| represents a complete row in a table. Support for this construct is
| backend dependent, and is supported in various forms by backends
| such as PostgreSQL, Oracle Database and SQL Server.
|
| E.g.:
|
| .. sourcecode:: pycon+sql
|
| >>> from sqlalchemy import select, column, func, table
| >>> a = table("a", column("id"), column("x"), column("y"))
| >>> stmt = select(func.row_to_json(a.table_valued()))
| >>> print(stmt)
| {printsql}SELECT row_to_json(a) AS row_to_json_1
| FROM a
|
| .. versionadded:: 1.4.0b2
|
| .. seealso::
|
| :ref:`tutorial_functions` - in the :ref:`unified_tutorial`
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from NamedFromClause:
|
| named_with_column = True
|
| ----------------------------------------------------------------------
| Methods inherited from FromClause:
|
| alias(self, name: 'Optional[str]' = None, flat: 'bool' = False) -> 'NamedFromClause'
| 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`
|
| c(...)
| A synonym for :attr:`.FromClause.columns`
|
| :return: a :class:`.ColumnCollection`
|
| columns(...)
| 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.
|
| entity_namespace(...)
| 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.
|
| exported_columns(...)
| A :class:`_expression.ColumnCollection`
| that represents the "exported"
| columns of this :class:`_expression.Selectable`.
|
| 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`
|
| foreign_keys(...)
| Return the collection of :class:`_schema.ForeignKey` marker objects
| which this FromClause references.
|
| Each :class:`_schema.ForeignKey` is a member of a
| :class:`_schema.Table`-wide
| :class:`_schema.ForeignKeyConstraint`.
|
| .. seealso::
|
| :attr:`_schema.Table.foreign_key_constraints`
|
| 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
|
| 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`
|
| primary_key(...)
| 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.
|
| select(self) -> 'Select[Any]'
| 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.
|
| 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
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from FromClause:
|
| is_selectable = True
|
| schema = None
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.AllowsLambdaRole:
|
| allows_lambda = True
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.UsesInspection:
|
| uses_inspection = True
|
| ----------------------------------------------------------------------
| Methods inherited from Selectable:
|
| 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.
|
| 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.
|
| 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`.
|
| .. deprecated:: 1.4 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.
|
| ----------------------------------------------------------------------
| Readonly properties inherited from ReturnsRows:
|
| selectable
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.elements.ClauseElement:
|
| __bool__(self)
|
| __getstate__(self)
| Helper for pickle.
|
| __invert__(self)
|
| __repr__(self)
| Return repr(self).
|
| compare(self, other: 'ClauseElement', **kw: 'Any') -> 'bool'
| Compare this :class:`_expression.ClauseElement` to
| the given :class:`_expression.ClauseElement`.
|
| Subclasses should override the default behavior, which is a
| straight identity comparison.
|
| \**kw are arguments consumed by subclass ``compare()`` methods and
| may be used to modify the criteria for comparison
| (see :class:`_expression.ColumnElement`).
|
| params(self, _ClauseElement__optionaldict: 'Optional[Mapping[str, Any]]' = None, **kwargs: 'Any') -> 'Self'
| Return a copy with :func:`_expression.bindparam` elements
| replaced.
|
| Returns a copy of this ClauseElement with
| :func:`_expression.bindparam`
| elements replaced with values taken from the given dictionary::
|
| >>> clause = column("x") + bindparam("foo")
| >>> print(clause.compile().params)
| {'foo':None}
| >>> print(clause.params({"foo": 7}).compile().params)
| {'foo':7}
|
| self_group(self, against: 'Optional[OperatorType]' = None) -> 'ClauseElement'
| 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.
|
| unique_params(self, _ClauseElement__optionaldict: 'Optional[Dict[str, Any]]' = None, **kwargs: 'Any') -> 'Self'
| Return a copy with :func:`_expression.bindparam` elements
| replaced.
|
| Same functionality as :meth:`_expression.ClauseElement.params`,
| except adds `unique=True`
| to affected bind parameters so that multiple statements can be
| used.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.elements.ClauseElement:
|
| is_clause_element = True
|
| is_dml = False
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_instancemethod(fn: '_F') -> '_F'
| Decorate a method memoize its return value.
|
| :meta private:
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_attribute = <class 'sqlalchemy.util.langhelpers.HasMemoized.m...
| A read-only @property that is only evaluated once.
|
| :meta private:
|
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.visitors.HasTraverseInternals:
|
| get_children(self, *, omit_attrs: 'Tuple[str, ...]' = (), **kw: 'Any') -> 'Iterable[HasTraverseInternals]'
| Return immediate child :class:`.visitors.HasTraverseInternals`
| elements of this :class:`.visitors.HasTraverseInternals`.
|
| This is used for visit traversal.
|
| \**kw may contain flags that change the collection that is
| returned, for example to return a subset of items in order to
| cut down on larger traversals, or to return child items from a
| different context (such as schema-level collections instead of
| clause-level).
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.elements.CompilerElement:
|
| __str__(self) -> 'str'
| Return str(self).
|
| compile(self, bind: 'Optional[_HasDialect]' = None, dialect: 'Optional[Dialect]' = None, **kw: 'Any') -> 'Compiled'
| Compile this SQL expression.
|
| The return value is a :class:`~.Compiled` object.
| Calling ``str()`` or ``unicode()`` on the returned value will yield a
| string representation of the result. The
| :class:`~.Compiled` object also can return a
| dictionary of bind parameter names and values
| using the ``params`` accessor.
|
| :param bind: An :class:`.Connection` or :class:`.Engine` which
| can provide a :class:`.Dialect` in order to generate a
| :class:`.Compiled` object. If the ``bind`` and
| ``dialect`` parameters are both omitted, a default SQL compiler
| is used.
|
| :param column_keys: Used for INSERT and UPDATE statements, a list of
| column names which should be present in the VALUES clause of the
| compiled statement. If ``None``, all columns from the target table
| object are rendered.
|
| :param dialect: A :class:`.Dialect` instance which can generate
| a :class:`.Compiled` object. This argument takes precedence over
| the ``bind`` argument.
|
| :param compile_kwargs: optional dictionary of additional parameters
| that will be passed through to the compiler within all "visit"
| methods. This allows any custom flag to be passed through to
| a custom compilation construct, for example. It is also used
| for the case of passing the ``literal_binds`` flag through::
|
| from sqlalchemy.sql import table, column, select
|
| t = table("t", column("x"))
|
| s = select(t).where(t.c.x == 5)
|
| print(s.compile(compile_kwargs={"literal_binds": True}))
|
| .. seealso::
|
| :ref:`faq_sql_expression_string`
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.elements.CompilerElement:
|
| stringify_dialect = 'default'
|
| supports_execution = False
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.visitors.Visitable:
|
| __class_getitem__(key: 'Any') -> 'Any'
|
| __init_subclass__() -> 'None'
| This method is called when a class is subclassed.
|
| The default implementation does nothing. It may be
| overridden to extend subclasses.
sqlalchemy.MappingResult
Python Library Documentation: class MappingResult in module sqlalchemy.engine.result
class MappingResult(_WithKeys, FilterResult)
| MappingResult(result: 'Result[Any]')
|
| A wrapper for a :class:`_engine.Result` that returns dictionary values
| rather than :class:`_engine.Row` values.
|
| The :class:`_engine.MappingResult` object is acquired by calling the
| :meth:`_engine.Result.mappings` method.
|
| Method resolution order:
| MappingResult
| _WithKeys
| FilterResult
| ResultInternal
| sqlalchemy.sql.base.InPlaceGenerative
| sqlalchemy.util.langhelpers.HasMemoized
| typing.Generic
| builtins.object
|
| Methods defined here:
|
| __init__(self, result: 'Result[Any]')
| Initialize self. See help(type(self)) for accurate signature.
|
| __iter__(self) -> 'Iterator[RowMapping]'
|
| __next__(self) -> 'RowMapping'
|
| all(self) -> 'Sequence[RowMapping]'
| Return all scalar values in a sequence.
|
| Equivalent to :meth:`_engine.Result.all` except that
| :class:`_engine.RowMapping` values, rather than :class:`_engine.Row`
| objects, are returned.
|
| columns(self, *col_expressions: '_KeyIndexType') -> 'Self'
| Establish the columns that should be returned in each row.
|
| fetchall(self) -> 'Sequence[RowMapping]'
| A synonym for the :meth:`_engine.MappingResult.all` method.
|
| fetchmany(self, size: 'Optional[int]' = None) -> 'Sequence[RowMapping]'
| Fetch many objects.
|
| Equivalent to :meth:`_engine.Result.fetchmany` except that
| :class:`_engine.RowMapping` values, rather than :class:`_engine.Row`
| objects, are returned.
|
| fetchone(self) -> 'Optional[RowMapping]'
| Fetch one object.
|
| Equivalent to :meth:`_engine.Result.fetchone` except that
| :class:`_engine.RowMapping` values, rather than :class:`_engine.Row`
| objects, are returned.
|
| first(self) -> 'Optional[RowMapping]'
| Fetch the first object or ``None`` if no object is present.
|
| Equivalent to :meth:`_engine.Result.first` except that
| :class:`_engine.RowMapping` values, rather than :class:`_engine.Row`
| objects, are returned.
|
| one(self) -> 'RowMapping'
| Return exactly one object or raise an exception.
|
| Equivalent to :meth:`_engine.Result.one` except that
| :class:`_engine.RowMapping` values, rather than :class:`_engine.Row`
| objects, are returned.
|
| one_or_none(self) -> 'Optional[RowMapping]'
| Return at most one object or raise an exception.
|
| Equivalent to :meth:`_engine.Result.one_or_none` except that
| :class:`_engine.RowMapping` values, rather than :class:`_engine.Row`
| objects, are returned.
|
| partitions(self, size: 'Optional[int]' = None) -> 'Iterator[Sequence[RowMapping]]'
| Iterate through sub-lists of elements of the size given.
|
| Equivalent to :meth:`_engine.Result.partitions` except that
| :class:`_engine.RowMapping` values, rather than :class:`_engine.Row`
| objects, are returned.
|
| unique(self, strategy: 'Optional[_UniqueFilterType]' = None) -> 'Self'
| Apply unique filtering to the objects returned by this
| :class:`_engine.MappingResult`.
|
| See :meth:`_engine.Result.unique` for usage details.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| __orig_bases__ = (<class 'sqlalchemy.engine.result._WithKeys'>, sqlalc...
|
| __parameters__ = ()
|
| ----------------------------------------------------------------------
| Methods inherited from _WithKeys:
|
| keys(self) -> 'RMKeyView'
| Return an iterable view which yields the string keys that would
| be represented by each :class:`_engine.Row`.
|
| The keys can represent the labels of the columns returned by a core
| statement or the names of the orm classes returned by an orm
| execution.
|
| The view also can be tested for key containment using the Python
| ``in`` operator, which will test both for the string keys represented
| in the view, as well as for alternate keys such as column objects.
|
| .. versionchanged:: 1.4 a key view object is returned rather than a
| plain list.
|
| ----------------------------------------------------------------------
| Methods inherited from FilterResult:
|
| __enter__(self) -> 'Self'
|
| __exit__(self, type_: 'Any', value: 'Any', traceback: 'Any') -> 'None'
|
| close(self) -> 'None'
| Close this :class:`_engine.FilterResult`.
|
| .. versionadded:: 1.4.43
|
| yield_per(self, num: 'int') -> 'Self'
| Configure the row-fetching strategy to fetch ``num`` rows at a time.
|
| The :meth:`_engine.FilterResult.yield_per` method is a pass through
| to the :meth:`_engine.Result.yield_per` method. See that method's
| documentation for usage notes.
|
| .. versionadded:: 1.4.40 - added :meth:`_engine.FilterResult.yield_per`
| so that the method is available on all result set implementations
|
| .. seealso::
|
| :ref:`engine_stream_results` - describes Core behavior for
| :meth:`_engine.Result.yield_per`
|
| :ref:`orm_queryguide_yield_per` - in the :ref:`queryguide_toplevel`
|
| ----------------------------------------------------------------------
| Readonly properties inherited from FilterResult:
|
| closed
| Return ``True`` if this :class:`_engine.Result` being
| proxied by this :class:`_engine.FilterResult` was
| **hard closed** by explicitly calling the :meth:`_engine.Result.close`
| method.
|
| This is a direct proxy for the :attr:`_engine.Result.closed` attribute;
| see that attribute for details.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from FilterResult:
|
| __dict__
| dictionary for instance variables
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_instancemethod(fn: '_F') -> '_F'
| Decorate a method memoize its return value.
|
| :meta private:
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_attribute = <class 'sqlalchemy.util.langhelpers.HasMemoized.m...
| A read-only @property that is only evaluated once.
|
| :meta private:
|
|
| ----------------------------------------------------------------------
| Class methods inherited from typing.Generic:
|
| __class_getitem__(...)
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__(...)
| Function to initialize subclasses.
sqlalchemy.MergedResult
Python Library Documentation: class MergedResult in module sqlalchemy.engine.result
class MergedResult(IteratorResult)
| MergedResult(cursor_metadata: 'ResultMetaData', results: 'Sequence[Result[_TP]]')
|
| A :class:`_engine.Result` that is merged from any number of
| :class:`_engine.Result` objects.
|
| Returned by the :meth:`_engine.Result.merge` method.
|
| .. versionadded:: 1.4
|
| Method resolution order:
| MergedResult
| IteratorResult
| Result
| _WithKeys
| ResultInternal
| sqlalchemy.sql.base.InPlaceGenerative
| sqlalchemy.util.langhelpers.HasMemoized
| typing.Generic
| builtins.object
|
| Methods defined here:
|
| __init__(self, cursor_metadata: 'ResultMetaData', results: 'Sequence[Result[_TP]]')
| Initialize self. See help(type(self)) for accurate signature.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'rowcount': 'Optional[int]'}
|
| __orig_bases__ = (sqlalchemy.engine.result.IteratorResult[~_TP],)
|
| __parameters__ = (~_TP,)
|
| closed = False
|
| ----------------------------------------------------------------------
| Data descriptors inherited from IteratorResult:
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Methods inherited from Result:
|
| __enter__(self) -> 'Self'
|
| __exit__(self, type_: 'Any', value: 'Any', traceback: 'Any') -> 'None'
|
| __iter__(self) -> 'Iterator[Row[_TP]]'
|
| __next__(self) -> 'Row[_TP]'
|
| all(self) -> 'Sequence[Row[_TP]]'
| Return all rows in a sequence.
|
| Closes the result set after invocation. Subsequent invocations
| will return an empty sequence.
|
| .. versionadded:: 1.4
|
| :return: a sequence of :class:`_engine.Row` objects.
|
| .. seealso::
|
| :ref:`engine_stream_results` - How to stream a large result set
| without loading it completely in python.
|
| close(self) -> 'None'
| Hard close this :class:`_engine.Result`.
|
| The behavior of this method is implementation specific, and is
| not implemented by default. The method should generally end
| the resources in use by the result object and also cause any
| subsequent iteration or row fetching to raise
| :class:`.ResourceClosedError`.
|
| .. versionadded:: 1.4.27 - ``.close()`` was previously not generally
| available for all :class:`_engine.Result` classes, instead only
| being available on the :class:`_engine.CursorResult` returned for
| Core statement executions. As most other result objects, namely the
| ones used by the ORM, are proxying a :class:`_engine.CursorResult`
| in any case, this allows the underlying cursor result to be closed
| from the outside facade for the case when the ORM query is using
| the ``yield_per`` execution option where it does not immediately
| exhaust and autoclose the database cursor.
|
| columns(self, *col_expressions: '_KeyIndexType') -> 'Self'
| Establish the columns that should be returned in each row.
|
| This method may be used to limit the columns returned as well
| as to reorder them. The given list of expressions are normally
| a series of integers or string key names. They may also be
| appropriate :class:`.ColumnElement` objects which correspond to
| a given statement construct.
|
| .. versionchanged:: 2.0 Due to a bug in 1.4, the
| :meth:`_engine.Result.columns` method had an incorrect behavior
| where calling upon the method with just one index would cause the
| :class:`_engine.Result` object to yield scalar values rather than
| :class:`_engine.Row` objects. In version 2.0, this behavior
| has been corrected such that calling upon
| :meth:`_engine.Result.columns` with a single index will
| produce a :class:`_engine.Result` object that continues
| to yield :class:`_engine.Row` objects, which include
| only a single column.
|
| E.g.::
|
| statement = select(table.c.x, table.c.y, table.c.z)
| result = connection.execute(statement)
|
| for z, y in result.columns("z", "y"):
| ...
|
| Example of using the column objects from the statement itself::
|
| for z, y in result.columns(
| statement.selected_columns.c.z, statement.selected_columns.c.y
| ):
| ...
|
| .. versionadded:: 1.4
|
| :param \*col_expressions: indicates columns to be returned. Elements
| may be integer row indexes, string column names, or appropriate
| :class:`.ColumnElement` objects corresponding to a select construct.
|
| :return: this :class:`_engine.Result` object with the modifications
| given.
|
| fetchall(self) -> 'Sequence[Row[_TP]]'
| A synonym for the :meth:`_engine.Result.all` method.
|
| fetchmany(self, size: 'Optional[int]' = None) -> 'Sequence[Row[_TP]]'
| Fetch many rows.
|
| When all rows are exhausted, returns an empty sequence.
|
| This method is provided for backwards compatibility with
| SQLAlchemy 1.x.x.
|
| To fetch rows in groups, use the :meth:`_engine.Result.partitions`
| method.
|
| :return: a sequence of :class:`_engine.Row` objects.
|
| .. seealso::
|
| :meth:`_engine.Result.partitions`
|
| fetchone(self) -> 'Optional[Row[_TP]]'
| Fetch one row.
|
| When all rows are exhausted, returns None.
|
| This method is provided for backwards compatibility with
| SQLAlchemy 1.x.x.
|
| To fetch the first row of a result only, use the
| :meth:`_engine.Result.first` method. To iterate through all
| rows, iterate the :class:`_engine.Result` object directly.
|
| :return: a :class:`_engine.Row` object if no filters are applied,
| or ``None`` if no rows remain.
|
| first(self) -> 'Optional[Row[_TP]]'
| Fetch the first row or ``None`` if no row is present.
|
| Closes the result set and discards remaining rows.
|
| .. note:: This method returns one **row**, e.g. tuple, by default.
| To return exactly one single scalar value, that is, the first
| column of the first row, use the
| :meth:`_engine.Result.scalar` method,
| or combine :meth:`_engine.Result.scalars` and
| :meth:`_engine.Result.first`.
|
| Additionally, in contrast to the behavior of the legacy ORM
| :meth:`_orm.Query.first` method, **no limit is applied** to the
| SQL query which was invoked to produce this
| :class:`_engine.Result`;
| for a DBAPI driver that buffers results in memory before yielding
| rows, all rows will be sent to the Python process and all but
| the first row will be discarded.
|
| .. seealso::
|
| :ref:`migration_20_unify_select`
|
| :return: a :class:`_engine.Row` object, or None
| if no rows remain.
|
| .. seealso::
|
| :meth:`_engine.Result.scalar`
|
| :meth:`_engine.Result.one`
|
| freeze(self) -> 'FrozenResult[_TP]'
| Return a callable object that will produce copies of this
| :class:`_engine.Result` when invoked.
|
| The callable object returned is an instance of
| :class:`_engine.FrozenResult`.
|
| This is used for result set caching. The method must be called
| on the result when it has been unconsumed, and calling the method
| will consume the result fully. When the :class:`_engine.FrozenResult`
| is retrieved from a cache, it can be called any number of times where
| it will produce a new :class:`_engine.Result` object each time
| against its stored set of rows.
|
| .. seealso::
|
| :ref:`do_orm_execute_re_executing` - example usage within the
| ORM to implement a result-set cache.
|
| mappings(self) -> 'MappingResult'
| Apply a mappings filter to returned rows, returning an instance of
| :class:`_engine.MappingResult`.
|
| When this filter is applied, fetching rows will return
| :class:`_engine.RowMapping` objects instead of :class:`_engine.Row`
| objects.
|
| .. versionadded:: 1.4
|
| :return: a new :class:`_engine.MappingResult` filtering object
| referring to this :class:`_engine.Result` object.
|
| merge(self, *others: 'Result[Any]') -> 'MergedResult[_TP]'
| Merge this :class:`_engine.Result` with other compatible result
| objects.
|
| The object returned is an instance of :class:`_engine.MergedResult`,
| which will be composed of iterators from the given result
| objects.
|
| The new result will use the metadata from this result object.
| The subsequent result objects must be against an identical
| set of result / cursor metadata, otherwise the behavior is
| undefined.
|
| one(self) -> 'Row[_TP]'
| Return exactly one row or raise an exception.
|
| Raises :class:`_exc.NoResultFound` if the result returns no
| rows, or :class:`_exc.MultipleResultsFound` if multiple rows
| would be returned.
|
| .. note:: This method returns one **row**, e.g. tuple, by default.
| To return exactly one single scalar value, that is, the first
| column of the first row, use the
| :meth:`_engine.Result.scalar_one` method, or combine
| :meth:`_engine.Result.scalars` and
| :meth:`_engine.Result.one`.
|
| .. versionadded:: 1.4
|
| :return: The first :class:`_engine.Row`.
|
| :raises: :class:`.MultipleResultsFound`, :class:`.NoResultFound`
|
| .. seealso::
|
| :meth:`_engine.Result.first`
|
| :meth:`_engine.Result.one_or_none`
|
| :meth:`_engine.Result.scalar_one`
|
| one_or_none(self) -> 'Optional[Row[_TP]]'
| Return at most one result or raise an exception.
|
| Returns ``None`` if the result has no rows.
| Raises :class:`.MultipleResultsFound`
| if multiple rows are returned.
|
| .. versionadded:: 1.4
|
| :return: The first :class:`_engine.Row` or ``None`` if no row
| is available.
|
| :raises: :class:`.MultipleResultsFound`
|
| .. seealso::
|
| :meth:`_engine.Result.first`
|
| :meth:`_engine.Result.one`
|
| partitions(self, size: 'Optional[int]' = None) -> 'Iterator[Sequence[Row[_TP]]]'
| Iterate through sub-lists of rows of the size given.
|
| Each list will be of the size given, excluding the last list to
| be yielded, which may have a small number of rows. No empty
| lists will be yielded.
|
| The result object is automatically closed when the iterator
| is fully consumed.
|
| Note that the backend driver will usually buffer the entire result
| ahead of time unless the
| :paramref:`.Connection.execution_options.stream_results` execution
| option is used indicating that the driver should not pre-buffer
| results, if possible. Not all drivers support this option and
| the option is silently ignored for those who do not.
|
| When using the ORM, the :meth:`_engine.Result.partitions` method
| is typically more effective from a memory perspective when it is
| combined with use of the
| :ref:`yield_per execution option <orm_queryguide_yield_per>`,
| which instructs both the DBAPI driver to use server side cursors,
| if available, as well as instructs the ORM loading internals to only
| build a certain amount of ORM objects from a result at a time before
| yielding them out.
|
| .. versionadded:: 1.4
|
| :param size: indicate the maximum number of rows to be present
| in each list yielded. If None, makes use of the value set by
| the :meth:`_engine.Result.yield_per`, method, if it were called,
| or the :paramref:`_engine.Connection.execution_options.yield_per`
| execution option, which is equivalent in this regard. If
| yield_per weren't set, it makes use of the
| :meth:`_engine.Result.fetchmany` default, which may be backend
| specific and not well defined.
|
| :return: iterator of lists
|
| .. seealso::
|
| :ref:`engine_stream_results`
|
| :ref:`orm_queryguide_yield_per` - in the :ref:`queryguide_toplevel`
|
| scalar(self) -> 'Any'
| Fetch the first column of the first row, and close the result set.
|
| Returns ``None`` if there are no rows to fetch.
|
| No validation is performed to test if additional rows remain.
|
| After calling this method, the object is fully closed,
| e.g. the :meth:`_engine.CursorResult.close`
| method will have been called.
|
| :return: a Python scalar value, or ``None`` if no rows remain.
|
| scalar_one(self) -> 'Any'
| Return exactly one scalar result or raise an exception.
|
| This is equivalent to calling :meth:`_engine.Result.scalars` and
| then :meth:`_engine.ScalarResult.one`.
|
| .. seealso::
|
| :meth:`_engine.ScalarResult.one`
|
| :meth:`_engine.Result.scalars`
|
| scalar_one_or_none(self) -> 'Optional[Any]'
| Return exactly one scalar result or ``None``.
|
| This is equivalent to calling :meth:`_engine.Result.scalars` and
| then :meth:`_engine.ScalarResult.one_or_none`.
|
| .. seealso::
|
| :meth:`_engine.ScalarResult.one_or_none`
|
| :meth:`_engine.Result.scalars`
|
| scalars(self, index: '_KeyIndexType' = 0) -> 'ScalarResult[Any]'
| Return a :class:`_engine.ScalarResult` filtering object which
| will return single elements rather than :class:`_row.Row` objects.
|
| E.g.::
|
| >>> result = conn.execute(text("select int_id from table"))
| >>> result.scalars().all()
| [1, 2, 3]
|
| When results are fetched from the :class:`_engine.ScalarResult`
| filtering object, the single column-row that would be returned by the
| :class:`_engine.Result` is instead returned as the column's value.
|
| .. versionadded:: 1.4
|
| :param index: integer or row key indicating the column to be fetched
| from each row, defaults to ``0`` indicating the first column.
|
| :return: a new :class:`_engine.ScalarResult` filtering object referring
| to this :class:`_engine.Result` object.
|
| tuples(self) -> 'TupleResult[_TP]'
| Apply a "typed tuple" typing filter to returned rows.
|
| This method returns the same :class:`_engine.Result` object
| at runtime,
| however annotates as returning a :class:`_engine.TupleResult` object
| that will indicate to :pep:`484` typing tools that plain typed
| ``Tuple`` instances are returned rather than rows. This allows
| tuple unpacking and ``__getitem__`` access of :class:`_engine.Row`
| objects to by typed, for those cases where the statement invoked
| itself included typing information.
|
| .. versionadded:: 2.0
|
| :return: the :class:`_engine.TupleResult` type at typing time.
|
| .. seealso::
|
| :attr:`_engine.Result.t` - shorter synonym
|
| :attr:`_engine.Row._t` - :class:`_engine.Row` version
|
| unique(self, strategy: 'Optional[_UniqueFilterType]' = None) -> 'Self'
| Apply unique filtering to the objects returned by this
| :class:`_engine.Result`.
|
| When this filter is applied with no arguments, the rows or objects
| returned will filtered such that each row is returned uniquely. The
| algorithm used to determine this uniqueness is by default the Python
| hashing identity of the whole tuple. In some cases a specialized
| per-entity hashing scheme may be used, such as when using the ORM, a
| scheme is applied which works against the primary key identity of
| returned objects.
|
| The unique filter is applied **after all other filters**, which means
| if the columns returned have been refined using a method such as the
| :meth:`_engine.Result.columns` or :meth:`_engine.Result.scalars`
| method, the uniquing is applied to **only the column or columns
| returned**. This occurs regardless of the order in which these
| methods have been called upon the :class:`_engine.Result` object.
|
| The unique filter also changes the calculus used for methods like
| :meth:`_engine.Result.fetchmany` and :meth:`_engine.Result.partitions`.
| When using :meth:`_engine.Result.unique`, these methods will continue
| to yield the number of rows or objects requested, after uniquing
| has been applied. However, this necessarily impacts the buffering
| behavior of the underlying cursor or datasource, such that multiple
| underlying calls to ``cursor.fetchmany()`` may be necessary in order
| to accumulate enough objects in order to provide a unique collection
| of the requested size.
|
| :param strategy: a callable that will be applied to rows or objects
| being iterated, which should return an object that represents the
| unique value of the row. A Python ``set()`` is used to store
| these identities. If not passed, a default uniqueness strategy
| is used which may have been assembled by the source of this
| :class:`_engine.Result` object.
|
| yield_per(self, num: 'int') -> 'Self'
| Configure the row-fetching strategy to fetch ``num`` rows at a time.
|
| This impacts the underlying behavior of the result when iterating over
| the result object, or otherwise making use of methods such as
| :meth:`_engine.Result.fetchone` that return one row at a time. Data
| from the underlying cursor or other data source will be buffered up to
| this many rows in memory, and the buffered collection will then be
| yielded out one row at a time or as many rows are requested. Each time
| the buffer clears, it will be refreshed to this many rows or as many
| rows remain if fewer remain.
|
| The :meth:`_engine.Result.yield_per` method is generally used in
| conjunction with the
| :paramref:`_engine.Connection.execution_options.stream_results`
| execution option, which will allow the database dialect in use to make
| use of a server side cursor, if the DBAPI supports a specific "server
| side cursor" mode separate from its default mode of operation.
|
| .. tip::
|
| Consider using the
| :paramref:`_engine.Connection.execution_options.yield_per`
| execution option, which will simultaneously set
| :paramref:`_engine.Connection.execution_options.stream_results`
| to ensure the use of server side cursors, as well as automatically
| invoke the :meth:`_engine.Result.yield_per` method to establish
| a fixed row buffer size at once.
|
| The :paramref:`_engine.Connection.execution_options.yield_per`
| execution option is available for ORM operations, with
| :class:`_orm.Session`-oriented use described at
| :ref:`orm_queryguide_yield_per`. The Core-only version which works
| with :class:`_engine.Connection` is new as of SQLAlchemy 1.4.40.
|
| .. versionadded:: 1.4
|
| :param num: number of rows to fetch each time the buffer is refilled.
| If set to a value below 1, fetches all rows for the next buffer.
|
| .. seealso::
|
| :ref:`engine_stream_results` - describes Core behavior for
| :meth:`_engine.Result.yield_per`
|
| :ref:`orm_queryguide_yield_per` - in the :ref:`queryguide_toplevel`
|
| ----------------------------------------------------------------------
| Readonly properties inherited from Result:
|
| t
| Apply a "typed tuple" typing filter to returned rows.
|
| The :attr:`_engine.Result.t` attribute is a synonym for
| calling the :meth:`_engine.Result.tuples` method.
|
| .. versionadded:: 2.0
|
| ----------------------------------------------------------------------
| Data descriptors inherited from Result:
|
| __dict__
| dictionary for instance variables
|
| ----------------------------------------------------------------------
| Methods inherited from _WithKeys:
|
| keys(self) -> 'RMKeyView'
| Return an iterable view which yields the string keys that would
| be represented by each :class:`_engine.Row`.
|
| The keys can represent the labels of the columns returned by a core
| statement or the names of the orm classes returned by an orm
| execution.
|
| The view also can be tested for key containment using the Python
| ``in`` operator, which will test both for the string keys represented
| in the view, as well as for alternate keys such as column objects.
|
| .. versionchanged:: 1.4 a key view object is returned rather than a
| plain list.
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_instancemethod(fn: '_F') -> '_F'
| Decorate a method memoize its return value.
|
| :meta private:
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_attribute = <class 'sqlalchemy.util.langhelpers.HasMemoized.m...
| A read-only @property that is only evaluated once.
|
| :meta private:
|
|
| ----------------------------------------------------------------------
| Class methods inherited from typing.Generic:
|
| __class_getitem__(...)
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__(...)
| Function to initialize subclasses.
sqlalchemy.MetaData
Python Library Documentation: class MetaData in module sqlalchemy.sql.schema
class MetaData(HasSchemaAttr)
| MetaData(schema: 'Optional[str]' = None, quote_schema: 'Optional[bool]' = None, naming_convention: 'Optional[_NamingSchemaParameter]' = None, info: 'Optional[_InfoType]' = None) -> 'None'
|
| A collection of :class:`_schema.Table`
| objects and their associated schema
| constructs.
|
| Holds a collection of :class:`_schema.Table` objects as well as
| an optional binding to an :class:`_engine.Engine` or
| :class:`_engine.Connection`. If bound, the :class:`_schema.Table` objects
| in the collection and their columns may participate in implicit SQL
| execution.
|
| The :class:`_schema.Table` objects themselves are stored in the
| :attr:`_schema.MetaData.tables` dictionary.
|
| :class:`_schema.MetaData` is a thread-safe object for read operations.
| Construction of new tables within a single :class:`_schema.MetaData`
| object,
| either explicitly or via reflection, may not be completely thread-safe.
|
| .. seealso::
|
| :ref:`metadata_describing` - Introduction to database metadata
|
| Method resolution order:
| MetaData
| HasSchemaAttr
| SchemaItem
| sqlalchemy.sql.base.SchemaVisitable
| sqlalchemy.sql.base.SchemaEventTarget
| sqlalchemy.event.registry.EventTarget
| sqlalchemy.sql.visitors.Visitable
| builtins.object
|
| Methods defined here:
|
| __contains__(self, table_or_key: 'Union[str, Table]') -> 'bool'
|
| __getstate__(self) -> 'Dict[str, Any]'
| Helper for pickle.
|
| __init__(self, schema: 'Optional[str]' = None, quote_schema: 'Optional[bool]' = None, naming_convention: 'Optional[_NamingSchemaParameter]' = None, info: 'Optional[_InfoType]' = None) -> 'None'
| Create a new MetaData object.
|
| :param schema:
| The default schema to use for the :class:`_schema.Table`,
| :class:`.Sequence`, and potentially other objects associated with
| this :class:`_schema.MetaData`. Defaults to ``None``.
|
| .. seealso::
|
| :ref:`schema_metadata_schema_name` - details on how the
| :paramref:`_schema.MetaData.schema` parameter is used.
|
| :paramref:`_schema.Table.schema`
|
| :paramref:`.Sequence.schema`
|
| :param quote_schema:
| Sets the ``quote_schema`` flag for those :class:`_schema.Table`,
| :class:`.Sequence`, and other objects which make usage of the
| local ``schema`` name.
|
| :param info: Optional data dictionary which will be populated into the
| :attr:`.SchemaItem.info` attribute of this object.
|
| :param naming_convention: a dictionary referring to values which
| will establish default naming conventions for :class:`.Constraint`
| and :class:`.Index` objects, for those objects which are not given
| a name explicitly.
|
| The keys of this dictionary may be:
|
| * a constraint or Index class, e.g. the :class:`.UniqueConstraint`,
| :class:`_schema.ForeignKeyConstraint` class, the :class:`.Index`
| class
|
| * a string mnemonic for one of the known constraint classes;
| ``"fk"``, ``"pk"``, ``"ix"``, ``"ck"``, ``"uq"`` for foreign key,
| primary key, index, check, and unique constraint, respectively.
|
| * the string name of a user-defined "token" that can be used
| to define new naming tokens.
|
| The values associated with each "constraint class" or "constraint
| mnemonic" key are string naming templates, such as
| ``"uq_%(table_name)s_%(column_0_name)s"``,
| which describe how the name should be composed. The values
| associated with user-defined "token" keys should be callables of the
| form ``fn(constraint, table)``, which accepts the constraint/index
| object and :class:`_schema.Table` as arguments, returning a string
| result.
|
| The built-in names are as follows, some of which may only be
| available for certain types of constraint:
|
| * ``%(table_name)s`` - the name of the :class:`_schema.Table`
| object
| associated with the constraint.
|
| * ``%(referred_table_name)s`` - the name of the
| :class:`_schema.Table`
| object associated with the referencing target of a
| :class:`_schema.ForeignKeyConstraint`.
|
| * ``%(column_0_name)s`` - the name of the :class:`_schema.Column`
| at
| index position "0" within the constraint.
|
| * ``%(column_0N_name)s`` - the name of all :class:`_schema.Column`
| objects in order within the constraint, joined without a
| separator.
|
| * ``%(column_0_N_name)s`` - the name of all
| :class:`_schema.Column`
| objects in order within the constraint, joined with an
| underscore as a separator.
|
| * ``%(column_0_label)s``, ``%(column_0N_label)s``,
| ``%(column_0_N_label)s`` - the label of either the zeroth
| :class:`_schema.Column` or all :class:`.Columns`, separated with
| or without an underscore
|
| * ``%(column_0_key)s``, ``%(column_0N_key)s``,
| ``%(column_0_N_key)s`` - the key of either the zeroth
| :class:`_schema.Column` or all :class:`.Columns`, separated with
| or without an underscore
|
| * ``%(referred_column_0_name)s``, ``%(referred_column_0N_name)s``
| ``%(referred_column_0_N_name)s``, ``%(referred_column_0_key)s``,
| ``%(referred_column_0N_key)s``, ... column tokens which
| render the names/keys/labels of columns that are referenced
| by a :class:`_schema.ForeignKeyConstraint`.
|
| * ``%(constraint_name)s`` - a special key that refers to the
| existing name given to the constraint. When this key is
| present, the :class:`.Constraint` object's existing name will be
| replaced with one that is composed from template string that
| uses this token. When this token is present, it is required that
| the :class:`.Constraint` is given an explicit name ahead of time.
|
| * user-defined: any additional token may be implemented by passing
| it along with a ``fn(constraint, table)`` callable to the
| naming_convention dictionary.
|
| .. versionadded:: 1.3.0 - added new ``%(column_0N_name)s``,
| ``%(column_0_N_name)s``, and related tokens that produce
| concatenations of names, keys, or labels for all columns referred
| to by a given constraint.
|
| .. seealso::
|
| :ref:`constraint_naming_conventions` - for detailed usage
| examples.
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| __setstate__(self, state: 'Dict[str, Any]') -> 'None'
|
| clear(self) -> 'None'
| Clear all Table objects from this MetaData.
|
| create_all(self, bind: '_CreateDropBind', tables: 'Optional[_typing_Sequence[Table]]' = None, checkfirst: 'bool' = True) -> 'None'
| Create all tables stored in this metadata.
|
| Conditional by default, will not attempt to recreate tables already
| present in the target database.
|
| :param bind:
| A :class:`.Connection` or :class:`.Engine` used to access the
| database.
|
| :param tables:
| Optional list of ``Table`` objects, which is a subset of the total
| tables in the ``MetaData`` (others are ignored).
|
| :param checkfirst:
| Defaults to True, don't issue CREATEs for tables already present
| in the target database.
|
| drop_all(self, bind: '_CreateDropBind', tables: 'Optional[_typing_Sequence[Table]]' = None, checkfirst: 'bool' = True) -> 'None'
| Drop all tables stored in this metadata.
|
| Conditional by default, will not attempt to drop tables not present in
| the target database.
|
| :param bind:
| A :class:`.Connection` or :class:`.Engine` used to access the
| database.
|
| :param tables:
| Optional list of ``Table`` objects, which is a subset of the
| total tables in the ``MetaData`` (others are ignored).
|
| :param checkfirst:
| Defaults to True, only issue DROPs for tables confirmed to be
| present in the target database.
|
| reflect(self, bind: 'Union[Engine, Connection]', schema: 'Optional[str]' = None, views: 'bool' = False, only: 'Union[_typing_Sequence[str], Callable[[str, MetaData], bool], None]' = None, extend_existing: 'bool' = False, autoload_replace: 'bool' = True, resolve_fks: 'bool' = True, **dialect_kwargs: 'Any') -> 'None'
| Load all available table definitions from the database.
|
| Automatically creates ``Table`` entries in this ``MetaData`` for any
| table available in the database but not yet present in the
| ``MetaData``. May be called multiple times to pick up tables recently
| added to the database, however no special action is taken if a table
| in this ``MetaData`` no longer exists in the database.
|
| :param bind:
| A :class:`.Connection` or :class:`.Engine` used to access the
| database.
|
| :param schema:
| Optional, query and reflect tables from an alternate schema.
| If None, the schema associated with this :class:`_schema.MetaData`
| is used, if any.
|
| :param views:
| If True, also reflect views (materialized and plain).
|
| :param only:
| Optional. Load only a sub-set of available named tables. May be
| specified as a sequence of names or a callable.
|
| If a sequence of names is provided, only those tables will be
| reflected. An error is raised if a table is requested but not
| available. Named tables already present in this ``MetaData`` are
| ignored.
|
| If a callable is provided, it will be used as a boolean predicate to
| filter the list of potential table names. The callable is called
| with a table name and this ``MetaData`` instance as positional
| arguments and should return a true value for any table to reflect.
|
| :param extend_existing: Passed along to each :class:`_schema.Table` as
| :paramref:`_schema.Table.extend_existing`.
|
| :param autoload_replace: Passed along to each :class:`_schema.Table`
| as
| :paramref:`_schema.Table.autoload_replace`.
|
| :param resolve_fks: if True, reflect :class:`_schema.Table`
| objects linked
| to :class:`_schema.ForeignKey` objects located in each
| :class:`_schema.Table`.
| For :meth:`_schema.MetaData.reflect`,
| this has the effect of reflecting
| related tables that might otherwise not be in the list of tables
| being reflected, for example if the referenced table is in a
| different schema or is omitted via the
| :paramref:`.MetaData.reflect.only` parameter. When False,
| :class:`_schema.ForeignKey` objects are not followed to the
| :class:`_schema.Table`
| in which they link, however if the related table is also part of the
| list of tables that would be reflected in any case, the
| :class:`_schema.ForeignKey` object will still resolve to its related
| :class:`_schema.Table` after the :meth:`_schema.MetaData.reflect`
| operation is
| complete. Defaults to True.
|
| .. versionadded:: 1.3.0
|
| .. seealso::
|
| :paramref:`_schema.Table.resolve_fks`
|
| :param \**dialect_kwargs: Additional keyword arguments not mentioned
| above are dialect specific, and passed in the form
| ``<dialectname>_<argname>``. See the documentation regarding an
| individual dialect at :ref:`dialect_toplevel` for detail on
| documented arguments.
|
| .. seealso::
|
| :ref:`metadata_reflection_toplevel`
|
| :meth:`_events.DDLEvents.column_reflect` - Event used to customize
| the reflected columns. Usually used to generalize the types using
| :meth:`_types.TypeEngine.as_generic`
|
| :ref:`metadata_reflection_dbagnostic_types` - describes how to
| reflect tables using general types.
|
| remove(self, table: 'Table') -> 'None'
| Remove the given Table object from this MetaData.
|
| ----------------------------------------------------------------------
| Readonly properties defined here:
|
| sorted_tables
| Returns a list of :class:`_schema.Table` objects sorted in order of
| foreign key dependency.
|
| The sorting will place :class:`_schema.Table`
| objects that have dependencies
| first, before the dependencies themselves, representing the
| order in which they can be created. To get the order in which
| the tables would be dropped, use the ``reversed()`` Python built-in.
|
| .. warning::
|
| The :attr:`.MetaData.sorted_tables` attribute cannot by itself
| accommodate automatic resolution of dependency cycles between
| tables, which are usually caused by mutually dependent foreign key
| constraints. When these cycles are detected, the foreign keys
| of these tables are omitted from consideration in the sort.
| A warning is emitted when this condition occurs, which will be an
| exception raise in a future release. Tables which are not part
| of the cycle will still be returned in dependency order.
|
| To resolve these cycles, the
| :paramref:`_schema.ForeignKeyConstraint.use_alter` parameter may be
| applied to those constraints which create a cycle. Alternatively,
| the :func:`_schema.sort_tables_and_constraints` function will
| automatically return foreign key constraints in a separate
| collection when cycles are detected so that they may be applied
| to a schema separately.
|
| .. versionchanged:: 1.3.17 - a warning is emitted when
| :attr:`.MetaData.sorted_tables` cannot perform a proper sort
| due to cyclical dependencies. This will be an exception in a
| future release. Additionally, the sort will continue to return
| other tables not involved in the cycle in dependency order which
| was not the case previously.
|
| .. seealso::
|
| :func:`_schema.sort_tables`
|
| :func:`_schema.sort_tables_and_constraints`
|
| :attr:`_schema.MetaData.tables`
|
| :meth:`_reflection.Inspector.get_table_names`
|
| :meth:`_reflection.Inspector.get_sorted_table_and_fkc_names`
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'tables': 'util.FacadeDict[str, Table]'}
|
| __visit_name__ = 'metadata'
|
| ----------------------------------------------------------------------
| Methods inherited from SchemaItem:
|
| info(...)
| Info dictionary associated with the object, allowing user-defined
| data to be associated with this :class:`.SchemaItem`.
|
| The dictionary is automatically generated when first accessed.
| It can also be specified in the constructor of some objects,
| such as :class:`_schema.Table` and :class:`_schema.Column`.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from SchemaItem:
|
| create_drop_stringify_dialect = 'default'
|
| ----------------------------------------------------------------------
| Data descriptors inherited from sqlalchemy.sql.base.SchemaEventTarget:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.base.SchemaEventTarget:
|
| dispatch = <sqlalchemy.event.base.DDLEventsDispatch object>
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.visitors.Visitable:
|
| __class_getitem__(key: 'Any') -> 'Any'
|
| __init_subclass__() -> 'None'
| This method is called when a class is subclassed.
|
| The default implementation does nothing. It may be
| overridden to extend subclasses.
sqlalchemy.NCHAR
Python Library Documentation: class NCHAR in module sqlalchemy.sql.sqltypes
class NCHAR(Unicode)
| NCHAR(length: 'Optional[int]' = None, collation: 'Optional[str]' = None)
|
| The SQL NCHAR type.
|
| Method resolution order:
| NCHAR
| Unicode
| String
| Concatenable
| sqlalchemy.sql.type_api.TypeEngineMixin
| sqlalchemy.sql.type_api.TypeEngine
| sqlalchemy.sql.visitors.Visitable
| typing.Generic
| builtins.object
|
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| __parameters__ = ()
|
| __visit_name__ = 'NCHAR'
|
| ----------------------------------------------------------------------
| Methods inherited from String:
|
| __init__(self, length: 'Optional[int]' = None, collation: 'Optional[str]' = None)
| Create a string-holding type.
|
| :param length: optional, a length for the column for use in
| DDL and CAST expressions. May be safely omitted if no ``CREATE
| TABLE`` will be issued. Certain databases may require a
| ``length`` for use in DDL, and will raise an exception when
| the ``CREATE TABLE`` DDL is issued if a ``VARCHAR``
| with no length is included. Whether the value is
| interpreted as bytes or characters is database specific.
|
| :param collation: Optional, a column-level collation for
| use in DDL and CAST expressions. Renders using the
| COLLATE keyword supported by SQLite, MySQL, and PostgreSQL.
| E.g.:
|
| .. sourcecode:: pycon+sql
|
| >>> from sqlalchemy import cast, select, String
| >>> print(select(cast("some string", String(collation="utf8"))))
| {printsql}SELECT CAST(:param_1 AS VARCHAR COLLATE utf8) AS anon_1
|
| .. note::
|
| In most cases, the :class:`.Unicode` or :class:`.UnicodeText`
| datatypes should be used for a :class:`_schema.Column` that expects
| to store non-ascii data. These datatypes will ensure that the
| correct types are used on the database.
|
| bind_processor(self, dialect: 'Dialect') -> 'Optional[_BindProcessorType[str]]'
| Return a conversion function for processing bind values.
|
| Returns a callable which will receive a bind parameter value
| as the sole positional argument and will return a value to
| send to the DB-API.
|
| If processing is not necessary, the method should return ``None``.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.bind_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.bind_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_bind_param`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
|
| :param dialect: Dialect instance in use.
|
| get_dbapi_type(self, dbapi)
| Return the corresponding type object from the underlying DB-API, if
| any.
|
| This can be useful for calling ``setinputsizes()``, for example.
|
| literal_processor(self, dialect)
| Return a conversion function for processing literal values that are
| to be rendered directly without using binds.
|
| This function is used when the compiler makes use of the
| "literal_binds" flag, typically used in DDL generation as well
| as in certain scenarios where backends don't accept bound parameters.
|
| Returns a callable which will receive a literal Python value
| as the sole positional argument and will return a string representation
| to be rendered in a SQL statement.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.literal_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.literal_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_literal_param`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| result_processor(self, dialect: 'Dialect', coltype: 'object') -> 'Optional[_ResultProcessorType[str]]'
| Return a conversion function for processing result row values.
|
| Returns a callable which will receive a result row column
| value as the sole positional argument and will return a value
| to return to the user.
|
| If processing is not necessary, the method should return ``None``.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.result_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.result_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_result_value`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| :param dialect: Dialect instance in use.
|
| :param coltype: DBAPI coltype argument received in cursor.description.
|
| ----------------------------------------------------------------------
| Readonly properties inherited from String:
|
| python_type
| Return the Python type object expected to be returned
| by instances of this type, if known.
|
| Basically, for those types which enforce a return type,
| or are known across the board to do such for all common
| DBAPIs (like ``int`` for example), will return that type.
|
| If a return type is not defined, raises
| ``NotImplementedError``.
|
| Note that any type also accommodates NULL in SQL which
| means you can also get back ``None`` from any type
| in practice.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from Concatenable:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from Concatenable:
|
| Comparator = <class 'sqlalchemy.sql.sqltypes.Concatenable.Comparator'>
|
| comparator_factory = <class 'sqlalchemy.sql.sqltypes.Concatenable.Comp...
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.type_api.TypeEngine:
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| __str__(self) -> 'str'
| Return str(self).
|
| adapt(self, cls: 'Type[Union[TypeEngine[Any], TypeEngineMixin]]', **kw: 'Any') -> 'TypeEngine[Any]'
| Produce an "adapted" form of this type, given an "impl" class
| to work with.
|
| This method is used internally to associate generic
| types with "implementation" types that are specific to a particular
| dialect.
|
| as_generic(self, allow_nulltype: 'bool' = False) -> 'TypeEngine[_T]'
| Return an instance of the generic type corresponding to this type
| using heuristic rule. The method may be overridden if this
| heuristic rule is not sufficient.
|
| >>> from sqlalchemy.dialects.mysql import INTEGER
| >>> INTEGER(display_width=4).as_generic()
| Integer()
|
| >>> from sqlalchemy.dialects.mysql import NVARCHAR
| >>> NVARCHAR(length=100).as_generic()
| Unicode(length=100)
|
| .. versionadded:: 1.4.0b2
|
|
| .. seealso::
|
| :ref:`metadata_reflection_dbagnostic_types` - describes the
| use of :meth:`_types.TypeEngine.as_generic` in conjunction with
| the :meth:`_sql.DDLEvents.column_reflect` event, which is its
| intended use.
|
| bind_expression(self, bindvalue: 'BindParameter[_T]') -> 'Optional[ColumnElement[_T]]'
| Given a bind value (i.e. a :class:`.BindParameter` instance),
| return a SQL expression in its place.
|
| This is typically a SQL function that wraps the existing bound
| parameter within the statement. It is used for special data types
| that require literals being wrapped in some special database function
| in order to coerce an application-level value into a database-specific
| format. It is the SQL analogue of the
| :meth:`.TypeEngine.bind_processor` method.
|
| This method is called during the **SQL compilation** phase of a
| statement, when rendering a SQL string. It is **not** called
| against specific values.
|
| Note that this method, when implemented, should always return
| the exact same structure, without any conditional logic, as it
| may be used in an executemany() call against an arbitrary number
| of bound parameter sets.
|
| .. note::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.bind_expression`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.bind_expression`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.bind_expression`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| .. seealso::
|
| :ref:`types_sql_value_processing`
|
| coerce_compared_value(self, op: 'Optional[OperatorType]', value: 'Any') -> 'TypeEngine[Any]'
| Suggest a type for a 'coerced' Python value in an expression.
|
| Given an operator and value, gives the type a chance
| to return a type which the value should be coerced into.
|
| The default behavior here is conservative; if the right-hand
| side is already coerced into a SQL type based on its
| Python type, it is usually left alone.
|
| End-user functionality extension here should generally be via
| :class:`.TypeDecorator`, which provides more liberal behavior in that
| it defaults to coercing the other side of the expression into this
| type, thus applying special Python conversions above and beyond those
| needed by the DBAPI to both ides. It also provides the public method
| :meth:`.TypeDecorator.coerce_compared_value` which is intended for
| end-user customization of this behavior.
|
| column_expression(self, colexpr: 'ColumnElement[_T]') -> 'Optional[ColumnElement[_T]]'
| Given a SELECT column expression, return a wrapping SQL expression.
|
| This is typically a SQL function that wraps a column expression
| as rendered in the columns clause of a SELECT statement.
| It is used for special data types that require
| columns to be wrapped in some special database function in order
| to coerce the value before being sent back to the application.
| It is the SQL analogue of the :meth:`.TypeEngine.result_processor`
| method.
|
| .. note:: The :func:`.TypeEngine.column_expression` method is applied
| only to the **outermost columns clause** of a SELECT statement, that
| is, the columns that are to be delivered directly into the returned
| result rows. It does **not** apply to the columns clause inside
| of subqueries. This necessarily avoids double conversions against
| the column and only runs the conversion when ready to be returned
| to the client.
|
| This method is called during the **SQL compilation** phase of a
| statement, when rendering a SQL string. It is **not** called
| against specific values.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.column_expression`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.column_expression`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.column_expression`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
|
| .. seealso::
|
| :ref:`types_sql_value_processing`
|
| compare_values(self, x: 'Any', y: 'Any') -> 'bool'
| Compare two values for equality.
|
| compile(self, dialect: 'Optional[Dialect]' = None) -> 'str'
| Produce a string-compiled form of this :class:`.TypeEngine`.
|
| When called with no arguments, uses a "default" dialect
| to produce a string result.
|
| :param dialect: a :class:`.Dialect` instance.
|
| copy(self, **kw: 'Any') -> 'Self'
|
| copy_value(self, value: 'Any') -> 'Any'
|
| dialect_impl(self, dialect: 'Dialect') -> 'TypeEngine[_T]'
| Return a dialect-specific implementation for this
| :class:`.TypeEngine`.
|
| evaluates_none(self) -> 'Self'
| Return a copy of this type which has the
| :attr:`.should_evaluate_none` flag set to True.
|
| E.g.::
|
| Table(
| "some_table",
| metadata,
| Column(
| String(50).evaluates_none(),
| nullable=True,
| server_default="no value",
| ),
| )
|
| The ORM uses this flag to indicate that a positive value of ``None``
| is passed to the column in an INSERT statement, rather than omitting
| the column from the INSERT statement which has the effect of firing
| off column-level defaults. It also allows for types which have
| special behavior associated with the Python None value to indicate
| that the value doesn't necessarily translate into SQL NULL; a
| prime example of this is a JSON type which may wish to persist the
| JSON value ``'null'``.
|
| In all cases, the actual NULL SQL value can be always be
| persisted in any column by using
| the :obj:`_expression.null` SQL construct in an INSERT statement
| or associated with an ORM-mapped attribute.
|
| .. note::
|
| The "evaluates none" flag does **not** apply to a value
| of ``None`` passed to :paramref:`_schema.Column.default` or
| :paramref:`_schema.Column.server_default`; in these cases,
| ``None``
| still means "no default".
|
| .. seealso::
|
| :ref:`session_forcing_null` - in the ORM documentation
|
| :paramref:`.postgresql.JSON.none_as_null` - PostgreSQL JSON
| interaction with this flag.
|
| :attr:`.TypeEngine.should_evaluate_none` - class-level flag
|
| with_variant(self, type_: '_TypeEngineArgument[Any]', *dialect_names: 'str') -> 'Self'
| Produce a copy of this type object that will utilize the given
| type when applied to the dialect of the given name.
|
| e.g.::
|
| from sqlalchemy.types import String
| from sqlalchemy.dialects import mysql
|
| string_type = String()
|
| string_type = string_type.with_variant(
| mysql.VARCHAR(collation="foo"), "mysql", "mariadb"
| )
|
| The variant mapping indicates that when this type is
| interpreted by a specific dialect, it will instead be
| transmuted into the given type, rather than using the
| primary type.
|
| .. versionchanged:: 2.0 the :meth:`_types.TypeEngine.with_variant`
| method now works with a :class:`_types.TypeEngine` object "in
| place", returning a copy of the original type rather than returning
| a wrapping object; the ``Variant`` class is no longer used.
|
| :param type\_: a :class:`.TypeEngine` that will be selected
| as a variant from the originating type, when a dialect
| of the given name is in use.
| :param \*dialect_names: one or more base names of the dialect which
| uses this type. (i.e. ``'postgresql'``, ``'mysql'``, etc.)
|
| .. versionchanged:: 2.0 multiple dialect names can be specified
| for one variant.
|
| .. seealso::
|
| :ref:`types_with_variant` - illustrates the use of
| :meth:`_types.TypeEngine.with_variant`.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.type_api.TypeEngine:
|
| __orig_bases__ = (<class 'sqlalchemy.sql.visitors.Visitable'>, typing....
|
| hashable = True
|
| render_bind_cast = False
|
| render_literal_cast = False
|
| should_evaluate_none = False
|
| sort_key_function = None
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.visitors.Visitable:
|
| __class_getitem__(key: 'Any') -> 'Any'
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__() -> 'None'
| This method is called when a class is subclassed.
|
| The default implementation does nothing. It may be
| overridden to extend subclasses.
sqlalchemy.NUMERIC
Python Library Documentation: class NUMERIC in module sqlalchemy.sql.sqltypes
class NUMERIC(Numeric)
| NUMERIC(precision: 'Optional[int]' = None, scale: 'Optional[int]' = None, decimal_return_scale: 'Optional[int]' = None, asdecimal: 'bool' = True)
|
| The SQL NUMERIC type.
|
| .. seealso::
|
| :class:`_types.Numeric` - documentation for the base type.
|
| Method resolution order:
| NUMERIC
| Numeric
| HasExpressionLookup
| sqlalchemy.sql.type_api.TypeEngineMixin
| sqlalchemy.sql.type_api.TypeEngine
| sqlalchemy.sql.visitors.Visitable
| typing.Generic
| builtins.object
|
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| __parameters__ = ()
|
| __visit_name__ = 'NUMERIC'
|
| ----------------------------------------------------------------------
| Methods inherited from Numeric:
|
| __init__(self, precision: 'Optional[int]' = None, scale: 'Optional[int]' = None, decimal_return_scale: 'Optional[int]' = None, asdecimal: 'bool' = True)
| Construct a Numeric.
|
| :param precision: the numeric precision for use in DDL ``CREATE
| TABLE``.
|
| :param scale: the numeric scale for use in DDL ``CREATE TABLE``.
|
| :param asdecimal: default True. Return whether or not
| values should be sent as Python Decimal objects, or
| as floats. Different DBAPIs send one or the other based on
| datatypes - the Numeric type will ensure that return values
| are one or the other across DBAPIs consistently.
|
| :param decimal_return_scale: Default scale to use when converting
| from floats to Python decimals. Floating point values will typically
| be much longer due to decimal inaccuracy, and most floating point
| database types don't have a notion of "scale", so by default the
| float type looks for the first ten decimal places when converting.
| Specifying this value will override that length. Types which
| do include an explicit ".scale" value, such as the base
| :class:`.Numeric` as well as the MySQL float types, will use the
| value of ".scale" as the default for decimal_return_scale, if not
| otherwise specified.
|
| When using the ``Numeric`` type, care should be taken to ensure
| that the asdecimal setting is appropriate for the DBAPI in use -
| when Numeric applies a conversion from Decimal->float or float->
| Decimal, this conversion incurs an additional performance overhead
| for all result columns received.
|
| DBAPIs that return Decimal natively (e.g. psycopg2) will have
| better accuracy and higher performance with a setting of ``True``,
| as the native translation to Decimal reduces the amount of floating-
| point issues at play, and the Numeric type itself doesn't need
| to apply any further conversions. However, another DBAPI which
| returns floats natively *will* incur an additional conversion
| overhead, and is still subject to floating point data loss - in
| which case ``asdecimal=False`` will at least remove the extra
| conversion overhead.
|
| bind_processor(self, dialect)
| Return a conversion function for processing bind values.
|
| Returns a callable which will receive a bind parameter value
| as the sole positional argument and will return a value to
| send to the DB-API.
|
| If processing is not necessary, the method should return ``None``.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.bind_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.bind_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_bind_param`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
|
| :param dialect: Dialect instance in use.
|
| get_dbapi_type(self, dbapi)
| Return the corresponding type object from the underlying DB-API, if
| any.
|
| This can be useful for calling ``setinputsizes()``, for example.
|
| literal_processor(self, dialect)
| Return a conversion function for processing literal values that are
| to be rendered directly without using binds.
|
| This function is used when the compiler makes use of the
| "literal_binds" flag, typically used in DDL generation as well
| as in certain scenarios where backends don't accept bound parameters.
|
| Returns a callable which will receive a literal Python value
| as the sole positional argument and will return a string representation
| to be rendered in a SQL statement.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.literal_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.literal_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_literal_param`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| result_processor(self, dialect, coltype)
| Return a conversion function for processing result row values.
|
| Returns a callable which will receive a result row column
| value as the sole positional argument and will return a value
| to return to the user.
|
| If processing is not necessary, the method should return ``None``.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.result_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.result_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_result_value`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| :param dialect: Dialect instance in use.
|
| :param coltype: DBAPI coltype argument received in cursor.description.
|
| ----------------------------------------------------------------------
| Readonly properties inherited from Numeric:
|
| python_type
| Return the Python type object expected to be returned
| by instances of this type, if known.
|
| Basically, for those types which enforce a return type,
| or are known across the board to do such for all common
| DBAPIs (like ``int`` for example), will return that type.
|
| If a return type is not defined, raises
| ``NotImplementedError``.
|
| Note that any type also accommodates NULL in SQL which
| means you can also get back ``None`` from any type
| in practice.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from HasExpressionLookup:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from HasExpressionLookup:
|
| Comparator = <class 'sqlalchemy.sql.sqltypes.HasExpressionLookup.Compa...
|
| comparator_factory = <class 'sqlalchemy.sql.sqltypes.HasExpressionLook...
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.type_api.TypeEngine:
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| __str__(self) -> 'str'
| Return str(self).
|
| adapt(self, cls: 'Type[Union[TypeEngine[Any], TypeEngineMixin]]', **kw: 'Any') -> 'TypeEngine[Any]'
| Produce an "adapted" form of this type, given an "impl" class
| to work with.
|
| This method is used internally to associate generic
| types with "implementation" types that are specific to a particular
| dialect.
|
| as_generic(self, allow_nulltype: 'bool' = False) -> 'TypeEngine[_T]'
| Return an instance of the generic type corresponding to this type
| using heuristic rule. The method may be overridden if this
| heuristic rule is not sufficient.
|
| >>> from sqlalchemy.dialects.mysql import INTEGER
| >>> INTEGER(display_width=4).as_generic()
| Integer()
|
| >>> from sqlalchemy.dialects.mysql import NVARCHAR
| >>> NVARCHAR(length=100).as_generic()
| Unicode(length=100)
|
| .. versionadded:: 1.4.0b2
|
|
| .. seealso::
|
| :ref:`metadata_reflection_dbagnostic_types` - describes the
| use of :meth:`_types.TypeEngine.as_generic` in conjunction with
| the :meth:`_sql.DDLEvents.column_reflect` event, which is its
| intended use.
|
| bind_expression(self, bindvalue: 'BindParameter[_T]') -> 'Optional[ColumnElement[_T]]'
| Given a bind value (i.e. a :class:`.BindParameter` instance),
| return a SQL expression in its place.
|
| This is typically a SQL function that wraps the existing bound
| parameter within the statement. It is used for special data types
| that require literals being wrapped in some special database function
| in order to coerce an application-level value into a database-specific
| format. It is the SQL analogue of the
| :meth:`.TypeEngine.bind_processor` method.
|
| This method is called during the **SQL compilation** phase of a
| statement, when rendering a SQL string. It is **not** called
| against specific values.
|
| Note that this method, when implemented, should always return
| the exact same structure, without any conditional logic, as it
| may be used in an executemany() call against an arbitrary number
| of bound parameter sets.
|
| .. note::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.bind_expression`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.bind_expression`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.bind_expression`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| .. seealso::
|
| :ref:`types_sql_value_processing`
|
| coerce_compared_value(self, op: 'Optional[OperatorType]', value: 'Any') -> 'TypeEngine[Any]'
| Suggest a type for a 'coerced' Python value in an expression.
|
| Given an operator and value, gives the type a chance
| to return a type which the value should be coerced into.
|
| The default behavior here is conservative; if the right-hand
| side is already coerced into a SQL type based on its
| Python type, it is usually left alone.
|
| End-user functionality extension here should generally be via
| :class:`.TypeDecorator`, which provides more liberal behavior in that
| it defaults to coercing the other side of the expression into this
| type, thus applying special Python conversions above and beyond those
| needed by the DBAPI to both ides. It also provides the public method
| :meth:`.TypeDecorator.coerce_compared_value` which is intended for
| end-user customization of this behavior.
|
| column_expression(self, colexpr: 'ColumnElement[_T]') -> 'Optional[ColumnElement[_T]]'
| Given a SELECT column expression, return a wrapping SQL expression.
|
| This is typically a SQL function that wraps a column expression
| as rendered in the columns clause of a SELECT statement.
| It is used for special data types that require
| columns to be wrapped in some special database function in order
| to coerce the value before being sent back to the application.
| It is the SQL analogue of the :meth:`.TypeEngine.result_processor`
| method.
|
| .. note:: The :func:`.TypeEngine.column_expression` method is applied
| only to the **outermost columns clause** of a SELECT statement, that
| is, the columns that are to be delivered directly into the returned
| result rows. It does **not** apply to the columns clause inside
| of subqueries. This necessarily avoids double conversions against
| the column and only runs the conversion when ready to be returned
| to the client.
|
| This method is called during the **SQL compilation** phase of a
| statement, when rendering a SQL string. It is **not** called
| against specific values.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.column_expression`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.column_expression`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.column_expression`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
|
| .. seealso::
|
| :ref:`types_sql_value_processing`
|
| compare_values(self, x: 'Any', y: 'Any') -> 'bool'
| Compare two values for equality.
|
| compile(self, dialect: 'Optional[Dialect]' = None) -> 'str'
| Produce a string-compiled form of this :class:`.TypeEngine`.
|
| When called with no arguments, uses a "default" dialect
| to produce a string result.
|
| :param dialect: a :class:`.Dialect` instance.
|
| copy(self, **kw: 'Any') -> 'Self'
|
| copy_value(self, value: 'Any') -> 'Any'
|
| dialect_impl(self, dialect: 'Dialect') -> 'TypeEngine[_T]'
| Return a dialect-specific implementation for this
| :class:`.TypeEngine`.
|
| evaluates_none(self) -> 'Self'
| Return a copy of this type which has the
| :attr:`.should_evaluate_none` flag set to True.
|
| E.g.::
|
| Table(
| "some_table",
| metadata,
| Column(
| String(50).evaluates_none(),
| nullable=True,
| server_default="no value",
| ),
| )
|
| The ORM uses this flag to indicate that a positive value of ``None``
| is passed to the column in an INSERT statement, rather than omitting
| the column from the INSERT statement which has the effect of firing
| off column-level defaults. It also allows for types which have
| special behavior associated with the Python None value to indicate
| that the value doesn't necessarily translate into SQL NULL; a
| prime example of this is a JSON type which may wish to persist the
| JSON value ``'null'``.
|
| In all cases, the actual NULL SQL value can be always be
| persisted in any column by using
| the :obj:`_expression.null` SQL construct in an INSERT statement
| or associated with an ORM-mapped attribute.
|
| .. note::
|
| The "evaluates none" flag does **not** apply to a value
| of ``None`` passed to :paramref:`_schema.Column.default` or
| :paramref:`_schema.Column.server_default`; in these cases,
| ``None``
| still means "no default".
|
| .. seealso::
|
| :ref:`session_forcing_null` - in the ORM documentation
|
| :paramref:`.postgresql.JSON.none_as_null` - PostgreSQL JSON
| interaction with this flag.
|
| :attr:`.TypeEngine.should_evaluate_none` - class-level flag
|
| with_variant(self, type_: '_TypeEngineArgument[Any]', *dialect_names: 'str') -> 'Self'
| Produce a copy of this type object that will utilize the given
| type when applied to the dialect of the given name.
|
| e.g.::
|
| from sqlalchemy.types import String
| from sqlalchemy.dialects import mysql
|
| string_type = String()
|
| string_type = string_type.with_variant(
| mysql.VARCHAR(collation="foo"), "mysql", "mariadb"
| )
|
| The variant mapping indicates that when this type is
| interpreted by a specific dialect, it will instead be
| transmuted into the given type, rather than using the
| primary type.
|
| .. versionchanged:: 2.0 the :meth:`_types.TypeEngine.with_variant`
| method now works with a :class:`_types.TypeEngine` object "in
| place", returning a copy of the original type rather than returning
| a wrapping object; the ``Variant`` class is no longer used.
|
| :param type\_: a :class:`.TypeEngine` that will be selected
| as a variant from the originating type, when a dialect
| of the given name is in use.
| :param \*dialect_names: one or more base names of the dialect which
| uses this type. (i.e. ``'postgresql'``, ``'mysql'``, etc.)
|
| .. versionchanged:: 2.0 multiple dialect names can be specified
| for one variant.
|
| .. seealso::
|
| :ref:`types_with_variant` - illustrates the use of
| :meth:`_types.TypeEngine.with_variant`.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.type_api.TypeEngine:
|
| __orig_bases__ = (<class 'sqlalchemy.sql.visitors.Visitable'>, typing....
|
| hashable = True
|
| render_bind_cast = False
|
| render_literal_cast = False
|
| should_evaluate_none = False
|
| sort_key_function = None
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.visitors.Visitable:
|
| __class_getitem__(key: 'Any') -> 'Any'
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__() -> 'None'
| This method is called when a class is subclassed.
|
| The default implementation does nothing. It may be
| overridden to extend subclasses.
sqlalchemy.NVARCHAR
Python Library Documentation: class NVARCHAR in module sqlalchemy.sql.sqltypes
class NVARCHAR(Unicode)
| NVARCHAR(length: 'Optional[int]' = None, collation: 'Optional[str]' = None)
|
| The SQL NVARCHAR type.
|
| Method resolution order:
| NVARCHAR
| Unicode
| String
| Concatenable
| sqlalchemy.sql.type_api.TypeEngineMixin
| sqlalchemy.sql.type_api.TypeEngine
| sqlalchemy.sql.visitors.Visitable
| typing.Generic
| builtins.object
|
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| __parameters__ = ()
|
| __visit_name__ = 'NVARCHAR'
|
| ----------------------------------------------------------------------
| Methods inherited from String:
|
| __init__(self, length: 'Optional[int]' = None, collation: 'Optional[str]' = None)
| Create a string-holding type.
|
| :param length: optional, a length for the column for use in
| DDL and CAST expressions. May be safely omitted if no ``CREATE
| TABLE`` will be issued. Certain databases may require a
| ``length`` for use in DDL, and will raise an exception when
| the ``CREATE TABLE`` DDL is issued if a ``VARCHAR``
| with no length is included. Whether the value is
| interpreted as bytes or characters is database specific.
|
| :param collation: Optional, a column-level collation for
| use in DDL and CAST expressions. Renders using the
| COLLATE keyword supported by SQLite, MySQL, and PostgreSQL.
| E.g.:
|
| .. sourcecode:: pycon+sql
|
| >>> from sqlalchemy import cast, select, String
| >>> print(select(cast("some string", String(collation="utf8"))))
| {printsql}SELECT CAST(:param_1 AS VARCHAR COLLATE utf8) AS anon_1
|
| .. note::
|
| In most cases, the :class:`.Unicode` or :class:`.UnicodeText`
| datatypes should be used for a :class:`_schema.Column` that expects
| to store non-ascii data. These datatypes will ensure that the
| correct types are used on the database.
|
| bind_processor(self, dialect: 'Dialect') -> 'Optional[_BindProcessorType[str]]'
| Return a conversion function for processing bind values.
|
| Returns a callable which will receive a bind parameter value
| as the sole positional argument and will return a value to
| send to the DB-API.
|
| If processing is not necessary, the method should return ``None``.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.bind_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.bind_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_bind_param`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
|
| :param dialect: Dialect instance in use.
|
| get_dbapi_type(self, dbapi)
| Return the corresponding type object from the underlying DB-API, if
| any.
|
| This can be useful for calling ``setinputsizes()``, for example.
|
| literal_processor(self, dialect)
| Return a conversion function for processing literal values that are
| to be rendered directly without using binds.
|
| This function is used when the compiler makes use of the
| "literal_binds" flag, typically used in DDL generation as well
| as in certain scenarios where backends don't accept bound parameters.
|
| Returns a callable which will receive a literal Python value
| as the sole positional argument and will return a string representation
| to be rendered in a SQL statement.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.literal_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.literal_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_literal_param`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| result_processor(self, dialect: 'Dialect', coltype: 'object') -> 'Optional[_ResultProcessorType[str]]'
| Return a conversion function for processing result row values.
|
| Returns a callable which will receive a result row column
| value as the sole positional argument and will return a value
| to return to the user.
|
| If processing is not necessary, the method should return ``None``.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.result_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.result_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_result_value`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| :param dialect: Dialect instance in use.
|
| :param coltype: DBAPI coltype argument received in cursor.description.
|
| ----------------------------------------------------------------------
| Readonly properties inherited from String:
|
| python_type
| Return the Python type object expected to be returned
| by instances of this type, if known.
|
| Basically, for those types which enforce a return type,
| or are known across the board to do such for all common
| DBAPIs (like ``int`` for example), will return that type.
|
| If a return type is not defined, raises
| ``NotImplementedError``.
|
| Note that any type also accommodates NULL in SQL which
| means you can also get back ``None`` from any type
| in practice.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from Concatenable:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from Concatenable:
|
| Comparator = <class 'sqlalchemy.sql.sqltypes.Concatenable.Comparator'>
|
| comparator_factory = <class 'sqlalchemy.sql.sqltypes.Concatenable.Comp...
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.type_api.TypeEngine:
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| __str__(self) -> 'str'
| Return str(self).
|
| adapt(self, cls: 'Type[Union[TypeEngine[Any], TypeEngineMixin]]', **kw: 'Any') -> 'TypeEngine[Any]'
| Produce an "adapted" form of this type, given an "impl" class
| to work with.
|
| This method is used internally to associate generic
| types with "implementation" types that are specific to a particular
| dialect.
|
| as_generic(self, allow_nulltype: 'bool' = False) -> 'TypeEngine[_T]'
| Return an instance of the generic type corresponding to this type
| using heuristic rule. The method may be overridden if this
| heuristic rule is not sufficient.
|
| >>> from sqlalchemy.dialects.mysql import INTEGER
| >>> INTEGER(display_width=4).as_generic()
| Integer()
|
| >>> from sqlalchemy.dialects.mysql import NVARCHAR
| >>> NVARCHAR(length=100).as_generic()
| Unicode(length=100)
|
| .. versionadded:: 1.4.0b2
|
|
| .. seealso::
|
| :ref:`metadata_reflection_dbagnostic_types` - describes the
| use of :meth:`_types.TypeEngine.as_generic` in conjunction with
| the :meth:`_sql.DDLEvents.column_reflect` event, which is its
| intended use.
|
| bind_expression(self, bindvalue: 'BindParameter[_T]') -> 'Optional[ColumnElement[_T]]'
| Given a bind value (i.e. a :class:`.BindParameter` instance),
| return a SQL expression in its place.
|
| This is typically a SQL function that wraps the existing bound
| parameter within the statement. It is used for special data types
| that require literals being wrapped in some special database function
| in order to coerce an application-level value into a database-specific
| format. It is the SQL analogue of the
| :meth:`.TypeEngine.bind_processor` method.
|
| This method is called during the **SQL compilation** phase of a
| statement, when rendering a SQL string. It is **not** called
| against specific values.
|
| Note that this method, when implemented, should always return
| the exact same structure, without any conditional logic, as it
| may be used in an executemany() call against an arbitrary number
| of bound parameter sets.
|
| .. note::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.bind_expression`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.bind_expression`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.bind_expression`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| .. seealso::
|
| :ref:`types_sql_value_processing`
|
| coerce_compared_value(self, op: 'Optional[OperatorType]', value: 'Any') -> 'TypeEngine[Any]'
| Suggest a type for a 'coerced' Python value in an expression.
|
| Given an operator and value, gives the type a chance
| to return a type which the value should be coerced into.
|
| The default behavior here is conservative; if the right-hand
| side is already coerced into a SQL type based on its
| Python type, it is usually left alone.
|
| End-user functionality extension here should generally be via
| :class:`.TypeDecorator`, which provides more liberal behavior in that
| it defaults to coercing the other side of the expression into this
| type, thus applying special Python conversions above and beyond those
| needed by the DBAPI to both ides. It also provides the public method
| :meth:`.TypeDecorator.coerce_compared_value` which is intended for
| end-user customization of this behavior.
|
| column_expression(self, colexpr: 'ColumnElement[_T]') -> 'Optional[ColumnElement[_T]]'
| Given a SELECT column expression, return a wrapping SQL expression.
|
| This is typically a SQL function that wraps a column expression
| as rendered in the columns clause of a SELECT statement.
| It is used for special data types that require
| columns to be wrapped in some special database function in order
| to coerce the value before being sent back to the application.
| It is the SQL analogue of the :meth:`.TypeEngine.result_processor`
| method.
|
| .. note:: The :func:`.TypeEngine.column_expression` method is applied
| only to the **outermost columns clause** of a SELECT statement, that
| is, the columns that are to be delivered directly into the returned
| result rows. It does **not** apply to the columns clause inside
| of subqueries. This necessarily avoids double conversions against
| the column and only runs the conversion when ready to be returned
| to the client.
|
| This method is called during the **SQL compilation** phase of a
| statement, when rendering a SQL string. It is **not** called
| against specific values.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.column_expression`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.column_expression`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.column_expression`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
|
| .. seealso::
|
| :ref:`types_sql_value_processing`
|
| compare_values(self, x: 'Any', y: 'Any') -> 'bool'
| Compare two values for equality.
|
| compile(self, dialect: 'Optional[Dialect]' = None) -> 'str'
| Produce a string-compiled form of this :class:`.TypeEngine`.
|
| When called with no arguments, uses a "default" dialect
| to produce a string result.
|
| :param dialect: a :class:`.Dialect` instance.
|
| copy(self, **kw: 'Any') -> 'Self'
|
| copy_value(self, value: 'Any') -> 'Any'
|
| dialect_impl(self, dialect: 'Dialect') -> 'TypeEngine[_T]'
| Return a dialect-specific implementation for this
| :class:`.TypeEngine`.
|
| evaluates_none(self) -> 'Self'
| Return a copy of this type which has the
| :attr:`.should_evaluate_none` flag set to True.
|
| E.g.::
|
| Table(
| "some_table",
| metadata,
| Column(
| String(50).evaluates_none(),
| nullable=True,
| server_default="no value",
| ),
| )
|
| The ORM uses this flag to indicate that a positive value of ``None``
| is passed to the column in an INSERT statement, rather than omitting
| the column from the INSERT statement which has the effect of firing
| off column-level defaults. It also allows for types which have
| special behavior associated with the Python None value to indicate
| that the value doesn't necessarily translate into SQL NULL; a
| prime example of this is a JSON type which may wish to persist the
| JSON value ``'null'``.
|
| In all cases, the actual NULL SQL value can be always be
| persisted in any column by using
| the :obj:`_expression.null` SQL construct in an INSERT statement
| or associated with an ORM-mapped attribute.
|
| .. note::
|
| The "evaluates none" flag does **not** apply to a value
| of ``None`` passed to :paramref:`_schema.Column.default` or
| :paramref:`_schema.Column.server_default`; in these cases,
| ``None``
| still means "no default".
|
| .. seealso::
|
| :ref:`session_forcing_null` - in the ORM documentation
|
| :paramref:`.postgresql.JSON.none_as_null` - PostgreSQL JSON
| interaction with this flag.
|
| :attr:`.TypeEngine.should_evaluate_none` - class-level flag
|
| with_variant(self, type_: '_TypeEngineArgument[Any]', *dialect_names: 'str') -> 'Self'
| Produce a copy of this type object that will utilize the given
| type when applied to the dialect of the given name.
|
| e.g.::
|
| from sqlalchemy.types import String
| from sqlalchemy.dialects import mysql
|
| string_type = String()
|
| string_type = string_type.with_variant(
| mysql.VARCHAR(collation="foo"), "mysql", "mariadb"
| )
|
| The variant mapping indicates that when this type is
| interpreted by a specific dialect, it will instead be
| transmuted into the given type, rather than using the
| primary type.
|
| .. versionchanged:: 2.0 the :meth:`_types.TypeEngine.with_variant`
| method now works with a :class:`_types.TypeEngine` object "in
| place", returning a copy of the original type rather than returning
| a wrapping object; the ``Variant`` class is no longer used.
|
| :param type\_: a :class:`.TypeEngine` that will be selected
| as a variant from the originating type, when a dialect
| of the given name is in use.
| :param \*dialect_names: one or more base names of the dialect which
| uses this type. (i.e. ``'postgresql'``, ``'mysql'``, etc.)
|
| .. versionchanged:: 2.0 multiple dialect names can be specified
| for one variant.
|
| .. seealso::
|
| :ref:`types_with_variant` - illustrates the use of
| :meth:`_types.TypeEngine.with_variant`.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.type_api.TypeEngine:
|
| __orig_bases__ = (<class 'sqlalchemy.sql.visitors.Visitable'>, typing....
|
| hashable = True
|
| render_bind_cast = False
|
| render_literal_cast = False
|
| should_evaluate_none = False
|
| sort_key_function = None
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.visitors.Visitable:
|
| __class_getitem__(key: 'Any') -> 'Any'
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__() -> 'None'
| This method is called when a class is subclassed.
|
| The default implementation does nothing. It may be
| overridden to extend subclasses.
sqlalchemy.NestedTransaction
Python Library Documentation: class NestedTransaction in module sqlalchemy.engine.base
class NestedTransaction(Transaction)
| NestedTransaction(connection: 'Connection')
|
| Represent a 'nested', or SAVEPOINT transaction.
|
| The :class:`.NestedTransaction` object is created by calling the
| :meth:`_engine.Connection.begin_nested` method of
| :class:`_engine.Connection`.
|
| When using :class:`.NestedTransaction`, the semantics of "begin" /
| "commit" / "rollback" are as follows:
|
| * the "begin" operation corresponds to the "BEGIN SAVEPOINT" command, where
| the savepoint is given an explicit name that is part of the state
| of this object.
|
| * The :meth:`.NestedTransaction.commit` method corresponds to a
| "RELEASE SAVEPOINT" operation, using the savepoint identifier associated
| with this :class:`.NestedTransaction`.
|
| * The :meth:`.NestedTransaction.rollback` method corresponds to a
| "ROLLBACK TO SAVEPOINT" operation, using the savepoint identifier
| associated with this :class:`.NestedTransaction`.
|
| The rationale for mimicking the semantics of an outer transaction in
| terms of savepoints so that code may deal with a "savepoint" transaction
| and an "outer" transaction in an agnostic way.
|
| .. seealso::
|
| :ref:`session_begin_nested` - ORM version of the SAVEPOINT API.
|
| Method resolution order:
| NestedTransaction
| Transaction
| sqlalchemy.engine.util.TransactionalContext
| builtins.object
|
| Methods defined here:
|
| __init__(self, connection: 'Connection')
| Initialize self. See help(type(self)) for accurate signature.
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| connection
|
| is_active
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'_savepoint': 'str'}
|
| ----------------------------------------------------------------------
| Methods inherited from Transaction:
|
| close(self) -> 'None'
| Close this :class:`.Transaction`.
|
| If this transaction is the base transaction in a begin/commit
| nesting, the transaction will rollback(). Otherwise, the
| method returns.
|
| This is used to cancel a Transaction without affecting the scope of
| an enclosing transaction.
|
| commit(self) -> 'None'
| Commit this :class:`.Transaction`.
|
| The implementation of this may vary based on the type of transaction in
| use:
|
| * For a simple database transaction (e.g. :class:`.RootTransaction`),
| it corresponds to a COMMIT.
|
| * For a :class:`.NestedTransaction`, it corresponds to a
| "RELEASE SAVEPOINT" operation.
|
| * For a :class:`.TwoPhaseTransaction`, DBAPI-specific methods for two
| phase transactions may be used.
|
| rollback(self) -> 'None'
| Roll back this :class:`.Transaction`.
|
| The implementation of this may vary based on the type of transaction in
| use:
|
| * For a simple database transaction (e.g. :class:`.RootTransaction`),
| it corresponds to a ROLLBACK.
|
| * For a :class:`.NestedTransaction`, it corresponds to a
| "ROLLBACK TO SAVEPOINT" operation.
|
| * For a :class:`.TwoPhaseTransaction`, DBAPI-specific methods for two
| phase transactions may be used.
|
| ----------------------------------------------------------------------
| Readonly properties inherited from Transaction:
|
| is_valid
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.engine.util.TransactionalContext:
|
| __enter__(self) -> 'Self'
|
| __exit__(self, type_: 'Any', value: 'Any', traceback: 'Any') -> 'None'
|
| ----------------------------------------------------------------------
| Data descriptors inherited from sqlalchemy.engine.util.TransactionalContext:
|
| __weakref__
| list of weak references to the object
sqlalchemy.NotNullable
Python Library Documentation: function NotNullable in module sqlalchemy.sql._typing
NotNullable(val: 'Union[_TypedColumnClauseArgument[Optional[_T]], Optional[Type[_T]]]') -> '_TypedColumnClauseArgument[_T]'
Types a column or ORM class as not nullable.
This can be used in select and other contexts to express that the value of
a column cannot be null, for example due to a where condition on a
nullable column::
stmt = select(NotNullable(A.value)).where(A.value.is_not(None))
At runtime this method returns the input unchanged.
.. versionadded:: 2.0.20
sqlalchemy.Null
Python Library Documentation: class Null in module sqlalchemy.sql.elements
class Null(sqlalchemy.sql.base.SingletonConstant, sqlalchemy.sql.roles.ConstExprRole, ColumnElement)
| Null(*arg: 'Any', **kw: 'Any') -> '_T'
|
| Represent the NULL keyword in a SQL statement.
|
| :class:`.Null` is accessed as a constant via the
| :func:`.null` function.
|
| Method resolution order:
| Null
| sqlalchemy.sql.base.SingletonConstant
| sqlalchemy.sql.base.Immutable
| sqlalchemy.sql.roles.ConstExprRole
| ColumnElement
| sqlalchemy.sql.roles.ColumnArgumentOrKeyRole
| sqlalchemy.sql.roles.ColumnArgumentRole
| sqlalchemy.sql.roles.StatementOptionRole
| sqlalchemy.sql.roles.WhereHavingRole
| sqlalchemy.sql.roles.OnClauseRole
| sqlalchemy.sql.roles.BinaryElementRole
| sqlalchemy.sql.roles.OrderByRole
| sqlalchemy.sql.roles.ColumnsClauseRole
| sqlalchemy.sql.roles.AllowsLambdaRole
| sqlalchemy.sql.roles.ByOfRole
| sqlalchemy.sql.roles.UsesInspection
| sqlalchemy.sql.roles.ColumnListRole
| sqlalchemy.sql.roles.LimitOffsetRole
| sqlalchemy.sql.roles.DMLColumnRole
| sqlalchemy.sql.roles.DDLConstraintColumnRole
| sqlalchemy.sql.roles.DDLExpressionRole
| sqlalchemy.sql.roles.StructuralRole
| SQLColumnExpression
| SQLCoreOperations
| sqlalchemy.sql.roles.ExpressionElementRole
| sqlalchemy.sql.roles.TypedColumnsClauseRole
| typing.Generic
| sqlalchemy.sql.operators.ColumnOperators
| sqlalchemy.sql.operators.Operators
| sqlalchemy.util.langhelpers.TypingOnly
| sqlalchemy.sql.roles.SQLRole
| DQLDMLClauseElement
| ClauseElement
| sqlalchemy.sql.annotation.SupportsWrappingAnnotations
| sqlalchemy.sql.annotation.SupportsAnnotations
| sqlalchemy.sql.cache_key.MemoizedHasCacheKey
| sqlalchemy.sql.cache_key.HasCacheKey
| sqlalchemy.util.langhelpers.HasMemoized
| sqlalchemy.sql.traversals.HasCopyInternals
| sqlalchemy.sql.visitors.ExternallyTraversible
| sqlalchemy.sql.visitors.HasTraverseInternals
| CompilerElement
| sqlalchemy.sql.visitors.Visitable
| builtins.object
|
| Methods defined here:
|
| type(...)
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'_singleton': 'Null', '_traverse_internals': '_Trav...
|
| __orig_bases__ = (<class 'sqlalchemy.sql.base.SingletonConstant'>, sql...
|
| __parameters__ = ()
|
| __visit_name__ = 'null'
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.base.SingletonConstant:
|
| proxy_set(...)
|
| ----------------------------------------------------------------------
| Static methods inherited from sqlalchemy.sql.base.SingletonConstant:
|
| __new__(cls: '_T', *arg: 'Any', **kw: 'Any') -> '_T'
| Create and return a new object. See help(type) for accurate signature.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from sqlalchemy.sql.base.SingletonConstant:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.base.Immutable:
|
| params(self, *optionaldict: 'Any', **kwargs: 'Any') -> 'NoReturn'
|
| unique_params(self, *optionaldict: 'Any', **kwargs: 'Any') -> 'NoReturn'
|
| ----------------------------------------------------------------------
| Methods inherited from ColumnElement:
|
| __getattr__(self, key: 'str') -> 'Any'
|
| __setstate__(self, state)
|
| base_columns(...)
|
| cast(self, type_: '_TypeEngineArgument[_OPT]') -> 'Cast[_OPT]'
| Produce a type cast, i.e. ``CAST(<expression> AS <type>)``.
|
| This is a shortcut to the :func:`_expression.cast` function.
|
| .. seealso::
|
| :ref:`tutorial_casts`
|
| :func:`_expression.cast`
|
| :func:`_expression.type_coerce`
|
| comparator(...)
|
| label(self, name: 'Optional[str]') -> 'Label[_T]'
| Produce a column label, i.e. ``<columnname> AS <name>``.
|
| This is a shortcut to the :func:`_expression.label` function.
|
| If 'name' is ``None``, an anonymous label name will be generated.
|
| operate(self, op: 'operators.OperatorType', *other: 'Any', **kwargs: 'Any') -> 'ColumnElement[Any]'
| Operate on an argument.
|
| This is the lowest level of operation, raises
| :class:`NotImplementedError` by default.
|
| Overriding this on a subclass can allow common
| behavior to be applied to all operations.
| For example, overriding :class:`.ColumnOperators`
| to apply ``func.lower()`` to the left and right
| side::
|
| class MyComparator(ColumnOperators):
| def operate(self, op, other, **kwargs):
| return op(func.lower(self), func.lower(other), **kwargs)
|
| :param op: Operator callable.
| :param \*other: the 'other' side of the operation. Will
| be a single scalar for most operations.
| :param \**kwargs: modifiers. These may be passed by special
| operators such as :meth:`ColumnOperators.contains`.
|
| reverse_operate(self, op: 'operators.OperatorType', other: 'Any', **kwargs: 'Any') -> 'ColumnElement[Any]'
| Reverse operate on an argument.
|
| Usage is the same as :meth:`operate`.
|
| self_group(self, against: 'Optional[OperatorType]' = None) -> 'ColumnElement[Any]'
| 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.
|
| shares_lineage(self, othercolumn: 'ColumnElement[Any]') -> 'bool'
| Return True if the given :class:`_expression.ColumnElement`
| has a common ancestor to this :class:`_expression.ColumnElement`.
|
| ----------------------------------------------------------------------
| Readonly properties inherited from ColumnElement:
|
| anon_key_label
| .. deprecated:: 1.4 The :attr:`_expression.ColumnElement.anon_key_label` attribute is now private, and the public accessor is deprecated.
|
| anon_label
| .. deprecated:: 1.4 The :attr:`_expression.ColumnElement.anon_label` attribute is now private, and the public accessor is deprecated.
|
| expression
| Return a column expression.
|
| Part of the inspection interface; returns self.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from ColumnElement:
|
| foreign_keys = frozenset()
|
| key = None
|
| primary_key = False
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.AllowsLambdaRole:
|
| allows_lambda = True
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.UsesInspection:
|
| uses_inspection = True
|
| ----------------------------------------------------------------------
| Class methods inherited from typing.Generic:
|
| __class_getitem__(...)
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__(...)
| Function to initialize subclasses.
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.operators.ColumnOperators:
|
| __add__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``+`` operator.
|
| In a column context, produces the clause ``a + b``
| if the parent object has non-string affinity.
| If the parent object has a string affinity,
| produces the concatenation operator, ``a || b`` -
| see :meth:`.ColumnOperators.concat`.
|
| __contains__(self, other: 'Any') -> 'ColumnOperators'
|
| __eq__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``==`` operator.
|
| In a column context, produces the clause ``a = b``.
| If the target is ``None``, produces ``a IS NULL``.
|
| __floordiv__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``//`` operator.
|
| In a column context, produces the clause ``a / b``,
| which is the same as "truediv", but considers the result
| type to be integer.
|
| .. versionadded:: 2.0
|
| __ge__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``>=`` operator.
|
| In a column context, produces the clause ``a >= b``.
|
| __getitem__(self, index: 'Any') -> 'ColumnOperators'
| Implement the [] operator.
|
| This can be used by some database-specific types
| such as PostgreSQL ARRAY and HSTORE.
|
| __gt__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``>`` operator.
|
| In a column context, produces the clause ``a > b``.
|
| __hash__(self, /) from builtins.object
| Return hash(self).
|
| __le__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``<=`` operator.
|
| In a column context, produces the clause ``a <= b``.
|
| __lshift__(self, other: 'Any') -> 'ColumnOperators'
| implement the << operator.
|
| Not used by SQLAlchemy core, this is provided
| for custom operator systems which want to use
| << as an extension point.
|
| __lt__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``<`` operator.
|
| In a column context, produces the clause ``a < b``.
|
| __mod__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``%`` operator.
|
| In a column context, produces the clause ``a % b``.
|
| __mul__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``*`` operator.
|
| In a column context, produces the clause ``a * b``.
|
| __ne__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``!=`` operator.
|
| In a column context, produces the clause ``a != b``.
| If the target is ``None``, produces ``a IS NOT NULL``.
|
| __neg__(self) -> 'ColumnOperators'
| Implement the ``-`` operator.
|
| In a column context, produces the clause ``-a``.
|
| __radd__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``+`` operator in reverse.
|
| See :meth:`.ColumnOperators.__add__`.
|
| __rfloordiv__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``//`` operator in reverse.
|
| See :meth:`.ColumnOperators.__floordiv__`.
|
| __rmod__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``%`` operator in reverse.
|
| See :meth:`.ColumnOperators.__mod__`.
|
| __rmul__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``*`` operator in reverse.
|
| See :meth:`.ColumnOperators.__mul__`.
|
| __rshift__(self, other: 'Any') -> 'ColumnOperators'
| implement the >> operator.
|
| Not used by SQLAlchemy core, this is provided
| for custom operator systems which want to use
| >> as an extension point.
|
| __rsub__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``-`` operator in reverse.
|
| See :meth:`.ColumnOperators.__sub__`.
|
| __rtruediv__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``/`` operator in reverse.
|
| See :meth:`.ColumnOperators.__truediv__`.
|
| __sub__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``-`` operator.
|
| In a column context, produces the clause ``a - b``.
|
| __truediv__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``/`` operator.
|
| In a column context, produces the clause ``a / b``, and
| considers the result type to be numeric.
|
| .. versionchanged:: 2.0 The truediv operator against two integers
| is now considered to return a numeric value. Behavior on specific
| backends may vary.
|
| all_(self) -> 'ColumnOperators'
| Produce an :func:`_expression.all_` clause against the
| parent object.
|
| See the documentation for :func:`_sql.all_` for examples.
|
| .. note:: be sure to not confuse the newer
| :meth:`_sql.ColumnOperators.all_` method with the **legacy**
| version of this method, the :meth:`_types.ARRAY.Comparator.all`
| method that's specific to :class:`_types.ARRAY`, which uses a
| different calling style.
|
| any_(self) -> 'ColumnOperators'
| Produce an :func:`_expression.any_` clause against the
| parent object.
|
| See the documentation for :func:`_sql.any_` for examples.
|
| .. note:: be sure to not confuse the newer
| :meth:`_sql.ColumnOperators.any_` method with the **legacy**
| version of this method, the :meth:`_types.ARRAY.Comparator.any`
| method that's specific to :class:`_types.ARRAY`, which uses a
| different calling style.
|
| asc(self) -> 'ColumnOperators'
| Produce a :func:`_expression.asc` clause against the
| parent object.
|
| between(self, cleft: 'Any', cright: 'Any', symmetric: 'bool' = False) -> 'ColumnOperators'
| Produce a :func:`_expression.between` clause against
| the parent object, given the lower and upper range.
|
| bitwise_and(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise AND operation, typically via the ``&``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_lshift(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise LSHIFT operation, typically via the ``<<``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_not(self) -> 'ColumnOperators'
| Produce a bitwise NOT operation, typically via the ``~``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_or(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise OR operation, typically via the ``|``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_rshift(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise RSHIFT operation, typically via the ``>>``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_xor(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise XOR operation, typically via the ``^``
| operator, or ``#`` for PostgreSQL.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| collate(self, collation: 'str') -> 'ColumnOperators'
| Produce a :func:`_expression.collate` clause against
| the parent object, given the collation string.
|
| .. seealso::
|
| :func:`_expression.collate`
|
| concat(self, other: 'Any') -> 'ColumnOperators'
| Implement the 'concat' operator.
|
| In a column context, produces the clause ``a || b``,
| or uses the ``concat()`` operator on MySQL.
|
| contains(self, other: 'Any', **kw: 'Any') -> 'ColumnOperators'
| Implement the 'contains' operator.
|
| Produces a LIKE expression that tests against a match for the middle
| of a string value:
|
| .. sourcecode:: sql
|
| column LIKE '%' || <other> || '%'
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.contains("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.contains.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.contains.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.contains.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.contains("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE '%' || :param || '%' ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.contains("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE '%' || :param || '%' ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.contains.autoescape`::
|
| somecolumn.contains("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.startswith`
|
| :meth:`.ColumnOperators.endswith`
|
| :meth:`.ColumnOperators.like`
|
| desc(self) -> 'ColumnOperators'
| Produce a :func:`_expression.desc` clause against the
| parent object.
|
| distinct(self) -> 'ColumnOperators'
| Produce a :func:`_expression.distinct` clause against the
| parent object.
|
| endswith(self, other: 'Any', escape: 'Optional[str]' = None, autoescape: 'bool' = False) -> 'ColumnOperators'
| Implement the 'endswith' operator.
|
| Produces a LIKE expression that tests against a match for the end
| of a string value:
|
| .. sourcecode:: sql
|
| column LIKE '%' || <other>
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.endswith("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.endswith.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.endswith.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.endswith.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.endswith("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE '%' || :param ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.endswith("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE '%' || :param ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.endswith.autoescape`::
|
| somecolumn.endswith("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.startswith`
|
| :meth:`.ColumnOperators.contains`
|
| :meth:`.ColumnOperators.like`
|
| icontains(self, other: 'Any', **kw: 'Any') -> 'ColumnOperators'
| Implement the ``icontains`` operator, e.g. case insensitive
| version of :meth:`.ColumnOperators.contains`.
|
| Produces a LIKE expression that tests against an insensitive match
| for the middle of a string value:
|
| .. sourcecode:: sql
|
| lower(column) LIKE '%' || lower(<other>) || '%'
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.icontains("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.icontains.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.icontains.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.icontains.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.icontains("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE '%' || lower(:param) || '%' ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.icontains("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE '%' || lower(:param) || '%' ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.contains.autoescape`::
|
| somecolumn.icontains("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.contains`
|
| iendswith(self, other: 'Any', escape: 'Optional[str]' = None, autoescape: 'bool' = False) -> 'ColumnOperators'
| Implement the ``iendswith`` operator, e.g. case insensitive
| version of :meth:`.ColumnOperators.endswith`.
|
| Produces a LIKE expression that tests against an insensitive match
| for the end of a string value:
|
| .. sourcecode:: sql
|
| lower(column) LIKE '%' || lower(<other>)
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.iendswith("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.iendswith.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.iendswith.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.iendswith.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.iendswith("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE '%' || lower(:param) ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.iendswith("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE '%' || lower(:param) ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.iendswith.autoescape`::
|
| somecolumn.endswith("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.endswith`
|
| ilike(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
| Implement the ``ilike`` operator, e.g. case insensitive LIKE.
|
| In a column context, produces an expression either of the form:
|
| .. sourcecode:: sql
|
| lower(a) LIKE lower(other)
|
| Or on backends that support the ILIKE operator:
|
| .. sourcecode:: sql
|
| a ILIKE other
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.ilike("%foobar%"))
|
| :param other: expression to be compared
| :param escape: optional escape character, renders the ``ESCAPE``
| keyword, e.g.::
|
| somecolumn.ilike("foo/%bar", escape="/")
|
| .. seealso::
|
| :meth:`.ColumnOperators.like`
|
| in_(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``in`` operator.
|
| In a column context, produces the clause ``column IN <other>``.
|
| The given parameter ``other`` may be:
|
| * A list of literal values,
| e.g.::
|
| stmt.where(column.in_([1, 2, 3]))
|
| In this calling form, the list of items is converted to a set of
| bound parameters the same length as the list given:
|
| .. sourcecode:: sql
|
| WHERE COL IN (?, ?, ?)
|
| * A list of tuples may be provided if the comparison is against a
| :func:`.tuple_` containing multiple expressions::
|
| from sqlalchemy import tuple_
|
| stmt.where(tuple_(col1, col2).in_([(1, 10), (2, 20), (3, 30)]))
|
| * An empty list,
| e.g.::
|
| stmt.where(column.in_([]))
|
| In this calling form, the expression renders an "empty set"
| expression. These expressions are tailored to individual backends
| and are generally trying to get an empty SELECT statement as a
| subquery. Such as on SQLite, the expression is:
|
| .. sourcecode:: sql
|
| WHERE col IN (SELECT 1 FROM (SELECT 1) WHERE 1!=1)
|
| .. versionchanged:: 1.4 empty IN expressions now use an
| execution-time generated SELECT subquery in all cases.
|
| * A bound parameter, e.g. :func:`.bindparam`, may be used if it
| includes the :paramref:`.bindparam.expanding` flag::
|
| stmt.where(column.in_(bindparam("value", expanding=True)))
|
| In this calling form, the expression renders a special non-SQL
| placeholder expression that looks like:
|
| .. sourcecode:: sql
|
| WHERE COL IN ([EXPANDING_value])
|
| This placeholder expression is intercepted at statement execution
| time to be converted into the variable number of bound parameter
| form illustrated earlier. If the statement were executed as::
|
| connection.execute(stmt, {"value": [1, 2, 3]})
|
| The database would be passed a bound parameter for each value:
|
| .. sourcecode:: sql
|
| WHERE COL IN (?, ?, ?)
|
| .. versionadded:: 1.2 added "expanding" bound parameters
|
| If an empty list is passed, a special "empty list" expression,
| which is specific to the database in use, is rendered. On
| SQLite this would be:
|
| .. sourcecode:: sql
|
| WHERE COL IN (SELECT 1 FROM (SELECT 1) WHERE 1!=1)
|
| .. versionadded:: 1.3 "expanding" bound parameters now support
| empty lists
|
| * a :func:`_expression.select` construct, which is usually a
| correlated scalar select::
|
| stmt.where(
| column.in_(select(othertable.c.y).where(table.c.x == othertable.c.x))
| )
|
| In this calling form, :meth:`.ColumnOperators.in_` renders as given:
|
| .. sourcecode:: sql
|
| WHERE COL IN (SELECT othertable.y
| FROM othertable WHERE othertable.x = table.x)
|
| :param other: a list of literals, a :func:`_expression.select`
| construct, or a :func:`.bindparam` construct that includes the
| :paramref:`.bindparam.expanding` flag set to True.
|
| is_(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``IS`` operator.
|
| Normally, ``IS`` is generated automatically when comparing to a
| value of ``None``, which resolves to ``NULL``. However, explicit
| usage of ``IS`` may be desirable if comparing to boolean values
| on certain platforms.
|
| .. seealso:: :meth:`.ColumnOperators.is_not`
|
| is_distinct_from(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``IS DISTINCT FROM`` operator.
|
| Renders "a IS DISTINCT FROM b" on most platforms;
| on some such as SQLite may render "a IS NOT b".
|
| is_not(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``IS NOT`` operator.
|
| Normally, ``IS NOT`` is generated automatically when comparing to a
| value of ``None``, which resolves to ``NULL``. However, explicit
| usage of ``IS NOT`` may be desirable if comparing to boolean values
| on certain platforms.
|
| .. versionchanged:: 1.4 The ``is_not()`` operator is renamed from
| ``isnot()`` in previous releases. The previous name remains
| available for backwards compatibility.
|
| .. seealso:: :meth:`.ColumnOperators.is_`
|
| is_not_distinct_from(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``IS NOT DISTINCT FROM`` operator.
|
| Renders "a IS NOT DISTINCT FROM b" on most platforms;
| on some such as SQLite may render "a IS b".
|
| .. versionchanged:: 1.4 The ``is_not_distinct_from()`` operator is
| renamed from ``isnot_distinct_from()`` in previous releases.
| The previous name remains available for backwards compatibility.
|
| isnot = is_not(self, other: 'Any') -> 'ColumnOperators'
|
| isnot_distinct_from = is_not_distinct_from(self, other: 'Any') -> 'ColumnOperators'
|
| istartswith(self, other: 'Any', escape: 'Optional[str]' = None, autoescape: 'bool' = False) -> 'ColumnOperators'
| Implement the ``istartswith`` operator, e.g. case insensitive
| version of :meth:`.ColumnOperators.startswith`.
|
| Produces a LIKE expression that tests against an insensitive
| match for the start of a string value:
|
| .. sourcecode:: sql
|
| lower(column) LIKE lower(<other>) || '%'
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.istartswith("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.istartswith.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.istartswith.escape` parameter will
| establish a given character as an escape character which can be of
| use when the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.istartswith.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.istartswith("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE lower(:param) || '%' ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.istartswith("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE lower(:param) || '%' ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.istartswith.autoescape`::
|
| somecolumn.istartswith("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.startswith`
|
| like(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
| Implement the ``like`` operator.
|
| In a column context, produces the expression:
|
| .. sourcecode:: sql
|
| a LIKE other
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.like("%foobar%"))
|
| :param other: expression to be compared
| :param escape: optional escape character, renders the ``ESCAPE``
| keyword, e.g.::
|
| somecolumn.like("foo/%bar", escape="/")
|
| .. seealso::
|
| :meth:`.ColumnOperators.ilike`
|
| match(self, other: 'Any', **kwargs: 'Any') -> 'ColumnOperators'
| Implements a database-specific 'match' operator.
|
| :meth:`_sql.ColumnOperators.match` attempts to resolve to
| a MATCH-like function or operator provided by the backend.
| Examples include:
|
| * PostgreSQL - renders ``x @@ plainto_tsquery(y)``
|
| .. versionchanged:: 2.0 ``plainto_tsquery()`` is used instead
| of ``to_tsquery()`` for PostgreSQL now; for compatibility with
| other forms, see :ref:`postgresql_match`.
|
|
| * MySQL - renders ``MATCH (x) AGAINST (y IN BOOLEAN MODE)``
|
| .. seealso::
|
| :class:`_mysql.match` - MySQL specific construct with
| additional features.
|
| * Oracle Database - renders ``CONTAINS(x, y)``
| * other backends may provide special implementations.
| * Backends without any special implementation will emit
| the operator as "MATCH". This is compatible with SQLite, for
| example.
|
| not_ilike(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
| implement the ``NOT ILIKE`` operator.
|
| This is equivalent to using negation with
| :meth:`.ColumnOperators.ilike`, i.e. ``~x.ilike(y)``.
|
| .. versionchanged:: 1.4 The ``not_ilike()`` operator is renamed from
| ``notilike()`` in previous releases. The previous name remains
| available for backwards compatibility.
|
| .. seealso::
|
| :meth:`.ColumnOperators.ilike`
|
| not_in(self, other: 'Any') -> 'ColumnOperators'
| implement the ``NOT IN`` operator.
|
| This is equivalent to using negation with
| :meth:`.ColumnOperators.in_`, i.e. ``~x.in_(y)``.
|
| In the case that ``other`` is an empty sequence, the compiler
| produces an "empty not in" expression. This defaults to the
| expression "1 = 1" to produce true in all cases. The
| :paramref:`_sa.create_engine.empty_in_strategy` may be used to
| alter this behavior.
|
| .. versionchanged:: 1.4 The ``not_in()`` operator is renamed from
| ``notin_()`` in previous releases. The previous name remains
| available for backwards compatibility.
|
| .. versionchanged:: 1.2 The :meth:`.ColumnOperators.in_` and
| :meth:`.ColumnOperators.not_in` operators
| now produce a "static" expression for an empty IN sequence
| by default.
|
| .. seealso::
|
| :meth:`.ColumnOperators.in_`
|
| not_like(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
| implement the ``NOT LIKE`` operator.
|
| This is equivalent to using negation with
| :meth:`.ColumnOperators.like`, i.e. ``~x.like(y)``.
|
| .. versionchanged:: 1.4 The ``not_like()`` operator is renamed from
| ``notlike()`` in previous releases. The previous name remains
| available for backwards compatibility.
|
| .. seealso::
|
| :meth:`.ColumnOperators.like`
|
| notilike = not_ilike(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
|
| notin_ = not_in(self, other: 'Any') -> 'ColumnOperators'
|
| notlike = not_like(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
|
| nulls_first(self) -> 'ColumnOperators'
| Produce a :func:`_expression.nulls_first` clause against the
| parent object.
|
| .. versionchanged:: 1.4 The ``nulls_first()`` operator is
| renamed from ``nullsfirst()`` in previous releases.
| The previous name remains available for backwards compatibility.
|
| nulls_last(self) -> 'ColumnOperators'
| Produce a :func:`_expression.nulls_last` clause against the
| parent object.
|
| .. versionchanged:: 1.4 The ``nulls_last()`` operator is
| renamed from ``nullslast()`` in previous releases.
| The previous name remains available for backwards compatibility.
|
| nullsfirst = nulls_first(self) -> 'ColumnOperators'
|
| nullslast = nulls_last(self) -> 'ColumnOperators'
|
| regexp_match(self, pattern: 'Any', flags: 'Optional[str]' = None) -> 'ColumnOperators'
| Implements a database-specific 'regexp match' operator.
|
| E.g.::
|
| stmt = select(table.c.some_column).where(
| table.c.some_column.regexp_match("^(b|c)")
| )
|
| :meth:`_sql.ColumnOperators.regexp_match` attempts to resolve to
| a REGEXP-like function or operator provided by the backend, however
| the specific regular expression syntax and flags available are
| **not backend agnostic**.
|
| Examples include:
|
| * PostgreSQL - renders ``x ~ y`` or ``x !~ y`` when negated.
| * Oracle Database - renders ``REGEXP_LIKE(x, y)``
| * SQLite - uses SQLite's ``REGEXP`` placeholder operator and calls into
| the Python ``re.match()`` builtin.
| * other backends may provide special implementations.
| * Backends without any special implementation will emit
| the operator as "REGEXP" or "NOT REGEXP". This is compatible with
| SQLite and MySQL, for example.
|
| Regular expression support is currently implemented for Oracle
| Database, PostgreSQL, MySQL and MariaDB. Partial support is available
| for SQLite. Support among third-party dialects may vary.
|
| :param pattern: The regular expression pattern string or column
| clause.
| :param flags: Any regular expression string flags to apply, passed as
| plain Python string only. These flags are backend specific.
| Some backends, like PostgreSQL and MariaDB, may alternatively
| specify the flags as part of the pattern.
| When using the ignore case flag 'i' in PostgreSQL, the ignore case
| regexp match operator ``~*`` or ``!~*`` will be used.
|
| .. versionadded:: 1.4
|
| .. versionchanged:: 1.4.48, 2.0.18 Note that due to an implementation
| error, the "flags" parameter previously accepted SQL expression
| objects such as column expressions in addition to plain Python
| strings. This implementation did not work correctly with caching
| and was removed; strings only should be passed for the "flags"
| parameter, as these flags are rendered as literal inline values
| within SQL expressions.
|
| .. seealso::
|
| :meth:`_sql.ColumnOperators.regexp_replace`
|
| regexp_replace(self, pattern: 'Any', replacement: 'Any', flags: 'Optional[str]' = None) -> 'ColumnOperators'
| Implements a database-specific 'regexp replace' operator.
|
| E.g.::
|
| stmt = select(
| table.c.some_column.regexp_replace("b(..)", "XY", flags="g")
| )
|
| :meth:`_sql.ColumnOperators.regexp_replace` attempts to resolve to
| a REGEXP_REPLACE-like function provided by the backend, that
| usually emit the function ``REGEXP_REPLACE()``. However,
| the specific regular expression syntax and flags available are
| **not backend agnostic**.
|
| Regular expression replacement support is currently implemented for
| Oracle Database, PostgreSQL, MySQL 8 or greater and MariaDB. Support
| among third-party dialects may vary.
|
| :param pattern: The regular expression pattern string or column
| clause.
| :param pattern: The replacement string or column clause.
| :param flags: Any regular expression string flags to apply, passed as
| plain Python string only. These flags are backend specific.
| Some backends, like PostgreSQL and MariaDB, may alternatively
| specify the flags as part of the pattern.
|
| .. versionadded:: 1.4
|
| .. versionchanged:: 1.4.48, 2.0.18 Note that due to an implementation
| error, the "flags" parameter previously accepted SQL expression
| objects such as column expressions in addition to plain Python
| strings. This implementation did not work correctly with caching
| and was removed; strings only should be passed for the "flags"
| parameter, as these flags are rendered as literal inline values
| within SQL expressions.
|
|
| .. seealso::
|
| :meth:`_sql.ColumnOperators.regexp_match`
|
| startswith(self, other: 'Any', escape: 'Optional[str]' = None, autoescape: 'bool' = False) -> 'ColumnOperators'
| Implement the ``startswith`` operator.
|
| Produces a LIKE expression that tests against a match for the start
| of a string value:
|
| .. sourcecode:: sql
|
| column LIKE <other> || '%'
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.startswith("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.startswith.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.startswith.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.startswith.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.startswith("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE :param || '%' ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.startswith("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE :param || '%' ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.startswith.autoescape`::
|
| somecolumn.startswith("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.endswith`
|
| :meth:`.ColumnOperators.contains`
|
| :meth:`.ColumnOperators.like`
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.operators.ColumnOperators:
|
| timetuple = None
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.operators.Operators:
|
| __and__(self, other: 'Any') -> 'Operators'
| Implement the ``&`` operator.
|
| When used with SQL expressions, results in an
| AND operation, equivalent to
| :func:`_expression.and_`, that is::
|
| a & b
|
| is equivalent to::
|
| from sqlalchemy import and_
|
| and_(a, b)
|
| Care should be taken when using ``&`` regarding
| operator precedence; the ``&`` operator has the highest precedence.
| The operands should be enclosed in parenthesis if they contain
| further sub expressions::
|
| (a == 2) & (b == 4)
|
| __invert__(self) -> 'Operators'
| Implement the ``~`` operator.
|
| When used with SQL expressions, results in a
| NOT operation, equivalent to
| :func:`_expression.not_`, that is::
|
| ~a
|
| is equivalent to::
|
| from sqlalchemy import not_
|
| not_(a)
|
| __or__(self, other: 'Any') -> 'Operators'
| Implement the ``|`` operator.
|
| When used with SQL expressions, results in an
| OR operation, equivalent to
| :func:`_expression.or_`, that is::
|
| a | b
|
| is equivalent to::
|
| from sqlalchemy import or_
|
| or_(a, b)
|
| Care should be taken when using ``|`` regarding
| operator precedence; the ``|`` operator has the highest precedence.
| The operands should be enclosed in parenthesis if they contain
| further sub expressions::
|
| (a == 2) | (b == 4)
|
| __sa_operate__ = operate(self, op: 'OperatorType', *other: 'Any', **kwargs: 'Any') -> 'Operators'
| Operate on an argument.
|
| This is the lowest level of operation, raises
| :class:`NotImplementedError` by default.
|
| Overriding this on a subclass can allow common
| behavior to be applied to all operations.
| For example, overriding :class:`.ColumnOperators`
| to apply ``func.lower()`` to the left and right
| side::
|
| class MyComparator(ColumnOperators):
| def operate(self, op, other, **kwargs):
| return op(func.lower(self), func.lower(other), **kwargs)
|
| :param op: Operator callable.
| :param \*other: the 'other' side of the operation. Will
| be a single scalar for most operations.
| :param \**kwargs: modifiers. These may be passed by special
| operators such as :meth:`ColumnOperators.contains`.
|
| bool_op(self, opstring: 'str', precedence: 'int' = 0, python_impl: 'Optional[Callable[..., Any]]' = None) -> 'Callable[[Any], Operators]'
| Return a custom boolean operator.
|
| This method is shorthand for calling
| :meth:`.Operators.op` and passing the
| :paramref:`.Operators.op.is_comparison`
| flag with True. A key advantage to using :meth:`.Operators.bool_op`
| is that when using column constructs, the "boolean" nature of the
| returned expression will be present for :pep:`484` purposes.
|
| .. seealso::
|
| :meth:`.Operators.op`
|
| op(self, opstring: 'str', precedence: 'int' = 0, is_comparison: 'bool' = False, return_type: 'Optional[Union[Type[TypeEngine[Any]], TypeEngine[Any]]]' = None, python_impl: 'Optional[Callable[..., Any]]' = None) -> 'Callable[[Any], Operators]'
| Produce a generic operator function.
|
| e.g.::
|
| somecolumn.op("*")(5)
|
| produces::
|
| somecolumn * 5
|
| This function can also be used to make bitwise operators explicit. For
| example::
|
| somecolumn.op("&")(0xFF)
|
| is a bitwise AND of the value in ``somecolumn``.
|
| :param opstring: a string which will be output as the infix operator
| between this element and the expression passed to the
| generated function.
|
| :param precedence: precedence which the database is expected to apply
| to the operator in SQL expressions. This integer value acts as a hint
| for the SQL compiler to know when explicit parenthesis should be
| rendered around a particular operation. A lower number will cause the
| expression to be parenthesized when applied against another operator
| with higher precedence. The default value of ``0`` is lower than all
| operators except for the comma (``,``) and ``AS`` operators. A value
| of 100 will be higher or equal to all operators, and -100 will be
| lower than or equal to all operators.
|
| .. seealso::
|
| :ref:`faq_sql_expression_op_parenthesis` - detailed description
| of how the SQLAlchemy SQL compiler renders parenthesis
|
| :param is_comparison: legacy; if True, the operator will be considered
| as a "comparison" operator, that is which evaluates to a boolean
| true/false value, like ``==``, ``>``, etc. This flag is provided
| so that ORM relationships can establish that the operator is a
| comparison operator when used in a custom join condition.
|
| Using the ``is_comparison`` parameter is superseded by using the
| :meth:`.Operators.bool_op` method instead; this more succinct
| operator sets this parameter automatically, but also provides
| correct :pep:`484` typing support as the returned object will
| express a "boolean" datatype, i.e. ``BinaryExpression[bool]``.
|
| :param return_type: a :class:`.TypeEngine` class or object that will
| force the return type of an expression produced by this operator
| to be of that type. By default, operators that specify
| :paramref:`.Operators.op.is_comparison` will resolve to
| :class:`.Boolean`, and those that do not will be of the same
| type as the left-hand operand.
|
| :param python_impl: an optional Python function that can evaluate
| two Python values in the same way as this operator works when
| run on the database server. Useful for in-Python SQL expression
| evaluation functions, such as for ORM hybrid attributes, and the
| ORM "evaluator" used to match objects in a session after a multi-row
| update or delete.
|
| e.g.::
|
| >>> expr = column("x").op("+", python_impl=lambda a, b: a + b)("y")
|
| The operator for the above expression will also work for non-SQL
| left and right objects::
|
| >>> expr.operator(5, 10)
| 15
|
| .. versionadded:: 2.0
|
|
| .. seealso::
|
| :meth:`.Operators.bool_op`
|
| :ref:`types_operators`
|
| :ref:`relationship_custom_operator`
|
| ----------------------------------------------------------------------
| Methods inherited from ClauseElement:
|
| __bool__(self)
|
| __getstate__(self)
| Helper for pickle.
|
| __repr__(self)
| Return repr(self).
|
| compare(self, other: 'ClauseElement', **kw: 'Any') -> 'bool'
| Compare this :class:`_expression.ClauseElement` to
| the given :class:`_expression.ClauseElement`.
|
| Subclasses should override the default behavior, which is a
| straight identity comparison.
|
| \**kw are arguments consumed by subclass ``compare()`` methods and
| may be used to modify the criteria for comparison
| (see :class:`_expression.ColumnElement`).
|
| description(...)
|
| entity_namespace(...)
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from ClauseElement:
|
| is_clause_element = True
|
| is_dml = False
|
| is_selectable = False
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.cache_key.HasCacheKey:
|
| inherit_cache = None
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_instancemethod(fn: '_F') -> '_F'
| Decorate a method memoize its return value.
|
| :meta private:
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_attribute = <class 'sqlalchemy.util.langhelpers.HasMemoized.m...
| A read-only @property that is only evaluated once.
|
| :meta private:
|
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.visitors.HasTraverseInternals:
|
| get_children(self, *, omit_attrs: 'Tuple[str, ...]' = (), **kw: 'Any') -> 'Iterable[HasTraverseInternals]'
| Return immediate child :class:`.visitors.HasTraverseInternals`
| elements of this :class:`.visitors.HasTraverseInternals`.
|
| This is used for visit traversal.
|
| \**kw may contain flags that change the collection that is
| returned, for example to return a subset of items in order to
| cut down on larger traversals, or to return child items from a
| different context (such as schema-level collections instead of
| clause-level).
|
| ----------------------------------------------------------------------
| Methods inherited from CompilerElement:
|
| __str__(self) -> 'str'
| Return str(self).
|
| compile(self, bind: 'Optional[_HasDialect]' = None, dialect: 'Optional[Dialect]' = None, **kw: 'Any') -> 'Compiled'
| Compile this SQL expression.
|
| The return value is a :class:`~.Compiled` object.
| Calling ``str()`` or ``unicode()`` on the returned value will yield a
| string representation of the result. The
| :class:`~.Compiled` object also can return a
| dictionary of bind parameter names and values
| using the ``params`` accessor.
|
| :param bind: An :class:`.Connection` or :class:`.Engine` which
| can provide a :class:`.Dialect` in order to generate a
| :class:`.Compiled` object. If the ``bind`` and
| ``dialect`` parameters are both omitted, a default SQL compiler
| is used.
|
| :param column_keys: Used for INSERT and UPDATE statements, a list of
| column names which should be present in the VALUES clause of the
| compiled statement. If ``None``, all columns from the target table
| object are rendered.
|
| :param dialect: A :class:`.Dialect` instance which can generate
| a :class:`.Compiled` object. This argument takes precedence over
| the ``bind`` argument.
|
| :param compile_kwargs: optional dictionary of additional parameters
| that will be passed through to the compiler within all "visit"
| methods. This allows any custom flag to be passed through to
| a custom compilation construct, for example. It is also used
| for the case of passing the ``literal_binds`` flag through::
|
| from sqlalchemy.sql import table, column, select
|
| t = table("t", column("x"))
|
| s = select(t).where(t.c.x == 5)
|
| print(s.compile(compile_kwargs={"literal_binds": True}))
|
| .. seealso::
|
| :ref:`faq_sql_expression_string`
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from CompilerElement:
|
| stringify_dialect = 'default'
|
| supports_execution = False
sqlalchemy.NullPool
Python Library Documentation: class NullPool in module sqlalchemy.pool.impl
class NullPool(sqlalchemy.pool.base.Pool)
| NullPool(creator: 'Union[_CreatorFnType, _CreatorWRecFnType]', recycle: 'int' = -1, echo: 'log._EchoFlagType' = None, logging_name: 'Optional[str]' = None, reset_on_return: '_ResetStyleArgType' = True, events: 'Optional[List[Tuple[_ListenerFnType, str]]]' = None, dialect: 'Optional[Union[_ConnDialect, Dialect]]' = None, pre_ping: 'bool' = False, _dispatch: 'Optional[_DispatchCommon[Pool]]' = None)
|
| A Pool which does not pool connections.
|
| Instead it literally opens and closes the underlying DB-API connection
| per each connection open/close.
|
| Reconnect-related functions such as ``recycle`` and connection
| invalidation are not supported by this Pool implementation, since
| no connections are held persistently.
|
| The :class:`.NullPool` class **is compatible** with asyncio and
| :func:`_asyncio.create_async_engine`.
|
| Method resolution order:
| NullPool
| sqlalchemy.pool.base.Pool
| sqlalchemy.log.Identified
| sqlalchemy.event.registry.EventTarget
| builtins.object
|
| Methods defined here:
|
| dispose(self) -> 'None'
| Dispose of this pool.
|
| This method leaves the possibility of checked-out connections
| remaining open, as it only affects connections that are
| idle in the pool.
|
| .. seealso::
|
| :meth:`Pool.recreate`
|
| recreate(self) -> 'NullPool'
| Return a new :class:`_pool.Pool`, of the same class as this one
| and configured with identical creation arguments.
|
| This method is used in conjunction with :meth:`dispose`
| to close out an entire :class:`_pool.Pool` and create a new one in
| its place.
|
| status(self) -> 'str'
| Returns a brief description of the state of this pool.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.pool.base.Pool:
|
| __init__(self, creator: 'Union[_CreatorFnType, _CreatorWRecFnType]', recycle: 'int' = -1, echo: 'log._EchoFlagType' = None, logging_name: 'Optional[str]' = None, reset_on_return: '_ResetStyleArgType' = True, events: 'Optional[List[Tuple[_ListenerFnType, str]]]' = None, dialect: 'Optional[Union[_ConnDialect, Dialect]]' = None, pre_ping: 'bool' = False, _dispatch: 'Optional[_DispatchCommon[Pool]]' = None)
| Construct a Pool.
|
| :param creator: a callable function that returns a DB-API
| connection object. The function will be called with
| parameters.
|
| :param recycle: If set to a value other than -1, number of
| seconds between connection recycling, which means upon
| checkout, if this timeout is surpassed the connection will be
| closed and replaced with a newly opened connection. Defaults to -1.
|
| :param logging_name: String identifier which will be used within
| the "name" field of logging records generated within the
| "sqlalchemy.pool" logger. Defaults to a hexstring of the object's
| id.
|
| :param echo: if True, the connection pool will log
| informational output such as when connections are invalidated
| as well as when connections are recycled to the default log handler,
| which defaults to ``sys.stdout`` for output.. If set to the string
| ``"debug"``, the logging will include pool checkouts and checkins.
|
| The :paramref:`_pool.Pool.echo` parameter can also be set from the
| :func:`_sa.create_engine` call by using the
| :paramref:`_sa.create_engine.echo_pool` parameter.
|
| .. seealso::
|
| :ref:`dbengine_logging` - further detail on how to configure
| logging.
|
| :param reset_on_return: Determine steps to take on
| connections as they are returned to the pool, which were
| not otherwise handled by a :class:`_engine.Connection`.
| Available from :func:`_sa.create_engine` via the
| :paramref:`_sa.create_engine.pool_reset_on_return` parameter.
|
| :paramref:`_pool.Pool.reset_on_return` can have any of these values:
|
| * ``"rollback"`` - call rollback() on the connection,
| to release locks and transaction resources.
| This is the default value. The vast majority
| of use cases should leave this value set.
| * ``"commit"`` - call commit() on the connection,
| to release locks and transaction resources.
| A commit here may be desirable for databases that
| cache query plans if a commit is emitted,
| such as Microsoft SQL Server. However, this
| value is more dangerous than 'rollback' because
| any data changes present on the transaction
| are committed unconditionally.
| * ``None`` - don't do anything on the connection.
| This setting may be appropriate if the database / DBAPI
| works in pure "autocommit" mode at all times, or if
| a custom reset handler is established using the
| :meth:`.PoolEvents.reset` event handler.
|
| * ``True`` - same as 'rollback', this is here for
| backwards compatibility.
| * ``False`` - same as None, this is here for
| backwards compatibility.
|
| For further customization of reset on return, the
| :meth:`.PoolEvents.reset` event hook may be used which can perform
| any connection activity desired on reset.
|
| .. seealso::
|
| :ref:`pool_reset_on_return`
|
| :meth:`.PoolEvents.reset`
|
| :param events: a list of 2-tuples, each of the form
| ``(callable, target)`` which will be passed to :func:`.event.listen`
| upon construction. Provided here so that event listeners
| can be assigned via :func:`_sa.create_engine` before dialect-level
| listeners are applied.
|
| :param dialect: a :class:`.Dialect` that will handle the job
| of calling rollback(), close(), or commit() on DBAPI connections.
| If omitted, a built-in "stub" dialect is used. Applications that
| make use of :func:`_sa.create_engine` should not use this parameter
| as it is handled by the engine creation strategy.
|
| :param pre_ping: if True, the pool will emit a "ping" (typically
| "SELECT 1", but is dialect-specific) on the connection
| upon checkout, to test if the connection is alive or not. If not,
| the connection is transparently re-connected and upon success, all
| other pooled connections established prior to that timestamp are
| invalidated. Requires that a dialect is passed as well to
| interpret the disconnection error.
|
| .. versionadded:: 1.2
|
| connect(self) -> 'PoolProxiedConnection'
| Return a DBAPI connection from the pool.
|
| The connection is instrumented such that when its
| ``close()`` method is called, the connection will be returned to
| the pool.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from sqlalchemy.pool.base.Pool:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.pool.base.Pool:
|
| dispatch = <sqlalchemy.event.base.PoolEventsDispatch object>
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.log.Identified:
|
| logging_name = None
sqlalchemy.Nullable
Python Library Documentation: function Nullable in module sqlalchemy.sql._typing
Nullable(val: '_TypedColumnClauseArgument[_T]') -> '_TypedColumnClauseArgument[Optional[_T]]'
Types a column or ORM class as nullable.
This can be used in select and other contexts to express that the value of
a column can be null, for example due to an outer join::
stmt1 = select(A, Nullable(B)).outerjoin(A.bs)
stmt2 = select(A.data, Nullable(B.data)).outerjoin(A.bs)
At runtime this method returns the input unchanged.
.. versionadded:: 2.0.20
sqlalchemy.Numeric
Python Library Documentation: class Numeric in module sqlalchemy.sql.sqltypes
class Numeric(HasExpressionLookup, sqlalchemy.sql.type_api.TypeEngine)
| Numeric(precision: 'Optional[int]' = None, scale: 'Optional[int]' = None, decimal_return_scale: 'Optional[int]' = None, asdecimal: 'bool' = True)
|
| Base for non-integer numeric types, such as
| ``NUMERIC``, ``FLOAT``, ``DECIMAL``, and other variants.
|
| The :class:`.Numeric` datatype when used directly will render DDL
| corresponding to precision numerics if available, such as
| ``NUMERIC(precision, scale)``. The :class:`.Float` subclass will
| attempt to render a floating-point datatype such as ``FLOAT(precision)``.
|
| :class:`.Numeric` returns Python ``decimal.Decimal`` objects by default,
| based on the default value of ``True`` for the
| :paramref:`.Numeric.asdecimal` parameter. If this parameter is set to
| False, returned values are coerced to Python ``float`` objects.
|
| The :class:`.Float` subtype, being more specific to floating point,
| defaults the :paramref:`.Float.asdecimal` flag to False so that the
| default Python datatype is ``float``.
|
| .. note::
|
| When using a :class:`.Numeric` datatype against a database type that
| returns Python floating point values to the driver, the accuracy of the
| decimal conversion indicated by :paramref:`.Numeric.asdecimal` may be
| limited. The behavior of specific numeric/floating point datatypes
| is a product of the SQL datatype in use, the Python :term:`DBAPI`
| in use, as well as strategies that may be present within
| the SQLAlchemy dialect in use. Users requiring specific precision/
| scale are encouraged to experiment with the available datatypes
| in order to determine the best results.
|
| Method resolution order:
| Numeric
| HasExpressionLookup
| sqlalchemy.sql.type_api.TypeEngineMixin
| sqlalchemy.sql.type_api.TypeEngine
| sqlalchemy.sql.visitors.Visitable
| typing.Generic
| builtins.object
|
| Methods defined here:
|
| __init__(self, precision: 'Optional[int]' = None, scale: 'Optional[int]' = None, decimal_return_scale: 'Optional[int]' = None, asdecimal: 'bool' = True)
| Construct a Numeric.
|
| :param precision: the numeric precision for use in DDL ``CREATE
| TABLE``.
|
| :param scale: the numeric scale for use in DDL ``CREATE TABLE``.
|
| :param asdecimal: default True. Return whether or not
| values should be sent as Python Decimal objects, or
| as floats. Different DBAPIs send one or the other based on
| datatypes - the Numeric type will ensure that return values
| are one or the other across DBAPIs consistently.
|
| :param decimal_return_scale: Default scale to use when converting
| from floats to Python decimals. Floating point values will typically
| be much longer due to decimal inaccuracy, and most floating point
| database types don't have a notion of "scale", so by default the
| float type looks for the first ten decimal places when converting.
| Specifying this value will override that length. Types which
| do include an explicit ".scale" value, such as the base
| :class:`.Numeric` as well as the MySQL float types, will use the
| value of ".scale" as the default for decimal_return_scale, if not
| otherwise specified.
|
| When using the ``Numeric`` type, care should be taken to ensure
| that the asdecimal setting is appropriate for the DBAPI in use -
| when Numeric applies a conversion from Decimal->float or float->
| Decimal, this conversion incurs an additional performance overhead
| for all result columns received.
|
| DBAPIs that return Decimal natively (e.g. psycopg2) will have
| better accuracy and higher performance with a setting of ``True``,
| as the native translation to Decimal reduces the amount of floating-
| point issues at play, and the Numeric type itself doesn't need
| to apply any further conversions. However, another DBAPI which
| returns floats natively *will* incur an additional conversion
| overhead, and is still subject to floating point data loss - in
| which case ``asdecimal=False`` will at least remove the extra
| conversion overhead.
|
| bind_processor(self, dialect)
| Return a conversion function for processing bind values.
|
| Returns a callable which will receive a bind parameter value
| as the sole positional argument and will return a value to
| send to the DB-API.
|
| If processing is not necessary, the method should return ``None``.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.bind_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.bind_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_bind_param`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
|
| :param dialect: Dialect instance in use.
|
| get_dbapi_type(self, dbapi)
| Return the corresponding type object from the underlying DB-API, if
| any.
|
| This can be useful for calling ``setinputsizes()``, for example.
|
| literal_processor(self, dialect)
| Return a conversion function for processing literal values that are
| to be rendered directly without using binds.
|
| This function is used when the compiler makes use of the
| "literal_binds" flag, typically used in DDL generation as well
| as in certain scenarios where backends don't accept bound parameters.
|
| Returns a callable which will receive a literal Python value
| as the sole positional argument and will return a string representation
| to be rendered in a SQL statement.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.literal_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.literal_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_literal_param`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| result_processor(self, dialect, coltype)
| Return a conversion function for processing result row values.
|
| Returns a callable which will receive a result row column
| value as the sole positional argument and will return a value
| to return to the user.
|
| If processing is not necessary, the method should return ``None``.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.result_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.result_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_result_value`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| :param dialect: Dialect instance in use.
|
| :param coltype: DBAPI coltype argument received in cursor.description.
|
| ----------------------------------------------------------------------
| Readonly properties defined here:
|
| python_type
| Return the Python type object expected to be returned
| by instances of this type, if known.
|
| Basically, for those types which enforce a return type,
| or are known across the board to do such for all common
| DBAPIs (like ``int`` for example), will return that type.
|
| If a return type is not defined, raises
| ``NotImplementedError``.
|
| Note that any type also accommodates NULL in SQL which
| means you can also get back ``None`` from any type
| in practice.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| __parameters__ = ()
|
| __visit_name__ = 'numeric'
|
| ----------------------------------------------------------------------
| Data descriptors inherited from HasExpressionLookup:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from HasExpressionLookup:
|
| Comparator = <class 'sqlalchemy.sql.sqltypes.HasExpressionLookup.Compa...
|
| comparator_factory = <class 'sqlalchemy.sql.sqltypes.HasExpressionLook...
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.type_api.TypeEngine:
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| __str__(self) -> 'str'
| Return str(self).
|
| adapt(self, cls: 'Type[Union[TypeEngine[Any], TypeEngineMixin]]', **kw: 'Any') -> 'TypeEngine[Any]'
| Produce an "adapted" form of this type, given an "impl" class
| to work with.
|
| This method is used internally to associate generic
| types with "implementation" types that are specific to a particular
| dialect.
|
| as_generic(self, allow_nulltype: 'bool' = False) -> 'TypeEngine[_T]'
| Return an instance of the generic type corresponding to this type
| using heuristic rule. The method may be overridden if this
| heuristic rule is not sufficient.
|
| >>> from sqlalchemy.dialects.mysql import INTEGER
| >>> INTEGER(display_width=4).as_generic()
| Integer()
|
| >>> from sqlalchemy.dialects.mysql import NVARCHAR
| >>> NVARCHAR(length=100).as_generic()
| Unicode(length=100)
|
| .. versionadded:: 1.4.0b2
|
|
| .. seealso::
|
| :ref:`metadata_reflection_dbagnostic_types` - describes the
| use of :meth:`_types.TypeEngine.as_generic` in conjunction with
| the :meth:`_sql.DDLEvents.column_reflect` event, which is its
| intended use.
|
| bind_expression(self, bindvalue: 'BindParameter[_T]') -> 'Optional[ColumnElement[_T]]'
| Given a bind value (i.e. a :class:`.BindParameter` instance),
| return a SQL expression in its place.
|
| This is typically a SQL function that wraps the existing bound
| parameter within the statement. It is used for special data types
| that require literals being wrapped in some special database function
| in order to coerce an application-level value into a database-specific
| format. It is the SQL analogue of the
| :meth:`.TypeEngine.bind_processor` method.
|
| This method is called during the **SQL compilation** phase of a
| statement, when rendering a SQL string. It is **not** called
| against specific values.
|
| Note that this method, when implemented, should always return
| the exact same structure, without any conditional logic, as it
| may be used in an executemany() call against an arbitrary number
| of bound parameter sets.
|
| .. note::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.bind_expression`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.bind_expression`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.bind_expression`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| .. seealso::
|
| :ref:`types_sql_value_processing`
|
| coerce_compared_value(self, op: 'Optional[OperatorType]', value: 'Any') -> 'TypeEngine[Any]'
| Suggest a type for a 'coerced' Python value in an expression.
|
| Given an operator and value, gives the type a chance
| to return a type which the value should be coerced into.
|
| The default behavior here is conservative; if the right-hand
| side is already coerced into a SQL type based on its
| Python type, it is usually left alone.
|
| End-user functionality extension here should generally be via
| :class:`.TypeDecorator`, which provides more liberal behavior in that
| it defaults to coercing the other side of the expression into this
| type, thus applying special Python conversions above and beyond those
| needed by the DBAPI to both ides. It also provides the public method
| :meth:`.TypeDecorator.coerce_compared_value` which is intended for
| end-user customization of this behavior.
|
| column_expression(self, colexpr: 'ColumnElement[_T]') -> 'Optional[ColumnElement[_T]]'
| Given a SELECT column expression, return a wrapping SQL expression.
|
| This is typically a SQL function that wraps a column expression
| as rendered in the columns clause of a SELECT statement.
| It is used for special data types that require
| columns to be wrapped in some special database function in order
| to coerce the value before being sent back to the application.
| It is the SQL analogue of the :meth:`.TypeEngine.result_processor`
| method.
|
| .. note:: The :func:`.TypeEngine.column_expression` method is applied
| only to the **outermost columns clause** of a SELECT statement, that
| is, the columns that are to be delivered directly into the returned
| result rows. It does **not** apply to the columns clause inside
| of subqueries. This necessarily avoids double conversions against
| the column and only runs the conversion when ready to be returned
| to the client.
|
| This method is called during the **SQL compilation** phase of a
| statement, when rendering a SQL string. It is **not** called
| against specific values.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.column_expression`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.column_expression`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.column_expression`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
|
| .. seealso::
|
| :ref:`types_sql_value_processing`
|
| compare_values(self, x: 'Any', y: 'Any') -> 'bool'
| Compare two values for equality.
|
| compile(self, dialect: 'Optional[Dialect]' = None) -> 'str'
| Produce a string-compiled form of this :class:`.TypeEngine`.
|
| When called with no arguments, uses a "default" dialect
| to produce a string result.
|
| :param dialect: a :class:`.Dialect` instance.
|
| copy(self, **kw: 'Any') -> 'Self'
|
| copy_value(self, value: 'Any') -> 'Any'
|
| dialect_impl(self, dialect: 'Dialect') -> 'TypeEngine[_T]'
| Return a dialect-specific implementation for this
| :class:`.TypeEngine`.
|
| evaluates_none(self) -> 'Self'
| Return a copy of this type which has the
| :attr:`.should_evaluate_none` flag set to True.
|
| E.g.::
|
| Table(
| "some_table",
| metadata,
| Column(
| String(50).evaluates_none(),
| nullable=True,
| server_default="no value",
| ),
| )
|
| The ORM uses this flag to indicate that a positive value of ``None``
| is passed to the column in an INSERT statement, rather than omitting
| the column from the INSERT statement which has the effect of firing
| off column-level defaults. It also allows for types which have
| special behavior associated with the Python None value to indicate
| that the value doesn't necessarily translate into SQL NULL; a
| prime example of this is a JSON type which may wish to persist the
| JSON value ``'null'``.
|
| In all cases, the actual NULL SQL value can be always be
| persisted in any column by using
| the :obj:`_expression.null` SQL construct in an INSERT statement
| or associated with an ORM-mapped attribute.
|
| .. note::
|
| The "evaluates none" flag does **not** apply to a value
| of ``None`` passed to :paramref:`_schema.Column.default` or
| :paramref:`_schema.Column.server_default`; in these cases,
| ``None``
| still means "no default".
|
| .. seealso::
|
| :ref:`session_forcing_null` - in the ORM documentation
|
| :paramref:`.postgresql.JSON.none_as_null` - PostgreSQL JSON
| interaction with this flag.
|
| :attr:`.TypeEngine.should_evaluate_none` - class-level flag
|
| with_variant(self, type_: '_TypeEngineArgument[Any]', *dialect_names: 'str') -> 'Self'
| Produce a copy of this type object that will utilize the given
| type when applied to the dialect of the given name.
|
| e.g.::
|
| from sqlalchemy.types import String
| from sqlalchemy.dialects import mysql
|
| string_type = String()
|
| string_type = string_type.with_variant(
| mysql.VARCHAR(collation="foo"), "mysql", "mariadb"
| )
|
| The variant mapping indicates that when this type is
| interpreted by a specific dialect, it will instead be
| transmuted into the given type, rather than using the
| primary type.
|
| .. versionchanged:: 2.0 the :meth:`_types.TypeEngine.with_variant`
| method now works with a :class:`_types.TypeEngine` object "in
| place", returning a copy of the original type rather than returning
| a wrapping object; the ``Variant`` class is no longer used.
|
| :param type\_: a :class:`.TypeEngine` that will be selected
| as a variant from the originating type, when a dialect
| of the given name is in use.
| :param \*dialect_names: one or more base names of the dialect which
| uses this type. (i.e. ``'postgresql'``, ``'mysql'``, etc.)
|
| .. versionchanged:: 2.0 multiple dialect names can be specified
| for one variant.
|
| .. seealso::
|
| :ref:`types_with_variant` - illustrates the use of
| :meth:`_types.TypeEngine.with_variant`.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.type_api.TypeEngine:
|
| __orig_bases__ = (<class 'sqlalchemy.sql.visitors.Visitable'>, typing....
|
| hashable = True
|
| render_bind_cast = False
|
| render_literal_cast = False
|
| should_evaluate_none = False
|
| sort_key_function = None
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.visitors.Visitable:
|
| __class_getitem__(key: 'Any') -> 'Any'
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__() -> 'None'
| This method is called when a class is subclassed.
|
| The default implementation does nothing. It may be
| overridden to extend subclasses.
sqlalchemy.Operators
Python Library Documentation: class Operators in module sqlalchemy.sql.operators
class Operators(builtins.object)
| Base of comparison and logical operators.
|
| Implements base methods
| :meth:`~sqlalchemy.sql.operators.Operators.operate` and
| :meth:`~sqlalchemy.sql.operators.Operators.reverse_operate`, as well as
| :meth:`~sqlalchemy.sql.operators.Operators.__and__`,
| :meth:`~sqlalchemy.sql.operators.Operators.__or__`,
| :meth:`~sqlalchemy.sql.operators.Operators.__invert__`.
|
| Usually is used via its most common subclass
| :class:`.ColumnOperators`.
|
| Methods defined here:
|
| __and__(self, other: 'Any') -> 'Operators'
| Implement the ``&`` operator.
|
| When used with SQL expressions, results in an
| AND operation, equivalent to
| :func:`_expression.and_`, that is::
|
| a & b
|
| is equivalent to::
|
| from sqlalchemy import and_
|
| and_(a, b)
|
| Care should be taken when using ``&`` regarding
| operator precedence; the ``&`` operator has the highest precedence.
| The operands should be enclosed in parenthesis if they contain
| further sub expressions::
|
| (a == 2) & (b == 4)
|
| __invert__(self) -> 'Operators'
| Implement the ``~`` operator.
|
| When used with SQL expressions, results in a
| NOT operation, equivalent to
| :func:`_expression.not_`, that is::
|
| ~a
|
| is equivalent to::
|
| from sqlalchemy import not_
|
| not_(a)
|
| __or__(self, other: 'Any') -> 'Operators'
| Implement the ``|`` operator.
|
| When used with SQL expressions, results in an
| OR operation, equivalent to
| :func:`_expression.or_`, that is::
|
| a | b
|
| is equivalent to::
|
| from sqlalchemy import or_
|
| or_(a, b)
|
| Care should be taken when using ``|`` regarding
| operator precedence; the ``|`` operator has the highest precedence.
| The operands should be enclosed in parenthesis if they contain
| further sub expressions::
|
| (a == 2) | (b == 4)
|
| __sa_operate__ = operate(self, op: 'OperatorType', *other: 'Any', **kwargs: 'Any') -> 'Operators'
|
| bool_op(self, opstring: 'str', precedence: 'int' = 0, python_impl: 'Optional[Callable[..., Any]]' = None) -> 'Callable[[Any], Operators]'
| Return a custom boolean operator.
|
| This method is shorthand for calling
| :meth:`.Operators.op` and passing the
| :paramref:`.Operators.op.is_comparison`
| flag with True. A key advantage to using :meth:`.Operators.bool_op`
| is that when using column constructs, the "boolean" nature of the
| returned expression will be present for :pep:`484` purposes.
|
| .. seealso::
|
| :meth:`.Operators.op`
|
| op(self, opstring: 'str', precedence: 'int' = 0, is_comparison: 'bool' = False, return_type: 'Optional[Union[Type[TypeEngine[Any]], TypeEngine[Any]]]' = None, python_impl: 'Optional[Callable[..., Any]]' = None) -> 'Callable[[Any], Operators]'
| Produce a generic operator function.
|
| e.g.::
|
| somecolumn.op("*")(5)
|
| produces::
|
| somecolumn * 5
|
| This function can also be used to make bitwise operators explicit. For
| example::
|
| somecolumn.op("&")(0xFF)
|
| is a bitwise AND of the value in ``somecolumn``.
|
| :param opstring: a string which will be output as the infix operator
| between this element and the expression passed to the
| generated function.
|
| :param precedence: precedence which the database is expected to apply
| to the operator in SQL expressions. This integer value acts as a hint
| for the SQL compiler to know when explicit parenthesis should be
| rendered around a particular operation. A lower number will cause the
| expression to be parenthesized when applied against another operator
| with higher precedence. The default value of ``0`` is lower than all
| operators except for the comma (``,``) and ``AS`` operators. A value
| of 100 will be higher or equal to all operators, and -100 will be
| lower than or equal to all operators.
|
| .. seealso::
|
| :ref:`faq_sql_expression_op_parenthesis` - detailed description
| of how the SQLAlchemy SQL compiler renders parenthesis
|
| :param is_comparison: legacy; if True, the operator will be considered
| as a "comparison" operator, that is which evaluates to a boolean
| true/false value, like ``==``, ``>``, etc. This flag is provided
| so that ORM relationships can establish that the operator is a
| comparison operator when used in a custom join condition.
|
| Using the ``is_comparison`` parameter is superseded by using the
| :meth:`.Operators.bool_op` method instead; this more succinct
| operator sets this parameter automatically, but also provides
| correct :pep:`484` typing support as the returned object will
| express a "boolean" datatype, i.e. ``BinaryExpression[bool]``.
|
| :param return_type: a :class:`.TypeEngine` class or object that will
| force the return type of an expression produced by this operator
| to be of that type. By default, operators that specify
| :paramref:`.Operators.op.is_comparison` will resolve to
| :class:`.Boolean`, and those that do not will be of the same
| type as the left-hand operand.
|
| :param python_impl: an optional Python function that can evaluate
| two Python values in the same way as this operator works when
| run on the database server. Useful for in-Python SQL expression
| evaluation functions, such as for ORM hybrid attributes, and the
| ORM "evaluator" used to match objects in a session after a multi-row
| update or delete.
|
| e.g.::
|
| >>> expr = column("x").op("+", python_impl=lambda a, b: a + b)("y")
|
| The operator for the above expression will also work for non-SQL
| left and right objects::
|
| >>> expr.operator(5, 10)
| 15
|
| .. versionadded:: 2.0
|
|
| .. seealso::
|
| :meth:`.Operators.bool_op`
|
| :ref:`types_operators`
|
| :ref:`relationship_custom_operator`
|
| operate(self, op: 'OperatorType', *other: 'Any', **kwargs: 'Any') -> 'Operators'
| Operate on an argument.
|
| This is the lowest level of operation, raises
| :class:`NotImplementedError` by default.
|
| Overriding this on a subclass can allow common
| behavior to be applied to all operations.
| For example, overriding :class:`.ColumnOperators`
| to apply ``func.lower()`` to the left and right
| side::
|
| class MyComparator(ColumnOperators):
| def operate(self, op, other, **kwargs):
| return op(func.lower(self), func.lower(other), **kwargs)
|
| :param op: Operator callable.
| :param \*other: the 'other' side of the operation. Will
| be a single scalar for most operations.
| :param \**kwargs: modifiers. These may be passed by special
| operators such as :meth:`ColumnOperators.contains`.
|
| reverse_operate(self, op: 'OperatorType', other: 'Any', **kwargs: 'Any') -> 'Operators'
| Reverse operate on an argument.
|
| Usage is the same as :meth:`operate`.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {}
sqlalchemy.Over
Python Library Documentation: class Over in module sqlalchemy.sql.elements
class Over(ColumnElement)
| Over(element: 'ColumnElement[_T]', partition_by: 'Optional[_ByArgument]' = None, order_by: 'Optional[_ByArgument]' = None, range_: 'Optional[typing_Tuple[Optional[int], Optional[int]]]' = None, rows: 'Optional[typing_Tuple[Optional[int], Optional[int]]]' = None, groups: 'Optional[typing_Tuple[Optional[int], Optional[int]]]' = None)
|
| Represent an OVER clause.
|
| This is a special operator against a so-called
| "window" function, as well as any aggregate function,
| which produces results relative to the result set
| itself. Most modern SQL backends now support window functions.
|
| Method resolution order:
| Over
| ColumnElement
| sqlalchemy.sql.roles.ColumnArgumentOrKeyRole
| sqlalchemy.sql.roles.ColumnArgumentRole
| sqlalchemy.sql.roles.StatementOptionRole
| sqlalchemy.sql.roles.WhereHavingRole
| sqlalchemy.sql.roles.OnClauseRole
| sqlalchemy.sql.roles.BinaryElementRole
| sqlalchemy.sql.roles.OrderByRole
| sqlalchemy.sql.roles.ColumnsClauseRole
| sqlalchemy.sql.roles.AllowsLambdaRole
| sqlalchemy.sql.roles.ByOfRole
| sqlalchemy.sql.roles.UsesInspection
| sqlalchemy.sql.roles.ColumnListRole
| sqlalchemy.sql.roles.LimitOffsetRole
| sqlalchemy.sql.roles.DMLColumnRole
| sqlalchemy.sql.roles.DDLConstraintColumnRole
| sqlalchemy.sql.roles.DDLExpressionRole
| sqlalchemy.sql.roles.StructuralRole
| SQLColumnExpression
| SQLCoreOperations
| sqlalchemy.sql.roles.ExpressionElementRole
| sqlalchemy.sql.roles.TypedColumnsClauseRole
| typing.Generic
| sqlalchemy.sql.operators.ColumnOperators
| sqlalchemy.sql.operators.Operators
| sqlalchemy.util.langhelpers.TypingOnly
| sqlalchemy.sql.roles.SQLRole
| DQLDMLClauseElement
| ClauseElement
| sqlalchemy.sql.annotation.SupportsWrappingAnnotations
| sqlalchemy.sql.annotation.SupportsAnnotations
| sqlalchemy.sql.cache_key.MemoizedHasCacheKey
| sqlalchemy.sql.cache_key.HasCacheKey
| sqlalchemy.util.langhelpers.HasMemoized
| sqlalchemy.sql.traversals.HasCopyInternals
| sqlalchemy.sql.visitors.ExternallyTraversible
| sqlalchemy.sql.visitors.HasTraverseInternals
| CompilerElement
| sqlalchemy.sql.visitors.Visitable
| builtins.object
|
| Methods defined here:
|
| __init__(self, element: 'ColumnElement[_T]', partition_by: 'Optional[_ByArgument]' = None, order_by: 'Optional[_ByArgument]' = None, range_: 'Optional[typing_Tuple[Optional[int], Optional[int]]]' = None, rows: 'Optional[typing_Tuple[Optional[int], Optional[int]]]' = None, groups: 'Optional[typing_Tuple[Optional[int], Optional[int]]]' = None)
| Initialize self. See help(type(self)) for accurate signature.
|
| __reduce__(self)
| Helper for pickle.
|
| type(...)
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'_traverse_internals': '_TraverseInternalsType', 'e...
|
| __orig_bases__ = (sqlalchemy.sql.elements.ColumnElement[~_T],)
|
| __parameters__ = (~_T,)
|
| __visit_name__ = 'over'
|
| order_by = None
|
| partition_by = None
|
| ----------------------------------------------------------------------
| Methods inherited from ColumnElement:
|
| __getattr__(self, key: 'str') -> 'Any'
|
| __setstate__(self, state)
|
| base_columns(...)
|
| cast(self, type_: '_TypeEngineArgument[_OPT]') -> 'Cast[_OPT]'
| Produce a type cast, i.e. ``CAST(<expression> AS <type>)``.
|
| This is a shortcut to the :func:`_expression.cast` function.
|
| .. seealso::
|
| :ref:`tutorial_casts`
|
| :func:`_expression.cast`
|
| :func:`_expression.type_coerce`
|
| comparator(...)
|
| label(self, name: 'Optional[str]') -> 'Label[_T]'
| Produce a column label, i.e. ``<columnname> AS <name>``.
|
| This is a shortcut to the :func:`_expression.label` function.
|
| If 'name' is ``None``, an anonymous label name will be generated.
|
| operate(self, op: 'operators.OperatorType', *other: 'Any', **kwargs: 'Any') -> 'ColumnElement[Any]'
| Operate on an argument.
|
| This is the lowest level of operation, raises
| :class:`NotImplementedError` by default.
|
| Overriding this on a subclass can allow common
| behavior to be applied to all operations.
| For example, overriding :class:`.ColumnOperators`
| to apply ``func.lower()`` to the left and right
| side::
|
| class MyComparator(ColumnOperators):
| def operate(self, op, other, **kwargs):
| return op(func.lower(self), func.lower(other), **kwargs)
|
| :param op: Operator callable.
| :param \*other: the 'other' side of the operation. Will
| be a single scalar for most operations.
| :param \**kwargs: modifiers. These may be passed by special
| operators such as :meth:`ColumnOperators.contains`.
|
| proxy_set(...)
| set of all columns we are proxying
|
| as of 2.0 this is explicitly deannotated columns. previously it was
| effectively deannotated columns but wasn't enforced. annotated
| columns should basically not go into sets if at all possible because
| their hashing behavior is very non-performant.
|
| reverse_operate(self, op: 'operators.OperatorType', other: 'Any', **kwargs: 'Any') -> 'ColumnElement[Any]'
| Reverse operate on an argument.
|
| Usage is the same as :meth:`operate`.
|
| self_group(self, against: 'Optional[OperatorType]' = None) -> 'ColumnElement[Any]'
| 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.
|
| shares_lineage(self, othercolumn: 'ColumnElement[Any]') -> 'bool'
| Return True if the given :class:`_expression.ColumnElement`
| has a common ancestor to this :class:`_expression.ColumnElement`.
|
| ----------------------------------------------------------------------
| Readonly properties inherited from ColumnElement:
|
| anon_key_label
| .. deprecated:: 1.4 The :attr:`_expression.ColumnElement.anon_key_label` attribute is now private, and the public accessor is deprecated.
|
| anon_label
| .. deprecated:: 1.4 The :attr:`_expression.ColumnElement.anon_label` attribute is now private, and the public accessor is deprecated.
|
| expression
| Return a column expression.
|
| Part of the inspection interface; returns self.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from ColumnElement:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from ColumnElement:
|
| foreign_keys = frozenset()
|
| key = None
|
| primary_key = False
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.AllowsLambdaRole:
|
| allows_lambda = True
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.UsesInspection:
|
| uses_inspection = True
|
| ----------------------------------------------------------------------
| Class methods inherited from typing.Generic:
|
| __class_getitem__(...)
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__(...)
| Function to initialize subclasses.
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.operators.ColumnOperators:
|
| __add__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``+`` operator.
|
| In a column context, produces the clause ``a + b``
| if the parent object has non-string affinity.
| If the parent object has a string affinity,
| produces the concatenation operator, ``a || b`` -
| see :meth:`.ColumnOperators.concat`.
|
| __contains__(self, other: 'Any') -> 'ColumnOperators'
|
| __eq__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``==`` operator.
|
| In a column context, produces the clause ``a = b``.
| If the target is ``None``, produces ``a IS NULL``.
|
| __floordiv__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``//`` operator.
|
| In a column context, produces the clause ``a / b``,
| which is the same as "truediv", but considers the result
| type to be integer.
|
| .. versionadded:: 2.0
|
| __ge__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``>=`` operator.
|
| In a column context, produces the clause ``a >= b``.
|
| __getitem__(self, index: 'Any') -> 'ColumnOperators'
| Implement the [] operator.
|
| This can be used by some database-specific types
| such as PostgreSQL ARRAY and HSTORE.
|
| __gt__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``>`` operator.
|
| In a column context, produces the clause ``a > b``.
|
| __hash__(self, /) from builtins.object
| Return hash(self).
|
| __le__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``<=`` operator.
|
| In a column context, produces the clause ``a <= b``.
|
| __lshift__(self, other: 'Any') -> 'ColumnOperators'
| implement the << operator.
|
| Not used by SQLAlchemy core, this is provided
| for custom operator systems which want to use
| << as an extension point.
|
| __lt__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``<`` operator.
|
| In a column context, produces the clause ``a < b``.
|
| __mod__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``%`` operator.
|
| In a column context, produces the clause ``a % b``.
|
| __mul__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``*`` operator.
|
| In a column context, produces the clause ``a * b``.
|
| __ne__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``!=`` operator.
|
| In a column context, produces the clause ``a != b``.
| If the target is ``None``, produces ``a IS NOT NULL``.
|
| __neg__(self) -> 'ColumnOperators'
| Implement the ``-`` operator.
|
| In a column context, produces the clause ``-a``.
|
| __radd__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``+`` operator in reverse.
|
| See :meth:`.ColumnOperators.__add__`.
|
| __rfloordiv__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``//`` operator in reverse.
|
| See :meth:`.ColumnOperators.__floordiv__`.
|
| __rmod__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``%`` operator in reverse.
|
| See :meth:`.ColumnOperators.__mod__`.
|
| __rmul__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``*`` operator in reverse.
|
| See :meth:`.ColumnOperators.__mul__`.
|
| __rshift__(self, other: 'Any') -> 'ColumnOperators'
| implement the >> operator.
|
| Not used by SQLAlchemy core, this is provided
| for custom operator systems which want to use
| >> as an extension point.
|
| __rsub__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``-`` operator in reverse.
|
| See :meth:`.ColumnOperators.__sub__`.
|
| __rtruediv__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``/`` operator in reverse.
|
| See :meth:`.ColumnOperators.__truediv__`.
|
| __sub__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``-`` operator.
|
| In a column context, produces the clause ``a - b``.
|
| __truediv__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``/`` operator.
|
| In a column context, produces the clause ``a / b``, and
| considers the result type to be numeric.
|
| .. versionchanged:: 2.0 The truediv operator against two integers
| is now considered to return a numeric value. Behavior on specific
| backends may vary.
|
| all_(self) -> 'ColumnOperators'
| Produce an :func:`_expression.all_` clause against the
| parent object.
|
| See the documentation for :func:`_sql.all_` for examples.
|
| .. note:: be sure to not confuse the newer
| :meth:`_sql.ColumnOperators.all_` method with the **legacy**
| version of this method, the :meth:`_types.ARRAY.Comparator.all`
| method that's specific to :class:`_types.ARRAY`, which uses a
| different calling style.
|
| any_(self) -> 'ColumnOperators'
| Produce an :func:`_expression.any_` clause against the
| parent object.
|
| See the documentation for :func:`_sql.any_` for examples.
|
| .. note:: be sure to not confuse the newer
| :meth:`_sql.ColumnOperators.any_` method with the **legacy**
| version of this method, the :meth:`_types.ARRAY.Comparator.any`
| method that's specific to :class:`_types.ARRAY`, which uses a
| different calling style.
|
| asc(self) -> 'ColumnOperators'
| Produce a :func:`_expression.asc` clause against the
| parent object.
|
| between(self, cleft: 'Any', cright: 'Any', symmetric: 'bool' = False) -> 'ColumnOperators'
| Produce a :func:`_expression.between` clause against
| the parent object, given the lower and upper range.
|
| bitwise_and(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise AND operation, typically via the ``&``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_lshift(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise LSHIFT operation, typically via the ``<<``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_not(self) -> 'ColumnOperators'
| Produce a bitwise NOT operation, typically via the ``~``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_or(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise OR operation, typically via the ``|``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_rshift(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise RSHIFT operation, typically via the ``>>``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_xor(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise XOR operation, typically via the ``^``
| operator, or ``#`` for PostgreSQL.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| collate(self, collation: 'str') -> 'ColumnOperators'
| Produce a :func:`_expression.collate` clause against
| the parent object, given the collation string.
|
| .. seealso::
|
| :func:`_expression.collate`
|
| concat(self, other: 'Any') -> 'ColumnOperators'
| Implement the 'concat' operator.
|
| In a column context, produces the clause ``a || b``,
| or uses the ``concat()`` operator on MySQL.
|
| contains(self, other: 'Any', **kw: 'Any') -> 'ColumnOperators'
| Implement the 'contains' operator.
|
| Produces a LIKE expression that tests against a match for the middle
| of a string value:
|
| .. sourcecode:: sql
|
| column LIKE '%' || <other> || '%'
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.contains("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.contains.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.contains.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.contains.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.contains("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE '%' || :param || '%' ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.contains("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE '%' || :param || '%' ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.contains.autoescape`::
|
| somecolumn.contains("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.startswith`
|
| :meth:`.ColumnOperators.endswith`
|
| :meth:`.ColumnOperators.like`
|
| desc(self) -> 'ColumnOperators'
| Produce a :func:`_expression.desc` clause against the
| parent object.
|
| distinct(self) -> 'ColumnOperators'
| Produce a :func:`_expression.distinct` clause against the
| parent object.
|
| endswith(self, other: 'Any', escape: 'Optional[str]' = None, autoescape: 'bool' = False) -> 'ColumnOperators'
| Implement the 'endswith' operator.
|
| Produces a LIKE expression that tests against a match for the end
| of a string value:
|
| .. sourcecode:: sql
|
| column LIKE '%' || <other>
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.endswith("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.endswith.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.endswith.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.endswith.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.endswith("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE '%' || :param ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.endswith("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE '%' || :param ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.endswith.autoescape`::
|
| somecolumn.endswith("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.startswith`
|
| :meth:`.ColumnOperators.contains`
|
| :meth:`.ColumnOperators.like`
|
| icontains(self, other: 'Any', **kw: 'Any') -> 'ColumnOperators'
| Implement the ``icontains`` operator, e.g. case insensitive
| version of :meth:`.ColumnOperators.contains`.
|
| Produces a LIKE expression that tests against an insensitive match
| for the middle of a string value:
|
| .. sourcecode:: sql
|
| lower(column) LIKE '%' || lower(<other>) || '%'
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.icontains("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.icontains.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.icontains.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.icontains.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.icontains("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE '%' || lower(:param) || '%' ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.icontains("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE '%' || lower(:param) || '%' ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.contains.autoescape`::
|
| somecolumn.icontains("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.contains`
|
| iendswith(self, other: 'Any', escape: 'Optional[str]' = None, autoescape: 'bool' = False) -> 'ColumnOperators'
| Implement the ``iendswith`` operator, e.g. case insensitive
| version of :meth:`.ColumnOperators.endswith`.
|
| Produces a LIKE expression that tests against an insensitive match
| for the end of a string value:
|
| .. sourcecode:: sql
|
| lower(column) LIKE '%' || lower(<other>)
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.iendswith("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.iendswith.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.iendswith.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.iendswith.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.iendswith("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE '%' || lower(:param) ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.iendswith("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE '%' || lower(:param) ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.iendswith.autoescape`::
|
| somecolumn.endswith("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.endswith`
|
| ilike(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
| Implement the ``ilike`` operator, e.g. case insensitive LIKE.
|
| In a column context, produces an expression either of the form:
|
| .. sourcecode:: sql
|
| lower(a) LIKE lower(other)
|
| Or on backends that support the ILIKE operator:
|
| .. sourcecode:: sql
|
| a ILIKE other
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.ilike("%foobar%"))
|
| :param other: expression to be compared
| :param escape: optional escape character, renders the ``ESCAPE``
| keyword, e.g.::
|
| somecolumn.ilike("foo/%bar", escape="/")
|
| .. seealso::
|
| :meth:`.ColumnOperators.like`
|
| in_(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``in`` operator.
|
| In a column context, produces the clause ``column IN <other>``.
|
| The given parameter ``other`` may be:
|
| * A list of literal values,
| e.g.::
|
| stmt.where(column.in_([1, 2, 3]))
|
| In this calling form, the list of items is converted to a set of
| bound parameters the same length as the list given:
|
| .. sourcecode:: sql
|
| WHERE COL IN (?, ?, ?)
|
| * A list of tuples may be provided if the comparison is against a
| :func:`.tuple_` containing multiple expressions::
|
| from sqlalchemy import tuple_
|
| stmt.where(tuple_(col1, col2).in_([(1, 10), (2, 20), (3, 30)]))
|
| * An empty list,
| e.g.::
|
| stmt.where(column.in_([]))
|
| In this calling form, the expression renders an "empty set"
| expression. These expressions are tailored to individual backends
| and are generally trying to get an empty SELECT statement as a
| subquery. Such as on SQLite, the expression is:
|
| .. sourcecode:: sql
|
| WHERE col IN (SELECT 1 FROM (SELECT 1) WHERE 1!=1)
|
| .. versionchanged:: 1.4 empty IN expressions now use an
| execution-time generated SELECT subquery in all cases.
|
| * A bound parameter, e.g. :func:`.bindparam`, may be used if it
| includes the :paramref:`.bindparam.expanding` flag::
|
| stmt.where(column.in_(bindparam("value", expanding=True)))
|
| In this calling form, the expression renders a special non-SQL
| placeholder expression that looks like:
|
| .. sourcecode:: sql
|
| WHERE COL IN ([EXPANDING_value])
|
| This placeholder expression is intercepted at statement execution
| time to be converted into the variable number of bound parameter
| form illustrated earlier. If the statement were executed as::
|
| connection.execute(stmt, {"value": [1, 2, 3]})
|
| The database would be passed a bound parameter for each value:
|
| .. sourcecode:: sql
|
| WHERE COL IN (?, ?, ?)
|
| .. versionadded:: 1.2 added "expanding" bound parameters
|
| If an empty list is passed, a special "empty list" expression,
| which is specific to the database in use, is rendered. On
| SQLite this would be:
|
| .. sourcecode:: sql
|
| WHERE COL IN (SELECT 1 FROM (SELECT 1) WHERE 1!=1)
|
| .. versionadded:: 1.3 "expanding" bound parameters now support
| empty lists
|
| * a :func:`_expression.select` construct, which is usually a
| correlated scalar select::
|
| stmt.where(
| column.in_(select(othertable.c.y).where(table.c.x == othertable.c.x))
| )
|
| In this calling form, :meth:`.ColumnOperators.in_` renders as given:
|
| .. sourcecode:: sql
|
| WHERE COL IN (SELECT othertable.y
| FROM othertable WHERE othertable.x = table.x)
|
| :param other: a list of literals, a :func:`_expression.select`
| construct, or a :func:`.bindparam` construct that includes the
| :paramref:`.bindparam.expanding` flag set to True.
|
| is_(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``IS`` operator.
|
| Normally, ``IS`` is generated automatically when comparing to a
| value of ``None``, which resolves to ``NULL``. However, explicit
| usage of ``IS`` may be desirable if comparing to boolean values
| on certain platforms.
|
| .. seealso:: :meth:`.ColumnOperators.is_not`
|
| is_distinct_from(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``IS DISTINCT FROM`` operator.
|
| Renders "a IS DISTINCT FROM b" on most platforms;
| on some such as SQLite may render "a IS NOT b".
|
| is_not(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``IS NOT`` operator.
|
| Normally, ``IS NOT`` is generated automatically when comparing to a
| value of ``None``, which resolves to ``NULL``. However, explicit
| usage of ``IS NOT`` may be desirable if comparing to boolean values
| on certain platforms.
|
| .. versionchanged:: 1.4 The ``is_not()`` operator is renamed from
| ``isnot()`` in previous releases. The previous name remains
| available for backwards compatibility.
|
| .. seealso:: :meth:`.ColumnOperators.is_`
|
| is_not_distinct_from(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``IS NOT DISTINCT FROM`` operator.
|
| Renders "a IS NOT DISTINCT FROM b" on most platforms;
| on some such as SQLite may render "a IS b".
|
| .. versionchanged:: 1.4 The ``is_not_distinct_from()`` operator is
| renamed from ``isnot_distinct_from()`` in previous releases.
| The previous name remains available for backwards compatibility.
|
| isnot = is_not(self, other: 'Any') -> 'ColumnOperators'
|
| isnot_distinct_from = is_not_distinct_from(self, other: 'Any') -> 'ColumnOperators'
|
| istartswith(self, other: 'Any', escape: 'Optional[str]' = None, autoescape: 'bool' = False) -> 'ColumnOperators'
| Implement the ``istartswith`` operator, e.g. case insensitive
| version of :meth:`.ColumnOperators.startswith`.
|
| Produces a LIKE expression that tests against an insensitive
| match for the start of a string value:
|
| .. sourcecode:: sql
|
| lower(column) LIKE lower(<other>) || '%'
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.istartswith("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.istartswith.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.istartswith.escape` parameter will
| establish a given character as an escape character which can be of
| use when the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.istartswith.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.istartswith("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE lower(:param) || '%' ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.istartswith("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE lower(:param) || '%' ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.istartswith.autoescape`::
|
| somecolumn.istartswith("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.startswith`
|
| like(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
| Implement the ``like`` operator.
|
| In a column context, produces the expression:
|
| .. sourcecode:: sql
|
| a LIKE other
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.like("%foobar%"))
|
| :param other: expression to be compared
| :param escape: optional escape character, renders the ``ESCAPE``
| keyword, e.g.::
|
| somecolumn.like("foo/%bar", escape="/")
|
| .. seealso::
|
| :meth:`.ColumnOperators.ilike`
|
| match(self, other: 'Any', **kwargs: 'Any') -> 'ColumnOperators'
| Implements a database-specific 'match' operator.
|
| :meth:`_sql.ColumnOperators.match` attempts to resolve to
| a MATCH-like function or operator provided by the backend.
| Examples include:
|
| * PostgreSQL - renders ``x @@ plainto_tsquery(y)``
|
| .. versionchanged:: 2.0 ``plainto_tsquery()`` is used instead
| of ``to_tsquery()`` for PostgreSQL now; for compatibility with
| other forms, see :ref:`postgresql_match`.
|
|
| * MySQL - renders ``MATCH (x) AGAINST (y IN BOOLEAN MODE)``
|
| .. seealso::
|
| :class:`_mysql.match` - MySQL specific construct with
| additional features.
|
| * Oracle Database - renders ``CONTAINS(x, y)``
| * other backends may provide special implementations.
| * Backends without any special implementation will emit
| the operator as "MATCH". This is compatible with SQLite, for
| example.
|
| not_ilike(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
| implement the ``NOT ILIKE`` operator.
|
| This is equivalent to using negation with
| :meth:`.ColumnOperators.ilike`, i.e. ``~x.ilike(y)``.
|
| .. versionchanged:: 1.4 The ``not_ilike()`` operator is renamed from
| ``notilike()`` in previous releases. The previous name remains
| available for backwards compatibility.
|
| .. seealso::
|
| :meth:`.ColumnOperators.ilike`
|
| not_in(self, other: 'Any') -> 'ColumnOperators'
| implement the ``NOT IN`` operator.
|
| This is equivalent to using negation with
| :meth:`.ColumnOperators.in_`, i.e. ``~x.in_(y)``.
|
| In the case that ``other`` is an empty sequence, the compiler
| produces an "empty not in" expression. This defaults to the
| expression "1 = 1" to produce true in all cases. The
| :paramref:`_sa.create_engine.empty_in_strategy` may be used to
| alter this behavior.
|
| .. versionchanged:: 1.4 The ``not_in()`` operator is renamed from
| ``notin_()`` in previous releases. The previous name remains
| available for backwards compatibility.
|
| .. versionchanged:: 1.2 The :meth:`.ColumnOperators.in_` and
| :meth:`.ColumnOperators.not_in` operators
| now produce a "static" expression for an empty IN sequence
| by default.
|
| .. seealso::
|
| :meth:`.ColumnOperators.in_`
|
| not_like(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
| implement the ``NOT LIKE`` operator.
|
| This is equivalent to using negation with
| :meth:`.ColumnOperators.like`, i.e. ``~x.like(y)``.
|
| .. versionchanged:: 1.4 The ``not_like()`` operator is renamed from
| ``notlike()`` in previous releases. The previous name remains
| available for backwards compatibility.
|
| .. seealso::
|
| :meth:`.ColumnOperators.like`
|
| notilike = not_ilike(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
|
| notin_ = not_in(self, other: 'Any') -> 'ColumnOperators'
|
| notlike = not_like(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
|
| nulls_first(self) -> 'ColumnOperators'
| Produce a :func:`_expression.nulls_first` clause against the
| parent object.
|
| .. versionchanged:: 1.4 The ``nulls_first()`` operator is
| renamed from ``nullsfirst()`` in previous releases.
| The previous name remains available for backwards compatibility.
|
| nulls_last(self) -> 'ColumnOperators'
| Produce a :func:`_expression.nulls_last` clause against the
| parent object.
|
| .. versionchanged:: 1.4 The ``nulls_last()`` operator is
| renamed from ``nullslast()`` in previous releases.
| The previous name remains available for backwards compatibility.
|
| nullsfirst = nulls_first(self) -> 'ColumnOperators'
|
| nullslast = nulls_last(self) -> 'ColumnOperators'
|
| regexp_match(self, pattern: 'Any', flags: 'Optional[str]' = None) -> 'ColumnOperators'
| Implements a database-specific 'regexp match' operator.
|
| E.g.::
|
| stmt = select(table.c.some_column).where(
| table.c.some_column.regexp_match("^(b|c)")
| )
|
| :meth:`_sql.ColumnOperators.regexp_match` attempts to resolve to
| a REGEXP-like function or operator provided by the backend, however
| the specific regular expression syntax and flags available are
| **not backend agnostic**.
|
| Examples include:
|
| * PostgreSQL - renders ``x ~ y`` or ``x !~ y`` when negated.
| * Oracle Database - renders ``REGEXP_LIKE(x, y)``
| * SQLite - uses SQLite's ``REGEXP`` placeholder operator and calls into
| the Python ``re.match()`` builtin.
| * other backends may provide special implementations.
| * Backends without any special implementation will emit
| the operator as "REGEXP" or "NOT REGEXP". This is compatible with
| SQLite and MySQL, for example.
|
| Regular expression support is currently implemented for Oracle
| Database, PostgreSQL, MySQL and MariaDB. Partial support is available
| for SQLite. Support among third-party dialects may vary.
|
| :param pattern: The regular expression pattern string or column
| clause.
| :param flags: Any regular expression string flags to apply, passed as
| plain Python string only. These flags are backend specific.
| Some backends, like PostgreSQL and MariaDB, may alternatively
| specify the flags as part of the pattern.
| When using the ignore case flag 'i' in PostgreSQL, the ignore case
| regexp match operator ``~*`` or ``!~*`` will be used.
|
| .. versionadded:: 1.4
|
| .. versionchanged:: 1.4.48, 2.0.18 Note that due to an implementation
| error, the "flags" parameter previously accepted SQL expression
| objects such as column expressions in addition to plain Python
| strings. This implementation did not work correctly with caching
| and was removed; strings only should be passed for the "flags"
| parameter, as these flags are rendered as literal inline values
| within SQL expressions.
|
| .. seealso::
|
| :meth:`_sql.ColumnOperators.regexp_replace`
|
| regexp_replace(self, pattern: 'Any', replacement: 'Any', flags: 'Optional[str]' = None) -> 'ColumnOperators'
| Implements a database-specific 'regexp replace' operator.
|
| E.g.::
|
| stmt = select(
| table.c.some_column.regexp_replace("b(..)", "XY", flags="g")
| )
|
| :meth:`_sql.ColumnOperators.regexp_replace` attempts to resolve to
| a REGEXP_REPLACE-like function provided by the backend, that
| usually emit the function ``REGEXP_REPLACE()``. However,
| the specific regular expression syntax and flags available are
| **not backend agnostic**.
|
| Regular expression replacement support is currently implemented for
| Oracle Database, PostgreSQL, MySQL 8 or greater and MariaDB. Support
| among third-party dialects may vary.
|
| :param pattern: The regular expression pattern string or column
| clause.
| :param pattern: The replacement string or column clause.
| :param flags: Any regular expression string flags to apply, passed as
| plain Python string only. These flags are backend specific.
| Some backends, like PostgreSQL and MariaDB, may alternatively
| specify the flags as part of the pattern.
|
| .. versionadded:: 1.4
|
| .. versionchanged:: 1.4.48, 2.0.18 Note that due to an implementation
| error, the "flags" parameter previously accepted SQL expression
| objects such as column expressions in addition to plain Python
| strings. This implementation did not work correctly with caching
| and was removed; strings only should be passed for the "flags"
| parameter, as these flags are rendered as literal inline values
| within SQL expressions.
|
|
| .. seealso::
|
| :meth:`_sql.ColumnOperators.regexp_match`
|
| startswith(self, other: 'Any', escape: 'Optional[str]' = None, autoescape: 'bool' = False) -> 'ColumnOperators'
| Implement the ``startswith`` operator.
|
| Produces a LIKE expression that tests against a match for the start
| of a string value:
|
| .. sourcecode:: sql
|
| column LIKE <other> || '%'
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.startswith("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.startswith.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.startswith.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.startswith.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.startswith("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE :param || '%' ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.startswith("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE :param || '%' ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.startswith.autoescape`::
|
| somecolumn.startswith("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.endswith`
|
| :meth:`.ColumnOperators.contains`
|
| :meth:`.ColumnOperators.like`
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.operators.ColumnOperators:
|
| timetuple = None
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.operators.Operators:
|
| __and__(self, other: 'Any') -> 'Operators'
| Implement the ``&`` operator.
|
| When used with SQL expressions, results in an
| AND operation, equivalent to
| :func:`_expression.and_`, that is::
|
| a & b
|
| is equivalent to::
|
| from sqlalchemy import and_
|
| and_(a, b)
|
| Care should be taken when using ``&`` regarding
| operator precedence; the ``&`` operator has the highest precedence.
| The operands should be enclosed in parenthesis if they contain
| further sub expressions::
|
| (a == 2) & (b == 4)
|
| __invert__(self) -> 'Operators'
| Implement the ``~`` operator.
|
| When used with SQL expressions, results in a
| NOT operation, equivalent to
| :func:`_expression.not_`, that is::
|
| ~a
|
| is equivalent to::
|
| from sqlalchemy import not_
|
| not_(a)
|
| __or__(self, other: 'Any') -> 'Operators'
| Implement the ``|`` operator.
|
| When used with SQL expressions, results in an
| OR operation, equivalent to
| :func:`_expression.or_`, that is::
|
| a | b
|
| is equivalent to::
|
| from sqlalchemy import or_
|
| or_(a, b)
|
| Care should be taken when using ``|`` regarding
| operator precedence; the ``|`` operator has the highest precedence.
| The operands should be enclosed in parenthesis if they contain
| further sub expressions::
|
| (a == 2) | (b == 4)
|
| __sa_operate__ = operate(self, op: 'OperatorType', *other: 'Any', **kwargs: 'Any') -> 'Operators'
| Operate on an argument.
|
| This is the lowest level of operation, raises
| :class:`NotImplementedError` by default.
|
| Overriding this on a subclass can allow common
| behavior to be applied to all operations.
| For example, overriding :class:`.ColumnOperators`
| to apply ``func.lower()`` to the left and right
| side::
|
| class MyComparator(ColumnOperators):
| def operate(self, op, other, **kwargs):
| return op(func.lower(self), func.lower(other), **kwargs)
|
| :param op: Operator callable.
| :param \*other: the 'other' side of the operation. Will
| be a single scalar for most operations.
| :param \**kwargs: modifiers. These may be passed by special
| operators such as :meth:`ColumnOperators.contains`.
|
| bool_op(self, opstring: 'str', precedence: 'int' = 0, python_impl: 'Optional[Callable[..., Any]]' = None) -> 'Callable[[Any], Operators]'
| Return a custom boolean operator.
|
| This method is shorthand for calling
| :meth:`.Operators.op` and passing the
| :paramref:`.Operators.op.is_comparison`
| flag with True. A key advantage to using :meth:`.Operators.bool_op`
| is that when using column constructs, the "boolean" nature of the
| returned expression will be present for :pep:`484` purposes.
|
| .. seealso::
|
| :meth:`.Operators.op`
|
| op(self, opstring: 'str', precedence: 'int' = 0, is_comparison: 'bool' = False, return_type: 'Optional[Union[Type[TypeEngine[Any]], TypeEngine[Any]]]' = None, python_impl: 'Optional[Callable[..., Any]]' = None) -> 'Callable[[Any], Operators]'
| Produce a generic operator function.
|
| e.g.::
|
| somecolumn.op("*")(5)
|
| produces::
|
| somecolumn * 5
|
| This function can also be used to make bitwise operators explicit. For
| example::
|
| somecolumn.op("&")(0xFF)
|
| is a bitwise AND of the value in ``somecolumn``.
|
| :param opstring: a string which will be output as the infix operator
| between this element and the expression passed to the
| generated function.
|
| :param precedence: precedence which the database is expected to apply
| to the operator in SQL expressions. This integer value acts as a hint
| for the SQL compiler to know when explicit parenthesis should be
| rendered around a particular operation. A lower number will cause the
| expression to be parenthesized when applied against another operator
| with higher precedence. The default value of ``0`` is lower than all
| operators except for the comma (``,``) and ``AS`` operators. A value
| of 100 will be higher or equal to all operators, and -100 will be
| lower than or equal to all operators.
|
| .. seealso::
|
| :ref:`faq_sql_expression_op_parenthesis` - detailed description
| of how the SQLAlchemy SQL compiler renders parenthesis
|
| :param is_comparison: legacy; if True, the operator will be considered
| as a "comparison" operator, that is which evaluates to a boolean
| true/false value, like ``==``, ``>``, etc. This flag is provided
| so that ORM relationships can establish that the operator is a
| comparison operator when used in a custom join condition.
|
| Using the ``is_comparison`` parameter is superseded by using the
| :meth:`.Operators.bool_op` method instead; this more succinct
| operator sets this parameter automatically, but also provides
| correct :pep:`484` typing support as the returned object will
| express a "boolean" datatype, i.e. ``BinaryExpression[bool]``.
|
| :param return_type: a :class:`.TypeEngine` class or object that will
| force the return type of an expression produced by this operator
| to be of that type. By default, operators that specify
| :paramref:`.Operators.op.is_comparison` will resolve to
| :class:`.Boolean`, and those that do not will be of the same
| type as the left-hand operand.
|
| :param python_impl: an optional Python function that can evaluate
| two Python values in the same way as this operator works when
| run on the database server. Useful for in-Python SQL expression
| evaluation functions, such as for ORM hybrid attributes, and the
| ORM "evaluator" used to match objects in a session after a multi-row
| update or delete.
|
| e.g.::
|
| >>> expr = column("x").op("+", python_impl=lambda a, b: a + b)("y")
|
| The operator for the above expression will also work for non-SQL
| left and right objects::
|
| >>> expr.operator(5, 10)
| 15
|
| .. versionadded:: 2.0
|
|
| .. seealso::
|
| :meth:`.Operators.bool_op`
|
| :ref:`types_operators`
|
| :ref:`relationship_custom_operator`
|
| ----------------------------------------------------------------------
| Methods inherited from ClauseElement:
|
| __bool__(self)
|
| __getstate__(self)
| Helper for pickle.
|
| __repr__(self)
| Return repr(self).
|
| compare(self, other: 'ClauseElement', **kw: 'Any') -> 'bool'
| Compare this :class:`_expression.ClauseElement` to
| the given :class:`_expression.ClauseElement`.
|
| Subclasses should override the default behavior, which is a
| straight identity comparison.
|
| \**kw are arguments consumed by subclass ``compare()`` methods and
| may be used to modify the criteria for comparison
| (see :class:`_expression.ColumnElement`).
|
| description(...)
|
| entity_namespace(...)
|
| params(self, _ClauseElement__optionaldict: 'Optional[Mapping[str, Any]]' = None, **kwargs: 'Any') -> 'Self'
| Return a copy with :func:`_expression.bindparam` elements
| replaced.
|
| Returns a copy of this ClauseElement with
| :func:`_expression.bindparam`
| elements replaced with values taken from the given dictionary::
|
| >>> clause = column("x") + bindparam("foo")
| >>> print(clause.compile().params)
| {'foo':None}
| >>> print(clause.params({"foo": 7}).compile().params)
| {'foo':7}
|
| unique_params(self, _ClauseElement__optionaldict: 'Optional[Dict[str, Any]]' = None, **kwargs: 'Any') -> 'Self'
| Return a copy with :func:`_expression.bindparam` elements
| replaced.
|
| Same functionality as :meth:`_expression.ClauseElement.params`,
| except adds `unique=True`
| to affected bind parameters so that multiple statements can be
| used.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from ClauseElement:
|
| is_clause_element = True
|
| is_dml = False
|
| is_selectable = False
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.cache_key.HasCacheKey:
|
| inherit_cache = None
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_instancemethod(fn: '_F') -> '_F'
| Decorate a method memoize its return value.
|
| :meta private:
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_attribute = <class 'sqlalchemy.util.langhelpers.HasMemoized.m...
| A read-only @property that is only evaluated once.
|
| :meta private:
|
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.visitors.HasTraverseInternals:
|
| get_children(self, *, omit_attrs: 'Tuple[str, ...]' = (), **kw: 'Any') -> 'Iterable[HasTraverseInternals]'
| Return immediate child :class:`.visitors.HasTraverseInternals`
| elements of this :class:`.visitors.HasTraverseInternals`.
|
| This is used for visit traversal.
|
| \**kw may contain flags that change the collection that is
| returned, for example to return a subset of items in order to
| cut down on larger traversals, or to return child items from a
| different context (such as schema-level collections instead of
| clause-level).
|
| ----------------------------------------------------------------------
| Methods inherited from CompilerElement:
|
| __str__(self) -> 'str'
| Return str(self).
|
| compile(self, bind: 'Optional[_HasDialect]' = None, dialect: 'Optional[Dialect]' = None, **kw: 'Any') -> 'Compiled'
| Compile this SQL expression.
|
| The return value is a :class:`~.Compiled` object.
| Calling ``str()`` or ``unicode()`` on the returned value will yield a
| string representation of the result. The
| :class:`~.Compiled` object also can return a
| dictionary of bind parameter names and values
| using the ``params`` accessor.
|
| :param bind: An :class:`.Connection` or :class:`.Engine` which
| can provide a :class:`.Dialect` in order to generate a
| :class:`.Compiled` object. If the ``bind`` and
| ``dialect`` parameters are both omitted, a default SQL compiler
| is used.
|
| :param column_keys: Used for INSERT and UPDATE statements, a list of
| column names which should be present in the VALUES clause of the
| compiled statement. If ``None``, all columns from the target table
| object are rendered.
|
| :param dialect: A :class:`.Dialect` instance which can generate
| a :class:`.Compiled` object. This argument takes precedence over
| the ``bind`` argument.
|
| :param compile_kwargs: optional dictionary of additional parameters
| that will be passed through to the compiler within all "visit"
| methods. This allows any custom flag to be passed through to
| a custom compilation construct, for example. It is also used
| for the case of passing the ``literal_binds`` flag through::
|
| from sqlalchemy.sql import table, column, select
|
| t = table("t", column("x"))
|
| s = select(t).where(t.c.x == 5)
|
| print(s.compile(compile_kwargs={"literal_binds": True}))
|
| .. seealso::
|
| :ref:`faq_sql_expression_string`
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from CompilerElement:
|
| stringify_dialect = 'default'
|
| supports_execution = False
sqlalchemy.PickleType
Python Library Documentation: class PickleType in module sqlalchemy.sql.sqltypes
class PickleType(sqlalchemy.sql.type_api.TypeDecorator)
| PickleType(protocol: 'int' = 5, pickler: 'Any' = None, comparator: 'Optional[Callable[[Any, Any], bool]]' = None, impl: 'Optional[_TypeEngineArgument[Any]]' = None)
|
| Holds Python objects, which are serialized using pickle.
|
| PickleType builds upon the Binary type to apply Python's
| ``pickle.dumps()`` to incoming objects, and ``pickle.loads()`` on
| the way out, allowing any pickleable Python object to be stored as
| a serialized binary field.
|
| To allow ORM change events to propagate for elements associated
| with :class:`.PickleType`, see :ref:`mutable_toplevel`.
|
| Method resolution order:
| PickleType
| sqlalchemy.sql.type_api.TypeDecorator
| sqlalchemy.sql.base.SchemaEventTarget
| sqlalchemy.event.registry.EventTarget
| sqlalchemy.sql.type_api.ExternalType
| sqlalchemy.sql.type_api.TypeEngineMixin
| sqlalchemy.sql.type_api.TypeEngine
| sqlalchemy.sql.visitors.Visitable
| typing.Generic
| builtins.object
|
| Methods defined here:
|
| __init__(self, protocol: 'int' = 5, pickler: 'Any' = None, comparator: 'Optional[Callable[[Any, Any], bool]]' = None, impl: 'Optional[_TypeEngineArgument[Any]]' = None)
| Construct a PickleType.
|
| :param protocol: defaults to ``pickle.HIGHEST_PROTOCOL``.
|
| :param pickler: defaults to pickle. May be any object with
| pickle-compatible ``dumps`` and ``loads`` methods.
|
| :param comparator: a 2-arg callable predicate used
| to compare values of this type. If left as ``None``,
| the Python "equals" operator is used to compare values.
|
| :param impl: A binary-storing :class:`_types.TypeEngine` class or
| instance to use in place of the default :class:`_types.LargeBinary`.
| For example the :class: `_mysql.LONGBLOB` class may be more effective
| when using MySQL.
|
| .. versionadded:: 1.4.20
|
| __reduce__(self)
| Helper for pickle.
|
| bind_processor(self, dialect)
| Provide a bound value processing function for the
| given :class:`.Dialect`.
|
| This is the method that fulfills the :class:`.TypeEngine`
| contract for bound value conversion which normally occurs via
| the :meth:`_types.TypeEngine.bind_processor` method.
|
| .. note::
|
| User-defined subclasses of :class:`_types.TypeDecorator` should
| **not** implement this method, and should instead implement
| :meth:`_types.TypeDecorator.process_bind_param` so that the "inner"
| processing provided by the implementing type is maintained.
|
| :param dialect: Dialect instance in use.
|
| compare_values(self, x, y)
| Given two values, compare them for equality.
|
| By default this calls upon :meth:`.TypeEngine.compare_values`
| of the underlying "impl", which in turn usually
| uses the Python equals operator ``==``.
|
| This function is used by the ORM to compare
| an original-loaded value with an intercepted
| "changed" value, to determine if a net change
| has occurred.
|
| result_processor(self, dialect, coltype)
| Provide a result value processing function for the given
| :class:`.Dialect`.
|
| This is the method that fulfills the :class:`.TypeEngine`
| contract for bound value conversion which normally occurs via
| the :meth:`_types.TypeEngine.result_processor` method.
|
| .. note::
|
| User-defined subclasses of :class:`_types.TypeDecorator` should
| **not** implement this method, and should instead implement
| :meth:`_types.TypeDecorator.process_result_value` so that the
| "inner" processing provided by the implementing type is maintained.
|
| :param dialect: Dialect instance in use.
| :param coltype: A SQLAlchemy data type
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| __parameters__ = ()
|
| cache_ok = True
|
| impl = <class 'sqlalchemy.sql.sqltypes.LargeBinary'>
| A type for large binary byte data.
|
| The :class:`.LargeBinary` type corresponds to a large and/or unlengthed
| binary type for the target platform, such as BLOB on MySQL and BYTEA for
| PostgreSQL. It also handles the necessary conversions for the DBAPI.
|
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.type_api.TypeDecorator:
|
| __getattr__(self, key: 'str') -> 'Any'
| Proxy all other undefined accessors to the underlying
| implementation.
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| bind_expression(self, bindparam: 'BindParameter[_T]') -> 'Optional[ColumnElement[_T]]'
| Given a bind value (i.e. a :class:`.BindParameter` instance),
| return a SQL expression which will typically wrap the given parameter.
|
| .. note::
|
| This method is called during the **SQL compilation** phase of a
| statement, when rendering a SQL string. It is **not** necessarily
| called against specific values, and should not be confused with the
| :meth:`_types.TypeDecorator.process_bind_param` method, which is
| the more typical method that processes the actual value passed to a
| particular parameter at statement execution time.
|
| Subclasses of :class:`_types.TypeDecorator` can override this method
| to provide custom bind expression behavior for the type. This
| implementation will **replace** that of the underlying implementation
| type.
|
| coerce_compared_value(self, op: 'Optional[OperatorType]', value: 'Any') -> 'Any'
| Suggest a type for a 'coerced' Python value in an expression.
|
| By default, returns self. This method is called by
| the expression system when an object using this type is
| on the left or right side of an expression against a plain Python
| object which does not yet have a SQLAlchemy type assigned::
|
| expr = table.c.somecolumn + 35
|
| Where above, if ``somecolumn`` uses this type, this method will
| be called with the value ``operator.add``
| and ``35``. The return value is whatever SQLAlchemy type should
| be used for ``35`` for this particular operation.
|
| column_expression(self, column: 'ColumnElement[_T]') -> 'Optional[ColumnElement[_T]]'
| Given a SELECT column expression, return a wrapping SQL expression.
|
| .. note::
|
| This method is called during the **SQL compilation** phase of a
| statement, when rendering a SQL string. It is **not** called
| against specific values, and should not be confused with the
| :meth:`_types.TypeDecorator.process_result_value` method, which is
| the more typical method that processes the actual value returned
| in a result row subsequent to statement execution time.
|
| Subclasses of :class:`_types.TypeDecorator` can override this method
| to provide custom column expression behavior for the type. This
| implementation will **replace** that of the underlying implementation
| type.
|
| See the description of :meth:`_types.TypeEngine.column_expression`
| for a complete description of the method's use.
|
| copy(self, **kw: 'Any') -> 'Self'
| Produce a copy of this :class:`.TypeDecorator` instance.
|
| This is a shallow copy and is provided to fulfill part of
| the :class:`.TypeEngine` contract. It usually does not
| need to be overridden unless the user-defined :class:`.TypeDecorator`
| has local state that should be deep-copied.
|
| get_dbapi_type(self, dbapi: 'DBAPIModule') -> 'Optional[Any]'
| Return the DBAPI type object represented by this
| :class:`.TypeDecorator`.
|
| By default this calls upon :meth:`.TypeEngine.get_dbapi_type` of the
| underlying "impl".
|
| impl_instance(...)
|
| literal_processor(self, dialect: 'Dialect') -> 'Optional[_LiteralProcessorType[_T]]'
| Provide a literal processing function for the given
| :class:`.Dialect`.
|
| This is the method that fulfills the :class:`.TypeEngine`
| contract for literal value conversion which normally occurs via
| the :meth:`_types.TypeEngine.literal_processor` method.
|
| .. note::
|
| User-defined subclasses of :class:`_types.TypeDecorator` should
| **not** implement this method, and should instead implement
| :meth:`_types.TypeDecorator.process_literal_param` so that the
| "inner" processing provided by the implementing type is maintained.
|
| load_dialect_impl(self, dialect: 'Dialect') -> 'TypeEngine[Any]'
| Return a :class:`.TypeEngine` object corresponding to a dialect.
|
| This is an end-user override hook that can be used to provide
| differing types depending on the given dialect. It is used
| by the :class:`.TypeDecorator` implementation of :meth:`type_engine`
| to help determine what type should ultimately be returned
| for a given :class:`.TypeDecorator`.
|
| By default returns ``self.impl``.
|
| process_bind_param(self, value: 'Optional[_T]', dialect: 'Dialect') -> 'Any'
| Receive a bound parameter value to be converted.
|
| Custom subclasses of :class:`_types.TypeDecorator` should override
| this method to provide custom behaviors for incoming data values.
| This method is called at **statement execution time** and is passed
| the literal Python data value which is to be associated with a bound
| parameter in the statement.
|
| The operation could be anything desired to perform custom
| behavior, such as transforming or serializing data.
| This could also be used as a hook for validating logic.
|
| :param value: Data to operate upon, of any type expected by
| this method in the subclass. Can be ``None``.
| :param dialect: the :class:`.Dialect` in use.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| :meth:`_types.TypeDecorator.process_result_value`
|
| process_literal_param(self, value: 'Optional[_T]', dialect: 'Dialect') -> 'str'
| Receive a literal parameter value to be rendered inline within
| a statement.
|
| .. note::
|
| This method is called during the **SQL compilation** phase of a
| statement, when rendering a SQL string. Unlike other SQL
| compilation methods, it is passed a specific Python value to be
| rendered as a string. However it should not be confused with the
| :meth:`_types.TypeDecorator.process_bind_param` method, which is
| the more typical method that processes the actual value passed to a
| particular parameter at statement execution time.
|
| Custom subclasses of :class:`_types.TypeDecorator` should override
| this method to provide custom behaviors for incoming data values
| that are in the special case of being rendered as literals.
|
| The returned string will be rendered into the output string.
|
| process_result_value(self, value: 'Optional[Any]', dialect: 'Dialect') -> 'Optional[_T]'
| Receive a result-row column value to be converted.
|
| Custom subclasses of :class:`_types.TypeDecorator` should override
| this method to provide custom behaviors for data values
| being received in result rows coming from the database.
| This method is called at **result fetching time** and is passed
| the literal Python data value that's extracted from a database result
| row.
|
| The operation could be anything desired to perform custom
| behavior, such as transforming or deserializing data.
|
| :param value: Data to operate upon, of any type expected by
| this method in the subclass. Can be ``None``.
| :param dialect: the :class:`.Dialect` in use.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| :meth:`_types.TypeDecorator.process_bind_param`
|
| type_engine(self, dialect: 'Dialect') -> 'TypeEngine[Any]'
| Return a dialect-specific :class:`.TypeEngine` instance
| for this :class:`.TypeDecorator`.
|
| In most cases this returns a dialect-adapted form of
| the :class:`.TypeEngine` type represented by ``self.impl``.
| Makes usage of :meth:`dialect_impl`.
| Behavior can be customized here by overriding
| :meth:`load_dialect_impl`.
|
| ----------------------------------------------------------------------
| Readonly properties inherited from sqlalchemy.sql.type_api.TypeDecorator:
|
| comparator_factory
| Base class for custom comparison operations defined at the
| type level. See :attr:`.TypeEngine.comparator_factory`.
|
| sort_key_function
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.type_api.TypeDecorator:
|
| Comparator = <class 'sqlalchemy.sql.type_api.TypeDecorator.Comparator'...
| A :class:`.TypeEngine.Comparator` that is specific to
| :class:`.TypeDecorator`.
|
| User-defined :class:`.TypeDecorator` classes should not typically
| need to modify this.
|
|
| __visit_name__ = 'type_decorator'
|
| coerce_to_is_types = (<class 'NoneType'>,)
|
| ----------------------------------------------------------------------
| Data descriptors inherited from sqlalchemy.sql.base.SchemaEventTarget:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.base.SchemaEventTarget:
|
| dispatch = <sqlalchemy.event.base.DDLEventsDispatch object>
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.type_api.TypeEngine:
|
| __str__(self) -> 'str'
| Return str(self).
|
| adapt(self, cls: 'Type[Union[TypeEngine[Any], TypeEngineMixin]]', **kw: 'Any') -> 'TypeEngine[Any]'
| Produce an "adapted" form of this type, given an "impl" class
| to work with.
|
| This method is used internally to associate generic
| types with "implementation" types that are specific to a particular
| dialect.
|
| as_generic(self, allow_nulltype: 'bool' = False) -> 'TypeEngine[_T]'
| Return an instance of the generic type corresponding to this type
| using heuristic rule. The method may be overridden if this
| heuristic rule is not sufficient.
|
| >>> from sqlalchemy.dialects.mysql import INTEGER
| >>> INTEGER(display_width=4).as_generic()
| Integer()
|
| >>> from sqlalchemy.dialects.mysql import NVARCHAR
| >>> NVARCHAR(length=100).as_generic()
| Unicode(length=100)
|
| .. versionadded:: 1.4.0b2
|
|
| .. seealso::
|
| :ref:`metadata_reflection_dbagnostic_types` - describes the
| use of :meth:`_types.TypeEngine.as_generic` in conjunction with
| the :meth:`_sql.DDLEvents.column_reflect` event, which is its
| intended use.
|
| compile(self, dialect: 'Optional[Dialect]' = None) -> 'str'
| Produce a string-compiled form of this :class:`.TypeEngine`.
|
| When called with no arguments, uses a "default" dialect
| to produce a string result.
|
| :param dialect: a :class:`.Dialect` instance.
|
| copy_value(self, value: 'Any') -> 'Any'
|
| dialect_impl(self, dialect: 'Dialect') -> 'TypeEngine[_T]'
| Return a dialect-specific implementation for this
| :class:`.TypeEngine`.
|
| evaluates_none(self) -> 'Self'
| Return a copy of this type which has the
| :attr:`.should_evaluate_none` flag set to True.
|
| E.g.::
|
| Table(
| "some_table",
| metadata,
| Column(
| String(50).evaluates_none(),
| nullable=True,
| server_default="no value",
| ),
| )
|
| The ORM uses this flag to indicate that a positive value of ``None``
| is passed to the column in an INSERT statement, rather than omitting
| the column from the INSERT statement which has the effect of firing
| off column-level defaults. It also allows for types which have
| special behavior associated with the Python None value to indicate
| that the value doesn't necessarily translate into SQL NULL; a
| prime example of this is a JSON type which may wish to persist the
| JSON value ``'null'``.
|
| In all cases, the actual NULL SQL value can be always be
| persisted in any column by using
| the :obj:`_expression.null` SQL construct in an INSERT statement
| or associated with an ORM-mapped attribute.
|
| .. note::
|
| The "evaluates none" flag does **not** apply to a value
| of ``None`` passed to :paramref:`_schema.Column.default` or
| :paramref:`_schema.Column.server_default`; in these cases,
| ``None``
| still means "no default".
|
| .. seealso::
|
| :ref:`session_forcing_null` - in the ORM documentation
|
| :paramref:`.postgresql.JSON.none_as_null` - PostgreSQL JSON
| interaction with this flag.
|
| :attr:`.TypeEngine.should_evaluate_none` - class-level flag
|
| with_variant(self, type_: '_TypeEngineArgument[Any]', *dialect_names: 'str') -> 'Self'
| Produce a copy of this type object that will utilize the given
| type when applied to the dialect of the given name.
|
| e.g.::
|
| from sqlalchemy.types import String
| from sqlalchemy.dialects import mysql
|
| string_type = String()
|
| string_type = string_type.with_variant(
| mysql.VARCHAR(collation="foo"), "mysql", "mariadb"
| )
|
| The variant mapping indicates that when this type is
| interpreted by a specific dialect, it will instead be
| transmuted into the given type, rather than using the
| primary type.
|
| .. versionchanged:: 2.0 the :meth:`_types.TypeEngine.with_variant`
| method now works with a :class:`_types.TypeEngine` object "in
| place", returning a copy of the original type rather than returning
| a wrapping object; the ``Variant`` class is no longer used.
|
| :param type\_: a :class:`.TypeEngine` that will be selected
| as a variant from the originating type, when a dialect
| of the given name is in use.
| :param \*dialect_names: one or more base names of the dialect which
| uses this type. (i.e. ``'postgresql'``, ``'mysql'``, etc.)
|
| .. versionchanged:: 2.0 multiple dialect names can be specified
| for one variant.
|
| .. seealso::
|
| :ref:`types_with_variant` - illustrates the use of
| :meth:`_types.TypeEngine.with_variant`.
|
| ----------------------------------------------------------------------
| Readonly properties inherited from sqlalchemy.sql.type_api.TypeEngine:
|
| python_type
| Return the Python type object expected to be returned
| by instances of this type, if known.
|
| Basically, for those types which enforce a return type,
| or are known across the board to do such for all common
| DBAPIs (like ``int`` for example), will return that type.
|
| If a return type is not defined, raises
| ``NotImplementedError``.
|
| Note that any type also accommodates NULL in SQL which
| means you can also get back ``None`` from any type
| in practice.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.type_api.TypeEngine:
|
| __orig_bases__ = (<class 'sqlalchemy.sql.visitors.Visitable'>, typing....
|
| hashable = True
|
| render_bind_cast = False
|
| render_literal_cast = False
|
| should_evaluate_none = False
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.visitors.Visitable:
|
| __class_getitem__(key: 'Any') -> 'Any'
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__() -> 'None'
| This method is called when a class is subclassed.
|
| The default implementation does nothing. It may be
| overridden to extend subclasses.
sqlalchemy.Pool
Python Library Documentation: class Pool in module sqlalchemy.pool.base
class Pool(sqlalchemy.log.Identified, sqlalchemy.event.registry.EventTarget)
| Pool(creator: 'Union[_CreatorFnType, _CreatorWRecFnType]', recycle: 'int' = -1, echo: 'log._EchoFlagType' = None, logging_name: 'Optional[str]' = None, reset_on_return: '_ResetStyleArgType' = True, events: 'Optional[List[Tuple[_ListenerFnType, str]]]' = None, dialect: 'Optional[Union[_ConnDialect, Dialect]]' = None, pre_ping: 'bool' = False, _dispatch: 'Optional[_DispatchCommon[Pool]]' = None)
|
| Abstract base class for connection pools.
|
| Method resolution order:
| Pool
| sqlalchemy.log.Identified
| sqlalchemy.event.registry.EventTarget
| builtins.object
|
| Methods defined here:
|
| __init__(self, creator: 'Union[_CreatorFnType, _CreatorWRecFnType]', recycle: 'int' = -1, echo: 'log._EchoFlagType' = None, logging_name: 'Optional[str]' = None, reset_on_return: '_ResetStyleArgType' = True, events: 'Optional[List[Tuple[_ListenerFnType, str]]]' = None, dialect: 'Optional[Union[_ConnDialect, Dialect]]' = None, pre_ping: 'bool' = False, _dispatch: 'Optional[_DispatchCommon[Pool]]' = None)
| Construct a Pool.
|
| :param creator: a callable function that returns a DB-API
| connection object. The function will be called with
| parameters.
|
| :param recycle: If set to a value other than -1, number of
| seconds between connection recycling, which means upon
| checkout, if this timeout is surpassed the connection will be
| closed and replaced with a newly opened connection. Defaults to -1.
|
| :param logging_name: String identifier which will be used within
| the "name" field of logging records generated within the
| "sqlalchemy.pool" logger. Defaults to a hexstring of the object's
| id.
|
| :param echo: if True, the connection pool will log
| informational output such as when connections are invalidated
| as well as when connections are recycled to the default log handler,
| which defaults to ``sys.stdout`` for output.. If set to the string
| ``"debug"``, the logging will include pool checkouts and checkins.
|
| The :paramref:`_pool.Pool.echo` parameter can also be set from the
| :func:`_sa.create_engine` call by using the
| :paramref:`_sa.create_engine.echo_pool` parameter.
|
| .. seealso::
|
| :ref:`dbengine_logging` - further detail on how to configure
| logging.
|
| :param reset_on_return: Determine steps to take on
| connections as they are returned to the pool, which were
| not otherwise handled by a :class:`_engine.Connection`.
| Available from :func:`_sa.create_engine` via the
| :paramref:`_sa.create_engine.pool_reset_on_return` parameter.
|
| :paramref:`_pool.Pool.reset_on_return` can have any of these values:
|
| * ``"rollback"`` - call rollback() on the connection,
| to release locks and transaction resources.
| This is the default value. The vast majority
| of use cases should leave this value set.
| * ``"commit"`` - call commit() on the connection,
| to release locks and transaction resources.
| A commit here may be desirable for databases that
| cache query plans if a commit is emitted,
| such as Microsoft SQL Server. However, this
| value is more dangerous than 'rollback' because
| any data changes present on the transaction
| are committed unconditionally.
| * ``None`` - don't do anything on the connection.
| This setting may be appropriate if the database / DBAPI
| works in pure "autocommit" mode at all times, or if
| a custom reset handler is established using the
| :meth:`.PoolEvents.reset` event handler.
|
| * ``True`` - same as 'rollback', this is here for
| backwards compatibility.
| * ``False`` - same as None, this is here for
| backwards compatibility.
|
| For further customization of reset on return, the
| :meth:`.PoolEvents.reset` event hook may be used which can perform
| any connection activity desired on reset.
|
| .. seealso::
|
| :ref:`pool_reset_on_return`
|
| :meth:`.PoolEvents.reset`
|
| :param events: a list of 2-tuples, each of the form
| ``(callable, target)`` which will be passed to :func:`.event.listen`
| upon construction. Provided here so that event listeners
| can be assigned via :func:`_sa.create_engine` before dialect-level
| listeners are applied.
|
| :param dialect: a :class:`.Dialect` that will handle the job
| of calling rollback(), close(), or commit() on DBAPI connections.
| If omitted, a built-in "stub" dialect is used. Applications that
| make use of :func:`_sa.create_engine` should not use this parameter
| as it is handled by the engine creation strategy.
|
| :param pre_ping: if True, the pool will emit a "ping" (typically
| "SELECT 1", but is dialect-specific) on the connection
| upon checkout, to test if the connection is alive or not. If not,
| the connection is transparently re-connected and upon success, all
| other pooled connections established prior to that timestamp are
| invalidated. Requires that a dialect is passed as well to
| interpret the disconnection error.
|
| .. versionadded:: 1.2
|
| connect(self) -> 'PoolProxiedConnection'
| Return a DBAPI connection from the pool.
|
| The connection is instrumented such that when its
| ``close()`` method is called, the connection will be returned to
| the pool.
|
| dispose(self) -> 'None'
| Dispose of this pool.
|
| This method leaves the possibility of checked-out connections
| remaining open, as it only affects connections that are
| idle in the pool.
|
| .. seealso::
|
| :meth:`Pool.recreate`
|
| recreate(self) -> 'Pool'
| Return a new :class:`_pool.Pool`, of the same class as this one
| and configured with identical creation arguments.
|
| This method is used in conjunction with :meth:`dispose`
| to close out an entire :class:`_pool.Pool` and create a new one in
| its place.
|
| status(self) -> 'str'
| Returns a brief description of the state of this pool.
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'_creator_arg': 'Union[_CreatorFnType, _CreatorWRec...
|
| dispatch = <sqlalchemy.event.base.PoolEventsDispatch object>
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.log.Identified:
|
| logging_name = None
sqlalchemy.PoolProxiedConnection
Python Library Documentation: class PoolProxiedConnection in module sqlalchemy.pool.base
class PoolProxiedConnection(ManagesConnection)
| A connection-like adapter for a :pep:`249` DBAPI connection, which
| includes additional methods specific to the :class:`.Pool` implementation.
|
| :class:`.PoolProxiedConnection` is the public-facing interface for the
| internal :class:`._ConnectionFairy` implementation object; users familiar
| with :class:`._ConnectionFairy` can consider this object to be equivalent.
|
| .. versionadded:: 2.0 :class:`.PoolProxiedConnection` provides the public-
| facing interface for the :class:`._ConnectionFairy` internal class.
|
| Method resolution order:
| PoolProxiedConnection
| ManagesConnection
| builtins.object
|
| Methods defined here:
|
| __enter__(self) -> 'Self'
|
| __exit__(self, exc_type: 'Any', exc_value: 'Any', traceback: 'Any') -> 'None'
|
| close(self) -> 'None'
| Release this connection back to the pool.
|
| The :meth:`.PoolProxiedConnection.close` method shadows the
| :pep:`249` ``.close()`` method, altering its behavior to instead
| :term:`release` the proxied connection back to the connection pool.
|
| Upon release to the pool, whether the connection stays "opened" and
| pooled in the Python process, versus actually closed out and removed
| from the Python process, is based on the pool implementation in use and
| its configuration and current state.
|
| detach(self) -> 'None'
| Separate this connection from its Pool.
|
| This means that the connection will no longer be returned to the
| pool when closed, and will instead be literally closed. The
| associated :class:`.ConnectionPoolEntry` is de-associated from this
| DBAPI connection.
|
| Note that any overall connection limiting constraints imposed by a
| Pool implementation may be violated after a detach, as the detached
| connection is removed from the pool's knowledge and control.
|
| ----------------------------------------------------------------------
| Readonly properties defined here:
|
| is_detached
| Return True if this :class:`.PoolProxiedConnection` is detached
| from its pool.
|
| is_valid
| Return True if this :class:`.PoolProxiedConnection` still refers
| to an active DBAPI connection.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| ----------------------------------------------------------------------
| Methods inherited from ManagesConnection:
|
| info(...)
| Info dictionary associated with the underlying DBAPI connection
| referred to by this :class:`.ManagesConnection` instance, allowing
| user-defined data to be associated with the connection.
|
| The data in this dictionary is persistent for the lifespan
| of the DBAPI connection itself, including across pool checkins
| and checkouts. When the connection is invalidated
| and replaced with a new one, this dictionary is cleared.
|
| For a :class:`.PoolProxiedConnection` instance that's not associated
| with a :class:`.ConnectionPoolEntry`, such as if it were detached, the
| attribute returns a dictionary that is local to that
| :class:`.ConnectionPoolEntry`. Therefore the
| :attr:`.ManagesConnection.info` attribute will always provide a Python
| dictionary.
|
| .. seealso::
|
| :attr:`.ManagesConnection.record_info`
|
| invalidate(self, e: 'Optional[BaseException]' = None, soft: 'bool' = False) -> 'None'
| Mark the managed connection as invalidated.
|
| :param e: an exception object indicating a reason for the invalidation.
|
| :param soft: if True, the connection isn't closed; instead, this
| connection will be recycled on next checkout.
|
| .. seealso::
|
| :ref:`pool_connection_invalidation`
|
| record_info(...)
| Persistent info dictionary associated with this
| :class:`.ManagesConnection`.
|
| Unlike the :attr:`.ManagesConnection.info` dictionary, the lifespan
| of this dictionary is that of the :class:`.ConnectionPoolEntry`
| which owns it; therefore this dictionary will persist across
| reconnects and connection invalidation for a particular entry
| in the connection pool.
|
| For a :class:`.PoolProxiedConnection` instance that's not associated
| with a :class:`.ConnectionPoolEntry`, such as if it were detached, the
| attribute returns None. Contrast to the :attr:`.ManagesConnection.info`
| dictionary which is never None.
|
|
| .. seealso::
|
| :attr:`.ManagesConnection.info`
sqlalchemy.PoolResetState
Python Library Documentation: class PoolResetState in module sqlalchemy.pool.base
class PoolResetState(builtins.object)
| PoolResetState(transaction_was_reset: 'bool', terminate_only: 'bool', asyncio_safe: 'bool') -> None
|
| describes the state of a DBAPI connection as it is being passed to
| the :meth:`.PoolEvents.reset` connection pool event.
|
| .. versionadded:: 2.0.0b3
|
| Methods defined here:
|
| __delattr__(self, name)
| Implement delattr(self, name).
|
| __eq__(self, other)
| Return self==value.
|
| __hash__(self)
| Return hash(self).
|
| __init__(self, transaction_was_reset: 'bool', terminate_only: 'bool', asyncio_safe: 'bool') -> None
| Initialize self. See help(type(self)) for accurate signature.
|
| __repr__(self)
| Return repr(self).
|
| __setattr__(self, name, value)
| Implement setattr(self, name, value).
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| asyncio_safe
|
| terminate_only
|
| transaction_was_reset
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'asyncio_safe': 'bool', 'terminate_only': 'bool', '...
|
| __dataclass_fields__ = {'asyncio_safe': Field(name='asyncio_safe',type...
|
| __dataclass_params__ = _DataclassParams(init=True,repr=True,eq=True,or...
|
| __match_args__ = ('transaction_was_reset', 'terminate_only', 'asyncio_...
sqlalchemy.PrimaryKeyConstraint
Python Library Documentation: class PrimaryKeyConstraint in module sqlalchemy.sql.schema
class PrimaryKeyConstraint(ColumnCollectionConstraint)
| PrimaryKeyConstraint(*columns: '_DDLColumnArgument', name: 'Optional[str]' = None, deferrable: 'Optional[bool]' = None, initially: 'Optional[str]' = None, info: 'Optional[_InfoType]' = None, _implicit_generated: 'bool' = False, **dialect_kw: 'Any') -> 'None'
|
| A table-level PRIMARY KEY constraint.
|
| The :class:`.PrimaryKeyConstraint` object is present automatically
| on any :class:`_schema.Table` object; it is assigned a set of
| :class:`_schema.Column` objects corresponding to those marked with
| the :paramref:`_schema.Column.primary_key` flag::
|
| >>> my_table = Table(
| ... "mytable",
| ... metadata,
| ... Column("id", Integer, primary_key=True),
| ... Column("version_id", Integer, primary_key=True),
| ... Column("data", String(50)),
| ... )
| >>> my_table.primary_key
| PrimaryKeyConstraint(
| Column('id', Integer(), table=<mytable>,
| primary_key=True, nullable=False),
| Column('version_id', Integer(), table=<mytable>,
| primary_key=True, nullable=False)
| )
|
| The primary key of a :class:`_schema.Table` can also be specified by using
| a :class:`.PrimaryKeyConstraint` object explicitly; in this mode of usage,
| the "name" of the constraint can also be specified, as well as other
| options which may be recognized by dialects::
|
| my_table = Table(
| "mytable",
| metadata,
| Column("id", Integer),
| Column("version_id", Integer),
| Column("data", String(50)),
| PrimaryKeyConstraint("id", "version_id", name="mytable_pk"),
| )
|
| The two styles of column-specification should generally not be mixed.
| An warning is emitted if the columns present in the
| :class:`.PrimaryKeyConstraint`
| don't match the columns that were marked as ``primary_key=True``, if both
| are present; in this case, the columns are taken strictly from the
| :class:`.PrimaryKeyConstraint` declaration, and those columns otherwise
| marked as ``primary_key=True`` are ignored. This behavior is intended to
| be backwards compatible with previous behavior.
|
| For the use case where specific options are to be specified on the
| :class:`.PrimaryKeyConstraint`, but the usual style of using
| ``primary_key=True`` flags is still desirable, an empty
| :class:`.PrimaryKeyConstraint` may be specified, which will take on the
| primary key column collection from the :class:`_schema.Table` based on the
| flags::
|
| my_table = Table(
| "mytable",
| metadata,
| Column("id", Integer, primary_key=True),
| Column("version_id", Integer, primary_key=True),
| Column("data", String(50)),
| PrimaryKeyConstraint(name="mytable_pk", mssql_clustered=True),
| )
|
| Method resolution order:
| PrimaryKeyConstraint
| ColumnCollectionConstraint
| ColumnCollectionMixin
| Constraint
| sqlalchemy.sql.base.DialectKWArgs
| HasConditionalDDL
| SchemaItem
| sqlalchemy.sql.base.SchemaVisitable
| sqlalchemy.sql.base.SchemaEventTarget
| sqlalchemy.event.registry.EventTarget
| sqlalchemy.sql.visitors.Visitable
| builtins.object
|
| Methods defined here:
|
| __init__(self, *columns: '_DDLColumnArgument', name: 'Optional[str]' = None, deferrable: 'Optional[bool]' = None, initially: 'Optional[str]' = None, info: 'Optional[_InfoType]' = None, _implicit_generated: 'bool' = False, **dialect_kw: 'Any') -> 'None'
| :param \*columns:
| A sequence of column names or Column objects.
|
| :param name:
| Optional, the in-database name of this constraint.
|
| :param deferrable:
| Optional bool. If set, emit DEFERRABLE or NOT DEFERRABLE when
| issuing DDL for this constraint.
|
| :param initially:
| Optional string. If set, emit INITIALLY <value> when issuing DDL
| for this constraint.
|
| :param \**dialect_kw: other keyword arguments including
| dialect-specific arguments are propagated to the :class:`.Constraint`
| superclass.
|
| ----------------------------------------------------------------------
| Readonly properties defined here:
|
| columns_autoinc_first
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| __visit_name__ = 'primary_key_constraint'
|
| ----------------------------------------------------------------------
| Methods inherited from ColumnCollectionConstraint:
|
| __contains__(self, x: 'Any') -> 'bool'
|
| __iter__(self) -> 'Iterator[Column[Any]]'
|
| __len__(self) -> 'int'
|
| contains_column(self, col: 'Column[Any]') -> 'bool'
| Return True if this constraint contains the given column.
|
| Note that this object also contains an attribute ``.columns``
| which is a :class:`_expression.ColumnCollection` of
| :class:`_schema.Column` objects.
|
| copy(self, *, target_table: 'Optional[Table]' = None, **kw: 'Any') -> 'ColumnCollectionConstraint'
| .. deprecated:: 1.4 The :meth:`_schema.ColumnCollectionConstraint.copy` method is deprecated and will be removed in a future release.
|
| ----------------------------------------------------------------------
| Methods inherited from ColumnCollectionMixin:
|
| c(...)
|
| columns(...)
|
| ----------------------------------------------------------------------
| Data descriptors inherited from ColumnCollectionMixin:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Readonly properties inherited from Constraint:
|
| table
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.base.DialectKWArgs:
|
| dialect_options(...)
| A collection of keyword arguments specified as dialect-specific
| options to this construct.
|
| This is a two-level nested registry, keyed to ``<dialect_name>``
| and ``<argument_name>``. For example, the ``postgresql_where``
| argument would be locatable as::
|
| arg = my_object.dialect_options["postgresql"]["where"]
|
| .. versionadded:: 0.9.2
|
| .. seealso::
|
| :attr:`.DialectKWArgs.dialect_kwargs` - flat dictionary form
|
| get_dialect_option(self, dialect: 'Dialect', argument_name: 'str', *, else_: 'Any' = None, deprecated_fallback: 'Optional[str]' = None) -> 'Any'
| Return the value of a dialect-specific option, or *else_* if
| this dialect does not register the given argument.
|
| This is useful for DDL compilers that may be inherited by
| third-party dialects whose ``construct_arguments`` do not
| include the same set of keys as the parent dialect.
|
| :param dialect: The dialect for which to retrieve the option.
| :param argument_name: The name of the argument to retrieve.
| :param else\_: The value to return if the argument is not present.
| :param deprecated_fallback: Optional dialect name to fall back to
| if the argument is not present for the current dialect. If the
| argument is present for the fallback dialect but not the current
| dialect, a deprecation warning will be emitted.
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.base.DialectKWArgs:
|
| argument_for(dialect_name: 'str', argument_name: 'str', default: 'Any') -> 'None'
| Add a new kind of dialect-specific keyword argument for this class.
|
| E.g.::
|
| Index.argument_for("mydialect", "length", None)
|
| some_index = Index("a", "b", mydialect_length=5)
|
| The :meth:`.DialectKWArgs.argument_for` method is a per-argument
| way adding extra arguments to the
| :attr:`.DefaultDialect.construct_arguments` dictionary. This
| dictionary provides a list of argument names accepted by various
| schema-level constructs on behalf of a dialect.
|
| New dialects should typically specify this dictionary all at once as a
| data member of the dialect class. The use case for ad-hoc addition of
| argument names is typically for end-user code that is also using
| a custom compilation scheme which consumes the additional arguments.
|
| :param dialect_name: name of a dialect. The dialect must be
| locatable, else a :class:`.NoSuchModuleError` is raised. The
| dialect must also include an existing
| :attr:`.DefaultDialect.construct_arguments` collection, indicating
| that it participates in the keyword-argument validation and default
| system, else :class:`.ArgumentError` is raised. If the dialect does
| not include this collection, then any keyword argument can be
| specified on behalf of this dialect already. All dialects packaged
| within SQLAlchemy include this collection, however for third party
| dialects, support may vary.
|
| :param argument_name: name of the parameter.
|
| :param default: default value of the parameter.
|
| ----------------------------------------------------------------------
| Readonly properties inherited from sqlalchemy.sql.base.DialectKWArgs:
|
| dialect_kwargs
| A collection of keyword arguments specified as dialect-specific
| options to this construct.
|
| The arguments are present here in their original ``<dialect>_<kwarg>``
| format. Only arguments that were actually passed are included;
| unlike the :attr:`.DialectKWArgs.dialect_options` collection, which
| contains all options known by this dialect including defaults.
|
| The collection is also writable; keys are accepted of the
| form ``<dialect>_<kwarg>`` where the value will be assembled
| into the list of options.
|
| .. seealso::
|
| :attr:`.DialectKWArgs.dialect_options` - nested dictionary form
|
| kwargs
| A synonym for :attr:`.DialectKWArgs.dialect_kwargs`.
|
| ----------------------------------------------------------------------
| Methods inherited from HasConditionalDDL:
|
| ddl_if(self, dialect: 'Optional[str]' = None, callable_: 'Optional[ddl.DDLIfCallable]' = None, state: 'Optional[Any]' = None) -> 'Self'
| apply a conditional DDL rule to this schema item.
|
| These rules work in a similar manner to the
| :meth:`.ExecutableDDLElement.execute_if` callable, with the added
| feature that the criteria may be checked within the DDL compilation
| phase for a construct such as :class:`.CreateTable`.
| :meth:`.HasConditionalDDL.ddl_if` currently applies towards the
| :class:`.Index` construct as well as all :class:`.Constraint`
| constructs.
|
| :param dialect: string name of a dialect, or a tuple of string names
| to indicate multiple dialect types.
|
| :param callable\_: a callable that is constructed using the same form
| as that described in
| :paramref:`.ExecutableDDLElement.execute_if.callable_`.
|
| :param state: any arbitrary object that will be passed to the
| callable, if present.
|
| .. versionadded:: 2.0
|
| .. seealso::
|
| :ref:`schema_ddl_ddl_if` - background and usage examples
|
| ----------------------------------------------------------------------
| Methods inherited from SchemaItem:
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| info(...)
| Info dictionary associated with the object, allowing user-defined
| data to be associated with this :class:`.SchemaItem`.
|
| The dictionary is automatically generated when first accessed.
| It can also be specified in the constructor of some objects,
| such as :class:`_schema.Table` and :class:`_schema.Column`.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from SchemaItem:
|
| create_drop_stringify_dialect = 'default'
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.base.SchemaEventTarget:
|
| dispatch = <sqlalchemy.event.base.DDLEventsDispatch object>
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.visitors.Visitable:
|
| __class_getitem__(key: 'Any') -> 'Any'
|
| __init_subclass__() -> 'None'
| This method is called when a class is subclassed.
|
| The default implementation does nothing. It may be
| overridden to extend subclasses.
sqlalchemy.QueuePool
Python Library Documentation: class QueuePool in module sqlalchemy.pool.impl
class QueuePool(sqlalchemy.pool.base.Pool)
| QueuePool(creator: 'Union[_CreatorFnType, _CreatorWRecFnType]', pool_size: 'int' = 5, max_overflow: 'int' = 10, timeout: 'float' = 30.0, use_lifo: 'bool' = False, **kw: 'Any')
|
| A :class:`_pool.Pool`
| that imposes a limit on the number of open connections.
|
| :class:`.QueuePool` is the default pooling implementation used for
| all :class:`_engine.Engine` objects other than SQLite with a ``:memory:``
| database.
|
| The :class:`.QueuePool` class **is not compatible** with asyncio and
| :func:`_asyncio.create_async_engine`. The
| :class:`.AsyncAdaptedQueuePool` class is used automatically when
| using :func:`_asyncio.create_async_engine`, if no other kind of pool
| is specified.
|
| .. seealso::
|
| :class:`.AsyncAdaptedQueuePool`
|
| Method resolution order:
| QueuePool
| sqlalchemy.pool.base.Pool
| sqlalchemy.log.Identified
| sqlalchemy.event.registry.EventTarget
| builtins.object
|
| Methods defined here:
|
| __init__(self, creator: 'Union[_CreatorFnType, _CreatorWRecFnType]', pool_size: 'int' = 5, max_overflow: 'int' = 10, timeout: 'float' = 30.0, use_lifo: 'bool' = False, **kw: 'Any')
| Construct a QueuePool.
|
| :param creator: a callable function that returns a DB-API
| connection object, same as that of :paramref:`_pool.Pool.creator`.
|
| :param pool_size: The size of the pool to be maintained,
| defaults to 5. This is the largest number of connections that
| will be kept persistently in the pool. Note that the pool
| begins with no connections; once this number of connections
| is requested, that number of connections will remain.
| ``pool_size`` can be set to 0 to indicate no size limit; to
| disable pooling, use a :class:`~sqlalchemy.pool.NullPool`
| instead.
|
| :param max_overflow: The maximum overflow size of the
| pool. When the number of checked-out connections reaches the
| size set in pool_size, additional connections will be
| returned up to this limit. When those additional connections
| are returned to the pool, they are disconnected and
| discarded. It follows then that the total number of
| simultaneous connections the pool will allow is pool_size +
| `max_overflow`, and the total number of "sleeping"
| connections the pool will allow is pool_size. `max_overflow`
| can be set to -1 to indicate no overflow limit; no limit
| will be placed on the total number of concurrent
| connections. Defaults to 10.
|
| :param timeout: The number of seconds to wait before giving up
| on returning a connection. Defaults to 30.0. This can be a float
| but is subject to the limitations of Python time functions which
| may not be reliable in the tens of milliseconds.
|
| :param use_lifo: use LIFO (last-in-first-out) when retrieving
| connections instead of FIFO (first-in-first-out). Using LIFO, a
| server-side timeout scheme can reduce the number of connections used
| during non-peak periods of use. When planning for server-side
| timeouts, ensure that a recycle or pre-ping strategy is in use to
| gracefully handle stale connections.
|
| .. versionadded:: 1.3
|
| .. seealso::
|
| :ref:`pool_use_lifo`
|
| :ref:`pool_disconnects`
|
| :param \**kw: Other keyword arguments including
| :paramref:`_pool.Pool.recycle`, :paramref:`_pool.Pool.echo`,
| :paramref:`_pool.Pool.reset_on_return` and others are passed to the
| :class:`_pool.Pool` constructor.
|
| checkedin(self) -> 'int'
|
| checkedout(self) -> 'int'
|
| dispose(self) -> 'None'
| Dispose of this pool.
|
| This method leaves the possibility of checked-out connections
| remaining open, as it only affects connections that are
| idle in the pool.
|
| .. seealso::
|
| :meth:`Pool.recreate`
|
| overflow(self) -> 'int'
|
| recreate(self) -> 'QueuePool'
| Return a new :class:`_pool.Pool`, of the same class as this one
| and configured with identical creation arguments.
|
| This method is used in conjunction with :meth:`dispose`
| to close out an entire :class:`_pool.Pool` and create a new one in
| its place.
|
| size(self) -> 'int'
|
| status(self) -> 'str'
| Returns a brief description of the state of this pool.
|
| timeout(self) -> 'float'
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'_pool': 'sqla_queue.QueueCommon[ConnectionPoolEntr...
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.pool.base.Pool:
|
| connect(self) -> 'PoolProxiedConnection'
| Return a DBAPI connection from the pool.
|
| The connection is instrumented such that when its
| ``close()`` method is called, the connection will be returned to
| the pool.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from sqlalchemy.pool.base.Pool:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.pool.base.Pool:
|
| dispatch = <sqlalchemy.event.base.PoolEventsDispatch object>
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.log.Identified:
|
| logging_name = None
sqlalchemy.REAL
Python Library Documentation: class REAL in module sqlalchemy.sql.sqltypes
class REAL(Float)
| REAL(precision: 'Optional[int]' = None, asdecimal: 'bool' = False, decimal_return_scale: 'Optional[int]' = None)
|
| The SQL REAL type.
|
| .. seealso::
|
| :class:`_types.Float` - documentation for the base type.
|
| Method resolution order:
| REAL
| Float
| Numeric
| HasExpressionLookup
| sqlalchemy.sql.type_api.TypeEngineMixin
| sqlalchemy.sql.type_api.TypeEngine
| sqlalchemy.sql.visitors.Visitable
| typing.Generic
| builtins.object
|
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| __parameters__ = ()
|
| __visit_name__ = 'REAL'
|
| ----------------------------------------------------------------------
| Methods inherited from Float:
|
| __init__(self: 'Float[_N]', precision: 'Optional[int]' = None, asdecimal: 'bool' = False, decimal_return_scale: 'Optional[int]' = None)
| Construct a Float.
|
| :param precision: the numeric precision for use in DDL ``CREATE
| TABLE``. Backends **should** attempt to ensure this precision
| indicates a number of digits for the generic
| :class:`_sqltypes.Float` datatype.
|
| .. note:: For the Oracle Database backend, the
| :paramref:`_sqltypes.Float.precision` parameter is not accepted
| when rendering DDL, as Oracle Database does not support float precision
| specified as a number of decimal places. Instead, use the
| Oracle Database-specific :class:`_oracle.FLOAT` datatype and specify the
| :paramref:`_oracle.FLOAT.binary_precision` parameter. This is new
| in version 2.0 of SQLAlchemy.
|
| To create a database agnostic :class:`_types.Float` that
| separately specifies binary precision for Oracle Database, use
| :meth:`_types.TypeEngine.with_variant` as follows::
|
| from sqlalchemy import Column
| from sqlalchemy import Float
| from sqlalchemy.dialects import oracle
|
| Column(
| "float_data",
| Float(5).with_variant(oracle.FLOAT(binary_precision=16), "oracle"),
| )
|
| :param asdecimal: the same flag as that of :class:`.Numeric`, but
| defaults to ``False``. Note that setting this flag to ``True``
| results in floating point conversion.
|
| :param decimal_return_scale: Default scale to use when converting
| from floats to Python decimals. Floating point values will typically
| be much longer due to decimal inaccuracy, and most floating point
| database types don't have a notion of "scale", so by default the
| float type looks for the first ten decimal places when converting.
| Specifying this value will override that length. Note that the
| MySQL float types, which do include "scale", will use "scale"
| as the default for decimal_return_scale, if not otherwise specified.
|
| result_processor(self, dialect, coltype)
| Return a conversion function for processing result row values.
|
| Returns a callable which will receive a result row column
| value as the sole positional argument and will return a value
| to return to the user.
|
| If processing is not necessary, the method should return ``None``.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.result_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.result_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_result_value`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| :param dialect: Dialect instance in use.
|
| :param coltype: DBAPI coltype argument received in cursor.description.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from Float:
|
| scale = None
|
| ----------------------------------------------------------------------
| Methods inherited from Numeric:
|
| bind_processor(self, dialect)
| Return a conversion function for processing bind values.
|
| Returns a callable which will receive a bind parameter value
| as the sole positional argument and will return a value to
| send to the DB-API.
|
| If processing is not necessary, the method should return ``None``.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.bind_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.bind_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_bind_param`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
|
| :param dialect: Dialect instance in use.
|
| get_dbapi_type(self, dbapi)
| Return the corresponding type object from the underlying DB-API, if
| any.
|
| This can be useful for calling ``setinputsizes()``, for example.
|
| literal_processor(self, dialect)
| Return a conversion function for processing literal values that are
| to be rendered directly without using binds.
|
| This function is used when the compiler makes use of the
| "literal_binds" flag, typically used in DDL generation as well
| as in certain scenarios where backends don't accept bound parameters.
|
| Returns a callable which will receive a literal Python value
| as the sole positional argument and will return a string representation
| to be rendered in a SQL statement.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.literal_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.literal_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_literal_param`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| ----------------------------------------------------------------------
| Readonly properties inherited from Numeric:
|
| python_type
| Return the Python type object expected to be returned
| by instances of this type, if known.
|
| Basically, for those types which enforce a return type,
| or are known across the board to do such for all common
| DBAPIs (like ``int`` for example), will return that type.
|
| If a return type is not defined, raises
| ``NotImplementedError``.
|
| Note that any type also accommodates NULL in SQL which
| means you can also get back ``None`` from any type
| in practice.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from HasExpressionLookup:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from HasExpressionLookup:
|
| Comparator = <class 'sqlalchemy.sql.sqltypes.HasExpressionLookup.Compa...
|
| comparator_factory = <class 'sqlalchemy.sql.sqltypes.HasExpressionLook...
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.type_api.TypeEngine:
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| __str__(self) -> 'str'
| Return str(self).
|
| adapt(self, cls: 'Type[Union[TypeEngine[Any], TypeEngineMixin]]', **kw: 'Any') -> 'TypeEngine[Any]'
| Produce an "adapted" form of this type, given an "impl" class
| to work with.
|
| This method is used internally to associate generic
| types with "implementation" types that are specific to a particular
| dialect.
|
| as_generic(self, allow_nulltype: 'bool' = False) -> 'TypeEngine[_T]'
| Return an instance of the generic type corresponding to this type
| using heuristic rule. The method may be overridden if this
| heuristic rule is not sufficient.
|
| >>> from sqlalchemy.dialects.mysql import INTEGER
| >>> INTEGER(display_width=4).as_generic()
| Integer()
|
| >>> from sqlalchemy.dialects.mysql import NVARCHAR
| >>> NVARCHAR(length=100).as_generic()
| Unicode(length=100)
|
| .. versionadded:: 1.4.0b2
|
|
| .. seealso::
|
| :ref:`metadata_reflection_dbagnostic_types` - describes the
| use of :meth:`_types.TypeEngine.as_generic` in conjunction with
| the :meth:`_sql.DDLEvents.column_reflect` event, which is its
| intended use.
|
| bind_expression(self, bindvalue: 'BindParameter[_T]') -> 'Optional[ColumnElement[_T]]'
| Given a bind value (i.e. a :class:`.BindParameter` instance),
| return a SQL expression in its place.
|
| This is typically a SQL function that wraps the existing bound
| parameter within the statement. It is used for special data types
| that require literals being wrapped in some special database function
| in order to coerce an application-level value into a database-specific
| format. It is the SQL analogue of the
| :meth:`.TypeEngine.bind_processor` method.
|
| This method is called during the **SQL compilation** phase of a
| statement, when rendering a SQL string. It is **not** called
| against specific values.
|
| Note that this method, when implemented, should always return
| the exact same structure, without any conditional logic, as it
| may be used in an executemany() call against an arbitrary number
| of bound parameter sets.
|
| .. note::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.bind_expression`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.bind_expression`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.bind_expression`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| .. seealso::
|
| :ref:`types_sql_value_processing`
|
| coerce_compared_value(self, op: 'Optional[OperatorType]', value: 'Any') -> 'TypeEngine[Any]'
| Suggest a type for a 'coerced' Python value in an expression.
|
| Given an operator and value, gives the type a chance
| to return a type which the value should be coerced into.
|
| The default behavior here is conservative; if the right-hand
| side is already coerced into a SQL type based on its
| Python type, it is usually left alone.
|
| End-user functionality extension here should generally be via
| :class:`.TypeDecorator`, which provides more liberal behavior in that
| it defaults to coercing the other side of the expression into this
| type, thus applying special Python conversions above and beyond those
| needed by the DBAPI to both ides. It also provides the public method
| :meth:`.TypeDecorator.coerce_compared_value` which is intended for
| end-user customization of this behavior.
|
| column_expression(self, colexpr: 'ColumnElement[_T]') -> 'Optional[ColumnElement[_T]]'
| Given a SELECT column expression, return a wrapping SQL expression.
|
| This is typically a SQL function that wraps a column expression
| as rendered in the columns clause of a SELECT statement.
| It is used for special data types that require
| columns to be wrapped in some special database function in order
| to coerce the value before being sent back to the application.
| It is the SQL analogue of the :meth:`.TypeEngine.result_processor`
| method.
|
| .. note:: The :func:`.TypeEngine.column_expression` method is applied
| only to the **outermost columns clause** of a SELECT statement, that
| is, the columns that are to be delivered directly into the returned
| result rows. It does **not** apply to the columns clause inside
| of subqueries. This necessarily avoids double conversions against
| the column and only runs the conversion when ready to be returned
| to the client.
|
| This method is called during the **SQL compilation** phase of a
| statement, when rendering a SQL string. It is **not** called
| against specific values.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.column_expression`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.column_expression`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.column_expression`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
|
| .. seealso::
|
| :ref:`types_sql_value_processing`
|
| compare_values(self, x: 'Any', y: 'Any') -> 'bool'
| Compare two values for equality.
|
| compile(self, dialect: 'Optional[Dialect]' = None) -> 'str'
| Produce a string-compiled form of this :class:`.TypeEngine`.
|
| When called with no arguments, uses a "default" dialect
| to produce a string result.
|
| :param dialect: a :class:`.Dialect` instance.
|
| copy(self, **kw: 'Any') -> 'Self'
|
| copy_value(self, value: 'Any') -> 'Any'
|
| dialect_impl(self, dialect: 'Dialect') -> 'TypeEngine[_T]'
| Return a dialect-specific implementation for this
| :class:`.TypeEngine`.
|
| evaluates_none(self) -> 'Self'
| Return a copy of this type which has the
| :attr:`.should_evaluate_none` flag set to True.
|
| E.g.::
|
| Table(
| "some_table",
| metadata,
| Column(
| String(50).evaluates_none(),
| nullable=True,
| server_default="no value",
| ),
| )
|
| The ORM uses this flag to indicate that a positive value of ``None``
| is passed to the column in an INSERT statement, rather than omitting
| the column from the INSERT statement which has the effect of firing
| off column-level defaults. It also allows for types which have
| special behavior associated with the Python None value to indicate
| that the value doesn't necessarily translate into SQL NULL; a
| prime example of this is a JSON type which may wish to persist the
| JSON value ``'null'``.
|
| In all cases, the actual NULL SQL value can be always be
| persisted in any column by using
| the :obj:`_expression.null` SQL construct in an INSERT statement
| or associated with an ORM-mapped attribute.
|
| .. note::
|
| The "evaluates none" flag does **not** apply to a value
| of ``None`` passed to :paramref:`_schema.Column.default` or
| :paramref:`_schema.Column.server_default`; in these cases,
| ``None``
| still means "no default".
|
| .. seealso::
|
| :ref:`session_forcing_null` - in the ORM documentation
|
| :paramref:`.postgresql.JSON.none_as_null` - PostgreSQL JSON
| interaction with this flag.
|
| :attr:`.TypeEngine.should_evaluate_none` - class-level flag
|
| with_variant(self, type_: '_TypeEngineArgument[Any]', *dialect_names: 'str') -> 'Self'
| Produce a copy of this type object that will utilize the given
| type when applied to the dialect of the given name.
|
| e.g.::
|
| from sqlalchemy.types import String
| from sqlalchemy.dialects import mysql
|
| string_type = String()
|
| string_type = string_type.with_variant(
| mysql.VARCHAR(collation="foo"), "mysql", "mariadb"
| )
|
| The variant mapping indicates that when this type is
| interpreted by a specific dialect, it will instead be
| transmuted into the given type, rather than using the
| primary type.
|
| .. versionchanged:: 2.0 the :meth:`_types.TypeEngine.with_variant`
| method now works with a :class:`_types.TypeEngine` object "in
| place", returning a copy of the original type rather than returning
| a wrapping object; the ``Variant`` class is no longer used.
|
| :param type\_: a :class:`.TypeEngine` that will be selected
| as a variant from the originating type, when a dialect
| of the given name is in use.
| :param \*dialect_names: one or more base names of the dialect which
| uses this type. (i.e. ``'postgresql'``, ``'mysql'``, etc.)
|
| .. versionchanged:: 2.0 multiple dialect names can be specified
| for one variant.
|
| .. seealso::
|
| :ref:`types_with_variant` - illustrates the use of
| :meth:`_types.TypeEngine.with_variant`.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.type_api.TypeEngine:
|
| __orig_bases__ = (<class 'sqlalchemy.sql.visitors.Visitable'>, typing....
|
| hashable = True
|
| render_bind_cast = False
|
| render_literal_cast = False
|
| should_evaluate_none = False
|
| sort_key_function = None
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.visitors.Visitable:
|
| __class_getitem__(key: 'Any') -> 'Any'
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__() -> 'None'
| This method is called when a class is subclassed.
|
| The default implementation does nothing. It may be
| overridden to extend subclasses.
sqlalchemy.ReleaseSavepointClause
Python Library Documentation: class ReleaseSavepointClause in module sqlalchemy.sql.elements
class ReleaseSavepointClause(_IdentifiedClause)
| ReleaseSavepointClause(ident)
|
| Method resolution order:
| ReleaseSavepointClause
| _IdentifiedClause
| sqlalchemy.sql.base.Executable
| sqlalchemy.sql.roles.StatementRole
| sqlalchemy.sql.roles.SQLRole
| ClauseElement
| sqlalchemy.sql.annotation.SupportsWrappingAnnotations
| sqlalchemy.sql.annotation.SupportsAnnotations
| sqlalchemy.sql.cache_key.MemoizedHasCacheKey
| sqlalchemy.sql.cache_key.HasCacheKey
| sqlalchemy.util.langhelpers.HasMemoized
| sqlalchemy.sql.traversals.HasCopyInternals
| sqlalchemy.sql.visitors.ExternallyTraversible
| sqlalchemy.sql.visitors.HasTraverseInternals
| CompilerElement
| sqlalchemy.sql.visitors.Visitable
| builtins.object
|
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| __visit_name__ = 'release_savepoint'
|
| inherit_cache = False
|
| ----------------------------------------------------------------------
| Methods inherited from _IdentifiedClause:
|
| __init__(self, ident)
| Initialize self. See help(type(self)) for accurate signature.
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.base.Executable:
|
| execution_options(self, **kw: 'Any') -> 'Self'
| Set non-SQL options for the statement which take effect during
| execution.
|
| Execution options can be set at many scopes, including per-statement,
| per-connection, or per execution, using methods such as
| :meth:`_engine.Connection.execution_options` and parameters which
| accept a dictionary of options such as
| :paramref:`_engine.Connection.execute.execution_options` and
| :paramref:`_orm.Session.execute.execution_options`.
|
| The primary characteristic of an execution option, as opposed to
| other kinds of options such as ORM loader options, is that
| **execution options never affect the compiled SQL of a query, only
| things that affect how the SQL statement itself is invoked or how
| results are fetched**. That is, execution options are not part of
| what's accommodated by SQL compilation nor are they considered part of
| the cached state of a statement.
|
| The :meth:`_sql.Executable.execution_options` method is
| :term:`generative`, as
| is the case for the method as applied to the :class:`_engine.Engine`
| and :class:`_orm.Query` objects, which means when the method is called,
| a copy of the object is returned, which applies the given parameters to
| that new copy, but leaves the original unchanged::
|
| statement = select(table.c.x, table.c.y)
| new_statement = statement.execution_options(my_option=True)
|
| An exception to this behavior is the :class:`_engine.Connection`
| object, where the :meth:`_engine.Connection.execution_options` method
| is explicitly **not** generative.
|
| The kinds of options that may be passed to
| :meth:`_sql.Executable.execution_options` and other related methods and
| parameter dictionaries include parameters that are explicitly consumed
| by SQLAlchemy Core or ORM, as well as arbitrary keyword arguments not
| defined by SQLAlchemy, which means the methods and/or parameter
| dictionaries may be used for user-defined parameters that interact with
| custom code, which may access the parameters using methods such as
| :meth:`_sql.Executable.get_execution_options` and
| :meth:`_engine.Connection.get_execution_options`, or within selected
| event hooks using a dedicated ``execution_options`` event parameter
| such as
| :paramref:`_events.ConnectionEvents.before_execute.execution_options`
| or :attr:`_orm.ORMExecuteState.execution_options`, e.g.::
|
| from sqlalchemy import event
|
|
| @event.listens_for(some_engine, "before_execute")
| def _process_opt(conn, statement, multiparams, params, execution_options):
| "run a SQL function before invoking a statement"
|
| if execution_options.get("do_special_thing", False):
| conn.exec_driver_sql("run_special_function()")
|
| Within the scope of options that are explicitly recognized by
| SQLAlchemy, most apply to specific classes of objects and not others.
| The most common execution options include:
|
| * :paramref:`_engine.Connection.execution_options.isolation_level` -
| sets the isolation level for a connection or a class of connections
| via an :class:`_engine.Engine`. This option is accepted only
| by :class:`_engine.Connection` or :class:`_engine.Engine`.
|
| * :paramref:`_engine.Connection.execution_options.stream_results` -
| indicates results should be fetched using a server side cursor;
| this option is accepted by :class:`_engine.Connection`, by the
| :paramref:`_engine.Connection.execute.execution_options` parameter
| on :meth:`_engine.Connection.execute`, and additionally by
| :meth:`_sql.Executable.execution_options` on a SQL statement object,
| as well as by ORM constructs like :meth:`_orm.Session.execute`.
|
| * :paramref:`_engine.Connection.execution_options.compiled_cache` -
| indicates a dictionary that will serve as the
| :ref:`SQL compilation cache <sql_caching>`
| for a :class:`_engine.Connection` or :class:`_engine.Engine`, as
| well as for ORM methods like :meth:`_orm.Session.execute`.
| Can be passed as ``None`` to disable caching for statements.
| This option is not accepted by
| :meth:`_sql.Executable.execution_options` as it is inadvisable to
| carry along a compilation cache within a statement object.
|
| * :paramref:`_engine.Connection.execution_options.schema_translate_map`
| - a mapping of schema names used by the
| :ref:`Schema Translate Map <schema_translating>` feature, accepted
| by :class:`_engine.Connection`, :class:`_engine.Engine`,
| :class:`_sql.Executable`, as well as by ORM constructs
| like :meth:`_orm.Session.execute`.
|
| .. seealso::
|
| :meth:`_engine.Connection.execution_options`
|
| :paramref:`_engine.Connection.execute.execution_options`
|
| :paramref:`_orm.Session.execute.execution_options`
|
| :ref:`orm_queryguide_execution_options` - documentation on all
| ORM-specific execution options
|
| get_execution_options(self) -> '_ExecuteOptions'
| Get the non-SQL options which will take effect during execution.
|
| .. versionadded:: 1.3
|
| .. seealso::
|
| :meth:`.Executable.execution_options`
|
| options(self, *options: 'ExecutableOption') -> 'Self'
| Apply options to this statement.
|
| In the general sense, options are any kind of Python object
| that can be interpreted by the SQL compiler for the statement.
| These options can be consumed by specific dialects or specific kinds
| of compilers.
|
| The most commonly known kind of option are the ORM level options
| that apply "eager load" and other loading behaviors to an ORM
| query. However, options can theoretically be used for many other
| purposes.
|
| For background on specific kinds of options for specific kinds of
| statements, refer to the documentation for those option objects.
|
| .. versionchanged:: 1.4 - added :meth:`.Executable.options` to
| Core statement objects towards the goal of allowing unified
| Core / ORM querying capabilities.
|
| .. seealso::
|
| :ref:`loading_columns` - refers to options specific to the usage
| of ORM queries
|
| :ref:`relationship_loader_options` - refers to options specific
| to the usage of ORM queries
|
| ----------------------------------------------------------------------
| Data descriptors inherited from sqlalchemy.sql.base.Executable:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.base.Executable:
|
| is_delete = False
|
| is_dml = False
|
| is_from_statement = False
|
| is_insert = False
|
| is_select = False
|
| is_text = False
|
| is_update = False
|
| supports_execution = True
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.SQLRole:
|
| allows_lambda = False
|
| uses_inspection = False
|
| ----------------------------------------------------------------------
| Methods inherited from ClauseElement:
|
| __bool__(self)
|
| __getstate__(self)
| Helper for pickle.
|
| __invert__(self)
|
| __repr__(self)
| Return repr(self).
|
| compare(self, other: 'ClauseElement', **kw: 'Any') -> 'bool'
| Compare this :class:`_expression.ClauseElement` to
| the given :class:`_expression.ClauseElement`.
|
| Subclasses should override the default behavior, which is a
| straight identity comparison.
|
| \**kw are arguments consumed by subclass ``compare()`` methods and
| may be used to modify the criteria for comparison
| (see :class:`_expression.ColumnElement`).
|
| description(...)
|
| entity_namespace(...)
|
| params(self, _ClauseElement__optionaldict: 'Optional[Mapping[str, Any]]' = None, **kwargs: 'Any') -> 'Self'
| Return a copy with :func:`_expression.bindparam` elements
| replaced.
|
| Returns a copy of this ClauseElement with
| :func:`_expression.bindparam`
| elements replaced with values taken from the given dictionary::
|
| >>> clause = column("x") + bindparam("foo")
| >>> print(clause.compile().params)
| {'foo':None}
| >>> print(clause.params({"foo": 7}).compile().params)
| {'foo':7}
|
| self_group(self, against: 'Optional[OperatorType]' = None) -> 'ClauseElement'
| 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.
|
| unique_params(self, _ClauseElement__optionaldict: 'Optional[Dict[str, Any]]' = None, **kwargs: 'Any') -> 'Self'
| Return a copy with :func:`_expression.bindparam` elements
| replaced.
|
| Same functionality as :meth:`_expression.ClauseElement.params`,
| except adds `unique=True`
| to affected bind parameters so that multiple statements can be
| used.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from ClauseElement:
|
| is_clause_element = True
|
| is_selectable = False
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_instancemethod(fn: '_F') -> '_F'
| Decorate a method memoize its return value.
|
| :meta private:
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_attribute = <class 'sqlalchemy.util.langhelpers.HasMemoized.m...
| A read-only @property that is only evaluated once.
|
| :meta private:
|
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.visitors.HasTraverseInternals:
|
| get_children(self, *, omit_attrs: 'Tuple[str, ...]' = (), **kw: 'Any') -> 'Iterable[HasTraverseInternals]'
| Return immediate child :class:`.visitors.HasTraverseInternals`
| elements of this :class:`.visitors.HasTraverseInternals`.
|
| This is used for visit traversal.
|
| \**kw may contain flags that change the collection that is
| returned, for example to return a subset of items in order to
| cut down on larger traversals, or to return child items from a
| different context (such as schema-level collections instead of
| clause-level).
|
| ----------------------------------------------------------------------
| Methods inherited from CompilerElement:
|
| __str__(self) -> 'str'
| Return str(self).
|
| compile(self, bind: 'Optional[_HasDialect]' = None, dialect: 'Optional[Dialect]' = None, **kw: 'Any') -> 'Compiled'
| Compile this SQL expression.
|
| The return value is a :class:`~.Compiled` object.
| Calling ``str()`` or ``unicode()`` on the returned value will yield a
| string representation of the result. The
| :class:`~.Compiled` object also can return a
| dictionary of bind parameter names and values
| using the ``params`` accessor.
|
| :param bind: An :class:`.Connection` or :class:`.Engine` which
| can provide a :class:`.Dialect` in order to generate a
| :class:`.Compiled` object. If the ``bind`` and
| ``dialect`` parameters are both omitted, a default SQL compiler
| is used.
|
| :param column_keys: Used for INSERT and UPDATE statements, a list of
| column names which should be present in the VALUES clause of the
| compiled statement. If ``None``, all columns from the target table
| object are rendered.
|
| :param dialect: A :class:`.Dialect` instance which can generate
| a :class:`.Compiled` object. This argument takes precedence over
| the ``bind`` argument.
|
| :param compile_kwargs: optional dictionary of additional parameters
| that will be passed through to the compiler within all "visit"
| methods. This allows any custom flag to be passed through to
| a custom compilation construct, for example. It is also used
| for the case of passing the ``literal_binds`` flag through::
|
| from sqlalchemy.sql import table, column, select
|
| t = table("t", column("x"))
|
| s = select(t).where(t.c.x == 5)
|
| print(s.compile(compile_kwargs={"literal_binds": True}))
|
| .. seealso::
|
| :ref:`faq_sql_expression_string`
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from CompilerElement:
|
| stringify_dialect = 'default'
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.visitors.Visitable:
|
| __class_getitem__(key: 'Any') -> 'Any'
|
| __init_subclass__() -> 'None'
| This method is called when a class is subclassed.
|
| The default implementation does nothing. It may be
| overridden to extend subclasses.
sqlalchemy.Result
Python Library Documentation: class Result in module sqlalchemy.engine.result
class Result(_WithKeys, ResultInternal)
| Result(cursor_metadata: 'ResultMetaData')
|
| Represent a set of database results.
|
| .. versionadded:: 1.4 The :class:`_engine.Result` object provides a
| completely updated usage model and calling facade for SQLAlchemy
| Core and SQLAlchemy ORM. In Core, it forms the basis of the
| :class:`_engine.CursorResult` object which replaces the previous
| :class:`_engine.ResultProxy` interface. When using the ORM, a
| higher level object called :class:`_engine.ChunkedIteratorResult`
| is normally used.
|
| .. note:: In SQLAlchemy 1.4 and above, this object is
| used for ORM results returned by :meth:`_orm.Session.execute`, which can
| yield instances of ORM mapped objects either individually or within
| tuple-like rows. Note that the :class:`_engine.Result` object does not
| deduplicate instances or rows automatically as is the case with the
| legacy :class:`_orm.Query` object. For in-Python de-duplication of
| instances or rows, use the :meth:`_engine.Result.unique` modifier
| method.
|
| .. seealso::
|
| :ref:`tutorial_fetching_rows` - in the :doc:`/tutorial/index`
|
| Method resolution order:
| Result
| _WithKeys
| ResultInternal
| sqlalchemy.sql.base.InPlaceGenerative
| sqlalchemy.util.langhelpers.HasMemoized
| typing.Generic
| builtins.object
|
| Methods defined here:
|
| __enter__(self) -> 'Self'
|
| __exit__(self, type_: 'Any', value: 'Any', traceback: 'Any') -> 'None'
|
| __init__(self, cursor_metadata: 'ResultMetaData')
| Initialize self. See help(type(self)) for accurate signature.
|
| __iter__(self) -> 'Iterator[Row[_TP]]'
|
| __next__(self) -> 'Row[_TP]'
|
| all(self) -> 'Sequence[Row[_TP]]'
| Return all rows in a sequence.
|
| Closes the result set after invocation. Subsequent invocations
| will return an empty sequence.
|
| .. versionadded:: 1.4
|
| :return: a sequence of :class:`_engine.Row` objects.
|
| .. seealso::
|
| :ref:`engine_stream_results` - How to stream a large result set
| without loading it completely in python.
|
| close(self) -> 'None'
| Hard close this :class:`_engine.Result`.
|
| The behavior of this method is implementation specific, and is
| not implemented by default. The method should generally end
| the resources in use by the result object and also cause any
| subsequent iteration or row fetching to raise
| :class:`.ResourceClosedError`.
|
| .. versionadded:: 1.4.27 - ``.close()`` was previously not generally
| available for all :class:`_engine.Result` classes, instead only
| being available on the :class:`_engine.CursorResult` returned for
| Core statement executions. As most other result objects, namely the
| ones used by the ORM, are proxying a :class:`_engine.CursorResult`
| in any case, this allows the underlying cursor result to be closed
| from the outside facade for the case when the ORM query is using
| the ``yield_per`` execution option where it does not immediately
| exhaust and autoclose the database cursor.
|
| columns(self, *col_expressions: '_KeyIndexType') -> 'Self'
| Establish the columns that should be returned in each row.
|
| This method may be used to limit the columns returned as well
| as to reorder them. The given list of expressions are normally
| a series of integers or string key names. They may also be
| appropriate :class:`.ColumnElement` objects which correspond to
| a given statement construct.
|
| .. versionchanged:: 2.0 Due to a bug in 1.4, the
| :meth:`_engine.Result.columns` method had an incorrect behavior
| where calling upon the method with just one index would cause the
| :class:`_engine.Result` object to yield scalar values rather than
| :class:`_engine.Row` objects. In version 2.0, this behavior
| has been corrected such that calling upon
| :meth:`_engine.Result.columns` with a single index will
| produce a :class:`_engine.Result` object that continues
| to yield :class:`_engine.Row` objects, which include
| only a single column.
|
| E.g.::
|
| statement = select(table.c.x, table.c.y, table.c.z)
| result = connection.execute(statement)
|
| for z, y in result.columns("z", "y"):
| ...
|
| Example of using the column objects from the statement itself::
|
| for z, y in result.columns(
| statement.selected_columns.c.z, statement.selected_columns.c.y
| ):
| ...
|
| .. versionadded:: 1.4
|
| :param \*col_expressions: indicates columns to be returned. Elements
| may be integer row indexes, string column names, or appropriate
| :class:`.ColumnElement` objects corresponding to a select construct.
|
| :return: this :class:`_engine.Result` object with the modifications
| given.
|
| fetchall(self) -> 'Sequence[Row[_TP]]'
| A synonym for the :meth:`_engine.Result.all` method.
|
| fetchmany(self, size: 'Optional[int]' = None) -> 'Sequence[Row[_TP]]'
| Fetch many rows.
|
| When all rows are exhausted, returns an empty sequence.
|
| This method is provided for backwards compatibility with
| SQLAlchemy 1.x.x.
|
| To fetch rows in groups, use the :meth:`_engine.Result.partitions`
| method.
|
| :return: a sequence of :class:`_engine.Row` objects.
|
| .. seealso::
|
| :meth:`_engine.Result.partitions`
|
| fetchone(self) -> 'Optional[Row[_TP]]'
| Fetch one row.
|
| When all rows are exhausted, returns None.
|
| This method is provided for backwards compatibility with
| SQLAlchemy 1.x.x.
|
| To fetch the first row of a result only, use the
| :meth:`_engine.Result.first` method. To iterate through all
| rows, iterate the :class:`_engine.Result` object directly.
|
| :return: a :class:`_engine.Row` object if no filters are applied,
| or ``None`` if no rows remain.
|
| first(self) -> 'Optional[Row[_TP]]'
| Fetch the first row or ``None`` if no row is present.
|
| Closes the result set and discards remaining rows.
|
| .. note:: This method returns one **row**, e.g. tuple, by default.
| To return exactly one single scalar value, that is, the first
| column of the first row, use the
| :meth:`_engine.Result.scalar` method,
| or combine :meth:`_engine.Result.scalars` and
| :meth:`_engine.Result.first`.
|
| Additionally, in contrast to the behavior of the legacy ORM
| :meth:`_orm.Query.first` method, **no limit is applied** to the
| SQL query which was invoked to produce this
| :class:`_engine.Result`;
| for a DBAPI driver that buffers results in memory before yielding
| rows, all rows will be sent to the Python process and all but
| the first row will be discarded.
|
| .. seealso::
|
| :ref:`migration_20_unify_select`
|
| :return: a :class:`_engine.Row` object, or None
| if no rows remain.
|
| .. seealso::
|
| :meth:`_engine.Result.scalar`
|
| :meth:`_engine.Result.one`
|
| freeze(self) -> 'FrozenResult[_TP]'
| Return a callable object that will produce copies of this
| :class:`_engine.Result` when invoked.
|
| The callable object returned is an instance of
| :class:`_engine.FrozenResult`.
|
| This is used for result set caching. The method must be called
| on the result when it has been unconsumed, and calling the method
| will consume the result fully. When the :class:`_engine.FrozenResult`
| is retrieved from a cache, it can be called any number of times where
| it will produce a new :class:`_engine.Result` object each time
| against its stored set of rows.
|
| .. seealso::
|
| :ref:`do_orm_execute_re_executing` - example usage within the
| ORM to implement a result-set cache.
|
| mappings(self) -> 'MappingResult'
| Apply a mappings filter to returned rows, returning an instance of
| :class:`_engine.MappingResult`.
|
| When this filter is applied, fetching rows will return
| :class:`_engine.RowMapping` objects instead of :class:`_engine.Row`
| objects.
|
| .. versionadded:: 1.4
|
| :return: a new :class:`_engine.MappingResult` filtering object
| referring to this :class:`_engine.Result` object.
|
| merge(self, *others: 'Result[Any]') -> 'MergedResult[_TP]'
| Merge this :class:`_engine.Result` with other compatible result
| objects.
|
| The object returned is an instance of :class:`_engine.MergedResult`,
| which will be composed of iterators from the given result
| objects.
|
| The new result will use the metadata from this result object.
| The subsequent result objects must be against an identical
| set of result / cursor metadata, otherwise the behavior is
| undefined.
|
| one(self) -> 'Row[_TP]'
| Return exactly one row or raise an exception.
|
| Raises :class:`_exc.NoResultFound` if the result returns no
| rows, or :class:`_exc.MultipleResultsFound` if multiple rows
| would be returned.
|
| .. note:: This method returns one **row**, e.g. tuple, by default.
| To return exactly one single scalar value, that is, the first
| column of the first row, use the
| :meth:`_engine.Result.scalar_one` method, or combine
| :meth:`_engine.Result.scalars` and
| :meth:`_engine.Result.one`.
|
| .. versionadded:: 1.4
|
| :return: The first :class:`_engine.Row`.
|
| :raises: :class:`.MultipleResultsFound`, :class:`.NoResultFound`
|
| .. seealso::
|
| :meth:`_engine.Result.first`
|
| :meth:`_engine.Result.one_or_none`
|
| :meth:`_engine.Result.scalar_one`
|
| one_or_none(self) -> 'Optional[Row[_TP]]'
| Return at most one result or raise an exception.
|
| Returns ``None`` if the result has no rows.
| Raises :class:`.MultipleResultsFound`
| if multiple rows are returned.
|
| .. versionadded:: 1.4
|
| :return: The first :class:`_engine.Row` or ``None`` if no row
| is available.
|
| :raises: :class:`.MultipleResultsFound`
|
| .. seealso::
|
| :meth:`_engine.Result.first`
|
| :meth:`_engine.Result.one`
|
| partitions(self, size: 'Optional[int]' = None) -> 'Iterator[Sequence[Row[_TP]]]'
| Iterate through sub-lists of rows of the size given.
|
| Each list will be of the size given, excluding the last list to
| be yielded, which may have a small number of rows. No empty
| lists will be yielded.
|
| The result object is automatically closed when the iterator
| is fully consumed.
|
| Note that the backend driver will usually buffer the entire result
| ahead of time unless the
| :paramref:`.Connection.execution_options.stream_results` execution
| option is used indicating that the driver should not pre-buffer
| results, if possible. Not all drivers support this option and
| the option is silently ignored for those who do not.
|
| When using the ORM, the :meth:`_engine.Result.partitions` method
| is typically more effective from a memory perspective when it is
| combined with use of the
| :ref:`yield_per execution option <orm_queryguide_yield_per>`,
| which instructs both the DBAPI driver to use server side cursors,
| if available, as well as instructs the ORM loading internals to only
| build a certain amount of ORM objects from a result at a time before
| yielding them out.
|
| .. versionadded:: 1.4
|
| :param size: indicate the maximum number of rows to be present
| in each list yielded. If None, makes use of the value set by
| the :meth:`_engine.Result.yield_per`, method, if it were called,
| or the :paramref:`_engine.Connection.execution_options.yield_per`
| execution option, which is equivalent in this regard. If
| yield_per weren't set, it makes use of the
| :meth:`_engine.Result.fetchmany` default, which may be backend
| specific and not well defined.
|
| :return: iterator of lists
|
| .. seealso::
|
| :ref:`engine_stream_results`
|
| :ref:`orm_queryguide_yield_per` - in the :ref:`queryguide_toplevel`
|
| scalar(self) -> 'Any'
| Fetch the first column of the first row, and close the result set.
|
| Returns ``None`` if there are no rows to fetch.
|
| No validation is performed to test if additional rows remain.
|
| After calling this method, the object is fully closed,
| e.g. the :meth:`_engine.CursorResult.close`
| method will have been called.
|
| :return: a Python scalar value, or ``None`` if no rows remain.
|
| scalar_one(self) -> 'Any'
| Return exactly one scalar result or raise an exception.
|
| This is equivalent to calling :meth:`_engine.Result.scalars` and
| then :meth:`_engine.ScalarResult.one`.
|
| .. seealso::
|
| :meth:`_engine.ScalarResult.one`
|
| :meth:`_engine.Result.scalars`
|
| scalar_one_or_none(self) -> 'Optional[Any]'
| Return exactly one scalar result or ``None``.
|
| This is equivalent to calling :meth:`_engine.Result.scalars` and
| then :meth:`_engine.ScalarResult.one_or_none`.
|
| .. seealso::
|
| :meth:`_engine.ScalarResult.one_or_none`
|
| :meth:`_engine.Result.scalars`
|
| scalars(self, index: '_KeyIndexType' = 0) -> 'ScalarResult[Any]'
| Return a :class:`_engine.ScalarResult` filtering object which
| will return single elements rather than :class:`_row.Row` objects.
|
| E.g.::
|
| >>> result = conn.execute(text("select int_id from table"))
| >>> result.scalars().all()
| [1, 2, 3]
|
| When results are fetched from the :class:`_engine.ScalarResult`
| filtering object, the single column-row that would be returned by the
| :class:`_engine.Result` is instead returned as the column's value.
|
| .. versionadded:: 1.4
|
| :param index: integer or row key indicating the column to be fetched
| from each row, defaults to ``0`` indicating the first column.
|
| :return: a new :class:`_engine.ScalarResult` filtering object referring
| to this :class:`_engine.Result` object.
|
| tuples(self) -> 'TupleResult[_TP]'
| Apply a "typed tuple" typing filter to returned rows.
|
| This method returns the same :class:`_engine.Result` object
| at runtime,
| however annotates as returning a :class:`_engine.TupleResult` object
| that will indicate to :pep:`484` typing tools that plain typed
| ``Tuple`` instances are returned rather than rows. This allows
| tuple unpacking and ``__getitem__`` access of :class:`_engine.Row`
| objects to by typed, for those cases where the statement invoked
| itself included typing information.
|
| .. versionadded:: 2.0
|
| :return: the :class:`_engine.TupleResult` type at typing time.
|
| .. seealso::
|
| :attr:`_engine.Result.t` - shorter synonym
|
| :attr:`_engine.Row._t` - :class:`_engine.Row` version
|
| unique(self, strategy: 'Optional[_UniqueFilterType]' = None) -> 'Self'
| Apply unique filtering to the objects returned by this
| :class:`_engine.Result`.
|
| When this filter is applied with no arguments, the rows or objects
| returned will filtered such that each row is returned uniquely. The
| algorithm used to determine this uniqueness is by default the Python
| hashing identity of the whole tuple. In some cases a specialized
| per-entity hashing scheme may be used, such as when using the ORM, a
| scheme is applied which works against the primary key identity of
| returned objects.
|
| The unique filter is applied **after all other filters**, which means
| if the columns returned have been refined using a method such as the
| :meth:`_engine.Result.columns` or :meth:`_engine.Result.scalars`
| method, the uniquing is applied to **only the column or columns
| returned**. This occurs regardless of the order in which these
| methods have been called upon the :class:`_engine.Result` object.
|
| The unique filter also changes the calculus used for methods like
| :meth:`_engine.Result.fetchmany` and :meth:`_engine.Result.partitions`.
| When using :meth:`_engine.Result.unique`, these methods will continue
| to yield the number of rows or objects requested, after uniquing
| has been applied. However, this necessarily impacts the buffering
| behavior of the underlying cursor or datasource, such that multiple
| underlying calls to ``cursor.fetchmany()`` may be necessary in order
| to accumulate enough objects in order to provide a unique collection
| of the requested size.
|
| :param strategy: a callable that will be applied to rows or objects
| being iterated, which should return an object that represents the
| unique value of the row. A Python ``set()`` is used to store
| these identities. If not passed, a default uniqueness strategy
| is used which may have been assembled by the source of this
| :class:`_engine.Result` object.
|
| yield_per(self, num: 'int') -> 'Self'
| Configure the row-fetching strategy to fetch ``num`` rows at a time.
|
| This impacts the underlying behavior of the result when iterating over
| the result object, or otherwise making use of methods such as
| :meth:`_engine.Result.fetchone` that return one row at a time. Data
| from the underlying cursor or other data source will be buffered up to
| this many rows in memory, and the buffered collection will then be
| yielded out one row at a time or as many rows are requested. Each time
| the buffer clears, it will be refreshed to this many rows or as many
| rows remain if fewer remain.
|
| The :meth:`_engine.Result.yield_per` method is generally used in
| conjunction with the
| :paramref:`_engine.Connection.execution_options.stream_results`
| execution option, which will allow the database dialect in use to make
| use of a server side cursor, if the DBAPI supports a specific "server
| side cursor" mode separate from its default mode of operation.
|
| .. tip::
|
| Consider using the
| :paramref:`_engine.Connection.execution_options.yield_per`
| execution option, which will simultaneously set
| :paramref:`_engine.Connection.execution_options.stream_results`
| to ensure the use of server side cursors, as well as automatically
| invoke the :meth:`_engine.Result.yield_per` method to establish
| a fixed row buffer size at once.
|
| The :paramref:`_engine.Connection.execution_options.yield_per`
| execution option is available for ORM operations, with
| :class:`_orm.Session`-oriented use described at
| :ref:`orm_queryguide_yield_per`. The Core-only version which works
| with :class:`_engine.Connection` is new as of SQLAlchemy 1.4.40.
|
| .. versionadded:: 1.4
|
| :param num: number of rows to fetch each time the buffer is refilled.
| If set to a value below 1, fetches all rows for the next buffer.
|
| .. seealso::
|
| :ref:`engine_stream_results` - describes Core behavior for
| :meth:`_engine.Result.yield_per`
|
| :ref:`orm_queryguide_yield_per` - in the :ref:`queryguide_toplevel`
|
| ----------------------------------------------------------------------
| Readonly properties defined here:
|
| closed
| Return ``True`` if this :class:`_engine.Result` was **hard closed**
| by explicitly calling the :meth:`close` method.
|
| The attribute is **not** True if the :class:`_engine.Result` was only
| **soft closed**; a "soft close" is the style of close that takes place
| for example when the :class:`.CursorResult` is returned for a DML
| only statement without RETURNING, or when all result rows are fetched.
|
| .. seealso::
|
| :attr:`.CursorResult.returns_rows` - attribute specific to
| :class:`.CursorResult` which indicates if the result is one that
| may return zero or more rows
|
| t
| Apply a "typed tuple" typing filter to returned rows.
|
| The :attr:`_engine.Result.t` attribute is a synonym for
| calling the :meth:`_engine.Result.tuples` method.
|
| .. versionadded:: 2.0
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'_attributes': 'util.immutabledict[Any, Any]', '_ro...
|
| __orig_bases__ = (<class 'sqlalchemy.engine.result._WithKeys'>, sqlalc...
|
| __parameters__ = (~_TP,)
|
| ----------------------------------------------------------------------
| Methods inherited from _WithKeys:
|
| keys(self) -> 'RMKeyView'
| Return an iterable view which yields the string keys that would
| be represented by each :class:`_engine.Row`.
|
| The keys can represent the labels of the columns returned by a core
| statement or the names of the orm classes returned by an orm
| execution.
|
| The view also can be tested for key containment using the Python
| ``in`` operator, which will test both for the string keys represented
| in the view, as well as for alternate keys such as column objects.
|
| .. versionchanged:: 1.4 a key view object is returned rather than a
| plain list.
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_instancemethod(fn: '_F') -> '_F'
| Decorate a method memoize its return value.
|
| :meta private:
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_attribute = <class 'sqlalchemy.util.langhelpers.HasMemoized.m...
| A read-only @property that is only evaluated once.
|
| :meta private:
|
|
| ----------------------------------------------------------------------
| Class methods inherited from typing.Generic:
|
| __class_getitem__(...)
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__(...)
| Function to initialize subclasses.
sqlalchemy.ResultProxy
Python Library Documentation: class CursorResult in module sqlalchemy.engine.cursor
class CursorResult(sqlalchemy.engine.result.Result)
| CursorResult(context: 'DefaultExecutionContext', cursor_strategy: 'ResultFetchStrategy', cursor_description: 'Optional[_DBAPICursorDescription]')
|
| A Result that is representing state from a DBAPI cursor.
|
| .. versionchanged:: 1.4 The :class:`.CursorResult``
| class replaces the previous :class:`.ResultProxy` interface.
| This classes are based on the :class:`.Result` calling API
| which provides an updated usage model and calling facade for
| SQLAlchemy Core and SQLAlchemy ORM.
|
| Returns database rows via the :class:`.Row` class, which provides
| additional API features and behaviors on top of the raw data returned by
| the DBAPI. Through the use of filters such as the :meth:`.Result.scalars`
| method, other kinds of objects may also be returned.
|
| .. seealso::
|
| :ref:`tutorial_selecting_data` - introductory material for accessing
| :class:`_engine.CursorResult` and :class:`.Row` objects.
|
| Method resolution order:
| CursorResult
| sqlalchemy.engine.result.Result
| sqlalchemy.engine.result._WithKeys
| sqlalchemy.engine.result.ResultInternal
| sqlalchemy.sql.base.InPlaceGenerative
| sqlalchemy.util.langhelpers.HasMemoized
| typing.Generic
| builtins.object
|
| Methods defined here:
|
| __init__(self, context: 'DefaultExecutionContext', cursor_strategy: 'ResultFetchStrategy', cursor_description: 'Optional[_DBAPICursorDescription]')
| Initialize self. See help(type(self)) for accurate signature.
|
| close(self) -> 'None'
| Close this :class:`_engine.CursorResult`.
|
| This closes out the underlying DBAPI cursor corresponding to the
| statement execution, if one is still present. Note that the DBAPI
| cursor is automatically released when the :class:`_engine.CursorResult`
| exhausts all available rows. :meth:`_engine.CursorResult.close` is
| generally an optional method except in the case when discarding a
| :class:`_engine.CursorResult` that still has additional rows pending
| for fetch.
|
| After this method is called, it is no longer valid to call upon
| the fetch methods, which will raise a :class:`.ResourceClosedError`
| on subsequent use.
|
| .. seealso::
|
| :ref:`connections_toplevel`
|
| last_inserted_params(self) -> 'Union[List[_MutableCoreSingleExecuteParams], _MutableCoreSingleExecuteParams]'
| Return the collection of inserted parameters from this
| execution.
|
| Raises :class:`~sqlalchemy.exc.InvalidRequestError` if the executed
| statement is not a compiled expression construct
| or is not an insert() construct.
|
| last_updated_params(self) -> 'Union[List[_MutableCoreSingleExecuteParams], _MutableCoreSingleExecuteParams]'
| Return the collection of updated parameters from this
| execution.
|
| Raises :class:`~sqlalchemy.exc.InvalidRequestError` if the executed
| statement is not a compiled expression construct
| or is not an update() construct.
|
| lastrow_has_defaults(self) -> 'bool'
| Return ``lastrow_has_defaults()`` from the underlying
| :class:`.ExecutionContext`.
|
| See :class:`.ExecutionContext` for details.
|
| merge(self, *others: 'Result[Any]') -> 'MergedResult[Any]'
| Merge this :class:`_engine.Result` with other compatible result
| objects.
|
| The object returned is an instance of :class:`_engine.MergedResult`,
| which will be composed of iterators from the given result
| objects.
|
| The new result will use the metadata from this result object.
| The subsequent result objects must be against an identical
| set of result / cursor metadata, otherwise the behavior is
| undefined.
|
| postfetch_cols(self) -> 'Optional[Sequence[Column[Any]]]'
| Return ``postfetch_cols()`` from the underlying
| :class:`.ExecutionContext`.
|
| See :class:`.ExecutionContext` for details.
|
| Raises :class:`~sqlalchemy.exc.InvalidRequestError` if the executed
| statement is not a compiled expression construct
| or is not an insert() or update() construct.
|
| prefetch_cols(self) -> 'Optional[Sequence[Column[Any]]]'
| Return ``prefetch_cols()`` from the underlying
| :class:`.ExecutionContext`.
|
| See :class:`.ExecutionContext` for details.
|
| Raises :class:`~sqlalchemy.exc.InvalidRequestError` if the executed
| statement is not a compiled expression construct
| or is not an insert() or update() construct.
|
| rowcount(...)
| Return the 'rowcount' for this result.
|
| The primary purpose of 'rowcount' is to report the number of rows
| matched by the WHERE criterion of an UPDATE or DELETE statement
| executed once (i.e. for a single parameter set), which may then be
| compared to the number of rows expected to be updated or deleted as a
| means of asserting data integrity.
|
| This attribute is transferred from the ``cursor.rowcount`` attribute
| of the DBAPI before the cursor is closed, to support DBAPIs that
| don't make this value available after cursor close. Some DBAPIs may
| offer meaningful values for other kinds of statements, such as INSERT
| and SELECT statements as well. In order to retrieve ``cursor.rowcount``
| for these statements, set the
| :paramref:`.Connection.execution_options.preserve_rowcount`
| execution option to True, which will cause the ``cursor.rowcount``
| value to be unconditionally memoized before any results are returned
| or the cursor is closed, regardless of statement type.
|
| For cases where the DBAPI does not support rowcount for a particular
| kind of statement and/or execution, the returned value will be ``-1``,
| which is delivered directly from the DBAPI and is part of :pep:`249`.
| All DBAPIs should support rowcount for single-parameter-set
| UPDATE and DELETE statements, however.
|
| .. note::
|
| Notes regarding :attr:`_engine.CursorResult.rowcount`:
|
|
| * This attribute returns the number of rows *matched*,
| which is not necessarily the same as the number of rows
| that were actually *modified*. For example, an UPDATE statement
| may have no net change on a given row if the SET values
| given are the same as those present in the row already.
| Such a row would be matched but not modified.
| On backends that feature both styles, such as MySQL,
| rowcount is configured to return the match
| count in all cases.
|
| * :attr:`_engine.CursorResult.rowcount` in the default case is
| *only* useful in conjunction with an UPDATE or DELETE statement,
| and only with a single set of parameters. For other kinds of
| statements, SQLAlchemy will not attempt to pre-memoize the value
| unless the
| :paramref:`.Connection.execution_options.preserve_rowcount`
| execution option is used. Note that contrary to :pep:`249`, many
| DBAPIs do not support rowcount values for statements that are not
| UPDATE or DELETE, particularly when rows are being returned which
| are not fully pre-buffered. DBAPIs that dont support rowcount
| for a particular kind of statement should return the value ``-1``
| for such statements.
|
| * :attr:`_engine.CursorResult.rowcount` may not be meaningful
| when executing a single statement with multiple parameter sets
| (i.e. an :term:`executemany`). Most DBAPIs do not sum "rowcount"
| values across multiple parameter sets and will return ``-1``
| when accessed.
|
| * SQLAlchemy's :ref:`engine_insertmanyvalues` feature does support
| a correct population of :attr:`_engine.CursorResult.rowcount`
| when the :paramref:`.Connection.execution_options.preserve_rowcount`
| execution option is set to True.
|
| * Statements that use RETURNING may not support rowcount, returning
| a ``-1`` value instead.
|
| .. seealso::
|
| :ref:`tutorial_update_delete_rowcount` - in the :ref:`unified_tutorial`
|
| :paramref:`.Connection.execution_options.preserve_rowcount`
|
| splice_horizontally(self, other: 'CursorResult[Any]') -> 'Self'
| Return a new :class:`.CursorResult` that "horizontally splices"
| together the rows of this :class:`.CursorResult` with that of another
| :class:`.CursorResult`.
|
| .. tip:: This method is for the benefit of the SQLAlchemy ORM and is
| not intended for general use.
|
| "horizontally splices" means that for each row in the first and second
| result sets, a new row that concatenates the two rows together is
| produced, which then becomes the new row. The incoming
| :class:`.CursorResult` must have the identical number of rows. It is
| typically expected that the two result sets come from the same sort
| order as well, as the result rows are spliced together based on their
| position in the result.
|
| The expected use case here is so that multiple INSERT..RETURNING
| statements (which definitely need to be sorted) against different
| tables can produce a single result that looks like a JOIN of those two
| tables.
|
| E.g.::
|
| r1 = connection.execute(
| users.insert().returning(
| users.c.user_name, users.c.user_id, sort_by_parameter_order=True
| ),
| user_values,
| )
|
| r2 = connection.execute(
| addresses.insert().returning(
| addresses.c.address_id,
| addresses.c.address,
| addresses.c.user_id,
| sort_by_parameter_order=True,
| ),
| address_values,
| )
|
| rows = r1.splice_horizontally(r2).all()
| assert rows == [
| ("john", 1, 1, "foo@bar.com", 1),
| ("jack", 2, 2, "bar@bat.com", 2),
| ]
|
| .. versionadded:: 2.0
|
| .. seealso::
|
| :meth:`.CursorResult.splice_vertically`
|
| splice_vertically(self, other: 'CursorResult[Any]') -> 'Self'
| Return a new :class:`.CursorResult` that "vertically splices",
| i.e. "extends", the rows of this :class:`.CursorResult` with that of
| another :class:`.CursorResult`.
|
| .. tip:: This method is for the benefit of the SQLAlchemy ORM and is
| not intended for general use.
|
| "vertically splices" means the rows of the given result are appended to
| the rows of this cursor result. The incoming :class:`.CursorResult`
| must have rows that represent the identical list of columns in the
| identical order as they are in this :class:`.CursorResult`.
|
| .. versionadded:: 2.0
|
| .. seealso::
|
| :meth:`.CursorResult.splice_horizontally`
|
| supports_sane_multi_rowcount(self) -> 'bool'
| Return ``supports_sane_multi_rowcount`` from the dialect.
|
| See :attr:`_engine.CursorResult.rowcount` for background.
|
| supports_sane_rowcount(self) -> 'bool'
| Return ``supports_sane_rowcount`` from the dialect.
|
| See :attr:`_engine.CursorResult.rowcount` for background.
|
| yield_per(self, num: 'int') -> 'Self'
| Configure the row-fetching strategy to fetch ``num`` rows at a time.
|
| This impacts the underlying behavior of the result when iterating over
| the result object, or otherwise making use of methods such as
| :meth:`_engine.Result.fetchone` that return one row at a time. Data
| from the underlying cursor or other data source will be buffered up to
| this many rows in memory, and the buffered collection will then be
| yielded out one row at a time or as many rows are requested. Each time
| the buffer clears, it will be refreshed to this many rows or as many
| rows remain if fewer remain.
|
| The :meth:`_engine.Result.yield_per` method is generally used in
| conjunction with the
| :paramref:`_engine.Connection.execution_options.stream_results`
| execution option, which will allow the database dialect in use to make
| use of a server side cursor, if the DBAPI supports a specific "server
| side cursor" mode separate from its default mode of operation.
|
| .. tip::
|
| Consider using the
| :paramref:`_engine.Connection.execution_options.yield_per`
| execution option, which will simultaneously set
| :paramref:`_engine.Connection.execution_options.stream_results`
| to ensure the use of server side cursors, as well as automatically
| invoke the :meth:`_engine.Result.yield_per` method to establish
| a fixed row buffer size at once.
|
| The :paramref:`_engine.Connection.execution_options.yield_per`
| execution option is available for ORM operations, with
| :class:`_orm.Session`-oriented use described at
| :ref:`orm_queryguide_yield_per`. The Core-only version which works
| with :class:`_engine.Connection` is new as of SQLAlchemy 1.4.40.
|
| .. versionadded:: 1.4
|
| :param num: number of rows to fetch each time the buffer is refilled.
| If set to a value below 1, fetches all rows for the next buffer.
|
| .. seealso::
|
| :ref:`engine_stream_results` - describes Core behavior for
| :meth:`_engine.Result.yield_per`
|
| :ref:`orm_queryguide_yield_per` - in the :ref:`queryguide_toplevel`
|
| ----------------------------------------------------------------------
| Readonly properties defined here:
|
| inserted_primary_key
| Return the primary key for the row just inserted.
|
| The return value is a :class:`_result.Row` object representing
| a named tuple of primary key values in the order in which the
| primary key columns are configured in the source
| :class:`_schema.Table`.
|
| .. versionchanged:: 1.4.8 - the
| :attr:`_engine.CursorResult.inserted_primary_key`
| value is now a named tuple via the :class:`_result.Row` class,
| rather than a plain tuple.
|
| This accessor only applies to single row :func:`_expression.insert`
| constructs which did not explicitly specify
| :meth:`_expression.Insert.returning`. Support for multirow inserts,
| while not yet available for most backends, would be accessed using
| the :attr:`_engine.CursorResult.inserted_primary_key_rows` accessor.
|
| Note that primary key columns which specify a server_default clause, or
| otherwise do not qualify as "autoincrement" columns (see the notes at
| :class:`_schema.Column`), and were generated using the database-side
| default, will appear in this list as ``None`` unless the backend
| supports "returning" and the insert statement executed with the
| "implicit returning" enabled.
|
| Raises :class:`~sqlalchemy.exc.InvalidRequestError` if the executed
| statement is not a compiled expression construct
| or is not an insert() construct.
|
| inserted_primary_key_rows
| Return the value of
| :attr:`_engine.CursorResult.inserted_primary_key`
| as a row contained within a list; some dialects may support a
| multiple row form as well.
|
| .. note:: As indicated below, in current SQLAlchemy versions this
| accessor is only useful beyond what's already supplied by
| :attr:`_engine.CursorResult.inserted_primary_key` when using the
| :ref:`postgresql_psycopg2` dialect. Future versions hope to
| generalize this feature to more dialects.
|
| This accessor is added to support dialects that offer the feature
| that is currently implemented by the :ref:`psycopg2_executemany_mode`
| feature, currently **only the psycopg2 dialect**, which provides
| for many rows to be INSERTed at once while still retaining the
| behavior of being able to return server-generated primary key values.
|
| * **When using the psycopg2 dialect, or other dialects that may support
| "fast executemany" style inserts in upcoming releases** : When
| invoking an INSERT statement while passing a list of rows as the
| second argument to :meth:`_engine.Connection.execute`, this accessor
| will then provide a list of rows, where each row contains the primary
| key value for each row that was INSERTed.
|
| * **When using all other dialects / backends that don't yet support
| this feature**: This accessor is only useful for **single row INSERT
| statements**, and returns the same information as that of the
| :attr:`_engine.CursorResult.inserted_primary_key` within a
| single-element list. When an INSERT statement is executed in
| conjunction with a list of rows to be INSERTed, the list will contain
| one row per row inserted in the statement, however it will contain
| ``None`` for any server-generated values.
|
| Future releases of SQLAlchemy will further generalize the
| "fast execution helper" feature of psycopg2 to suit other dialects,
| thus allowing this accessor to be of more general use.
|
| .. versionadded:: 1.4
|
| .. seealso::
|
| :attr:`_engine.CursorResult.inserted_primary_key`
|
| is_insert
| True if this :class:`_engine.CursorResult` is the result
| of a executing an expression language compiled
| :func:`_expression.insert` construct.
|
| When True, this implies that the
| :attr:`inserted_primary_key` attribute is accessible,
| assuming the statement did not include
| a user defined "returning" construct.
|
| lastrowid
| Return the 'lastrowid' accessor on the DBAPI cursor.
|
| This is a DBAPI specific method and is only functional
| for those backends which support it, for statements
| where it is appropriate. It's behavior is not
| consistent across backends.
|
| Usage of this method is normally unnecessary when
| using insert() expression constructs; the
| :attr:`~CursorResult.inserted_primary_key` attribute provides a
| tuple of primary key values for a newly inserted row,
| regardless of database backend.
|
| returned_defaults
| Return the values of default columns that were fetched using
| the :meth:`.ValuesBase.return_defaults` feature.
|
| The value is an instance of :class:`.Row`, or ``None``
| if :meth:`.ValuesBase.return_defaults` was not used or if the
| backend does not support RETURNING.
|
| .. seealso::
|
| :meth:`.ValuesBase.return_defaults`
|
| returned_defaults_rows
| Return a list of rows each containing the values of default
| columns that were fetched using
| the :meth:`.ValuesBase.return_defaults` feature.
|
| The return value is a list of :class:`.Row` objects.
|
| .. versionadded:: 1.4
|
| returns_rows
| True if this :class:`_engine.CursorResult` returns zero or more
| rows.
|
| I.e. if it is legal to call the methods
| :meth:`_engine.CursorResult.fetchone`,
| :meth:`_engine.CursorResult.fetchmany`
| :meth:`_engine.CursorResult.fetchall`.
|
| Overall, the value of :attr:`_engine.CursorResult.returns_rows` should
| always be synonymous with whether or not the DBAPI cursor had a
| ``.description`` attribute, indicating the presence of result columns,
| noting that a cursor that returns zero rows still has a
| ``.description`` if a row-returning statement was emitted.
|
| This attribute should be True for all results that are against
| SELECT statements, as well as for DML statements INSERT/UPDATE/DELETE
| that use RETURNING. For INSERT/UPDATE/DELETE statements that were
| not using RETURNING, the value will usually be False, however
| there are some dialect-specific exceptions to this, such as when
| using the MSSQL / pyodbc dialect a SELECT is emitted inline in
| order to retrieve an inserted primary key value.
|
| .. seealso::
|
| :meth:`.Result.close`
|
| :attr:`.Result.closed`
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| connection
|
| context
|
| cursor
|
| cursor_strategy
|
| dialect
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'_metadata': 'Union[CursorResultMetaData, _NoResult...
|
| __orig_bases__ = (sqlalchemy.engine.result.Result[~_T],)
|
| __parameters__ = (~_T,)
|
| closed = False
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.engine.result.Result:
|
| __enter__(self) -> 'Self'
|
| __exit__(self, type_: 'Any', value: 'Any', traceback: 'Any') -> 'None'
|
| __iter__(self) -> 'Iterator[Row[_TP]]'
|
| __next__(self) -> 'Row[_TP]'
|
| all(self) -> 'Sequence[Row[_TP]]'
| Return all rows in a sequence.
|
| Closes the result set after invocation. Subsequent invocations
| will return an empty sequence.
|
| .. versionadded:: 1.4
|
| :return: a sequence of :class:`_engine.Row` objects.
|
| .. seealso::
|
| :ref:`engine_stream_results` - How to stream a large result set
| without loading it completely in python.
|
| columns(self, *col_expressions: '_KeyIndexType') -> 'Self'
| Establish the columns that should be returned in each row.
|
| This method may be used to limit the columns returned as well
| as to reorder them. The given list of expressions are normally
| a series of integers or string key names. They may also be
| appropriate :class:`.ColumnElement` objects which correspond to
| a given statement construct.
|
| .. versionchanged:: 2.0 Due to a bug in 1.4, the
| :meth:`_engine.Result.columns` method had an incorrect behavior
| where calling upon the method with just one index would cause the
| :class:`_engine.Result` object to yield scalar values rather than
| :class:`_engine.Row` objects. In version 2.0, this behavior
| has been corrected such that calling upon
| :meth:`_engine.Result.columns` with a single index will
| produce a :class:`_engine.Result` object that continues
| to yield :class:`_engine.Row` objects, which include
| only a single column.
|
| E.g.::
|
| statement = select(table.c.x, table.c.y, table.c.z)
| result = connection.execute(statement)
|
| for z, y in result.columns("z", "y"):
| ...
|
| Example of using the column objects from the statement itself::
|
| for z, y in result.columns(
| statement.selected_columns.c.z, statement.selected_columns.c.y
| ):
| ...
|
| .. versionadded:: 1.4
|
| :param \*col_expressions: indicates columns to be returned. Elements
| may be integer row indexes, string column names, or appropriate
| :class:`.ColumnElement` objects corresponding to a select construct.
|
| :return: this :class:`_engine.Result` object with the modifications
| given.
|
| fetchall(self) -> 'Sequence[Row[_TP]]'
| A synonym for the :meth:`_engine.Result.all` method.
|
| fetchmany(self, size: 'Optional[int]' = None) -> 'Sequence[Row[_TP]]'
| Fetch many rows.
|
| When all rows are exhausted, returns an empty sequence.
|
| This method is provided for backwards compatibility with
| SQLAlchemy 1.x.x.
|
| To fetch rows in groups, use the :meth:`_engine.Result.partitions`
| method.
|
| :return: a sequence of :class:`_engine.Row` objects.
|
| .. seealso::
|
| :meth:`_engine.Result.partitions`
|
| fetchone(self) -> 'Optional[Row[_TP]]'
| Fetch one row.
|
| When all rows are exhausted, returns None.
|
| This method is provided for backwards compatibility with
| SQLAlchemy 1.x.x.
|
| To fetch the first row of a result only, use the
| :meth:`_engine.Result.first` method. To iterate through all
| rows, iterate the :class:`_engine.Result` object directly.
|
| :return: a :class:`_engine.Row` object if no filters are applied,
| or ``None`` if no rows remain.
|
| first(self) -> 'Optional[Row[_TP]]'
| Fetch the first row or ``None`` if no row is present.
|
| Closes the result set and discards remaining rows.
|
| .. note:: This method returns one **row**, e.g. tuple, by default.
| To return exactly one single scalar value, that is, the first
| column of the first row, use the
| :meth:`_engine.Result.scalar` method,
| or combine :meth:`_engine.Result.scalars` and
| :meth:`_engine.Result.first`.
|
| Additionally, in contrast to the behavior of the legacy ORM
| :meth:`_orm.Query.first` method, **no limit is applied** to the
| SQL query which was invoked to produce this
| :class:`_engine.Result`;
| for a DBAPI driver that buffers results in memory before yielding
| rows, all rows will be sent to the Python process and all but
| the first row will be discarded.
|
| .. seealso::
|
| :ref:`migration_20_unify_select`
|
| :return: a :class:`_engine.Row` object, or None
| if no rows remain.
|
| .. seealso::
|
| :meth:`_engine.Result.scalar`
|
| :meth:`_engine.Result.one`
|
| freeze(self) -> 'FrozenResult[_TP]'
| Return a callable object that will produce copies of this
| :class:`_engine.Result` when invoked.
|
| The callable object returned is an instance of
| :class:`_engine.FrozenResult`.
|
| This is used for result set caching. The method must be called
| on the result when it has been unconsumed, and calling the method
| will consume the result fully. When the :class:`_engine.FrozenResult`
| is retrieved from a cache, it can be called any number of times where
| it will produce a new :class:`_engine.Result` object each time
| against its stored set of rows.
|
| .. seealso::
|
| :ref:`do_orm_execute_re_executing` - example usage within the
| ORM to implement a result-set cache.
|
| mappings(self) -> 'MappingResult'
| Apply a mappings filter to returned rows, returning an instance of
| :class:`_engine.MappingResult`.
|
| When this filter is applied, fetching rows will return
| :class:`_engine.RowMapping` objects instead of :class:`_engine.Row`
| objects.
|
| .. versionadded:: 1.4
|
| :return: a new :class:`_engine.MappingResult` filtering object
| referring to this :class:`_engine.Result` object.
|
| one(self) -> 'Row[_TP]'
| Return exactly one row or raise an exception.
|
| Raises :class:`_exc.NoResultFound` if the result returns no
| rows, or :class:`_exc.MultipleResultsFound` if multiple rows
| would be returned.
|
| .. note:: This method returns one **row**, e.g. tuple, by default.
| To return exactly one single scalar value, that is, the first
| column of the first row, use the
| :meth:`_engine.Result.scalar_one` method, or combine
| :meth:`_engine.Result.scalars` and
| :meth:`_engine.Result.one`.
|
| .. versionadded:: 1.4
|
| :return: The first :class:`_engine.Row`.
|
| :raises: :class:`.MultipleResultsFound`, :class:`.NoResultFound`
|
| .. seealso::
|
| :meth:`_engine.Result.first`
|
| :meth:`_engine.Result.one_or_none`
|
| :meth:`_engine.Result.scalar_one`
|
| one_or_none(self) -> 'Optional[Row[_TP]]'
| Return at most one result or raise an exception.
|
| Returns ``None`` if the result has no rows.
| Raises :class:`.MultipleResultsFound`
| if multiple rows are returned.
|
| .. versionadded:: 1.4
|
| :return: The first :class:`_engine.Row` or ``None`` if no row
| is available.
|
| :raises: :class:`.MultipleResultsFound`
|
| .. seealso::
|
| :meth:`_engine.Result.first`
|
| :meth:`_engine.Result.one`
|
| partitions(self, size: 'Optional[int]' = None) -> 'Iterator[Sequence[Row[_TP]]]'
| Iterate through sub-lists of rows of the size given.
|
| Each list will be of the size given, excluding the last list to
| be yielded, which may have a small number of rows. No empty
| lists will be yielded.
|
| The result object is automatically closed when the iterator
| is fully consumed.
|
| Note that the backend driver will usually buffer the entire result
| ahead of time unless the
| :paramref:`.Connection.execution_options.stream_results` execution
| option is used indicating that the driver should not pre-buffer
| results, if possible. Not all drivers support this option and
| the option is silently ignored for those who do not.
|
| When using the ORM, the :meth:`_engine.Result.partitions` method
| is typically more effective from a memory perspective when it is
| combined with use of the
| :ref:`yield_per execution option <orm_queryguide_yield_per>`,
| which instructs both the DBAPI driver to use server side cursors,
| if available, as well as instructs the ORM loading internals to only
| build a certain amount of ORM objects from a result at a time before
| yielding them out.
|
| .. versionadded:: 1.4
|
| :param size: indicate the maximum number of rows to be present
| in each list yielded. If None, makes use of the value set by
| the :meth:`_engine.Result.yield_per`, method, if it were called,
| or the :paramref:`_engine.Connection.execution_options.yield_per`
| execution option, which is equivalent in this regard. If
| yield_per weren't set, it makes use of the
| :meth:`_engine.Result.fetchmany` default, which may be backend
| specific and not well defined.
|
| :return: iterator of lists
|
| .. seealso::
|
| :ref:`engine_stream_results`
|
| :ref:`orm_queryguide_yield_per` - in the :ref:`queryguide_toplevel`
|
| scalar(self) -> 'Any'
| Fetch the first column of the first row, and close the result set.
|
| Returns ``None`` if there are no rows to fetch.
|
| No validation is performed to test if additional rows remain.
|
| After calling this method, the object is fully closed,
| e.g. the :meth:`_engine.CursorResult.close`
| method will have been called.
|
| :return: a Python scalar value, or ``None`` if no rows remain.
|
| scalar_one(self) -> 'Any'
| Return exactly one scalar result or raise an exception.
|
| This is equivalent to calling :meth:`_engine.Result.scalars` and
| then :meth:`_engine.ScalarResult.one`.
|
| .. seealso::
|
| :meth:`_engine.ScalarResult.one`
|
| :meth:`_engine.Result.scalars`
|
| scalar_one_or_none(self) -> 'Optional[Any]'
| Return exactly one scalar result or ``None``.
|
| This is equivalent to calling :meth:`_engine.Result.scalars` and
| then :meth:`_engine.ScalarResult.one_or_none`.
|
| .. seealso::
|
| :meth:`_engine.ScalarResult.one_or_none`
|
| :meth:`_engine.Result.scalars`
|
| scalars(self, index: '_KeyIndexType' = 0) -> 'ScalarResult[Any]'
| Return a :class:`_engine.ScalarResult` filtering object which
| will return single elements rather than :class:`_row.Row` objects.
|
| E.g.::
|
| >>> result = conn.execute(text("select int_id from table"))
| >>> result.scalars().all()
| [1, 2, 3]
|
| When results are fetched from the :class:`_engine.ScalarResult`
| filtering object, the single column-row that would be returned by the
| :class:`_engine.Result` is instead returned as the column's value.
|
| .. versionadded:: 1.4
|
| :param index: integer or row key indicating the column to be fetched
| from each row, defaults to ``0`` indicating the first column.
|
| :return: a new :class:`_engine.ScalarResult` filtering object referring
| to this :class:`_engine.Result` object.
|
| tuples(self) -> 'TupleResult[_TP]'
| Apply a "typed tuple" typing filter to returned rows.
|
| This method returns the same :class:`_engine.Result` object
| at runtime,
| however annotates as returning a :class:`_engine.TupleResult` object
| that will indicate to :pep:`484` typing tools that plain typed
| ``Tuple`` instances are returned rather than rows. This allows
| tuple unpacking and ``__getitem__`` access of :class:`_engine.Row`
| objects to by typed, for those cases where the statement invoked
| itself included typing information.
|
| .. versionadded:: 2.0
|
| :return: the :class:`_engine.TupleResult` type at typing time.
|
| .. seealso::
|
| :attr:`_engine.Result.t` - shorter synonym
|
| :attr:`_engine.Row._t` - :class:`_engine.Row` version
|
| unique(self, strategy: 'Optional[_UniqueFilterType]' = None) -> 'Self'
| Apply unique filtering to the objects returned by this
| :class:`_engine.Result`.
|
| When this filter is applied with no arguments, the rows or objects
| returned will filtered such that each row is returned uniquely. The
| algorithm used to determine this uniqueness is by default the Python
| hashing identity of the whole tuple. In some cases a specialized
| per-entity hashing scheme may be used, such as when using the ORM, a
| scheme is applied which works against the primary key identity of
| returned objects.
|
| The unique filter is applied **after all other filters**, which means
| if the columns returned have been refined using a method such as the
| :meth:`_engine.Result.columns` or :meth:`_engine.Result.scalars`
| method, the uniquing is applied to **only the column or columns
| returned**. This occurs regardless of the order in which these
| methods have been called upon the :class:`_engine.Result` object.
|
| The unique filter also changes the calculus used for methods like
| :meth:`_engine.Result.fetchmany` and :meth:`_engine.Result.partitions`.
| When using :meth:`_engine.Result.unique`, these methods will continue
| to yield the number of rows or objects requested, after uniquing
| has been applied. However, this necessarily impacts the buffering
| behavior of the underlying cursor or datasource, such that multiple
| underlying calls to ``cursor.fetchmany()`` may be necessary in order
| to accumulate enough objects in order to provide a unique collection
| of the requested size.
|
| :param strategy: a callable that will be applied to rows or objects
| being iterated, which should return an object that represents the
| unique value of the row. A Python ``set()`` is used to store
| these identities. If not passed, a default uniqueness strategy
| is used which may have been assembled by the source of this
| :class:`_engine.Result` object.
|
| ----------------------------------------------------------------------
| Readonly properties inherited from sqlalchemy.engine.result.Result:
|
| t
| Apply a "typed tuple" typing filter to returned rows.
|
| The :attr:`_engine.Result.t` attribute is a synonym for
| calling the :meth:`_engine.Result.tuples` method.
|
| .. versionadded:: 2.0
|
| ----------------------------------------------------------------------
| Data descriptors inherited from sqlalchemy.engine.result.Result:
|
| __dict__
| dictionary for instance variables
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.engine.result._WithKeys:
|
| keys(self) -> 'RMKeyView'
| Return an iterable view which yields the string keys that would
| be represented by each :class:`_engine.Row`.
|
| The keys can represent the labels of the columns returned by a core
| statement or the names of the orm classes returned by an orm
| execution.
|
| The view also can be tested for key containment using the Python
| ``in`` operator, which will test both for the string keys represented
| in the view, as well as for alternate keys such as column objects.
|
| .. versionchanged:: 1.4 a key view object is returned rather than a
| plain list.
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_instancemethod(fn: '_F') -> '_F'
| Decorate a method memoize its return value.
|
| :meta private:
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_attribute = <class 'sqlalchemy.util.langhelpers.HasMemoized.m...
| A read-only @property that is only evaluated once.
|
| :meta private:
|
|
| ----------------------------------------------------------------------
| Class methods inherited from typing.Generic:
|
| __class_getitem__(...)
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__(...)
| Function to initialize subclasses.
sqlalchemy.ReturnsRows
Python Library Documentation: class ReturnsRows in module sqlalchemy.sql.selectable
class ReturnsRows(sqlalchemy.sql.roles.ReturnsRowsRole, sqlalchemy.sql.elements.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
|
| Method resolution order:
| ReturnsRows
| sqlalchemy.sql.roles.ReturnsRowsRole
| sqlalchemy.sql.roles.SQLRole
| sqlalchemy.sql.elements.DQLDMLClauseElement
| sqlalchemy.sql.elements.ClauseElement
| sqlalchemy.sql.annotation.SupportsWrappingAnnotations
| sqlalchemy.sql.annotation.SupportsAnnotations
| sqlalchemy.sql.cache_key.MemoizedHasCacheKey
| sqlalchemy.sql.cache_key.HasCacheKey
| sqlalchemy.util.langhelpers.HasMemoized
| sqlalchemy.sql.traversals.HasCopyInternals
| sqlalchemy.sql.visitors.ExternallyTraversible
| sqlalchemy.sql.visitors.HasTraverseInternals
| sqlalchemy.sql.elements.CompilerElement
| sqlalchemy.sql.visitors.Visitable
| builtins.object
|
| Methods defined here:
|
| 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.
|
| ----------------------------------------------------------------------
| Readonly properties defined here:
|
| exported_columns
| 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`
|
| selectable
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.SQLRole:
|
| allows_lambda = False
|
| uses_inspection = False
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.elements.ClauseElement:
|
| __bool__(self)
|
| __getstate__(self)
| Helper for pickle.
|
| __invert__(self)
|
| __repr__(self)
| Return repr(self).
|
| compare(self, other: 'ClauseElement', **kw: 'Any') -> 'bool'
| Compare this :class:`_expression.ClauseElement` to
| the given :class:`_expression.ClauseElement`.
|
| Subclasses should override the default behavior, which is a
| straight identity comparison.
|
| \**kw are arguments consumed by subclass ``compare()`` methods and
| may be used to modify the criteria for comparison
| (see :class:`_expression.ColumnElement`).
|
| description(...)
|
| entity_namespace(...)
|
| params(self, _ClauseElement__optionaldict: 'Optional[Mapping[str, Any]]' = None, **kwargs: 'Any') -> 'Self'
| Return a copy with :func:`_expression.bindparam` elements
| replaced.
|
| Returns a copy of this ClauseElement with
| :func:`_expression.bindparam`
| elements replaced with values taken from the given dictionary::
|
| >>> clause = column("x") + bindparam("foo")
| >>> print(clause.compile().params)
| {'foo':None}
| >>> print(clause.params({"foo": 7}).compile().params)
| {'foo':7}
|
| self_group(self, against: 'Optional[OperatorType]' = None) -> 'ClauseElement'
| 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.
|
| unique_params(self, _ClauseElement__optionaldict: 'Optional[Dict[str, Any]]' = None, **kwargs: 'Any') -> 'Self'
| Return a copy with :func:`_expression.bindparam` elements
| replaced.
|
| Same functionality as :meth:`_expression.ClauseElement.params`,
| except adds `unique=True`
| to affected bind parameters so that multiple statements can be
| used.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.elements.ClauseElement:
|
| __visit_name__ = 'clause'
|
| is_clause_element = True
|
| is_dml = False
|
| is_selectable = False
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.cache_key.HasCacheKey:
|
| inherit_cache = None
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_instancemethod(fn: '_F') -> '_F'
| Decorate a method memoize its return value.
|
| :meta private:
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_attribute = <class 'sqlalchemy.util.langhelpers.HasMemoized.m...
| A read-only @property that is only evaluated once.
|
| :meta private:
|
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.visitors.HasTraverseInternals:
|
| get_children(self, *, omit_attrs: 'Tuple[str, ...]' = (), **kw: 'Any') -> 'Iterable[HasTraverseInternals]'
| Return immediate child :class:`.visitors.HasTraverseInternals`
| elements of this :class:`.visitors.HasTraverseInternals`.
|
| This is used for visit traversal.
|
| \**kw may contain flags that change the collection that is
| returned, for example to return a subset of items in order to
| cut down on larger traversals, or to return child items from a
| different context (such as schema-level collections instead of
| clause-level).
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.elements.CompilerElement:
|
| __str__(self) -> 'str'
| Return str(self).
|
| compile(self, bind: 'Optional[_HasDialect]' = None, dialect: 'Optional[Dialect]' = None, **kw: 'Any') -> 'Compiled'
| Compile this SQL expression.
|
| The return value is a :class:`~.Compiled` object.
| Calling ``str()`` or ``unicode()`` on the returned value will yield a
| string representation of the result. The
| :class:`~.Compiled` object also can return a
| dictionary of bind parameter names and values
| using the ``params`` accessor.
|
| :param bind: An :class:`.Connection` or :class:`.Engine` which
| can provide a :class:`.Dialect` in order to generate a
| :class:`.Compiled` object. If the ``bind`` and
| ``dialect`` parameters are both omitted, a default SQL compiler
| is used.
|
| :param column_keys: Used for INSERT and UPDATE statements, a list of
| column names which should be present in the VALUES clause of the
| compiled statement. If ``None``, all columns from the target table
| object are rendered.
|
| :param dialect: A :class:`.Dialect` instance which can generate
| a :class:`.Compiled` object. This argument takes precedence over
| the ``bind`` argument.
|
| :param compile_kwargs: optional dictionary of additional parameters
| that will be passed through to the compiler within all "visit"
| methods. This allows any custom flag to be passed through to
| a custom compilation construct, for example. It is also used
| for the case of passing the ``literal_binds`` flag through::
|
| from sqlalchemy.sql import table, column, select
|
| t = table("t", column("x"))
|
| s = select(t).where(t.c.x == 5)
|
| print(s.compile(compile_kwargs={"literal_binds": True}))
|
| .. seealso::
|
| :ref:`faq_sql_expression_string`
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.elements.CompilerElement:
|
| stringify_dialect = 'default'
|
| supports_execution = False
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.visitors.Visitable:
|
| __class_getitem__(key: 'Any') -> 'Any'
|
| __init_subclass__() -> 'None'
| This method is called when a class is subclassed.
|
| The default implementation does nothing. It may be
| overridden to extend subclasses.
sqlalchemy.RollbackToSavepointClause
Python Library Documentation: class RollbackToSavepointClause in module sqlalchemy.sql.elements
class RollbackToSavepointClause(_IdentifiedClause)
| RollbackToSavepointClause(ident)
|
| Method resolution order:
| RollbackToSavepointClause
| _IdentifiedClause
| sqlalchemy.sql.base.Executable
| sqlalchemy.sql.roles.StatementRole
| sqlalchemy.sql.roles.SQLRole
| ClauseElement
| sqlalchemy.sql.annotation.SupportsWrappingAnnotations
| sqlalchemy.sql.annotation.SupportsAnnotations
| sqlalchemy.sql.cache_key.MemoizedHasCacheKey
| sqlalchemy.sql.cache_key.HasCacheKey
| sqlalchemy.util.langhelpers.HasMemoized
| sqlalchemy.sql.traversals.HasCopyInternals
| sqlalchemy.sql.visitors.ExternallyTraversible
| sqlalchemy.sql.visitors.HasTraverseInternals
| CompilerElement
| sqlalchemy.sql.visitors.Visitable
| builtins.object
|
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| __visit_name__ = 'rollback_to_savepoint'
|
| inherit_cache = False
|
| ----------------------------------------------------------------------
| Methods inherited from _IdentifiedClause:
|
| __init__(self, ident)
| Initialize self. See help(type(self)) for accurate signature.
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.base.Executable:
|
| execution_options(self, **kw: 'Any') -> 'Self'
| Set non-SQL options for the statement which take effect during
| execution.
|
| Execution options can be set at many scopes, including per-statement,
| per-connection, or per execution, using methods such as
| :meth:`_engine.Connection.execution_options` and parameters which
| accept a dictionary of options such as
| :paramref:`_engine.Connection.execute.execution_options` and
| :paramref:`_orm.Session.execute.execution_options`.
|
| The primary characteristic of an execution option, as opposed to
| other kinds of options such as ORM loader options, is that
| **execution options never affect the compiled SQL of a query, only
| things that affect how the SQL statement itself is invoked or how
| results are fetched**. That is, execution options are not part of
| what's accommodated by SQL compilation nor are they considered part of
| the cached state of a statement.
|
| The :meth:`_sql.Executable.execution_options` method is
| :term:`generative`, as
| is the case for the method as applied to the :class:`_engine.Engine`
| and :class:`_orm.Query` objects, which means when the method is called,
| a copy of the object is returned, which applies the given parameters to
| that new copy, but leaves the original unchanged::
|
| statement = select(table.c.x, table.c.y)
| new_statement = statement.execution_options(my_option=True)
|
| An exception to this behavior is the :class:`_engine.Connection`
| object, where the :meth:`_engine.Connection.execution_options` method
| is explicitly **not** generative.
|
| The kinds of options that may be passed to
| :meth:`_sql.Executable.execution_options` and other related methods and
| parameter dictionaries include parameters that are explicitly consumed
| by SQLAlchemy Core or ORM, as well as arbitrary keyword arguments not
| defined by SQLAlchemy, which means the methods and/or parameter
| dictionaries may be used for user-defined parameters that interact with
| custom code, which may access the parameters using methods such as
| :meth:`_sql.Executable.get_execution_options` and
| :meth:`_engine.Connection.get_execution_options`, or within selected
| event hooks using a dedicated ``execution_options`` event parameter
| such as
| :paramref:`_events.ConnectionEvents.before_execute.execution_options`
| or :attr:`_orm.ORMExecuteState.execution_options`, e.g.::
|
| from sqlalchemy import event
|
|
| @event.listens_for(some_engine, "before_execute")
| def _process_opt(conn, statement, multiparams, params, execution_options):
| "run a SQL function before invoking a statement"
|
| if execution_options.get("do_special_thing", False):
| conn.exec_driver_sql("run_special_function()")
|
| Within the scope of options that are explicitly recognized by
| SQLAlchemy, most apply to specific classes of objects and not others.
| The most common execution options include:
|
| * :paramref:`_engine.Connection.execution_options.isolation_level` -
| sets the isolation level for a connection or a class of connections
| via an :class:`_engine.Engine`. This option is accepted only
| by :class:`_engine.Connection` or :class:`_engine.Engine`.
|
| * :paramref:`_engine.Connection.execution_options.stream_results` -
| indicates results should be fetched using a server side cursor;
| this option is accepted by :class:`_engine.Connection`, by the
| :paramref:`_engine.Connection.execute.execution_options` parameter
| on :meth:`_engine.Connection.execute`, and additionally by
| :meth:`_sql.Executable.execution_options` on a SQL statement object,
| as well as by ORM constructs like :meth:`_orm.Session.execute`.
|
| * :paramref:`_engine.Connection.execution_options.compiled_cache` -
| indicates a dictionary that will serve as the
| :ref:`SQL compilation cache <sql_caching>`
| for a :class:`_engine.Connection` or :class:`_engine.Engine`, as
| well as for ORM methods like :meth:`_orm.Session.execute`.
| Can be passed as ``None`` to disable caching for statements.
| This option is not accepted by
| :meth:`_sql.Executable.execution_options` as it is inadvisable to
| carry along a compilation cache within a statement object.
|
| * :paramref:`_engine.Connection.execution_options.schema_translate_map`
| - a mapping of schema names used by the
| :ref:`Schema Translate Map <schema_translating>` feature, accepted
| by :class:`_engine.Connection`, :class:`_engine.Engine`,
| :class:`_sql.Executable`, as well as by ORM constructs
| like :meth:`_orm.Session.execute`.
|
| .. seealso::
|
| :meth:`_engine.Connection.execution_options`
|
| :paramref:`_engine.Connection.execute.execution_options`
|
| :paramref:`_orm.Session.execute.execution_options`
|
| :ref:`orm_queryguide_execution_options` - documentation on all
| ORM-specific execution options
|
| get_execution_options(self) -> '_ExecuteOptions'
| Get the non-SQL options which will take effect during execution.
|
| .. versionadded:: 1.3
|
| .. seealso::
|
| :meth:`.Executable.execution_options`
|
| options(self, *options: 'ExecutableOption') -> 'Self'
| Apply options to this statement.
|
| In the general sense, options are any kind of Python object
| that can be interpreted by the SQL compiler for the statement.
| These options can be consumed by specific dialects or specific kinds
| of compilers.
|
| The most commonly known kind of option are the ORM level options
| that apply "eager load" and other loading behaviors to an ORM
| query. However, options can theoretically be used for many other
| purposes.
|
| For background on specific kinds of options for specific kinds of
| statements, refer to the documentation for those option objects.
|
| .. versionchanged:: 1.4 - added :meth:`.Executable.options` to
| Core statement objects towards the goal of allowing unified
| Core / ORM querying capabilities.
|
| .. seealso::
|
| :ref:`loading_columns` - refers to options specific to the usage
| of ORM queries
|
| :ref:`relationship_loader_options` - refers to options specific
| to the usage of ORM queries
|
| ----------------------------------------------------------------------
| Data descriptors inherited from sqlalchemy.sql.base.Executable:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.base.Executable:
|
| is_delete = False
|
| is_dml = False
|
| is_from_statement = False
|
| is_insert = False
|
| is_select = False
|
| is_text = False
|
| is_update = False
|
| supports_execution = True
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.SQLRole:
|
| allows_lambda = False
|
| uses_inspection = False
|
| ----------------------------------------------------------------------
| Methods inherited from ClauseElement:
|
| __bool__(self)
|
| __getstate__(self)
| Helper for pickle.
|
| __invert__(self)
|
| __repr__(self)
| Return repr(self).
|
| compare(self, other: 'ClauseElement', **kw: 'Any') -> 'bool'
| Compare this :class:`_expression.ClauseElement` to
| the given :class:`_expression.ClauseElement`.
|
| Subclasses should override the default behavior, which is a
| straight identity comparison.
|
| \**kw are arguments consumed by subclass ``compare()`` methods and
| may be used to modify the criteria for comparison
| (see :class:`_expression.ColumnElement`).
|
| description(...)
|
| entity_namespace(...)
|
| params(self, _ClauseElement__optionaldict: 'Optional[Mapping[str, Any]]' = None, **kwargs: 'Any') -> 'Self'
| Return a copy with :func:`_expression.bindparam` elements
| replaced.
|
| Returns a copy of this ClauseElement with
| :func:`_expression.bindparam`
| elements replaced with values taken from the given dictionary::
|
| >>> clause = column("x") + bindparam("foo")
| >>> print(clause.compile().params)
| {'foo':None}
| >>> print(clause.params({"foo": 7}).compile().params)
| {'foo':7}
|
| self_group(self, against: 'Optional[OperatorType]' = None) -> 'ClauseElement'
| 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.
|
| unique_params(self, _ClauseElement__optionaldict: 'Optional[Dict[str, Any]]' = None, **kwargs: 'Any') -> 'Self'
| Return a copy with :func:`_expression.bindparam` elements
| replaced.
|
| Same functionality as :meth:`_expression.ClauseElement.params`,
| except adds `unique=True`
| to affected bind parameters so that multiple statements can be
| used.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from ClauseElement:
|
| is_clause_element = True
|
| is_selectable = False
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_instancemethod(fn: '_F') -> '_F'
| Decorate a method memoize its return value.
|
| :meta private:
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_attribute = <class 'sqlalchemy.util.langhelpers.HasMemoized.m...
| A read-only @property that is only evaluated once.
|
| :meta private:
|
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.visitors.HasTraverseInternals:
|
| get_children(self, *, omit_attrs: 'Tuple[str, ...]' = (), **kw: 'Any') -> 'Iterable[HasTraverseInternals]'
| Return immediate child :class:`.visitors.HasTraverseInternals`
| elements of this :class:`.visitors.HasTraverseInternals`.
|
| This is used for visit traversal.
|
| \**kw may contain flags that change the collection that is
| returned, for example to return a subset of items in order to
| cut down on larger traversals, or to return child items from a
| different context (such as schema-level collections instead of
| clause-level).
|
| ----------------------------------------------------------------------
| Methods inherited from CompilerElement:
|
| __str__(self) -> 'str'
| Return str(self).
|
| compile(self, bind: 'Optional[_HasDialect]' = None, dialect: 'Optional[Dialect]' = None, **kw: 'Any') -> 'Compiled'
| Compile this SQL expression.
|
| The return value is a :class:`~.Compiled` object.
| Calling ``str()`` or ``unicode()`` on the returned value will yield a
| string representation of the result. The
| :class:`~.Compiled` object also can return a
| dictionary of bind parameter names and values
| using the ``params`` accessor.
|
| :param bind: An :class:`.Connection` or :class:`.Engine` which
| can provide a :class:`.Dialect` in order to generate a
| :class:`.Compiled` object. If the ``bind`` and
| ``dialect`` parameters are both omitted, a default SQL compiler
| is used.
|
| :param column_keys: Used for INSERT and UPDATE statements, a list of
| column names which should be present in the VALUES clause of the
| compiled statement. If ``None``, all columns from the target table
| object are rendered.
|
| :param dialect: A :class:`.Dialect` instance which can generate
| a :class:`.Compiled` object. This argument takes precedence over
| the ``bind`` argument.
|
| :param compile_kwargs: optional dictionary of additional parameters
| that will be passed through to the compiler within all "visit"
| methods. This allows any custom flag to be passed through to
| a custom compilation construct, for example. It is also used
| for the case of passing the ``literal_binds`` flag through::
|
| from sqlalchemy.sql import table, column, select
|
| t = table("t", column("x"))
|
| s = select(t).where(t.c.x == 5)
|
| print(s.compile(compile_kwargs={"literal_binds": True}))
|
| .. seealso::
|
| :ref:`faq_sql_expression_string`
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from CompilerElement:
|
| stringify_dialect = 'default'
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.visitors.Visitable:
|
| __class_getitem__(key: 'Any') -> 'Any'
|
| __init_subclass__() -> 'None'
| This method is called when a class is subclassed.
|
| The default implementation does nothing. It may be
| overridden to extend subclasses.
sqlalchemy.RootTransaction
Python Library Documentation: class RootTransaction in module sqlalchemy.engine.base
class RootTransaction(Transaction)
| RootTransaction(connection: 'Connection')
|
| Represent the "root" transaction on a :class:`_engine.Connection`.
|
| This corresponds to the current "BEGIN/COMMIT/ROLLBACK" that's occurring
| for the :class:`_engine.Connection`. The :class:`_engine.RootTransaction`
| is created by calling upon the :meth:`_engine.Connection.begin` method, and
| remains associated with the :class:`_engine.Connection` throughout its
| active span. The current :class:`_engine.RootTransaction` in use is
| accessible via the :attr:`_engine.Connection.get_transaction` method of
| :class:`_engine.Connection`.
|
| In :term:`2.0 style` use, the :class:`_engine.Connection` also employs
| "autobegin" behavior that will create a new
| :class:`_engine.RootTransaction` whenever a connection in a
| non-transactional state is used to emit commands on the DBAPI connection.
| The scope of the :class:`_engine.RootTransaction` in 2.0 style
| use can be controlled using the :meth:`_engine.Connection.commit` and
| :meth:`_engine.Connection.rollback` methods.
|
| Method resolution order:
| RootTransaction
| Transaction
| sqlalchemy.engine.util.TransactionalContext
| builtins.object
|
| Methods defined here:
|
| __init__(self, connection: 'Connection')
| Initialize self. See help(type(self)) for accurate signature.
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| connection
|
| is_active
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| ----------------------------------------------------------------------
| Methods inherited from Transaction:
|
| close(self) -> 'None'
| Close this :class:`.Transaction`.
|
| If this transaction is the base transaction in a begin/commit
| nesting, the transaction will rollback(). Otherwise, the
| method returns.
|
| This is used to cancel a Transaction without affecting the scope of
| an enclosing transaction.
|
| commit(self) -> 'None'
| Commit this :class:`.Transaction`.
|
| The implementation of this may vary based on the type of transaction in
| use:
|
| * For a simple database transaction (e.g. :class:`.RootTransaction`),
| it corresponds to a COMMIT.
|
| * For a :class:`.NestedTransaction`, it corresponds to a
| "RELEASE SAVEPOINT" operation.
|
| * For a :class:`.TwoPhaseTransaction`, DBAPI-specific methods for two
| phase transactions may be used.
|
| rollback(self) -> 'None'
| Roll back this :class:`.Transaction`.
|
| The implementation of this may vary based on the type of transaction in
| use:
|
| * For a simple database transaction (e.g. :class:`.RootTransaction`),
| it corresponds to a ROLLBACK.
|
| * For a :class:`.NestedTransaction`, it corresponds to a
| "ROLLBACK TO SAVEPOINT" operation.
|
| * For a :class:`.TwoPhaseTransaction`, DBAPI-specific methods for two
| phase transactions may be used.
|
| ----------------------------------------------------------------------
| Readonly properties inherited from Transaction:
|
| is_valid
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.engine.util.TransactionalContext:
|
| __enter__(self) -> 'Self'
|
| __exit__(self, type_: 'Any', value: 'Any', traceback: 'Any') -> 'None'
|
| ----------------------------------------------------------------------
| Data descriptors inherited from sqlalchemy.engine.util.TransactionalContext:
|
| __weakref__
| list of weak references to the object
sqlalchemy.Row
Python Library Documentation: class Row in module sqlalchemy.engine.row
class Row(sqlalchemy.cyextension.resultproxy.BaseRow, collections.abc.Sequence, typing.Generic)
| Represent a single result row.
|
| The :class:`.Row` object represents a row of a database result. It is
| typically associated in the 1.x series of SQLAlchemy with the
| :class:`_engine.CursorResult` object, however is also used by the ORM for
| tuple-like results as of SQLAlchemy 1.4.
|
| The :class:`.Row` object seeks to act as much like a Python named
| tuple as possible. For mapping (i.e. dictionary) behavior on a row,
| such as testing for containment of keys, refer to the :attr:`.Row._mapping`
| attribute.
|
| .. seealso::
|
| :ref:`tutorial_selecting_data` - includes examples of selecting
| rows from SELECT statements.
|
| .. versionchanged:: 1.4
|
| Renamed ``RowProxy`` to :class:`.Row`. :class:`.Row` is no longer a
| "proxy" object in that it contains the final form of data within it,
| and now acts mostly like a named tuple. Mapping-like functionality is
| moved to the :attr:`.Row._mapping` attribute. See
| :ref:`change_4710_core` for background on this change.
|
| Method resolution order:
| Row
| sqlalchemy.cyextension.resultproxy.BaseRow
| collections.abc.Sequence
| collections.abc.Reversible
| collections.abc.Collection
| collections.abc.Sized
| collections.abc.Iterable
| collections.abc.Container
| typing.Generic
| builtins.object
|
| Methods defined here:
|
| __contains__(self, key: 'Any') -> 'bool'
|
| __delattr__(self, name: 'str') -> 'NoReturn'
| Implement delattr(self, name).
|
| __eq__(self, other: 'Any') -> 'bool'
| Return self==value.
|
| __ge__(self, other: 'Any') -> 'bool'
| Return self>=value.
|
| __gt__(self, other: 'Any') -> 'bool'
| Return self>value.
|
| __hash__(self, /) from sqlalchemy.cyextension.resultproxy.BaseRow
| Return hash(self).
|
| __le__(self, other: 'Any') -> 'bool'
| Return self<=value.
|
| __lt__(self, other: 'Any') -> 'bool'
| Return self<value.
|
| __ne__(self, other: 'Any') -> 'bool'
| Return self!=value.
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| __setattr__(self, name: 'str', value: 'Any') -> 'NoReturn'
| Implement setattr(self, name, value).
|
| _asdict(self) -> 'Dict[str, Any]'
| Return a new dict which maps field names to their corresponding
| values.
|
| This method is analogous to the Python named tuple ``._asdict()``
| method, and works by applying the ``dict()`` constructor to the
| :attr:`.Row._mapping` attribute.
|
| .. versionadded:: 1.4
|
| .. seealso::
|
| :attr:`.Row._mapping`
|
| _filter_on_values(self, processor: 'Optional[_ProcessorsType]') -> 'Row[Any]'
|
| _op(self, other: 'Any', op: 'Callable[[Any, Any], bool]') -> 'bool'
|
| _special_name_accessor(name: 'str') -> 'Any'
| Handle ambiguous names such as "count" and "index"
|
| _tuple(self) -> '_TP'
| Return a 'tuple' form of this :class:`.Row`.
|
| At runtime, this method returns "self"; the :class:`.Row` object is
| already a named tuple. However, at the typing level, if this
| :class:`.Row` is typed, the "tuple" return type will be a :pep:`484`
| ``Tuple`` datatype that contains typing information about individual
| elements, supporting typed unpacking and attribute access.
|
| .. versionadded:: 2.0.19 - The :meth:`.Row._tuple` method supersedes
| the previous :meth:`.Row.tuple` method, which is now underscored
| to avoid name conflicts with column names in the same way as other
| named-tuple methods on :class:`.Row`.
|
| .. seealso::
|
| :attr:`.Row._t` - shorthand attribute notation
|
| :meth:`.Result.tuples`
|
| tuple(self) -> '_TP'
| Return a 'tuple' form of this :class:`.Row`.
|
| .. deprecated:: 2.0.19 The :meth:`.Row.tuple` method is deprecated in favor of :meth:`.Row._tuple`; all :class:`.Row` methods and library-level attributes are intended to be underscored to avoid name conflicts. Please use :meth:`Row._tuple`.
|
| .. versionadded:: 2.0
|
| ----------------------------------------------------------------------
| Readonly properties defined here:
|
| _fields
| Return a tuple of string keys as represented by this
| :class:`.Row`.
|
| The keys can represent the labels of the columns returned by a core
| statement or the names of the orm classes returned by an orm
| execution.
|
| This attribute is analogous to the Python named tuple ``._fields``
| attribute.
|
| .. versionadded:: 1.4
|
| .. seealso::
|
| :attr:`.Row._mapping`
|
| _mapping
| Return a :class:`.RowMapping` for this :class:`.Row`.
|
| This object provides a consistent Python mapping (i.e. dictionary)
| interface for the data contained within the row. The :class:`.Row`
| by itself behaves like a named tuple.
|
| .. seealso::
|
| :attr:`.Row._fields`
|
| .. versionadded:: 1.4
|
| _t
| A synonym for :meth:`.Row._tuple`.
|
| .. versionadded:: 2.0.19 - The :attr:`.Row._t` attribute supersedes
| the previous :attr:`.Row.t` attribute, which is now underscored
| to avoid name conflicts with column names in the same way as other
| named-tuple methods on :class:`.Row`.
|
| .. seealso::
|
| :attr:`.Result.t`
|
| count
|
| index
|
| t
| A synonym for :meth:`.Row._tuple`.
|
| .. deprecated:: 2.0.19 The :attr:`.Row.t` attribute is deprecated in favor of :attr:`.Row._t`; all :class:`.Row` methods and library-level attributes are intended to be underscored to avoid name conflicts. Please use :attr:`Row._t`.
|
| .. versionadded:: 2.0
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __abstractmethods__ = frozenset()
|
| __annotations__ = {}
|
| __orig_bases__ = (<class 'sqlalchemy.cyextension.resultproxy.BaseRow'>...
|
| __parameters__ = (~_TP,)
|
| _abc_impl = <_abc._abc_data object>
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.cyextension.resultproxy.BaseRow:
|
| __getattr__(...)
|
| __getattribute__(self, name, /)
| Return getattr(self, name).
|
| __getitem__(self, key, /)
| Return self[key].
|
| __getstate__(self)
|
| __init__(...)
| Row objects are constructed by CursorResult objects.
|
| __iter__(self, /)
| Implement iter(self).
|
| __len__(self, /)
| Return len(self).
|
| __reduce__(self)
|
| __setstate__(self, state)
|
| _get_by_key_impl_mapping(self, key)
|
| _to_tuple_instance(self)
|
| _values_impl(self)
|
| ----------------------------------------------------------------------
| Static methods inherited from sqlalchemy.cyextension.resultproxy.BaseRow:
|
| __new__(*args, **kwargs) class method of sqlalchemy.cyextension.resultproxy.BaseRow
| Create and return a new object. See help(type) for accurate signature.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from sqlalchemy.cyextension.resultproxy.BaseRow:
|
| _data
|
| _key_to_index
|
| _parent
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.cyextension.resultproxy.BaseRow:
|
| __pyx_vtable__ = <capsule object NULL>
|
| ----------------------------------------------------------------------
| Methods inherited from collections.abc.Sequence:
|
| __reversed__(self)
|
| ----------------------------------------------------------------------
| Class methods inherited from collections.abc.Reversible:
|
| __subclasshook__(C)
| Abstract classes can override this to customize issubclass().
|
| This is invoked early on by abc.ABCMeta.__subclasscheck__().
| It should return True, False or NotImplemented. If it returns
| NotImplemented, the normal algorithm is used. Otherwise, it
| overrides the normal algorithm (and the outcome is cached).
|
| ----------------------------------------------------------------------
| Class methods inherited from collections.abc.Iterable:
|
| __class_getitem__ = GenericAlias(...)
| Represent a PEP 585 generic type
|
| E.g. for t = list[int], t.__origin__ is list and t.__args__ is (int,).
|
| ----------------------------------------------------------------------
| Class methods inherited from typing.Generic:
|
| __init_subclass__(...)
| Function to initialize subclasses.
sqlalchemy.RowMapping
Python Library Documentation: class RowMapping in module sqlalchemy.engine.row
class RowMapping(sqlalchemy.cyextension.resultproxy.BaseRow, collections.abc.Mapping, typing.Generic)
| A ``Mapping`` that maps column names and objects to :class:`.Row`
| values.
|
| The :class:`.RowMapping` is available from a :class:`.Row` via the
| :attr:`.Row._mapping` attribute, as well as from the iterable interface
| provided by the :class:`.MappingResult` object returned by the
| :meth:`_engine.Result.mappings` method.
|
| :class:`.RowMapping` supplies Python mapping (i.e. dictionary) access to
| the contents of the row. This includes support for testing of
| containment of specific keys (string column names or objects), as well
| as iteration of keys, values, and items::
|
| for row in result:
| if "a" in row._mapping:
| print("Column 'a': %s" % row._mapping["a"])
|
| print("Column b: %s" % row._mapping[table.c.b])
|
| .. versionadded:: 1.4 The :class:`.RowMapping` object replaces the
| mapping-like access previously provided by a database result row,
| which now seeks to behave mostly like a named tuple.
|
| Method resolution order:
| RowMapping
| sqlalchemy.cyextension.resultproxy.BaseRow
| collections.abc.Mapping
| collections.abc.Collection
| collections.abc.Sized
| collections.abc.Iterable
| collections.abc.Container
| typing.Generic
| builtins.object
|
| Methods defined here:
|
| __contains__(self, key: 'object') -> 'bool'
|
| __getitem__ = _get_by_key_impl_mapping(self, key)
|
| __iter__(self) -> 'Iterator[str]'
| Implement iter(self).
|
| __len__(self) -> 'int'
| Return len(self).
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| items(self) -> 'ROMappingItemsView'
| Return a view of key/value tuples for the elements in the
| underlying :class:`.Row`.
|
| keys(self) -> 'RMKeyView'
| Return a view of 'keys' for string column names represented
| by the underlying :class:`.Row`.
|
| values(self) -> 'ROMappingKeysValuesView'
| Return a view of values for the values represented in the
| underlying :class:`.Row`.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __abstractmethods__ = frozenset()
|
| __annotations__ = {}
|
| __orig_bases__ = (<class 'sqlalchemy.cyextension.resultproxy.BaseRow'>...
|
| __parameters__ = ()
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.cyextension.resultproxy.BaseRow:
|
| __getattr__(...)
|
| __getattribute__(self, name, /)
| Return getattr(self, name).
|
| __getstate__(self)
|
| __hash__(self, /)
| Return hash(self).
|
| __init__(...)
| Row objects are constructed by CursorResult objects.
|
| __reduce__(self)
|
| __setstate__(self, state)
|
| ----------------------------------------------------------------------
| Static methods inherited from sqlalchemy.cyextension.resultproxy.BaseRow:
|
| __new__(*args, **kwargs) class method of sqlalchemy.cyextension.resultproxy.BaseRow
| Create and return a new object. See help(type) for accurate signature.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.cyextension.resultproxy.BaseRow:
|
| __pyx_vtable__ = <capsule object NULL>
|
| ----------------------------------------------------------------------
| Methods inherited from collections.abc.Mapping:
|
| __eq__(self, other)
| Return self==value.
|
| get(self, key, default=None)
| D.get(k[,d]) -> D[k] if k in D, else d. d defaults to None.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from collections.abc.Mapping:
|
| __reversed__ = None
|
| ----------------------------------------------------------------------
| Class methods inherited from collections.abc.Collection:
|
| __subclasshook__(C)
| Abstract classes can override this to customize issubclass().
|
| This is invoked early on by abc.ABCMeta.__subclasscheck__().
| It should return True, False or NotImplemented. If it returns
| NotImplemented, the normal algorithm is used. Otherwise, it
| overrides the normal algorithm (and the outcome is cached).
|
| ----------------------------------------------------------------------
| Class methods inherited from collections.abc.Iterable:
|
| __class_getitem__ = GenericAlias(...)
| Represent a PEP 585 generic type
|
| E.g. for t = list[int], t.__origin__ is list and t.__args__ is (int,).
|
| ----------------------------------------------------------------------
| Class methods inherited from typing.Generic:
|
| __init_subclass__(...)
| Function to initialize subclasses.
sqlalchemy.SMALLINT
Python Library Documentation: class SMALLINT in module sqlalchemy.sql.sqltypes
class SMALLINT(SmallInteger)
| The SQL SMALLINT type.
|
| .. seealso::
|
| :class:`_types.SmallInteger` - documentation for the base type.
|
| Method resolution order:
| SMALLINT
| SmallInteger
| Integer
| HasExpressionLookup
| sqlalchemy.sql.type_api.TypeEngineMixin
| sqlalchemy.sql.type_api.TypeEngine
| sqlalchemy.sql.visitors.Visitable
| typing.Generic
| builtins.object
|
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| __parameters__ = ()
|
| __visit_name__ = 'SMALLINT'
|
| ----------------------------------------------------------------------
| Methods inherited from Integer:
|
| get_dbapi_type(self, dbapi)
| Return the corresponding type object from the underlying DB-API, if
| any.
|
| This can be useful for calling ``setinputsizes()``, for example.
|
| literal_processor(self, dialect)
| Return a conversion function for processing literal values that are
| to be rendered directly without using binds.
|
| This function is used when the compiler makes use of the
| "literal_binds" flag, typically used in DDL generation as well
| as in certain scenarios where backends don't accept bound parameters.
|
| Returns a callable which will receive a literal Python value
| as the sole positional argument and will return a string representation
| to be rendered in a SQL statement.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.literal_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.literal_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_literal_param`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| ----------------------------------------------------------------------
| Readonly properties inherited from Integer:
|
| python_type
| Return the Python type object expected to be returned
| by instances of this type, if known.
|
| Basically, for those types which enforce a return type,
| or are known across the board to do such for all common
| DBAPIs (like ``int`` for example), will return that type.
|
| If a return type is not defined, raises
| ``NotImplementedError``.
|
| Note that any type also accommodates NULL in SQL which
| means you can also get back ``None`` from any type
| in practice.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from HasExpressionLookup:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from HasExpressionLookup:
|
| Comparator = <class 'sqlalchemy.sql.sqltypes.HasExpressionLookup.Compa...
|
| comparator_factory = <class 'sqlalchemy.sql.sqltypes.HasExpressionLook...
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.type_api.TypeEngine:
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| __str__(self) -> 'str'
| Return str(self).
|
| adapt(self, cls: 'Type[Union[TypeEngine[Any], TypeEngineMixin]]', **kw: 'Any') -> 'TypeEngine[Any]'
| Produce an "adapted" form of this type, given an "impl" class
| to work with.
|
| This method is used internally to associate generic
| types with "implementation" types that are specific to a particular
| dialect.
|
| as_generic(self, allow_nulltype: 'bool' = False) -> 'TypeEngine[_T]'
| Return an instance of the generic type corresponding to this type
| using heuristic rule. The method may be overridden if this
| heuristic rule is not sufficient.
|
| >>> from sqlalchemy.dialects.mysql import INTEGER
| >>> INTEGER(display_width=4).as_generic()
| Integer()
|
| >>> from sqlalchemy.dialects.mysql import NVARCHAR
| >>> NVARCHAR(length=100).as_generic()
| Unicode(length=100)
|
| .. versionadded:: 1.4.0b2
|
|
| .. seealso::
|
| :ref:`metadata_reflection_dbagnostic_types` - describes the
| use of :meth:`_types.TypeEngine.as_generic` in conjunction with
| the :meth:`_sql.DDLEvents.column_reflect` event, which is its
| intended use.
|
| bind_expression(self, bindvalue: 'BindParameter[_T]') -> 'Optional[ColumnElement[_T]]'
| Given a bind value (i.e. a :class:`.BindParameter` instance),
| return a SQL expression in its place.
|
| This is typically a SQL function that wraps the existing bound
| parameter within the statement. It is used for special data types
| that require literals being wrapped in some special database function
| in order to coerce an application-level value into a database-specific
| format. It is the SQL analogue of the
| :meth:`.TypeEngine.bind_processor` method.
|
| This method is called during the **SQL compilation** phase of a
| statement, when rendering a SQL string. It is **not** called
| against specific values.
|
| Note that this method, when implemented, should always return
| the exact same structure, without any conditional logic, as it
| may be used in an executemany() call against an arbitrary number
| of bound parameter sets.
|
| .. note::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.bind_expression`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.bind_expression`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.bind_expression`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| .. seealso::
|
| :ref:`types_sql_value_processing`
|
| bind_processor(self, dialect: 'Dialect') -> 'Optional[_BindProcessorType[_T]]'
| Return a conversion function for processing bind values.
|
| Returns a callable which will receive a bind parameter value
| as the sole positional argument and will return a value to
| send to the DB-API.
|
| If processing is not necessary, the method should return ``None``.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.bind_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.bind_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_bind_param`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
|
| :param dialect: Dialect instance in use.
|
| coerce_compared_value(self, op: 'Optional[OperatorType]', value: 'Any') -> 'TypeEngine[Any]'
| Suggest a type for a 'coerced' Python value in an expression.
|
| Given an operator and value, gives the type a chance
| to return a type which the value should be coerced into.
|
| The default behavior here is conservative; if the right-hand
| side is already coerced into a SQL type based on its
| Python type, it is usually left alone.
|
| End-user functionality extension here should generally be via
| :class:`.TypeDecorator`, which provides more liberal behavior in that
| it defaults to coercing the other side of the expression into this
| type, thus applying special Python conversions above and beyond those
| needed by the DBAPI to both ides. It also provides the public method
| :meth:`.TypeDecorator.coerce_compared_value` which is intended for
| end-user customization of this behavior.
|
| column_expression(self, colexpr: 'ColumnElement[_T]') -> 'Optional[ColumnElement[_T]]'
| Given a SELECT column expression, return a wrapping SQL expression.
|
| This is typically a SQL function that wraps a column expression
| as rendered in the columns clause of a SELECT statement.
| It is used for special data types that require
| columns to be wrapped in some special database function in order
| to coerce the value before being sent back to the application.
| It is the SQL analogue of the :meth:`.TypeEngine.result_processor`
| method.
|
| .. note:: The :func:`.TypeEngine.column_expression` method is applied
| only to the **outermost columns clause** of a SELECT statement, that
| is, the columns that are to be delivered directly into the returned
| result rows. It does **not** apply to the columns clause inside
| of subqueries. This necessarily avoids double conversions against
| the column and only runs the conversion when ready to be returned
| to the client.
|
| This method is called during the **SQL compilation** phase of a
| statement, when rendering a SQL string. It is **not** called
| against specific values.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.column_expression`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.column_expression`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.column_expression`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
|
| .. seealso::
|
| :ref:`types_sql_value_processing`
|
| compare_values(self, x: 'Any', y: 'Any') -> 'bool'
| Compare two values for equality.
|
| compile(self, dialect: 'Optional[Dialect]' = None) -> 'str'
| Produce a string-compiled form of this :class:`.TypeEngine`.
|
| When called with no arguments, uses a "default" dialect
| to produce a string result.
|
| :param dialect: a :class:`.Dialect` instance.
|
| copy(self, **kw: 'Any') -> 'Self'
|
| copy_value(self, value: 'Any') -> 'Any'
|
| dialect_impl(self, dialect: 'Dialect') -> 'TypeEngine[_T]'
| Return a dialect-specific implementation for this
| :class:`.TypeEngine`.
|
| evaluates_none(self) -> 'Self'
| Return a copy of this type which has the
| :attr:`.should_evaluate_none` flag set to True.
|
| E.g.::
|
| Table(
| "some_table",
| metadata,
| Column(
| String(50).evaluates_none(),
| nullable=True,
| server_default="no value",
| ),
| )
|
| The ORM uses this flag to indicate that a positive value of ``None``
| is passed to the column in an INSERT statement, rather than omitting
| the column from the INSERT statement which has the effect of firing
| off column-level defaults. It also allows for types which have
| special behavior associated with the Python None value to indicate
| that the value doesn't necessarily translate into SQL NULL; a
| prime example of this is a JSON type which may wish to persist the
| JSON value ``'null'``.
|
| In all cases, the actual NULL SQL value can be always be
| persisted in any column by using
| the :obj:`_expression.null` SQL construct in an INSERT statement
| or associated with an ORM-mapped attribute.
|
| .. note::
|
| The "evaluates none" flag does **not** apply to a value
| of ``None`` passed to :paramref:`_schema.Column.default` or
| :paramref:`_schema.Column.server_default`; in these cases,
| ``None``
| still means "no default".
|
| .. seealso::
|
| :ref:`session_forcing_null` - in the ORM documentation
|
| :paramref:`.postgresql.JSON.none_as_null` - PostgreSQL JSON
| interaction with this flag.
|
| :attr:`.TypeEngine.should_evaluate_none` - class-level flag
|
| result_processor(self, dialect: 'Dialect', coltype: 'object') -> 'Optional[_ResultProcessorType[_T]]'
| Return a conversion function for processing result row values.
|
| Returns a callable which will receive a result row column
| value as the sole positional argument and will return a value
| to return to the user.
|
| If processing is not necessary, the method should return ``None``.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.result_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.result_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_result_value`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| :param dialect: Dialect instance in use.
|
| :param coltype: DBAPI coltype argument received in cursor.description.
|
| with_variant(self, type_: '_TypeEngineArgument[Any]', *dialect_names: 'str') -> 'Self'
| Produce a copy of this type object that will utilize the given
| type when applied to the dialect of the given name.
|
| e.g.::
|
| from sqlalchemy.types import String
| from sqlalchemy.dialects import mysql
|
| string_type = String()
|
| string_type = string_type.with_variant(
| mysql.VARCHAR(collation="foo"), "mysql", "mariadb"
| )
|
| The variant mapping indicates that when this type is
| interpreted by a specific dialect, it will instead be
| transmuted into the given type, rather than using the
| primary type.
|
| .. versionchanged:: 2.0 the :meth:`_types.TypeEngine.with_variant`
| method now works with a :class:`_types.TypeEngine` object "in
| place", returning a copy of the original type rather than returning
| a wrapping object; the ``Variant`` class is no longer used.
|
| :param type\_: a :class:`.TypeEngine` that will be selected
| as a variant from the originating type, when a dialect
| of the given name is in use.
| :param \*dialect_names: one or more base names of the dialect which
| uses this type. (i.e. ``'postgresql'``, ``'mysql'``, etc.)
|
| .. versionchanged:: 2.0 multiple dialect names can be specified
| for one variant.
|
| .. seealso::
|
| :ref:`types_with_variant` - illustrates the use of
| :meth:`_types.TypeEngine.with_variant`.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.type_api.TypeEngine:
|
| __orig_bases__ = (<class 'sqlalchemy.sql.visitors.Visitable'>, typing....
|
| hashable = True
|
| render_bind_cast = False
|
| render_literal_cast = False
|
| should_evaluate_none = False
|
| sort_key_function = None
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.visitors.Visitable:
|
| __class_getitem__(key: 'Any') -> 'Any'
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__() -> 'None'
| This method is called when a class is subclassed.
|
| The default implementation does nothing. It may be
| overridden to extend subclasses.
sqlalchemy.SQLColumnExpression
Python Library Documentation: class SQLColumnExpression in module sqlalchemy.sql.elements
class SQLColumnExpression(SQLCoreOperations, sqlalchemy.sql.roles.ExpressionElementRole, sqlalchemy.util.langhelpers.TypingOnly)
| A type that may be used to indicate any SQL column element or object
| that acts in place of one.
|
| :class:`.SQLColumnExpression` is a base of
| :class:`.ColumnElement`, as well as within the bases of ORM elements
| such as :class:`.InstrumentedAttribute`, and may be used in :pep:`484`
| typing to indicate arguments or return values that should behave
| as column expressions.
|
| .. versionadded:: 2.0.0b4
|
| Method resolution order:
| SQLColumnExpression
| SQLCoreOperations
| sqlalchemy.sql.roles.ExpressionElementRole
| sqlalchemy.sql.roles.TypedColumnsClauseRole
| typing.Generic
| sqlalchemy.sql.operators.ColumnOperators
| sqlalchemy.sql.operators.Operators
| sqlalchemy.util.langhelpers.TypingOnly
| sqlalchemy.sql.roles.SQLRole
| builtins.object
|
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| __orig_bases__ = (sqlalchemy.sql.elements.SQLCoreOperations[+_T_co], s...
|
| __parameters__ = (+_T_co,)
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.roles.ExpressionElementRole:
|
| label(self, name: 'Optional[str]') -> 'Label[_T]'
|
| ----------------------------------------------------------------------
| Class methods inherited from typing.Generic:
|
| __class_getitem__(...)
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__(...)
| Function to initialize subclasses.
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.operators.ColumnOperators:
|
| __add__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``+`` operator.
|
| In a column context, produces the clause ``a + b``
| if the parent object has non-string affinity.
| If the parent object has a string affinity,
| produces the concatenation operator, ``a || b`` -
| see :meth:`.ColumnOperators.concat`.
|
| __contains__(self, other: 'Any') -> 'ColumnOperators'
|
| __eq__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``==`` operator.
|
| In a column context, produces the clause ``a = b``.
| If the target is ``None``, produces ``a IS NULL``.
|
| __floordiv__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``//`` operator.
|
| In a column context, produces the clause ``a / b``,
| which is the same as "truediv", but considers the result
| type to be integer.
|
| .. versionadded:: 2.0
|
| __ge__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``>=`` operator.
|
| In a column context, produces the clause ``a >= b``.
|
| __getitem__(self, index: 'Any') -> 'ColumnOperators'
| Implement the [] operator.
|
| This can be used by some database-specific types
| such as PostgreSQL ARRAY and HSTORE.
|
| __gt__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``>`` operator.
|
| In a column context, produces the clause ``a > b``.
|
| __hash__(self, /) from builtins.object
| Return hash(self).
|
| __le__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``<=`` operator.
|
| In a column context, produces the clause ``a <= b``.
|
| __lshift__(self, other: 'Any') -> 'ColumnOperators'
| implement the << operator.
|
| Not used by SQLAlchemy core, this is provided
| for custom operator systems which want to use
| << as an extension point.
|
| __lt__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``<`` operator.
|
| In a column context, produces the clause ``a < b``.
|
| __mod__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``%`` operator.
|
| In a column context, produces the clause ``a % b``.
|
| __mul__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``*`` operator.
|
| In a column context, produces the clause ``a * b``.
|
| __ne__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``!=`` operator.
|
| In a column context, produces the clause ``a != b``.
| If the target is ``None``, produces ``a IS NOT NULL``.
|
| __neg__(self) -> 'ColumnOperators'
| Implement the ``-`` operator.
|
| In a column context, produces the clause ``-a``.
|
| __radd__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``+`` operator in reverse.
|
| See :meth:`.ColumnOperators.__add__`.
|
| __rfloordiv__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``//`` operator in reverse.
|
| See :meth:`.ColumnOperators.__floordiv__`.
|
| __rmod__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``%`` operator in reverse.
|
| See :meth:`.ColumnOperators.__mod__`.
|
| __rmul__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``*`` operator in reverse.
|
| See :meth:`.ColumnOperators.__mul__`.
|
| __rshift__(self, other: 'Any') -> 'ColumnOperators'
| implement the >> operator.
|
| Not used by SQLAlchemy core, this is provided
| for custom operator systems which want to use
| >> as an extension point.
|
| __rsub__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``-`` operator in reverse.
|
| See :meth:`.ColumnOperators.__sub__`.
|
| __rtruediv__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``/`` operator in reverse.
|
| See :meth:`.ColumnOperators.__truediv__`.
|
| __sub__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``-`` operator.
|
| In a column context, produces the clause ``a - b``.
|
| __truediv__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``/`` operator.
|
| In a column context, produces the clause ``a / b``, and
| considers the result type to be numeric.
|
| .. versionchanged:: 2.0 The truediv operator against two integers
| is now considered to return a numeric value. Behavior on specific
| backends may vary.
|
| all_(self) -> 'ColumnOperators'
| Produce an :func:`_expression.all_` clause against the
| parent object.
|
| See the documentation for :func:`_sql.all_` for examples.
|
| .. note:: be sure to not confuse the newer
| :meth:`_sql.ColumnOperators.all_` method with the **legacy**
| version of this method, the :meth:`_types.ARRAY.Comparator.all`
| method that's specific to :class:`_types.ARRAY`, which uses a
| different calling style.
|
| any_(self) -> 'ColumnOperators'
| Produce an :func:`_expression.any_` clause against the
| parent object.
|
| See the documentation for :func:`_sql.any_` for examples.
|
| .. note:: be sure to not confuse the newer
| :meth:`_sql.ColumnOperators.any_` method with the **legacy**
| version of this method, the :meth:`_types.ARRAY.Comparator.any`
| method that's specific to :class:`_types.ARRAY`, which uses a
| different calling style.
|
| asc(self) -> 'ColumnOperators'
| Produce a :func:`_expression.asc` clause against the
| parent object.
|
| between(self, cleft: 'Any', cright: 'Any', symmetric: 'bool' = False) -> 'ColumnOperators'
| Produce a :func:`_expression.between` clause against
| the parent object, given the lower and upper range.
|
| bitwise_and(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise AND operation, typically via the ``&``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_lshift(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise LSHIFT operation, typically via the ``<<``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_not(self) -> 'ColumnOperators'
| Produce a bitwise NOT operation, typically via the ``~``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_or(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise OR operation, typically via the ``|``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_rshift(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise RSHIFT operation, typically via the ``>>``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_xor(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise XOR operation, typically via the ``^``
| operator, or ``#`` for PostgreSQL.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| collate(self, collation: 'str') -> 'ColumnOperators'
| Produce a :func:`_expression.collate` clause against
| the parent object, given the collation string.
|
| .. seealso::
|
| :func:`_expression.collate`
|
| concat(self, other: 'Any') -> 'ColumnOperators'
| Implement the 'concat' operator.
|
| In a column context, produces the clause ``a || b``,
| or uses the ``concat()`` operator on MySQL.
|
| contains(self, other: 'Any', **kw: 'Any') -> 'ColumnOperators'
| Implement the 'contains' operator.
|
| Produces a LIKE expression that tests against a match for the middle
| of a string value:
|
| .. sourcecode:: sql
|
| column LIKE '%' || <other> || '%'
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.contains("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.contains.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.contains.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.contains.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.contains("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE '%' || :param || '%' ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.contains("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE '%' || :param || '%' ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.contains.autoescape`::
|
| somecolumn.contains("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.startswith`
|
| :meth:`.ColumnOperators.endswith`
|
| :meth:`.ColumnOperators.like`
|
| desc(self) -> 'ColumnOperators'
| Produce a :func:`_expression.desc` clause against the
| parent object.
|
| distinct(self) -> 'ColumnOperators'
| Produce a :func:`_expression.distinct` clause against the
| parent object.
|
| endswith(self, other: 'Any', escape: 'Optional[str]' = None, autoescape: 'bool' = False) -> 'ColumnOperators'
| Implement the 'endswith' operator.
|
| Produces a LIKE expression that tests against a match for the end
| of a string value:
|
| .. sourcecode:: sql
|
| column LIKE '%' || <other>
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.endswith("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.endswith.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.endswith.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.endswith.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.endswith("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE '%' || :param ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.endswith("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE '%' || :param ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.endswith.autoescape`::
|
| somecolumn.endswith("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.startswith`
|
| :meth:`.ColumnOperators.contains`
|
| :meth:`.ColumnOperators.like`
|
| icontains(self, other: 'Any', **kw: 'Any') -> 'ColumnOperators'
| Implement the ``icontains`` operator, e.g. case insensitive
| version of :meth:`.ColumnOperators.contains`.
|
| Produces a LIKE expression that tests against an insensitive match
| for the middle of a string value:
|
| .. sourcecode:: sql
|
| lower(column) LIKE '%' || lower(<other>) || '%'
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.icontains("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.icontains.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.icontains.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.icontains.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.icontains("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE '%' || lower(:param) || '%' ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.icontains("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE '%' || lower(:param) || '%' ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.contains.autoescape`::
|
| somecolumn.icontains("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.contains`
|
| iendswith(self, other: 'Any', escape: 'Optional[str]' = None, autoescape: 'bool' = False) -> 'ColumnOperators'
| Implement the ``iendswith`` operator, e.g. case insensitive
| version of :meth:`.ColumnOperators.endswith`.
|
| Produces a LIKE expression that tests against an insensitive match
| for the end of a string value:
|
| .. sourcecode:: sql
|
| lower(column) LIKE '%' || lower(<other>)
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.iendswith("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.iendswith.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.iendswith.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.iendswith.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.iendswith("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE '%' || lower(:param) ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.iendswith("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE '%' || lower(:param) ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.iendswith.autoescape`::
|
| somecolumn.endswith("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.endswith`
|
| ilike(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
| Implement the ``ilike`` operator, e.g. case insensitive LIKE.
|
| In a column context, produces an expression either of the form:
|
| .. sourcecode:: sql
|
| lower(a) LIKE lower(other)
|
| Or on backends that support the ILIKE operator:
|
| .. sourcecode:: sql
|
| a ILIKE other
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.ilike("%foobar%"))
|
| :param other: expression to be compared
| :param escape: optional escape character, renders the ``ESCAPE``
| keyword, e.g.::
|
| somecolumn.ilike("foo/%bar", escape="/")
|
| .. seealso::
|
| :meth:`.ColumnOperators.like`
|
| in_(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``in`` operator.
|
| In a column context, produces the clause ``column IN <other>``.
|
| The given parameter ``other`` may be:
|
| * A list of literal values,
| e.g.::
|
| stmt.where(column.in_([1, 2, 3]))
|
| In this calling form, the list of items is converted to a set of
| bound parameters the same length as the list given:
|
| .. sourcecode:: sql
|
| WHERE COL IN (?, ?, ?)
|
| * A list of tuples may be provided if the comparison is against a
| :func:`.tuple_` containing multiple expressions::
|
| from sqlalchemy import tuple_
|
| stmt.where(tuple_(col1, col2).in_([(1, 10), (2, 20), (3, 30)]))
|
| * An empty list,
| e.g.::
|
| stmt.where(column.in_([]))
|
| In this calling form, the expression renders an "empty set"
| expression. These expressions are tailored to individual backends
| and are generally trying to get an empty SELECT statement as a
| subquery. Such as on SQLite, the expression is:
|
| .. sourcecode:: sql
|
| WHERE col IN (SELECT 1 FROM (SELECT 1) WHERE 1!=1)
|
| .. versionchanged:: 1.4 empty IN expressions now use an
| execution-time generated SELECT subquery in all cases.
|
| * A bound parameter, e.g. :func:`.bindparam`, may be used if it
| includes the :paramref:`.bindparam.expanding` flag::
|
| stmt.where(column.in_(bindparam("value", expanding=True)))
|
| In this calling form, the expression renders a special non-SQL
| placeholder expression that looks like:
|
| .. sourcecode:: sql
|
| WHERE COL IN ([EXPANDING_value])
|
| This placeholder expression is intercepted at statement execution
| time to be converted into the variable number of bound parameter
| form illustrated earlier. If the statement were executed as::
|
| connection.execute(stmt, {"value": [1, 2, 3]})
|
| The database would be passed a bound parameter for each value:
|
| .. sourcecode:: sql
|
| WHERE COL IN (?, ?, ?)
|
| .. versionadded:: 1.2 added "expanding" bound parameters
|
| If an empty list is passed, a special "empty list" expression,
| which is specific to the database in use, is rendered. On
| SQLite this would be:
|
| .. sourcecode:: sql
|
| WHERE COL IN (SELECT 1 FROM (SELECT 1) WHERE 1!=1)
|
| .. versionadded:: 1.3 "expanding" bound parameters now support
| empty lists
|
| * a :func:`_expression.select` construct, which is usually a
| correlated scalar select::
|
| stmt.where(
| column.in_(select(othertable.c.y).where(table.c.x == othertable.c.x))
| )
|
| In this calling form, :meth:`.ColumnOperators.in_` renders as given:
|
| .. sourcecode:: sql
|
| WHERE COL IN (SELECT othertable.y
| FROM othertable WHERE othertable.x = table.x)
|
| :param other: a list of literals, a :func:`_expression.select`
| construct, or a :func:`.bindparam` construct that includes the
| :paramref:`.bindparam.expanding` flag set to True.
|
| is_(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``IS`` operator.
|
| Normally, ``IS`` is generated automatically when comparing to a
| value of ``None``, which resolves to ``NULL``. However, explicit
| usage of ``IS`` may be desirable if comparing to boolean values
| on certain platforms.
|
| .. seealso:: :meth:`.ColumnOperators.is_not`
|
| is_distinct_from(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``IS DISTINCT FROM`` operator.
|
| Renders "a IS DISTINCT FROM b" on most platforms;
| on some such as SQLite may render "a IS NOT b".
|
| is_not(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``IS NOT`` operator.
|
| Normally, ``IS NOT`` is generated automatically when comparing to a
| value of ``None``, which resolves to ``NULL``. However, explicit
| usage of ``IS NOT`` may be desirable if comparing to boolean values
| on certain platforms.
|
| .. versionchanged:: 1.4 The ``is_not()`` operator is renamed from
| ``isnot()`` in previous releases. The previous name remains
| available for backwards compatibility.
|
| .. seealso:: :meth:`.ColumnOperators.is_`
|
| is_not_distinct_from(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``IS NOT DISTINCT FROM`` operator.
|
| Renders "a IS NOT DISTINCT FROM b" on most platforms;
| on some such as SQLite may render "a IS b".
|
| .. versionchanged:: 1.4 The ``is_not_distinct_from()`` operator is
| renamed from ``isnot_distinct_from()`` in previous releases.
| The previous name remains available for backwards compatibility.
|
| isnot = is_not(self, other: 'Any') -> 'ColumnOperators'
|
| isnot_distinct_from = is_not_distinct_from(self, other: 'Any') -> 'ColumnOperators'
|
| istartswith(self, other: 'Any', escape: 'Optional[str]' = None, autoescape: 'bool' = False) -> 'ColumnOperators'
| Implement the ``istartswith`` operator, e.g. case insensitive
| version of :meth:`.ColumnOperators.startswith`.
|
| Produces a LIKE expression that tests against an insensitive
| match for the start of a string value:
|
| .. sourcecode:: sql
|
| lower(column) LIKE lower(<other>) || '%'
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.istartswith("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.istartswith.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.istartswith.escape` parameter will
| establish a given character as an escape character which can be of
| use when the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.istartswith.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.istartswith("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE lower(:param) || '%' ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.istartswith("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE lower(:param) || '%' ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.istartswith.autoescape`::
|
| somecolumn.istartswith("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.startswith`
|
| like(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
| Implement the ``like`` operator.
|
| In a column context, produces the expression:
|
| .. sourcecode:: sql
|
| a LIKE other
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.like("%foobar%"))
|
| :param other: expression to be compared
| :param escape: optional escape character, renders the ``ESCAPE``
| keyword, e.g.::
|
| somecolumn.like("foo/%bar", escape="/")
|
| .. seealso::
|
| :meth:`.ColumnOperators.ilike`
|
| match(self, other: 'Any', **kwargs: 'Any') -> 'ColumnOperators'
| Implements a database-specific 'match' operator.
|
| :meth:`_sql.ColumnOperators.match` attempts to resolve to
| a MATCH-like function or operator provided by the backend.
| Examples include:
|
| * PostgreSQL - renders ``x @@ plainto_tsquery(y)``
|
| .. versionchanged:: 2.0 ``plainto_tsquery()`` is used instead
| of ``to_tsquery()`` for PostgreSQL now; for compatibility with
| other forms, see :ref:`postgresql_match`.
|
|
| * MySQL - renders ``MATCH (x) AGAINST (y IN BOOLEAN MODE)``
|
| .. seealso::
|
| :class:`_mysql.match` - MySQL specific construct with
| additional features.
|
| * Oracle Database - renders ``CONTAINS(x, y)``
| * other backends may provide special implementations.
| * Backends without any special implementation will emit
| the operator as "MATCH". This is compatible with SQLite, for
| example.
|
| not_ilike(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
| implement the ``NOT ILIKE`` operator.
|
| This is equivalent to using negation with
| :meth:`.ColumnOperators.ilike`, i.e. ``~x.ilike(y)``.
|
| .. versionchanged:: 1.4 The ``not_ilike()`` operator is renamed from
| ``notilike()`` in previous releases. The previous name remains
| available for backwards compatibility.
|
| .. seealso::
|
| :meth:`.ColumnOperators.ilike`
|
| not_in(self, other: 'Any') -> 'ColumnOperators'
| implement the ``NOT IN`` operator.
|
| This is equivalent to using negation with
| :meth:`.ColumnOperators.in_`, i.e. ``~x.in_(y)``.
|
| In the case that ``other`` is an empty sequence, the compiler
| produces an "empty not in" expression. This defaults to the
| expression "1 = 1" to produce true in all cases. The
| :paramref:`_sa.create_engine.empty_in_strategy` may be used to
| alter this behavior.
|
| .. versionchanged:: 1.4 The ``not_in()`` operator is renamed from
| ``notin_()`` in previous releases. The previous name remains
| available for backwards compatibility.
|
| .. versionchanged:: 1.2 The :meth:`.ColumnOperators.in_` and
| :meth:`.ColumnOperators.not_in` operators
| now produce a "static" expression for an empty IN sequence
| by default.
|
| .. seealso::
|
| :meth:`.ColumnOperators.in_`
|
| not_like(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
| implement the ``NOT LIKE`` operator.
|
| This is equivalent to using negation with
| :meth:`.ColumnOperators.like`, i.e. ``~x.like(y)``.
|
| .. versionchanged:: 1.4 The ``not_like()`` operator is renamed from
| ``notlike()`` in previous releases. The previous name remains
| available for backwards compatibility.
|
| .. seealso::
|
| :meth:`.ColumnOperators.like`
|
| notilike = not_ilike(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
|
| notin_ = not_in(self, other: 'Any') -> 'ColumnOperators'
|
| notlike = not_like(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
|
| nulls_first(self) -> 'ColumnOperators'
| Produce a :func:`_expression.nulls_first` clause against the
| parent object.
|
| .. versionchanged:: 1.4 The ``nulls_first()`` operator is
| renamed from ``nullsfirst()`` in previous releases.
| The previous name remains available for backwards compatibility.
|
| nulls_last(self) -> 'ColumnOperators'
| Produce a :func:`_expression.nulls_last` clause against the
| parent object.
|
| .. versionchanged:: 1.4 The ``nulls_last()`` operator is
| renamed from ``nullslast()`` in previous releases.
| The previous name remains available for backwards compatibility.
|
| nullsfirst = nulls_first(self) -> 'ColumnOperators'
|
| nullslast = nulls_last(self) -> 'ColumnOperators'
|
| regexp_match(self, pattern: 'Any', flags: 'Optional[str]' = None) -> 'ColumnOperators'
| Implements a database-specific 'regexp match' operator.
|
| E.g.::
|
| stmt = select(table.c.some_column).where(
| table.c.some_column.regexp_match("^(b|c)")
| )
|
| :meth:`_sql.ColumnOperators.regexp_match` attempts to resolve to
| a REGEXP-like function or operator provided by the backend, however
| the specific regular expression syntax and flags available are
| **not backend agnostic**.
|
| Examples include:
|
| * PostgreSQL - renders ``x ~ y`` or ``x !~ y`` when negated.
| * Oracle Database - renders ``REGEXP_LIKE(x, y)``
| * SQLite - uses SQLite's ``REGEXP`` placeholder operator and calls into
| the Python ``re.match()`` builtin.
| * other backends may provide special implementations.
| * Backends without any special implementation will emit
| the operator as "REGEXP" or "NOT REGEXP". This is compatible with
| SQLite and MySQL, for example.
|
| Regular expression support is currently implemented for Oracle
| Database, PostgreSQL, MySQL and MariaDB. Partial support is available
| for SQLite. Support among third-party dialects may vary.
|
| :param pattern: The regular expression pattern string or column
| clause.
| :param flags: Any regular expression string flags to apply, passed as
| plain Python string only. These flags are backend specific.
| Some backends, like PostgreSQL and MariaDB, may alternatively
| specify the flags as part of the pattern.
| When using the ignore case flag 'i' in PostgreSQL, the ignore case
| regexp match operator ``~*`` or ``!~*`` will be used.
|
| .. versionadded:: 1.4
|
| .. versionchanged:: 1.4.48, 2.0.18 Note that due to an implementation
| error, the "flags" parameter previously accepted SQL expression
| objects such as column expressions in addition to plain Python
| strings. This implementation did not work correctly with caching
| and was removed; strings only should be passed for the "flags"
| parameter, as these flags are rendered as literal inline values
| within SQL expressions.
|
| .. seealso::
|
| :meth:`_sql.ColumnOperators.regexp_replace`
|
| regexp_replace(self, pattern: 'Any', replacement: 'Any', flags: 'Optional[str]' = None) -> 'ColumnOperators'
| Implements a database-specific 'regexp replace' operator.
|
| E.g.::
|
| stmt = select(
| table.c.some_column.regexp_replace("b(..)", "XY", flags="g")
| )
|
| :meth:`_sql.ColumnOperators.regexp_replace` attempts to resolve to
| a REGEXP_REPLACE-like function provided by the backend, that
| usually emit the function ``REGEXP_REPLACE()``. However,
| the specific regular expression syntax and flags available are
| **not backend agnostic**.
|
| Regular expression replacement support is currently implemented for
| Oracle Database, PostgreSQL, MySQL 8 or greater and MariaDB. Support
| among third-party dialects may vary.
|
| :param pattern: The regular expression pattern string or column
| clause.
| :param pattern: The replacement string or column clause.
| :param flags: Any regular expression string flags to apply, passed as
| plain Python string only. These flags are backend specific.
| Some backends, like PostgreSQL and MariaDB, may alternatively
| specify the flags as part of the pattern.
|
| .. versionadded:: 1.4
|
| .. versionchanged:: 1.4.48, 2.0.18 Note that due to an implementation
| error, the "flags" parameter previously accepted SQL expression
| objects such as column expressions in addition to plain Python
| strings. This implementation did not work correctly with caching
| and was removed; strings only should be passed for the "flags"
| parameter, as these flags are rendered as literal inline values
| within SQL expressions.
|
|
| .. seealso::
|
| :meth:`_sql.ColumnOperators.regexp_match`
|
| startswith(self, other: 'Any', escape: 'Optional[str]' = None, autoescape: 'bool' = False) -> 'ColumnOperators'
| Implement the ``startswith`` operator.
|
| Produces a LIKE expression that tests against a match for the start
| of a string value:
|
| .. sourcecode:: sql
|
| column LIKE <other> || '%'
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.startswith("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.startswith.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.startswith.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.startswith.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.startswith("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE :param || '%' ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.startswith("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE :param || '%' ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.startswith.autoescape`::
|
| somecolumn.startswith("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.endswith`
|
| :meth:`.ColumnOperators.contains`
|
| :meth:`.ColumnOperators.like`
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.operators.ColumnOperators:
|
| timetuple = None
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.operators.Operators:
|
| __and__(self, other: 'Any') -> 'Operators'
| Implement the ``&`` operator.
|
| When used with SQL expressions, results in an
| AND operation, equivalent to
| :func:`_expression.and_`, that is::
|
| a & b
|
| is equivalent to::
|
| from sqlalchemy import and_
|
| and_(a, b)
|
| Care should be taken when using ``&`` regarding
| operator precedence; the ``&`` operator has the highest precedence.
| The operands should be enclosed in parenthesis if they contain
| further sub expressions::
|
| (a == 2) & (b == 4)
|
| __invert__(self) -> 'Operators'
| Implement the ``~`` operator.
|
| When used with SQL expressions, results in a
| NOT operation, equivalent to
| :func:`_expression.not_`, that is::
|
| ~a
|
| is equivalent to::
|
| from sqlalchemy import not_
|
| not_(a)
|
| __or__(self, other: 'Any') -> 'Operators'
| Implement the ``|`` operator.
|
| When used with SQL expressions, results in an
| OR operation, equivalent to
| :func:`_expression.or_`, that is::
|
| a | b
|
| is equivalent to::
|
| from sqlalchemy import or_
|
| or_(a, b)
|
| Care should be taken when using ``|`` regarding
| operator precedence; the ``|`` operator has the highest precedence.
| The operands should be enclosed in parenthesis if they contain
| further sub expressions::
|
| (a == 2) | (b == 4)
|
| __sa_operate__ = operate(self, op: 'OperatorType', *other: 'Any', **kwargs: 'Any') -> 'Operators'
|
| bool_op(self, opstring: 'str', precedence: 'int' = 0, python_impl: 'Optional[Callable[..., Any]]' = None) -> 'Callable[[Any], Operators]'
| Return a custom boolean operator.
|
| This method is shorthand for calling
| :meth:`.Operators.op` and passing the
| :paramref:`.Operators.op.is_comparison`
| flag with True. A key advantage to using :meth:`.Operators.bool_op`
| is that when using column constructs, the "boolean" nature of the
| returned expression will be present for :pep:`484` purposes.
|
| .. seealso::
|
| :meth:`.Operators.op`
|
| op(self, opstring: 'str', precedence: 'int' = 0, is_comparison: 'bool' = False, return_type: 'Optional[Union[Type[TypeEngine[Any]], TypeEngine[Any]]]' = None, python_impl: 'Optional[Callable[..., Any]]' = None) -> 'Callable[[Any], Operators]'
| Produce a generic operator function.
|
| e.g.::
|
| somecolumn.op("*")(5)
|
| produces::
|
| somecolumn * 5
|
| This function can also be used to make bitwise operators explicit. For
| example::
|
| somecolumn.op("&")(0xFF)
|
| is a bitwise AND of the value in ``somecolumn``.
|
| :param opstring: a string which will be output as the infix operator
| between this element and the expression passed to the
| generated function.
|
| :param precedence: precedence which the database is expected to apply
| to the operator in SQL expressions. This integer value acts as a hint
| for the SQL compiler to know when explicit parenthesis should be
| rendered around a particular operation. A lower number will cause the
| expression to be parenthesized when applied against another operator
| with higher precedence. The default value of ``0`` is lower than all
| operators except for the comma (``,``) and ``AS`` operators. A value
| of 100 will be higher or equal to all operators, and -100 will be
| lower than or equal to all operators.
|
| .. seealso::
|
| :ref:`faq_sql_expression_op_parenthesis` - detailed description
| of how the SQLAlchemy SQL compiler renders parenthesis
|
| :param is_comparison: legacy; if True, the operator will be considered
| as a "comparison" operator, that is which evaluates to a boolean
| true/false value, like ``==``, ``>``, etc. This flag is provided
| so that ORM relationships can establish that the operator is a
| comparison operator when used in a custom join condition.
|
| Using the ``is_comparison`` parameter is superseded by using the
| :meth:`.Operators.bool_op` method instead; this more succinct
| operator sets this parameter automatically, but also provides
| correct :pep:`484` typing support as the returned object will
| express a "boolean" datatype, i.e. ``BinaryExpression[bool]``.
|
| :param return_type: a :class:`.TypeEngine` class or object that will
| force the return type of an expression produced by this operator
| to be of that type. By default, operators that specify
| :paramref:`.Operators.op.is_comparison` will resolve to
| :class:`.Boolean`, and those that do not will be of the same
| type as the left-hand operand.
|
| :param python_impl: an optional Python function that can evaluate
| two Python values in the same way as this operator works when
| run on the database server. Useful for in-Python SQL expression
| evaluation functions, such as for ORM hybrid attributes, and the
| ORM "evaluator" used to match objects in a session after a multi-row
| update or delete.
|
| e.g.::
|
| >>> expr = column("x").op("+", python_impl=lambda a, b: a + b)("y")
|
| The operator for the above expression will also work for non-SQL
| left and right objects::
|
| >>> expr.operator(5, 10)
| 15
|
| .. versionadded:: 2.0
|
|
| .. seealso::
|
| :meth:`.Operators.bool_op`
|
| :ref:`types_operators`
|
| :ref:`relationship_custom_operator`
|
| operate(self, op: 'OperatorType', *other: 'Any', **kwargs: 'Any') -> 'Operators'
| Operate on an argument.
|
| This is the lowest level of operation, raises
| :class:`NotImplementedError` by default.
|
| Overriding this on a subclass can allow common
| behavior to be applied to all operations.
| For example, overriding :class:`.ColumnOperators`
| to apply ``func.lower()`` to the left and right
| side::
|
| class MyComparator(ColumnOperators):
| def operate(self, op, other, **kwargs):
| return op(func.lower(self), func.lower(other), **kwargs)
|
| :param op: Operator callable.
| :param \*other: the 'other' side of the operation. Will
| be a single scalar for most operations.
| :param \**kwargs: modifiers. These may be passed by special
| operators such as :meth:`ColumnOperators.contains`.
|
| reverse_operate(self, op: 'OperatorType', other: 'Any', **kwargs: 'Any') -> 'Operators'
| Reverse operate on an argument.
|
| Usage is the same as :meth:`operate`.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.SQLRole:
|
| allows_lambda = False
|
| uses_inspection = False
sqlalchemy.SavepointClause
Python Library Documentation: class SavepointClause in module sqlalchemy.sql.elements
class SavepointClause(_IdentifiedClause)
| SavepointClause(ident)
|
| Method resolution order:
| SavepointClause
| _IdentifiedClause
| sqlalchemy.sql.base.Executable
| sqlalchemy.sql.roles.StatementRole
| sqlalchemy.sql.roles.SQLRole
| ClauseElement
| sqlalchemy.sql.annotation.SupportsWrappingAnnotations
| sqlalchemy.sql.annotation.SupportsAnnotations
| sqlalchemy.sql.cache_key.MemoizedHasCacheKey
| sqlalchemy.sql.cache_key.HasCacheKey
| sqlalchemy.util.langhelpers.HasMemoized
| sqlalchemy.sql.traversals.HasCopyInternals
| sqlalchemy.sql.visitors.ExternallyTraversible
| sqlalchemy.sql.visitors.HasTraverseInternals
| CompilerElement
| sqlalchemy.sql.visitors.Visitable
| builtins.object
|
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| __visit_name__ = 'savepoint'
|
| inherit_cache = False
|
| ----------------------------------------------------------------------
| Methods inherited from _IdentifiedClause:
|
| __init__(self, ident)
| Initialize self. See help(type(self)) for accurate signature.
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.base.Executable:
|
| execution_options(self, **kw: 'Any') -> 'Self'
| Set non-SQL options for the statement which take effect during
| execution.
|
| Execution options can be set at many scopes, including per-statement,
| per-connection, or per execution, using methods such as
| :meth:`_engine.Connection.execution_options` and parameters which
| accept a dictionary of options such as
| :paramref:`_engine.Connection.execute.execution_options` and
| :paramref:`_orm.Session.execute.execution_options`.
|
| The primary characteristic of an execution option, as opposed to
| other kinds of options such as ORM loader options, is that
| **execution options never affect the compiled SQL of a query, only
| things that affect how the SQL statement itself is invoked or how
| results are fetched**. That is, execution options are not part of
| what's accommodated by SQL compilation nor are they considered part of
| the cached state of a statement.
|
| The :meth:`_sql.Executable.execution_options` method is
| :term:`generative`, as
| is the case for the method as applied to the :class:`_engine.Engine`
| and :class:`_orm.Query` objects, which means when the method is called,
| a copy of the object is returned, which applies the given parameters to
| that new copy, but leaves the original unchanged::
|
| statement = select(table.c.x, table.c.y)
| new_statement = statement.execution_options(my_option=True)
|
| An exception to this behavior is the :class:`_engine.Connection`
| object, where the :meth:`_engine.Connection.execution_options` method
| is explicitly **not** generative.
|
| The kinds of options that may be passed to
| :meth:`_sql.Executable.execution_options` and other related methods and
| parameter dictionaries include parameters that are explicitly consumed
| by SQLAlchemy Core or ORM, as well as arbitrary keyword arguments not
| defined by SQLAlchemy, which means the methods and/or parameter
| dictionaries may be used for user-defined parameters that interact with
| custom code, which may access the parameters using methods such as
| :meth:`_sql.Executable.get_execution_options` and
| :meth:`_engine.Connection.get_execution_options`, or within selected
| event hooks using a dedicated ``execution_options`` event parameter
| such as
| :paramref:`_events.ConnectionEvents.before_execute.execution_options`
| or :attr:`_orm.ORMExecuteState.execution_options`, e.g.::
|
| from sqlalchemy import event
|
|
| @event.listens_for(some_engine, "before_execute")
| def _process_opt(conn, statement, multiparams, params, execution_options):
| "run a SQL function before invoking a statement"
|
| if execution_options.get("do_special_thing", False):
| conn.exec_driver_sql("run_special_function()")
|
| Within the scope of options that are explicitly recognized by
| SQLAlchemy, most apply to specific classes of objects and not others.
| The most common execution options include:
|
| * :paramref:`_engine.Connection.execution_options.isolation_level` -
| sets the isolation level for a connection or a class of connections
| via an :class:`_engine.Engine`. This option is accepted only
| by :class:`_engine.Connection` or :class:`_engine.Engine`.
|
| * :paramref:`_engine.Connection.execution_options.stream_results` -
| indicates results should be fetched using a server side cursor;
| this option is accepted by :class:`_engine.Connection`, by the
| :paramref:`_engine.Connection.execute.execution_options` parameter
| on :meth:`_engine.Connection.execute`, and additionally by
| :meth:`_sql.Executable.execution_options` on a SQL statement object,
| as well as by ORM constructs like :meth:`_orm.Session.execute`.
|
| * :paramref:`_engine.Connection.execution_options.compiled_cache` -
| indicates a dictionary that will serve as the
| :ref:`SQL compilation cache <sql_caching>`
| for a :class:`_engine.Connection` or :class:`_engine.Engine`, as
| well as for ORM methods like :meth:`_orm.Session.execute`.
| Can be passed as ``None`` to disable caching for statements.
| This option is not accepted by
| :meth:`_sql.Executable.execution_options` as it is inadvisable to
| carry along a compilation cache within a statement object.
|
| * :paramref:`_engine.Connection.execution_options.schema_translate_map`
| - a mapping of schema names used by the
| :ref:`Schema Translate Map <schema_translating>` feature, accepted
| by :class:`_engine.Connection`, :class:`_engine.Engine`,
| :class:`_sql.Executable`, as well as by ORM constructs
| like :meth:`_orm.Session.execute`.
|
| .. seealso::
|
| :meth:`_engine.Connection.execution_options`
|
| :paramref:`_engine.Connection.execute.execution_options`
|
| :paramref:`_orm.Session.execute.execution_options`
|
| :ref:`orm_queryguide_execution_options` - documentation on all
| ORM-specific execution options
|
| get_execution_options(self) -> '_ExecuteOptions'
| Get the non-SQL options which will take effect during execution.
|
| .. versionadded:: 1.3
|
| .. seealso::
|
| :meth:`.Executable.execution_options`
|
| options(self, *options: 'ExecutableOption') -> 'Self'
| Apply options to this statement.
|
| In the general sense, options are any kind of Python object
| that can be interpreted by the SQL compiler for the statement.
| These options can be consumed by specific dialects or specific kinds
| of compilers.
|
| The most commonly known kind of option are the ORM level options
| that apply "eager load" and other loading behaviors to an ORM
| query. However, options can theoretically be used for many other
| purposes.
|
| For background on specific kinds of options for specific kinds of
| statements, refer to the documentation for those option objects.
|
| .. versionchanged:: 1.4 - added :meth:`.Executable.options` to
| Core statement objects towards the goal of allowing unified
| Core / ORM querying capabilities.
|
| .. seealso::
|
| :ref:`loading_columns` - refers to options specific to the usage
| of ORM queries
|
| :ref:`relationship_loader_options` - refers to options specific
| to the usage of ORM queries
|
| ----------------------------------------------------------------------
| Data descriptors inherited from sqlalchemy.sql.base.Executable:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.base.Executable:
|
| is_delete = False
|
| is_dml = False
|
| is_from_statement = False
|
| is_insert = False
|
| is_select = False
|
| is_text = False
|
| is_update = False
|
| supports_execution = True
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.SQLRole:
|
| allows_lambda = False
|
| uses_inspection = False
|
| ----------------------------------------------------------------------
| Methods inherited from ClauseElement:
|
| __bool__(self)
|
| __getstate__(self)
| Helper for pickle.
|
| __invert__(self)
|
| __repr__(self)
| Return repr(self).
|
| compare(self, other: 'ClauseElement', **kw: 'Any') -> 'bool'
| Compare this :class:`_expression.ClauseElement` to
| the given :class:`_expression.ClauseElement`.
|
| Subclasses should override the default behavior, which is a
| straight identity comparison.
|
| \**kw are arguments consumed by subclass ``compare()`` methods and
| may be used to modify the criteria for comparison
| (see :class:`_expression.ColumnElement`).
|
| description(...)
|
| entity_namespace(...)
|
| params(self, _ClauseElement__optionaldict: 'Optional[Mapping[str, Any]]' = None, **kwargs: 'Any') -> 'Self'
| Return a copy with :func:`_expression.bindparam` elements
| replaced.
|
| Returns a copy of this ClauseElement with
| :func:`_expression.bindparam`
| elements replaced with values taken from the given dictionary::
|
| >>> clause = column("x") + bindparam("foo")
| >>> print(clause.compile().params)
| {'foo':None}
| >>> print(clause.params({"foo": 7}).compile().params)
| {'foo':7}
|
| self_group(self, against: 'Optional[OperatorType]' = None) -> 'ClauseElement'
| 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.
|
| unique_params(self, _ClauseElement__optionaldict: 'Optional[Dict[str, Any]]' = None, **kwargs: 'Any') -> 'Self'
| Return a copy with :func:`_expression.bindparam` elements
| replaced.
|
| Same functionality as :meth:`_expression.ClauseElement.params`,
| except adds `unique=True`
| to affected bind parameters so that multiple statements can be
| used.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from ClauseElement:
|
| is_clause_element = True
|
| is_selectable = False
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_instancemethod(fn: '_F') -> '_F'
| Decorate a method memoize its return value.
|
| :meta private:
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_attribute = <class 'sqlalchemy.util.langhelpers.HasMemoized.m...
| A read-only @property that is only evaluated once.
|
| :meta private:
|
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.visitors.HasTraverseInternals:
|
| get_children(self, *, omit_attrs: 'Tuple[str, ...]' = (), **kw: 'Any') -> 'Iterable[HasTraverseInternals]'
| Return immediate child :class:`.visitors.HasTraverseInternals`
| elements of this :class:`.visitors.HasTraverseInternals`.
|
| This is used for visit traversal.
|
| \**kw may contain flags that change the collection that is
| returned, for example to return a subset of items in order to
| cut down on larger traversals, or to return child items from a
| different context (such as schema-level collections instead of
| clause-level).
|
| ----------------------------------------------------------------------
| Methods inherited from CompilerElement:
|
| __str__(self) -> 'str'
| Return str(self).
|
| compile(self, bind: 'Optional[_HasDialect]' = None, dialect: 'Optional[Dialect]' = None, **kw: 'Any') -> 'Compiled'
| Compile this SQL expression.
|
| The return value is a :class:`~.Compiled` object.
| Calling ``str()`` or ``unicode()`` on the returned value will yield a
| string representation of the result. The
| :class:`~.Compiled` object also can return a
| dictionary of bind parameter names and values
| using the ``params`` accessor.
|
| :param bind: An :class:`.Connection` or :class:`.Engine` which
| can provide a :class:`.Dialect` in order to generate a
| :class:`.Compiled` object. If the ``bind`` and
| ``dialect`` parameters are both omitted, a default SQL compiler
| is used.
|
| :param column_keys: Used for INSERT and UPDATE statements, a list of
| column names which should be present in the VALUES clause of the
| compiled statement. If ``None``, all columns from the target table
| object are rendered.
|
| :param dialect: A :class:`.Dialect` instance which can generate
| a :class:`.Compiled` object. This argument takes precedence over
| the ``bind`` argument.
|
| :param compile_kwargs: optional dictionary of additional parameters
| that will be passed through to the compiler within all "visit"
| methods. This allows any custom flag to be passed through to
| a custom compilation construct, for example. It is also used
| for the case of passing the ``literal_binds`` flag through::
|
| from sqlalchemy.sql import table, column, select
|
| t = table("t", column("x"))
|
| s = select(t).where(t.c.x == 5)
|
| print(s.compile(compile_kwargs={"literal_binds": True}))
|
| .. seealso::
|
| :ref:`faq_sql_expression_string`
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from CompilerElement:
|
| stringify_dialect = 'default'
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.visitors.Visitable:
|
| __class_getitem__(key: 'Any') -> 'Any'
|
| __init_subclass__() -> 'None'
| This method is called when a class is subclassed.
|
| The default implementation does nothing. It may be
| overridden to extend subclasses.
sqlalchemy.ScalarResult
Python Library Documentation: class ScalarResult in module sqlalchemy.engine.result
class ScalarResult(FilterResult)
| ScalarResult(real_result: 'Result[Any]', index: '_KeyIndexType')
|
| A wrapper for a :class:`_engine.Result` that returns scalar values
| rather than :class:`_row.Row` values.
|
| The :class:`_engine.ScalarResult` object is acquired by calling the
| :meth:`_engine.Result.scalars` method.
|
| A special limitation of :class:`_engine.ScalarResult` is that it has
| no ``fetchone()`` method; since the semantics of ``fetchone()`` are that
| the ``None`` value indicates no more results, this is not compatible
| with :class:`_engine.ScalarResult` since there is no way to distinguish
| between ``None`` as a row value versus ``None`` as an indicator. Use
| ``next(result)`` to receive values individually.
|
| Method resolution order:
| ScalarResult
| FilterResult
| ResultInternal
| sqlalchemy.sql.base.InPlaceGenerative
| sqlalchemy.util.langhelpers.HasMemoized
| typing.Generic
| builtins.object
|
| Methods defined here:
|
| __init__(self, real_result: 'Result[Any]', index: '_KeyIndexType')
| Initialize self. See help(type(self)) for accurate signature.
|
| __iter__(self) -> 'Iterator[_R]'
|
| __next__(self) -> '_R'
|
| all(self) -> 'Sequence[_R]'
| Return all scalar values in a sequence.
|
| Equivalent to :meth:`_engine.Result.all` except that
| scalar values, rather than :class:`_engine.Row` objects,
| are returned.
|
| fetchall(self) -> 'Sequence[_R]'
| A synonym for the :meth:`_engine.ScalarResult.all` method.
|
| fetchmany(self, size: 'Optional[int]' = None) -> 'Sequence[_R]'
| Fetch many objects.
|
| Equivalent to :meth:`_engine.Result.fetchmany` except that
| scalar values, rather than :class:`_engine.Row` objects,
| are returned.
|
| first(self) -> 'Optional[_R]'
| Fetch the first object or ``None`` if no object is present.
|
| Equivalent to :meth:`_engine.Result.first` except that
| scalar values, rather than :class:`_engine.Row` objects,
| are returned.
|
| one(self) -> '_R'
| Return exactly one object or raise an exception.
|
| Equivalent to :meth:`_engine.Result.one` except that
| scalar values, rather than :class:`_engine.Row` objects,
| are returned.
|
| one_or_none(self) -> 'Optional[_R]'
| Return at most one object or raise an exception.
|
| Equivalent to :meth:`_engine.Result.one_or_none` except that
| scalar values, rather than :class:`_engine.Row` objects,
| are returned.
|
| partitions(self, size: 'Optional[int]' = None) -> 'Iterator[Sequence[_R]]'
| Iterate through sub-lists of elements of the size given.
|
| Equivalent to :meth:`_engine.Result.partitions` except that
| scalar values, rather than :class:`_engine.Row` objects,
| are returned.
|
| unique(self, strategy: 'Optional[_UniqueFilterType]' = None) -> 'Self'
| Apply unique filtering to the objects returned by this
| :class:`_engine.ScalarResult`.
|
| See :meth:`_engine.Result.unique` for usage details.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'_post_creational_filter': 'Optional[Callable[[Any]...
|
| __orig_bases__ = (sqlalchemy.engine.result.FilterResult[~_R],)
|
| __parameters__ = (~_R,)
|
| ----------------------------------------------------------------------
| Methods inherited from FilterResult:
|
| __enter__(self) -> 'Self'
|
| __exit__(self, type_: 'Any', value: 'Any', traceback: 'Any') -> 'None'
|
| close(self) -> 'None'
| Close this :class:`_engine.FilterResult`.
|
| .. versionadded:: 1.4.43
|
| yield_per(self, num: 'int') -> 'Self'
| Configure the row-fetching strategy to fetch ``num`` rows at a time.
|
| The :meth:`_engine.FilterResult.yield_per` method is a pass through
| to the :meth:`_engine.Result.yield_per` method. See that method's
| documentation for usage notes.
|
| .. versionadded:: 1.4.40 - added :meth:`_engine.FilterResult.yield_per`
| so that the method is available on all result set implementations
|
| .. seealso::
|
| :ref:`engine_stream_results` - describes Core behavior for
| :meth:`_engine.Result.yield_per`
|
| :ref:`orm_queryguide_yield_per` - in the :ref:`queryguide_toplevel`
|
| ----------------------------------------------------------------------
| Readonly properties inherited from FilterResult:
|
| closed
| Return ``True`` if this :class:`_engine.Result` being
| proxied by this :class:`_engine.FilterResult` was
| **hard closed** by explicitly calling the :meth:`_engine.Result.close`
| method.
|
| This is a direct proxy for the :attr:`_engine.Result.closed` attribute;
| see that attribute for details.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from FilterResult:
|
| __dict__
| dictionary for instance variables
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_instancemethod(fn: '_F') -> '_F'
| Decorate a method memoize its return value.
|
| :meta private:
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_attribute = <class 'sqlalchemy.util.langhelpers.HasMemoized.m...
| A read-only @property that is only evaluated once.
|
| :meta private:
|
|
| ----------------------------------------------------------------------
| Class methods inherited from typing.Generic:
|
| __class_getitem__(...)
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__(...)
| Function to initialize subclasses.
sqlalchemy.ScalarSelect
Python Library Documentation: class ScalarSelect in module sqlalchemy.sql.selectable
class ScalarSelect(sqlalchemy.sql.roles.InElementRole, sqlalchemy.sql.base.Generative, sqlalchemy.sql.elements.GroupedElement, sqlalchemy.sql.elements.ColumnElement)
| ScalarSelect(element: 'SelectBase') -> 'None'
|
| Represent a scalar subquery.
|
|
| A :class:`_sql.ScalarSelect` is created by invoking the
| :meth:`_sql.SelectBase.scalar_subquery` method. The object
| then participates in other SQL expressions as a SQL column expression
| within the :class:`_sql.ColumnElement` hierarchy.
|
| .. seealso::
|
| :meth:`_sql.SelectBase.scalar_subquery`
|
| :ref:`tutorial_scalar_subquery` - in the 2.0 tutorial
|
| Method resolution order:
| ScalarSelect
| sqlalchemy.sql.roles.InElementRole
| sqlalchemy.sql.base.Generative
| sqlalchemy.sql.elements.GroupedElement
| sqlalchemy.sql.elements.ColumnElement
| sqlalchemy.sql.roles.ColumnArgumentOrKeyRole
| sqlalchemy.sql.roles.ColumnArgumentRole
| sqlalchemy.sql.roles.StatementOptionRole
| sqlalchemy.sql.roles.WhereHavingRole
| sqlalchemy.sql.roles.OnClauseRole
| sqlalchemy.sql.roles.BinaryElementRole
| sqlalchemy.sql.roles.OrderByRole
| sqlalchemy.sql.roles.ColumnsClauseRole
| sqlalchemy.sql.roles.AllowsLambdaRole
| sqlalchemy.sql.roles.ByOfRole
| sqlalchemy.sql.roles.UsesInspection
| sqlalchemy.sql.roles.ColumnListRole
| sqlalchemy.sql.roles.LimitOffsetRole
| sqlalchemy.sql.roles.DMLColumnRole
| sqlalchemy.sql.roles.DDLConstraintColumnRole
| sqlalchemy.sql.roles.DDLExpressionRole
| sqlalchemy.sql.roles.StructuralRole
| sqlalchemy.sql.elements.SQLColumnExpression
| sqlalchemy.sql.elements.SQLCoreOperations
| sqlalchemy.sql.roles.ExpressionElementRole
| sqlalchemy.sql.roles.TypedColumnsClauseRole
| typing.Generic
| sqlalchemy.sql.operators.ColumnOperators
| sqlalchemy.sql.operators.Operators
| sqlalchemy.util.langhelpers.TypingOnly
| sqlalchemy.sql.roles.SQLRole
| sqlalchemy.sql.elements.DQLDMLClauseElement
| sqlalchemy.sql.elements.ClauseElement
| sqlalchemy.sql.annotation.SupportsWrappingAnnotations
| sqlalchemy.sql.annotation.SupportsAnnotations
| sqlalchemy.sql.cache_key.MemoizedHasCacheKey
| sqlalchemy.sql.cache_key.HasCacheKey
| sqlalchemy.util.langhelpers.HasMemoized
| sqlalchemy.sql.traversals.HasCopyInternals
| sqlalchemy.sql.visitors.ExternallyTraversible
| sqlalchemy.sql.visitors.HasTraverseInternals
| sqlalchemy.sql.elements.CompilerElement
| sqlalchemy.sql.visitors.Visitable
| builtins.object
|
| Methods defined here:
|
| __getattr__(self, attr: 'str') -> 'Any'
|
| __getstate__(self) -> 'Dict[str, Any]'
| Helper for pickle.
|
| __init__(self, element: 'SelectBase') -> 'None'
| Initialize self. See help(type(self)) for accurate signature.
|
| __setstate__(self, state: 'Dict[str, Any]') -> 'None'
|
| correlate(self, *fromclauses: 'Union[Literal[None, False], _FromClauseArgument]') -> 'Self'
| Return a new :class:`_expression.ScalarSelect`
| which will correlate the given FROM
| clauses to that of an enclosing :class:`_expression.Select`.
|
| This method is mirrored from the :meth:`_sql.Select.correlate` method
| of the underlying :class:`_sql.Select`. The method applies the
| :meth:_sql.Select.correlate` method, then returns a new
| :class:`_sql.ScalarSelect` against that statement.
|
| .. versionadded:: 1.4 Previously, the
| :meth:`_sql.ScalarSelect.correlate`
| method was only available from :class:`_sql.Select`.
|
| :param \*fromclauses: a list of one or more
| :class:`_expression.FromClause`
| constructs, or other compatible constructs (i.e. ORM-mapped
| classes) to become part of the correlate collection.
|
| .. seealso::
|
| :meth:`_expression.ScalarSelect.correlate_except`
|
| :ref:`tutorial_scalar_subquery` - in the 2.0 tutorial
|
| correlate_except(self, *fromclauses: 'Union[Literal[None, False], _FromClauseArgument]') -> 'Self'
| Return a new :class:`_expression.ScalarSelect`
| which will omit the given FROM
| clauses from the auto-correlation process.
|
| This method is mirrored from the
| :meth:`_sql.Select.correlate_except` method of the underlying
| :class:`_sql.Select`. The method applies the
| :meth:_sql.Select.correlate_except` method, then returns a new
| :class:`_sql.ScalarSelect` against that statement.
|
| .. versionadded:: 1.4 Previously, the
| :meth:`_sql.ScalarSelect.correlate_except`
| method was only available from :class:`_sql.Select`.
|
| :param \*fromclauses: a list of one or more
| :class:`_expression.FromClause`
| constructs, or other compatible constructs (i.e. ORM-mapped
| classes) to become part of the correlate-exception collection.
|
| .. seealso::
|
| :meth:`_expression.ScalarSelect.correlate`
|
| :ref:`tutorial_scalar_subquery` - in the 2.0 tutorial
|
| self_group(self, against: 'Optional[OperatorType]' = None) -> 'Self'
| 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.
|
| where(self, crit: '_ColumnExpressionArgument[bool]') -> 'Self'
| Apply a WHERE clause to the SELECT statement referred to
| by this :class:`_expression.ScalarSelect`.
|
| ----------------------------------------------------------------------
| Readonly properties defined here:
|
| c
|
| columns
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'_from_objects': 'List[FromClause]', '_traverse_int...
|
| __orig_bases__ = (<class 'sqlalchemy.sql.roles.InElementRole'>, <class...
|
| __parameters__ = (~_T,)
|
| inherit_cache = True
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.elements.GroupedElement:
|
| __visit_name__ = 'grouping'
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.elements.ColumnElement:
|
| base_columns(...)
|
| cast(self, type_: '_TypeEngineArgument[_OPT]') -> 'Cast[_OPT]'
| Produce a type cast, i.e. ``CAST(<expression> AS <type>)``.
|
| This is a shortcut to the :func:`_expression.cast` function.
|
| .. seealso::
|
| :ref:`tutorial_casts`
|
| :func:`_expression.cast`
|
| :func:`_expression.type_coerce`
|
| comparator(...)
|
| label(self, name: 'Optional[str]') -> 'Label[_T]'
| Produce a column label, i.e. ``<columnname> AS <name>``.
|
| This is a shortcut to the :func:`_expression.label` function.
|
| If 'name' is ``None``, an anonymous label name will be generated.
|
| operate(self, op: 'operators.OperatorType', *other: 'Any', **kwargs: 'Any') -> 'ColumnElement[Any]'
| Operate on an argument.
|
| This is the lowest level of operation, raises
| :class:`NotImplementedError` by default.
|
| Overriding this on a subclass can allow common
| behavior to be applied to all operations.
| For example, overriding :class:`.ColumnOperators`
| to apply ``func.lower()`` to the left and right
| side::
|
| class MyComparator(ColumnOperators):
| def operate(self, op, other, **kwargs):
| return op(func.lower(self), func.lower(other), **kwargs)
|
| :param op: Operator callable.
| :param \*other: the 'other' side of the operation. Will
| be a single scalar for most operations.
| :param \**kwargs: modifiers. These may be passed by special
| operators such as :meth:`ColumnOperators.contains`.
|
| proxy_set(...)
| set of all columns we are proxying
|
| as of 2.0 this is explicitly deannotated columns. previously it was
| effectively deannotated columns but wasn't enforced. annotated
| columns should basically not go into sets if at all possible because
| their hashing behavior is very non-performant.
|
| reverse_operate(self, op: 'operators.OperatorType', other: 'Any', **kwargs: 'Any') -> 'ColumnElement[Any]'
| Reverse operate on an argument.
|
| Usage is the same as :meth:`operate`.
|
| shares_lineage(self, othercolumn: 'ColumnElement[Any]') -> 'bool'
| Return True if the given :class:`_expression.ColumnElement`
| has a common ancestor to this :class:`_expression.ColumnElement`.
|
| type(...)
|
| ----------------------------------------------------------------------
| Readonly properties inherited from sqlalchemy.sql.elements.ColumnElement:
|
| anon_key_label
| .. deprecated:: 1.4 The :attr:`_expression.ColumnElement.anon_key_label` attribute is now private, and the public accessor is deprecated.
|
| anon_label
| .. deprecated:: 1.4 The :attr:`_expression.ColumnElement.anon_label` attribute is now private, and the public accessor is deprecated.
|
| expression
| Return a column expression.
|
| Part of the inspection interface; returns self.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.elements.ColumnElement:
|
| foreign_keys = frozenset()
|
| key = None
|
| primary_key = False
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.AllowsLambdaRole:
|
| allows_lambda = True
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.UsesInspection:
|
| uses_inspection = True
|
| ----------------------------------------------------------------------
| Class methods inherited from typing.Generic:
|
| __class_getitem__(...)
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__(...)
| Function to initialize subclasses.
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.operators.ColumnOperators:
|
| __add__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``+`` operator.
|
| In a column context, produces the clause ``a + b``
| if the parent object has non-string affinity.
| If the parent object has a string affinity,
| produces the concatenation operator, ``a || b`` -
| see :meth:`.ColumnOperators.concat`.
|
| __contains__(self, other: 'Any') -> 'ColumnOperators'
|
| __eq__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``==`` operator.
|
| In a column context, produces the clause ``a = b``.
| If the target is ``None``, produces ``a IS NULL``.
|
| __floordiv__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``//`` operator.
|
| In a column context, produces the clause ``a / b``,
| which is the same as "truediv", but considers the result
| type to be integer.
|
| .. versionadded:: 2.0
|
| __ge__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``>=`` operator.
|
| In a column context, produces the clause ``a >= b``.
|
| __getitem__(self, index: 'Any') -> 'ColumnOperators'
| Implement the [] operator.
|
| This can be used by some database-specific types
| such as PostgreSQL ARRAY and HSTORE.
|
| __gt__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``>`` operator.
|
| In a column context, produces the clause ``a > b``.
|
| __hash__(self, /) from builtins.object
| Return hash(self).
|
| __le__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``<=`` operator.
|
| In a column context, produces the clause ``a <= b``.
|
| __lshift__(self, other: 'Any') -> 'ColumnOperators'
| implement the << operator.
|
| Not used by SQLAlchemy core, this is provided
| for custom operator systems which want to use
| << as an extension point.
|
| __lt__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``<`` operator.
|
| In a column context, produces the clause ``a < b``.
|
| __mod__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``%`` operator.
|
| In a column context, produces the clause ``a % b``.
|
| __mul__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``*`` operator.
|
| In a column context, produces the clause ``a * b``.
|
| __ne__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``!=`` operator.
|
| In a column context, produces the clause ``a != b``.
| If the target is ``None``, produces ``a IS NOT NULL``.
|
| __neg__(self) -> 'ColumnOperators'
| Implement the ``-`` operator.
|
| In a column context, produces the clause ``-a``.
|
| __radd__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``+`` operator in reverse.
|
| See :meth:`.ColumnOperators.__add__`.
|
| __rfloordiv__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``//`` operator in reverse.
|
| See :meth:`.ColumnOperators.__floordiv__`.
|
| __rmod__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``%`` operator in reverse.
|
| See :meth:`.ColumnOperators.__mod__`.
|
| __rmul__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``*`` operator in reverse.
|
| See :meth:`.ColumnOperators.__mul__`.
|
| __rshift__(self, other: 'Any') -> 'ColumnOperators'
| implement the >> operator.
|
| Not used by SQLAlchemy core, this is provided
| for custom operator systems which want to use
| >> as an extension point.
|
| __rsub__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``-`` operator in reverse.
|
| See :meth:`.ColumnOperators.__sub__`.
|
| __rtruediv__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``/`` operator in reverse.
|
| See :meth:`.ColumnOperators.__truediv__`.
|
| __sub__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``-`` operator.
|
| In a column context, produces the clause ``a - b``.
|
| __truediv__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``/`` operator.
|
| In a column context, produces the clause ``a / b``, and
| considers the result type to be numeric.
|
| .. versionchanged:: 2.0 The truediv operator against two integers
| is now considered to return a numeric value. Behavior on specific
| backends may vary.
|
| all_(self) -> 'ColumnOperators'
| Produce an :func:`_expression.all_` clause against the
| parent object.
|
| See the documentation for :func:`_sql.all_` for examples.
|
| .. note:: be sure to not confuse the newer
| :meth:`_sql.ColumnOperators.all_` method with the **legacy**
| version of this method, the :meth:`_types.ARRAY.Comparator.all`
| method that's specific to :class:`_types.ARRAY`, which uses a
| different calling style.
|
| any_(self) -> 'ColumnOperators'
| Produce an :func:`_expression.any_` clause against the
| parent object.
|
| See the documentation for :func:`_sql.any_` for examples.
|
| .. note:: be sure to not confuse the newer
| :meth:`_sql.ColumnOperators.any_` method with the **legacy**
| version of this method, the :meth:`_types.ARRAY.Comparator.any`
| method that's specific to :class:`_types.ARRAY`, which uses a
| different calling style.
|
| asc(self) -> 'ColumnOperators'
| Produce a :func:`_expression.asc` clause against the
| parent object.
|
| between(self, cleft: 'Any', cright: 'Any', symmetric: 'bool' = False) -> 'ColumnOperators'
| Produce a :func:`_expression.between` clause against
| the parent object, given the lower and upper range.
|
| bitwise_and(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise AND operation, typically via the ``&``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_lshift(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise LSHIFT operation, typically via the ``<<``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_not(self) -> 'ColumnOperators'
| Produce a bitwise NOT operation, typically via the ``~``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_or(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise OR operation, typically via the ``|``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_rshift(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise RSHIFT operation, typically via the ``>>``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_xor(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise XOR operation, typically via the ``^``
| operator, or ``#`` for PostgreSQL.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| collate(self, collation: 'str') -> 'ColumnOperators'
| Produce a :func:`_expression.collate` clause against
| the parent object, given the collation string.
|
| .. seealso::
|
| :func:`_expression.collate`
|
| concat(self, other: 'Any') -> 'ColumnOperators'
| Implement the 'concat' operator.
|
| In a column context, produces the clause ``a || b``,
| or uses the ``concat()`` operator on MySQL.
|
| contains(self, other: 'Any', **kw: 'Any') -> 'ColumnOperators'
| Implement the 'contains' operator.
|
| Produces a LIKE expression that tests against a match for the middle
| of a string value:
|
| .. sourcecode:: sql
|
| column LIKE '%' || <other> || '%'
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.contains("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.contains.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.contains.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.contains.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.contains("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE '%' || :param || '%' ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.contains("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE '%' || :param || '%' ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.contains.autoescape`::
|
| somecolumn.contains("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.startswith`
|
| :meth:`.ColumnOperators.endswith`
|
| :meth:`.ColumnOperators.like`
|
| desc(self) -> 'ColumnOperators'
| Produce a :func:`_expression.desc` clause against the
| parent object.
|
| distinct(self) -> 'ColumnOperators'
| Produce a :func:`_expression.distinct` clause against the
| parent object.
|
| endswith(self, other: 'Any', escape: 'Optional[str]' = None, autoescape: 'bool' = False) -> 'ColumnOperators'
| Implement the 'endswith' operator.
|
| Produces a LIKE expression that tests against a match for the end
| of a string value:
|
| .. sourcecode:: sql
|
| column LIKE '%' || <other>
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.endswith("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.endswith.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.endswith.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.endswith.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.endswith("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE '%' || :param ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.endswith("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE '%' || :param ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.endswith.autoescape`::
|
| somecolumn.endswith("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.startswith`
|
| :meth:`.ColumnOperators.contains`
|
| :meth:`.ColumnOperators.like`
|
| icontains(self, other: 'Any', **kw: 'Any') -> 'ColumnOperators'
| Implement the ``icontains`` operator, e.g. case insensitive
| version of :meth:`.ColumnOperators.contains`.
|
| Produces a LIKE expression that tests against an insensitive match
| for the middle of a string value:
|
| .. sourcecode:: sql
|
| lower(column) LIKE '%' || lower(<other>) || '%'
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.icontains("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.icontains.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.icontains.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.icontains.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.icontains("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE '%' || lower(:param) || '%' ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.icontains("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE '%' || lower(:param) || '%' ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.contains.autoescape`::
|
| somecolumn.icontains("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.contains`
|
| iendswith(self, other: 'Any', escape: 'Optional[str]' = None, autoescape: 'bool' = False) -> 'ColumnOperators'
| Implement the ``iendswith`` operator, e.g. case insensitive
| version of :meth:`.ColumnOperators.endswith`.
|
| Produces a LIKE expression that tests against an insensitive match
| for the end of a string value:
|
| .. sourcecode:: sql
|
| lower(column) LIKE '%' || lower(<other>)
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.iendswith("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.iendswith.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.iendswith.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.iendswith.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.iendswith("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE '%' || lower(:param) ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.iendswith("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE '%' || lower(:param) ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.iendswith.autoescape`::
|
| somecolumn.endswith("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.endswith`
|
| ilike(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
| Implement the ``ilike`` operator, e.g. case insensitive LIKE.
|
| In a column context, produces an expression either of the form:
|
| .. sourcecode:: sql
|
| lower(a) LIKE lower(other)
|
| Or on backends that support the ILIKE operator:
|
| .. sourcecode:: sql
|
| a ILIKE other
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.ilike("%foobar%"))
|
| :param other: expression to be compared
| :param escape: optional escape character, renders the ``ESCAPE``
| keyword, e.g.::
|
| somecolumn.ilike("foo/%bar", escape="/")
|
| .. seealso::
|
| :meth:`.ColumnOperators.like`
|
| in_(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``in`` operator.
|
| In a column context, produces the clause ``column IN <other>``.
|
| The given parameter ``other`` may be:
|
| * A list of literal values,
| e.g.::
|
| stmt.where(column.in_([1, 2, 3]))
|
| In this calling form, the list of items is converted to a set of
| bound parameters the same length as the list given:
|
| .. sourcecode:: sql
|
| WHERE COL IN (?, ?, ?)
|
| * A list of tuples may be provided if the comparison is against a
| :func:`.tuple_` containing multiple expressions::
|
| from sqlalchemy import tuple_
|
| stmt.where(tuple_(col1, col2).in_([(1, 10), (2, 20), (3, 30)]))
|
| * An empty list,
| e.g.::
|
| stmt.where(column.in_([]))
|
| In this calling form, the expression renders an "empty set"
| expression. These expressions are tailored to individual backends
| and are generally trying to get an empty SELECT statement as a
| subquery. Such as on SQLite, the expression is:
|
| .. sourcecode:: sql
|
| WHERE col IN (SELECT 1 FROM (SELECT 1) WHERE 1!=1)
|
| .. versionchanged:: 1.4 empty IN expressions now use an
| execution-time generated SELECT subquery in all cases.
|
| * A bound parameter, e.g. :func:`.bindparam`, may be used if it
| includes the :paramref:`.bindparam.expanding` flag::
|
| stmt.where(column.in_(bindparam("value", expanding=True)))
|
| In this calling form, the expression renders a special non-SQL
| placeholder expression that looks like:
|
| .. sourcecode:: sql
|
| WHERE COL IN ([EXPANDING_value])
|
| This placeholder expression is intercepted at statement execution
| time to be converted into the variable number of bound parameter
| form illustrated earlier. If the statement were executed as::
|
| connection.execute(stmt, {"value": [1, 2, 3]})
|
| The database would be passed a bound parameter for each value:
|
| .. sourcecode:: sql
|
| WHERE COL IN (?, ?, ?)
|
| .. versionadded:: 1.2 added "expanding" bound parameters
|
| If an empty list is passed, a special "empty list" expression,
| which is specific to the database in use, is rendered. On
| SQLite this would be:
|
| .. sourcecode:: sql
|
| WHERE COL IN (SELECT 1 FROM (SELECT 1) WHERE 1!=1)
|
| .. versionadded:: 1.3 "expanding" bound parameters now support
| empty lists
|
| * a :func:`_expression.select` construct, which is usually a
| correlated scalar select::
|
| stmt.where(
| column.in_(select(othertable.c.y).where(table.c.x == othertable.c.x))
| )
|
| In this calling form, :meth:`.ColumnOperators.in_` renders as given:
|
| .. sourcecode:: sql
|
| WHERE COL IN (SELECT othertable.y
| FROM othertable WHERE othertable.x = table.x)
|
| :param other: a list of literals, a :func:`_expression.select`
| construct, or a :func:`.bindparam` construct that includes the
| :paramref:`.bindparam.expanding` flag set to True.
|
| is_(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``IS`` operator.
|
| Normally, ``IS`` is generated automatically when comparing to a
| value of ``None``, which resolves to ``NULL``. However, explicit
| usage of ``IS`` may be desirable if comparing to boolean values
| on certain platforms.
|
| .. seealso:: :meth:`.ColumnOperators.is_not`
|
| is_distinct_from(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``IS DISTINCT FROM`` operator.
|
| Renders "a IS DISTINCT FROM b" on most platforms;
| on some such as SQLite may render "a IS NOT b".
|
| is_not(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``IS NOT`` operator.
|
| Normally, ``IS NOT`` is generated automatically when comparing to a
| value of ``None``, which resolves to ``NULL``. However, explicit
| usage of ``IS NOT`` may be desirable if comparing to boolean values
| on certain platforms.
|
| .. versionchanged:: 1.4 The ``is_not()`` operator is renamed from
| ``isnot()`` in previous releases. The previous name remains
| available for backwards compatibility.
|
| .. seealso:: :meth:`.ColumnOperators.is_`
|
| is_not_distinct_from(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``IS NOT DISTINCT FROM`` operator.
|
| Renders "a IS NOT DISTINCT FROM b" on most platforms;
| on some such as SQLite may render "a IS b".
|
| .. versionchanged:: 1.4 The ``is_not_distinct_from()`` operator is
| renamed from ``isnot_distinct_from()`` in previous releases.
| The previous name remains available for backwards compatibility.
|
| isnot = is_not(self, other: 'Any') -> 'ColumnOperators'
|
| isnot_distinct_from = is_not_distinct_from(self, other: 'Any') -> 'ColumnOperators'
|
| istartswith(self, other: 'Any', escape: 'Optional[str]' = None, autoescape: 'bool' = False) -> 'ColumnOperators'
| Implement the ``istartswith`` operator, e.g. case insensitive
| version of :meth:`.ColumnOperators.startswith`.
|
| Produces a LIKE expression that tests against an insensitive
| match for the start of a string value:
|
| .. sourcecode:: sql
|
| lower(column) LIKE lower(<other>) || '%'
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.istartswith("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.istartswith.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.istartswith.escape` parameter will
| establish a given character as an escape character which can be of
| use when the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.istartswith.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.istartswith("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE lower(:param) || '%' ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.istartswith("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE lower(:param) || '%' ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.istartswith.autoescape`::
|
| somecolumn.istartswith("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.startswith`
|
| like(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
| Implement the ``like`` operator.
|
| In a column context, produces the expression:
|
| .. sourcecode:: sql
|
| a LIKE other
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.like("%foobar%"))
|
| :param other: expression to be compared
| :param escape: optional escape character, renders the ``ESCAPE``
| keyword, e.g.::
|
| somecolumn.like("foo/%bar", escape="/")
|
| .. seealso::
|
| :meth:`.ColumnOperators.ilike`
|
| match(self, other: 'Any', **kwargs: 'Any') -> 'ColumnOperators'
| Implements a database-specific 'match' operator.
|
| :meth:`_sql.ColumnOperators.match` attempts to resolve to
| a MATCH-like function or operator provided by the backend.
| Examples include:
|
| * PostgreSQL - renders ``x @@ plainto_tsquery(y)``
|
| .. versionchanged:: 2.0 ``plainto_tsquery()`` is used instead
| of ``to_tsquery()`` for PostgreSQL now; for compatibility with
| other forms, see :ref:`postgresql_match`.
|
|
| * MySQL - renders ``MATCH (x) AGAINST (y IN BOOLEAN MODE)``
|
| .. seealso::
|
| :class:`_mysql.match` - MySQL specific construct with
| additional features.
|
| * Oracle Database - renders ``CONTAINS(x, y)``
| * other backends may provide special implementations.
| * Backends without any special implementation will emit
| the operator as "MATCH". This is compatible with SQLite, for
| example.
|
| not_ilike(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
| implement the ``NOT ILIKE`` operator.
|
| This is equivalent to using negation with
| :meth:`.ColumnOperators.ilike`, i.e. ``~x.ilike(y)``.
|
| .. versionchanged:: 1.4 The ``not_ilike()`` operator is renamed from
| ``notilike()`` in previous releases. The previous name remains
| available for backwards compatibility.
|
| .. seealso::
|
| :meth:`.ColumnOperators.ilike`
|
| not_in(self, other: 'Any') -> 'ColumnOperators'
| implement the ``NOT IN`` operator.
|
| This is equivalent to using negation with
| :meth:`.ColumnOperators.in_`, i.e. ``~x.in_(y)``.
|
| In the case that ``other`` is an empty sequence, the compiler
| produces an "empty not in" expression. This defaults to the
| expression "1 = 1" to produce true in all cases. The
| :paramref:`_sa.create_engine.empty_in_strategy` may be used to
| alter this behavior.
|
| .. versionchanged:: 1.4 The ``not_in()`` operator is renamed from
| ``notin_()`` in previous releases. The previous name remains
| available for backwards compatibility.
|
| .. versionchanged:: 1.2 The :meth:`.ColumnOperators.in_` and
| :meth:`.ColumnOperators.not_in` operators
| now produce a "static" expression for an empty IN sequence
| by default.
|
| .. seealso::
|
| :meth:`.ColumnOperators.in_`
|
| not_like(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
| implement the ``NOT LIKE`` operator.
|
| This is equivalent to using negation with
| :meth:`.ColumnOperators.like`, i.e. ``~x.like(y)``.
|
| .. versionchanged:: 1.4 The ``not_like()`` operator is renamed from
| ``notlike()`` in previous releases. The previous name remains
| available for backwards compatibility.
|
| .. seealso::
|
| :meth:`.ColumnOperators.like`
|
| notilike = not_ilike(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
|
| notin_ = not_in(self, other: 'Any') -> 'ColumnOperators'
|
| notlike = not_like(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
|
| nulls_first(self) -> 'ColumnOperators'
| Produce a :func:`_expression.nulls_first` clause against the
| parent object.
|
| .. versionchanged:: 1.4 The ``nulls_first()`` operator is
| renamed from ``nullsfirst()`` in previous releases.
| The previous name remains available for backwards compatibility.
|
| nulls_last(self) -> 'ColumnOperators'
| Produce a :func:`_expression.nulls_last` clause against the
| parent object.
|
| .. versionchanged:: 1.4 The ``nulls_last()`` operator is
| renamed from ``nullslast()`` in previous releases.
| The previous name remains available for backwards compatibility.
|
| nullsfirst = nulls_first(self) -> 'ColumnOperators'
|
| nullslast = nulls_last(self) -> 'ColumnOperators'
|
| regexp_match(self, pattern: 'Any', flags: 'Optional[str]' = None) -> 'ColumnOperators'
| Implements a database-specific 'regexp match' operator.
|
| E.g.::
|
| stmt = select(table.c.some_column).where(
| table.c.some_column.regexp_match("^(b|c)")
| )
|
| :meth:`_sql.ColumnOperators.regexp_match` attempts to resolve to
| a REGEXP-like function or operator provided by the backend, however
| the specific regular expression syntax and flags available are
| **not backend agnostic**.
|
| Examples include:
|
| * PostgreSQL - renders ``x ~ y`` or ``x !~ y`` when negated.
| * Oracle Database - renders ``REGEXP_LIKE(x, y)``
| * SQLite - uses SQLite's ``REGEXP`` placeholder operator and calls into
| the Python ``re.match()`` builtin.
| * other backends may provide special implementations.
| * Backends without any special implementation will emit
| the operator as "REGEXP" or "NOT REGEXP". This is compatible with
| SQLite and MySQL, for example.
|
| Regular expression support is currently implemented for Oracle
| Database, PostgreSQL, MySQL and MariaDB. Partial support is available
| for SQLite. Support among third-party dialects may vary.
|
| :param pattern: The regular expression pattern string or column
| clause.
| :param flags: Any regular expression string flags to apply, passed as
| plain Python string only. These flags are backend specific.
| Some backends, like PostgreSQL and MariaDB, may alternatively
| specify the flags as part of the pattern.
| When using the ignore case flag 'i' in PostgreSQL, the ignore case
| regexp match operator ``~*`` or ``!~*`` will be used.
|
| .. versionadded:: 1.4
|
| .. versionchanged:: 1.4.48, 2.0.18 Note that due to an implementation
| error, the "flags" parameter previously accepted SQL expression
| objects such as column expressions in addition to plain Python
| strings. This implementation did not work correctly with caching
| and was removed; strings only should be passed for the "flags"
| parameter, as these flags are rendered as literal inline values
| within SQL expressions.
|
| .. seealso::
|
| :meth:`_sql.ColumnOperators.regexp_replace`
|
| regexp_replace(self, pattern: 'Any', replacement: 'Any', flags: 'Optional[str]' = None) -> 'ColumnOperators'
| Implements a database-specific 'regexp replace' operator.
|
| E.g.::
|
| stmt = select(
| table.c.some_column.regexp_replace("b(..)", "XY", flags="g")
| )
|
| :meth:`_sql.ColumnOperators.regexp_replace` attempts to resolve to
| a REGEXP_REPLACE-like function provided by the backend, that
| usually emit the function ``REGEXP_REPLACE()``. However,
| the specific regular expression syntax and flags available are
| **not backend agnostic**.
|
| Regular expression replacement support is currently implemented for
| Oracle Database, PostgreSQL, MySQL 8 or greater and MariaDB. Support
| among third-party dialects may vary.
|
| :param pattern: The regular expression pattern string or column
| clause.
| :param pattern: The replacement string or column clause.
| :param flags: Any regular expression string flags to apply, passed as
| plain Python string only. These flags are backend specific.
| Some backends, like PostgreSQL and MariaDB, may alternatively
| specify the flags as part of the pattern.
|
| .. versionadded:: 1.4
|
| .. versionchanged:: 1.4.48, 2.0.18 Note that due to an implementation
| error, the "flags" parameter previously accepted SQL expression
| objects such as column expressions in addition to plain Python
| strings. This implementation did not work correctly with caching
| and was removed; strings only should be passed for the "flags"
| parameter, as these flags are rendered as literal inline values
| within SQL expressions.
|
|
| .. seealso::
|
| :meth:`_sql.ColumnOperators.regexp_match`
|
| startswith(self, other: 'Any', escape: 'Optional[str]' = None, autoescape: 'bool' = False) -> 'ColumnOperators'
| Implement the ``startswith`` operator.
|
| Produces a LIKE expression that tests against a match for the start
| of a string value:
|
| .. sourcecode:: sql
|
| column LIKE <other> || '%'
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.startswith("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.startswith.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.startswith.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.startswith.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.startswith("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE :param || '%' ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.startswith("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE :param || '%' ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.startswith.autoescape`::
|
| somecolumn.startswith("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.endswith`
|
| :meth:`.ColumnOperators.contains`
|
| :meth:`.ColumnOperators.like`
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.operators.ColumnOperators:
|
| timetuple = None
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.operators.Operators:
|
| __and__(self, other: 'Any') -> 'Operators'
| Implement the ``&`` operator.
|
| When used with SQL expressions, results in an
| AND operation, equivalent to
| :func:`_expression.and_`, that is::
|
| a & b
|
| is equivalent to::
|
| from sqlalchemy import and_
|
| and_(a, b)
|
| Care should be taken when using ``&`` regarding
| operator precedence; the ``&`` operator has the highest precedence.
| The operands should be enclosed in parenthesis if they contain
| further sub expressions::
|
| (a == 2) & (b == 4)
|
| __invert__(self) -> 'Operators'
| Implement the ``~`` operator.
|
| When used with SQL expressions, results in a
| NOT operation, equivalent to
| :func:`_expression.not_`, that is::
|
| ~a
|
| is equivalent to::
|
| from sqlalchemy import not_
|
| not_(a)
|
| __or__(self, other: 'Any') -> 'Operators'
| Implement the ``|`` operator.
|
| When used with SQL expressions, results in an
| OR operation, equivalent to
| :func:`_expression.or_`, that is::
|
| a | b
|
| is equivalent to::
|
| from sqlalchemy import or_
|
| or_(a, b)
|
| Care should be taken when using ``|`` regarding
| operator precedence; the ``|`` operator has the highest precedence.
| The operands should be enclosed in parenthesis if they contain
| further sub expressions::
|
| (a == 2) | (b == 4)
|
| __sa_operate__ = operate(self, op: 'OperatorType', *other: 'Any', **kwargs: 'Any') -> 'Operators'
| Operate on an argument.
|
| This is the lowest level of operation, raises
| :class:`NotImplementedError` by default.
|
| Overriding this on a subclass can allow common
| behavior to be applied to all operations.
| For example, overriding :class:`.ColumnOperators`
| to apply ``func.lower()`` to the left and right
| side::
|
| class MyComparator(ColumnOperators):
| def operate(self, op, other, **kwargs):
| return op(func.lower(self), func.lower(other), **kwargs)
|
| :param op: Operator callable.
| :param \*other: the 'other' side of the operation. Will
| be a single scalar for most operations.
| :param \**kwargs: modifiers. These may be passed by special
| operators such as :meth:`ColumnOperators.contains`.
|
| bool_op(self, opstring: 'str', precedence: 'int' = 0, python_impl: 'Optional[Callable[..., Any]]' = None) -> 'Callable[[Any], Operators]'
| Return a custom boolean operator.
|
| This method is shorthand for calling
| :meth:`.Operators.op` and passing the
| :paramref:`.Operators.op.is_comparison`
| flag with True. A key advantage to using :meth:`.Operators.bool_op`
| is that when using column constructs, the "boolean" nature of the
| returned expression will be present for :pep:`484` purposes.
|
| .. seealso::
|
| :meth:`.Operators.op`
|
| op(self, opstring: 'str', precedence: 'int' = 0, is_comparison: 'bool' = False, return_type: 'Optional[Union[Type[TypeEngine[Any]], TypeEngine[Any]]]' = None, python_impl: 'Optional[Callable[..., Any]]' = None) -> 'Callable[[Any], Operators]'
| Produce a generic operator function.
|
| e.g.::
|
| somecolumn.op("*")(5)
|
| produces::
|
| somecolumn * 5
|
| This function can also be used to make bitwise operators explicit. For
| example::
|
| somecolumn.op("&")(0xFF)
|
| is a bitwise AND of the value in ``somecolumn``.
|
| :param opstring: a string which will be output as the infix operator
| between this element and the expression passed to the
| generated function.
|
| :param precedence: precedence which the database is expected to apply
| to the operator in SQL expressions. This integer value acts as a hint
| for the SQL compiler to know when explicit parenthesis should be
| rendered around a particular operation. A lower number will cause the
| expression to be parenthesized when applied against another operator
| with higher precedence. The default value of ``0`` is lower than all
| operators except for the comma (``,``) and ``AS`` operators. A value
| of 100 will be higher or equal to all operators, and -100 will be
| lower than or equal to all operators.
|
| .. seealso::
|
| :ref:`faq_sql_expression_op_parenthesis` - detailed description
| of how the SQLAlchemy SQL compiler renders parenthesis
|
| :param is_comparison: legacy; if True, the operator will be considered
| as a "comparison" operator, that is which evaluates to a boolean
| true/false value, like ``==``, ``>``, etc. This flag is provided
| so that ORM relationships can establish that the operator is a
| comparison operator when used in a custom join condition.
|
| Using the ``is_comparison`` parameter is superseded by using the
| :meth:`.Operators.bool_op` method instead; this more succinct
| operator sets this parameter automatically, but also provides
| correct :pep:`484` typing support as the returned object will
| express a "boolean" datatype, i.e. ``BinaryExpression[bool]``.
|
| :param return_type: a :class:`.TypeEngine` class or object that will
| force the return type of an expression produced by this operator
| to be of that type. By default, operators that specify
| :paramref:`.Operators.op.is_comparison` will resolve to
| :class:`.Boolean`, and those that do not will be of the same
| type as the left-hand operand.
|
| :param python_impl: an optional Python function that can evaluate
| two Python values in the same way as this operator works when
| run on the database server. Useful for in-Python SQL expression
| evaluation functions, such as for ORM hybrid attributes, and the
| ORM "evaluator" used to match objects in a session after a multi-row
| update or delete.
|
| e.g.::
|
| >>> expr = column("x").op("+", python_impl=lambda a, b: a + b)("y")
|
| The operator for the above expression will also work for non-SQL
| left and right objects::
|
| >>> expr.operator(5, 10)
| 15
|
| .. versionadded:: 2.0
|
|
| .. seealso::
|
| :meth:`.Operators.bool_op`
|
| :ref:`types_operators`
|
| :ref:`relationship_custom_operator`
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.elements.ClauseElement:
|
| __bool__(self)
|
| __repr__(self)
| Return repr(self).
|
| compare(self, other: 'ClauseElement', **kw: 'Any') -> 'bool'
| Compare this :class:`_expression.ClauseElement` to
| the given :class:`_expression.ClauseElement`.
|
| Subclasses should override the default behavior, which is a
| straight identity comparison.
|
| \**kw are arguments consumed by subclass ``compare()`` methods and
| may be used to modify the criteria for comparison
| (see :class:`_expression.ColumnElement`).
|
| description(...)
|
| entity_namespace(...)
|
| params(self, _ClauseElement__optionaldict: 'Optional[Mapping[str, Any]]' = None, **kwargs: 'Any') -> 'Self'
| Return a copy with :func:`_expression.bindparam` elements
| replaced.
|
| Returns a copy of this ClauseElement with
| :func:`_expression.bindparam`
| elements replaced with values taken from the given dictionary::
|
| >>> clause = column("x") + bindparam("foo")
| >>> print(clause.compile().params)
| {'foo':None}
| >>> print(clause.params({"foo": 7}).compile().params)
| {'foo':7}
|
| unique_params(self, _ClauseElement__optionaldict: 'Optional[Dict[str, Any]]' = None, **kwargs: 'Any') -> 'Self'
| Return a copy with :func:`_expression.bindparam` elements
| replaced.
|
| Same functionality as :meth:`_expression.ClauseElement.params`,
| except adds `unique=True`
| to affected bind parameters so that multiple statements can be
| used.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.elements.ClauseElement:
|
| is_clause_element = True
|
| is_dml = False
|
| is_selectable = False
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_instancemethod(fn: '_F') -> '_F'
| Decorate a method memoize its return value.
|
| :meta private:
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_attribute = <class 'sqlalchemy.util.langhelpers.HasMemoized.m...
| A read-only @property that is only evaluated once.
|
| :meta private:
|
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.visitors.HasTraverseInternals:
|
| get_children(self, *, omit_attrs: 'Tuple[str, ...]' = (), **kw: 'Any') -> 'Iterable[HasTraverseInternals]'
| Return immediate child :class:`.visitors.HasTraverseInternals`
| elements of this :class:`.visitors.HasTraverseInternals`.
|
| This is used for visit traversal.
|
| \**kw may contain flags that change the collection that is
| returned, for example to return a subset of items in order to
| cut down on larger traversals, or to return child items from a
| different context (such as schema-level collections instead of
| clause-level).
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.elements.CompilerElement:
|
| __str__(self) -> 'str'
| Return str(self).
|
| compile(self, bind: 'Optional[_HasDialect]' = None, dialect: 'Optional[Dialect]' = None, **kw: 'Any') -> 'Compiled'
| Compile this SQL expression.
|
| The return value is a :class:`~.Compiled` object.
| Calling ``str()`` or ``unicode()`` on the returned value will yield a
| string representation of the result. The
| :class:`~.Compiled` object also can return a
| dictionary of bind parameter names and values
| using the ``params`` accessor.
|
| :param bind: An :class:`.Connection` or :class:`.Engine` which
| can provide a :class:`.Dialect` in order to generate a
| :class:`.Compiled` object. If the ``bind`` and
| ``dialect`` parameters are both omitted, a default SQL compiler
| is used.
|
| :param column_keys: Used for INSERT and UPDATE statements, a list of
| column names which should be present in the VALUES clause of the
| compiled statement. If ``None``, all columns from the target table
| object are rendered.
|
| :param dialect: A :class:`.Dialect` instance which can generate
| a :class:`.Compiled` object. This argument takes precedence over
| the ``bind`` argument.
|
| :param compile_kwargs: optional dictionary of additional parameters
| that will be passed through to the compiler within all "visit"
| methods. This allows any custom flag to be passed through to
| a custom compilation construct, for example. It is also used
| for the case of passing the ``literal_binds`` flag through::
|
| from sqlalchemy.sql import table, column, select
|
| t = table("t", column("x"))
|
| s = select(t).where(t.c.x == 5)
|
| print(s.compile(compile_kwargs={"literal_binds": True}))
|
| .. seealso::
|
| :ref:`faq_sql_expression_string`
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.elements.CompilerElement:
|
| stringify_dialect = 'default'
|
| supports_execution = False
sqlalchemy.Select
Python Library Documentation: class Select in module sqlalchemy.sql.selectable
class Select(HasPrefixes, HasSuffixes, HasHints, sqlalchemy.sql.base.HasCompileState, _SelectFromElements, GenerativeSelect, TypedReturnsRows)
| Select(*entities: '_ColumnsClauseArgument[Any]', **dialect_kw: 'Any')
|
| Represents a ``SELECT`` statement.
|
| The :class:`_sql.Select` object is normally constructed using the
| :func:`_sql.select` function. See that function for details.
|
| .. seealso::
|
| :func:`_sql.select`
|
| :ref:`tutorial_selecting_data` - in the 2.0 tutorial
|
| Method resolution order:
| Select
| HasPrefixes
| HasSuffixes
| HasHints
| sqlalchemy.sql.base.HasCompileState
| _SelectFromElements
| GenerativeSelect
| sqlalchemy.sql.base.DialectKWArgs
| SelectBase
| sqlalchemy.sql.roles.SelectStatementRole
| TypedReturnsRows
| ExecutableReturnsRows
| sqlalchemy.sql.base.Executable
| sqlalchemy.sql.roles.StatementRole
| sqlalchemy.sql.roles.DMLSelectRole
| sqlalchemy.sql.roles.CompoundElementRole
| sqlalchemy.sql.roles.AllowsLambdaRole
| sqlalchemy.sql.roles.InElementRole
| HasCTE
| sqlalchemy.sql.roles.HasCTERole
| SelectsRows
| sqlalchemy.sql.annotation.SupportsCloneAnnotations
| Selectable
| ReturnsRows
| sqlalchemy.sql.roles.ReturnsRowsRole
| sqlalchemy.sql.roles.SQLRole
| sqlalchemy.sql.elements.DQLDMLClauseElement
| sqlalchemy.sql.elements.ClauseElement
| sqlalchemy.sql.annotation.SupportsWrappingAnnotations
| sqlalchemy.sql.annotation.SupportsAnnotations
| sqlalchemy.sql.cache_key.MemoizedHasCacheKey
| sqlalchemy.sql.cache_key.HasCacheKey
| sqlalchemy.sql.base.Generative
| sqlalchemy.util.langhelpers.HasMemoized
| sqlalchemy.sql.traversals.HasCopyInternals
| sqlalchemy.sql.visitors.ExternallyTraversible
| sqlalchemy.sql.visitors.HasTraverseInternals
| sqlalchemy.sql.elements.CompilerElement
| sqlalchemy.sql.visitors.Visitable
| typing.Generic
| builtins.object
|
| Methods defined here:
|
| __init__(self, *entities: '_ColumnsClauseArgument[Any]', **dialect_kw: 'Any')
| Construct a new :class:`_expression.Select`.
|
| The public constructor for :class:`_expression.Select` is the
| :func:`_sql.select` function.
|
| add_columns(self, *entities: '_ColumnsClauseArgument[Any]') -> 'Select[Any]'
| Return a new :func:`_expression.select` construct with
| the given entities appended to its columns clause.
|
| E.g.::
|
| my_select = my_select.add_columns(table.c.new_column)
|
| The original expressions in the columns clause remain in place.
| To replace the original expressions with new ones, see the method
| :meth:`_expression.Select.with_only_columns`.
|
| :param \*entities: column, table, or other entity expressions to be
| added to the columns clause
|
| .. seealso::
|
| :meth:`_expression.Select.with_only_columns` - replaces existing
| expressions rather than appending.
|
| :ref:`orm_queryguide_select_multiple_entities` - ORM-centric
| example
|
| column(self, column: '_ColumnsClauseArgument[Any]') -> 'Select[Any]'
| Return a new :func:`_expression.select` construct with
| the given column expression added to its columns clause.
|
| .. deprecated:: 1.4 The :meth:`_expression.Select.column` method is deprecated and will be removed in a future release. Please use :meth:`_expression.Select.add_columns`
|
| E.g.::
|
| my_select = my_select.column(table.c.new_column)
|
| See the documentation for
| :meth:`_expression.Select.with_only_columns`
| for guidelines on adding /replacing the columns of a
| :class:`_expression.Select` object.
|
| correlate(self, *fromclauses: 'Union[Literal[None, False], _FromClauseArgument]') -> 'Self'
| Return a new :class:`_expression.Select`
| which will correlate the given FROM
| clauses to that of an enclosing :class:`_expression.Select`.
|
| Calling this method turns off the :class:`_expression.Select` object's
| default behavior of "auto-correlation". Normally, FROM elements
| which appear in a :class:`_expression.Select`
| that encloses this one via
| its :term:`WHERE clause`, ORDER BY, HAVING or
| :term:`columns clause` will be omitted from this
| :class:`_expression.Select`
| object's :term:`FROM clause`.
| Setting an explicit correlation collection using the
| :meth:`_expression.Select.correlate`
| method provides a fixed list of FROM objects
| that can potentially take place in this process.
|
| When :meth:`_expression.Select.correlate`
| is used to apply specific FROM clauses
| for correlation, the FROM elements become candidates for
| correlation regardless of how deeply nested this
| :class:`_expression.Select`
| object is, relative to an enclosing :class:`_expression.Select`
| which refers to
| the same FROM object. This is in contrast to the behavior of
| "auto-correlation" which only correlates to an immediate enclosing
| :class:`_expression.Select`.
| Multi-level correlation ensures that the link
| between enclosed and enclosing :class:`_expression.Select`
| is always via
| at least one WHERE/ORDER BY/HAVING/columns clause in order for
| correlation to take place.
|
| If ``None`` is passed, the :class:`_expression.Select`
| object will correlate
| none of its FROM entries, and all will render unconditionally
| in the local FROM clause.
|
| :param \*fromclauses: one or more :class:`.FromClause` or other
| FROM-compatible construct such as an ORM mapped entity to become part
| of the correlate collection; alternatively pass a single value
| ``None`` to remove all existing correlations.
|
| .. seealso::
|
| :meth:`_expression.Select.correlate_except`
|
| :ref:`tutorial_scalar_subquery`
|
| correlate_except(self, *fromclauses: 'Union[Literal[None, False], _FromClauseArgument]') -> 'Self'
| Return a new :class:`_expression.Select`
| which will omit the given FROM
| clauses from the auto-correlation process.
|
| Calling :meth:`_expression.Select.correlate_except` turns off the
| :class:`_expression.Select` object's default behavior of
| "auto-correlation" for the given FROM elements. An element
| specified here will unconditionally appear in the FROM list, while
| all other FROM elements remain subject to normal auto-correlation
| behaviors.
|
| If ``None`` is passed, or no arguments are passed,
| the :class:`_expression.Select` object will correlate all of its
| FROM entries.
|
| :param \*fromclauses: a list of one or more
| :class:`_expression.FromClause`
| constructs, or other compatible constructs (i.e. ORM-mapped
| classes) to become part of the correlate-exception collection.
|
| .. seealso::
|
| :meth:`_expression.Select.correlate`
|
| :ref:`tutorial_scalar_subquery`
|
| distinct(self, *expr: '_ColumnExpressionArgument[Any]') -> 'Self'
| Return a new :func:`_expression.select` construct which
| will apply DISTINCT to the SELECT statement overall.
|
| E.g.::
|
| from sqlalchemy import select
|
| stmt = select(users_table.c.id, users_table.c.name).distinct()
|
| The above would produce an statement resembling:
|
| .. sourcecode:: sql
|
| SELECT DISTINCT user.id, user.name FROM user
|
| The method also accepts an ``*expr`` parameter which produces the
| PostgreSQL dialect-specific ``DISTINCT ON`` expression. Using this
| parameter on other backends which don't support this syntax will
| raise an error.
|
| :param \*expr: optional column expressions. When present,
| the PostgreSQL dialect will render a ``DISTINCT ON (<expressions>)``
| construct. A deprecation warning and/or :class:`_exc.CompileError`
| will be raised on other backends.
|
| .. deprecated:: 1.4 Using \*expr in other dialects is deprecated
| and will raise :class:`_exc.CompileError` in a future version.
|
| except_(self, *other: '_SelectStatementForCompoundArgument[_TP]') -> 'CompoundSelect[_TP]'
| Return a SQL ``EXCEPT`` of this select() construct against
| the given selectable provided as positional arguments.
|
| :param \*other: one or more elements with which to create a
| UNION.
|
| .. versionchanged:: 1.4.28
|
| multiple elements are now accepted.
|
| except_all(self, *other: '_SelectStatementForCompoundArgument[_TP]') -> 'CompoundSelect[_TP]'
| Return a SQL ``EXCEPT ALL`` of this select() construct against
| the given selectables provided as positional arguments.
|
| :param \*other: one or more elements with which to create a
| UNION.
|
| .. versionchanged:: 1.4.28
|
| multiple elements are now accepted.
|
| filter(self, *criteria: '_ColumnExpressionArgument[bool]') -> 'Self'
| A synonym for the :meth:`_sql.Select.where` method.
|
| filter_by(self, **kwargs: 'Any') -> 'Self'
| apply the given filtering criterion as a WHERE clause
| to this select.
|
| from_statement(self, statement: 'roles.ReturnsRowsRole') -> 'ExecutableReturnsRows'
| Apply the columns which this :class:`.Select` would select
| onto another statement.
|
| This operation is :term:`plugin-specific` and will raise a not
| supported exception if this :class:`_sql.Select` does not select from
| plugin-enabled entities.
|
|
| The statement is typically either a :func:`_expression.text` or
| :func:`_expression.select` construct, and should return the set of
| columns appropriate to the entities represented by this
| :class:`.Select`.
|
| .. seealso::
|
| :ref:`orm_queryguide_selecting_text` - usage examples in the
| ORM Querying Guide
|
| get_children(self, **kw: 'Any') -> 'Iterable[ClauseElement]'
| Return immediate child :class:`.visitors.HasTraverseInternals`
| elements of this :class:`.visitors.HasTraverseInternals`.
|
| This is used for visit traversal.
|
| \**kw may contain flags that change the collection that is
| returned, for example to return a subset of items in order to
| cut down on larger traversals, or to return child items from a
| different context (such as schema-level collections instead of
| clause-level).
|
| get_final_froms(self) -> 'Sequence[FromClause]'
| Compute the final displayed list of :class:`_expression.FromClause`
| elements.
|
| This method will run through the full computation required to
| determine what FROM elements will be displayed in the resulting
| SELECT statement, including shadowing individual tables with
| JOIN objects, as well as full computation for ORM use cases including
| eager loading clauses.
|
| For ORM use, this accessor returns the **post compilation**
| list of FROM objects; this collection will include elements such as
| eagerly loaded tables and joins. The objects will **not** be
| ORM enabled and not work as a replacement for the
| :meth:`_sql.Select.select_froms` collection; additionally, the
| method is not well performing for an ORM enabled statement as it
| will incur the full ORM construction process.
|
| To retrieve the FROM list that's implied by the "columns" collection
| passed to the :class:`_sql.Select` originally, use the
| :attr:`_sql.Select.columns_clause_froms` accessor.
|
| To select from an alternative set of columns while maintaining the
| FROM list, use the :meth:`_sql.Select.with_only_columns` method and
| pass the
| :paramref:`_sql.Select.with_only_columns.maintain_column_froms`
| parameter.
|
| .. versionadded:: 1.4.23 - the :meth:`_sql.Select.get_final_froms`
| method replaces the previous :attr:`_sql.Select.froms` accessor,
| which is deprecated.
|
| .. seealso::
|
| :attr:`_sql.Select.columns_clause_froms`
|
| having(self, *having: '_ColumnExpressionArgument[bool]') -> 'Self'
| Return a new :func:`_expression.select` construct with
| the given expression added to
| its HAVING clause, joined to the existing clause via AND, if any.
|
| intersect(self, *other: '_SelectStatementForCompoundArgument[_TP]') -> 'CompoundSelect[_TP]'
| Return a SQL ``INTERSECT`` of this select() construct against
| the given selectables provided as positional arguments.
|
| :param \*other: one or more elements with which to create a
| UNION.
|
| .. versionchanged:: 1.4.28
|
| multiple elements are now accepted.
|
| :param \**kwargs: keyword arguments are forwarded to the constructor
| for the newly created :class:`_sql.CompoundSelect` object.
|
| intersect_all(self, *other: '_SelectStatementForCompoundArgument[_TP]') -> 'CompoundSelect[_TP]'
| Return a SQL ``INTERSECT ALL`` of this select() construct
| against the given selectables provided as positional arguments.
|
| :param \*other: one or more elements with which to create a
| UNION.
|
| .. versionchanged:: 1.4.28
|
| multiple elements are now accepted.
|
| :param \**kwargs: keyword arguments are forwarded to the constructor
| for the newly created :class:`_sql.CompoundSelect` object.
|
| 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.
|
| join(self, target: '_JoinTargetArgument', onclause: 'Optional[_OnClauseArgument]' = None, *, isouter: 'bool' = False, full: 'bool' = False) -> 'Self'
| Create a SQL JOIN against this :class:`_expression.Select`
| object's criterion
| and apply generatively, returning the newly resulting
| :class:`_expression.Select`.
|
| E.g.::
|
| stmt = select(user_table).join(
| address_table, user_table.c.id == address_table.c.user_id
| )
|
| The above statement generates SQL similar to:
|
| .. sourcecode:: sql
|
| SELECT user.id, user.name
| FROM user
| JOIN address ON user.id = address.user_id
|
| .. versionchanged:: 1.4 :meth:`_expression.Select.join` now creates
| a :class:`_sql.Join` object between a :class:`_sql.FromClause`
| source that is within the FROM clause of the existing SELECT,
| and a given target :class:`_sql.FromClause`, and then adds
| this :class:`_sql.Join` to the FROM clause of the newly generated
| SELECT statement. This is completely reworked from the behavior
| in 1.3, which would instead create a subquery of the entire
| :class:`_expression.Select` and then join that subquery to the
| target.
|
| This is a **backwards incompatible change** as the previous behavior
| was mostly useless, producing an unnamed subquery rejected by
| most databases in any case. The new behavior is modeled after
| that of the very successful :meth:`_orm.Query.join` method in the
| ORM, in order to support the functionality of :class:`_orm.Query`
| being available by using a :class:`_sql.Select` object with an
| :class:`_orm.Session`.
|
| See the notes for this change at :ref:`change_select_join`.
|
|
| :param target: target table to join towards
|
| :param onclause: ON clause of the join. If omitted, an ON clause
| is generated automatically based on the :class:`_schema.ForeignKey`
| linkages between the two tables, if one can be unambiguously
| determined, otherwise an error is raised.
|
| :param isouter: if True, generate LEFT OUTER join. Same as
| :meth:`_expression.Select.outerjoin`.
|
| :param full: if True, generate FULL OUTER join.
|
| .. seealso::
|
| :ref:`tutorial_select_join` - in the :doc:`/tutorial/index`
|
| :ref:`orm_queryguide_joins` - in the :ref:`queryguide_toplevel`
|
| :meth:`_expression.Select.join_from`
|
| :meth:`_expression.Select.outerjoin`
|
| join_from(self, from_: '_FromClauseArgument', target: '_JoinTargetArgument', onclause: 'Optional[_OnClauseArgument]' = None, *, isouter: 'bool' = False, full: 'bool' = False) -> 'Self'
| Create a SQL JOIN against this :class:`_expression.Select`
| object's criterion
| and apply generatively, returning the newly resulting
| :class:`_expression.Select`.
|
| E.g.::
|
| stmt = select(user_table, address_table).join_from(
| user_table, address_table, user_table.c.id == address_table.c.user_id
| )
|
| The above statement generates SQL similar to:
|
| .. sourcecode:: sql
|
| SELECT user.id, user.name, address.id, address.email, address.user_id
| FROM user JOIN address ON user.id = address.user_id
|
| .. versionadded:: 1.4
|
| :param from\_: the left side of the join, will be rendered in the
| FROM clause and is roughly equivalent to using the
| :meth:`.Select.select_from` method.
|
| :param target: target table to join towards
|
| :param onclause: ON clause of the join.
|
| :param isouter: if True, generate LEFT OUTER join. Same as
| :meth:`_expression.Select.outerjoin`.
|
| :param full: if True, generate FULL OUTER join.
|
| .. seealso::
|
| :ref:`tutorial_select_join` - in the :doc:`/tutorial/index`
|
| :ref:`orm_queryguide_joins` - in the :ref:`queryguide_toplevel`
|
| :meth:`_expression.Select.join`
|
| outerjoin(self, target: '_JoinTargetArgument', onclause: 'Optional[_OnClauseArgument]' = None, *, full: 'bool' = False) -> 'Self'
| Create a left outer join.
|
| Parameters are the same as that of :meth:`_expression.Select.join`.
|
| .. versionchanged:: 1.4 :meth:`_expression.Select.outerjoin` now
| creates a :class:`_sql.Join` object between a
| :class:`_sql.FromClause` source that is within the FROM clause of
| the existing SELECT, and a given target :class:`_sql.FromClause`,
| and then adds this :class:`_sql.Join` to the FROM clause of the
| newly generated SELECT statement. This is completely reworked
| from the behavior in 1.3, which would instead create a subquery of
| the entire
| :class:`_expression.Select` and then join that subquery to the
| target.
|
| This is a **backwards incompatible change** as the previous behavior
| was mostly useless, producing an unnamed subquery rejected by
| most databases in any case. The new behavior is modeled after
| that of the very successful :meth:`_orm.Query.join` method in the
| ORM, in order to support the functionality of :class:`_orm.Query`
| being available by using a :class:`_sql.Select` object with an
| :class:`_orm.Session`.
|
| See the notes for this change at :ref:`change_select_join`.
|
| .. seealso::
|
| :ref:`tutorial_select_join` - in the :doc:`/tutorial/index`
|
| :ref:`orm_queryguide_joins` - in the :ref:`queryguide_toplevel`
|
| :meth:`_expression.Select.join`
|
| outerjoin_from(self, from_: '_FromClauseArgument', target: '_JoinTargetArgument', onclause: 'Optional[_OnClauseArgument]' = None, *, full: 'bool' = False) -> 'Self'
| Create a SQL LEFT OUTER JOIN against this
| :class:`_expression.Select` object's criterion and apply generatively,
| returning the newly resulting :class:`_expression.Select`.
|
| Usage is the same as that of :meth:`_selectable.Select.join_from`.
|
| reduce_columns(self, only_synonyms: 'bool' = True) -> 'Select[Any]'
| Return a new :func:`_expression.select` construct with redundantly
| named, equivalently-valued columns removed from the columns clause.
|
| "Redundant" here means two columns where one refers to the
| other either based on foreign key, or via a simple equality
| comparison in the WHERE clause of the statement. The primary purpose
| of this method is to automatically construct a select statement
| with all uniquely-named columns, without the need to use
| table-qualified labels as
| :meth:`_expression.Select.set_label_style`
| does.
|
| When columns are omitted based on foreign key, the referred-to
| column is the one that's kept. When columns are omitted based on
| WHERE equivalence, the first column in the columns clause is the
| one that's kept.
|
| :param only_synonyms: when True, limit the removal of columns
| to those which have the same name as the equivalent. Otherwise,
| all columns that are equivalent to another are removed.
|
| select_from(self, *froms: '_FromClauseArgument') -> 'Self'
| Return a new :func:`_expression.select` construct with the
| given FROM expression(s)
| merged into its list of FROM objects.
|
| E.g.::
|
| table1 = table("t1", column("a"))
| table2 = table("t2", column("b"))
| s = select(table1.c.a).select_from(
| table1.join(table2, table1.c.a == table2.c.b)
| )
|
| The "from" list is a unique set on the identity of each element,
| so adding an already present :class:`_schema.Table`
| or other selectable
| will have no effect. Passing a :class:`_expression.Join` that refers
| to an already present :class:`_schema.Table`
| or other selectable will have
| the effect of concealing the presence of that selectable as
| an individual element in the rendered FROM list, instead
| rendering it into a JOIN clause.
|
| While the typical purpose of :meth:`_expression.Select.select_from`
| is to
| replace the default, derived FROM clause with a join, it can
| also be called with individual table elements, multiple times
| if desired, in the case that the FROM clause cannot be fully
| derived from the columns clause::
|
| select(func.count("*")).select_from(table1)
|
| selected_columns(...)
| A :class:`_expression.ColumnCollection`
| representing the columns that
| this SELECT statement or similar construct returns in its result set,
| not including :class:`_sql.TextClause` constructs.
|
| 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.
|
| For a :func:`_expression.select` construct, the collection here is
| exactly what would be rendered inside the "SELECT" statement, and the
| :class:`_expression.ColumnElement` objects are directly present as they
| were given, e.g.::
|
| col1 = column("q", Integer)
| col2 = column("p", Integer)
| stmt = select(col1, col2)
|
| Above, ``stmt.selected_columns`` would be a collection that contains
| the ``col1`` and ``col2`` objects directly. For a statement that is
| against a :class:`_schema.Table` or other
| :class:`_expression.FromClause`, the collection will use the
| :class:`_expression.ColumnElement` objects that are in the
| :attr:`_expression.FromClause.c` collection of the from element.
|
| A use case for the :attr:`_sql.Select.selected_columns` collection is
| to allow the existing columns to be referenced when adding additional
| criteria, e.g.::
|
| def filter_on_id(my_select, id):
| return my_select.where(my_select.selected_columns["id"] == id)
|
|
| stmt = select(MyModel)
|
| # adds "WHERE id=:param" to the statement
| stmt = filter_on_id(stmt, 42)
|
| .. note::
|
| The :attr:`_sql.Select.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.
|
|
| .. versionadded:: 1.4
|
| self_group(self, against: 'Optional[OperatorType]' = None) -> 'Union[SelectStatementGrouping[Self], Self]'
| Return a 'grouping' construct as per the
| :class:`_expression.ClauseElement` specification.
|
| This produces an element that can be embedded in an expression. Note
| that this method is called automatically as needed when constructing
| expressions and should not require explicit use.
|
| union(self, *other: '_SelectStatementForCompoundArgument[_TP]') -> 'CompoundSelect[_TP]'
| Return a SQL ``UNION`` of this select() construct against
| the given selectables provided as positional arguments.
|
| :param \*other: one or more elements with which to create a
| UNION.
|
| .. versionchanged:: 1.4.28
|
| multiple elements are now accepted.
|
| :param \**kwargs: keyword arguments are forwarded to the constructor
| for the newly created :class:`_sql.CompoundSelect` object.
|
| union_all(self, *other: '_SelectStatementForCompoundArgument[_TP]') -> 'CompoundSelect[_TP]'
| Return a SQL ``UNION ALL`` of this select() construct against
| the given selectables provided as positional arguments.
|
| :param \*other: one or more elements with which to create a
| UNION.
|
| .. versionchanged:: 1.4.28
|
| multiple elements are now accepted.
|
| :param \**kwargs: keyword arguments are forwarded to the constructor
| for the newly created :class:`_sql.CompoundSelect` object.
|
| where(self, *whereclause: '_ColumnExpressionArgument[bool]') -> 'Self'
| Return a new :func:`_expression.select` construct with
| the given expression added to
| its WHERE clause, joined to the existing clause via AND, if any.
|
| with_only_columns(self, *entities: '_ColumnsClauseArgument[Any]', maintain_column_froms: 'bool' = False, **_Select__kw: 'Any') -> 'Select[Any]'
| Return a new :func:`_expression.select` construct with its columns
| clause replaced with the given entities.
|
| By default, this method is exactly equivalent to as if the original
| :func:`_expression.select` had been called with the given entities.
| E.g. a statement::
|
| s = select(table1.c.a, table1.c.b)
| s = s.with_only_columns(table1.c.b)
|
| should be exactly equivalent to::
|
| s = select(table1.c.b)
|
| In this mode of operation, :meth:`_sql.Select.with_only_columns`
| will also dynamically alter the FROM clause of the
| statement if it is not explicitly stated.
| To maintain the existing set of FROMs including those implied by the
| current columns clause, add the
| :paramref:`_sql.Select.with_only_columns.maintain_column_froms`
| parameter::
|
| s = select(table1.c.a, table2.c.b)
| s = s.with_only_columns(table1.c.a, maintain_column_froms=True)
|
| The above parameter performs a transfer of the effective FROMs
| in the columns collection to the :meth:`_sql.Select.select_from`
| method, as though the following were invoked::
|
| s = select(table1.c.a, table2.c.b)
| s = s.select_from(table1, table2).with_only_columns(table1.c.a)
|
| The :paramref:`_sql.Select.with_only_columns.maintain_column_froms`
| parameter makes use of the :attr:`_sql.Select.columns_clause_froms`
| collection and performs an operation equivalent to the following::
|
| s = select(table1.c.a, table2.c.b)
| s = s.select_from(*s.columns_clause_froms).with_only_columns(table1.c.a)
|
| :param \*entities: column expressions to be used.
|
| :param maintain_column_froms: boolean parameter that will ensure the
| FROM list implied from the current columns clause will be transferred
| to the :meth:`_sql.Select.select_from` method first.
|
| .. versionadded:: 1.4.23
|
| ----------------------------------------------------------------------
| Readonly properties defined here:
|
| column_descriptions
| Return a :term:`plugin-enabled` 'column descriptions' structure
| referring to the columns which are SELECTed by this statement.
|
| This attribute is generally useful when using the ORM, as an
| extended structure which includes information about mapped
| entities is returned. The section :ref:`queryguide_inspection`
| contains more background.
|
| For a Core-only statement, the structure returned by this accessor
| is derived from the same objects that are returned by the
| :attr:`.Select.selected_columns` accessor, formatted as a list of
| dictionaries which contain the keys ``name``, ``type`` and ``expr``,
| which indicate the column expressions to be selected::
|
| >>> stmt = select(user_table)
| >>> stmt.column_descriptions
| [
| {
| 'name': 'id',
| 'type': Integer(),
| 'expr': Column('id', Integer(), ...)},
| {
| 'name': 'name',
| 'type': String(length=30),
| 'expr': Column('name', String(length=30), ...)}
| ]
|
| .. versionchanged:: 1.4.33 The :attr:`.Select.column_descriptions`
| attribute returns a structure for a Core-only set of entities,
| not just ORM-only entities.
|
| .. seealso::
|
| :attr:`.UpdateBase.entity_description` - entity information for
| an :func:`.insert`, :func:`.update`, or :func:`.delete`
|
| :ref:`queryguide_inspection` - ORM background
|
| columns_clause_froms
| Return the set of :class:`_expression.FromClause` objects implied
| by the columns clause of this SELECT statement.
|
| .. versionadded:: 1.4.23
|
| .. seealso::
|
| :attr:`_sql.Select.froms` - "final" FROM list taking the full
| statement into account
|
| :meth:`_sql.Select.with_only_columns` - makes use of this
| collection to set up a new FROM list
|
| froms
| Return the displayed list of :class:`_expression.FromClause`
| elements.
|
| .. deprecated:: 1.4.23 The :attr:`_expression.Select.froms` attribute is moved to the :meth:`_expression.Select.get_final_froms` method.
|
| inner_columns
| An iterator of all :class:`_expression.ColumnElement`
| expressions which would
| be rendered into the columns clause of the resulting SELECT statement.
|
| This method is legacy as of 1.4 and is superseded by the
| :attr:`_expression.Select.exported_columns` collection.
|
| whereclause
| Return the completed WHERE clause for this
| :class:`_expression.Select` statement.
|
| This assembles the current collection of WHERE criteria
| into a single :class:`_expression.BooleanClauseList` construct.
|
|
| .. versionadded:: 1.4
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'_cache_key_traversal': '_CacheKeyTraversalType', '...
|
| __parameters__ = ()
|
| __visit_name__ = 'select'
|
| ----------------------------------------------------------------------
| Methods inherited from HasPrefixes:
|
| prefix_with(self, *prefixes: '_TextCoercedExpressionArgument[Any]', dialect: 'str' = '*') -> 'Self'
| 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.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from HasPrefixes:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Methods inherited from HasSuffixes:
|
| suffix_with(self, *suffixes: '_TextCoercedExpressionArgument[Any]', dialect: 'str' = '*') -> 'Self'
| 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.
|
| ----------------------------------------------------------------------
| Methods inherited from HasHints:
|
| with_hint(self, selectable: '_FromClauseArgument', text: 'str', dialect_name: 'str' = '*') -> 'Self'
| 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
|
| 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
|
| ----------------------------------------------------------------------
| Methods inherited from GenerativeSelect:
|
| fetch(self, count: '_LimitOffsetType', with_ties: 'bool' = False, percent: 'bool' = False, **dialect_kw: 'Any') -> 'Self'
| Return a new selectable with the given FETCH FIRST criterion
| applied.
|
| This is a numeric value which usually renders as ``FETCH {FIRST | NEXT}
| [ count ] {ROW | ROWS} {ONLY | WITH TIES}`` expression in the resulting
| select. This functionality is is currently implemented for Oracle
| Database, PostgreSQL, MSSQL.
|
| Use :meth:`_sql.GenerativeSelect.offset` to specify the offset.
|
| .. note::
|
| The :meth:`_sql.GenerativeSelect.fetch` method will replace
| any clause applied with :meth:`_sql.GenerativeSelect.limit`.
|
| .. versionadded:: 1.4
|
| :param count: an integer COUNT parameter, or a SQL expression
| that provides an integer result. When ``percent=True`` this will
| represent the percentage of rows to return, not the absolute value.
| Pass ``None`` to reset it.
|
| :param with_ties: When ``True``, the WITH TIES option is used
| to return any additional rows that tie for the last place in the
| result set according to the ``ORDER BY`` clause. The
| ``ORDER BY`` may be mandatory in this case. Defaults to ``False``
|
| :param percent: When ``True``, ``count`` represents the percentage
| of the total number of selected rows to return. Defaults to ``False``
|
| :param \**dialect_kw: Additional dialect-specific keyword arguments
| may be accepted by dialects.
|
| .. versionadded:: 2.0.41
|
| .. seealso::
|
| :meth:`_sql.GenerativeSelect.limit`
|
| :meth:`_sql.GenerativeSelect.offset`
|
| get_label_style(self) -> 'SelectLabelStyle'
| Retrieve the current label style.
|
| .. versionadded:: 1.4
|
| group_by(self, _GenerativeSelect__first: 'Union[Literal[None, _NoArg.NO_ARG], _ColumnExpressionOrStrLabelArgument[Any]]' = _NoArg.NO_ARG, *clauses: '_ColumnExpressionOrStrLabelArgument[Any]') -> 'Self'
| Return a new selectable with the given list of GROUP BY
| criterion applied.
|
| All existing GROUP BY settings can be suppressed by passing ``None``.
|
| e.g.::
|
| stmt = select(table.c.name, func.max(table.c.stat)).group_by(table.c.name)
|
| :param \*clauses: a series of :class:`_expression.ColumnElement`
| constructs which will be used to generate an GROUP BY clause.
|
| Alternatively, an individual entry may also be the string name of a
| label located elsewhere in the columns clause of the statement which
| will be matched and rendered in a backend-specific way based on
| context; see :ref:`tutorial_order_by_label` for background on string
| label matching in ORDER BY and GROUP BY expressions.
|
| .. seealso::
|
| :ref:`tutorial_group_by_w_aggregates` - in the
| :ref:`unified_tutorial`
|
| :ref:`tutorial_order_by_label` - in the :ref:`unified_tutorial`
|
| limit(self, limit: '_LimitOffsetType') -> 'Self'
| Return a new selectable with the given LIMIT criterion
| applied.
|
| This is a numerical value which usually renders as a ``LIMIT``
| expression in the resulting select. Backends that don't
| support ``LIMIT`` will attempt to provide similar
| functionality.
|
| .. note::
|
| The :meth:`_sql.GenerativeSelect.limit` method will replace
| any clause applied with :meth:`_sql.GenerativeSelect.fetch`.
|
| :param limit: an integer LIMIT parameter, or a SQL expression
| that provides an integer result. Pass ``None`` to reset it.
|
| .. seealso::
|
| :meth:`_sql.GenerativeSelect.fetch`
|
| :meth:`_sql.GenerativeSelect.offset`
|
| offset(self, offset: '_LimitOffsetType') -> 'Self'
| Return a new selectable with the given OFFSET criterion
| applied.
|
|
| This is a numeric value which usually renders as an ``OFFSET``
| expression in the resulting select. Backends that don't
| support ``OFFSET`` will attempt to provide similar
| functionality.
|
| :param offset: an integer OFFSET parameter, or a SQL expression
| that provides an integer result. Pass ``None`` to reset it.
|
| .. seealso::
|
| :meth:`_sql.GenerativeSelect.limit`
|
| :meth:`_sql.GenerativeSelect.fetch`
|
| order_by(self, _GenerativeSelect__first: 'Union[Literal[None, _NoArg.NO_ARG], _ColumnExpressionOrStrLabelArgument[Any]]' = _NoArg.NO_ARG, *clauses: '_ColumnExpressionOrStrLabelArgument[Any]') -> 'Self'
| Return a new selectable with the given list of ORDER BY
| criteria applied.
|
| e.g.::
|
| stmt = select(table).order_by(table.c.id, table.c.name)
|
| Calling this method multiple times is equivalent to calling it once
| with all the clauses concatenated. All existing ORDER BY criteria may
| be cancelled by passing ``None`` by itself. New ORDER BY criteria may
| then be added by invoking :meth:`_orm.Query.order_by` again, e.g.::
|
| # will erase all ORDER BY and ORDER BY new_col alone
| stmt = stmt.order_by(None).order_by(new_col)
|
| :param \*clauses: a series of :class:`_expression.ColumnElement`
| constructs which will be used to generate an ORDER BY clause.
|
| Alternatively, an individual entry may also be the string name of a
| label located elsewhere in the columns clause of the statement which
| will be matched and rendered in a backend-specific way based on
| context; see :ref:`tutorial_order_by_label` for background on string
| label matching in ORDER BY and GROUP BY expressions.
|
| .. seealso::
|
| :ref:`tutorial_order_by` - in the :ref:`unified_tutorial`
|
| :ref:`tutorial_order_by_label` - in the :ref:`unified_tutorial`
|
| set_label_style(self, style: 'SelectLabelStyle') -> 'Self'
| Return a new selectable with the specified label style.
|
| There are three "label styles" available,
| :attr:`_sql.SelectLabelStyle.LABEL_STYLE_DISAMBIGUATE_ONLY`,
| :attr:`_sql.SelectLabelStyle.LABEL_STYLE_TABLENAME_PLUS_COL`, and
| :attr:`_sql.SelectLabelStyle.LABEL_STYLE_NONE`. The default style is
| :attr:`_sql.SelectLabelStyle.LABEL_STYLE_DISAMBIGUATE_ONLY`.
|
| In modern SQLAlchemy, there is not generally a need to change the
| labeling style, as per-expression labels are more effectively used by
| making use of the :meth:`_sql.ColumnElement.label` method. In past
| versions, :data:`_sql.LABEL_STYLE_TABLENAME_PLUS_COL` was used to
| disambiguate same-named columns from different tables, aliases, or
| subqueries; the newer :data:`_sql.LABEL_STYLE_DISAMBIGUATE_ONLY` now
| applies labels only to names that conflict with an existing name so
| that the impact of this labeling is minimal.
|
| The rationale for disambiguation is mostly so that all column
| expressions are available from a given :attr:`_sql.FromClause.c`
| collection when a subquery is created.
|
| .. versionadded:: 1.4 - the
| :meth:`_sql.GenerativeSelect.set_label_style` method replaces the
| previous combination of ``.apply_labels()``, ``.with_labels()`` and
| ``use_labels=True`` methods and/or parameters.
|
| .. seealso::
|
| :data:`_sql.LABEL_STYLE_DISAMBIGUATE_ONLY`
|
| :data:`_sql.LABEL_STYLE_TABLENAME_PLUS_COL`
|
| :data:`_sql.LABEL_STYLE_NONE`
|
| :data:`_sql.LABEL_STYLE_DEFAULT`
|
| slice(self, start: 'int', stop: 'int') -> 'Self'
| Apply LIMIT / OFFSET to this statement based on a slice.
|
| The start and stop indices behave like the argument to Python's
| built-in :func:`range` function. This method provides an
| alternative to using ``LIMIT``/``OFFSET`` to get a slice of the
| query.
|
| For example, ::
|
| stmt = select(User).order_by(User.id).slice(1, 3)
|
| renders as
|
| .. sourcecode:: sql
|
| SELECT users.id AS users_id,
| users.name AS users_name
| FROM users ORDER BY users.id
| LIMIT ? OFFSET ?
| (2, 1)
|
| .. note::
|
| The :meth:`_sql.GenerativeSelect.slice` method will replace
| any clause applied with :meth:`_sql.GenerativeSelect.fetch`.
|
| .. versionadded:: 1.4 Added the :meth:`_sql.GenerativeSelect.slice`
| method generalized from the ORM.
|
| .. seealso::
|
| :meth:`_sql.GenerativeSelect.limit`
|
| :meth:`_sql.GenerativeSelect.offset`
|
| :meth:`_sql.GenerativeSelect.fetch`
|
| with_for_update(self, *, nowait: 'bool' = False, read: 'bool' = False, of: 'Optional[_ForUpdateOfArgument]' = None, skip_locked: 'bool' = False, key_share: 'bool' = False) -> 'Self'
| Specify a ``FOR UPDATE`` clause for this
| :class:`_expression.GenerativeSelect`.
|
| E.g.::
|
| stmt = select(table).with_for_update(nowait=True)
|
| On a database like PostgreSQL or Oracle Database, the above would
| render a statement like:
|
| .. sourcecode:: sql
|
| SELECT table.a, table.b FROM table FOR UPDATE NOWAIT
|
| on other backends, the ``nowait`` option is ignored and instead
| would produce:
|
| .. sourcecode:: sql
|
| SELECT table.a, table.b FROM table FOR UPDATE
|
| When called with no arguments, the statement will render with
| the suffix ``FOR UPDATE``. Additional arguments can then be
| provided which allow for common database-specific
| variants.
|
| :param nowait: boolean; will render ``FOR UPDATE NOWAIT`` on Oracle
| Database and PostgreSQL dialects.
|
| :param read: boolean; will render ``LOCK IN SHARE MODE`` on MySQL,
| ``FOR SHARE`` on PostgreSQL. On PostgreSQL, when combined with
| ``nowait``, will render ``FOR SHARE NOWAIT``.
|
| :param of: SQL expression or list of SQL expression elements,
| (typically :class:`_schema.Column` objects or a compatible expression,
| for some backends may also be a table expression) which will render
| into a ``FOR UPDATE OF`` clause; supported by PostgreSQL, Oracle
| Database, some MySQL versions and possibly others. May render as a
| table or as a column depending on backend.
|
| :param skip_locked: boolean, will render ``FOR UPDATE SKIP LOCKED`` on
| Oracle Database and PostgreSQL dialects or ``FOR SHARE SKIP LOCKED``
| if ``read=True`` is also specified.
|
| :param key_share: boolean, will render ``FOR NO KEY UPDATE``,
| or if combined with ``read=True`` will render ``FOR KEY SHARE``,
| on the PostgreSQL dialect.
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.base.DialectKWArgs:
|
| dialect_options(...)
| A collection of keyword arguments specified as dialect-specific
| options to this construct.
|
| This is a two-level nested registry, keyed to ``<dialect_name>``
| and ``<argument_name>``. For example, the ``postgresql_where``
| argument would be locatable as::
|
| arg = my_object.dialect_options["postgresql"]["where"]
|
| .. versionadded:: 0.9.2
|
| .. seealso::
|
| :attr:`.DialectKWArgs.dialect_kwargs` - flat dictionary form
|
| get_dialect_option(self, dialect: 'Dialect', argument_name: 'str', *, else_: 'Any' = None, deprecated_fallback: 'Optional[str]' = None) -> 'Any'
| Return the value of a dialect-specific option, or *else_* if
| this dialect does not register the given argument.
|
| This is useful for DDL compilers that may be inherited by
| third-party dialects whose ``construct_arguments`` do not
| include the same set of keys as the parent dialect.
|
| :param dialect: The dialect for which to retrieve the option.
| :param argument_name: The name of the argument to retrieve.
| :param else\_: The value to return if the argument is not present.
| :param deprecated_fallback: Optional dialect name to fall back to
| if the argument is not present for the current dialect. If the
| argument is present for the fallback dialect but not the current
| dialect, a deprecation warning will be emitted.
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.base.DialectKWArgs:
|
| argument_for(dialect_name: 'str', argument_name: 'str', default: 'Any') -> 'None'
| Add a new kind of dialect-specific keyword argument for this class.
|
| E.g.::
|
| Index.argument_for("mydialect", "length", None)
|
| some_index = Index("a", "b", mydialect_length=5)
|
| The :meth:`.DialectKWArgs.argument_for` method is a per-argument
| way adding extra arguments to the
| :attr:`.DefaultDialect.construct_arguments` dictionary. This
| dictionary provides a list of argument names accepted by various
| schema-level constructs on behalf of a dialect.
|
| New dialects should typically specify this dictionary all at once as a
| data member of the dialect class. The use case for ad-hoc addition of
| argument names is typically for end-user code that is also using
| a custom compilation scheme which consumes the additional arguments.
|
| :param dialect_name: name of a dialect. The dialect must be
| locatable, else a :class:`.NoSuchModuleError` is raised. The
| dialect must also include an existing
| :attr:`.DefaultDialect.construct_arguments` collection, indicating
| that it participates in the keyword-argument validation and default
| system, else :class:`.ArgumentError` is raised. If the dialect does
| not include this collection, then any keyword argument can be
| specified on behalf of this dialect already. All dialects packaged
| within SQLAlchemy include this collection, however for third party
| dialects, support may vary.
|
| :param argument_name: name of the parameter.
|
| :param default: default value of the parameter.
|
| ----------------------------------------------------------------------
| Readonly properties inherited from sqlalchemy.sql.base.DialectKWArgs:
|
| dialect_kwargs
| A collection of keyword arguments specified as dialect-specific
| options to this construct.
|
| The arguments are present here in their original ``<dialect>_<kwarg>``
| format. Only arguments that were actually passed are included;
| unlike the :attr:`.DialectKWArgs.dialect_options` collection, which
| contains all options known by this dialect including defaults.
|
| The collection is also writable; keys are accepted of the
| form ``<dialect>_<kwarg>`` where the value will be assembled
| into the list of options.
|
| .. seealso::
|
| :attr:`.DialectKWArgs.dialect_options` - nested dictionary form
|
| kwargs
| A synonym for :attr:`.DialectKWArgs.dialect_kwargs`.
|
| ----------------------------------------------------------------------
| Methods inherited from SelectBase:
|
| alias(self, name: 'Optional[str]' = None, flat: 'bool' = False) -> 'Subquery'
| 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.
|
| as_scalar(self) -> 'ScalarSelect[Any]'
| .. 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`.
|
| exists(self) -> 'Exists'
| 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
|
| label(self, name: 'Optional[str]') -> 'Label[Any]'
| Return a 'scalar' representation of this selectable, embedded as a
| subquery with a label.
|
| .. seealso::
|
| :meth:`_expression.SelectBase.scalar_subquery`.
|
| 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.
|
| scalar_subquery(self) -> 'ScalarSelect[Any]'
| 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
|
| select(self, *arg: 'Any', **kw: 'Any') -> 'Select[Any]'
| .. 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.
|
| subquery(self, name: 'Optional[str]' = None) -> '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:
|
| .. sourcecode:: sql
|
| 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:
|
| .. sourcecode:: sql
|
| 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
|
| ----------------------------------------------------------------------
| Readonly properties inherited from SelectBase:
|
| c
| .. 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.
|
| columns
|
| 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`
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from SelectBase:
|
| is_select = True
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from TypedReturnsRows:
|
| __orig_bases__ = (<class 'sqlalchemy.sql.selectable.ExecutableReturnsR...
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.base.Executable:
|
| execution_options(self, **kw: 'Any') -> 'Self'
| Set non-SQL options for the statement which take effect during
| execution.
|
| Execution options can be set at many scopes, including per-statement,
| per-connection, or per execution, using methods such as
| :meth:`_engine.Connection.execution_options` and parameters which
| accept a dictionary of options such as
| :paramref:`_engine.Connection.execute.execution_options` and
| :paramref:`_orm.Session.execute.execution_options`.
|
| The primary characteristic of an execution option, as opposed to
| other kinds of options such as ORM loader options, is that
| **execution options never affect the compiled SQL of a query, only
| things that affect how the SQL statement itself is invoked or how
| results are fetched**. That is, execution options are not part of
| what's accommodated by SQL compilation nor are they considered part of
| the cached state of a statement.
|
| The :meth:`_sql.Executable.execution_options` method is
| :term:`generative`, as
| is the case for the method as applied to the :class:`_engine.Engine`
| and :class:`_orm.Query` objects, which means when the method is called,
| a copy of the object is returned, which applies the given parameters to
| that new copy, but leaves the original unchanged::
|
| statement = select(table.c.x, table.c.y)
| new_statement = statement.execution_options(my_option=True)
|
| An exception to this behavior is the :class:`_engine.Connection`
| object, where the :meth:`_engine.Connection.execution_options` method
| is explicitly **not** generative.
|
| The kinds of options that may be passed to
| :meth:`_sql.Executable.execution_options` and other related methods and
| parameter dictionaries include parameters that are explicitly consumed
| by SQLAlchemy Core or ORM, as well as arbitrary keyword arguments not
| defined by SQLAlchemy, which means the methods and/or parameter
| dictionaries may be used for user-defined parameters that interact with
| custom code, which may access the parameters using methods such as
| :meth:`_sql.Executable.get_execution_options` and
| :meth:`_engine.Connection.get_execution_options`, or within selected
| event hooks using a dedicated ``execution_options`` event parameter
| such as
| :paramref:`_events.ConnectionEvents.before_execute.execution_options`
| or :attr:`_orm.ORMExecuteState.execution_options`, e.g.::
|
| from sqlalchemy import event
|
|
| @event.listens_for(some_engine, "before_execute")
| def _process_opt(conn, statement, multiparams, params, execution_options):
| "run a SQL function before invoking a statement"
|
| if execution_options.get("do_special_thing", False):
| conn.exec_driver_sql("run_special_function()")
|
| Within the scope of options that are explicitly recognized by
| SQLAlchemy, most apply to specific classes of objects and not others.
| The most common execution options include:
|
| * :paramref:`_engine.Connection.execution_options.isolation_level` -
| sets the isolation level for a connection or a class of connections
| via an :class:`_engine.Engine`. This option is accepted only
| by :class:`_engine.Connection` or :class:`_engine.Engine`.
|
| * :paramref:`_engine.Connection.execution_options.stream_results` -
| indicates results should be fetched using a server side cursor;
| this option is accepted by :class:`_engine.Connection`, by the
| :paramref:`_engine.Connection.execute.execution_options` parameter
| on :meth:`_engine.Connection.execute`, and additionally by
| :meth:`_sql.Executable.execution_options` on a SQL statement object,
| as well as by ORM constructs like :meth:`_orm.Session.execute`.
|
| * :paramref:`_engine.Connection.execution_options.compiled_cache` -
| indicates a dictionary that will serve as the
| :ref:`SQL compilation cache <sql_caching>`
| for a :class:`_engine.Connection` or :class:`_engine.Engine`, as
| well as for ORM methods like :meth:`_orm.Session.execute`.
| Can be passed as ``None`` to disable caching for statements.
| This option is not accepted by
| :meth:`_sql.Executable.execution_options` as it is inadvisable to
| carry along a compilation cache within a statement object.
|
| * :paramref:`_engine.Connection.execution_options.schema_translate_map`
| - a mapping of schema names used by the
| :ref:`Schema Translate Map <schema_translating>` feature, accepted
| by :class:`_engine.Connection`, :class:`_engine.Engine`,
| :class:`_sql.Executable`, as well as by ORM constructs
| like :meth:`_orm.Session.execute`.
|
| .. seealso::
|
| :meth:`_engine.Connection.execution_options`
|
| :paramref:`_engine.Connection.execute.execution_options`
|
| :paramref:`_orm.Session.execute.execution_options`
|
| :ref:`orm_queryguide_execution_options` - documentation on all
| ORM-specific execution options
|
| get_execution_options(self) -> '_ExecuteOptions'
| Get the non-SQL options which will take effect during execution.
|
| .. versionadded:: 1.3
|
| .. seealso::
|
| :meth:`.Executable.execution_options`
|
| options(self, *options: 'ExecutableOption') -> 'Self'
| Apply options to this statement.
|
| In the general sense, options are any kind of Python object
| that can be interpreted by the SQL compiler for the statement.
| These options can be consumed by specific dialects or specific kinds
| of compilers.
|
| The most commonly known kind of option are the ORM level options
| that apply "eager load" and other loading behaviors to an ORM
| query. However, options can theoretically be used for many other
| purposes.
|
| For background on specific kinds of options for specific kinds of
| statements, refer to the documentation for those option objects.
|
| .. versionchanged:: 1.4 - added :meth:`.Executable.options` to
| Core statement objects towards the goal of allowing unified
| Core / ORM querying capabilities.
|
| .. seealso::
|
| :ref:`loading_columns` - refers to options specific to the usage
| of ORM queries
|
| :ref:`relationship_loader_options` - refers to options specific
| to the usage of ORM queries
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.base.Executable:
|
| is_delete = False
|
| is_dml = False
|
| is_from_statement = False
|
| is_insert = False
|
| is_text = False
|
| is_update = False
|
| supports_execution = True
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.AllowsLambdaRole:
|
| allows_lambda = True
|
| ----------------------------------------------------------------------
| Methods inherited from HasCTE:
|
| add_cte(self, *ctes: 'CTE', nest_here: 'bool' = False) -> 'Self'
| Add one or more :class:`_sql.CTE` constructs to this statement.
|
| This method will associate the given :class:`_sql.CTE` constructs with
| the parent statement such that they will each be unconditionally
| rendered in the WITH clause of the final statement, even if not
| referenced elsewhere within the statement or any sub-selects.
|
| The optional :paramref:`.HasCTE.add_cte.nest_here` parameter when set
| to True will have the effect that each given :class:`_sql.CTE` will
| render in a WITH clause rendered directly along with this statement,
| rather than being moved to the top of the ultimate rendered statement,
| even if this statement is rendered as a subquery within a larger
| statement.
|
| This method has two general uses. One is to embed CTE statements that
| serve some purpose without being referenced explicitly, such as the use
| case of embedding a DML statement such as an INSERT or UPDATE as a CTE
| inline with a primary statement that may draw from its results
| indirectly. The other is to provide control over the exact placement
| of a particular series of CTE constructs that should remain rendered
| directly in terms of a particular statement that may be nested in a
| larger statement.
|
| E.g.::
|
| from sqlalchemy import table, column, select
|
| t = table("t", column("c1"), column("c2"))
|
| ins = t.insert().values({"c1": "x", "c2": "y"}).cte()
|
| stmt = select(t).add_cte(ins)
|
| Would render:
|
| .. sourcecode:: sql
|
| WITH anon_1 AS (
| INSERT INTO t (c1, c2) VALUES (:param_1, :param_2)
| )
| SELECT t.c1, t.c2
| FROM t
|
| Above, the "anon_1" CTE is not referenced in the SELECT
| statement, however still accomplishes the task of running an INSERT
| statement.
|
| Similarly in a DML-related context, using the PostgreSQL
| :class:`_postgresql.Insert` construct to generate an "upsert"::
|
| from sqlalchemy import table, column
| from sqlalchemy.dialects.postgresql import insert
|
| t = table("t", column("c1"), column("c2"))
|
| delete_statement_cte = t.delete().where(t.c.c1 < 1).cte("deletions")
|
| insert_stmt = insert(t).values({"c1": 1, "c2": 2})
| update_statement = insert_stmt.on_conflict_do_update(
| index_elements=[t.c.c1],
| set_={
| "c1": insert_stmt.excluded.c1,
| "c2": insert_stmt.excluded.c2,
| },
| ).add_cte(delete_statement_cte)
|
| print(update_statement)
|
| The above statement renders as:
|
| .. sourcecode:: sql
|
| WITH deletions AS (
| DELETE FROM t WHERE t.c1 < %(c1_1)s
| )
| INSERT INTO t (c1, c2) VALUES (%(c1)s, %(c2)s)
| ON CONFLICT (c1) DO UPDATE SET c1 = excluded.c1, c2 = excluded.c2
|
| .. versionadded:: 1.4.21
|
| :param \*ctes: zero or more :class:`.CTE` constructs.
|
| .. versionchanged:: 2.0 Multiple CTE instances are accepted
|
| :param nest_here: if True, the given CTE or CTEs will be rendered
| as though they specified the :paramref:`.HasCTE.cte.nesting` flag
| to ``True`` when they were added to this :class:`.HasCTE`.
| Assuming the given CTEs are not referenced in an outer-enclosing
| statement as well, the CTEs given should render at the level of
| this statement when this flag is given.
|
| .. versionadded:: 2.0
|
| .. seealso::
|
| :paramref:`.HasCTE.cte.nesting`
|
| cte(self, name: 'Optional[str]' = None, recursive: 'bool' = False, nesting: 'bool' = False) -> 'CTE'
| Return a new :class:`_expression.CTE`,
| or Common Table Expression instance.
|
| Common table expressions are a SQL standard whereby SELECT
| statements can draw upon secondary statements specified along
| with the primary statement, using a clause called "WITH".
| Special semantics regarding UNION can also be employed to
| allow "recursive" queries, where a SELECT statement can draw
| upon the set of rows that have previously been selected.
|
| CTEs can also be applied to DML constructs UPDATE, INSERT
| and DELETE on some databases, both as a source of CTE rows
| when combined with RETURNING, as well as a consumer of
| CTE rows.
|
| SQLAlchemy detects :class:`_expression.CTE` objects, which are treated
| similarly to :class:`_expression.Alias` objects, as special elements
| to be delivered to the FROM clause of the statement as well
| as to a WITH clause at the top of the statement.
|
| For special prefixes such as PostgreSQL "MATERIALIZED" and
| "NOT MATERIALIZED", the :meth:`_expression.CTE.prefix_with`
| method may be
| used to establish these.
|
| .. versionchanged:: 1.3.13 Added support for prefixes.
| In particular - MATERIALIZED and NOT MATERIALIZED.
|
| :param name: name given to the common table expression. Like
| :meth:`_expression.FromClause.alias`, the name can be left as
| ``None`` in which case an anonymous symbol will be used at query
| compile time.
| :param recursive: if ``True``, will render ``WITH RECURSIVE``.
| A recursive common table expression is intended to be used in
| conjunction with UNION ALL in order to derive rows
| from those already selected.
| :param nesting: if ``True``, will render the CTE locally to the
| statement in which it is referenced. For more complex scenarios,
| the :meth:`.HasCTE.add_cte` method using the
| :paramref:`.HasCTE.add_cte.nest_here`
| parameter may also be used to more carefully
| control the exact placement of a particular CTE.
|
| .. versionadded:: 1.4.24
|
| .. seealso::
|
| :meth:`.HasCTE.add_cte`
|
| The following examples include two from PostgreSQL's documentation at
| https://www.postgresql.org/docs/current/static/queries-with.html,
| as well as additional examples.
|
| Example 1, non recursive::
|
| from sqlalchemy import (
| Table,
| Column,
| String,
| Integer,
| MetaData,
| select,
| func,
| )
|
| metadata = MetaData()
|
| orders = Table(
| "orders",
| metadata,
| Column("region", String),
| Column("amount", Integer),
| Column("product", String),
| Column("quantity", Integer),
| )
|
| regional_sales = (
| select(orders.c.region, func.sum(orders.c.amount).label("total_sales"))
| .group_by(orders.c.region)
| .cte("regional_sales")
| )
|
|
| top_regions = (
| select(regional_sales.c.region)
| .where(
| regional_sales.c.total_sales
| > select(func.sum(regional_sales.c.total_sales) / 10)
| )
| .cte("top_regions")
| )
|
| statement = (
| select(
| orders.c.region,
| orders.c.product,
| func.sum(orders.c.quantity).label("product_units"),
| func.sum(orders.c.amount).label("product_sales"),
| )
| .where(orders.c.region.in_(select(top_regions.c.region)))
| .group_by(orders.c.region, orders.c.product)
| )
|
| result = conn.execute(statement).fetchall()
|
| Example 2, WITH RECURSIVE::
|
| from sqlalchemy import (
| Table,
| Column,
| String,
| Integer,
| MetaData,
| select,
| func,
| )
|
| metadata = MetaData()
|
| parts = Table(
| "parts",
| metadata,
| Column("part", String),
| Column("sub_part", String),
| Column("quantity", Integer),
| )
|
| included_parts = (
| select(parts.c.sub_part, parts.c.part, parts.c.quantity)
| .where(parts.c.part == "our part")
| .cte(recursive=True)
| )
|
|
| incl_alias = included_parts.alias()
| parts_alias = parts.alias()
| included_parts = included_parts.union_all(
| select(
| parts_alias.c.sub_part, parts_alias.c.part, parts_alias.c.quantity
| ).where(parts_alias.c.part == incl_alias.c.sub_part)
| )
|
| statement = select(
| included_parts.c.sub_part,
| func.sum(included_parts.c.quantity).label("total_quantity"),
| ).group_by(included_parts.c.sub_part)
|
| result = conn.execute(statement).fetchall()
|
| Example 3, an upsert using UPDATE and INSERT with CTEs::
|
| from datetime import date
| from sqlalchemy import (
| MetaData,
| Table,
| Column,
| Integer,
| Date,
| select,
| literal,
| and_,
| exists,
| )
|
| metadata = MetaData()
|
| visitors = Table(
| "visitors",
| metadata,
| Column("product_id", Integer, primary_key=True),
| Column("date", Date, primary_key=True),
| Column("count", Integer),
| )
|
| # add 5 visitors for the product_id == 1
| product_id = 1
| day = date.today()
| count = 5
|
| update_cte = (
| visitors.update()
| .where(
| and_(visitors.c.product_id == product_id, visitors.c.date == day)
| )
| .values(count=visitors.c.count + count)
| .returning(literal(1))
| .cte("update_cte")
| )
|
| upsert = visitors.insert().from_select(
| [visitors.c.product_id, visitors.c.date, visitors.c.count],
| select(literal(product_id), literal(day), literal(count)).where(
| ~exists(update_cte.select())
| ),
| )
|
| connection.execute(upsert)
|
| Example 4, Nesting CTE (SQLAlchemy 1.4.24 and above)::
|
| value_a = select(literal("root").label("n")).cte("value_a")
|
| # A nested CTE with the same name as the root one
| value_a_nested = select(literal("nesting").label("n")).cte(
| "value_a", nesting=True
| )
|
| # Nesting CTEs takes ascendency locally
| # over the CTEs at a higher level
| value_b = select(value_a_nested.c.n).cte("value_b")
|
| value_ab = select(value_a.c.n.label("a"), value_b.c.n.label("b"))
|
| The above query will render the second CTE nested inside the first,
| shown with inline parameters below as:
|
| .. sourcecode:: sql
|
| WITH
| value_a AS
| (SELECT 'root' AS n),
| value_b AS
| (WITH value_a AS
| (SELECT 'nesting' AS n)
| SELECT value_a.n AS n FROM value_a)
| SELECT value_a.n AS a, value_b.n AS b
| FROM value_a, value_b
|
| The same CTE can be set up using the :meth:`.HasCTE.add_cte` method
| as follows (SQLAlchemy 2.0 and above)::
|
| value_a = select(literal("root").label("n")).cte("value_a")
|
| # A nested CTE with the same name as the root one
| value_a_nested = select(literal("nesting").label("n")).cte("value_a")
|
| # Nesting CTEs takes ascendency locally
| # over the CTEs at a higher level
| value_b = (
| select(value_a_nested.c.n)
| .add_cte(value_a_nested, nest_here=True)
| .cte("value_b")
| )
|
| value_ab = select(value_a.c.n.label("a"), value_b.c.n.label("b"))
|
| Example 5, Non-Linear CTE (SQLAlchemy 1.4.28 and above)::
|
| edge = Table(
| "edge",
| metadata,
| Column("id", Integer, primary_key=True),
| Column("left", Integer),
| Column("right", Integer),
| )
|
| root_node = select(literal(1).label("node")).cte("nodes", recursive=True)
|
| left_edge = select(edge.c.left).join(
| root_node, edge.c.right == root_node.c.node
| )
| right_edge = select(edge.c.right).join(
| root_node, edge.c.left == root_node.c.node
| )
|
| subgraph_cte = root_node.union(left_edge, right_edge)
|
| subgraph = select(subgraph_cte)
|
| The above query will render 2 UNIONs inside the recursive CTE:
|
| .. sourcecode:: sql
|
| WITH RECURSIVE nodes(node) AS (
| SELECT 1 AS node
| UNION
| SELECT edge."left" AS "left"
| FROM edge JOIN nodes ON edge."right" = nodes.node
| UNION
| SELECT edge."right" AS "right"
| FROM edge JOIN nodes ON edge."left" = nodes.node
| )
| SELECT nodes.node FROM nodes
|
| .. seealso::
|
| :meth:`_orm.Query.cte` - ORM version of
| :meth:`_expression.HasCTE.cte`.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from HasCTE:
|
| name_cte_columns = False
|
| ----------------------------------------------------------------------
| Methods inherited from Selectable:
|
| 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.
|
| 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`.
|
| .. deprecated:: 1.4 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.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from Selectable:
|
| is_selectable = True
|
| ----------------------------------------------------------------------
| Readonly properties inherited from ReturnsRows:
|
| selectable
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.SQLRole:
|
| uses_inspection = False
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.elements.ClauseElement:
|
| __bool__(self)
|
| __getstate__(self)
| Helper for pickle.
|
| __invert__(self)
|
| __repr__(self)
| Return repr(self).
|
| compare(self, other: 'ClauseElement', **kw: 'Any') -> 'bool'
| Compare this :class:`_expression.ClauseElement` to
| the given :class:`_expression.ClauseElement`.
|
| Subclasses should override the default behavior, which is a
| straight identity comparison.
|
| \**kw are arguments consumed by subclass ``compare()`` methods and
| may be used to modify the criteria for comparison
| (see :class:`_expression.ColumnElement`).
|
| description(...)
|
| entity_namespace(...)
|
| params(self, _ClauseElement__optionaldict: 'Optional[Mapping[str, Any]]' = None, **kwargs: 'Any') -> 'Self'
| Return a copy with :func:`_expression.bindparam` elements
| replaced.
|
| Returns a copy of this ClauseElement with
| :func:`_expression.bindparam`
| elements replaced with values taken from the given dictionary::
|
| >>> clause = column("x") + bindparam("foo")
| >>> print(clause.compile().params)
| {'foo':None}
| >>> print(clause.params({"foo": 7}).compile().params)
| {'foo':7}
|
| unique_params(self, _ClauseElement__optionaldict: 'Optional[Dict[str, Any]]' = None, **kwargs: 'Any') -> 'Self'
| Return a copy with :func:`_expression.bindparam` elements
| replaced.
|
| Same functionality as :meth:`_expression.ClauseElement.params`,
| except adds `unique=True`
| to affected bind parameters so that multiple statements can be
| used.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.elements.ClauseElement:
|
| is_clause_element = True
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.cache_key.HasCacheKey:
|
| inherit_cache = None
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_instancemethod(fn: '_F') -> '_F'
| Decorate a method memoize its return value.
|
| :meta private:
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_attribute = <class 'sqlalchemy.util.langhelpers.HasMemoized.m...
| A read-only @property that is only evaluated once.
|
| :meta private:
|
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.elements.CompilerElement:
|
| __str__(self) -> 'str'
| Return str(self).
|
| compile(self, bind: 'Optional[_HasDialect]' = None, dialect: 'Optional[Dialect]' = None, **kw: 'Any') -> 'Compiled'
| Compile this SQL expression.
|
| The return value is a :class:`~.Compiled` object.
| Calling ``str()`` or ``unicode()`` on the returned value will yield a
| string representation of the result. The
| :class:`~.Compiled` object also can return a
| dictionary of bind parameter names and values
| using the ``params`` accessor.
|
| :param bind: An :class:`.Connection` or :class:`.Engine` which
| can provide a :class:`.Dialect` in order to generate a
| :class:`.Compiled` object. If the ``bind`` and
| ``dialect`` parameters are both omitted, a default SQL compiler
| is used.
|
| :param column_keys: Used for INSERT and UPDATE statements, a list of
| column names which should be present in the VALUES clause of the
| compiled statement. If ``None``, all columns from the target table
| object are rendered.
|
| :param dialect: A :class:`.Dialect` instance which can generate
| a :class:`.Compiled` object. This argument takes precedence over
| the ``bind`` argument.
|
| :param compile_kwargs: optional dictionary of additional parameters
| that will be passed through to the compiler within all "visit"
| methods. This allows any custom flag to be passed through to
| a custom compilation construct, for example. It is also used
| for the case of passing the ``literal_binds`` flag through::
|
| from sqlalchemy.sql import table, column, select
|
| t = table("t", column("x"))
|
| s = select(t).where(t.c.x == 5)
|
| print(s.compile(compile_kwargs={"literal_binds": True}))
|
| .. seealso::
|
| :ref:`faq_sql_expression_string`
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.elements.CompilerElement:
|
| stringify_dialect = 'default'
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.visitors.Visitable:
|
| __class_getitem__(key: 'Any') -> 'Any'
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__() -> 'None'
| This method is called when a class is subclassed.
|
| The default implementation does nothing. It may be
| overridden to extend subclasses.
sqlalchemy.SelectBase
Python Library Documentation: class SelectBase in module sqlalchemy.sql.selectable
class SelectBase(sqlalchemy.sql.roles.SelectStatementRole, sqlalchemy.sql.roles.DMLSelectRole, sqlalchemy.sql.roles.CompoundElementRole, sqlalchemy.sql.roles.InElementRole, HasCTE, sqlalchemy.sql.annotation.SupportsCloneAnnotations, Selectable)
| Base class for SELECT statements.
|
|
| This includes :class:`_expression.Select`,
| :class:`_expression.CompoundSelect` and
| :class:`_expression.TextualSelect`.
|
| Method resolution order:
| SelectBase
| sqlalchemy.sql.roles.SelectStatementRole
| sqlalchemy.sql.roles.StatementRole
| sqlalchemy.sql.roles.DMLSelectRole
| sqlalchemy.sql.roles.CompoundElementRole
| sqlalchemy.sql.roles.AllowsLambdaRole
| sqlalchemy.sql.roles.InElementRole
| HasCTE
| sqlalchemy.sql.roles.HasCTERole
| SelectsRows
| sqlalchemy.sql.annotation.SupportsCloneAnnotations
| Selectable
| ReturnsRows
| sqlalchemy.sql.roles.ReturnsRowsRole
| sqlalchemy.sql.roles.SQLRole
| sqlalchemy.sql.elements.DQLDMLClauseElement
| sqlalchemy.sql.elements.ClauseElement
| sqlalchemy.sql.annotation.SupportsWrappingAnnotations
| sqlalchemy.sql.annotation.SupportsAnnotations
| sqlalchemy.sql.cache_key.MemoizedHasCacheKey
| sqlalchemy.sql.cache_key.HasCacheKey
| sqlalchemy.util.langhelpers.HasMemoized
| sqlalchemy.sql.traversals.HasCopyInternals
| sqlalchemy.sql.visitors.ExternallyTraversible
| sqlalchemy.sql.visitors.HasTraverseInternals
| sqlalchemy.sql.elements.CompilerElement
| sqlalchemy.sql.visitors.Visitable
| builtins.object
|
| Methods defined here:
|
| alias(self, name: 'Optional[str]' = None, flat: 'bool' = False) -> 'Subquery'
| 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.
|
| as_scalar(self) -> 'ScalarSelect[Any]'
| .. 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`.
|
| exists(self) -> 'Exists'
| 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
|
| get_label_style(self) -> 'SelectLabelStyle'
| Retrieve the current label style.
|
| Implemented by subclasses.
|
| label(self, name: 'Optional[str]') -> 'Label[Any]'
| Return a 'scalar' representation of this selectable, embedded as a
| subquery with a label.
|
| .. seealso::
|
| :meth:`_expression.SelectBase.scalar_subquery`.
|
| 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.
|
| scalar_subquery(self) -> 'ScalarSelect[Any]'
| 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
|
| select(self, *arg: 'Any', **kw: 'Any') -> 'Select[Any]'
| .. 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.
|
| selected_columns(...)
| 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
|
| set_label_style(self, style: 'SelectLabelStyle') -> 'Self'
| Return a new selectable with the specified label style.
|
| Implemented by subclasses.
|
| subquery(self, name: 'Optional[str]' = None) -> '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:
|
| .. sourcecode:: sql
|
| 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:
|
| .. sourcecode:: sql
|
| 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
|
| ----------------------------------------------------------------------
| Readonly properties defined here:
|
| c
| .. 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.
|
| columns
|
| 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`
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'_label_style': 'SelectLabelStyle'}
|
| is_select = True
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.AllowsLambdaRole:
|
| allows_lambda = True
|
| ----------------------------------------------------------------------
| Methods inherited from HasCTE:
|
| add_cte(self, *ctes: 'CTE', nest_here: 'bool' = False) -> 'Self'
| Add one or more :class:`_sql.CTE` constructs to this statement.
|
| This method will associate the given :class:`_sql.CTE` constructs with
| the parent statement such that they will each be unconditionally
| rendered in the WITH clause of the final statement, even if not
| referenced elsewhere within the statement or any sub-selects.
|
| The optional :paramref:`.HasCTE.add_cte.nest_here` parameter when set
| to True will have the effect that each given :class:`_sql.CTE` will
| render in a WITH clause rendered directly along with this statement,
| rather than being moved to the top of the ultimate rendered statement,
| even if this statement is rendered as a subquery within a larger
| statement.
|
| This method has two general uses. One is to embed CTE statements that
| serve some purpose without being referenced explicitly, such as the use
| case of embedding a DML statement such as an INSERT or UPDATE as a CTE
| inline with a primary statement that may draw from its results
| indirectly. The other is to provide control over the exact placement
| of a particular series of CTE constructs that should remain rendered
| directly in terms of a particular statement that may be nested in a
| larger statement.
|
| E.g.::
|
| from sqlalchemy import table, column, select
|
| t = table("t", column("c1"), column("c2"))
|
| ins = t.insert().values({"c1": "x", "c2": "y"}).cte()
|
| stmt = select(t).add_cte(ins)
|
| Would render:
|
| .. sourcecode:: sql
|
| WITH anon_1 AS (
| INSERT INTO t (c1, c2) VALUES (:param_1, :param_2)
| )
| SELECT t.c1, t.c2
| FROM t
|
| Above, the "anon_1" CTE is not referenced in the SELECT
| statement, however still accomplishes the task of running an INSERT
| statement.
|
| Similarly in a DML-related context, using the PostgreSQL
| :class:`_postgresql.Insert` construct to generate an "upsert"::
|
| from sqlalchemy import table, column
| from sqlalchemy.dialects.postgresql import insert
|
| t = table("t", column("c1"), column("c2"))
|
| delete_statement_cte = t.delete().where(t.c.c1 < 1).cte("deletions")
|
| insert_stmt = insert(t).values({"c1": 1, "c2": 2})
| update_statement = insert_stmt.on_conflict_do_update(
| index_elements=[t.c.c1],
| set_={
| "c1": insert_stmt.excluded.c1,
| "c2": insert_stmt.excluded.c2,
| },
| ).add_cte(delete_statement_cte)
|
| print(update_statement)
|
| The above statement renders as:
|
| .. sourcecode:: sql
|
| WITH deletions AS (
| DELETE FROM t WHERE t.c1 < %(c1_1)s
| )
| INSERT INTO t (c1, c2) VALUES (%(c1)s, %(c2)s)
| ON CONFLICT (c1) DO UPDATE SET c1 = excluded.c1, c2 = excluded.c2
|
| .. versionadded:: 1.4.21
|
| :param \*ctes: zero or more :class:`.CTE` constructs.
|
| .. versionchanged:: 2.0 Multiple CTE instances are accepted
|
| :param nest_here: if True, the given CTE or CTEs will be rendered
| as though they specified the :paramref:`.HasCTE.cte.nesting` flag
| to ``True`` when they were added to this :class:`.HasCTE`.
| Assuming the given CTEs are not referenced in an outer-enclosing
| statement as well, the CTEs given should render at the level of
| this statement when this flag is given.
|
| .. versionadded:: 2.0
|
| .. seealso::
|
| :paramref:`.HasCTE.cte.nesting`
|
| cte(self, name: 'Optional[str]' = None, recursive: 'bool' = False, nesting: 'bool' = False) -> 'CTE'
| Return a new :class:`_expression.CTE`,
| or Common Table Expression instance.
|
| Common table expressions are a SQL standard whereby SELECT
| statements can draw upon secondary statements specified along
| with the primary statement, using a clause called "WITH".
| Special semantics regarding UNION can also be employed to
| allow "recursive" queries, where a SELECT statement can draw
| upon the set of rows that have previously been selected.
|
| CTEs can also be applied to DML constructs UPDATE, INSERT
| and DELETE on some databases, both as a source of CTE rows
| when combined with RETURNING, as well as a consumer of
| CTE rows.
|
| SQLAlchemy detects :class:`_expression.CTE` objects, which are treated
| similarly to :class:`_expression.Alias` objects, as special elements
| to be delivered to the FROM clause of the statement as well
| as to a WITH clause at the top of the statement.
|
| For special prefixes such as PostgreSQL "MATERIALIZED" and
| "NOT MATERIALIZED", the :meth:`_expression.CTE.prefix_with`
| method may be
| used to establish these.
|
| .. versionchanged:: 1.3.13 Added support for prefixes.
| In particular - MATERIALIZED and NOT MATERIALIZED.
|
| :param name: name given to the common table expression. Like
| :meth:`_expression.FromClause.alias`, the name can be left as
| ``None`` in which case an anonymous symbol will be used at query
| compile time.
| :param recursive: if ``True``, will render ``WITH RECURSIVE``.
| A recursive common table expression is intended to be used in
| conjunction with UNION ALL in order to derive rows
| from those already selected.
| :param nesting: if ``True``, will render the CTE locally to the
| statement in which it is referenced. For more complex scenarios,
| the :meth:`.HasCTE.add_cte` method using the
| :paramref:`.HasCTE.add_cte.nest_here`
| parameter may also be used to more carefully
| control the exact placement of a particular CTE.
|
| .. versionadded:: 1.4.24
|
| .. seealso::
|
| :meth:`.HasCTE.add_cte`
|
| The following examples include two from PostgreSQL's documentation at
| https://www.postgresql.org/docs/current/static/queries-with.html,
| as well as additional examples.
|
| Example 1, non recursive::
|
| from sqlalchemy import (
| Table,
| Column,
| String,
| Integer,
| MetaData,
| select,
| func,
| )
|
| metadata = MetaData()
|
| orders = Table(
| "orders",
| metadata,
| Column("region", String),
| Column("amount", Integer),
| Column("product", String),
| Column("quantity", Integer),
| )
|
| regional_sales = (
| select(orders.c.region, func.sum(orders.c.amount).label("total_sales"))
| .group_by(orders.c.region)
| .cte("regional_sales")
| )
|
|
| top_regions = (
| select(regional_sales.c.region)
| .where(
| regional_sales.c.total_sales
| > select(func.sum(regional_sales.c.total_sales) / 10)
| )
| .cte("top_regions")
| )
|
| statement = (
| select(
| orders.c.region,
| orders.c.product,
| func.sum(orders.c.quantity).label("product_units"),
| func.sum(orders.c.amount).label("product_sales"),
| )
| .where(orders.c.region.in_(select(top_regions.c.region)))
| .group_by(orders.c.region, orders.c.product)
| )
|
| result = conn.execute(statement).fetchall()
|
| Example 2, WITH RECURSIVE::
|
| from sqlalchemy import (
| Table,
| Column,
| String,
| Integer,
| MetaData,
| select,
| func,
| )
|
| metadata = MetaData()
|
| parts = Table(
| "parts",
| metadata,
| Column("part", String),
| Column("sub_part", String),
| Column("quantity", Integer),
| )
|
| included_parts = (
| select(parts.c.sub_part, parts.c.part, parts.c.quantity)
| .where(parts.c.part == "our part")
| .cte(recursive=True)
| )
|
|
| incl_alias = included_parts.alias()
| parts_alias = parts.alias()
| included_parts = included_parts.union_all(
| select(
| parts_alias.c.sub_part, parts_alias.c.part, parts_alias.c.quantity
| ).where(parts_alias.c.part == incl_alias.c.sub_part)
| )
|
| statement = select(
| included_parts.c.sub_part,
| func.sum(included_parts.c.quantity).label("total_quantity"),
| ).group_by(included_parts.c.sub_part)
|
| result = conn.execute(statement).fetchall()
|
| Example 3, an upsert using UPDATE and INSERT with CTEs::
|
| from datetime import date
| from sqlalchemy import (
| MetaData,
| Table,
| Column,
| Integer,
| Date,
| select,
| literal,
| and_,
| exists,
| )
|
| metadata = MetaData()
|
| visitors = Table(
| "visitors",
| metadata,
| Column("product_id", Integer, primary_key=True),
| Column("date", Date, primary_key=True),
| Column("count", Integer),
| )
|
| # add 5 visitors for the product_id == 1
| product_id = 1
| day = date.today()
| count = 5
|
| update_cte = (
| visitors.update()
| .where(
| and_(visitors.c.product_id == product_id, visitors.c.date == day)
| )
| .values(count=visitors.c.count + count)
| .returning(literal(1))
| .cte("update_cte")
| )
|
| upsert = visitors.insert().from_select(
| [visitors.c.product_id, visitors.c.date, visitors.c.count],
| select(literal(product_id), literal(day), literal(count)).where(
| ~exists(update_cte.select())
| ),
| )
|
| connection.execute(upsert)
|
| Example 4, Nesting CTE (SQLAlchemy 1.4.24 and above)::
|
| value_a = select(literal("root").label("n")).cte("value_a")
|
| # A nested CTE with the same name as the root one
| value_a_nested = select(literal("nesting").label("n")).cte(
| "value_a", nesting=True
| )
|
| # Nesting CTEs takes ascendency locally
| # over the CTEs at a higher level
| value_b = select(value_a_nested.c.n).cte("value_b")
|
| value_ab = select(value_a.c.n.label("a"), value_b.c.n.label("b"))
|
| The above query will render the second CTE nested inside the first,
| shown with inline parameters below as:
|
| .. sourcecode:: sql
|
| WITH
| value_a AS
| (SELECT 'root' AS n),
| value_b AS
| (WITH value_a AS
| (SELECT 'nesting' AS n)
| SELECT value_a.n AS n FROM value_a)
| SELECT value_a.n AS a, value_b.n AS b
| FROM value_a, value_b
|
| The same CTE can be set up using the :meth:`.HasCTE.add_cte` method
| as follows (SQLAlchemy 2.0 and above)::
|
| value_a = select(literal("root").label("n")).cte("value_a")
|
| # A nested CTE with the same name as the root one
| value_a_nested = select(literal("nesting").label("n")).cte("value_a")
|
| # Nesting CTEs takes ascendency locally
| # over the CTEs at a higher level
| value_b = (
| select(value_a_nested.c.n)
| .add_cte(value_a_nested, nest_here=True)
| .cte("value_b")
| )
|
| value_ab = select(value_a.c.n.label("a"), value_b.c.n.label("b"))
|
| Example 5, Non-Linear CTE (SQLAlchemy 1.4.28 and above)::
|
| edge = Table(
| "edge",
| metadata,
| Column("id", Integer, primary_key=True),
| Column("left", Integer),
| Column("right", Integer),
| )
|
| root_node = select(literal(1).label("node")).cte("nodes", recursive=True)
|
| left_edge = select(edge.c.left).join(
| root_node, edge.c.right == root_node.c.node
| )
| right_edge = select(edge.c.right).join(
| root_node, edge.c.left == root_node.c.node
| )
|
| subgraph_cte = root_node.union(left_edge, right_edge)
|
| subgraph = select(subgraph_cte)
|
| The above query will render 2 UNIONs inside the recursive CTE:
|
| .. sourcecode:: sql
|
| WITH RECURSIVE nodes(node) AS (
| SELECT 1 AS node
| UNION
| SELECT edge."left" AS "left"
| FROM edge JOIN nodes ON edge."right" = nodes.node
| UNION
| SELECT edge."right" AS "right"
| FROM edge JOIN nodes ON edge."left" = nodes.node
| )
| SELECT nodes.node FROM nodes
|
| .. seealso::
|
| :meth:`_orm.Query.cte` - ORM version of
| :meth:`_expression.HasCTE.cte`.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from HasCTE:
|
| name_cte_columns = False
|
| ----------------------------------------------------------------------
| Methods inherited from Selectable:
|
| 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.
|
| 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`.
|
| .. deprecated:: 1.4 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.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from Selectable:
|
| __visit_name__ = 'selectable'
|
| is_selectable = True
|
| ----------------------------------------------------------------------
| Methods inherited from ReturnsRows:
|
| 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.
|
| ----------------------------------------------------------------------
| Readonly properties inherited from ReturnsRows:
|
| selectable
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.SQLRole:
|
| uses_inspection = False
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.elements.ClauseElement:
|
| __bool__(self)
|
| __getstate__(self)
| Helper for pickle.
|
| __invert__(self)
|
| __repr__(self)
| Return repr(self).
|
| compare(self, other: 'ClauseElement', **kw: 'Any') -> 'bool'
| Compare this :class:`_expression.ClauseElement` to
| the given :class:`_expression.ClauseElement`.
|
| Subclasses should override the default behavior, which is a
| straight identity comparison.
|
| \**kw are arguments consumed by subclass ``compare()`` methods and
| may be used to modify the criteria for comparison
| (see :class:`_expression.ColumnElement`).
|
| description(...)
|
| entity_namespace(...)
|
| params(self, _ClauseElement__optionaldict: 'Optional[Mapping[str, Any]]' = None, **kwargs: 'Any') -> 'Self'
| Return a copy with :func:`_expression.bindparam` elements
| replaced.
|
| Returns a copy of this ClauseElement with
| :func:`_expression.bindparam`
| elements replaced with values taken from the given dictionary::
|
| >>> clause = column("x") + bindparam("foo")
| >>> print(clause.compile().params)
| {'foo':None}
| >>> print(clause.params({"foo": 7}).compile().params)
| {'foo':7}
|
| self_group(self, against: 'Optional[OperatorType]' = None) -> 'ClauseElement'
| 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.
|
| unique_params(self, _ClauseElement__optionaldict: 'Optional[Dict[str, Any]]' = None, **kwargs: 'Any') -> 'Self'
| Return a copy with :func:`_expression.bindparam` elements
| replaced.
|
| Same functionality as :meth:`_expression.ClauseElement.params`,
| except adds `unique=True`
| to affected bind parameters so that multiple statements can be
| used.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.elements.ClauseElement:
|
| is_clause_element = True
|
| is_dml = False
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.cache_key.HasCacheKey:
|
| inherit_cache = None
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_instancemethod(fn: '_F') -> '_F'
| Decorate a method memoize its return value.
|
| :meta private:
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_attribute = <class 'sqlalchemy.util.langhelpers.HasMemoized.m...
| A read-only @property that is only evaluated once.
|
| :meta private:
|
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.visitors.HasTraverseInternals:
|
| get_children(self, *, omit_attrs: 'Tuple[str, ...]' = (), **kw: 'Any') -> 'Iterable[HasTraverseInternals]'
| Return immediate child :class:`.visitors.HasTraverseInternals`
| elements of this :class:`.visitors.HasTraverseInternals`.
|
| This is used for visit traversal.
|
| \**kw may contain flags that change the collection that is
| returned, for example to return a subset of items in order to
| cut down on larger traversals, or to return child items from a
| different context (such as schema-level collections instead of
| clause-level).
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.elements.CompilerElement:
|
| __str__(self) -> 'str'
| Return str(self).
|
| compile(self, bind: 'Optional[_HasDialect]' = None, dialect: 'Optional[Dialect]' = None, **kw: 'Any') -> 'Compiled'
| Compile this SQL expression.
|
| The return value is a :class:`~.Compiled` object.
| Calling ``str()`` or ``unicode()`` on the returned value will yield a
| string representation of the result. The
| :class:`~.Compiled` object also can return a
| dictionary of bind parameter names and values
| using the ``params`` accessor.
|
| :param bind: An :class:`.Connection` or :class:`.Engine` which
| can provide a :class:`.Dialect` in order to generate a
| :class:`.Compiled` object. If the ``bind`` and
| ``dialect`` parameters are both omitted, a default SQL compiler
| is used.
|
| :param column_keys: Used for INSERT and UPDATE statements, a list of
| column names which should be present in the VALUES clause of the
| compiled statement. If ``None``, all columns from the target table
| object are rendered.
|
| :param dialect: A :class:`.Dialect` instance which can generate
| a :class:`.Compiled` object. This argument takes precedence over
| the ``bind`` argument.
|
| :param compile_kwargs: optional dictionary of additional parameters
| that will be passed through to the compiler within all "visit"
| methods. This allows any custom flag to be passed through to
| a custom compilation construct, for example. It is also used
| for the case of passing the ``literal_binds`` flag through::
|
| from sqlalchemy.sql import table, column, select
|
| t = table("t", column("x"))
|
| s = select(t).where(t.c.x == 5)
|
| print(s.compile(compile_kwargs={"literal_binds": True}))
|
| .. seealso::
|
| :ref:`faq_sql_expression_string`
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.elements.CompilerElement:
|
| stringify_dialect = 'default'
|
| supports_execution = False
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.visitors.Visitable:
|
| __class_getitem__(key: 'Any') -> 'Any'
|
| __init_subclass__() -> 'None'
| This method is called when a class is subclassed.
|
| The default implementation does nothing. It may be
| overridden to extend subclasses.
sqlalchemy.SelectLabelStyle
Python Library Documentation: class SelectLabelStyle in module sqlalchemy.sql.selectable class SelectLabelStyle(enum.Enum) | SelectLabelStyle(*values) | | Label style constants that may be passed to | :meth:`_sql.Select.set_label_style`. | | Method resolution order: | SelectLabelStyle | enum.Enum | builtins.object | | Data and other attributes defined here: | | LABEL_STYLE_DISAMBIGUATE_ONLY = <SelectLabelStyle.LABEL_STYLE_DISAMBIG... | | LABEL_STYLE_LEGACY_ORM = <SelectLabelStyle.LABEL_STYLE_LEGACY_ORM: 3> | | LABEL_STYLE_NONE = <SelectLabelStyle.LABEL_STYLE_NONE: 0> | | LABEL_STYLE_TABLENAME_PLUS_COL = <SelectLabelStyle.LABEL_STYLE_TABLENA... | | ---------------------------------------------------------------------- | Data descriptors inherited from enum.Enum: | | name | The name of the Enum member. | | value | The value of the Enum member. | | ---------------------------------------------------------------------- | Static methods inherited from enum.EnumType: | | __contains__(value) | Return True if `value` is in `cls`. | | `value` is in `cls` if: | 1) `value` is a member of `cls`, or | 2) `value` is the value of one of the `cls`'s members. | | __getitem__(name) | Return the member matching `name`. | | __iter__() | Return members in definition order. | | __len__() | Return the number of members (no aliases) | | ---------------------------------------------------------------------- | Readonly properties inherited from enum.EnumType: | | __members__ | Returns a mapping of member name->value. | | This mapping lists all enum members, including aliases. Note that this | is a read-only view of the internal mapping.
sqlalchemy.Selectable
Python Library Documentation: class Selectable in module sqlalchemy.sql.selectable
class Selectable(ReturnsRows)
| Mark a class as being selectable.
|
| Method resolution order:
| Selectable
| ReturnsRows
| sqlalchemy.sql.roles.ReturnsRowsRole
| sqlalchemy.sql.roles.SQLRole
| sqlalchemy.sql.elements.DQLDMLClauseElement
| sqlalchemy.sql.elements.ClauseElement
| sqlalchemy.sql.annotation.SupportsWrappingAnnotations
| sqlalchemy.sql.annotation.SupportsAnnotations
| sqlalchemy.sql.cache_key.MemoizedHasCacheKey
| sqlalchemy.sql.cache_key.HasCacheKey
| sqlalchemy.util.langhelpers.HasMemoized
| sqlalchemy.sql.traversals.HasCopyInternals
| sqlalchemy.sql.visitors.ExternallyTraversible
| sqlalchemy.sql.visitors.HasTraverseInternals
| sqlalchemy.sql.elements.CompilerElement
| sqlalchemy.sql.visitors.Visitable
| builtins.object
|
| Methods defined here:
|
| 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.
|
| 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.
|
| 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`.
|
| .. deprecated:: 1.4 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.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| __visit_name__ = 'selectable'
|
| is_selectable = True
|
| ----------------------------------------------------------------------
| Methods inherited from ReturnsRows:
|
| 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.
|
| ----------------------------------------------------------------------
| Readonly properties inherited from ReturnsRows:
|
| exported_columns
| 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`
|
| selectable
|
| ----------------------------------------------------------------------
| Data descriptors inherited from ReturnsRows:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.SQLRole:
|
| allows_lambda = False
|
| uses_inspection = False
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.elements.ClauseElement:
|
| __bool__(self)
|
| __getstate__(self)
| Helper for pickle.
|
| __invert__(self)
|
| __repr__(self)
| Return repr(self).
|
| compare(self, other: 'ClauseElement', **kw: 'Any') -> 'bool'
| Compare this :class:`_expression.ClauseElement` to
| the given :class:`_expression.ClauseElement`.
|
| Subclasses should override the default behavior, which is a
| straight identity comparison.
|
| \**kw are arguments consumed by subclass ``compare()`` methods and
| may be used to modify the criteria for comparison
| (see :class:`_expression.ColumnElement`).
|
| description(...)
|
| entity_namespace(...)
|
| params(self, _ClauseElement__optionaldict: 'Optional[Mapping[str, Any]]' = None, **kwargs: 'Any') -> 'Self'
| Return a copy with :func:`_expression.bindparam` elements
| replaced.
|
| Returns a copy of this ClauseElement with
| :func:`_expression.bindparam`
| elements replaced with values taken from the given dictionary::
|
| >>> clause = column("x") + bindparam("foo")
| >>> print(clause.compile().params)
| {'foo':None}
| >>> print(clause.params({"foo": 7}).compile().params)
| {'foo':7}
|
| self_group(self, against: 'Optional[OperatorType]' = None) -> 'ClauseElement'
| 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.
|
| unique_params(self, _ClauseElement__optionaldict: 'Optional[Dict[str, Any]]' = None, **kwargs: 'Any') -> 'Self'
| Return a copy with :func:`_expression.bindparam` elements
| replaced.
|
| Same functionality as :meth:`_expression.ClauseElement.params`,
| except adds `unique=True`
| to affected bind parameters so that multiple statements can be
| used.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.elements.ClauseElement:
|
| is_clause_element = True
|
| is_dml = False
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.cache_key.HasCacheKey:
|
| inherit_cache = None
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_instancemethod(fn: '_F') -> '_F'
| Decorate a method memoize its return value.
|
| :meta private:
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_attribute = <class 'sqlalchemy.util.langhelpers.HasMemoized.m...
| A read-only @property that is only evaluated once.
|
| :meta private:
|
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.visitors.HasTraverseInternals:
|
| get_children(self, *, omit_attrs: 'Tuple[str, ...]' = (), **kw: 'Any') -> 'Iterable[HasTraverseInternals]'
| Return immediate child :class:`.visitors.HasTraverseInternals`
| elements of this :class:`.visitors.HasTraverseInternals`.
|
| This is used for visit traversal.
|
| \**kw may contain flags that change the collection that is
| returned, for example to return a subset of items in order to
| cut down on larger traversals, or to return child items from a
| different context (such as schema-level collections instead of
| clause-level).
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.elements.CompilerElement:
|
| __str__(self) -> 'str'
| Return str(self).
|
| compile(self, bind: 'Optional[_HasDialect]' = None, dialect: 'Optional[Dialect]' = None, **kw: 'Any') -> 'Compiled'
| Compile this SQL expression.
|
| The return value is a :class:`~.Compiled` object.
| Calling ``str()`` or ``unicode()`` on the returned value will yield a
| string representation of the result. The
| :class:`~.Compiled` object also can return a
| dictionary of bind parameter names and values
| using the ``params`` accessor.
|
| :param bind: An :class:`.Connection` or :class:`.Engine` which
| can provide a :class:`.Dialect` in order to generate a
| :class:`.Compiled` object. If the ``bind`` and
| ``dialect`` parameters are both omitted, a default SQL compiler
| is used.
|
| :param column_keys: Used for INSERT and UPDATE statements, a list of
| column names which should be present in the VALUES clause of the
| compiled statement. If ``None``, all columns from the target table
| object are rendered.
|
| :param dialect: A :class:`.Dialect` instance which can generate
| a :class:`.Compiled` object. This argument takes precedence over
| the ``bind`` argument.
|
| :param compile_kwargs: optional dictionary of additional parameters
| that will be passed through to the compiler within all "visit"
| methods. This allows any custom flag to be passed through to
| a custom compilation construct, for example. It is also used
| for the case of passing the ``literal_binds`` flag through::
|
| from sqlalchemy.sql import table, column, select
|
| t = table("t", column("x"))
|
| s = select(t).where(t.c.x == 5)
|
| print(s.compile(compile_kwargs={"literal_binds": True}))
|
| .. seealso::
|
| :ref:`faq_sql_expression_string`
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.elements.CompilerElement:
|
| stringify_dialect = 'default'
|
| supports_execution = False
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.visitors.Visitable:
|
| __class_getitem__(key: 'Any') -> 'Any'
|
| __init_subclass__() -> 'None'
| This method is called when a class is subclassed.
|
| The default implementation does nothing. It may be
| overridden to extend subclasses.
sqlalchemy.Sequence
Python Library Documentation: class Sequence in module sqlalchemy.sql.schema
class Sequence(HasSchemaAttr, IdentityOptions, DefaultGenerator)
| Sequence(name: 'str', start: 'Optional[int]' = None, increment: 'Optional[int]' = None, minvalue: 'Optional[int]' = None, maxvalue: 'Optional[int]' = None, nominvalue: 'Optional[bool]' = None, nomaxvalue: 'Optional[bool]' = None, cycle: 'Optional[bool]' = None, schema: 'Optional[Union[str, Literal[SchemaConst.BLANK_SCHEMA]]]' = None, cache: 'Optional[int]' = None, order: 'Optional[bool]' = None, data_type: 'Optional[_TypeEngineArgument[int]]' = None, optional: 'bool' = False, quote: 'Optional[bool]' = None, metadata: 'Optional[MetaData]' = None, quote_schema: 'Optional[bool]' = None, for_update: 'bool' = False) -> 'None'
|
| Represents a named database sequence.
|
| The :class:`.Sequence` object represents the name and configurational
| parameters of a database sequence. It also represents
| a construct that can be "executed" by a SQLAlchemy :class:`_engine.Engine`
| or :class:`_engine.Connection`,
| rendering the appropriate "next value" function
| for the target database and returning a result.
|
| The :class:`.Sequence` is typically associated with a primary key column::
|
| some_table = Table(
| "some_table",
| metadata,
| Column(
| "id",
| Integer,
| Sequence("some_table_seq", start=1),
| primary_key=True,
| ),
| )
|
| When CREATE TABLE is emitted for the above :class:`_schema.Table`, if the
| target platform supports sequences, a CREATE SEQUENCE statement will
| be emitted as well. For platforms that don't support sequences,
| the :class:`.Sequence` construct is ignored.
|
| .. seealso::
|
| :ref:`defaults_sequences`
|
| :class:`.CreateSequence`
|
| :class:`.DropSequence`
|
| Method resolution order:
| Sequence
| HasSchemaAttr
| IdentityOptions
| DefaultGenerator
| sqlalchemy.sql.base.Executable
| sqlalchemy.sql.roles.StatementRole
| sqlalchemy.sql.roles.SQLRole
| SchemaItem
| sqlalchemy.sql.base.SchemaVisitable
| sqlalchemy.sql.base.SchemaEventTarget
| sqlalchemy.event.registry.EventTarget
| sqlalchemy.sql.visitors.Visitable
| builtins.object
|
| Methods defined here:
|
| __init__(self, name: 'str', start: 'Optional[int]' = None, increment: 'Optional[int]' = None, minvalue: 'Optional[int]' = None, maxvalue: 'Optional[int]' = None, nominvalue: 'Optional[bool]' = None, nomaxvalue: 'Optional[bool]' = None, cycle: 'Optional[bool]' = None, schema: 'Optional[Union[str, Literal[SchemaConst.BLANK_SCHEMA]]]' = None, cache: 'Optional[int]' = None, order: 'Optional[bool]' = None, data_type: 'Optional[_TypeEngineArgument[int]]' = None, optional: 'bool' = False, quote: 'Optional[bool]' = None, metadata: 'Optional[MetaData]' = None, quote_schema: 'Optional[bool]' = None, for_update: 'bool' = False) -> 'None'
| Construct a :class:`.Sequence` object.
|
| :param name: the name of the sequence.
|
| :param start: the starting index of the sequence. This value is
| used when the CREATE SEQUENCE command is emitted to the database
| as the value of the "START WITH" clause. If ``None``, the
| clause is omitted, which on most platforms indicates a starting
| value of 1.
|
| .. versionchanged:: 2.0 The :paramref:`.Sequence.start` parameter
| is required in order to have DDL emit "START WITH". This is a
| reversal of a change made in version 1.4 which would implicitly
| render "START WITH 1" if the :paramref:`.Sequence.start` were
| not included. See :ref:`change_7211` for more detail.
|
| :param increment: the increment value of the sequence. This
| value is used when the CREATE SEQUENCE command is emitted to
| the database as the value of the "INCREMENT BY" clause. If ``None``,
| the clause is omitted, which on most platforms indicates an
| increment of 1.
| :param minvalue: the minimum value of the sequence. This
| value is used when the CREATE SEQUENCE command is emitted to
| the database as the value of the "MINVALUE" clause. If ``None``,
| the clause is omitted, which on most platforms indicates a
| minvalue of 1 and -2^63-1 for ascending and descending sequences,
| respectively.
|
| :param maxvalue: the maximum value of the sequence. This
| value is used when the CREATE SEQUENCE command is emitted to
| the database as the value of the "MAXVALUE" clause. If ``None``,
| the clause is omitted, which on most platforms indicates a
| maxvalue of 2^63-1 and -1 for ascending and descending sequences,
| respectively.
|
| :param nominvalue: no minimum value of the sequence. This
| value is used when the CREATE SEQUENCE command is emitted to
| the database as the value of the "NO MINVALUE" clause. If ``None``,
| the clause is omitted, which on most platforms indicates a
| minvalue of 1 and -2^63-1 for ascending and descending sequences,
| respectively.
|
| :param nomaxvalue: no maximum value of the sequence. This
| value is used when the CREATE SEQUENCE command is emitted to
| the database as the value of the "NO MAXVALUE" clause. If ``None``,
| the clause is omitted, which on most platforms indicates a
| maxvalue of 2^63-1 and -1 for ascending and descending sequences,
| respectively.
|
| :param cycle: allows the sequence to wrap around when the maxvalue
| or minvalue has been reached by an ascending or descending sequence
| respectively. This value is used when the CREATE SEQUENCE command
| is emitted to the database as the "CYCLE" clause. If the limit is
| reached, the next number generated will be the minvalue or maxvalue,
| respectively. If cycle=False (the default) any calls to nextval
| after the sequence has reached its maximum value will return an
| error.
|
| :param schema: optional schema name for the sequence, if located
| in a schema other than the default. The rules for selecting the
| schema name when a :class:`_schema.MetaData`
| is also present are the same
| as that of :paramref:`_schema.Table.schema`.
|
| :param cache: optional integer value; number of future values in the
| sequence which are calculated in advance. Renders the CACHE keyword
| understood by Oracle Database and PostgreSQL.
|
| :param order: optional boolean value; if ``True``, renders the
| ORDER keyword, understood by Oracle Database, indicating the sequence
| is definitively ordered. May be necessary to provide deterministic
| ordering using Oracle RAC.
|
| :param data_type: The type to be returned by the sequence, for
| dialects that allow us to choose between INTEGER, BIGINT, etc.
| (e.g., mssql).
|
| .. versionadded:: 1.4.0
|
| :param optional: boolean value, when ``True``, indicates that this
| :class:`.Sequence` object only needs to be explicitly generated
| on backends that don't provide another way to generate primary
| key identifiers. Currently, it essentially means, "don't create
| this sequence on the PostgreSQL backend, where the SERIAL keyword
| creates a sequence for us automatically".
| :param quote: boolean value, when ``True`` or ``False``, explicitly
| forces quoting of the :paramref:`_schema.Sequence.name` on or off.
| When left at its default of ``None``, normal quoting rules based
| on casing and reserved words take place.
| :param quote_schema: Set the quoting preferences for the ``schema``
| name.
|
| :param metadata: optional :class:`_schema.MetaData` object which this
| :class:`.Sequence` will be associated with. A :class:`.Sequence`
| that is associated with a :class:`_schema.MetaData`
| gains the following
| capabilities:
|
| * The :class:`.Sequence` will inherit the
| :paramref:`_schema.MetaData.schema`
| parameter specified to the target :class:`_schema.MetaData`, which
| affects the production of CREATE / DROP DDL, if any.
|
| * The :meth:`.Sequence.create` and :meth:`.Sequence.drop` methods
| automatically use the engine bound to the :class:`_schema.MetaData`
| object, if any.
|
| * The :meth:`_schema.MetaData.create_all` and
| :meth:`_schema.MetaData.drop_all`
| methods will emit CREATE / DROP for this :class:`.Sequence`,
| even if the :class:`.Sequence` is not associated with any
| :class:`_schema.Table` / :class:`_schema.Column`
| that's a member of this
| :class:`_schema.MetaData`.
|
| The above behaviors can only occur if the :class:`.Sequence` is
| explicitly associated with the :class:`_schema.MetaData`
| via this parameter.
|
| .. seealso::
|
| :ref:`sequence_metadata` - full discussion of the
| :paramref:`.Sequence.metadata` parameter.
|
| :param for_update: Indicates this :class:`.Sequence`, when associated
| with a :class:`_schema.Column`,
| should be invoked for UPDATE statements
| on that column's table, rather than for INSERT statements, when
| no value is otherwise present for that column in the statement.
|
| create(self, bind: '_CreateDropBind', checkfirst: 'bool' = True) -> 'None'
| Creates this sequence in the database.
|
| drop(self, bind: '_CreateDropBind', checkfirst: 'bool' = True) -> 'None'
| Drops this sequence from the database.
|
| next_value(self) -> 'Function[int]'
| Return a :class:`.next_value` function element
| which will render the appropriate increment function
| for this :class:`.Sequence` within any SQL expression.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'column': 'Optional[Column[Any]]', 'data_type': 'Op...
|
| __visit_name__ = 'sequence'
|
| is_sequence = True
|
| ----------------------------------------------------------------------
| Data descriptors inherited from IdentityOptions:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from DefaultGenerator:
|
| has_arg = False
|
| is_callable = False
|
| is_clause_element = False
|
| is_identity = False
|
| is_scalar = False
|
| is_sentinel = False
|
| is_server_default = False
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.base.Executable:
|
| execution_options(self, **kw: 'Any') -> 'Self'
| Set non-SQL options for the statement which take effect during
| execution.
|
| Execution options can be set at many scopes, including per-statement,
| per-connection, or per execution, using methods such as
| :meth:`_engine.Connection.execution_options` and parameters which
| accept a dictionary of options such as
| :paramref:`_engine.Connection.execute.execution_options` and
| :paramref:`_orm.Session.execute.execution_options`.
|
| The primary characteristic of an execution option, as opposed to
| other kinds of options such as ORM loader options, is that
| **execution options never affect the compiled SQL of a query, only
| things that affect how the SQL statement itself is invoked or how
| results are fetched**. That is, execution options are not part of
| what's accommodated by SQL compilation nor are they considered part of
| the cached state of a statement.
|
| The :meth:`_sql.Executable.execution_options` method is
| :term:`generative`, as
| is the case for the method as applied to the :class:`_engine.Engine`
| and :class:`_orm.Query` objects, which means when the method is called,
| a copy of the object is returned, which applies the given parameters to
| that new copy, but leaves the original unchanged::
|
| statement = select(table.c.x, table.c.y)
| new_statement = statement.execution_options(my_option=True)
|
| An exception to this behavior is the :class:`_engine.Connection`
| object, where the :meth:`_engine.Connection.execution_options` method
| is explicitly **not** generative.
|
| The kinds of options that may be passed to
| :meth:`_sql.Executable.execution_options` and other related methods and
| parameter dictionaries include parameters that are explicitly consumed
| by SQLAlchemy Core or ORM, as well as arbitrary keyword arguments not
| defined by SQLAlchemy, which means the methods and/or parameter
| dictionaries may be used for user-defined parameters that interact with
| custom code, which may access the parameters using methods such as
| :meth:`_sql.Executable.get_execution_options` and
| :meth:`_engine.Connection.get_execution_options`, or within selected
| event hooks using a dedicated ``execution_options`` event parameter
| such as
| :paramref:`_events.ConnectionEvents.before_execute.execution_options`
| or :attr:`_orm.ORMExecuteState.execution_options`, e.g.::
|
| from sqlalchemy import event
|
|
| @event.listens_for(some_engine, "before_execute")
| def _process_opt(conn, statement, multiparams, params, execution_options):
| "run a SQL function before invoking a statement"
|
| if execution_options.get("do_special_thing", False):
| conn.exec_driver_sql("run_special_function()")
|
| Within the scope of options that are explicitly recognized by
| SQLAlchemy, most apply to specific classes of objects and not others.
| The most common execution options include:
|
| * :paramref:`_engine.Connection.execution_options.isolation_level` -
| sets the isolation level for a connection or a class of connections
| via an :class:`_engine.Engine`. This option is accepted only
| by :class:`_engine.Connection` or :class:`_engine.Engine`.
|
| * :paramref:`_engine.Connection.execution_options.stream_results` -
| indicates results should be fetched using a server side cursor;
| this option is accepted by :class:`_engine.Connection`, by the
| :paramref:`_engine.Connection.execute.execution_options` parameter
| on :meth:`_engine.Connection.execute`, and additionally by
| :meth:`_sql.Executable.execution_options` on a SQL statement object,
| as well as by ORM constructs like :meth:`_orm.Session.execute`.
|
| * :paramref:`_engine.Connection.execution_options.compiled_cache` -
| indicates a dictionary that will serve as the
| :ref:`SQL compilation cache <sql_caching>`
| for a :class:`_engine.Connection` or :class:`_engine.Engine`, as
| well as for ORM methods like :meth:`_orm.Session.execute`.
| Can be passed as ``None`` to disable caching for statements.
| This option is not accepted by
| :meth:`_sql.Executable.execution_options` as it is inadvisable to
| carry along a compilation cache within a statement object.
|
| * :paramref:`_engine.Connection.execution_options.schema_translate_map`
| - a mapping of schema names used by the
| :ref:`Schema Translate Map <schema_translating>` feature, accepted
| by :class:`_engine.Connection`, :class:`_engine.Engine`,
| :class:`_sql.Executable`, as well as by ORM constructs
| like :meth:`_orm.Session.execute`.
|
| .. seealso::
|
| :meth:`_engine.Connection.execution_options`
|
| :paramref:`_engine.Connection.execute.execution_options`
|
| :paramref:`_orm.Session.execute.execution_options`
|
| :ref:`orm_queryguide_execution_options` - documentation on all
| ORM-specific execution options
|
| get_execution_options(self) -> '_ExecuteOptions'
| Get the non-SQL options which will take effect during execution.
|
| .. versionadded:: 1.3
|
| .. seealso::
|
| :meth:`.Executable.execution_options`
|
| options(self, *options: 'ExecutableOption') -> 'Self'
| Apply options to this statement.
|
| In the general sense, options are any kind of Python object
| that can be interpreted by the SQL compiler for the statement.
| These options can be consumed by specific dialects or specific kinds
| of compilers.
|
| The most commonly known kind of option are the ORM level options
| that apply "eager load" and other loading behaviors to an ORM
| query. However, options can theoretically be used for many other
| purposes.
|
| For background on specific kinds of options for specific kinds of
| statements, refer to the documentation for those option objects.
|
| .. versionchanged:: 1.4 - added :meth:`.Executable.options` to
| Core statement objects towards the goal of allowing unified
| Core / ORM querying capabilities.
|
| .. seealso::
|
| :ref:`loading_columns` - refers to options specific to the usage
| of ORM queries
|
| :ref:`relationship_loader_options` - refers to options specific
| to the usage of ORM queries
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.base.Executable:
|
| is_delete = False
|
| is_dml = False
|
| is_from_statement = False
|
| is_insert = False
|
| is_select = False
|
| is_text = False
|
| is_update = False
|
| supports_execution = True
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.SQLRole:
|
| allows_lambda = False
|
| uses_inspection = False
|
| ----------------------------------------------------------------------
| Methods inherited from SchemaItem:
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| info(...)
| Info dictionary associated with the object, allowing user-defined
| data to be associated with this :class:`.SchemaItem`.
|
| The dictionary is automatically generated when first accessed.
| It can also be specified in the constructor of some objects,
| such as :class:`_schema.Table` and :class:`_schema.Column`.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from SchemaItem:
|
| create_drop_stringify_dialect = 'default'
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.base.SchemaEventTarget:
|
| dispatch = <sqlalchemy.event.base.DDLEventsDispatch object>
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.visitors.Visitable:
|
| __class_getitem__(key: 'Any') -> 'Any'
|
| __init_subclass__() -> 'None'
| This method is called when a class is subclassed.
|
| The default implementation does nothing. It may be
| overridden to extend subclasses.
sqlalchemy.SingletonThreadPool
Python Library Documentation: class SingletonThreadPool in module sqlalchemy.pool.impl
class SingletonThreadPool(sqlalchemy.pool.base.Pool)
| SingletonThreadPool(creator: 'Union[_CreatorFnType, _CreatorWRecFnType]', pool_size: 'int' = 5, **kw: 'Any')
|
| A Pool that maintains one connection per thread.
|
| Maintains one connection per each thread, never moving a connection to a
| thread other than the one which it was created in.
|
| .. warning:: the :class:`.SingletonThreadPool` will call ``.close()``
| on arbitrary connections that exist beyond the size setting of
| ``pool_size``, e.g. if more unique **thread identities**
| than what ``pool_size`` states are used. This cleanup is
| non-deterministic and not sensitive to whether or not the connections
| linked to those thread identities are currently in use.
|
| :class:`.SingletonThreadPool` may be improved in a future release,
| however in its current status it is generally used only for test
| scenarios using a SQLite ``:memory:`` database and is not recommended
| for production use.
|
| The :class:`.SingletonThreadPool` class **is not compatible** with asyncio
| and :func:`_asyncio.create_async_engine`.
|
|
| Options are the same as those of :class:`_pool.Pool`, as well as:
|
| :param pool_size: The number of threads in which to maintain connections
| at once. Defaults to five.
|
| :class:`.SingletonThreadPool` is used by the SQLite dialect
| automatically when a memory-based database is used.
| See :ref:`sqlite_toplevel`.
|
| Method resolution order:
| SingletonThreadPool
| sqlalchemy.pool.base.Pool
| sqlalchemy.log.Identified
| sqlalchemy.event.registry.EventTarget
| builtins.object
|
| Methods defined here:
|
| __init__(self, creator: 'Union[_CreatorFnType, _CreatorWRecFnType]', pool_size: 'int' = 5, **kw: 'Any')
| Construct a Pool.
|
| :param creator: a callable function that returns a DB-API
| connection object. The function will be called with
| parameters.
|
| :param recycle: If set to a value other than -1, number of
| seconds between connection recycling, which means upon
| checkout, if this timeout is surpassed the connection will be
| closed and replaced with a newly opened connection. Defaults to -1.
|
| :param logging_name: String identifier which will be used within
| the "name" field of logging records generated within the
| "sqlalchemy.pool" logger. Defaults to a hexstring of the object's
| id.
|
| :param echo: if True, the connection pool will log
| informational output such as when connections are invalidated
| as well as when connections are recycled to the default log handler,
| which defaults to ``sys.stdout`` for output.. If set to the string
| ``"debug"``, the logging will include pool checkouts and checkins.
|
| The :paramref:`_pool.Pool.echo` parameter can also be set from the
| :func:`_sa.create_engine` call by using the
| :paramref:`_sa.create_engine.echo_pool` parameter.
|
| .. seealso::
|
| :ref:`dbengine_logging` - further detail on how to configure
| logging.
|
| :param reset_on_return: Determine steps to take on
| connections as they are returned to the pool, which were
| not otherwise handled by a :class:`_engine.Connection`.
| Available from :func:`_sa.create_engine` via the
| :paramref:`_sa.create_engine.pool_reset_on_return` parameter.
|
| :paramref:`_pool.Pool.reset_on_return` can have any of these values:
|
| * ``"rollback"`` - call rollback() on the connection,
| to release locks and transaction resources.
| This is the default value. The vast majority
| of use cases should leave this value set.
| * ``"commit"`` - call commit() on the connection,
| to release locks and transaction resources.
| A commit here may be desirable for databases that
| cache query plans if a commit is emitted,
| such as Microsoft SQL Server. However, this
| value is more dangerous than 'rollback' because
| any data changes present on the transaction
| are committed unconditionally.
| * ``None`` - don't do anything on the connection.
| This setting may be appropriate if the database / DBAPI
| works in pure "autocommit" mode at all times, or if
| a custom reset handler is established using the
| :meth:`.PoolEvents.reset` event handler.
|
| * ``True`` - same as 'rollback', this is here for
| backwards compatibility.
| * ``False`` - same as None, this is here for
| backwards compatibility.
|
| For further customization of reset on return, the
| :meth:`.PoolEvents.reset` event hook may be used which can perform
| any connection activity desired on reset.
|
| .. seealso::
|
| :ref:`pool_reset_on_return`
|
| :meth:`.PoolEvents.reset`
|
| :param events: a list of 2-tuples, each of the form
| ``(callable, target)`` which will be passed to :func:`.event.listen`
| upon construction. Provided here so that event listeners
| can be assigned via :func:`_sa.create_engine` before dialect-level
| listeners are applied.
|
| :param dialect: a :class:`.Dialect` that will handle the job
| of calling rollback(), close(), or commit() on DBAPI connections.
| If omitted, a built-in "stub" dialect is used. Applications that
| make use of :func:`_sa.create_engine` should not use this parameter
| as it is handled by the engine creation strategy.
|
| :param pre_ping: if True, the pool will emit a "ping" (typically
| "SELECT 1", but is dialect-specific) on the connection
| upon checkout, to test if the connection is alive or not. If not,
| the connection is transparently re-connected and upon success, all
| other pooled connections established prior to that timestamp are
| invalidated. Requires that a dialect is passed as well to
| interpret the disconnection error.
|
| .. versionadded:: 1.2
|
| connect(self) -> 'PoolProxiedConnection'
| Return a DBAPI connection from the pool.
|
| The connection is instrumented such that when its
| ``close()`` method is called, the connection will be returned to
| the pool.
|
| dispose(self) -> 'None'
| Dispose of this pool.
|
| recreate(self) -> 'SingletonThreadPool'
| Return a new :class:`_pool.Pool`, of the same class as this one
| and configured with identical creation arguments.
|
| This method is used in conjunction with :meth:`dispose`
| to close out an entire :class:`_pool.Pool` and create a new one in
| its place.
|
| status(self) -> 'str'
| Returns a brief description of the state of this pool.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| ----------------------------------------------------------------------
| Data descriptors inherited from sqlalchemy.pool.base.Pool:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.pool.base.Pool:
|
| dispatch = <sqlalchemy.event.base.PoolEventsDispatch object>
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.log.Identified:
|
| logging_name = None
sqlalchemy.SmallInteger
Python Library Documentation: class SmallInteger in module sqlalchemy.sql.sqltypes
class SmallInteger(Integer)
| A type for smaller ``int`` integers.
|
| Typically generates a ``SMALLINT`` in DDL, and otherwise acts like
| a normal :class:`.Integer` on the Python side.
|
| Method resolution order:
| SmallInteger
| Integer
| HasExpressionLookup
| sqlalchemy.sql.type_api.TypeEngineMixin
| sqlalchemy.sql.type_api.TypeEngine
| sqlalchemy.sql.visitors.Visitable
| typing.Generic
| builtins.object
|
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| __parameters__ = ()
|
| __visit_name__ = 'small_integer'
|
| ----------------------------------------------------------------------
| Methods inherited from Integer:
|
| get_dbapi_type(self, dbapi)
| Return the corresponding type object from the underlying DB-API, if
| any.
|
| This can be useful for calling ``setinputsizes()``, for example.
|
| literal_processor(self, dialect)
| Return a conversion function for processing literal values that are
| to be rendered directly without using binds.
|
| This function is used when the compiler makes use of the
| "literal_binds" flag, typically used in DDL generation as well
| as in certain scenarios where backends don't accept bound parameters.
|
| Returns a callable which will receive a literal Python value
| as the sole positional argument and will return a string representation
| to be rendered in a SQL statement.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.literal_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.literal_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_literal_param`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| ----------------------------------------------------------------------
| Readonly properties inherited from Integer:
|
| python_type
| Return the Python type object expected to be returned
| by instances of this type, if known.
|
| Basically, for those types which enforce a return type,
| or are known across the board to do such for all common
| DBAPIs (like ``int`` for example), will return that type.
|
| If a return type is not defined, raises
| ``NotImplementedError``.
|
| Note that any type also accommodates NULL in SQL which
| means you can also get back ``None`` from any type
| in practice.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from HasExpressionLookup:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from HasExpressionLookup:
|
| Comparator = <class 'sqlalchemy.sql.sqltypes.HasExpressionLookup.Compa...
|
| comparator_factory = <class 'sqlalchemy.sql.sqltypes.HasExpressionLook...
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.type_api.TypeEngine:
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| __str__(self) -> 'str'
| Return str(self).
|
| adapt(self, cls: 'Type[Union[TypeEngine[Any], TypeEngineMixin]]', **kw: 'Any') -> 'TypeEngine[Any]'
| Produce an "adapted" form of this type, given an "impl" class
| to work with.
|
| This method is used internally to associate generic
| types with "implementation" types that are specific to a particular
| dialect.
|
| as_generic(self, allow_nulltype: 'bool' = False) -> 'TypeEngine[_T]'
| Return an instance of the generic type corresponding to this type
| using heuristic rule. The method may be overridden if this
| heuristic rule is not sufficient.
|
| >>> from sqlalchemy.dialects.mysql import INTEGER
| >>> INTEGER(display_width=4).as_generic()
| Integer()
|
| >>> from sqlalchemy.dialects.mysql import NVARCHAR
| >>> NVARCHAR(length=100).as_generic()
| Unicode(length=100)
|
| .. versionadded:: 1.4.0b2
|
|
| .. seealso::
|
| :ref:`metadata_reflection_dbagnostic_types` - describes the
| use of :meth:`_types.TypeEngine.as_generic` in conjunction with
| the :meth:`_sql.DDLEvents.column_reflect` event, which is its
| intended use.
|
| bind_expression(self, bindvalue: 'BindParameter[_T]') -> 'Optional[ColumnElement[_T]]'
| Given a bind value (i.e. a :class:`.BindParameter` instance),
| return a SQL expression in its place.
|
| This is typically a SQL function that wraps the existing bound
| parameter within the statement. It is used for special data types
| that require literals being wrapped in some special database function
| in order to coerce an application-level value into a database-specific
| format. It is the SQL analogue of the
| :meth:`.TypeEngine.bind_processor` method.
|
| This method is called during the **SQL compilation** phase of a
| statement, when rendering a SQL string. It is **not** called
| against specific values.
|
| Note that this method, when implemented, should always return
| the exact same structure, without any conditional logic, as it
| may be used in an executemany() call against an arbitrary number
| of bound parameter sets.
|
| .. note::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.bind_expression`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.bind_expression`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.bind_expression`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| .. seealso::
|
| :ref:`types_sql_value_processing`
|
| bind_processor(self, dialect: 'Dialect') -> 'Optional[_BindProcessorType[_T]]'
| Return a conversion function for processing bind values.
|
| Returns a callable which will receive a bind parameter value
| as the sole positional argument and will return a value to
| send to the DB-API.
|
| If processing is not necessary, the method should return ``None``.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.bind_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.bind_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_bind_param`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
|
| :param dialect: Dialect instance in use.
|
| coerce_compared_value(self, op: 'Optional[OperatorType]', value: 'Any') -> 'TypeEngine[Any]'
| Suggest a type for a 'coerced' Python value in an expression.
|
| Given an operator and value, gives the type a chance
| to return a type which the value should be coerced into.
|
| The default behavior here is conservative; if the right-hand
| side is already coerced into a SQL type based on its
| Python type, it is usually left alone.
|
| End-user functionality extension here should generally be via
| :class:`.TypeDecorator`, which provides more liberal behavior in that
| it defaults to coercing the other side of the expression into this
| type, thus applying special Python conversions above and beyond those
| needed by the DBAPI to both ides. It also provides the public method
| :meth:`.TypeDecorator.coerce_compared_value` which is intended for
| end-user customization of this behavior.
|
| column_expression(self, colexpr: 'ColumnElement[_T]') -> 'Optional[ColumnElement[_T]]'
| Given a SELECT column expression, return a wrapping SQL expression.
|
| This is typically a SQL function that wraps a column expression
| as rendered in the columns clause of a SELECT statement.
| It is used for special data types that require
| columns to be wrapped in some special database function in order
| to coerce the value before being sent back to the application.
| It is the SQL analogue of the :meth:`.TypeEngine.result_processor`
| method.
|
| .. note:: The :func:`.TypeEngine.column_expression` method is applied
| only to the **outermost columns clause** of a SELECT statement, that
| is, the columns that are to be delivered directly into the returned
| result rows. It does **not** apply to the columns clause inside
| of subqueries. This necessarily avoids double conversions against
| the column and only runs the conversion when ready to be returned
| to the client.
|
| This method is called during the **SQL compilation** phase of a
| statement, when rendering a SQL string. It is **not** called
| against specific values.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.column_expression`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.column_expression`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.column_expression`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
|
| .. seealso::
|
| :ref:`types_sql_value_processing`
|
| compare_values(self, x: 'Any', y: 'Any') -> 'bool'
| Compare two values for equality.
|
| compile(self, dialect: 'Optional[Dialect]' = None) -> 'str'
| Produce a string-compiled form of this :class:`.TypeEngine`.
|
| When called with no arguments, uses a "default" dialect
| to produce a string result.
|
| :param dialect: a :class:`.Dialect` instance.
|
| copy(self, **kw: 'Any') -> 'Self'
|
| copy_value(self, value: 'Any') -> 'Any'
|
| dialect_impl(self, dialect: 'Dialect') -> 'TypeEngine[_T]'
| Return a dialect-specific implementation for this
| :class:`.TypeEngine`.
|
| evaluates_none(self) -> 'Self'
| Return a copy of this type which has the
| :attr:`.should_evaluate_none` flag set to True.
|
| E.g.::
|
| Table(
| "some_table",
| metadata,
| Column(
| String(50).evaluates_none(),
| nullable=True,
| server_default="no value",
| ),
| )
|
| The ORM uses this flag to indicate that a positive value of ``None``
| is passed to the column in an INSERT statement, rather than omitting
| the column from the INSERT statement which has the effect of firing
| off column-level defaults. It also allows for types which have
| special behavior associated with the Python None value to indicate
| that the value doesn't necessarily translate into SQL NULL; a
| prime example of this is a JSON type which may wish to persist the
| JSON value ``'null'``.
|
| In all cases, the actual NULL SQL value can be always be
| persisted in any column by using
| the :obj:`_expression.null` SQL construct in an INSERT statement
| or associated with an ORM-mapped attribute.
|
| .. note::
|
| The "evaluates none" flag does **not** apply to a value
| of ``None`` passed to :paramref:`_schema.Column.default` or
| :paramref:`_schema.Column.server_default`; in these cases,
| ``None``
| still means "no default".
|
| .. seealso::
|
| :ref:`session_forcing_null` - in the ORM documentation
|
| :paramref:`.postgresql.JSON.none_as_null` - PostgreSQL JSON
| interaction with this flag.
|
| :attr:`.TypeEngine.should_evaluate_none` - class-level flag
|
| result_processor(self, dialect: 'Dialect', coltype: 'object') -> 'Optional[_ResultProcessorType[_T]]'
| Return a conversion function for processing result row values.
|
| Returns a callable which will receive a result row column
| value as the sole positional argument and will return a value
| to return to the user.
|
| If processing is not necessary, the method should return ``None``.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.result_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.result_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_result_value`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| :param dialect: Dialect instance in use.
|
| :param coltype: DBAPI coltype argument received in cursor.description.
|
| with_variant(self, type_: '_TypeEngineArgument[Any]', *dialect_names: 'str') -> 'Self'
| Produce a copy of this type object that will utilize the given
| type when applied to the dialect of the given name.
|
| e.g.::
|
| from sqlalchemy.types import String
| from sqlalchemy.dialects import mysql
|
| string_type = String()
|
| string_type = string_type.with_variant(
| mysql.VARCHAR(collation="foo"), "mysql", "mariadb"
| )
|
| The variant mapping indicates that when this type is
| interpreted by a specific dialect, it will instead be
| transmuted into the given type, rather than using the
| primary type.
|
| .. versionchanged:: 2.0 the :meth:`_types.TypeEngine.with_variant`
| method now works with a :class:`_types.TypeEngine` object "in
| place", returning a copy of the original type rather than returning
| a wrapping object; the ``Variant`` class is no longer used.
|
| :param type\_: a :class:`.TypeEngine` that will be selected
| as a variant from the originating type, when a dialect
| of the given name is in use.
| :param \*dialect_names: one or more base names of the dialect which
| uses this type. (i.e. ``'postgresql'``, ``'mysql'``, etc.)
|
| .. versionchanged:: 2.0 multiple dialect names can be specified
| for one variant.
|
| .. seealso::
|
| :ref:`types_with_variant` - illustrates the use of
| :meth:`_types.TypeEngine.with_variant`.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.type_api.TypeEngine:
|
| __orig_bases__ = (<class 'sqlalchemy.sql.visitors.Visitable'>, typing....
|
| hashable = True
|
| render_bind_cast = False
|
| render_literal_cast = False
|
| should_evaluate_none = False
|
| sort_key_function = None
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.visitors.Visitable:
|
| __class_getitem__(key: 'Any') -> 'Any'
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__() -> 'None'
| This method is called when a class is subclassed.
|
| The default implementation does nothing. It may be
| overridden to extend subclasses.
sqlalchemy.StatementLambdaElement
Python Library Documentation: class StatementLambdaElement in module sqlalchemy.sql.lambdas
class StatementLambdaElement(sqlalchemy.sql.roles.AllowsLambdaRole, LambdaElement, sqlalchemy.sql.base.Executable)
| StatementLambdaElement(fn: '_LambdaType', role: 'Type[SQLRole]', opts: 'Union[Type[LambdaOptions], LambdaOptions]' = <class 'sqlalchemy.sql.lambdas.LambdaOptions'>, apply_propagate_attrs: 'Optional[ClauseElement]' = None)
|
| Represent a composable SQL statement as a :class:`_sql.LambdaElement`.
|
| The :class:`_sql.StatementLambdaElement` is constructed using the
| :func:`_sql.lambda_stmt` function::
|
|
| from sqlalchemy import lambda_stmt
|
| stmt = lambda_stmt(lambda: select(table))
|
| Once constructed, additional criteria can be built onto the statement
| by adding subsequent lambdas, which accept the existing statement
| object as a single parameter::
|
| stmt += lambda s: s.where(table.c.col == parameter)
|
| .. versionadded:: 1.4
|
| .. seealso::
|
| :ref:`engine_lambda_caching`
|
| Method resolution order:
| StatementLambdaElement
| sqlalchemy.sql.roles.AllowsLambdaRole
| LambdaElement
| sqlalchemy.sql.elements.ClauseElement
| sqlalchemy.sql.annotation.SupportsWrappingAnnotations
| sqlalchemy.sql.annotation.SupportsAnnotations
| sqlalchemy.sql.cache_key.MemoizedHasCacheKey
| sqlalchemy.sql.cache_key.HasCacheKey
| sqlalchemy.util.langhelpers.HasMemoized
| sqlalchemy.sql.traversals.HasCopyInternals
| sqlalchemy.sql.visitors.ExternallyTraversible
| sqlalchemy.sql.visitors.HasTraverseInternals
| sqlalchemy.sql.elements.CompilerElement
| sqlalchemy.sql.visitors.Visitable
| sqlalchemy.sql.base.Executable
| sqlalchemy.sql.roles.StatementRole
| sqlalchemy.sql.roles.SQLRole
| builtins.object
|
| Methods defined here:
|
| __add__(self, other: '_StmtLambdaElementType[Any]') -> 'StatementLambdaElement'
|
| add_criteria(self, other: '_StmtLambdaElementType[Any]', enable_tracking: 'bool' = True, track_on: 'Optional[Any]' = None, track_closure_variables: 'bool' = True, track_bound_values: 'bool' = True) -> 'StatementLambdaElement'
| Add new criteria to this :class:`_sql.StatementLambdaElement`.
|
| E.g.::
|
| >>> def my_stmt(parameter):
| ... stmt = lambda_stmt(
| ... lambda: select(table.c.x, table.c.y),
| ... )
| ... stmt = stmt.add_criteria(lambda: table.c.x > parameter)
| ... return stmt
|
| The :meth:`_sql.StatementLambdaElement.add_criteria` method is
| equivalent to using the Python addition operator to add a new
| lambda, except that additional arguments may be added including
| ``track_closure_values`` and ``track_on``::
|
| >>> def my_stmt(self, foo):
| ... stmt = lambda_stmt(
| ... lambda: select(func.max(foo.x, foo.y)),
| ... track_closure_variables=False,
| ... )
| ... stmt = stmt.add_criteria(lambda: self.where_criteria, track_on=[self])
| ... return stmt
|
| See :func:`_sql.lambda_stmt` for a description of the parameters
| accepted.
|
| spoil(self) -> 'NullLambdaStatement'
| Return a new :class:`.StatementLambdaElement` that will run
| all lambdas unconditionally each time.
|
| ----------------------------------------------------------------------
| Readonly properties defined here:
|
| is_delete
|
| is_dml
|
| is_insert
|
| is_select
|
| is_text
|
| is_update
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.AllowsLambdaRole:
|
| allows_lambda = True
|
| ----------------------------------------------------------------------
| Methods inherited from LambdaElement:
|
| __getattr__(self, key)
|
| __init__(self, fn: '_LambdaType', role: 'Type[SQLRole]', opts: 'Union[Type[LambdaOptions], LambdaOptions]' = <class 'sqlalchemy.sql.lambdas.LambdaOptions'>, apply_propagate_attrs: 'Optional[ClauseElement]' = None)
| Initialize self. See help(type(self)) for accurate signature.
|
| __repr__(self)
| Return repr(self).
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from LambdaElement:
|
| __visit_name__ = 'lambda_element'
|
| parent_lambda = None
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.elements.ClauseElement:
|
| __bool__(self)
|
| __getstate__(self)
| Helper for pickle.
|
| __invert__(self)
|
| compare(self, other: 'ClauseElement', **kw: 'Any') -> 'bool'
| Compare this :class:`_expression.ClauseElement` to
| the given :class:`_expression.ClauseElement`.
|
| Subclasses should override the default behavior, which is a
| straight identity comparison.
|
| \**kw are arguments consumed by subclass ``compare()`` methods and
| may be used to modify the criteria for comparison
| (see :class:`_expression.ColumnElement`).
|
| description(...)
|
| entity_namespace(...)
|
| params(self, _ClauseElement__optionaldict: 'Optional[Mapping[str, Any]]' = None, **kwargs: 'Any') -> 'Self'
| Return a copy with :func:`_expression.bindparam` elements
| replaced.
|
| Returns a copy of this ClauseElement with
| :func:`_expression.bindparam`
| elements replaced with values taken from the given dictionary::
|
| >>> clause = column("x") + bindparam("foo")
| >>> print(clause.compile().params)
| {'foo':None}
| >>> print(clause.params({"foo": 7}).compile().params)
| {'foo':7}
|
| self_group(self, against: 'Optional[OperatorType]' = None) -> 'ClauseElement'
| 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.
|
| unique_params(self, _ClauseElement__optionaldict: 'Optional[Dict[str, Any]]' = None, **kwargs: 'Any') -> 'Self'
| Return a copy with :func:`_expression.bindparam` elements
| replaced.
|
| Same functionality as :meth:`_expression.ClauseElement.params`,
| except adds `unique=True`
| to affected bind parameters so that multiple statements can be
| used.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.elements.ClauseElement:
|
| is_clause_element = True
|
| is_selectable = False
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.cache_key.HasCacheKey:
|
| inherit_cache = None
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_instancemethod(fn: '_F') -> '_F'
| Decorate a method memoize its return value.
|
| :meta private:
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_attribute = <class 'sqlalchemy.util.langhelpers.HasMemoized.m...
| A read-only @property that is only evaluated once.
|
| :meta private:
|
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.visitors.HasTraverseInternals:
|
| get_children(self, *, omit_attrs: 'Tuple[str, ...]' = (), **kw: 'Any') -> 'Iterable[HasTraverseInternals]'
| Return immediate child :class:`.visitors.HasTraverseInternals`
| elements of this :class:`.visitors.HasTraverseInternals`.
|
| This is used for visit traversal.
|
| \**kw may contain flags that change the collection that is
| returned, for example to return a subset of items in order to
| cut down on larger traversals, or to return child items from a
| different context (such as schema-level collections instead of
| clause-level).
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.elements.CompilerElement:
|
| __str__(self) -> 'str'
| Return str(self).
|
| compile(self, bind: 'Optional[_HasDialect]' = None, dialect: 'Optional[Dialect]' = None, **kw: 'Any') -> 'Compiled'
| Compile this SQL expression.
|
| The return value is a :class:`~.Compiled` object.
| Calling ``str()`` or ``unicode()`` on the returned value will yield a
| string representation of the result. The
| :class:`~.Compiled` object also can return a
| dictionary of bind parameter names and values
| using the ``params`` accessor.
|
| :param bind: An :class:`.Connection` or :class:`.Engine` which
| can provide a :class:`.Dialect` in order to generate a
| :class:`.Compiled` object. If the ``bind`` and
| ``dialect`` parameters are both omitted, a default SQL compiler
| is used.
|
| :param column_keys: Used for INSERT and UPDATE statements, a list of
| column names which should be present in the VALUES clause of the
| compiled statement. If ``None``, all columns from the target table
| object are rendered.
|
| :param dialect: A :class:`.Dialect` instance which can generate
| a :class:`.Compiled` object. This argument takes precedence over
| the ``bind`` argument.
|
| :param compile_kwargs: optional dictionary of additional parameters
| that will be passed through to the compiler within all "visit"
| methods. This allows any custom flag to be passed through to
| a custom compilation construct, for example. It is also used
| for the case of passing the ``literal_binds`` flag through::
|
| from sqlalchemy.sql import table, column, select
|
| t = table("t", column("x"))
|
| s = select(t).where(t.c.x == 5)
|
| print(s.compile(compile_kwargs={"literal_binds": True}))
|
| .. seealso::
|
| :ref:`faq_sql_expression_string`
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.elements.CompilerElement:
|
| stringify_dialect = 'default'
|
| supports_execution = False
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.visitors.Visitable:
|
| __class_getitem__(key: 'Any') -> 'Any'
|
| __init_subclass__() -> 'None'
| This method is called when a class is subclassed.
|
| The default implementation does nothing. It may be
| overridden to extend subclasses.
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.base.Executable:
|
| execution_options(self, **kw: 'Any') -> 'Self'
| Set non-SQL options for the statement which take effect during
| execution.
|
| Execution options can be set at many scopes, including per-statement,
| per-connection, or per execution, using methods such as
| :meth:`_engine.Connection.execution_options` and parameters which
| accept a dictionary of options such as
| :paramref:`_engine.Connection.execute.execution_options` and
| :paramref:`_orm.Session.execute.execution_options`.
|
| The primary characteristic of an execution option, as opposed to
| other kinds of options such as ORM loader options, is that
| **execution options never affect the compiled SQL of a query, only
| things that affect how the SQL statement itself is invoked or how
| results are fetched**. That is, execution options are not part of
| what's accommodated by SQL compilation nor are they considered part of
| the cached state of a statement.
|
| The :meth:`_sql.Executable.execution_options` method is
| :term:`generative`, as
| is the case for the method as applied to the :class:`_engine.Engine`
| and :class:`_orm.Query` objects, which means when the method is called,
| a copy of the object is returned, which applies the given parameters to
| that new copy, but leaves the original unchanged::
|
| statement = select(table.c.x, table.c.y)
| new_statement = statement.execution_options(my_option=True)
|
| An exception to this behavior is the :class:`_engine.Connection`
| object, where the :meth:`_engine.Connection.execution_options` method
| is explicitly **not** generative.
|
| The kinds of options that may be passed to
| :meth:`_sql.Executable.execution_options` and other related methods and
| parameter dictionaries include parameters that are explicitly consumed
| by SQLAlchemy Core or ORM, as well as arbitrary keyword arguments not
| defined by SQLAlchemy, which means the methods and/or parameter
| dictionaries may be used for user-defined parameters that interact with
| custom code, which may access the parameters using methods such as
| :meth:`_sql.Executable.get_execution_options` and
| :meth:`_engine.Connection.get_execution_options`, or within selected
| event hooks using a dedicated ``execution_options`` event parameter
| such as
| :paramref:`_events.ConnectionEvents.before_execute.execution_options`
| or :attr:`_orm.ORMExecuteState.execution_options`, e.g.::
|
| from sqlalchemy import event
|
|
| @event.listens_for(some_engine, "before_execute")
| def _process_opt(conn, statement, multiparams, params, execution_options):
| "run a SQL function before invoking a statement"
|
| if execution_options.get("do_special_thing", False):
| conn.exec_driver_sql("run_special_function()")
|
| Within the scope of options that are explicitly recognized by
| SQLAlchemy, most apply to specific classes of objects and not others.
| The most common execution options include:
|
| * :paramref:`_engine.Connection.execution_options.isolation_level` -
| sets the isolation level for a connection or a class of connections
| via an :class:`_engine.Engine`. This option is accepted only
| by :class:`_engine.Connection` or :class:`_engine.Engine`.
|
| * :paramref:`_engine.Connection.execution_options.stream_results` -
| indicates results should be fetched using a server side cursor;
| this option is accepted by :class:`_engine.Connection`, by the
| :paramref:`_engine.Connection.execute.execution_options` parameter
| on :meth:`_engine.Connection.execute`, and additionally by
| :meth:`_sql.Executable.execution_options` on a SQL statement object,
| as well as by ORM constructs like :meth:`_orm.Session.execute`.
|
| * :paramref:`_engine.Connection.execution_options.compiled_cache` -
| indicates a dictionary that will serve as the
| :ref:`SQL compilation cache <sql_caching>`
| for a :class:`_engine.Connection` or :class:`_engine.Engine`, as
| well as for ORM methods like :meth:`_orm.Session.execute`.
| Can be passed as ``None`` to disable caching for statements.
| This option is not accepted by
| :meth:`_sql.Executable.execution_options` as it is inadvisable to
| carry along a compilation cache within a statement object.
|
| * :paramref:`_engine.Connection.execution_options.schema_translate_map`
| - a mapping of schema names used by the
| :ref:`Schema Translate Map <schema_translating>` feature, accepted
| by :class:`_engine.Connection`, :class:`_engine.Engine`,
| :class:`_sql.Executable`, as well as by ORM constructs
| like :meth:`_orm.Session.execute`.
|
| .. seealso::
|
| :meth:`_engine.Connection.execution_options`
|
| :paramref:`_engine.Connection.execute.execution_options`
|
| :paramref:`_orm.Session.execute.execution_options`
|
| :ref:`orm_queryguide_execution_options` - documentation on all
| ORM-specific execution options
|
| get_execution_options(self) -> '_ExecuteOptions'
| Get the non-SQL options which will take effect during execution.
|
| .. versionadded:: 1.3
|
| .. seealso::
|
| :meth:`.Executable.execution_options`
|
| options(self, *options: 'ExecutableOption') -> 'Self'
| Apply options to this statement.
|
| In the general sense, options are any kind of Python object
| that can be interpreted by the SQL compiler for the statement.
| These options can be consumed by specific dialects or specific kinds
| of compilers.
|
| The most commonly known kind of option are the ORM level options
| that apply "eager load" and other loading behaviors to an ORM
| query. However, options can theoretically be used for many other
| purposes.
|
| For background on specific kinds of options for specific kinds of
| statements, refer to the documentation for those option objects.
|
| .. versionchanged:: 1.4 - added :meth:`.Executable.options` to
| Core statement objects towards the goal of allowing unified
| Core / ORM querying capabilities.
|
| .. seealso::
|
| :ref:`loading_columns` - refers to options specific to the usage
| of ORM queries
|
| :ref:`relationship_loader_options` - refers to options specific
| to the usage of ORM queries
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.base.Executable:
|
| is_from_statement = False
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.SQLRole:
|
| uses_inspection = False
sqlalchemy.StaticPool
Python Library Documentation: class StaticPool in module sqlalchemy.pool.impl
class StaticPool(sqlalchemy.pool.base.Pool)
| StaticPool(creator: 'Union[_CreatorFnType, _CreatorWRecFnType]', recycle: 'int' = -1, echo: 'log._EchoFlagType' = None, logging_name: 'Optional[str]' = None, reset_on_return: '_ResetStyleArgType' = True, events: 'Optional[List[Tuple[_ListenerFnType, str]]]' = None, dialect: 'Optional[Union[_ConnDialect, Dialect]]' = None, pre_ping: 'bool' = False, _dispatch: 'Optional[_DispatchCommon[Pool]]' = None)
|
| A Pool of exactly one connection, used for all requests.
|
| Reconnect-related functions such as ``recycle`` and connection
| invalidation (which is also used to support auto-reconnect) are only
| partially supported right now and may not yield good results.
|
| The :class:`.StaticPool` class **is compatible** with asyncio and
| :func:`_asyncio.create_async_engine`.
|
| Method resolution order:
| StaticPool
| sqlalchemy.pool.base.Pool
| sqlalchemy.log.Identified
| sqlalchemy.event.registry.EventTarget
| builtins.object
|
| Methods defined here:
|
| connection(...)
|
| dispose(self) -> 'None'
| Dispose of this pool.
|
| This method leaves the possibility of checked-out connections
| remaining open, as it only affects connections that are
| idle in the pool.
|
| .. seealso::
|
| :meth:`Pool.recreate`
|
| recreate(self) -> 'StaticPool'
| Return a new :class:`_pool.Pool`, of the same class as this one
| and configured with identical creation arguments.
|
| This method is used in conjunction with :meth:`dispose`
| to close out an entire :class:`_pool.Pool` and create a new one in
| its place.
|
| status(self) -> 'str'
| Returns a brief description of the state of this pool.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.pool.base.Pool:
|
| __init__(self, creator: 'Union[_CreatorFnType, _CreatorWRecFnType]', recycle: 'int' = -1, echo: 'log._EchoFlagType' = None, logging_name: 'Optional[str]' = None, reset_on_return: '_ResetStyleArgType' = True, events: 'Optional[List[Tuple[_ListenerFnType, str]]]' = None, dialect: 'Optional[Union[_ConnDialect, Dialect]]' = None, pre_ping: 'bool' = False, _dispatch: 'Optional[_DispatchCommon[Pool]]' = None)
| Construct a Pool.
|
| :param creator: a callable function that returns a DB-API
| connection object. The function will be called with
| parameters.
|
| :param recycle: If set to a value other than -1, number of
| seconds between connection recycling, which means upon
| checkout, if this timeout is surpassed the connection will be
| closed and replaced with a newly opened connection. Defaults to -1.
|
| :param logging_name: String identifier which will be used within
| the "name" field of logging records generated within the
| "sqlalchemy.pool" logger. Defaults to a hexstring of the object's
| id.
|
| :param echo: if True, the connection pool will log
| informational output such as when connections are invalidated
| as well as when connections are recycled to the default log handler,
| which defaults to ``sys.stdout`` for output.. If set to the string
| ``"debug"``, the logging will include pool checkouts and checkins.
|
| The :paramref:`_pool.Pool.echo` parameter can also be set from the
| :func:`_sa.create_engine` call by using the
| :paramref:`_sa.create_engine.echo_pool` parameter.
|
| .. seealso::
|
| :ref:`dbengine_logging` - further detail on how to configure
| logging.
|
| :param reset_on_return: Determine steps to take on
| connections as they are returned to the pool, which were
| not otherwise handled by a :class:`_engine.Connection`.
| Available from :func:`_sa.create_engine` via the
| :paramref:`_sa.create_engine.pool_reset_on_return` parameter.
|
| :paramref:`_pool.Pool.reset_on_return` can have any of these values:
|
| * ``"rollback"`` - call rollback() on the connection,
| to release locks and transaction resources.
| This is the default value. The vast majority
| of use cases should leave this value set.
| * ``"commit"`` - call commit() on the connection,
| to release locks and transaction resources.
| A commit here may be desirable for databases that
| cache query plans if a commit is emitted,
| such as Microsoft SQL Server. However, this
| value is more dangerous than 'rollback' because
| any data changes present on the transaction
| are committed unconditionally.
| * ``None`` - don't do anything on the connection.
| This setting may be appropriate if the database / DBAPI
| works in pure "autocommit" mode at all times, or if
| a custom reset handler is established using the
| :meth:`.PoolEvents.reset` event handler.
|
| * ``True`` - same as 'rollback', this is here for
| backwards compatibility.
| * ``False`` - same as None, this is here for
| backwards compatibility.
|
| For further customization of reset on return, the
| :meth:`.PoolEvents.reset` event hook may be used which can perform
| any connection activity desired on reset.
|
| .. seealso::
|
| :ref:`pool_reset_on_return`
|
| :meth:`.PoolEvents.reset`
|
| :param events: a list of 2-tuples, each of the form
| ``(callable, target)`` which will be passed to :func:`.event.listen`
| upon construction. Provided here so that event listeners
| can be assigned via :func:`_sa.create_engine` before dialect-level
| listeners are applied.
|
| :param dialect: a :class:`.Dialect` that will handle the job
| of calling rollback(), close(), or commit() on DBAPI connections.
| If omitted, a built-in "stub" dialect is used. Applications that
| make use of :func:`_sa.create_engine` should not use this parameter
| as it is handled by the engine creation strategy.
|
| :param pre_ping: if True, the pool will emit a "ping" (typically
| "SELECT 1", but is dialect-specific) on the connection
| upon checkout, to test if the connection is alive or not. If not,
| the connection is transparently re-connected and upon success, all
| other pooled connections established prior to that timestamp are
| invalidated. Requires that a dialect is passed as well to
| interpret the disconnection error.
|
| .. versionadded:: 1.2
|
| connect(self) -> 'PoolProxiedConnection'
| Return a DBAPI connection from the pool.
|
| The connection is instrumented such that when its
| ``close()`` method is called, the connection will be returned to
| the pool.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from sqlalchemy.pool.base.Pool:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.pool.base.Pool:
|
| dispatch = <sqlalchemy.event.base.PoolEventsDispatch object>
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.log.Identified:
|
| logging_name = None
sqlalchemy.String
Python Library Documentation: class String in module sqlalchemy.sql.sqltypes
class String(Concatenable, sqlalchemy.sql.type_api.TypeEngine)
| String(length: 'Optional[int]' = None, collation: 'Optional[str]' = None)
|
| The base for all string and character types.
|
| In SQL, corresponds to VARCHAR.
|
| The `length` field is usually required when the `String` type is
| used within a CREATE TABLE statement, as VARCHAR requires a length
| on most databases.
|
| Method resolution order:
| String
| Concatenable
| sqlalchemy.sql.type_api.TypeEngineMixin
| sqlalchemy.sql.type_api.TypeEngine
| sqlalchemy.sql.visitors.Visitable
| typing.Generic
| builtins.object
|
| Methods defined here:
|
| __init__(self, length: 'Optional[int]' = None, collation: 'Optional[str]' = None)
| Create a string-holding type.
|
| :param length: optional, a length for the column for use in
| DDL and CAST expressions. May be safely omitted if no ``CREATE
| TABLE`` will be issued. Certain databases may require a
| ``length`` for use in DDL, and will raise an exception when
| the ``CREATE TABLE`` DDL is issued if a ``VARCHAR``
| with no length is included. Whether the value is
| interpreted as bytes or characters is database specific.
|
| :param collation: Optional, a column-level collation for
| use in DDL and CAST expressions. Renders using the
| COLLATE keyword supported by SQLite, MySQL, and PostgreSQL.
| E.g.:
|
| .. sourcecode:: pycon+sql
|
| >>> from sqlalchemy import cast, select, String
| >>> print(select(cast("some string", String(collation="utf8"))))
| {printsql}SELECT CAST(:param_1 AS VARCHAR COLLATE utf8) AS anon_1
|
| .. note::
|
| In most cases, the :class:`.Unicode` or :class:`.UnicodeText`
| datatypes should be used for a :class:`_schema.Column` that expects
| to store non-ascii data. These datatypes will ensure that the
| correct types are used on the database.
|
| bind_processor(self, dialect: 'Dialect') -> 'Optional[_BindProcessorType[str]]'
| Return a conversion function for processing bind values.
|
| Returns a callable which will receive a bind parameter value
| as the sole positional argument and will return a value to
| send to the DB-API.
|
| If processing is not necessary, the method should return ``None``.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.bind_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.bind_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_bind_param`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
|
| :param dialect: Dialect instance in use.
|
| get_dbapi_type(self, dbapi)
| Return the corresponding type object from the underlying DB-API, if
| any.
|
| This can be useful for calling ``setinputsizes()``, for example.
|
| literal_processor(self, dialect)
| Return a conversion function for processing literal values that are
| to be rendered directly without using binds.
|
| This function is used when the compiler makes use of the
| "literal_binds" flag, typically used in DDL generation as well
| as in certain scenarios where backends don't accept bound parameters.
|
| Returns a callable which will receive a literal Python value
| as the sole positional argument and will return a string representation
| to be rendered in a SQL statement.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.literal_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.literal_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_literal_param`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| result_processor(self, dialect: 'Dialect', coltype: 'object') -> 'Optional[_ResultProcessorType[str]]'
| Return a conversion function for processing result row values.
|
| Returns a callable which will receive a result row column
| value as the sole positional argument and will return a value
| to return to the user.
|
| If processing is not necessary, the method should return ``None``.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.result_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.result_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_result_value`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| :param dialect: Dialect instance in use.
|
| :param coltype: DBAPI coltype argument received in cursor.description.
|
| ----------------------------------------------------------------------
| Readonly properties defined here:
|
| python_type
| Return the Python type object expected to be returned
| by instances of this type, if known.
|
| Basically, for those types which enforce a return type,
| or are known across the board to do such for all common
| DBAPIs (like ``int`` for example), will return that type.
|
| If a return type is not defined, raises
| ``NotImplementedError``.
|
| Note that any type also accommodates NULL in SQL which
| means you can also get back ``None`` from any type
| in practice.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| __parameters__ = ()
|
| __visit_name__ = 'string'
|
| ----------------------------------------------------------------------
| Data descriptors inherited from Concatenable:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from Concatenable:
|
| Comparator = <class 'sqlalchemy.sql.sqltypes.Concatenable.Comparator'>
|
| comparator_factory = <class 'sqlalchemy.sql.sqltypes.Concatenable.Comp...
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.type_api.TypeEngine:
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| __str__(self) -> 'str'
| Return str(self).
|
| adapt(self, cls: 'Type[Union[TypeEngine[Any], TypeEngineMixin]]', **kw: 'Any') -> 'TypeEngine[Any]'
| Produce an "adapted" form of this type, given an "impl" class
| to work with.
|
| This method is used internally to associate generic
| types with "implementation" types that are specific to a particular
| dialect.
|
| as_generic(self, allow_nulltype: 'bool' = False) -> 'TypeEngine[_T]'
| Return an instance of the generic type corresponding to this type
| using heuristic rule. The method may be overridden if this
| heuristic rule is not sufficient.
|
| >>> from sqlalchemy.dialects.mysql import INTEGER
| >>> INTEGER(display_width=4).as_generic()
| Integer()
|
| >>> from sqlalchemy.dialects.mysql import NVARCHAR
| >>> NVARCHAR(length=100).as_generic()
| Unicode(length=100)
|
| .. versionadded:: 1.4.0b2
|
|
| .. seealso::
|
| :ref:`metadata_reflection_dbagnostic_types` - describes the
| use of :meth:`_types.TypeEngine.as_generic` in conjunction with
| the :meth:`_sql.DDLEvents.column_reflect` event, which is its
| intended use.
|
| bind_expression(self, bindvalue: 'BindParameter[_T]') -> 'Optional[ColumnElement[_T]]'
| Given a bind value (i.e. a :class:`.BindParameter` instance),
| return a SQL expression in its place.
|
| This is typically a SQL function that wraps the existing bound
| parameter within the statement. It is used for special data types
| that require literals being wrapped in some special database function
| in order to coerce an application-level value into a database-specific
| format. It is the SQL analogue of the
| :meth:`.TypeEngine.bind_processor` method.
|
| This method is called during the **SQL compilation** phase of a
| statement, when rendering a SQL string. It is **not** called
| against specific values.
|
| Note that this method, when implemented, should always return
| the exact same structure, without any conditional logic, as it
| may be used in an executemany() call against an arbitrary number
| of bound parameter sets.
|
| .. note::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.bind_expression`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.bind_expression`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.bind_expression`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| .. seealso::
|
| :ref:`types_sql_value_processing`
|
| coerce_compared_value(self, op: 'Optional[OperatorType]', value: 'Any') -> 'TypeEngine[Any]'
| Suggest a type for a 'coerced' Python value in an expression.
|
| Given an operator and value, gives the type a chance
| to return a type which the value should be coerced into.
|
| The default behavior here is conservative; if the right-hand
| side is already coerced into a SQL type based on its
| Python type, it is usually left alone.
|
| End-user functionality extension here should generally be via
| :class:`.TypeDecorator`, which provides more liberal behavior in that
| it defaults to coercing the other side of the expression into this
| type, thus applying special Python conversions above and beyond those
| needed by the DBAPI to both ides. It also provides the public method
| :meth:`.TypeDecorator.coerce_compared_value` which is intended for
| end-user customization of this behavior.
|
| column_expression(self, colexpr: 'ColumnElement[_T]') -> 'Optional[ColumnElement[_T]]'
| Given a SELECT column expression, return a wrapping SQL expression.
|
| This is typically a SQL function that wraps a column expression
| as rendered in the columns clause of a SELECT statement.
| It is used for special data types that require
| columns to be wrapped in some special database function in order
| to coerce the value before being sent back to the application.
| It is the SQL analogue of the :meth:`.TypeEngine.result_processor`
| method.
|
| .. note:: The :func:`.TypeEngine.column_expression` method is applied
| only to the **outermost columns clause** of a SELECT statement, that
| is, the columns that are to be delivered directly into the returned
| result rows. It does **not** apply to the columns clause inside
| of subqueries. This necessarily avoids double conversions against
| the column and only runs the conversion when ready to be returned
| to the client.
|
| This method is called during the **SQL compilation** phase of a
| statement, when rendering a SQL string. It is **not** called
| against specific values.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.column_expression`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.column_expression`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.column_expression`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
|
| .. seealso::
|
| :ref:`types_sql_value_processing`
|
| compare_values(self, x: 'Any', y: 'Any') -> 'bool'
| Compare two values for equality.
|
| compile(self, dialect: 'Optional[Dialect]' = None) -> 'str'
| Produce a string-compiled form of this :class:`.TypeEngine`.
|
| When called with no arguments, uses a "default" dialect
| to produce a string result.
|
| :param dialect: a :class:`.Dialect` instance.
|
| copy(self, **kw: 'Any') -> 'Self'
|
| copy_value(self, value: 'Any') -> 'Any'
|
| dialect_impl(self, dialect: 'Dialect') -> 'TypeEngine[_T]'
| Return a dialect-specific implementation for this
| :class:`.TypeEngine`.
|
| evaluates_none(self) -> 'Self'
| Return a copy of this type which has the
| :attr:`.should_evaluate_none` flag set to True.
|
| E.g.::
|
| Table(
| "some_table",
| metadata,
| Column(
| String(50).evaluates_none(),
| nullable=True,
| server_default="no value",
| ),
| )
|
| The ORM uses this flag to indicate that a positive value of ``None``
| is passed to the column in an INSERT statement, rather than omitting
| the column from the INSERT statement which has the effect of firing
| off column-level defaults. It also allows for types which have
| special behavior associated with the Python None value to indicate
| that the value doesn't necessarily translate into SQL NULL; a
| prime example of this is a JSON type which may wish to persist the
| JSON value ``'null'``.
|
| In all cases, the actual NULL SQL value can be always be
| persisted in any column by using
| the :obj:`_expression.null` SQL construct in an INSERT statement
| or associated with an ORM-mapped attribute.
|
| .. note::
|
| The "evaluates none" flag does **not** apply to a value
| of ``None`` passed to :paramref:`_schema.Column.default` or
| :paramref:`_schema.Column.server_default`; in these cases,
| ``None``
| still means "no default".
|
| .. seealso::
|
| :ref:`session_forcing_null` - in the ORM documentation
|
| :paramref:`.postgresql.JSON.none_as_null` - PostgreSQL JSON
| interaction with this flag.
|
| :attr:`.TypeEngine.should_evaluate_none` - class-level flag
|
| with_variant(self, type_: '_TypeEngineArgument[Any]', *dialect_names: 'str') -> 'Self'
| Produce a copy of this type object that will utilize the given
| type when applied to the dialect of the given name.
|
| e.g.::
|
| from sqlalchemy.types import String
| from sqlalchemy.dialects import mysql
|
| string_type = String()
|
| string_type = string_type.with_variant(
| mysql.VARCHAR(collation="foo"), "mysql", "mariadb"
| )
|
| The variant mapping indicates that when this type is
| interpreted by a specific dialect, it will instead be
| transmuted into the given type, rather than using the
| primary type.
|
| .. versionchanged:: 2.0 the :meth:`_types.TypeEngine.with_variant`
| method now works with a :class:`_types.TypeEngine` object "in
| place", returning a copy of the original type rather than returning
| a wrapping object; the ``Variant`` class is no longer used.
|
| :param type\_: a :class:`.TypeEngine` that will be selected
| as a variant from the originating type, when a dialect
| of the given name is in use.
| :param \*dialect_names: one or more base names of the dialect which
| uses this type. (i.e. ``'postgresql'``, ``'mysql'``, etc.)
|
| .. versionchanged:: 2.0 multiple dialect names can be specified
| for one variant.
|
| .. seealso::
|
| :ref:`types_with_variant` - illustrates the use of
| :meth:`_types.TypeEngine.with_variant`.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.type_api.TypeEngine:
|
| __orig_bases__ = (<class 'sqlalchemy.sql.visitors.Visitable'>, typing....
|
| hashable = True
|
| render_bind_cast = False
|
| render_literal_cast = False
|
| should_evaluate_none = False
|
| sort_key_function = None
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.visitors.Visitable:
|
| __class_getitem__(key: 'Any') -> 'Any'
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__() -> 'None'
| This method is called when a class is subclassed.
|
| The default implementation does nothing. It may be
| overridden to extend subclasses.
sqlalchemy.Subquery
Python Library Documentation: class Subquery in module sqlalchemy.sql.selectable
class Subquery(AliasedReturnsRows)
| Subquery(*arg: 'Any', **kw: 'Any')
|
| Represent a subquery of a SELECT.
|
| A :class:`.Subquery` is created by invoking the
| :meth:`_expression.SelectBase.subquery` method, or for convenience the
| :meth:`_expression.SelectBase.alias` method, on any
| :class:`_expression.SelectBase` subclass
| which includes :class:`_expression.Select`,
| :class:`_expression.CompoundSelect`, and
| :class:`_expression.TextualSelect`. As rendered in a FROM clause,
| it represents the
| body of the SELECT statement inside of parenthesis, followed by the usual
| "AS <somename>" that defines all "alias" objects.
|
| The :class:`.Subquery` object is very similar to the
| :class:`_expression.Alias`
| object and can be used in an equivalent way. The difference between
| :class:`_expression.Alias` and :class:`.Subquery` is that
| :class:`_expression.Alias` always
| contains a :class:`_expression.FromClause` object whereas
| :class:`.Subquery`
| always contains a :class:`_expression.SelectBase` object.
|
| .. versionadded:: 1.4 The :class:`.Subquery` class was added which now
| serves the purpose of providing an aliased version of a SELECT
| statement.
|
| Method resolution order:
| Subquery
| AliasedReturnsRows
| NoInit
| NamedFromClause
| FromClause
| sqlalchemy.sql.roles.AnonymizedFromClauseRole
| sqlalchemy.sql.roles.StrictFromClauseRole
| sqlalchemy.sql.roles.FromClauseRole
| sqlalchemy.sql.roles.ColumnsClauseRole
| sqlalchemy.sql.roles.JoinTargetRole
| sqlalchemy.sql.roles.AllowsLambdaRole
| sqlalchemy.sql.roles.UsesInspection
| sqlalchemy.sql.roles.ColumnListRole
| sqlalchemy.sql.roles.StructuralRole
| Selectable
| ReturnsRows
| sqlalchemy.sql.roles.ReturnsRowsRole
| sqlalchemy.sql.roles.SQLRole
| sqlalchemy.sql.elements.DQLDMLClauseElement
| sqlalchemy.sql.elements.ClauseElement
| sqlalchemy.sql.annotation.SupportsWrappingAnnotations
| sqlalchemy.sql.annotation.SupportsAnnotations
| sqlalchemy.sql.cache_key.MemoizedHasCacheKey
| sqlalchemy.sql.cache_key.HasCacheKey
| sqlalchemy.util.langhelpers.HasMemoized
| sqlalchemy.sql.traversals.HasCopyInternals
| sqlalchemy.sql.visitors.ExternallyTraversible
| sqlalchemy.sql.visitors.HasTraverseInternals
| sqlalchemy.sql.elements.CompilerElement
| sqlalchemy.sql.visitors.Visitable
| builtins.object
|
| Methods defined here:
|
| as_scalar(self) -> 'ScalarSelect[Any]'
| .. deprecated:: 1.4 The :meth:`.Subquery.as_scalar` method, which was previously ``Alias.as_scalar()`` prior to version 1.4, is deprecated and will be removed in a future release; Please use the :meth:`_expression.Select.scalar_subquery` method of the :func:`_expression.select` construct before constructing a subquery object, or with the ORM use the :meth:`_query.Query.scalar_subquery` method.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'element': 'SelectBase'}
|
| __visit_name__ = 'subquery'
|
| inherit_cache = True
|
| ----------------------------------------------------------------------
| Methods inherited from AliasedReturnsRows:
|
| description(...)
|
| implicit_returning(...)
|
| 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.
|
| ----------------------------------------------------------------------
| Readonly properties inherited from AliasedReturnsRows:
|
| original
| Legacy for dialects that are referring to Alias.original.
|
| ----------------------------------------------------------------------
| Methods inherited from NoInit:
|
| __init__(self, *arg: 'Any', **kw: 'Any')
| Initialize self. See help(type(self)) for accurate signature.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from NoInit:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Methods inherited from NamedFromClause:
|
| table_valued(self) -> 'TableValuedColumn[Any]'
| Return a :class:`_sql.TableValuedColumn` object for this
| :class:`_expression.FromClause`.
|
| A :class:`_sql.TableValuedColumn` is a :class:`_sql.ColumnElement` that
| represents a complete row in a table. Support for this construct is
| backend dependent, and is supported in various forms by backends
| such as PostgreSQL, Oracle Database and SQL Server.
|
| E.g.:
|
| .. sourcecode:: pycon+sql
|
| >>> from sqlalchemy import select, column, func, table
| >>> a = table("a", column("id"), column("x"), column("y"))
| >>> stmt = select(func.row_to_json(a.table_valued()))
| >>> print(stmt)
| {printsql}SELECT row_to_json(a) AS row_to_json_1
| FROM a
|
| .. versionadded:: 1.4.0b2
|
| .. seealso::
|
| :ref:`tutorial_functions` - in the :ref:`unified_tutorial`
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from NamedFromClause:
|
| named_with_column = True
|
| ----------------------------------------------------------------------
| Methods inherited from FromClause:
|
| alias(self, name: 'Optional[str]' = None, flat: 'bool' = False) -> 'NamedFromClause'
| 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`
|
| c(...)
| A synonym for :attr:`.FromClause.columns`
|
| :return: a :class:`.ColumnCollection`
|
| columns(...)
| 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.
|
| entity_namespace(...)
| 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.
|
| exported_columns(...)
| A :class:`_expression.ColumnCollection`
| that represents the "exported"
| columns of this :class:`_expression.Selectable`.
|
| 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`
|
| foreign_keys(...)
| Return the collection of :class:`_schema.ForeignKey` marker objects
| which this FromClause references.
|
| Each :class:`_schema.ForeignKey` is a member of a
| :class:`_schema.Table`-wide
| :class:`_schema.ForeignKeyConstraint`.
|
| .. seealso::
|
| :attr:`_schema.Table.foreign_key_constraints`
|
| 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
|
| 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`
|
| primary_key(...)
| 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.
|
| select(self) -> 'Select[Any]'
| 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.
|
| 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
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from FromClause:
|
| is_selectable = True
|
| schema = None
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.AllowsLambdaRole:
|
| allows_lambda = True
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.UsesInspection:
|
| uses_inspection = True
|
| ----------------------------------------------------------------------
| Methods inherited from Selectable:
|
| 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.
|
| 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.
|
| 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`.
|
| .. deprecated:: 1.4 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.
|
| ----------------------------------------------------------------------
| Readonly properties inherited from ReturnsRows:
|
| selectable
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.elements.ClauseElement:
|
| __bool__(self)
|
| __getstate__(self)
| Helper for pickle.
|
| __invert__(self)
|
| __repr__(self)
| Return repr(self).
|
| compare(self, other: 'ClauseElement', **kw: 'Any') -> 'bool'
| Compare this :class:`_expression.ClauseElement` to
| the given :class:`_expression.ClauseElement`.
|
| Subclasses should override the default behavior, which is a
| straight identity comparison.
|
| \**kw are arguments consumed by subclass ``compare()`` methods and
| may be used to modify the criteria for comparison
| (see :class:`_expression.ColumnElement`).
|
| params(self, _ClauseElement__optionaldict: 'Optional[Mapping[str, Any]]' = None, **kwargs: 'Any') -> 'Self'
| Return a copy with :func:`_expression.bindparam` elements
| replaced.
|
| Returns a copy of this ClauseElement with
| :func:`_expression.bindparam`
| elements replaced with values taken from the given dictionary::
|
| >>> clause = column("x") + bindparam("foo")
| >>> print(clause.compile().params)
| {'foo':None}
| >>> print(clause.params({"foo": 7}).compile().params)
| {'foo':7}
|
| self_group(self, against: 'Optional[OperatorType]' = None) -> 'ClauseElement'
| 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.
|
| unique_params(self, _ClauseElement__optionaldict: 'Optional[Dict[str, Any]]' = None, **kwargs: 'Any') -> 'Self'
| Return a copy with :func:`_expression.bindparam` elements
| replaced.
|
| Same functionality as :meth:`_expression.ClauseElement.params`,
| except adds `unique=True`
| to affected bind parameters so that multiple statements can be
| used.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.elements.ClauseElement:
|
| is_clause_element = True
|
| is_dml = False
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_instancemethod(fn: '_F') -> '_F'
| Decorate a method memoize its return value.
|
| :meta private:
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_attribute = <class 'sqlalchemy.util.langhelpers.HasMemoized.m...
| A read-only @property that is only evaluated once.
|
| :meta private:
|
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.visitors.HasTraverseInternals:
|
| get_children(self, *, omit_attrs: 'Tuple[str, ...]' = (), **kw: 'Any') -> 'Iterable[HasTraverseInternals]'
| Return immediate child :class:`.visitors.HasTraverseInternals`
| elements of this :class:`.visitors.HasTraverseInternals`.
|
| This is used for visit traversal.
|
| \**kw may contain flags that change the collection that is
| returned, for example to return a subset of items in order to
| cut down on larger traversals, or to return child items from a
| different context (such as schema-level collections instead of
| clause-level).
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.elements.CompilerElement:
|
| __str__(self) -> 'str'
| Return str(self).
|
| compile(self, bind: 'Optional[_HasDialect]' = None, dialect: 'Optional[Dialect]' = None, **kw: 'Any') -> 'Compiled'
| Compile this SQL expression.
|
| The return value is a :class:`~.Compiled` object.
| Calling ``str()`` or ``unicode()`` on the returned value will yield a
| string representation of the result. The
| :class:`~.Compiled` object also can return a
| dictionary of bind parameter names and values
| using the ``params`` accessor.
|
| :param bind: An :class:`.Connection` or :class:`.Engine` which
| can provide a :class:`.Dialect` in order to generate a
| :class:`.Compiled` object. If the ``bind`` and
| ``dialect`` parameters are both omitted, a default SQL compiler
| is used.
|
| :param column_keys: Used for INSERT and UPDATE statements, a list of
| column names which should be present in the VALUES clause of the
| compiled statement. If ``None``, all columns from the target table
| object are rendered.
|
| :param dialect: A :class:`.Dialect` instance which can generate
| a :class:`.Compiled` object. This argument takes precedence over
| the ``bind`` argument.
|
| :param compile_kwargs: optional dictionary of additional parameters
| that will be passed through to the compiler within all "visit"
| methods. This allows any custom flag to be passed through to
| a custom compilation construct, for example. It is also used
| for the case of passing the ``literal_binds`` flag through::
|
| from sqlalchemy.sql import table, column, select
|
| t = table("t", column("x"))
|
| s = select(t).where(t.c.x == 5)
|
| print(s.compile(compile_kwargs={"literal_binds": True}))
|
| .. seealso::
|
| :ref:`faq_sql_expression_string`
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.elements.CompilerElement:
|
| stringify_dialect = 'default'
|
| supports_execution = False
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.visitors.Visitable:
|
| __class_getitem__(key: 'Any') -> 'Any'
|
| __init_subclass__() -> 'None'
| This method is called when a class is subclassed.
|
| The default implementation does nothing. It may be
| overridden to extend subclasses.
sqlalchemy.TEXT
Python Library Documentation: class TEXT in module sqlalchemy.sql.sqltypes
class TEXT(Text)
| TEXT(length: 'Optional[int]' = None, collation: 'Optional[str]' = None)
|
| The SQL TEXT type.
|
| Method resolution order:
| TEXT
| Text
| String
| Concatenable
| sqlalchemy.sql.type_api.TypeEngineMixin
| sqlalchemy.sql.type_api.TypeEngine
| sqlalchemy.sql.visitors.Visitable
| typing.Generic
| builtins.object
|
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| __parameters__ = ()
|
| __visit_name__ = 'TEXT'
|
| ----------------------------------------------------------------------
| Methods inherited from String:
|
| __init__(self, length: 'Optional[int]' = None, collation: 'Optional[str]' = None)
| Create a string-holding type.
|
| :param length: optional, a length for the column for use in
| DDL and CAST expressions. May be safely omitted if no ``CREATE
| TABLE`` will be issued. Certain databases may require a
| ``length`` for use in DDL, and will raise an exception when
| the ``CREATE TABLE`` DDL is issued if a ``VARCHAR``
| with no length is included. Whether the value is
| interpreted as bytes or characters is database specific.
|
| :param collation: Optional, a column-level collation for
| use in DDL and CAST expressions. Renders using the
| COLLATE keyword supported by SQLite, MySQL, and PostgreSQL.
| E.g.:
|
| .. sourcecode:: pycon+sql
|
| >>> from sqlalchemy import cast, select, String
| >>> print(select(cast("some string", String(collation="utf8"))))
| {printsql}SELECT CAST(:param_1 AS VARCHAR COLLATE utf8) AS anon_1
|
| .. note::
|
| In most cases, the :class:`.Unicode` or :class:`.UnicodeText`
| datatypes should be used for a :class:`_schema.Column` that expects
| to store non-ascii data. These datatypes will ensure that the
| correct types are used on the database.
|
| bind_processor(self, dialect: 'Dialect') -> 'Optional[_BindProcessorType[str]]'
| Return a conversion function for processing bind values.
|
| Returns a callable which will receive a bind parameter value
| as the sole positional argument and will return a value to
| send to the DB-API.
|
| If processing is not necessary, the method should return ``None``.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.bind_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.bind_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_bind_param`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
|
| :param dialect: Dialect instance in use.
|
| get_dbapi_type(self, dbapi)
| Return the corresponding type object from the underlying DB-API, if
| any.
|
| This can be useful for calling ``setinputsizes()``, for example.
|
| literal_processor(self, dialect)
| Return a conversion function for processing literal values that are
| to be rendered directly without using binds.
|
| This function is used when the compiler makes use of the
| "literal_binds" flag, typically used in DDL generation as well
| as in certain scenarios where backends don't accept bound parameters.
|
| Returns a callable which will receive a literal Python value
| as the sole positional argument and will return a string representation
| to be rendered in a SQL statement.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.literal_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.literal_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_literal_param`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| result_processor(self, dialect: 'Dialect', coltype: 'object') -> 'Optional[_ResultProcessorType[str]]'
| Return a conversion function for processing result row values.
|
| Returns a callable which will receive a result row column
| value as the sole positional argument and will return a value
| to return to the user.
|
| If processing is not necessary, the method should return ``None``.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.result_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.result_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_result_value`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| :param dialect: Dialect instance in use.
|
| :param coltype: DBAPI coltype argument received in cursor.description.
|
| ----------------------------------------------------------------------
| Readonly properties inherited from String:
|
| python_type
| Return the Python type object expected to be returned
| by instances of this type, if known.
|
| Basically, for those types which enforce a return type,
| or are known across the board to do such for all common
| DBAPIs (like ``int`` for example), will return that type.
|
| If a return type is not defined, raises
| ``NotImplementedError``.
|
| Note that any type also accommodates NULL in SQL which
| means you can also get back ``None`` from any type
| in practice.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from Concatenable:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from Concatenable:
|
| Comparator = <class 'sqlalchemy.sql.sqltypes.Concatenable.Comparator'>
|
| comparator_factory = <class 'sqlalchemy.sql.sqltypes.Concatenable.Comp...
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.type_api.TypeEngine:
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| __str__(self) -> 'str'
| Return str(self).
|
| adapt(self, cls: 'Type[Union[TypeEngine[Any], TypeEngineMixin]]', **kw: 'Any') -> 'TypeEngine[Any]'
| Produce an "adapted" form of this type, given an "impl" class
| to work with.
|
| This method is used internally to associate generic
| types with "implementation" types that are specific to a particular
| dialect.
|
| as_generic(self, allow_nulltype: 'bool' = False) -> 'TypeEngine[_T]'
| Return an instance of the generic type corresponding to this type
| using heuristic rule. The method may be overridden if this
| heuristic rule is not sufficient.
|
| >>> from sqlalchemy.dialects.mysql import INTEGER
| >>> INTEGER(display_width=4).as_generic()
| Integer()
|
| >>> from sqlalchemy.dialects.mysql import NVARCHAR
| >>> NVARCHAR(length=100).as_generic()
| Unicode(length=100)
|
| .. versionadded:: 1.4.0b2
|
|
| .. seealso::
|
| :ref:`metadata_reflection_dbagnostic_types` - describes the
| use of :meth:`_types.TypeEngine.as_generic` in conjunction with
| the :meth:`_sql.DDLEvents.column_reflect` event, which is its
| intended use.
|
| bind_expression(self, bindvalue: 'BindParameter[_T]') -> 'Optional[ColumnElement[_T]]'
| Given a bind value (i.e. a :class:`.BindParameter` instance),
| return a SQL expression in its place.
|
| This is typically a SQL function that wraps the existing bound
| parameter within the statement. It is used for special data types
| that require literals being wrapped in some special database function
| in order to coerce an application-level value into a database-specific
| format. It is the SQL analogue of the
| :meth:`.TypeEngine.bind_processor` method.
|
| This method is called during the **SQL compilation** phase of a
| statement, when rendering a SQL string. It is **not** called
| against specific values.
|
| Note that this method, when implemented, should always return
| the exact same structure, without any conditional logic, as it
| may be used in an executemany() call against an arbitrary number
| of bound parameter sets.
|
| .. note::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.bind_expression`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.bind_expression`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.bind_expression`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| .. seealso::
|
| :ref:`types_sql_value_processing`
|
| coerce_compared_value(self, op: 'Optional[OperatorType]', value: 'Any') -> 'TypeEngine[Any]'
| Suggest a type for a 'coerced' Python value in an expression.
|
| Given an operator and value, gives the type a chance
| to return a type which the value should be coerced into.
|
| The default behavior here is conservative; if the right-hand
| side is already coerced into a SQL type based on its
| Python type, it is usually left alone.
|
| End-user functionality extension here should generally be via
| :class:`.TypeDecorator`, which provides more liberal behavior in that
| it defaults to coercing the other side of the expression into this
| type, thus applying special Python conversions above and beyond those
| needed by the DBAPI to both ides. It also provides the public method
| :meth:`.TypeDecorator.coerce_compared_value` which is intended for
| end-user customization of this behavior.
|
| column_expression(self, colexpr: 'ColumnElement[_T]') -> 'Optional[ColumnElement[_T]]'
| Given a SELECT column expression, return a wrapping SQL expression.
|
| This is typically a SQL function that wraps a column expression
| as rendered in the columns clause of a SELECT statement.
| It is used for special data types that require
| columns to be wrapped in some special database function in order
| to coerce the value before being sent back to the application.
| It is the SQL analogue of the :meth:`.TypeEngine.result_processor`
| method.
|
| .. note:: The :func:`.TypeEngine.column_expression` method is applied
| only to the **outermost columns clause** of a SELECT statement, that
| is, the columns that are to be delivered directly into the returned
| result rows. It does **not** apply to the columns clause inside
| of subqueries. This necessarily avoids double conversions against
| the column and only runs the conversion when ready to be returned
| to the client.
|
| This method is called during the **SQL compilation** phase of a
| statement, when rendering a SQL string. It is **not** called
| against specific values.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.column_expression`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.column_expression`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.column_expression`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
|
| .. seealso::
|
| :ref:`types_sql_value_processing`
|
| compare_values(self, x: 'Any', y: 'Any') -> 'bool'
| Compare two values for equality.
|
| compile(self, dialect: 'Optional[Dialect]' = None) -> 'str'
| Produce a string-compiled form of this :class:`.TypeEngine`.
|
| When called with no arguments, uses a "default" dialect
| to produce a string result.
|
| :param dialect: a :class:`.Dialect` instance.
|
| copy(self, **kw: 'Any') -> 'Self'
|
| copy_value(self, value: 'Any') -> 'Any'
|
| dialect_impl(self, dialect: 'Dialect') -> 'TypeEngine[_T]'
| Return a dialect-specific implementation for this
| :class:`.TypeEngine`.
|
| evaluates_none(self) -> 'Self'
| Return a copy of this type which has the
| :attr:`.should_evaluate_none` flag set to True.
|
| E.g.::
|
| Table(
| "some_table",
| metadata,
| Column(
| String(50).evaluates_none(),
| nullable=True,
| server_default="no value",
| ),
| )
|
| The ORM uses this flag to indicate that a positive value of ``None``
| is passed to the column in an INSERT statement, rather than omitting
| the column from the INSERT statement which has the effect of firing
| off column-level defaults. It also allows for types which have
| special behavior associated with the Python None value to indicate
| that the value doesn't necessarily translate into SQL NULL; a
| prime example of this is a JSON type which may wish to persist the
| JSON value ``'null'``.
|
| In all cases, the actual NULL SQL value can be always be
| persisted in any column by using
| the :obj:`_expression.null` SQL construct in an INSERT statement
| or associated with an ORM-mapped attribute.
|
| .. note::
|
| The "evaluates none" flag does **not** apply to a value
| of ``None`` passed to :paramref:`_schema.Column.default` or
| :paramref:`_schema.Column.server_default`; in these cases,
| ``None``
| still means "no default".
|
| .. seealso::
|
| :ref:`session_forcing_null` - in the ORM documentation
|
| :paramref:`.postgresql.JSON.none_as_null` - PostgreSQL JSON
| interaction with this flag.
|
| :attr:`.TypeEngine.should_evaluate_none` - class-level flag
|
| with_variant(self, type_: '_TypeEngineArgument[Any]', *dialect_names: 'str') -> 'Self'
| Produce a copy of this type object that will utilize the given
| type when applied to the dialect of the given name.
|
| e.g.::
|
| from sqlalchemy.types import String
| from sqlalchemy.dialects import mysql
|
| string_type = String()
|
| string_type = string_type.with_variant(
| mysql.VARCHAR(collation="foo"), "mysql", "mariadb"
| )
|
| The variant mapping indicates that when this type is
| interpreted by a specific dialect, it will instead be
| transmuted into the given type, rather than using the
| primary type.
|
| .. versionchanged:: 2.0 the :meth:`_types.TypeEngine.with_variant`
| method now works with a :class:`_types.TypeEngine` object "in
| place", returning a copy of the original type rather than returning
| a wrapping object; the ``Variant`` class is no longer used.
|
| :param type\_: a :class:`.TypeEngine` that will be selected
| as a variant from the originating type, when a dialect
| of the given name is in use.
| :param \*dialect_names: one or more base names of the dialect which
| uses this type. (i.e. ``'postgresql'``, ``'mysql'``, etc.)
|
| .. versionchanged:: 2.0 multiple dialect names can be specified
| for one variant.
|
| .. seealso::
|
| :ref:`types_with_variant` - illustrates the use of
| :meth:`_types.TypeEngine.with_variant`.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.type_api.TypeEngine:
|
| __orig_bases__ = (<class 'sqlalchemy.sql.visitors.Visitable'>, typing....
|
| hashable = True
|
| render_bind_cast = False
|
| render_literal_cast = False
|
| should_evaluate_none = False
|
| sort_key_function = None
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.visitors.Visitable:
|
| __class_getitem__(key: 'Any') -> 'Any'
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__() -> 'None'
| This method is called when a class is subclassed.
|
| The default implementation does nothing. It may be
| overridden to extend subclasses.
sqlalchemy.TIME
Python Library Documentation: class TIME in module sqlalchemy.sql.sqltypes
class TIME(Time)
| TIME(timezone: 'bool' = False)
|
| The SQL TIME type.
|
| Method resolution order:
| TIME
| Time
| _RenderISO8601NoT
| HasExpressionLookup
| sqlalchemy.sql.type_api.TypeEngineMixin
| sqlalchemy.sql.type_api.TypeEngine
| sqlalchemy.sql.visitors.Visitable
| typing.Generic
| builtins.object
|
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| __parameters__ = ()
|
| __visit_name__ = 'TIME'
|
| ----------------------------------------------------------------------
| Methods inherited from Time:
|
| __init__(self, timezone: 'bool' = False)
| Initialize self. See help(type(self)) for accurate signature.
|
| get_dbapi_type(self, dbapi)
| Return the corresponding type object from the underlying DB-API, if
| any.
|
| This can be useful for calling ``setinputsizes()``, for example.
|
| literal_processor(self, dialect)
| Return a conversion function for processing literal values that are
| to be rendered directly without using binds.
|
| This function is used when the compiler makes use of the
| "literal_binds" flag, typically used in DDL generation as well
| as in certain scenarios where backends don't accept bound parameters.
|
| Returns a callable which will receive a literal Python value
| as the sole positional argument and will return a string representation
| to be rendered in a SQL statement.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.literal_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.literal_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_literal_param`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| ----------------------------------------------------------------------
| Readonly properties inherited from Time:
|
| python_type
| Return the Python type object expected to be returned
| by instances of this type, if known.
|
| Basically, for those types which enforce a return type,
| or are known across the board to do such for all common
| DBAPIs (like ``int`` for example), will return that type.
|
| If a return type is not defined, raises
| ``NotImplementedError``.
|
| Note that any type also accommodates NULL in SQL which
| means you can also get back ``None`` from any type
| in practice.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from _RenderISO8601NoT:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from HasExpressionLookup:
|
| Comparator = <class 'sqlalchemy.sql.sqltypes.HasExpressionLookup.Compa...
|
| comparator_factory = <class 'sqlalchemy.sql.sqltypes.HasExpressionLook...
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.type_api.TypeEngine:
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| __str__(self) -> 'str'
| Return str(self).
|
| adapt(self, cls: 'Type[Union[TypeEngine[Any], TypeEngineMixin]]', **kw: 'Any') -> 'TypeEngine[Any]'
| Produce an "adapted" form of this type, given an "impl" class
| to work with.
|
| This method is used internally to associate generic
| types with "implementation" types that are specific to a particular
| dialect.
|
| as_generic(self, allow_nulltype: 'bool' = False) -> 'TypeEngine[_T]'
| Return an instance of the generic type corresponding to this type
| using heuristic rule. The method may be overridden if this
| heuristic rule is not sufficient.
|
| >>> from sqlalchemy.dialects.mysql import INTEGER
| >>> INTEGER(display_width=4).as_generic()
| Integer()
|
| >>> from sqlalchemy.dialects.mysql import NVARCHAR
| >>> NVARCHAR(length=100).as_generic()
| Unicode(length=100)
|
| .. versionadded:: 1.4.0b2
|
|
| .. seealso::
|
| :ref:`metadata_reflection_dbagnostic_types` - describes the
| use of :meth:`_types.TypeEngine.as_generic` in conjunction with
| the :meth:`_sql.DDLEvents.column_reflect` event, which is its
| intended use.
|
| bind_expression(self, bindvalue: 'BindParameter[_T]') -> 'Optional[ColumnElement[_T]]'
| Given a bind value (i.e. a :class:`.BindParameter` instance),
| return a SQL expression in its place.
|
| This is typically a SQL function that wraps the existing bound
| parameter within the statement. It is used for special data types
| that require literals being wrapped in some special database function
| in order to coerce an application-level value into a database-specific
| format. It is the SQL analogue of the
| :meth:`.TypeEngine.bind_processor` method.
|
| This method is called during the **SQL compilation** phase of a
| statement, when rendering a SQL string. It is **not** called
| against specific values.
|
| Note that this method, when implemented, should always return
| the exact same structure, without any conditional logic, as it
| may be used in an executemany() call against an arbitrary number
| of bound parameter sets.
|
| .. note::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.bind_expression`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.bind_expression`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.bind_expression`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| .. seealso::
|
| :ref:`types_sql_value_processing`
|
| bind_processor(self, dialect: 'Dialect') -> 'Optional[_BindProcessorType[_T]]'
| Return a conversion function for processing bind values.
|
| Returns a callable which will receive a bind parameter value
| as the sole positional argument and will return a value to
| send to the DB-API.
|
| If processing is not necessary, the method should return ``None``.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.bind_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.bind_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_bind_param`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
|
| :param dialect: Dialect instance in use.
|
| coerce_compared_value(self, op: 'Optional[OperatorType]', value: 'Any') -> 'TypeEngine[Any]'
| Suggest a type for a 'coerced' Python value in an expression.
|
| Given an operator and value, gives the type a chance
| to return a type which the value should be coerced into.
|
| The default behavior here is conservative; if the right-hand
| side is already coerced into a SQL type based on its
| Python type, it is usually left alone.
|
| End-user functionality extension here should generally be via
| :class:`.TypeDecorator`, which provides more liberal behavior in that
| it defaults to coercing the other side of the expression into this
| type, thus applying special Python conversions above and beyond those
| needed by the DBAPI to both ides. It also provides the public method
| :meth:`.TypeDecorator.coerce_compared_value` which is intended for
| end-user customization of this behavior.
|
| column_expression(self, colexpr: 'ColumnElement[_T]') -> 'Optional[ColumnElement[_T]]'
| Given a SELECT column expression, return a wrapping SQL expression.
|
| This is typically a SQL function that wraps a column expression
| as rendered in the columns clause of a SELECT statement.
| It is used for special data types that require
| columns to be wrapped in some special database function in order
| to coerce the value before being sent back to the application.
| It is the SQL analogue of the :meth:`.TypeEngine.result_processor`
| method.
|
| .. note:: The :func:`.TypeEngine.column_expression` method is applied
| only to the **outermost columns clause** of a SELECT statement, that
| is, the columns that are to be delivered directly into the returned
| result rows. It does **not** apply to the columns clause inside
| of subqueries. This necessarily avoids double conversions against
| the column and only runs the conversion when ready to be returned
| to the client.
|
| This method is called during the **SQL compilation** phase of a
| statement, when rendering a SQL string. It is **not** called
| against specific values.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.column_expression`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.column_expression`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.column_expression`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
|
| .. seealso::
|
| :ref:`types_sql_value_processing`
|
| compare_values(self, x: 'Any', y: 'Any') -> 'bool'
| Compare two values for equality.
|
| compile(self, dialect: 'Optional[Dialect]' = None) -> 'str'
| Produce a string-compiled form of this :class:`.TypeEngine`.
|
| When called with no arguments, uses a "default" dialect
| to produce a string result.
|
| :param dialect: a :class:`.Dialect` instance.
|
| copy(self, **kw: 'Any') -> 'Self'
|
| copy_value(self, value: 'Any') -> 'Any'
|
| dialect_impl(self, dialect: 'Dialect') -> 'TypeEngine[_T]'
| Return a dialect-specific implementation for this
| :class:`.TypeEngine`.
|
| evaluates_none(self) -> 'Self'
| Return a copy of this type which has the
| :attr:`.should_evaluate_none` flag set to True.
|
| E.g.::
|
| Table(
| "some_table",
| metadata,
| Column(
| String(50).evaluates_none(),
| nullable=True,
| server_default="no value",
| ),
| )
|
| The ORM uses this flag to indicate that a positive value of ``None``
| is passed to the column in an INSERT statement, rather than omitting
| the column from the INSERT statement which has the effect of firing
| off column-level defaults. It also allows for types which have
| special behavior associated with the Python None value to indicate
| that the value doesn't necessarily translate into SQL NULL; a
| prime example of this is a JSON type which may wish to persist the
| JSON value ``'null'``.
|
| In all cases, the actual NULL SQL value can be always be
| persisted in any column by using
| the :obj:`_expression.null` SQL construct in an INSERT statement
| or associated with an ORM-mapped attribute.
|
| .. note::
|
| The "evaluates none" flag does **not** apply to a value
| of ``None`` passed to :paramref:`_schema.Column.default` or
| :paramref:`_schema.Column.server_default`; in these cases,
| ``None``
| still means "no default".
|
| .. seealso::
|
| :ref:`session_forcing_null` - in the ORM documentation
|
| :paramref:`.postgresql.JSON.none_as_null` - PostgreSQL JSON
| interaction with this flag.
|
| :attr:`.TypeEngine.should_evaluate_none` - class-level flag
|
| result_processor(self, dialect: 'Dialect', coltype: 'object') -> 'Optional[_ResultProcessorType[_T]]'
| Return a conversion function for processing result row values.
|
| Returns a callable which will receive a result row column
| value as the sole positional argument and will return a value
| to return to the user.
|
| If processing is not necessary, the method should return ``None``.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.result_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.result_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_result_value`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| :param dialect: Dialect instance in use.
|
| :param coltype: DBAPI coltype argument received in cursor.description.
|
| with_variant(self, type_: '_TypeEngineArgument[Any]', *dialect_names: 'str') -> 'Self'
| Produce a copy of this type object that will utilize the given
| type when applied to the dialect of the given name.
|
| e.g.::
|
| from sqlalchemy.types import String
| from sqlalchemy.dialects import mysql
|
| string_type = String()
|
| string_type = string_type.with_variant(
| mysql.VARCHAR(collation="foo"), "mysql", "mariadb"
| )
|
| The variant mapping indicates that when this type is
| interpreted by a specific dialect, it will instead be
| transmuted into the given type, rather than using the
| primary type.
|
| .. versionchanged:: 2.0 the :meth:`_types.TypeEngine.with_variant`
| method now works with a :class:`_types.TypeEngine` object "in
| place", returning a copy of the original type rather than returning
| a wrapping object; the ``Variant`` class is no longer used.
|
| :param type\_: a :class:`.TypeEngine` that will be selected
| as a variant from the originating type, when a dialect
| of the given name is in use.
| :param \*dialect_names: one or more base names of the dialect which
| uses this type. (i.e. ``'postgresql'``, ``'mysql'``, etc.)
|
| .. versionchanged:: 2.0 multiple dialect names can be specified
| for one variant.
|
| .. seealso::
|
| :ref:`types_with_variant` - illustrates the use of
| :meth:`_types.TypeEngine.with_variant`.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.type_api.TypeEngine:
|
| __orig_bases__ = (<class 'sqlalchemy.sql.visitors.Visitable'>, typing....
|
| hashable = True
|
| render_bind_cast = False
|
| render_literal_cast = False
|
| should_evaluate_none = False
|
| sort_key_function = None
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.visitors.Visitable:
|
| __class_getitem__(key: 'Any') -> 'Any'
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__() -> 'None'
| This method is called when a class is subclassed.
|
| The default implementation does nothing. It may be
| overridden to extend subclasses.
sqlalchemy.TIMESTAMP
Python Library Documentation: class TIMESTAMP in module sqlalchemy.sql.sqltypes
class TIMESTAMP(DateTime)
| TIMESTAMP(timezone: 'bool' = False)
|
| The SQL TIMESTAMP type.
|
| :class:`_types.TIMESTAMP` datatypes have support for timezone storage on
| some backends, such as PostgreSQL and Oracle Database. Use the
| :paramref:`~types.TIMESTAMP.timezone` argument in order to enable
| "TIMESTAMP WITH TIMEZONE" for these backends.
|
| Method resolution order:
| TIMESTAMP
| DateTime
| _RenderISO8601NoT
| HasExpressionLookup
| sqlalchemy.sql.type_api.TypeEngineMixin
| sqlalchemy.sql.type_api.TypeEngine
| sqlalchemy.sql.visitors.Visitable
| typing.Generic
| builtins.object
|
| Methods defined here:
|
| __init__(self, timezone: 'bool' = False)
| Construct a new :class:`_types.TIMESTAMP`.
|
| :param timezone: boolean. Indicates that the TIMESTAMP type should
| enable timezone support, if available on the target database.
| On a per-dialect basis is similar to "TIMESTAMP WITH TIMEZONE".
| If the target database does not support timezones, this flag is
| ignored.
|
| get_dbapi_type(self, dbapi)
| Return the corresponding type object from the underlying DB-API, if
| any.
|
| This can be useful for calling ``setinputsizes()``, for example.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| __parameters__ = ()
|
| __visit_name__ = 'TIMESTAMP'
|
| ----------------------------------------------------------------------
| Methods inherited from DateTime:
|
| literal_processor(self, dialect)
| Return a conversion function for processing literal values that are
| to be rendered directly without using binds.
|
| This function is used when the compiler makes use of the
| "literal_binds" flag, typically used in DDL generation as well
| as in certain scenarios where backends don't accept bound parameters.
|
| Returns a callable which will receive a literal Python value
| as the sole positional argument and will return a string representation
| to be rendered in a SQL statement.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.literal_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.literal_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_literal_param`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| ----------------------------------------------------------------------
| Readonly properties inherited from DateTime:
|
| python_type
| Return the Python type object expected to be returned
| by instances of this type, if known.
|
| Basically, for those types which enforce a return type,
| or are known across the board to do such for all common
| DBAPIs (like ``int`` for example), will return that type.
|
| If a return type is not defined, raises
| ``NotImplementedError``.
|
| Note that any type also accommodates NULL in SQL which
| means you can also get back ``None`` from any type
| in practice.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from _RenderISO8601NoT:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from HasExpressionLookup:
|
| Comparator = <class 'sqlalchemy.sql.sqltypes.HasExpressionLookup.Compa...
|
| comparator_factory = <class 'sqlalchemy.sql.sqltypes.HasExpressionLook...
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.type_api.TypeEngine:
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| __str__(self) -> 'str'
| Return str(self).
|
| adapt(self, cls: 'Type[Union[TypeEngine[Any], TypeEngineMixin]]', **kw: 'Any') -> 'TypeEngine[Any]'
| Produce an "adapted" form of this type, given an "impl" class
| to work with.
|
| This method is used internally to associate generic
| types with "implementation" types that are specific to a particular
| dialect.
|
| as_generic(self, allow_nulltype: 'bool' = False) -> 'TypeEngine[_T]'
| Return an instance of the generic type corresponding to this type
| using heuristic rule. The method may be overridden if this
| heuristic rule is not sufficient.
|
| >>> from sqlalchemy.dialects.mysql import INTEGER
| >>> INTEGER(display_width=4).as_generic()
| Integer()
|
| >>> from sqlalchemy.dialects.mysql import NVARCHAR
| >>> NVARCHAR(length=100).as_generic()
| Unicode(length=100)
|
| .. versionadded:: 1.4.0b2
|
|
| .. seealso::
|
| :ref:`metadata_reflection_dbagnostic_types` - describes the
| use of :meth:`_types.TypeEngine.as_generic` in conjunction with
| the :meth:`_sql.DDLEvents.column_reflect` event, which is its
| intended use.
|
| bind_expression(self, bindvalue: 'BindParameter[_T]') -> 'Optional[ColumnElement[_T]]'
| Given a bind value (i.e. a :class:`.BindParameter` instance),
| return a SQL expression in its place.
|
| This is typically a SQL function that wraps the existing bound
| parameter within the statement. It is used for special data types
| that require literals being wrapped in some special database function
| in order to coerce an application-level value into a database-specific
| format. It is the SQL analogue of the
| :meth:`.TypeEngine.bind_processor` method.
|
| This method is called during the **SQL compilation** phase of a
| statement, when rendering a SQL string. It is **not** called
| against specific values.
|
| Note that this method, when implemented, should always return
| the exact same structure, without any conditional logic, as it
| may be used in an executemany() call against an arbitrary number
| of bound parameter sets.
|
| .. note::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.bind_expression`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.bind_expression`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.bind_expression`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| .. seealso::
|
| :ref:`types_sql_value_processing`
|
| bind_processor(self, dialect: 'Dialect') -> 'Optional[_BindProcessorType[_T]]'
| Return a conversion function for processing bind values.
|
| Returns a callable which will receive a bind parameter value
| as the sole positional argument and will return a value to
| send to the DB-API.
|
| If processing is not necessary, the method should return ``None``.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.bind_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.bind_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_bind_param`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
|
| :param dialect: Dialect instance in use.
|
| coerce_compared_value(self, op: 'Optional[OperatorType]', value: 'Any') -> 'TypeEngine[Any]'
| Suggest a type for a 'coerced' Python value in an expression.
|
| Given an operator and value, gives the type a chance
| to return a type which the value should be coerced into.
|
| The default behavior here is conservative; if the right-hand
| side is already coerced into a SQL type based on its
| Python type, it is usually left alone.
|
| End-user functionality extension here should generally be via
| :class:`.TypeDecorator`, which provides more liberal behavior in that
| it defaults to coercing the other side of the expression into this
| type, thus applying special Python conversions above and beyond those
| needed by the DBAPI to both ides. It also provides the public method
| :meth:`.TypeDecorator.coerce_compared_value` which is intended for
| end-user customization of this behavior.
|
| column_expression(self, colexpr: 'ColumnElement[_T]') -> 'Optional[ColumnElement[_T]]'
| Given a SELECT column expression, return a wrapping SQL expression.
|
| This is typically a SQL function that wraps a column expression
| as rendered in the columns clause of a SELECT statement.
| It is used for special data types that require
| columns to be wrapped in some special database function in order
| to coerce the value before being sent back to the application.
| It is the SQL analogue of the :meth:`.TypeEngine.result_processor`
| method.
|
| .. note:: The :func:`.TypeEngine.column_expression` method is applied
| only to the **outermost columns clause** of a SELECT statement, that
| is, the columns that are to be delivered directly into the returned
| result rows. It does **not** apply to the columns clause inside
| of subqueries. This necessarily avoids double conversions against
| the column and only runs the conversion when ready to be returned
| to the client.
|
| This method is called during the **SQL compilation** phase of a
| statement, when rendering a SQL string. It is **not** called
| against specific values.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.column_expression`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.column_expression`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.column_expression`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
|
| .. seealso::
|
| :ref:`types_sql_value_processing`
|
| compare_values(self, x: 'Any', y: 'Any') -> 'bool'
| Compare two values for equality.
|
| compile(self, dialect: 'Optional[Dialect]' = None) -> 'str'
| Produce a string-compiled form of this :class:`.TypeEngine`.
|
| When called with no arguments, uses a "default" dialect
| to produce a string result.
|
| :param dialect: a :class:`.Dialect` instance.
|
| copy(self, **kw: 'Any') -> 'Self'
|
| copy_value(self, value: 'Any') -> 'Any'
|
| dialect_impl(self, dialect: 'Dialect') -> 'TypeEngine[_T]'
| Return a dialect-specific implementation for this
| :class:`.TypeEngine`.
|
| evaluates_none(self) -> 'Self'
| Return a copy of this type which has the
| :attr:`.should_evaluate_none` flag set to True.
|
| E.g.::
|
| Table(
| "some_table",
| metadata,
| Column(
| String(50).evaluates_none(),
| nullable=True,
| server_default="no value",
| ),
| )
|
| The ORM uses this flag to indicate that a positive value of ``None``
| is passed to the column in an INSERT statement, rather than omitting
| the column from the INSERT statement which has the effect of firing
| off column-level defaults. It also allows for types which have
| special behavior associated with the Python None value to indicate
| that the value doesn't necessarily translate into SQL NULL; a
| prime example of this is a JSON type which may wish to persist the
| JSON value ``'null'``.
|
| In all cases, the actual NULL SQL value can be always be
| persisted in any column by using
| the :obj:`_expression.null` SQL construct in an INSERT statement
| or associated with an ORM-mapped attribute.
|
| .. note::
|
| The "evaluates none" flag does **not** apply to a value
| of ``None`` passed to :paramref:`_schema.Column.default` or
| :paramref:`_schema.Column.server_default`; in these cases,
| ``None``
| still means "no default".
|
| .. seealso::
|
| :ref:`session_forcing_null` - in the ORM documentation
|
| :paramref:`.postgresql.JSON.none_as_null` - PostgreSQL JSON
| interaction with this flag.
|
| :attr:`.TypeEngine.should_evaluate_none` - class-level flag
|
| result_processor(self, dialect: 'Dialect', coltype: 'object') -> 'Optional[_ResultProcessorType[_T]]'
| Return a conversion function for processing result row values.
|
| Returns a callable which will receive a result row column
| value as the sole positional argument and will return a value
| to return to the user.
|
| If processing is not necessary, the method should return ``None``.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.result_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.result_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_result_value`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| :param dialect: Dialect instance in use.
|
| :param coltype: DBAPI coltype argument received in cursor.description.
|
| with_variant(self, type_: '_TypeEngineArgument[Any]', *dialect_names: 'str') -> 'Self'
| Produce a copy of this type object that will utilize the given
| type when applied to the dialect of the given name.
|
| e.g.::
|
| from sqlalchemy.types import String
| from sqlalchemy.dialects import mysql
|
| string_type = String()
|
| string_type = string_type.with_variant(
| mysql.VARCHAR(collation="foo"), "mysql", "mariadb"
| )
|
| The variant mapping indicates that when this type is
| interpreted by a specific dialect, it will instead be
| transmuted into the given type, rather than using the
| primary type.
|
| .. versionchanged:: 2.0 the :meth:`_types.TypeEngine.with_variant`
| method now works with a :class:`_types.TypeEngine` object "in
| place", returning a copy of the original type rather than returning
| a wrapping object; the ``Variant`` class is no longer used.
|
| :param type\_: a :class:`.TypeEngine` that will be selected
| as a variant from the originating type, when a dialect
| of the given name is in use.
| :param \*dialect_names: one or more base names of the dialect which
| uses this type. (i.e. ``'postgresql'``, ``'mysql'``, etc.)
|
| .. versionchanged:: 2.0 multiple dialect names can be specified
| for one variant.
|
| .. seealso::
|
| :ref:`types_with_variant` - illustrates the use of
| :meth:`_types.TypeEngine.with_variant`.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.type_api.TypeEngine:
|
| __orig_bases__ = (<class 'sqlalchemy.sql.visitors.Visitable'>, typing....
|
| hashable = True
|
| render_bind_cast = False
|
| render_literal_cast = False
|
| should_evaluate_none = False
|
| sort_key_function = None
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.visitors.Visitable:
|
| __class_getitem__(key: 'Any') -> 'Any'
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__() -> 'None'
| This method is called when a class is subclassed.
|
| The default implementation does nothing. It may be
| overridden to extend subclasses.
sqlalchemy.Table
Python Library Documentation: class Table in module sqlalchemy.sql.schema
class Table(sqlalchemy.sql.base.DialectKWArgs, HasSchemaAttr, sqlalchemy.sql.selectable.TableClause, sqlalchemy.inspection.Inspectable)
| Table(*args: 'Any', **kw: 'Any') -> 'Any'
|
| Represent a table in a database.
|
| e.g.::
|
| mytable = Table(
| "mytable",
| metadata,
| Column("mytable_id", Integer, primary_key=True),
| Column("value", String(50)),
| )
|
| The :class:`_schema.Table`
| object constructs a unique instance of itself based
| on its name and optional schema name within the given
| :class:`_schema.MetaData` object. Calling the :class:`_schema.Table`
| constructor with the same name and same :class:`_schema.MetaData` argument
| a second time will return the *same* :class:`_schema.Table`
| object - in this way
| the :class:`_schema.Table` constructor acts as a registry function.
|
| .. seealso::
|
| :ref:`metadata_describing` - Introduction to database metadata
|
| Method resolution order:
| Table
| sqlalchemy.sql.base.DialectKWArgs
| HasSchemaAttr
| SchemaItem
| sqlalchemy.sql.base.SchemaVisitable
| sqlalchemy.sql.base.SchemaEventTarget
| sqlalchemy.event.registry.EventTarget
| sqlalchemy.sql.selectable.TableClause
| sqlalchemy.sql.roles.DMLTableRole
| sqlalchemy.sql.base.Immutable
| sqlalchemy.sql.selectable.NamedFromClause
| sqlalchemy.sql.selectable.FromClause
| sqlalchemy.sql.roles.AnonymizedFromClauseRole
| sqlalchemy.sql.roles.StrictFromClauseRole
| sqlalchemy.sql.roles.FromClauseRole
| sqlalchemy.sql.roles.ColumnsClauseRole
| sqlalchemy.sql.roles.JoinTargetRole
| sqlalchemy.sql.roles.AllowsLambdaRole
| sqlalchemy.sql.roles.UsesInspection
| sqlalchemy.sql.roles.ColumnListRole
| sqlalchemy.sql.roles.StructuralRole
| sqlalchemy.sql.selectable.Selectable
| sqlalchemy.sql.selectable.ReturnsRows
| sqlalchemy.sql.roles.ReturnsRowsRole
| sqlalchemy.sql.roles.SQLRole
| sqlalchemy.sql.elements.DQLDMLClauseElement
| sqlalchemy.sql.elements.ClauseElement
| sqlalchemy.sql.annotation.SupportsWrappingAnnotations
| sqlalchemy.sql.annotation.SupportsAnnotations
| sqlalchemy.sql.cache_key.MemoizedHasCacheKey
| sqlalchemy.sql.cache_key.HasCacheKey
| sqlalchemy.util.langhelpers.HasMemoized
| sqlalchemy.sql.traversals.HasCopyInternals
| sqlalchemy.sql.visitors.ExternallyTraversible
| sqlalchemy.sql.visitors.HasTraverseInternals
| sqlalchemy.sql.elements.CompilerElement
| sqlalchemy.sql.visitors.Visitable
| sqlalchemy.inspection.Inspectable
| typing.Generic
| builtins.object
|
| Methods defined here:
|
| __init__(self, name: 'str', metadata: 'MetaData', *args: 'SchemaItem', schema: 'Optional[Union[str, Literal[SchemaConst.BLANK_SCHEMA]]]' = None, quote: 'Optional[bool]' = None, quote_schema: 'Optional[bool]' = None, autoload_with: 'Optional[Union[Engine, Connection]]' = None, autoload_replace: 'bool' = True, keep_existing: 'bool' = False, extend_existing: 'bool' = False, resolve_fks: 'bool' = True, include_columns: 'Optional[Collection[str]]' = None, implicit_returning: 'bool' = True, comment: 'Optional[str]' = None, info: 'Optional[Dict[Any, Any]]' = None, listeners: 'Optional[_typing_Sequence[Tuple[str, Callable[..., Any]]]]' = None, prefixes: 'Optional[_typing_Sequence[str]]' = None, _extend_on: 'Optional[Set[Table]]' = None, _no_init: 'bool' = True, **kw: 'Any') -> 'None'
| Constructor for :class:`_schema.Table`.
|
|
| :param name: The name of this table as represented in the database.
|
| The table name, along with the value of the ``schema`` parameter,
| forms a key which uniquely identifies this :class:`_schema.Table`
| within
| the owning :class:`_schema.MetaData` collection.
| Additional calls to :class:`_schema.Table` with the same name,
| metadata,
| and schema name will return the same :class:`_schema.Table` object.
|
| Names which contain no upper case characters
| will be treated as case insensitive names, and will not be quoted
| unless they are a reserved word or contain special characters.
| A name with any number of upper case characters is considered
| to be case sensitive, and will be sent as quoted.
|
| To enable unconditional quoting for the table name, specify the flag
| ``quote=True`` to the constructor, or use the :class:`.quoted_name`
| construct to specify the name.
|
| :param metadata: a :class:`_schema.MetaData`
| object which will contain this
| table. The metadata is used as a point of association of this table
| with other tables which are referenced via foreign key. It also
| may be used to associate this table with a particular
| :class:`.Connection` or :class:`.Engine`.
|
| :param \*args: Additional positional arguments are used primarily
| to add the list of :class:`_schema.Column`
| objects contained within this
| table. Similar to the style of a CREATE TABLE statement, other
| :class:`.SchemaItem` constructs may be added here, including
| :class:`.PrimaryKeyConstraint`, and
| :class:`_schema.ForeignKeyConstraint`.
|
| :param autoload_replace: Defaults to ``True``; when using
| :paramref:`_schema.Table.autoload_with`
| in conjunction with :paramref:`_schema.Table.extend_existing`,
| indicates
| that :class:`_schema.Column` objects present in the already-existing
| :class:`_schema.Table`
| object should be replaced with columns of the same
| name retrieved from the autoload process. When ``False``, columns
| already present under existing names will be omitted from the
| reflection process.
|
| Note that this setting does not impact :class:`_schema.Column` objects
| specified programmatically within the call to :class:`_schema.Table`
| that
| also is autoloading; those :class:`_schema.Column` objects will always
| replace existing columns of the same name when
| :paramref:`_schema.Table.extend_existing` is ``True``.
|
| .. seealso::
|
| :paramref:`_schema.Table.autoload_with`
|
| :paramref:`_schema.Table.extend_existing`
|
| :param autoload_with: An :class:`_engine.Engine` or
| :class:`_engine.Connection` object,
| or a :class:`_reflection.Inspector` object as returned by
| :func:`_sa.inspect`
| against one, with which this :class:`_schema.Table`
| object will be reflected.
| When set to a non-None value, the autoload process will take place
| for this table against the given engine or connection.
|
| .. seealso::
|
| :ref:`metadata_reflection_toplevel`
|
| :meth:`_events.DDLEvents.column_reflect`
|
| :ref:`metadata_reflection_dbagnostic_types`
|
| :param extend_existing: When ``True``, indicates that if this
| :class:`_schema.Table` is already present in the given
| :class:`_schema.MetaData`,
| apply further arguments within the constructor to the existing
| :class:`_schema.Table`.
|
| If :paramref:`_schema.Table.extend_existing` or
| :paramref:`_schema.Table.keep_existing` are not set,
| and the given name
| of the new :class:`_schema.Table` refers to a :class:`_schema.Table`
| that is
| already present in the target :class:`_schema.MetaData` collection,
| and
| this :class:`_schema.Table`
| specifies additional columns or other constructs
| or flags that modify the table's state, an
| error is raised. The purpose of these two mutually-exclusive flags
| is to specify what action should be taken when a
| :class:`_schema.Table`
| is specified that matches an existing :class:`_schema.Table`,
| yet specifies
| additional constructs.
|
| :paramref:`_schema.Table.extend_existing`
| will also work in conjunction
| with :paramref:`_schema.Table.autoload_with` to run a new reflection
| operation against the database, even if a :class:`_schema.Table`
| of the same name is already present in the target
| :class:`_schema.MetaData`; newly reflected :class:`_schema.Column`
| objects
| and other options will be added into the state of the
| :class:`_schema.Table`, potentially overwriting existing columns
| and options of the same name.
|
| As is always the case with :paramref:`_schema.Table.autoload_with`,
| :class:`_schema.Column` objects can be specified in the same
| :class:`_schema.Table`
| constructor, which will take precedence. Below, the existing
| table ``mytable`` will be augmented with :class:`_schema.Column`
| objects
| both reflected from the database, as well as the given
| :class:`_schema.Column`
| named "y"::
|
| Table(
| "mytable",
| metadata,
| Column("y", Integer),
| extend_existing=True,
| autoload_with=engine,
| )
|
| .. seealso::
|
| :paramref:`_schema.Table.autoload_with`
|
| :paramref:`_schema.Table.autoload_replace`
|
| :paramref:`_schema.Table.keep_existing`
|
|
| :param implicit_returning: True by default - indicates that
| RETURNING can be used, typically by the ORM, in order to fetch
| server-generated values such as primary key values and
| server side defaults, on those backends which support RETURNING.
|
| In modern SQLAlchemy there is generally no reason to alter this
| setting, except for some backend specific cases
| (see :ref:`mssql_triggers` in the SQL Server dialect documentation
| for one such example).
|
| :param include_columns: A list of strings indicating a subset of
| columns to be loaded via the ``autoload`` operation; table columns who
| aren't present in this list will not be represented on the resulting
| ``Table`` object. Defaults to ``None`` which indicates all columns
| should be reflected.
|
| :param resolve_fks: Whether or not to reflect :class:`_schema.Table`
| objects
| related to this one via :class:`_schema.ForeignKey` objects, when
| :paramref:`_schema.Table.autoload_with` is
| specified. Defaults to True. Set to False to disable reflection of
| related tables as :class:`_schema.ForeignKey`
| objects are encountered; may be
| used either to save on SQL calls or to avoid issues with related tables
| that can't be accessed. Note that if a related table is already present
| in the :class:`_schema.MetaData` collection, or becomes present later,
| a
| :class:`_schema.ForeignKey` object associated with this
| :class:`_schema.Table` will
| resolve to that table normally.
|
| .. versionadded:: 1.3
|
| .. seealso::
|
| :paramref:`.MetaData.reflect.resolve_fks`
|
|
| :param info: Optional data dictionary which will be populated into the
| :attr:`.SchemaItem.info` attribute of this object.
|
| :param keep_existing: When ``True``, indicates that if this Table
| is already present in the given :class:`_schema.MetaData`, ignore
| further arguments within the constructor to the existing
| :class:`_schema.Table`, and return the :class:`_schema.Table`
| object as
| originally created. This is to allow a function that wishes
| to define a new :class:`_schema.Table` on first call, but on
| subsequent calls will return the same :class:`_schema.Table`,
| without any of the declarations (particularly constraints)
| being applied a second time.
|
| If :paramref:`_schema.Table.extend_existing` or
| :paramref:`_schema.Table.keep_existing` are not set,
| and the given name
| of the new :class:`_schema.Table` refers to a :class:`_schema.Table`
| that is
| already present in the target :class:`_schema.MetaData` collection,
| and
| this :class:`_schema.Table`
| specifies additional columns or other constructs
| or flags that modify the table's state, an
| error is raised. The purpose of these two mutually-exclusive flags
| is to specify what action should be taken when a
| :class:`_schema.Table`
| is specified that matches an existing :class:`_schema.Table`,
| yet specifies
| additional constructs.
|
| .. seealso::
|
| :paramref:`_schema.Table.extend_existing`
|
| :param listeners: A list of tuples of the form ``(<eventname>, <fn>)``
| which will be passed to :func:`.event.listen` upon construction.
| This alternate hook to :func:`.event.listen` allows the establishment
| of a listener function specific to this :class:`_schema.Table` before
| the "autoload" process begins. Historically this has been intended
| for use with the :meth:`.DDLEvents.column_reflect` event, however
| note that this event hook may now be associated with the
| :class:`_schema.MetaData` object directly::
|
| def listen_for_reflect(table, column_info):
| "handle the column reflection event"
| # ...
|
|
| t = Table(
| "sometable",
| autoload_with=engine,
| listeners=[("column_reflect", listen_for_reflect)],
| )
|
| .. seealso::
|
| :meth:`_events.DDLEvents.column_reflect`
|
| :param must_exist: When ``True``, indicates that this Table must already
| be present in the given :class:`_schema.MetaData` collection, else
| an exception is raised.
|
| :param prefixes:
| A list of strings to insert after CREATE in the CREATE TABLE
| statement. They will be separated by spaces.
|
| :param quote: Force quoting of this table's name on or off, corresponding
| to ``True`` or ``False``. When left at its default of ``None``,
| the column identifier will be quoted according to whether the name is
| case sensitive (identifiers with at least one upper case character are
| treated as case sensitive), or if it's a reserved word. This flag
| is only needed to force quoting of a reserved word which is not known
| by the SQLAlchemy dialect.
|
| .. note:: setting this flag to ``False`` will not provide
| case-insensitive behavior for table reflection; table reflection
| will always search for a mixed-case name in a case sensitive
| fashion. Case insensitive names are specified in SQLAlchemy only
| by stating the name with all lower case characters.
|
| :param quote_schema: same as 'quote' but applies to the schema identifier.
|
| :param schema: The schema name for this table, which is required if
| the table resides in a schema other than the default selected schema
| for the engine's database connection. Defaults to ``None``.
|
| If the owning :class:`_schema.MetaData` of this :class:`_schema.Table`
| specifies its
| own :paramref:`_schema.MetaData.schema` parameter,
| then that schema name will
| be applied to this :class:`_schema.Table`
| if the schema parameter here is set
| to ``None``. To set a blank schema name on a :class:`_schema.Table`
| that
| would otherwise use the schema set on the owning
| :class:`_schema.MetaData`,
| specify the special symbol :attr:`.BLANK_SCHEMA`.
|
| The quoting rules for the schema name are the same as those for the
| ``name`` parameter, in that quoting is applied for reserved words or
| case-sensitive names; to enable unconditional quoting for the schema
| name, specify the flag ``quote_schema=True`` to the constructor, or use
| the :class:`.quoted_name` construct to specify the name.
|
| :param comment: Optional string that will render an SQL comment on table
| creation.
|
| .. versionadded:: 1.2 Added the :paramref:`_schema.Table.comment`
| parameter
| to :class:`_schema.Table`.
|
| :param \**kw: Additional keyword arguments not mentioned above are
| dialect specific, and passed in the form ``<dialectname>_<argname>``.
| See the documentation regarding an individual dialect at
| :ref:`dialect_toplevel` for detail on documented arguments.
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| __str__(self) -> 'str'
| Return str(self).
|
| add_is_dependent_on(self, table: 'Table') -> 'None'
| Add a 'dependency' for this Table.
|
| This is another Table object which must be created
| first before this one can, or dropped after this one.
|
| Usually, dependencies between tables are determined via
| ForeignKey objects. However, for other situations that
| create dependencies outside of foreign keys (rules, inheriting),
| this method can manually establish such a link.
|
| append_column(self, column: 'ColumnClause[Any]', replace_existing: 'bool' = False) -> 'None'
| Append a :class:`_schema.Column` to this :class:`_schema.Table`.
|
| The "key" of the newly added :class:`_schema.Column`, i.e. the
| value of its ``.key`` attribute, will then be available
| in the ``.c`` collection of this :class:`_schema.Table`, and the
| column definition will be included in any CREATE TABLE, SELECT,
| UPDATE, etc. statements generated from this :class:`_schema.Table`
| construct.
|
| Note that this does **not** change the definition of the table
| as it exists within any underlying database, assuming that
| table has already been created in the database. Relational
| databases support the addition of columns to existing tables
| using the SQL ALTER command, which would need to be
| emitted for an already-existing table that doesn't contain
| the newly added column.
|
| :param replace_existing: When ``True``, allows replacing existing
| columns. When ``False``, the default, an warning will be raised
| if a column with the same ``.key`` already exists. A future
| version of sqlalchemy will instead rise a warning.
|
| .. versionadded:: 1.4.0
|
| append_constraint(self, constraint: 'Union[Index, Constraint]') -> 'None'
| Append a :class:`_schema.Constraint` to this
| :class:`_schema.Table`.
|
| This has the effect of the constraint being included in any
| future CREATE TABLE statement, assuming specific DDL creation
| events have not been associated with the given
| :class:`_schema.Constraint` object.
|
| Note that this does **not** produce the constraint within the
| relational database automatically, for a table that already exists
| in the database. To add a constraint to an
| existing relational database table, the SQL ALTER command must
| be used. SQLAlchemy also provides the
| :class:`.AddConstraint` construct which can produce this SQL when
| invoked as an executable clause.
|
| create(self, bind: '_CreateDropBind', checkfirst: 'bool' = False) -> 'None'
| Issue a ``CREATE`` statement for this
| :class:`_schema.Table`, using the given
| :class:`.Connection` or :class:`.Engine`
| for connectivity.
|
| .. seealso::
|
| :meth:`_schema.MetaData.create_all`.
|
| drop(self, bind: '_CreateDropBind', checkfirst: 'bool' = False) -> 'None'
| Issue a ``DROP`` statement for this
| :class:`_schema.Table`, using the given
| :class:`.Connection` or :class:`.Engine` for connectivity.
|
| .. seealso::
|
| :meth:`_schema.MetaData.drop_all`.
|
| to_metadata(self, metadata: 'MetaData', schema: 'Union[str, Literal[SchemaConst.RETAIN_SCHEMA]]' = <SchemaConst.RETAIN_SCHEMA: 1>, referred_schema_fn: 'Optional[Callable[[Table, Optional[str], ForeignKeyConstraint, Optional[str]], Optional[str]]]' = None, name: 'Optional[str]' = None) -> 'Table'
| Return a copy of this :class:`_schema.Table` associated with a
| different :class:`_schema.MetaData`.
|
| E.g.::
|
| m1 = MetaData()
|
| user = Table("user", m1, Column("id", Integer, primary_key=True))
|
| m2 = MetaData()
| user_copy = user.to_metadata(m2)
|
| .. versionchanged:: 1.4 The :meth:`_schema.Table.to_metadata` function
| was renamed from :meth:`_schema.Table.tometadata`.
|
|
| :param metadata: Target :class:`_schema.MetaData` object,
| into which the
| new :class:`_schema.Table` object will be created.
|
| :param schema: optional string name indicating the target schema.
| Defaults to the special symbol :attr:`.RETAIN_SCHEMA` which indicates
| that no change to the schema name should be made in the new
| :class:`_schema.Table`. If set to a string name, the new
| :class:`_schema.Table`
| will have this new name as the ``.schema``. If set to ``None``, the
| schema will be set to that of the schema set on the target
| :class:`_schema.MetaData`, which is typically ``None`` as well,
| unless
| set explicitly::
|
| m2 = MetaData(schema="newschema")
|
| # user_copy_one will have "newschema" as the schema name
| user_copy_one = user.to_metadata(m2, schema=None)
|
| m3 = MetaData() # schema defaults to None
|
| # user_copy_two will have None as the schema name
| user_copy_two = user.to_metadata(m3, schema=None)
|
| :param referred_schema_fn: optional callable which can be supplied
| in order to provide for the schema name that should be assigned
| to the referenced table of a :class:`_schema.ForeignKeyConstraint`.
| The callable accepts this parent :class:`_schema.Table`, the
| target schema that we are changing to, the
| :class:`_schema.ForeignKeyConstraint` object, and the existing
| "target schema" of that constraint. The function should return the
| string schema name that should be applied. To reset the schema
| to "none", return the symbol :data:`.BLANK_SCHEMA`. To effect no
| change, return ``None`` or :data:`.RETAIN_SCHEMA`.
|
| .. versionchanged:: 1.4.33 The ``referred_schema_fn`` function
| may return the :data:`.BLANK_SCHEMA` or :data:`.RETAIN_SCHEMA`
| symbols.
|
| E.g.::
|
| def referred_schema_fn(table, to_schema, constraint, referred_schema):
| if referred_schema == "base_tables":
| return referred_schema
| else:
| return to_schema
|
|
| new_table = table.to_metadata(
| m2, schema="alt_schema", referred_schema_fn=referred_schema_fn
| )
|
| :param name: optional string name indicating the target table name.
| If not specified or None, the table name is retained. This allows
| a :class:`_schema.Table` to be copied to the same
| :class:`_schema.MetaData` target
| with a new name.
|
| tometadata(self, metadata: 'MetaData', schema: 'Union[str, Literal[SchemaConst.RETAIN_SCHEMA]]' = <SchemaConst.RETAIN_SCHEMA: 1>, referred_schema_fn: 'Optional[Callable[[Table, Optional[str], ForeignKeyConstraint, Optional[str]], Optional[str]]]' = None, name: 'Optional[str]' = None) -> 'Table'
| Return a copy of this :class:`_schema.Table`
| associated with a different
| :class:`_schema.MetaData`.
|
| .. deprecated:: 1.4 :meth:`_schema.Table.tometadata` is renamed to :meth:`_schema.Table.to_metadata`
|
| See :meth:`_schema.Table.to_metadata` for a full description.
|
| ----------------------------------------------------------------------
| Static methods defined here:
|
| __new__(cls, *args: 'Any', **kw: 'Any') -> 'Any'
|
| ----------------------------------------------------------------------
| Readonly properties defined here:
|
| autoincrement_column
| Returns the :class:`.Column` object which currently represents
| the "auto increment" column, if any, else returns None.
|
| This is based on the rules for :class:`.Column` as defined by the
| :paramref:`.Column.autoincrement` parameter, which generally means the
| column within a single integer column primary key constraint that is
| not constrained by a foreign key. If the table does not have such
| a primary key constraint, then there's no "autoincrement" column.
| A :class:`.Table` may have only one column defined as the
| "autoincrement" column.
|
| .. versionadded:: 2.0.4
|
| .. seealso::
|
| :paramref:`.Column.autoincrement`
|
| foreign_key_constraints
| :class:`_schema.ForeignKeyConstraint` objects referred to by this
| :class:`_schema.Table`.
|
| This list is produced from the collection of
| :class:`_schema.ForeignKey`
| objects currently associated.
|
|
| .. seealso::
|
| :attr:`_schema.Table.constraints`
|
| :attr:`_schema.Table.foreign_keys`
|
| :attr:`_schema.Table.indexes`
|
| key
| Return the 'key' for this :class:`_schema.Table`.
|
| This value is used as the dictionary key within the
| :attr:`_schema.MetaData.tables` collection. It is typically the same
| as that of :attr:`_schema.Table.name` for a table with no
| :attr:`_schema.Table.schema`
| set; otherwise it is typically of the form
| ``schemaname.tablename``.
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'_columns': 'DedupeColumnCollection[Column[Any]]', ...
|
| __orig_bases__ = (<class 'sqlalchemy.sql.base.DialectKWArgs'>, <class ...
|
| __parameters__ = ()
|
| __visit_name__ = 'table'
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.base.DialectKWArgs:
|
| dialect_options(...)
| A collection of keyword arguments specified as dialect-specific
| options to this construct.
|
| This is a two-level nested registry, keyed to ``<dialect_name>``
| and ``<argument_name>``. For example, the ``postgresql_where``
| argument would be locatable as::
|
| arg = my_object.dialect_options["postgresql"]["where"]
|
| .. versionadded:: 0.9.2
|
| .. seealso::
|
| :attr:`.DialectKWArgs.dialect_kwargs` - flat dictionary form
|
| get_dialect_option(self, dialect: 'Dialect', argument_name: 'str', *, else_: 'Any' = None, deprecated_fallback: 'Optional[str]' = None) -> 'Any'
| Return the value of a dialect-specific option, or *else_* if
| this dialect does not register the given argument.
|
| This is useful for DDL compilers that may be inherited by
| third-party dialects whose ``construct_arguments`` do not
| include the same set of keys as the parent dialect.
|
| :param dialect: The dialect for which to retrieve the option.
| :param argument_name: The name of the argument to retrieve.
| :param else\_: The value to return if the argument is not present.
| :param deprecated_fallback: Optional dialect name to fall back to
| if the argument is not present for the current dialect. If the
| argument is present for the fallback dialect but not the current
| dialect, a deprecation warning will be emitted.
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.base.DialectKWArgs:
|
| argument_for(dialect_name: 'str', argument_name: 'str', default: 'Any') -> 'None'
| Add a new kind of dialect-specific keyword argument for this class.
|
| E.g.::
|
| Index.argument_for("mydialect", "length", None)
|
| some_index = Index("a", "b", mydialect_length=5)
|
| The :meth:`.DialectKWArgs.argument_for` method is a per-argument
| way adding extra arguments to the
| :attr:`.DefaultDialect.construct_arguments` dictionary. This
| dictionary provides a list of argument names accepted by various
| schema-level constructs on behalf of a dialect.
|
| New dialects should typically specify this dictionary all at once as a
| data member of the dialect class. The use case for ad-hoc addition of
| argument names is typically for end-user code that is also using
| a custom compilation scheme which consumes the additional arguments.
|
| :param dialect_name: name of a dialect. The dialect must be
| locatable, else a :class:`.NoSuchModuleError` is raised. The
| dialect must also include an existing
| :attr:`.DefaultDialect.construct_arguments` collection, indicating
| that it participates in the keyword-argument validation and default
| system, else :class:`.ArgumentError` is raised. If the dialect does
| not include this collection, then any keyword argument can be
| specified on behalf of this dialect already. All dialects packaged
| within SQLAlchemy include this collection, however for third party
| dialects, support may vary.
|
| :param argument_name: name of the parameter.
|
| :param default: default value of the parameter.
|
| ----------------------------------------------------------------------
| Readonly properties inherited from sqlalchemy.sql.base.DialectKWArgs:
|
| dialect_kwargs
| A collection of keyword arguments specified as dialect-specific
| options to this construct.
|
| The arguments are present here in their original ``<dialect>_<kwarg>``
| format. Only arguments that were actually passed are included;
| unlike the :attr:`.DialectKWArgs.dialect_options` collection, which
| contains all options known by this dialect including defaults.
|
| The collection is also writable; keys are accepted of the
| form ``<dialect>_<kwarg>`` where the value will be assembled
| into the list of options.
|
| .. seealso::
|
| :attr:`.DialectKWArgs.dialect_options` - nested dictionary form
|
| kwargs
| A synonym for :attr:`.DialectKWArgs.dialect_kwargs`.
|
| ----------------------------------------------------------------------
| Methods inherited from SchemaItem:
|
| info(...)
| Info dictionary associated with the object, allowing user-defined
| data to be associated with this :class:`.SchemaItem`.
|
| The dictionary is automatically generated when first accessed.
| It can also be specified in the constructor of some objects,
| such as :class:`_schema.Table` and :class:`_schema.Column`.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from SchemaItem:
|
| create_drop_stringify_dialect = 'default'
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.base.SchemaEventTarget:
|
| dispatch = <sqlalchemy.event.base.DDLEventsDispatch object>
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.selectable.TableClause:
|
| delete(self) -> 'Delete'
| Generate a :func:`_expression.delete` construct against this
| :class:`_expression.TableClause`.
|
| E.g.::
|
| table.delete().where(table.c.id == 7)
|
| See :func:`_expression.delete` for argument and usage information.
|
| description(...)
|
| insert(self) -> 'util.preloaded.sql_dml.Insert'
| Generate an :class:`_sql.Insert` construct against this
| :class:`_expression.TableClause`.
|
| E.g.::
|
| table.insert().values(name="foo")
|
| See :func:`_expression.insert` for argument and usage information.
|
| update(self) -> 'Update'
| Generate an :func:`_expression.update` construct against this
| :class:`_expression.TableClause`.
|
| E.g.::
|
| table.update().where(table.c.id == 7).values(name="foo")
|
| See :func:`_expression.update` for argument and usage information.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.selectable.TableClause:
|
| implicit_returning = False
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.base.Immutable:
|
| params(self, *optionaldict: 'Any', **kwargs: 'Any') -> 'NoReturn'
|
| unique_params(self, *optionaldict: 'Any', **kwargs: 'Any') -> 'NoReturn'
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.selectable.NamedFromClause:
|
| table_valued(self) -> 'TableValuedColumn[Any]'
| Return a :class:`_sql.TableValuedColumn` object for this
| :class:`_expression.FromClause`.
|
| A :class:`_sql.TableValuedColumn` is a :class:`_sql.ColumnElement` that
| represents a complete row in a table. Support for this construct is
| backend dependent, and is supported in various forms by backends
| such as PostgreSQL, Oracle Database and SQL Server.
|
| E.g.:
|
| .. sourcecode:: pycon+sql
|
| >>> from sqlalchemy import select, column, func, table
| >>> a = table("a", column("id"), column("x"), column("y"))
| >>> stmt = select(func.row_to_json(a.table_valued()))
| >>> print(stmt)
| {printsql}SELECT row_to_json(a) AS row_to_json_1
| FROM a
|
| .. versionadded:: 1.4.0b2
|
| .. seealso::
|
| :ref:`tutorial_functions` - in the :ref:`unified_tutorial`
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.selectable.NamedFromClause:
|
| named_with_column = True
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.selectable.FromClause:
|
| alias(self, name: 'Optional[str]' = None, flat: 'bool' = False) -> 'NamedFromClause'
| 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`
|
| c(...)
| A synonym for :attr:`.FromClause.columns`
|
| :return: a :class:`.ColumnCollection`
|
| columns(...)
| 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.
|
| entity_namespace(...)
| 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.
|
| exported_columns(...)
| A :class:`_expression.ColumnCollection`
| that represents the "exported"
| columns of this :class:`_expression.Selectable`.
|
| 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`
|
| foreign_keys(...)
| Return the collection of :class:`_schema.ForeignKey` marker objects
| which this FromClause references.
|
| Each :class:`_schema.ForeignKey` is a member of a
| :class:`_schema.Table`-wide
| :class:`_schema.ForeignKeyConstraint`.
|
| .. seealso::
|
| :attr:`_schema.Table.foreign_key_constraints`
|
| 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.
|
| 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
|
| 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`
|
| primary_key(...)
| 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.
|
| select(self) -> 'Select[Any]'
| 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.
|
| 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
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.selectable.FromClause:
|
| is_selectable = True
|
| schema = None
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.AllowsLambdaRole:
|
| allows_lambda = True
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.UsesInspection:
|
| uses_inspection = True
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.selectable.Selectable:
|
| 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.
|
| 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.
|
| 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`.
|
| .. deprecated:: 1.4 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.
|
| ----------------------------------------------------------------------
| Readonly properties inherited from sqlalchemy.sql.selectable.ReturnsRows:
|
| selectable
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.elements.ClauseElement:
|
| __bool__(self)
|
| __getstate__(self)
| Helper for pickle.
|
| __invert__(self)
|
| compare(self, other: 'ClauseElement', **kw: 'Any') -> 'bool'
| Compare this :class:`_expression.ClauseElement` to
| the given :class:`_expression.ClauseElement`.
|
| Subclasses should override the default behavior, which is a
| straight identity comparison.
|
| \**kw are arguments consumed by subclass ``compare()`` methods and
| may be used to modify the criteria for comparison
| (see :class:`_expression.ColumnElement`).
|
| self_group(self, against: 'Optional[OperatorType]' = None) -> 'ClauseElement'
| 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.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.elements.ClauseElement:
|
| is_clause_element = True
|
| is_dml = False
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.cache_key.HasCacheKey:
|
| inherit_cache = None
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_instancemethod(fn: '_F') -> '_F'
| Decorate a method memoize its return value.
|
| :meta private:
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_attribute = <class 'sqlalchemy.util.langhelpers.HasMemoized.m...
| A read-only @property that is only evaluated once.
|
| :meta private:
|
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.visitors.HasTraverseInternals:
|
| get_children(self, *, omit_attrs: 'Tuple[str, ...]' = (), **kw: 'Any') -> 'Iterable[HasTraverseInternals]'
| Return immediate child :class:`.visitors.HasTraverseInternals`
| elements of this :class:`.visitors.HasTraverseInternals`.
|
| This is used for visit traversal.
|
| \**kw may contain flags that change the collection that is
| returned, for example to return a subset of items in order to
| cut down on larger traversals, or to return child items from a
| different context (such as schema-level collections instead of
| clause-level).
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.elements.CompilerElement:
|
| compile(self, bind: 'Optional[_HasDialect]' = None, dialect: 'Optional[Dialect]' = None, **kw: 'Any') -> 'Compiled'
| Compile this SQL expression.
|
| The return value is a :class:`~.Compiled` object.
| Calling ``str()`` or ``unicode()`` on the returned value will yield a
| string representation of the result. The
| :class:`~.Compiled` object also can return a
| dictionary of bind parameter names and values
| using the ``params`` accessor.
|
| :param bind: An :class:`.Connection` or :class:`.Engine` which
| can provide a :class:`.Dialect` in order to generate a
| :class:`.Compiled` object. If the ``bind`` and
| ``dialect`` parameters are both omitted, a default SQL compiler
| is used.
|
| :param column_keys: Used for INSERT and UPDATE statements, a list of
| column names which should be present in the VALUES clause of the
| compiled statement. If ``None``, all columns from the target table
| object are rendered.
|
| :param dialect: A :class:`.Dialect` instance which can generate
| a :class:`.Compiled` object. This argument takes precedence over
| the ``bind`` argument.
|
| :param compile_kwargs: optional dictionary of additional parameters
| that will be passed through to the compiler within all "visit"
| methods. This allows any custom flag to be passed through to
| a custom compilation construct, for example. It is also used
| for the case of passing the ``literal_binds`` flag through::
|
| from sqlalchemy.sql import table, column, select
|
| t = table("t", column("x"))
|
| s = select(t).where(t.c.x == 5)
|
| print(s.compile(compile_kwargs={"literal_binds": True}))
|
| .. seealso::
|
| :ref:`faq_sql_expression_string`
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.elements.CompilerElement:
|
| stringify_dialect = 'default'
|
| supports_execution = False
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.visitors.Visitable:
|
| __class_getitem__(key: 'Any') -> 'Any'
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__() -> 'None'
| This method is called when a class is subclassed.
|
| The default implementation does nothing. It may be
| overridden to extend subclasses.
sqlalchemy.TableClause
Python Library Documentation: class TableClause in module sqlalchemy.sql.selectable
class TableClause(sqlalchemy.sql.roles.DMLTableRole, sqlalchemy.sql.base.Immutable, NamedFromClause)
| TableClause(name: 'str', *columns: 'ColumnClause[Any]', **kw: 'Any')
|
| Represents a minimal "table" construct.
|
| This is a lightweight table object that has only a name, a
| collection of columns, which are typically produced
| by the :func:`_expression.column` function, and a schema::
|
| from sqlalchemy import table, column
|
| user = table(
| "user",
| column("id"),
| column("name"),
| column("description"),
| )
|
| The :class:`_expression.TableClause` construct serves as the base for
| the more commonly used :class:`_schema.Table` object, providing
| the usual set of :class:`_expression.FromClause` services including
| the ``.c.`` collection and statement generation methods.
|
| It does **not** provide all the additional schema-level services
| of :class:`_schema.Table`, including constraints, references to other
| tables, or support for :class:`_schema.MetaData`-level services.
| It's useful
| on its own as an ad-hoc construct used to generate quick SQL
| statements when a more fully fledged :class:`_schema.Table`
| is not on hand.
|
| Method resolution order:
| TableClause
| sqlalchemy.sql.roles.DMLTableRole
| sqlalchemy.sql.base.Immutable
| NamedFromClause
| FromClause
| sqlalchemy.sql.roles.AnonymizedFromClauseRole
| sqlalchemy.sql.roles.StrictFromClauseRole
| sqlalchemy.sql.roles.FromClauseRole
| sqlalchemy.sql.roles.ColumnsClauseRole
| sqlalchemy.sql.roles.JoinTargetRole
| sqlalchemy.sql.roles.AllowsLambdaRole
| sqlalchemy.sql.roles.UsesInspection
| sqlalchemy.sql.roles.ColumnListRole
| sqlalchemy.sql.roles.StructuralRole
| Selectable
| ReturnsRows
| sqlalchemy.sql.roles.ReturnsRowsRole
| sqlalchemy.sql.roles.SQLRole
| sqlalchemy.sql.elements.DQLDMLClauseElement
| sqlalchemy.sql.elements.ClauseElement
| sqlalchemy.sql.annotation.SupportsWrappingAnnotations
| sqlalchemy.sql.annotation.SupportsAnnotations
| sqlalchemy.sql.cache_key.MemoizedHasCacheKey
| sqlalchemy.sql.cache_key.HasCacheKey
| sqlalchemy.util.langhelpers.HasMemoized
| sqlalchemy.sql.traversals.HasCopyInternals
| sqlalchemy.sql.visitors.ExternallyTraversible
| sqlalchemy.sql.visitors.HasTraverseInternals
| sqlalchemy.sql.elements.CompilerElement
| sqlalchemy.sql.visitors.Visitable
| builtins.object
|
| Methods defined here:
|
| __init__(self, name: 'str', *columns: 'ColumnClause[Any]', **kw: 'Any')
| Initialize self. See help(type(self)) for accurate signature.
|
| __str__(self) -> 'str'
| Return str(self).
|
| append_column(self, c: 'ColumnClause[Any]') -> 'None'
|
| delete(self) -> 'Delete'
| Generate a :func:`_expression.delete` construct against this
| :class:`_expression.TableClause`.
|
| E.g.::
|
| table.delete().where(table.c.id == 7)
|
| See :func:`_expression.delete` for argument and usage information.
|
| description(...)
|
| insert(self) -> 'util.preloaded.sql_dml.Insert'
| Generate an :class:`_sql.Insert` construct against this
| :class:`_expression.TableClause`.
|
| E.g.::
|
| table.insert().values(name="foo")
|
| See :func:`_expression.insert` for argument and usage information.
|
| update(self) -> 'Update'
| Generate an :func:`_expression.update` construct against this
| :class:`_expression.TableClause`.
|
| E.g.::
|
| table.update().where(table.c.id == 7).values(name="foo")
|
| See :func:`_expression.update` for argument and usage information.
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'_traverse_internals': '_TraverseInternalsType', 'f...
|
| __visit_name__ = 'table'
|
| implicit_returning = False
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.base.Immutable:
|
| params(self, *optionaldict: 'Any', **kwargs: 'Any') -> 'NoReturn'
|
| unique_params(self, *optionaldict: 'Any', **kwargs: 'Any') -> 'NoReturn'
|
| ----------------------------------------------------------------------
| Methods inherited from NamedFromClause:
|
| table_valued(self) -> 'TableValuedColumn[Any]'
| Return a :class:`_sql.TableValuedColumn` object for this
| :class:`_expression.FromClause`.
|
| A :class:`_sql.TableValuedColumn` is a :class:`_sql.ColumnElement` that
| represents a complete row in a table. Support for this construct is
| backend dependent, and is supported in various forms by backends
| such as PostgreSQL, Oracle Database and SQL Server.
|
| E.g.:
|
| .. sourcecode:: pycon+sql
|
| >>> from sqlalchemy import select, column, func, table
| >>> a = table("a", column("id"), column("x"), column("y"))
| >>> stmt = select(func.row_to_json(a.table_valued()))
| >>> print(stmt)
| {printsql}SELECT row_to_json(a) AS row_to_json_1
| FROM a
|
| .. versionadded:: 1.4.0b2
|
| .. seealso::
|
| :ref:`tutorial_functions` - in the :ref:`unified_tutorial`
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from NamedFromClause:
|
| named_with_column = True
|
| ----------------------------------------------------------------------
| Methods inherited from FromClause:
|
| alias(self, name: 'Optional[str]' = None, flat: 'bool' = False) -> 'NamedFromClause'
| 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`
|
| c(...)
| A synonym for :attr:`.FromClause.columns`
|
| :return: a :class:`.ColumnCollection`
|
| columns(...)
| 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.
|
| entity_namespace(...)
| 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.
|
| exported_columns(...)
| A :class:`_expression.ColumnCollection`
| that represents the "exported"
| columns of this :class:`_expression.Selectable`.
|
| 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`
|
| foreign_keys(...)
| Return the collection of :class:`_schema.ForeignKey` marker objects
| which this FromClause references.
|
| Each :class:`_schema.ForeignKey` is a member of a
| :class:`_schema.Table`-wide
| :class:`_schema.ForeignKeyConstraint`.
|
| .. seealso::
|
| :attr:`_schema.Table.foreign_key_constraints`
|
| 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.
|
| 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
|
| 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`
|
| primary_key(...)
| 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.
|
| select(self) -> 'Select[Any]'
| 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.
|
| 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
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from FromClause:
|
| is_selectable = True
|
| schema = None
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.AllowsLambdaRole:
|
| allows_lambda = True
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.UsesInspection:
|
| uses_inspection = True
|
| ----------------------------------------------------------------------
| Methods inherited from Selectable:
|
| 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.
|
| 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.
|
| 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`.
|
| .. deprecated:: 1.4 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.
|
| ----------------------------------------------------------------------
| Readonly properties inherited from ReturnsRows:
|
| selectable
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.elements.ClauseElement:
|
| __bool__(self)
|
| __getstate__(self)
| Helper for pickle.
|
| __invert__(self)
|
| __repr__(self)
| Return repr(self).
|
| compare(self, other: 'ClauseElement', **kw: 'Any') -> 'bool'
| Compare this :class:`_expression.ClauseElement` to
| the given :class:`_expression.ClauseElement`.
|
| Subclasses should override the default behavior, which is a
| straight identity comparison.
|
| \**kw are arguments consumed by subclass ``compare()`` methods and
| may be used to modify the criteria for comparison
| (see :class:`_expression.ColumnElement`).
|
| self_group(self, against: 'Optional[OperatorType]' = None) -> 'ClauseElement'
| 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.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.elements.ClauseElement:
|
| is_clause_element = True
|
| is_dml = False
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.cache_key.HasCacheKey:
|
| inherit_cache = None
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_instancemethod(fn: '_F') -> '_F'
| Decorate a method memoize its return value.
|
| :meta private:
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_attribute = <class 'sqlalchemy.util.langhelpers.HasMemoized.m...
| A read-only @property that is only evaluated once.
|
| :meta private:
|
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.visitors.HasTraverseInternals:
|
| get_children(self, *, omit_attrs: 'Tuple[str, ...]' = (), **kw: 'Any') -> 'Iterable[HasTraverseInternals]'
| Return immediate child :class:`.visitors.HasTraverseInternals`
| elements of this :class:`.visitors.HasTraverseInternals`.
|
| This is used for visit traversal.
|
| \**kw may contain flags that change the collection that is
| returned, for example to return a subset of items in order to
| cut down on larger traversals, or to return child items from a
| different context (such as schema-level collections instead of
| clause-level).
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.elements.CompilerElement:
|
| compile(self, bind: 'Optional[_HasDialect]' = None, dialect: 'Optional[Dialect]' = None, **kw: 'Any') -> 'Compiled'
| Compile this SQL expression.
|
| The return value is a :class:`~.Compiled` object.
| Calling ``str()`` or ``unicode()`` on the returned value will yield a
| string representation of the result. The
| :class:`~.Compiled` object also can return a
| dictionary of bind parameter names and values
| using the ``params`` accessor.
|
| :param bind: An :class:`.Connection` or :class:`.Engine` which
| can provide a :class:`.Dialect` in order to generate a
| :class:`.Compiled` object. If the ``bind`` and
| ``dialect`` parameters are both omitted, a default SQL compiler
| is used.
|
| :param column_keys: Used for INSERT and UPDATE statements, a list of
| column names which should be present in the VALUES clause of the
| compiled statement. If ``None``, all columns from the target table
| object are rendered.
|
| :param dialect: A :class:`.Dialect` instance which can generate
| a :class:`.Compiled` object. This argument takes precedence over
| the ``bind`` argument.
|
| :param compile_kwargs: optional dictionary of additional parameters
| that will be passed through to the compiler within all "visit"
| methods. This allows any custom flag to be passed through to
| a custom compilation construct, for example. It is also used
| for the case of passing the ``literal_binds`` flag through::
|
| from sqlalchemy.sql import table, column, select
|
| t = table("t", column("x"))
|
| s = select(t).where(t.c.x == 5)
|
| print(s.compile(compile_kwargs={"literal_binds": True}))
|
| .. seealso::
|
| :ref:`faq_sql_expression_string`
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.elements.CompilerElement:
|
| stringify_dialect = 'default'
|
| supports_execution = False
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.visitors.Visitable:
|
| __class_getitem__(key: 'Any') -> 'Any'
|
| __init_subclass__() -> 'None'
| This method is called when a class is subclassed.
|
| The default implementation does nothing. It may be
| overridden to extend subclasses.
sqlalchemy.TableSample
Python Library Documentation: class TableSample in module sqlalchemy.sql.selectable
class TableSample(FromClauseAlias)
| TableSample(*arg: 'Any', **kw: 'Any')
|
| Represent a TABLESAMPLE clause.
|
| This object is constructed from the :func:`_expression.tablesample` module
| level function as well as the :meth:`_expression.FromClause.tablesample`
| method
| available on all :class:`_expression.FromClause` subclasses.
|
| .. seealso::
|
| :func:`_expression.tablesample`
|
| Method resolution order:
| TableSample
| FromClauseAlias
| AliasedReturnsRows
| NoInit
| NamedFromClause
| FromClause
| sqlalchemy.sql.roles.AnonymizedFromClauseRole
| sqlalchemy.sql.roles.StrictFromClauseRole
| sqlalchemy.sql.roles.FromClauseRole
| sqlalchemy.sql.roles.ColumnsClauseRole
| sqlalchemy.sql.roles.JoinTargetRole
| sqlalchemy.sql.roles.AllowsLambdaRole
| sqlalchemy.sql.roles.UsesInspection
| sqlalchemy.sql.roles.ColumnListRole
| sqlalchemy.sql.roles.StructuralRole
| Selectable
| ReturnsRows
| sqlalchemy.sql.roles.ReturnsRowsRole
| sqlalchemy.sql.roles.SQLRole
| sqlalchemy.sql.elements.DQLDMLClauseElement
| sqlalchemy.sql.elements.ClauseElement
| sqlalchemy.sql.annotation.SupportsWrappingAnnotations
| sqlalchemy.sql.annotation.SupportsAnnotations
| sqlalchemy.sql.cache_key.MemoizedHasCacheKey
| sqlalchemy.sql.cache_key.HasCacheKey
| sqlalchemy.util.langhelpers.HasMemoized
| sqlalchemy.sql.traversals.HasCopyInternals
| sqlalchemy.sql.visitors.ExternallyTraversible
| sqlalchemy.sql.visitors.HasTraverseInternals
| sqlalchemy.sql.elements.CompilerElement
| sqlalchemy.sql.visitors.Visitable
| builtins.object
|
| Data and other attributes defined here:
|
| __annotations__ = {'_traverse_internals': '_TraverseInternalsType'}
|
| __visit_name__ = 'tablesample'
|
| ----------------------------------------------------------------------
| Methods inherited from FromClauseAlias:
|
| description(...)
|
| ----------------------------------------------------------------------
| Methods inherited from AliasedReturnsRows:
|
| implicit_returning(...)
|
| 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.
|
| ----------------------------------------------------------------------
| Readonly properties inherited from AliasedReturnsRows:
|
| original
| Legacy for dialects that are referring to Alias.original.
|
| ----------------------------------------------------------------------
| Methods inherited from NoInit:
|
| __init__(self, *arg: 'Any', **kw: 'Any')
| Initialize self. See help(type(self)) for accurate signature.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from NoInit:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Methods inherited from NamedFromClause:
|
| table_valued(self) -> 'TableValuedColumn[Any]'
| Return a :class:`_sql.TableValuedColumn` object for this
| :class:`_expression.FromClause`.
|
| A :class:`_sql.TableValuedColumn` is a :class:`_sql.ColumnElement` that
| represents a complete row in a table. Support for this construct is
| backend dependent, and is supported in various forms by backends
| such as PostgreSQL, Oracle Database and SQL Server.
|
| E.g.:
|
| .. sourcecode:: pycon+sql
|
| >>> from sqlalchemy import select, column, func, table
| >>> a = table("a", column("id"), column("x"), column("y"))
| >>> stmt = select(func.row_to_json(a.table_valued()))
| >>> print(stmt)
| {printsql}SELECT row_to_json(a) AS row_to_json_1
| FROM a
|
| .. versionadded:: 1.4.0b2
|
| .. seealso::
|
| :ref:`tutorial_functions` - in the :ref:`unified_tutorial`
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from NamedFromClause:
|
| named_with_column = True
|
| ----------------------------------------------------------------------
| Methods inherited from FromClause:
|
| alias(self, name: 'Optional[str]' = None, flat: 'bool' = False) -> 'NamedFromClause'
| 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`
|
| c(...)
| A synonym for :attr:`.FromClause.columns`
|
| :return: a :class:`.ColumnCollection`
|
| columns(...)
| 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.
|
| entity_namespace(...)
| 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.
|
| exported_columns(...)
| A :class:`_expression.ColumnCollection`
| that represents the "exported"
| columns of this :class:`_expression.Selectable`.
|
| 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`
|
| foreign_keys(...)
| Return the collection of :class:`_schema.ForeignKey` marker objects
| which this FromClause references.
|
| Each :class:`_schema.ForeignKey` is a member of a
| :class:`_schema.Table`-wide
| :class:`_schema.ForeignKeyConstraint`.
|
| .. seealso::
|
| :attr:`_schema.Table.foreign_key_constraints`
|
| 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
|
| 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`
|
| primary_key(...)
| 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.
|
| select(self) -> 'Select[Any]'
| 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.
|
| 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
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from FromClause:
|
| is_selectable = True
|
| schema = None
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.AllowsLambdaRole:
|
| allows_lambda = True
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.UsesInspection:
|
| uses_inspection = True
|
| ----------------------------------------------------------------------
| Methods inherited from Selectable:
|
| 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.
|
| 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.
|
| 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`.
|
| .. deprecated:: 1.4 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.
|
| ----------------------------------------------------------------------
| Readonly properties inherited from ReturnsRows:
|
| selectable
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.elements.ClauseElement:
|
| __bool__(self)
|
| __getstate__(self)
| Helper for pickle.
|
| __invert__(self)
|
| __repr__(self)
| Return repr(self).
|
| compare(self, other: 'ClauseElement', **kw: 'Any') -> 'bool'
| Compare this :class:`_expression.ClauseElement` to
| the given :class:`_expression.ClauseElement`.
|
| Subclasses should override the default behavior, which is a
| straight identity comparison.
|
| \**kw are arguments consumed by subclass ``compare()`` methods and
| may be used to modify the criteria for comparison
| (see :class:`_expression.ColumnElement`).
|
| params(self, _ClauseElement__optionaldict: 'Optional[Mapping[str, Any]]' = None, **kwargs: 'Any') -> 'Self'
| Return a copy with :func:`_expression.bindparam` elements
| replaced.
|
| Returns a copy of this ClauseElement with
| :func:`_expression.bindparam`
| elements replaced with values taken from the given dictionary::
|
| >>> clause = column("x") + bindparam("foo")
| >>> print(clause.compile().params)
| {'foo':None}
| >>> print(clause.params({"foo": 7}).compile().params)
| {'foo':7}
|
| self_group(self, against: 'Optional[OperatorType]' = None) -> 'ClauseElement'
| 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.
|
| unique_params(self, _ClauseElement__optionaldict: 'Optional[Dict[str, Any]]' = None, **kwargs: 'Any') -> 'Self'
| Return a copy with :func:`_expression.bindparam` elements
| replaced.
|
| Same functionality as :meth:`_expression.ClauseElement.params`,
| except adds `unique=True`
| to affected bind parameters so that multiple statements can be
| used.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.elements.ClauseElement:
|
| is_clause_element = True
|
| is_dml = False
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.cache_key.HasCacheKey:
|
| inherit_cache = None
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_instancemethod(fn: '_F') -> '_F'
| Decorate a method memoize its return value.
|
| :meta private:
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_attribute = <class 'sqlalchemy.util.langhelpers.HasMemoized.m...
| A read-only @property that is only evaluated once.
|
| :meta private:
|
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.visitors.HasTraverseInternals:
|
| get_children(self, *, omit_attrs: 'Tuple[str, ...]' = (), **kw: 'Any') -> 'Iterable[HasTraverseInternals]'
| Return immediate child :class:`.visitors.HasTraverseInternals`
| elements of this :class:`.visitors.HasTraverseInternals`.
|
| This is used for visit traversal.
|
| \**kw may contain flags that change the collection that is
| returned, for example to return a subset of items in order to
| cut down on larger traversals, or to return child items from a
| different context (such as schema-level collections instead of
| clause-level).
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.elements.CompilerElement:
|
| __str__(self) -> 'str'
| Return str(self).
|
| compile(self, bind: 'Optional[_HasDialect]' = None, dialect: 'Optional[Dialect]' = None, **kw: 'Any') -> 'Compiled'
| Compile this SQL expression.
|
| The return value is a :class:`~.Compiled` object.
| Calling ``str()`` or ``unicode()`` on the returned value will yield a
| string representation of the result. The
| :class:`~.Compiled` object also can return a
| dictionary of bind parameter names and values
| using the ``params`` accessor.
|
| :param bind: An :class:`.Connection` or :class:`.Engine` which
| can provide a :class:`.Dialect` in order to generate a
| :class:`.Compiled` object. If the ``bind`` and
| ``dialect`` parameters are both omitted, a default SQL compiler
| is used.
|
| :param column_keys: Used for INSERT and UPDATE statements, a list of
| column names which should be present in the VALUES clause of the
| compiled statement. If ``None``, all columns from the target table
| object are rendered.
|
| :param dialect: A :class:`.Dialect` instance which can generate
| a :class:`.Compiled` object. This argument takes precedence over
| the ``bind`` argument.
|
| :param compile_kwargs: optional dictionary of additional parameters
| that will be passed through to the compiler within all "visit"
| methods. This allows any custom flag to be passed through to
| a custom compilation construct, for example. It is also used
| for the case of passing the ``literal_binds`` flag through::
|
| from sqlalchemy.sql import table, column, select
|
| t = table("t", column("x"))
|
| s = select(t).where(t.c.x == 5)
|
| print(s.compile(compile_kwargs={"literal_binds": True}))
|
| .. seealso::
|
| :ref:`faq_sql_expression_string`
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.elements.CompilerElement:
|
| stringify_dialect = 'default'
|
| supports_execution = False
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.visitors.Visitable:
|
| __class_getitem__(key: 'Any') -> 'Any'
|
| __init_subclass__() -> 'None'
| This method is called when a class is subclassed.
|
| The default implementation does nothing. It may be
| overridden to extend subclasses.
sqlalchemy.TableValuedAlias
Python Library Documentation: class TableValuedAlias in module sqlalchemy.sql.selectable
class TableValuedAlias(LateralFromClause, Alias)
| TableValuedAlias(*arg: 'Any', **kw: 'Any')
|
| An alias against a "table valued" SQL function.
|
| This construct provides for a SQL function that returns columns
| to be used in the FROM clause of a SELECT statement. The
| object is generated using the :meth:`_functions.FunctionElement.table_valued`
| method, e.g.:
|
| .. sourcecode:: pycon+sql
|
| >>> from sqlalchemy import select, func
| >>> fn = func.json_array_elements_text('["one", "two", "three"]').table_valued(
| ... "value"
| ... )
| >>> print(select(fn.c.value))
| {printsql}SELECT anon_1.value
| FROM json_array_elements_text(:json_array_elements_text_1) AS anon_1
|
| .. versionadded:: 1.4.0b2
|
| .. seealso::
|
| :ref:`tutorial_functions_table_valued` - in the :ref:`unified_tutorial`
|
| Method resolution order:
| TableValuedAlias
| LateralFromClause
| Alias
| sqlalchemy.sql.roles.DMLTableRole
| FromClauseAlias
| AliasedReturnsRows
| NoInit
| NamedFromClause
| FromClause
| sqlalchemy.sql.roles.AnonymizedFromClauseRole
| sqlalchemy.sql.roles.StrictFromClauseRole
| sqlalchemy.sql.roles.FromClauseRole
| sqlalchemy.sql.roles.ColumnsClauseRole
| sqlalchemy.sql.roles.JoinTargetRole
| sqlalchemy.sql.roles.AllowsLambdaRole
| sqlalchemy.sql.roles.UsesInspection
| sqlalchemy.sql.roles.ColumnListRole
| sqlalchemy.sql.roles.StructuralRole
| Selectable
| ReturnsRows
| sqlalchemy.sql.roles.ReturnsRowsRole
| sqlalchemy.sql.roles.SQLRole
| sqlalchemy.sql.elements.DQLDMLClauseElement
| sqlalchemy.sql.elements.ClauseElement
| sqlalchemy.sql.annotation.SupportsWrappingAnnotations
| sqlalchemy.sql.annotation.SupportsAnnotations
| sqlalchemy.sql.cache_key.MemoizedHasCacheKey
| sqlalchemy.sql.cache_key.HasCacheKey
| sqlalchemy.util.langhelpers.HasMemoized
| sqlalchemy.sql.traversals.HasCopyInternals
| sqlalchemy.sql.visitors.ExternallyTraversible
| sqlalchemy.sql.visitors.HasTraverseInternals
| sqlalchemy.sql.elements.CompilerElement
| sqlalchemy.sql.visitors.Visitable
| builtins.object
|
| Methods defined here:
|
| alias(self, name: 'Optional[str]' = None, flat: 'bool' = False) -> 'TableValuedAlias'
| Return a new alias of this :class:`_sql.TableValuedAlias`.
|
| This creates a distinct FROM object that will be distinguished
| from the original one when used in a SQL statement.
|
| column(...)
| Return a column expression representing this
| :class:`_sql.TableValuedAlias`.
|
| This accessor is used to implement the
| :meth:`_functions.FunctionElement.column_valued` method. See that
| method for further details.
|
| E.g.:
|
| .. sourcecode:: pycon+sql
|
| >>> print(select(func.some_func().table_valued("value").column))
| {printsql}SELECT anon_1 FROM some_func() AS anon_1
|
| .. seealso::
|
| :meth:`_functions.FunctionElement.column_valued`
|
| lateral(self, name: 'Optional[str]' = None) -> 'LateralFromClause'
| Return a new :class:`_sql.TableValuedAlias` with the lateral flag
| set, so that it renders as LATERAL.
|
| .. seealso::
|
| :func:`_expression.lateral`
|
| render_derived(self, name: 'Optional[str]' = None, with_types: 'bool' = False) -> 'TableValuedAlias'
| Apply "render derived" to this :class:`_sql.TableValuedAlias`.
|
| This has the effect of the individual column names listed out
| after the alias name in the "AS" sequence, e.g.:
|
| .. sourcecode:: pycon+sql
|
| >>> print(
| ... select(
| ... func.unnest(array(["one", "two", "three"]))
| ... .table_valued("x", with_ordinality="o")
| ... .render_derived()
| ... )
| ... )
| {printsql}SELECT anon_1.x, anon_1.o
| FROM unnest(ARRAY[%(param_1)s, %(param_2)s, %(param_3)s]) WITH ORDINALITY AS anon_1(x, o)
|
| The ``with_types`` keyword will render column types inline within
| the alias expression (this syntax currently applies to the
| PostgreSQL database):
|
| .. sourcecode:: pycon+sql
|
| >>> print(
| ... select(
| ... func.json_to_recordset('[{"a":1,"b":"foo"},{"a":"2","c":"bar"}]')
| ... .table_valued(column("a", Integer), column("b", String))
| ... .render_derived(with_types=True)
| ... )
| ... )
| {printsql}SELECT anon_1.a, anon_1.b FROM json_to_recordset(:json_to_recordset_1)
| AS anon_1(a INTEGER, b VARCHAR)
|
| :param name: optional string name that will be applied to the alias
| generated. If left as None, a unique anonymizing name will be used.
|
| :param with_types: if True, the derived columns will include the
| datatype specification with each column. This is a special syntax
| currently known to be required by PostgreSQL for some SQL functions.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'_traverse_internals': '_TraverseInternalsType'}
|
| __visit_name__ = 'table_valued_alias'
|
| joins_implicitly = False
|
| ----------------------------------------------------------------------
| Data descriptors inherited from Alias:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from Alias:
|
| inherit_cache = True
|
| ----------------------------------------------------------------------
| Methods inherited from FromClauseAlias:
|
| description(...)
|
| ----------------------------------------------------------------------
| Methods inherited from AliasedReturnsRows:
|
| implicit_returning(...)
|
| 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.
|
| ----------------------------------------------------------------------
| Readonly properties inherited from AliasedReturnsRows:
|
| original
| Legacy for dialects that are referring to Alias.original.
|
| ----------------------------------------------------------------------
| Methods inherited from NoInit:
|
| __init__(self, *arg: 'Any', **kw: 'Any')
| Initialize self. See help(type(self)) for accurate signature.
|
| ----------------------------------------------------------------------
| Methods inherited from NamedFromClause:
|
| table_valued(self) -> 'TableValuedColumn[Any]'
| Return a :class:`_sql.TableValuedColumn` object for this
| :class:`_expression.FromClause`.
|
| A :class:`_sql.TableValuedColumn` is a :class:`_sql.ColumnElement` that
| represents a complete row in a table. Support for this construct is
| backend dependent, and is supported in various forms by backends
| such as PostgreSQL, Oracle Database and SQL Server.
|
| E.g.:
|
| .. sourcecode:: pycon+sql
|
| >>> from sqlalchemy import select, column, func, table
| >>> a = table("a", column("id"), column("x"), column("y"))
| >>> stmt = select(func.row_to_json(a.table_valued()))
| >>> print(stmt)
| {printsql}SELECT row_to_json(a) AS row_to_json_1
| FROM a
|
| .. versionadded:: 1.4.0b2
|
| .. seealso::
|
| :ref:`tutorial_functions` - in the :ref:`unified_tutorial`
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from NamedFromClause:
|
| named_with_column = True
|
| ----------------------------------------------------------------------
| Methods inherited from FromClause:
|
| c(...)
| A synonym for :attr:`.FromClause.columns`
|
| :return: a :class:`.ColumnCollection`
|
| columns(...)
| 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.
|
| entity_namespace(...)
| 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.
|
| exported_columns(...)
| A :class:`_expression.ColumnCollection`
| that represents the "exported"
| columns of this :class:`_expression.Selectable`.
|
| 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`
|
| foreign_keys(...)
| Return the collection of :class:`_schema.ForeignKey` marker objects
| which this FromClause references.
|
| Each :class:`_schema.ForeignKey` is a member of a
| :class:`_schema.Table`-wide
| :class:`_schema.ForeignKeyConstraint`.
|
| .. seealso::
|
| :attr:`_schema.Table.foreign_key_constraints`
|
| 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
|
| 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`
|
| primary_key(...)
| 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.
|
| select(self) -> 'Select[Any]'
| 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.
|
| 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
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from FromClause:
|
| is_selectable = True
|
| schema = None
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.AllowsLambdaRole:
|
| allows_lambda = True
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.UsesInspection:
|
| uses_inspection = True
|
| ----------------------------------------------------------------------
| Methods inherited from Selectable:
|
| 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.
|
| 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`.
|
| .. deprecated:: 1.4 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.
|
| ----------------------------------------------------------------------
| Readonly properties inherited from ReturnsRows:
|
| selectable
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.elements.ClauseElement:
|
| __bool__(self)
|
| __getstate__(self)
| Helper for pickle.
|
| __invert__(self)
|
| __repr__(self)
| Return repr(self).
|
| compare(self, other: 'ClauseElement', **kw: 'Any') -> 'bool'
| Compare this :class:`_expression.ClauseElement` to
| the given :class:`_expression.ClauseElement`.
|
| Subclasses should override the default behavior, which is a
| straight identity comparison.
|
| \**kw are arguments consumed by subclass ``compare()`` methods and
| may be used to modify the criteria for comparison
| (see :class:`_expression.ColumnElement`).
|
| params(self, _ClauseElement__optionaldict: 'Optional[Mapping[str, Any]]' = None, **kwargs: 'Any') -> 'Self'
| Return a copy with :func:`_expression.bindparam` elements
| replaced.
|
| Returns a copy of this ClauseElement with
| :func:`_expression.bindparam`
| elements replaced with values taken from the given dictionary::
|
| >>> clause = column("x") + bindparam("foo")
| >>> print(clause.compile().params)
| {'foo':None}
| >>> print(clause.params({"foo": 7}).compile().params)
| {'foo':7}
|
| self_group(self, against: 'Optional[OperatorType]' = None) -> 'ClauseElement'
| 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.
|
| unique_params(self, _ClauseElement__optionaldict: 'Optional[Dict[str, Any]]' = None, **kwargs: 'Any') -> 'Self'
| Return a copy with :func:`_expression.bindparam` elements
| replaced.
|
| Same functionality as :meth:`_expression.ClauseElement.params`,
| except adds `unique=True`
| to affected bind parameters so that multiple statements can be
| used.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.elements.ClauseElement:
|
| is_clause_element = True
|
| is_dml = False
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_instancemethod(fn: '_F') -> '_F'
| Decorate a method memoize its return value.
|
| :meta private:
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_attribute = <class 'sqlalchemy.util.langhelpers.HasMemoized.m...
| A read-only @property that is only evaluated once.
|
| :meta private:
|
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.visitors.HasTraverseInternals:
|
| get_children(self, *, omit_attrs: 'Tuple[str, ...]' = (), **kw: 'Any') -> 'Iterable[HasTraverseInternals]'
| Return immediate child :class:`.visitors.HasTraverseInternals`
| elements of this :class:`.visitors.HasTraverseInternals`.
|
| This is used for visit traversal.
|
| \**kw may contain flags that change the collection that is
| returned, for example to return a subset of items in order to
| cut down on larger traversals, or to return child items from a
| different context (such as schema-level collections instead of
| clause-level).
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.elements.CompilerElement:
|
| __str__(self) -> 'str'
| Return str(self).
|
| compile(self, bind: 'Optional[_HasDialect]' = None, dialect: 'Optional[Dialect]' = None, **kw: 'Any') -> 'Compiled'
| Compile this SQL expression.
|
| The return value is a :class:`~.Compiled` object.
| Calling ``str()`` or ``unicode()`` on the returned value will yield a
| string representation of the result. The
| :class:`~.Compiled` object also can return a
| dictionary of bind parameter names and values
| using the ``params`` accessor.
|
| :param bind: An :class:`.Connection` or :class:`.Engine` which
| can provide a :class:`.Dialect` in order to generate a
| :class:`.Compiled` object. If the ``bind`` and
| ``dialect`` parameters are both omitted, a default SQL compiler
| is used.
|
| :param column_keys: Used for INSERT and UPDATE statements, a list of
| column names which should be present in the VALUES clause of the
| compiled statement. If ``None``, all columns from the target table
| object are rendered.
|
| :param dialect: A :class:`.Dialect` instance which can generate
| a :class:`.Compiled` object. This argument takes precedence over
| the ``bind`` argument.
|
| :param compile_kwargs: optional dictionary of additional parameters
| that will be passed through to the compiler within all "visit"
| methods. This allows any custom flag to be passed through to
| a custom compilation construct, for example. It is also used
| for the case of passing the ``literal_binds`` flag through::
|
| from sqlalchemy.sql import table, column, select
|
| t = table("t", column("x"))
|
| s = select(t).where(t.c.x == 5)
|
| print(s.compile(compile_kwargs={"literal_binds": True}))
|
| .. seealso::
|
| :ref:`faq_sql_expression_string`
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.elements.CompilerElement:
|
| stringify_dialect = 'default'
|
| supports_execution = False
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.visitors.Visitable:
|
| __class_getitem__(key: 'Any') -> 'Any'
|
| __init_subclass__() -> 'None'
| This method is called when a class is subclassed.
|
| The default implementation does nothing. It may be
| overridden to extend subclasses.
sqlalchemy.Text
Python Library Documentation: class Text in module sqlalchemy.sql.sqltypes
class Text(String)
| Text(length: 'Optional[int]' = None, collation: 'Optional[str]' = None)
|
| A variably sized string type.
|
| In SQL, usually corresponds to CLOB or TEXT. In general, TEXT objects
| do not have a length; while some databases will accept a length
| argument here, it will be rejected by others.
|
| Method resolution order:
| Text
| String
| Concatenable
| sqlalchemy.sql.type_api.TypeEngineMixin
| sqlalchemy.sql.type_api.TypeEngine
| sqlalchemy.sql.visitors.Visitable
| typing.Generic
| builtins.object
|
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| __parameters__ = ()
|
| __visit_name__ = 'text'
|
| ----------------------------------------------------------------------
| Methods inherited from String:
|
| __init__(self, length: 'Optional[int]' = None, collation: 'Optional[str]' = None)
| Create a string-holding type.
|
| :param length: optional, a length for the column for use in
| DDL and CAST expressions. May be safely omitted if no ``CREATE
| TABLE`` will be issued. Certain databases may require a
| ``length`` for use in DDL, and will raise an exception when
| the ``CREATE TABLE`` DDL is issued if a ``VARCHAR``
| with no length is included. Whether the value is
| interpreted as bytes or characters is database specific.
|
| :param collation: Optional, a column-level collation for
| use in DDL and CAST expressions. Renders using the
| COLLATE keyword supported by SQLite, MySQL, and PostgreSQL.
| E.g.:
|
| .. sourcecode:: pycon+sql
|
| >>> from sqlalchemy import cast, select, String
| >>> print(select(cast("some string", String(collation="utf8"))))
| {printsql}SELECT CAST(:param_1 AS VARCHAR COLLATE utf8) AS anon_1
|
| .. note::
|
| In most cases, the :class:`.Unicode` or :class:`.UnicodeText`
| datatypes should be used for a :class:`_schema.Column` that expects
| to store non-ascii data. These datatypes will ensure that the
| correct types are used on the database.
|
| bind_processor(self, dialect: 'Dialect') -> 'Optional[_BindProcessorType[str]]'
| Return a conversion function for processing bind values.
|
| Returns a callable which will receive a bind parameter value
| as the sole positional argument and will return a value to
| send to the DB-API.
|
| If processing is not necessary, the method should return ``None``.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.bind_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.bind_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_bind_param`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
|
| :param dialect: Dialect instance in use.
|
| get_dbapi_type(self, dbapi)
| Return the corresponding type object from the underlying DB-API, if
| any.
|
| This can be useful for calling ``setinputsizes()``, for example.
|
| literal_processor(self, dialect)
| Return a conversion function for processing literal values that are
| to be rendered directly without using binds.
|
| This function is used when the compiler makes use of the
| "literal_binds" flag, typically used in DDL generation as well
| as in certain scenarios where backends don't accept bound parameters.
|
| Returns a callable which will receive a literal Python value
| as the sole positional argument and will return a string representation
| to be rendered in a SQL statement.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.literal_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.literal_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_literal_param`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| result_processor(self, dialect: 'Dialect', coltype: 'object') -> 'Optional[_ResultProcessorType[str]]'
| Return a conversion function for processing result row values.
|
| Returns a callable which will receive a result row column
| value as the sole positional argument and will return a value
| to return to the user.
|
| If processing is not necessary, the method should return ``None``.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.result_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.result_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_result_value`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| :param dialect: Dialect instance in use.
|
| :param coltype: DBAPI coltype argument received in cursor.description.
|
| ----------------------------------------------------------------------
| Readonly properties inherited from String:
|
| python_type
| Return the Python type object expected to be returned
| by instances of this type, if known.
|
| Basically, for those types which enforce a return type,
| or are known across the board to do such for all common
| DBAPIs (like ``int`` for example), will return that type.
|
| If a return type is not defined, raises
| ``NotImplementedError``.
|
| Note that any type also accommodates NULL in SQL which
| means you can also get back ``None`` from any type
| in practice.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from Concatenable:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from Concatenable:
|
| Comparator = <class 'sqlalchemy.sql.sqltypes.Concatenable.Comparator'>
|
| comparator_factory = <class 'sqlalchemy.sql.sqltypes.Concatenable.Comp...
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.type_api.TypeEngine:
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| __str__(self) -> 'str'
| Return str(self).
|
| adapt(self, cls: 'Type[Union[TypeEngine[Any], TypeEngineMixin]]', **kw: 'Any') -> 'TypeEngine[Any]'
| Produce an "adapted" form of this type, given an "impl" class
| to work with.
|
| This method is used internally to associate generic
| types with "implementation" types that are specific to a particular
| dialect.
|
| as_generic(self, allow_nulltype: 'bool' = False) -> 'TypeEngine[_T]'
| Return an instance of the generic type corresponding to this type
| using heuristic rule. The method may be overridden if this
| heuristic rule is not sufficient.
|
| >>> from sqlalchemy.dialects.mysql import INTEGER
| >>> INTEGER(display_width=4).as_generic()
| Integer()
|
| >>> from sqlalchemy.dialects.mysql import NVARCHAR
| >>> NVARCHAR(length=100).as_generic()
| Unicode(length=100)
|
| .. versionadded:: 1.4.0b2
|
|
| .. seealso::
|
| :ref:`metadata_reflection_dbagnostic_types` - describes the
| use of :meth:`_types.TypeEngine.as_generic` in conjunction with
| the :meth:`_sql.DDLEvents.column_reflect` event, which is its
| intended use.
|
| bind_expression(self, bindvalue: 'BindParameter[_T]') -> 'Optional[ColumnElement[_T]]'
| Given a bind value (i.e. a :class:`.BindParameter` instance),
| return a SQL expression in its place.
|
| This is typically a SQL function that wraps the existing bound
| parameter within the statement. It is used for special data types
| that require literals being wrapped in some special database function
| in order to coerce an application-level value into a database-specific
| format. It is the SQL analogue of the
| :meth:`.TypeEngine.bind_processor` method.
|
| This method is called during the **SQL compilation** phase of a
| statement, when rendering a SQL string. It is **not** called
| against specific values.
|
| Note that this method, when implemented, should always return
| the exact same structure, without any conditional logic, as it
| may be used in an executemany() call against an arbitrary number
| of bound parameter sets.
|
| .. note::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.bind_expression`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.bind_expression`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.bind_expression`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| .. seealso::
|
| :ref:`types_sql_value_processing`
|
| coerce_compared_value(self, op: 'Optional[OperatorType]', value: 'Any') -> 'TypeEngine[Any]'
| Suggest a type for a 'coerced' Python value in an expression.
|
| Given an operator and value, gives the type a chance
| to return a type which the value should be coerced into.
|
| The default behavior here is conservative; if the right-hand
| side is already coerced into a SQL type based on its
| Python type, it is usually left alone.
|
| End-user functionality extension here should generally be via
| :class:`.TypeDecorator`, which provides more liberal behavior in that
| it defaults to coercing the other side of the expression into this
| type, thus applying special Python conversions above and beyond those
| needed by the DBAPI to both ides. It also provides the public method
| :meth:`.TypeDecorator.coerce_compared_value` which is intended for
| end-user customization of this behavior.
|
| column_expression(self, colexpr: 'ColumnElement[_T]') -> 'Optional[ColumnElement[_T]]'
| Given a SELECT column expression, return a wrapping SQL expression.
|
| This is typically a SQL function that wraps a column expression
| as rendered in the columns clause of a SELECT statement.
| It is used for special data types that require
| columns to be wrapped in some special database function in order
| to coerce the value before being sent back to the application.
| It is the SQL analogue of the :meth:`.TypeEngine.result_processor`
| method.
|
| .. note:: The :func:`.TypeEngine.column_expression` method is applied
| only to the **outermost columns clause** of a SELECT statement, that
| is, the columns that are to be delivered directly into the returned
| result rows. It does **not** apply to the columns clause inside
| of subqueries. This necessarily avoids double conversions against
| the column and only runs the conversion when ready to be returned
| to the client.
|
| This method is called during the **SQL compilation** phase of a
| statement, when rendering a SQL string. It is **not** called
| against specific values.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.column_expression`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.column_expression`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.column_expression`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
|
| .. seealso::
|
| :ref:`types_sql_value_processing`
|
| compare_values(self, x: 'Any', y: 'Any') -> 'bool'
| Compare two values for equality.
|
| compile(self, dialect: 'Optional[Dialect]' = None) -> 'str'
| Produce a string-compiled form of this :class:`.TypeEngine`.
|
| When called with no arguments, uses a "default" dialect
| to produce a string result.
|
| :param dialect: a :class:`.Dialect` instance.
|
| copy(self, **kw: 'Any') -> 'Self'
|
| copy_value(self, value: 'Any') -> 'Any'
|
| dialect_impl(self, dialect: 'Dialect') -> 'TypeEngine[_T]'
| Return a dialect-specific implementation for this
| :class:`.TypeEngine`.
|
| evaluates_none(self) -> 'Self'
| Return a copy of this type which has the
| :attr:`.should_evaluate_none` flag set to True.
|
| E.g.::
|
| Table(
| "some_table",
| metadata,
| Column(
| String(50).evaluates_none(),
| nullable=True,
| server_default="no value",
| ),
| )
|
| The ORM uses this flag to indicate that a positive value of ``None``
| is passed to the column in an INSERT statement, rather than omitting
| the column from the INSERT statement which has the effect of firing
| off column-level defaults. It also allows for types which have
| special behavior associated with the Python None value to indicate
| that the value doesn't necessarily translate into SQL NULL; a
| prime example of this is a JSON type which may wish to persist the
| JSON value ``'null'``.
|
| In all cases, the actual NULL SQL value can be always be
| persisted in any column by using
| the :obj:`_expression.null` SQL construct in an INSERT statement
| or associated with an ORM-mapped attribute.
|
| .. note::
|
| The "evaluates none" flag does **not** apply to a value
| of ``None`` passed to :paramref:`_schema.Column.default` or
| :paramref:`_schema.Column.server_default`; in these cases,
| ``None``
| still means "no default".
|
| .. seealso::
|
| :ref:`session_forcing_null` - in the ORM documentation
|
| :paramref:`.postgresql.JSON.none_as_null` - PostgreSQL JSON
| interaction with this flag.
|
| :attr:`.TypeEngine.should_evaluate_none` - class-level flag
|
| with_variant(self, type_: '_TypeEngineArgument[Any]', *dialect_names: 'str') -> 'Self'
| Produce a copy of this type object that will utilize the given
| type when applied to the dialect of the given name.
|
| e.g.::
|
| from sqlalchemy.types import String
| from sqlalchemy.dialects import mysql
|
| string_type = String()
|
| string_type = string_type.with_variant(
| mysql.VARCHAR(collation="foo"), "mysql", "mariadb"
| )
|
| The variant mapping indicates that when this type is
| interpreted by a specific dialect, it will instead be
| transmuted into the given type, rather than using the
| primary type.
|
| .. versionchanged:: 2.0 the :meth:`_types.TypeEngine.with_variant`
| method now works with a :class:`_types.TypeEngine` object "in
| place", returning a copy of the original type rather than returning
| a wrapping object; the ``Variant`` class is no longer used.
|
| :param type\_: a :class:`.TypeEngine` that will be selected
| as a variant from the originating type, when a dialect
| of the given name is in use.
| :param \*dialect_names: one or more base names of the dialect which
| uses this type. (i.e. ``'postgresql'``, ``'mysql'``, etc.)
|
| .. versionchanged:: 2.0 multiple dialect names can be specified
| for one variant.
|
| .. seealso::
|
| :ref:`types_with_variant` - illustrates the use of
| :meth:`_types.TypeEngine.with_variant`.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.type_api.TypeEngine:
|
| __orig_bases__ = (<class 'sqlalchemy.sql.visitors.Visitable'>, typing....
|
| hashable = True
|
| render_bind_cast = False
|
| render_literal_cast = False
|
| should_evaluate_none = False
|
| sort_key_function = None
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.visitors.Visitable:
|
| __class_getitem__(key: 'Any') -> 'Any'
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__() -> 'None'
| This method is called when a class is subclassed.
|
| The default implementation does nothing. It may be
| overridden to extend subclasses.
sqlalchemy.TextAsFrom
Python Library Documentation: class TextualSelect in module sqlalchemy.sql.selectable
class TextualSelect(SelectBase, ExecutableReturnsRows, sqlalchemy.sql.base.Generative)
| TextualSelect(text: 'TextClause', columns: 'List[_ColumnExpressionArgument[Any]]', positional: 'bool' = False) -> 'None'
|
| Wrap a :class:`_expression.TextClause` construct within a
| :class:`_expression.SelectBase`
| interface.
|
| This allows the :class:`_expression.TextClause` object to gain a
| ``.c`` collection
| and other FROM-like capabilities such as
| :meth:`_expression.FromClause.alias`,
| :meth:`_expression.SelectBase.cte`, etc.
|
| The :class:`_expression.TextualSelect` construct is produced via the
| :meth:`_expression.TextClause.columns`
| method - see that method for details.
|
| .. versionchanged:: 1.4 the :class:`_expression.TextualSelect`
| class was renamed
| from ``TextAsFrom``, to more correctly suit its role as a
| SELECT-oriented object and not a FROM clause.
|
| .. seealso::
|
| :func:`_expression.text`
|
| :meth:`_expression.TextClause.columns` - primary creation interface.
|
| Method resolution order:
| TextualSelect
| SelectBase
| sqlalchemy.sql.roles.SelectStatementRole
| ExecutableReturnsRows
| sqlalchemy.sql.base.Executable
| sqlalchemy.sql.roles.StatementRole
| sqlalchemy.sql.roles.DMLSelectRole
| sqlalchemy.sql.roles.CompoundElementRole
| sqlalchemy.sql.roles.AllowsLambdaRole
| sqlalchemy.sql.roles.InElementRole
| HasCTE
| sqlalchemy.sql.roles.HasCTERole
| SelectsRows
| sqlalchemy.sql.annotation.SupportsCloneAnnotations
| Selectable
| ReturnsRows
| sqlalchemy.sql.roles.ReturnsRowsRole
| sqlalchemy.sql.roles.SQLRole
| sqlalchemy.sql.elements.DQLDMLClauseElement
| sqlalchemy.sql.elements.ClauseElement
| sqlalchemy.sql.annotation.SupportsWrappingAnnotations
| sqlalchemy.sql.annotation.SupportsAnnotations
| sqlalchemy.sql.cache_key.MemoizedHasCacheKey
| sqlalchemy.sql.cache_key.HasCacheKey
| sqlalchemy.sql.base.Generative
| sqlalchemy.util.langhelpers.HasMemoized
| sqlalchemy.sql.traversals.HasCopyInternals
| sqlalchemy.sql.visitors.ExternallyTraversible
| sqlalchemy.sql.visitors.HasTraverseInternals
| sqlalchemy.sql.elements.CompilerElement
| sqlalchemy.sql.visitors.Visitable
| builtins.object
|
| Methods defined here:
|
| __init__(self, text: 'TextClause', columns: 'List[_ColumnExpressionArgument[Any]]', positional: 'bool' = False) -> 'None'
| Initialize self. See help(type(self)) for accurate signature.
|
| bindparams(self, *binds: 'BindParameter[Any]', **bind_as_values: 'Any') -> 'Self'
|
| selected_columns(...)
| A :class:`_expression.ColumnCollection`
| representing the columns that
| this SELECT statement or similar construct returns in its result set,
| not including :class:`_sql.TextClause` constructs.
|
| 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.
|
| For a :class:`_expression.TextualSelect` construct, the collection
| contains the :class:`_expression.ColumnElement` objects that were
| passed to the constructor, typically via the
| :meth:`_expression.TextClause.columns` method.
|
|
| .. versionadded:: 1.4
|
| set_label_style(self, style: 'SelectLabelStyle') -> 'TextualSelect'
| Return a new selectable with the specified label style.
|
| Implemented by subclasses.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'_traverse_internals': '_TraverseInternalsType'}
|
| __visit_name__ = 'textual_select'
|
| is_select = True
|
| is_text = True
|
| ----------------------------------------------------------------------
| Methods inherited from SelectBase:
|
| alias(self, name: 'Optional[str]' = None, flat: 'bool' = False) -> 'Subquery'
| 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.
|
| as_scalar(self) -> 'ScalarSelect[Any]'
| .. 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`.
|
| exists(self) -> 'Exists'
| 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
|
| get_label_style(self) -> 'SelectLabelStyle'
| Retrieve the current label style.
|
| Implemented by subclasses.
|
| label(self, name: 'Optional[str]') -> 'Label[Any]'
| Return a 'scalar' representation of this selectable, embedded as a
| subquery with a label.
|
| .. seealso::
|
| :meth:`_expression.SelectBase.scalar_subquery`.
|
| 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.
|
| scalar_subquery(self) -> 'ScalarSelect[Any]'
| 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
|
| select(self, *arg: 'Any', **kw: 'Any') -> 'Select[Any]'
| .. 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.
|
| subquery(self, name: 'Optional[str]' = None) -> '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:
|
| .. sourcecode:: sql
|
| 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:
|
| .. sourcecode:: sql
|
| 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
|
| ----------------------------------------------------------------------
| Readonly properties inherited from SelectBase:
|
| c
| .. 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.
|
| columns
|
| 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`
|
| ----------------------------------------------------------------------
| Data descriptors inherited from SelectBase:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.base.Executable:
|
| execution_options(self, **kw: 'Any') -> 'Self'
| Set non-SQL options for the statement which take effect during
| execution.
|
| Execution options can be set at many scopes, including per-statement,
| per-connection, or per execution, using methods such as
| :meth:`_engine.Connection.execution_options` and parameters which
| accept a dictionary of options such as
| :paramref:`_engine.Connection.execute.execution_options` and
| :paramref:`_orm.Session.execute.execution_options`.
|
| The primary characteristic of an execution option, as opposed to
| other kinds of options such as ORM loader options, is that
| **execution options never affect the compiled SQL of a query, only
| things that affect how the SQL statement itself is invoked or how
| results are fetched**. That is, execution options are not part of
| what's accommodated by SQL compilation nor are they considered part of
| the cached state of a statement.
|
| The :meth:`_sql.Executable.execution_options` method is
| :term:`generative`, as
| is the case for the method as applied to the :class:`_engine.Engine`
| and :class:`_orm.Query` objects, which means when the method is called,
| a copy of the object is returned, which applies the given parameters to
| that new copy, but leaves the original unchanged::
|
| statement = select(table.c.x, table.c.y)
| new_statement = statement.execution_options(my_option=True)
|
| An exception to this behavior is the :class:`_engine.Connection`
| object, where the :meth:`_engine.Connection.execution_options` method
| is explicitly **not** generative.
|
| The kinds of options that may be passed to
| :meth:`_sql.Executable.execution_options` and other related methods and
| parameter dictionaries include parameters that are explicitly consumed
| by SQLAlchemy Core or ORM, as well as arbitrary keyword arguments not
| defined by SQLAlchemy, which means the methods and/or parameter
| dictionaries may be used for user-defined parameters that interact with
| custom code, which may access the parameters using methods such as
| :meth:`_sql.Executable.get_execution_options` and
| :meth:`_engine.Connection.get_execution_options`, or within selected
| event hooks using a dedicated ``execution_options`` event parameter
| such as
| :paramref:`_events.ConnectionEvents.before_execute.execution_options`
| or :attr:`_orm.ORMExecuteState.execution_options`, e.g.::
|
| from sqlalchemy import event
|
|
| @event.listens_for(some_engine, "before_execute")
| def _process_opt(conn, statement, multiparams, params, execution_options):
| "run a SQL function before invoking a statement"
|
| if execution_options.get("do_special_thing", False):
| conn.exec_driver_sql("run_special_function()")
|
| Within the scope of options that are explicitly recognized by
| SQLAlchemy, most apply to specific classes of objects and not others.
| The most common execution options include:
|
| * :paramref:`_engine.Connection.execution_options.isolation_level` -
| sets the isolation level for a connection or a class of connections
| via an :class:`_engine.Engine`. This option is accepted only
| by :class:`_engine.Connection` or :class:`_engine.Engine`.
|
| * :paramref:`_engine.Connection.execution_options.stream_results` -
| indicates results should be fetched using a server side cursor;
| this option is accepted by :class:`_engine.Connection`, by the
| :paramref:`_engine.Connection.execute.execution_options` parameter
| on :meth:`_engine.Connection.execute`, and additionally by
| :meth:`_sql.Executable.execution_options` on a SQL statement object,
| as well as by ORM constructs like :meth:`_orm.Session.execute`.
|
| * :paramref:`_engine.Connection.execution_options.compiled_cache` -
| indicates a dictionary that will serve as the
| :ref:`SQL compilation cache <sql_caching>`
| for a :class:`_engine.Connection` or :class:`_engine.Engine`, as
| well as for ORM methods like :meth:`_orm.Session.execute`.
| Can be passed as ``None`` to disable caching for statements.
| This option is not accepted by
| :meth:`_sql.Executable.execution_options` as it is inadvisable to
| carry along a compilation cache within a statement object.
|
| * :paramref:`_engine.Connection.execution_options.schema_translate_map`
| - a mapping of schema names used by the
| :ref:`Schema Translate Map <schema_translating>` feature, accepted
| by :class:`_engine.Connection`, :class:`_engine.Engine`,
| :class:`_sql.Executable`, as well as by ORM constructs
| like :meth:`_orm.Session.execute`.
|
| .. seealso::
|
| :meth:`_engine.Connection.execution_options`
|
| :paramref:`_engine.Connection.execute.execution_options`
|
| :paramref:`_orm.Session.execute.execution_options`
|
| :ref:`orm_queryguide_execution_options` - documentation on all
| ORM-specific execution options
|
| get_execution_options(self) -> '_ExecuteOptions'
| Get the non-SQL options which will take effect during execution.
|
| .. versionadded:: 1.3
|
| .. seealso::
|
| :meth:`.Executable.execution_options`
|
| options(self, *options: 'ExecutableOption') -> 'Self'
| Apply options to this statement.
|
| In the general sense, options are any kind of Python object
| that can be interpreted by the SQL compiler for the statement.
| These options can be consumed by specific dialects or specific kinds
| of compilers.
|
| The most commonly known kind of option are the ORM level options
| that apply "eager load" and other loading behaviors to an ORM
| query. However, options can theoretically be used for many other
| purposes.
|
| For background on specific kinds of options for specific kinds of
| statements, refer to the documentation for those option objects.
|
| .. versionchanged:: 1.4 - added :meth:`.Executable.options` to
| Core statement objects towards the goal of allowing unified
| Core / ORM querying capabilities.
|
| .. seealso::
|
| :ref:`loading_columns` - refers to options specific to the usage
| of ORM queries
|
| :ref:`relationship_loader_options` - refers to options specific
| to the usage of ORM queries
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.base.Executable:
|
| is_delete = False
|
| is_dml = False
|
| is_from_statement = False
|
| is_insert = False
|
| is_update = False
|
| supports_execution = True
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.AllowsLambdaRole:
|
| allows_lambda = True
|
| ----------------------------------------------------------------------
| Methods inherited from HasCTE:
|
| add_cte(self, *ctes: 'CTE', nest_here: 'bool' = False) -> 'Self'
| Add one or more :class:`_sql.CTE` constructs to this statement.
|
| This method will associate the given :class:`_sql.CTE` constructs with
| the parent statement such that they will each be unconditionally
| rendered in the WITH clause of the final statement, even if not
| referenced elsewhere within the statement or any sub-selects.
|
| The optional :paramref:`.HasCTE.add_cte.nest_here` parameter when set
| to True will have the effect that each given :class:`_sql.CTE` will
| render in a WITH clause rendered directly along with this statement,
| rather than being moved to the top of the ultimate rendered statement,
| even if this statement is rendered as a subquery within a larger
| statement.
|
| This method has two general uses. One is to embed CTE statements that
| serve some purpose without being referenced explicitly, such as the use
| case of embedding a DML statement such as an INSERT or UPDATE as a CTE
| inline with a primary statement that may draw from its results
| indirectly. The other is to provide control over the exact placement
| of a particular series of CTE constructs that should remain rendered
| directly in terms of a particular statement that may be nested in a
| larger statement.
|
| E.g.::
|
| from sqlalchemy import table, column, select
|
| t = table("t", column("c1"), column("c2"))
|
| ins = t.insert().values({"c1": "x", "c2": "y"}).cte()
|
| stmt = select(t).add_cte(ins)
|
| Would render:
|
| .. sourcecode:: sql
|
| WITH anon_1 AS (
| INSERT INTO t (c1, c2) VALUES (:param_1, :param_2)
| )
| SELECT t.c1, t.c2
| FROM t
|
| Above, the "anon_1" CTE is not referenced in the SELECT
| statement, however still accomplishes the task of running an INSERT
| statement.
|
| Similarly in a DML-related context, using the PostgreSQL
| :class:`_postgresql.Insert` construct to generate an "upsert"::
|
| from sqlalchemy import table, column
| from sqlalchemy.dialects.postgresql import insert
|
| t = table("t", column("c1"), column("c2"))
|
| delete_statement_cte = t.delete().where(t.c.c1 < 1).cte("deletions")
|
| insert_stmt = insert(t).values({"c1": 1, "c2": 2})
| update_statement = insert_stmt.on_conflict_do_update(
| index_elements=[t.c.c1],
| set_={
| "c1": insert_stmt.excluded.c1,
| "c2": insert_stmt.excluded.c2,
| },
| ).add_cte(delete_statement_cte)
|
| print(update_statement)
|
| The above statement renders as:
|
| .. sourcecode:: sql
|
| WITH deletions AS (
| DELETE FROM t WHERE t.c1 < %(c1_1)s
| )
| INSERT INTO t (c1, c2) VALUES (%(c1)s, %(c2)s)
| ON CONFLICT (c1) DO UPDATE SET c1 = excluded.c1, c2 = excluded.c2
|
| .. versionadded:: 1.4.21
|
| :param \*ctes: zero or more :class:`.CTE` constructs.
|
| .. versionchanged:: 2.0 Multiple CTE instances are accepted
|
| :param nest_here: if True, the given CTE or CTEs will be rendered
| as though they specified the :paramref:`.HasCTE.cte.nesting` flag
| to ``True`` when they were added to this :class:`.HasCTE`.
| Assuming the given CTEs are not referenced in an outer-enclosing
| statement as well, the CTEs given should render at the level of
| this statement when this flag is given.
|
| .. versionadded:: 2.0
|
| .. seealso::
|
| :paramref:`.HasCTE.cte.nesting`
|
| cte(self, name: 'Optional[str]' = None, recursive: 'bool' = False, nesting: 'bool' = False) -> 'CTE'
| Return a new :class:`_expression.CTE`,
| or Common Table Expression instance.
|
| Common table expressions are a SQL standard whereby SELECT
| statements can draw upon secondary statements specified along
| with the primary statement, using a clause called "WITH".
| Special semantics regarding UNION can also be employed to
| allow "recursive" queries, where a SELECT statement can draw
| upon the set of rows that have previously been selected.
|
| CTEs can also be applied to DML constructs UPDATE, INSERT
| and DELETE on some databases, both as a source of CTE rows
| when combined with RETURNING, as well as a consumer of
| CTE rows.
|
| SQLAlchemy detects :class:`_expression.CTE` objects, which are treated
| similarly to :class:`_expression.Alias` objects, as special elements
| to be delivered to the FROM clause of the statement as well
| as to a WITH clause at the top of the statement.
|
| For special prefixes such as PostgreSQL "MATERIALIZED" and
| "NOT MATERIALIZED", the :meth:`_expression.CTE.prefix_with`
| method may be
| used to establish these.
|
| .. versionchanged:: 1.3.13 Added support for prefixes.
| In particular - MATERIALIZED and NOT MATERIALIZED.
|
| :param name: name given to the common table expression. Like
| :meth:`_expression.FromClause.alias`, the name can be left as
| ``None`` in which case an anonymous symbol will be used at query
| compile time.
| :param recursive: if ``True``, will render ``WITH RECURSIVE``.
| A recursive common table expression is intended to be used in
| conjunction with UNION ALL in order to derive rows
| from those already selected.
| :param nesting: if ``True``, will render the CTE locally to the
| statement in which it is referenced. For more complex scenarios,
| the :meth:`.HasCTE.add_cte` method using the
| :paramref:`.HasCTE.add_cte.nest_here`
| parameter may also be used to more carefully
| control the exact placement of a particular CTE.
|
| .. versionadded:: 1.4.24
|
| .. seealso::
|
| :meth:`.HasCTE.add_cte`
|
| The following examples include two from PostgreSQL's documentation at
| https://www.postgresql.org/docs/current/static/queries-with.html,
| as well as additional examples.
|
| Example 1, non recursive::
|
| from sqlalchemy import (
| Table,
| Column,
| String,
| Integer,
| MetaData,
| select,
| func,
| )
|
| metadata = MetaData()
|
| orders = Table(
| "orders",
| metadata,
| Column("region", String),
| Column("amount", Integer),
| Column("product", String),
| Column("quantity", Integer),
| )
|
| regional_sales = (
| select(orders.c.region, func.sum(orders.c.amount).label("total_sales"))
| .group_by(orders.c.region)
| .cte("regional_sales")
| )
|
|
| top_regions = (
| select(regional_sales.c.region)
| .where(
| regional_sales.c.total_sales
| > select(func.sum(regional_sales.c.total_sales) / 10)
| )
| .cte("top_regions")
| )
|
| statement = (
| select(
| orders.c.region,
| orders.c.product,
| func.sum(orders.c.quantity).label("product_units"),
| func.sum(orders.c.amount).label("product_sales"),
| )
| .where(orders.c.region.in_(select(top_regions.c.region)))
| .group_by(orders.c.region, orders.c.product)
| )
|
| result = conn.execute(statement).fetchall()
|
| Example 2, WITH RECURSIVE::
|
| from sqlalchemy import (
| Table,
| Column,
| String,
| Integer,
| MetaData,
| select,
| func,
| )
|
| metadata = MetaData()
|
| parts = Table(
| "parts",
| metadata,
| Column("part", String),
| Column("sub_part", String),
| Column("quantity", Integer),
| )
|
| included_parts = (
| select(parts.c.sub_part, parts.c.part, parts.c.quantity)
| .where(parts.c.part == "our part")
| .cte(recursive=True)
| )
|
|
| incl_alias = included_parts.alias()
| parts_alias = parts.alias()
| included_parts = included_parts.union_all(
| select(
| parts_alias.c.sub_part, parts_alias.c.part, parts_alias.c.quantity
| ).where(parts_alias.c.part == incl_alias.c.sub_part)
| )
|
| statement = select(
| included_parts.c.sub_part,
| func.sum(included_parts.c.quantity).label("total_quantity"),
| ).group_by(included_parts.c.sub_part)
|
| result = conn.execute(statement).fetchall()
|
| Example 3, an upsert using UPDATE and INSERT with CTEs::
|
| from datetime import date
| from sqlalchemy import (
| MetaData,
| Table,
| Column,
| Integer,
| Date,
| select,
| literal,
| and_,
| exists,
| )
|
| metadata = MetaData()
|
| visitors = Table(
| "visitors",
| metadata,
| Column("product_id", Integer, primary_key=True),
| Column("date", Date, primary_key=True),
| Column("count", Integer),
| )
|
| # add 5 visitors for the product_id == 1
| product_id = 1
| day = date.today()
| count = 5
|
| update_cte = (
| visitors.update()
| .where(
| and_(visitors.c.product_id == product_id, visitors.c.date == day)
| )
| .values(count=visitors.c.count + count)
| .returning(literal(1))
| .cte("update_cte")
| )
|
| upsert = visitors.insert().from_select(
| [visitors.c.product_id, visitors.c.date, visitors.c.count],
| select(literal(product_id), literal(day), literal(count)).where(
| ~exists(update_cte.select())
| ),
| )
|
| connection.execute(upsert)
|
| Example 4, Nesting CTE (SQLAlchemy 1.4.24 and above)::
|
| value_a = select(literal("root").label("n")).cte("value_a")
|
| # A nested CTE with the same name as the root one
| value_a_nested = select(literal("nesting").label("n")).cte(
| "value_a", nesting=True
| )
|
| # Nesting CTEs takes ascendency locally
| # over the CTEs at a higher level
| value_b = select(value_a_nested.c.n).cte("value_b")
|
| value_ab = select(value_a.c.n.label("a"), value_b.c.n.label("b"))
|
| The above query will render the second CTE nested inside the first,
| shown with inline parameters below as:
|
| .. sourcecode:: sql
|
| WITH
| value_a AS
| (SELECT 'root' AS n),
| value_b AS
| (WITH value_a AS
| (SELECT 'nesting' AS n)
| SELECT value_a.n AS n FROM value_a)
| SELECT value_a.n AS a, value_b.n AS b
| FROM value_a, value_b
|
| The same CTE can be set up using the :meth:`.HasCTE.add_cte` method
| as follows (SQLAlchemy 2.0 and above)::
|
| value_a = select(literal("root").label("n")).cte("value_a")
|
| # A nested CTE with the same name as the root one
| value_a_nested = select(literal("nesting").label("n")).cte("value_a")
|
| # Nesting CTEs takes ascendency locally
| # over the CTEs at a higher level
| value_b = (
| select(value_a_nested.c.n)
| .add_cte(value_a_nested, nest_here=True)
| .cte("value_b")
| )
|
| value_ab = select(value_a.c.n.label("a"), value_b.c.n.label("b"))
|
| Example 5, Non-Linear CTE (SQLAlchemy 1.4.28 and above)::
|
| edge = Table(
| "edge",
| metadata,
| Column("id", Integer, primary_key=True),
| Column("left", Integer),
| Column("right", Integer),
| )
|
| root_node = select(literal(1).label("node")).cte("nodes", recursive=True)
|
| left_edge = select(edge.c.left).join(
| root_node, edge.c.right == root_node.c.node
| )
| right_edge = select(edge.c.right).join(
| root_node, edge.c.left == root_node.c.node
| )
|
| subgraph_cte = root_node.union(left_edge, right_edge)
|
| subgraph = select(subgraph_cte)
|
| The above query will render 2 UNIONs inside the recursive CTE:
|
| .. sourcecode:: sql
|
| WITH RECURSIVE nodes(node) AS (
| SELECT 1 AS node
| UNION
| SELECT edge."left" AS "left"
| FROM edge JOIN nodes ON edge."right" = nodes.node
| UNION
| SELECT edge."right" AS "right"
| FROM edge JOIN nodes ON edge."left" = nodes.node
| )
| SELECT nodes.node FROM nodes
|
| .. seealso::
|
| :meth:`_orm.Query.cte` - ORM version of
| :meth:`_expression.HasCTE.cte`.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from HasCTE:
|
| name_cte_columns = False
|
| ----------------------------------------------------------------------
| Methods inherited from Selectable:
|
| 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.
|
| 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`.
|
| .. deprecated:: 1.4 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.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from Selectable:
|
| is_selectable = True
|
| ----------------------------------------------------------------------
| Methods inherited from ReturnsRows:
|
| 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.
|
| ----------------------------------------------------------------------
| Readonly properties inherited from ReturnsRows:
|
| selectable
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.SQLRole:
|
| uses_inspection = False
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.elements.ClauseElement:
|
| __bool__(self)
|
| __getstate__(self)
| Helper for pickle.
|
| __invert__(self)
|
| __repr__(self)
| Return repr(self).
|
| compare(self, other: 'ClauseElement', **kw: 'Any') -> 'bool'
| Compare this :class:`_expression.ClauseElement` to
| the given :class:`_expression.ClauseElement`.
|
| Subclasses should override the default behavior, which is a
| straight identity comparison.
|
| \**kw are arguments consumed by subclass ``compare()`` methods and
| may be used to modify the criteria for comparison
| (see :class:`_expression.ColumnElement`).
|
| description(...)
|
| entity_namespace(...)
|
| params(self, _ClauseElement__optionaldict: 'Optional[Mapping[str, Any]]' = None, **kwargs: 'Any') -> 'Self'
| Return a copy with :func:`_expression.bindparam` elements
| replaced.
|
| Returns a copy of this ClauseElement with
| :func:`_expression.bindparam`
| elements replaced with values taken from the given dictionary::
|
| >>> clause = column("x") + bindparam("foo")
| >>> print(clause.compile().params)
| {'foo':None}
| >>> print(clause.params({"foo": 7}).compile().params)
| {'foo':7}
|
| self_group(self, against: 'Optional[OperatorType]' = None) -> 'ClauseElement'
| 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.
|
| unique_params(self, _ClauseElement__optionaldict: 'Optional[Dict[str, Any]]' = None, **kwargs: 'Any') -> 'Self'
| Return a copy with :func:`_expression.bindparam` elements
| replaced.
|
| Same functionality as :meth:`_expression.ClauseElement.params`,
| except adds `unique=True`
| to affected bind parameters so that multiple statements can be
| used.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.elements.ClauseElement:
|
| is_clause_element = True
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.cache_key.HasCacheKey:
|
| inherit_cache = None
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_instancemethod(fn: '_F') -> '_F'
| Decorate a method memoize its return value.
|
| :meta private:
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_attribute = <class 'sqlalchemy.util.langhelpers.HasMemoized.m...
| A read-only @property that is only evaluated once.
|
| :meta private:
|
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.visitors.HasTraverseInternals:
|
| get_children(self, *, omit_attrs: 'Tuple[str, ...]' = (), **kw: 'Any') -> 'Iterable[HasTraverseInternals]'
| Return immediate child :class:`.visitors.HasTraverseInternals`
| elements of this :class:`.visitors.HasTraverseInternals`.
|
| This is used for visit traversal.
|
| \**kw may contain flags that change the collection that is
| returned, for example to return a subset of items in order to
| cut down on larger traversals, or to return child items from a
| different context (such as schema-level collections instead of
| clause-level).
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.elements.CompilerElement:
|
| __str__(self) -> 'str'
| Return str(self).
|
| compile(self, bind: 'Optional[_HasDialect]' = None, dialect: 'Optional[Dialect]' = None, **kw: 'Any') -> 'Compiled'
| Compile this SQL expression.
|
| The return value is a :class:`~.Compiled` object.
| Calling ``str()`` or ``unicode()`` on the returned value will yield a
| string representation of the result. The
| :class:`~.Compiled` object also can return a
| dictionary of bind parameter names and values
| using the ``params`` accessor.
|
| :param bind: An :class:`.Connection` or :class:`.Engine` which
| can provide a :class:`.Dialect` in order to generate a
| :class:`.Compiled` object. If the ``bind`` and
| ``dialect`` parameters are both omitted, a default SQL compiler
| is used.
|
| :param column_keys: Used for INSERT and UPDATE statements, a list of
| column names which should be present in the VALUES clause of the
| compiled statement. If ``None``, all columns from the target table
| object are rendered.
|
| :param dialect: A :class:`.Dialect` instance which can generate
| a :class:`.Compiled` object. This argument takes precedence over
| the ``bind`` argument.
|
| :param compile_kwargs: optional dictionary of additional parameters
| that will be passed through to the compiler within all "visit"
| methods. This allows any custom flag to be passed through to
| a custom compilation construct, for example. It is also used
| for the case of passing the ``literal_binds`` flag through::
|
| from sqlalchemy.sql import table, column, select
|
| t = table("t", column("x"))
|
| s = select(t).where(t.c.x == 5)
|
| print(s.compile(compile_kwargs={"literal_binds": True}))
|
| .. seealso::
|
| :ref:`faq_sql_expression_string`
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.elements.CompilerElement:
|
| stringify_dialect = 'default'
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.visitors.Visitable:
|
| __class_getitem__(key: 'Any') -> 'Any'
|
| __init_subclass__() -> 'None'
| This method is called when a class is subclassed.
|
| The default implementation does nothing. It may be
| overridden to extend subclasses.
sqlalchemy.TextClause
Python Library Documentation: class TextClause in module sqlalchemy.sql.elements
class TextClause(sqlalchemy.sql.roles.DDLConstraintColumnRole, sqlalchemy.sql.roles.DDLExpressionRole, sqlalchemy.sql.roles.StatementOptionRole, sqlalchemy.sql.roles.WhereHavingRole, sqlalchemy.sql.roles.OrderByRole, sqlalchemy.sql.roles.FromClauseRole, sqlalchemy.sql.roles.SelectStatementRole, sqlalchemy.sql.roles.InElementRole, sqlalchemy.sql.base.Generative, sqlalchemy.sql.base.Executable, DQLDMLClauseElement, sqlalchemy.sql.roles.BinaryElementRole, sqlalchemy.inspection.Inspectable)
| TextClause(text: 'str')
|
| 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 resolution order:
| TextClause
| sqlalchemy.sql.roles.DDLConstraintColumnRole
| sqlalchemy.sql.roles.DDLExpressionRole
| sqlalchemy.sql.roles.StatementOptionRole
| sqlalchemy.sql.roles.WhereHavingRole
| sqlalchemy.sql.roles.OnClauseRole
| sqlalchemy.sql.roles.OrderByRole
| sqlalchemy.sql.roles.FromClauseRole
| sqlalchemy.sql.roles.ColumnsClauseRole
| sqlalchemy.sql.roles.JoinTargetRole
| sqlalchemy.sql.roles.AllowsLambdaRole
| sqlalchemy.sql.roles.ByOfRole
| sqlalchemy.sql.roles.UsesInspection
| sqlalchemy.sql.roles.ColumnListRole
| sqlalchemy.sql.roles.StructuralRole
| sqlalchemy.sql.roles.SelectStatementRole
| sqlalchemy.sql.roles.InElementRole
| sqlalchemy.sql.base.Generative
| sqlalchemy.sql.base.Executable
| sqlalchemy.sql.roles.StatementRole
| sqlalchemy.sql.roles.ReturnsRowsRole
| DQLDMLClauseElement
| ClauseElement
| sqlalchemy.sql.annotation.SupportsWrappingAnnotations
| sqlalchemy.sql.annotation.SupportsAnnotations
| sqlalchemy.sql.cache_key.MemoizedHasCacheKey
| sqlalchemy.sql.cache_key.HasCacheKey
| sqlalchemy.util.langhelpers.HasMemoized
| sqlalchemy.sql.traversals.HasCopyInternals
| sqlalchemy.sql.visitors.ExternallyTraversible
| sqlalchemy.sql.visitors.HasTraverseInternals
| CompilerElement
| sqlalchemy.sql.visitors.Visitable
| sqlalchemy.sql.roles.BinaryElementRole
| sqlalchemy.sql.roles.ExpressionElementRole
| sqlalchemy.sql.roles.TypedColumnsClauseRole
| sqlalchemy.inspection.Inspectable
| typing.Generic
| sqlalchemy.sql.roles.SQLRole
| builtins.object
|
| Methods defined here:
|
| __and__(self, other)
|
| __init__(self, text: 'str')
| Initialize self. See help(type(self)) for accurate signature.
|
| bindparams(self, *binds: 'BindParameter[Any]', **names_to_values: 'Any') -> 'Self'
| 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 reuse 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:
|
| .. sourcecode:: sql
|
| 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.
|
| columns(self, *cols: '_OnlyColumnArgument[Any]', **types: '_TypeEngineArgument[Any]') -> 'TextualSelect'
| 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))
| )
|
| 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.
|
| self_group(self, against: 'Optional[OperatorType]' = None) -> 'Union[Self, Grouping[Any]]'
| 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.
|
| ----------------------------------------------------------------------
| Readonly properties defined here:
|
| comparator
|
| type
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'_label': 'Optional[str]', '_traverse_internals': '...
|
| __orig_bases__ = (<class 'sqlalchemy.sql.roles.DDLConstraintColumnRole...
|
| __parameters__ = ()
|
| __visit_name__ = 'textclause'
|
| key = None
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.AllowsLambdaRole:
|
| allows_lambda = True
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.UsesInspection:
|
| uses_inspection = True
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.roles.SelectStatementRole:
|
| subquery(self) -> 'Subquery'
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.base.Executable:
|
| execution_options(self, **kw: 'Any') -> 'Self'
| Set non-SQL options for the statement which take effect during
| execution.
|
| Execution options can be set at many scopes, including per-statement,
| per-connection, or per execution, using methods such as
| :meth:`_engine.Connection.execution_options` and parameters which
| accept a dictionary of options such as
| :paramref:`_engine.Connection.execute.execution_options` and
| :paramref:`_orm.Session.execute.execution_options`.
|
| The primary characteristic of an execution option, as opposed to
| other kinds of options such as ORM loader options, is that
| **execution options never affect the compiled SQL of a query, only
| things that affect how the SQL statement itself is invoked or how
| results are fetched**. That is, execution options are not part of
| what's accommodated by SQL compilation nor are they considered part of
| the cached state of a statement.
|
| The :meth:`_sql.Executable.execution_options` method is
| :term:`generative`, as
| is the case for the method as applied to the :class:`_engine.Engine`
| and :class:`_orm.Query` objects, which means when the method is called,
| a copy of the object is returned, which applies the given parameters to
| that new copy, but leaves the original unchanged::
|
| statement = select(table.c.x, table.c.y)
| new_statement = statement.execution_options(my_option=True)
|
| An exception to this behavior is the :class:`_engine.Connection`
| object, where the :meth:`_engine.Connection.execution_options` method
| is explicitly **not** generative.
|
| The kinds of options that may be passed to
| :meth:`_sql.Executable.execution_options` and other related methods and
| parameter dictionaries include parameters that are explicitly consumed
| by SQLAlchemy Core or ORM, as well as arbitrary keyword arguments not
| defined by SQLAlchemy, which means the methods and/or parameter
| dictionaries may be used for user-defined parameters that interact with
| custom code, which may access the parameters using methods such as
| :meth:`_sql.Executable.get_execution_options` and
| :meth:`_engine.Connection.get_execution_options`, or within selected
| event hooks using a dedicated ``execution_options`` event parameter
| such as
| :paramref:`_events.ConnectionEvents.before_execute.execution_options`
| or :attr:`_orm.ORMExecuteState.execution_options`, e.g.::
|
| from sqlalchemy import event
|
|
| @event.listens_for(some_engine, "before_execute")
| def _process_opt(conn, statement, multiparams, params, execution_options):
| "run a SQL function before invoking a statement"
|
| if execution_options.get("do_special_thing", False):
| conn.exec_driver_sql("run_special_function()")
|
| Within the scope of options that are explicitly recognized by
| SQLAlchemy, most apply to specific classes of objects and not others.
| The most common execution options include:
|
| * :paramref:`_engine.Connection.execution_options.isolation_level` -
| sets the isolation level for a connection or a class of connections
| via an :class:`_engine.Engine`. This option is accepted only
| by :class:`_engine.Connection` or :class:`_engine.Engine`.
|
| * :paramref:`_engine.Connection.execution_options.stream_results` -
| indicates results should be fetched using a server side cursor;
| this option is accepted by :class:`_engine.Connection`, by the
| :paramref:`_engine.Connection.execute.execution_options` parameter
| on :meth:`_engine.Connection.execute`, and additionally by
| :meth:`_sql.Executable.execution_options` on a SQL statement object,
| as well as by ORM constructs like :meth:`_orm.Session.execute`.
|
| * :paramref:`_engine.Connection.execution_options.compiled_cache` -
| indicates a dictionary that will serve as the
| :ref:`SQL compilation cache <sql_caching>`
| for a :class:`_engine.Connection` or :class:`_engine.Engine`, as
| well as for ORM methods like :meth:`_orm.Session.execute`.
| Can be passed as ``None`` to disable caching for statements.
| This option is not accepted by
| :meth:`_sql.Executable.execution_options` as it is inadvisable to
| carry along a compilation cache within a statement object.
|
| * :paramref:`_engine.Connection.execution_options.schema_translate_map`
| - a mapping of schema names used by the
| :ref:`Schema Translate Map <schema_translating>` feature, accepted
| by :class:`_engine.Connection`, :class:`_engine.Engine`,
| :class:`_sql.Executable`, as well as by ORM constructs
| like :meth:`_orm.Session.execute`.
|
| .. seealso::
|
| :meth:`_engine.Connection.execution_options`
|
| :paramref:`_engine.Connection.execute.execution_options`
|
| :paramref:`_orm.Session.execute.execution_options`
|
| :ref:`orm_queryguide_execution_options` - documentation on all
| ORM-specific execution options
|
| get_execution_options(self) -> '_ExecuteOptions'
| Get the non-SQL options which will take effect during execution.
|
| .. versionadded:: 1.3
|
| .. seealso::
|
| :meth:`.Executable.execution_options`
|
| options(self, *options: 'ExecutableOption') -> 'Self'
| Apply options to this statement.
|
| In the general sense, options are any kind of Python object
| that can be interpreted by the SQL compiler for the statement.
| These options can be consumed by specific dialects or specific kinds
| of compilers.
|
| The most commonly known kind of option are the ORM level options
| that apply "eager load" and other loading behaviors to an ORM
| query. However, options can theoretically be used for many other
| purposes.
|
| For background on specific kinds of options for specific kinds of
| statements, refer to the documentation for those option objects.
|
| .. versionchanged:: 1.4 - added :meth:`.Executable.options` to
| Core statement objects towards the goal of allowing unified
| Core / ORM querying capabilities.
|
| .. seealso::
|
| :ref:`loading_columns` - refers to options specific to the usage
| of ORM queries
|
| :ref:`relationship_loader_options` - refers to options specific
| to the usage of ORM queries
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.base.Executable:
|
| is_delete = False
|
| is_dml = False
|
| is_from_statement = False
|
| is_insert = False
|
| is_select = False
|
| is_text = False
|
| is_update = False
|
| supports_execution = True
|
| ----------------------------------------------------------------------
| Methods inherited from ClauseElement:
|
| __bool__(self)
|
| __getstate__(self)
| Helper for pickle.
|
| __invert__(self)
|
| __repr__(self)
| Return repr(self).
|
| compare(self, other: 'ClauseElement', **kw: 'Any') -> 'bool'
| Compare this :class:`_expression.ClauseElement` to
| the given :class:`_expression.ClauseElement`.
|
| Subclasses should override the default behavior, which is a
| straight identity comparison.
|
| \**kw are arguments consumed by subclass ``compare()`` methods and
| may be used to modify the criteria for comparison
| (see :class:`_expression.ColumnElement`).
|
| description(...)
|
| entity_namespace(...)
|
| params(self, _ClauseElement__optionaldict: 'Optional[Mapping[str, Any]]' = None, **kwargs: 'Any') -> 'Self'
| Return a copy with :func:`_expression.bindparam` elements
| replaced.
|
| Returns a copy of this ClauseElement with
| :func:`_expression.bindparam`
| elements replaced with values taken from the given dictionary::
|
| >>> clause = column("x") + bindparam("foo")
| >>> print(clause.compile().params)
| {'foo':None}
| >>> print(clause.params({"foo": 7}).compile().params)
| {'foo':7}
|
| unique_params(self, _ClauseElement__optionaldict: 'Optional[Dict[str, Any]]' = None, **kwargs: 'Any') -> 'Self'
| Return a copy with :func:`_expression.bindparam` elements
| replaced.
|
| Same functionality as :meth:`_expression.ClauseElement.params`,
| except adds `unique=True`
| to affected bind parameters so that multiple statements can be
| used.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from ClauseElement:
|
| is_clause_element = True
|
| is_selectable = False
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.cache_key.HasCacheKey:
|
| inherit_cache = None
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_instancemethod(fn: '_F') -> '_F'
| Decorate a method memoize its return value.
|
| :meta private:
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_attribute = <class 'sqlalchemy.util.langhelpers.HasMemoized.m...
| A read-only @property that is only evaluated once.
|
| :meta private:
|
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.visitors.HasTraverseInternals:
|
| get_children(self, *, omit_attrs: 'Tuple[str, ...]' = (), **kw: 'Any') -> 'Iterable[HasTraverseInternals]'
| Return immediate child :class:`.visitors.HasTraverseInternals`
| elements of this :class:`.visitors.HasTraverseInternals`.
|
| This is used for visit traversal.
|
| \**kw may contain flags that change the collection that is
| returned, for example to return a subset of items in order to
| cut down on larger traversals, or to return child items from a
| different context (such as schema-level collections instead of
| clause-level).
|
| ----------------------------------------------------------------------
| Methods inherited from CompilerElement:
|
| __str__(self) -> 'str'
| Return str(self).
|
| compile(self, bind: 'Optional[_HasDialect]' = None, dialect: 'Optional[Dialect]' = None, **kw: 'Any') -> 'Compiled'
| Compile this SQL expression.
|
| The return value is a :class:`~.Compiled` object.
| Calling ``str()`` or ``unicode()`` on the returned value will yield a
| string representation of the result. The
| :class:`~.Compiled` object also can return a
| dictionary of bind parameter names and values
| using the ``params`` accessor.
|
| :param bind: An :class:`.Connection` or :class:`.Engine` which
| can provide a :class:`.Dialect` in order to generate a
| :class:`.Compiled` object. If the ``bind`` and
| ``dialect`` parameters are both omitted, a default SQL compiler
| is used.
|
| :param column_keys: Used for INSERT and UPDATE statements, a list of
| column names which should be present in the VALUES clause of the
| compiled statement. If ``None``, all columns from the target table
| object are rendered.
|
| :param dialect: A :class:`.Dialect` instance which can generate
| a :class:`.Compiled` object. This argument takes precedence over
| the ``bind`` argument.
|
| :param compile_kwargs: optional dictionary of additional parameters
| that will be passed through to the compiler within all "visit"
| methods. This allows any custom flag to be passed through to
| a custom compilation construct, for example. It is also used
| for the case of passing the ``literal_binds`` flag through::
|
| from sqlalchemy.sql import table, column, select
|
| t = table("t", column("x"))
|
| s = select(t).where(t.c.x == 5)
|
| print(s.compile(compile_kwargs={"literal_binds": True}))
|
| .. seealso::
|
| :ref:`faq_sql_expression_string`
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from CompilerElement:
|
| stringify_dialect = 'default'
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.visitors.Visitable:
|
| __class_getitem__(key: 'Any') -> 'Any'
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__() -> 'None'
| This method is called when a class is subclassed.
|
| The default implementation does nothing. It may be
| overridden to extend subclasses.
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.roles.ExpressionElementRole:
|
| label(self, name: 'Optional[str]') -> 'Label[_T]'
sqlalchemy.TextualSelect
Python Library Documentation: class TextualSelect in module sqlalchemy.sql.selectable
class TextualSelect(SelectBase, ExecutableReturnsRows, sqlalchemy.sql.base.Generative)
| TextualSelect(text: 'TextClause', columns: 'List[_ColumnExpressionArgument[Any]]', positional: 'bool' = False) -> 'None'
|
| Wrap a :class:`_expression.TextClause` construct within a
| :class:`_expression.SelectBase`
| interface.
|
| This allows the :class:`_expression.TextClause` object to gain a
| ``.c`` collection
| and other FROM-like capabilities such as
| :meth:`_expression.FromClause.alias`,
| :meth:`_expression.SelectBase.cte`, etc.
|
| The :class:`_expression.TextualSelect` construct is produced via the
| :meth:`_expression.TextClause.columns`
| method - see that method for details.
|
| .. versionchanged:: 1.4 the :class:`_expression.TextualSelect`
| class was renamed
| from ``TextAsFrom``, to more correctly suit its role as a
| SELECT-oriented object and not a FROM clause.
|
| .. seealso::
|
| :func:`_expression.text`
|
| :meth:`_expression.TextClause.columns` - primary creation interface.
|
| Method resolution order:
| TextualSelect
| SelectBase
| sqlalchemy.sql.roles.SelectStatementRole
| ExecutableReturnsRows
| sqlalchemy.sql.base.Executable
| sqlalchemy.sql.roles.StatementRole
| sqlalchemy.sql.roles.DMLSelectRole
| sqlalchemy.sql.roles.CompoundElementRole
| sqlalchemy.sql.roles.AllowsLambdaRole
| sqlalchemy.sql.roles.InElementRole
| HasCTE
| sqlalchemy.sql.roles.HasCTERole
| SelectsRows
| sqlalchemy.sql.annotation.SupportsCloneAnnotations
| Selectable
| ReturnsRows
| sqlalchemy.sql.roles.ReturnsRowsRole
| sqlalchemy.sql.roles.SQLRole
| sqlalchemy.sql.elements.DQLDMLClauseElement
| sqlalchemy.sql.elements.ClauseElement
| sqlalchemy.sql.annotation.SupportsWrappingAnnotations
| sqlalchemy.sql.annotation.SupportsAnnotations
| sqlalchemy.sql.cache_key.MemoizedHasCacheKey
| sqlalchemy.sql.cache_key.HasCacheKey
| sqlalchemy.sql.base.Generative
| sqlalchemy.util.langhelpers.HasMemoized
| sqlalchemy.sql.traversals.HasCopyInternals
| sqlalchemy.sql.visitors.ExternallyTraversible
| sqlalchemy.sql.visitors.HasTraverseInternals
| sqlalchemy.sql.elements.CompilerElement
| sqlalchemy.sql.visitors.Visitable
| builtins.object
|
| Methods defined here:
|
| __init__(self, text: 'TextClause', columns: 'List[_ColumnExpressionArgument[Any]]', positional: 'bool' = False) -> 'None'
| Initialize self. See help(type(self)) for accurate signature.
|
| bindparams(self, *binds: 'BindParameter[Any]', **bind_as_values: 'Any') -> 'Self'
|
| selected_columns(...)
| A :class:`_expression.ColumnCollection`
| representing the columns that
| this SELECT statement or similar construct returns in its result set,
| not including :class:`_sql.TextClause` constructs.
|
| 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.
|
| For a :class:`_expression.TextualSelect` construct, the collection
| contains the :class:`_expression.ColumnElement` objects that were
| passed to the constructor, typically via the
| :meth:`_expression.TextClause.columns` method.
|
|
| .. versionadded:: 1.4
|
| set_label_style(self, style: 'SelectLabelStyle') -> 'TextualSelect'
| Return a new selectable with the specified label style.
|
| Implemented by subclasses.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'_traverse_internals': '_TraverseInternalsType'}
|
| __visit_name__ = 'textual_select'
|
| is_select = True
|
| is_text = True
|
| ----------------------------------------------------------------------
| Methods inherited from SelectBase:
|
| alias(self, name: 'Optional[str]' = None, flat: 'bool' = False) -> 'Subquery'
| 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.
|
| as_scalar(self) -> 'ScalarSelect[Any]'
| .. 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`.
|
| exists(self) -> 'Exists'
| 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
|
| get_label_style(self) -> 'SelectLabelStyle'
| Retrieve the current label style.
|
| Implemented by subclasses.
|
| label(self, name: 'Optional[str]') -> 'Label[Any]'
| Return a 'scalar' representation of this selectable, embedded as a
| subquery with a label.
|
| .. seealso::
|
| :meth:`_expression.SelectBase.scalar_subquery`.
|
| 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.
|
| scalar_subquery(self) -> 'ScalarSelect[Any]'
| 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
|
| select(self, *arg: 'Any', **kw: 'Any') -> 'Select[Any]'
| .. 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.
|
| subquery(self, name: 'Optional[str]' = None) -> '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:
|
| .. sourcecode:: sql
|
| 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:
|
| .. sourcecode:: sql
|
| 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
|
| ----------------------------------------------------------------------
| Readonly properties inherited from SelectBase:
|
| c
| .. 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.
|
| columns
|
| 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`
|
| ----------------------------------------------------------------------
| Data descriptors inherited from SelectBase:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.base.Executable:
|
| execution_options(self, **kw: 'Any') -> 'Self'
| Set non-SQL options for the statement which take effect during
| execution.
|
| Execution options can be set at many scopes, including per-statement,
| per-connection, or per execution, using methods such as
| :meth:`_engine.Connection.execution_options` and parameters which
| accept a dictionary of options such as
| :paramref:`_engine.Connection.execute.execution_options` and
| :paramref:`_orm.Session.execute.execution_options`.
|
| The primary characteristic of an execution option, as opposed to
| other kinds of options such as ORM loader options, is that
| **execution options never affect the compiled SQL of a query, only
| things that affect how the SQL statement itself is invoked or how
| results are fetched**. That is, execution options are not part of
| what's accommodated by SQL compilation nor are they considered part of
| the cached state of a statement.
|
| The :meth:`_sql.Executable.execution_options` method is
| :term:`generative`, as
| is the case for the method as applied to the :class:`_engine.Engine`
| and :class:`_orm.Query` objects, which means when the method is called,
| a copy of the object is returned, which applies the given parameters to
| that new copy, but leaves the original unchanged::
|
| statement = select(table.c.x, table.c.y)
| new_statement = statement.execution_options(my_option=True)
|
| An exception to this behavior is the :class:`_engine.Connection`
| object, where the :meth:`_engine.Connection.execution_options` method
| is explicitly **not** generative.
|
| The kinds of options that may be passed to
| :meth:`_sql.Executable.execution_options` and other related methods and
| parameter dictionaries include parameters that are explicitly consumed
| by SQLAlchemy Core or ORM, as well as arbitrary keyword arguments not
| defined by SQLAlchemy, which means the methods and/or parameter
| dictionaries may be used for user-defined parameters that interact with
| custom code, which may access the parameters using methods such as
| :meth:`_sql.Executable.get_execution_options` and
| :meth:`_engine.Connection.get_execution_options`, or within selected
| event hooks using a dedicated ``execution_options`` event parameter
| such as
| :paramref:`_events.ConnectionEvents.before_execute.execution_options`
| or :attr:`_orm.ORMExecuteState.execution_options`, e.g.::
|
| from sqlalchemy import event
|
|
| @event.listens_for(some_engine, "before_execute")
| def _process_opt(conn, statement, multiparams, params, execution_options):
| "run a SQL function before invoking a statement"
|
| if execution_options.get("do_special_thing", False):
| conn.exec_driver_sql("run_special_function()")
|
| Within the scope of options that are explicitly recognized by
| SQLAlchemy, most apply to specific classes of objects and not others.
| The most common execution options include:
|
| * :paramref:`_engine.Connection.execution_options.isolation_level` -
| sets the isolation level for a connection or a class of connections
| via an :class:`_engine.Engine`. This option is accepted only
| by :class:`_engine.Connection` or :class:`_engine.Engine`.
|
| * :paramref:`_engine.Connection.execution_options.stream_results` -
| indicates results should be fetched using a server side cursor;
| this option is accepted by :class:`_engine.Connection`, by the
| :paramref:`_engine.Connection.execute.execution_options` parameter
| on :meth:`_engine.Connection.execute`, and additionally by
| :meth:`_sql.Executable.execution_options` on a SQL statement object,
| as well as by ORM constructs like :meth:`_orm.Session.execute`.
|
| * :paramref:`_engine.Connection.execution_options.compiled_cache` -
| indicates a dictionary that will serve as the
| :ref:`SQL compilation cache <sql_caching>`
| for a :class:`_engine.Connection` or :class:`_engine.Engine`, as
| well as for ORM methods like :meth:`_orm.Session.execute`.
| Can be passed as ``None`` to disable caching for statements.
| This option is not accepted by
| :meth:`_sql.Executable.execution_options` as it is inadvisable to
| carry along a compilation cache within a statement object.
|
| * :paramref:`_engine.Connection.execution_options.schema_translate_map`
| - a mapping of schema names used by the
| :ref:`Schema Translate Map <schema_translating>` feature, accepted
| by :class:`_engine.Connection`, :class:`_engine.Engine`,
| :class:`_sql.Executable`, as well as by ORM constructs
| like :meth:`_orm.Session.execute`.
|
| .. seealso::
|
| :meth:`_engine.Connection.execution_options`
|
| :paramref:`_engine.Connection.execute.execution_options`
|
| :paramref:`_orm.Session.execute.execution_options`
|
| :ref:`orm_queryguide_execution_options` - documentation on all
| ORM-specific execution options
|
| get_execution_options(self) -> '_ExecuteOptions'
| Get the non-SQL options which will take effect during execution.
|
| .. versionadded:: 1.3
|
| .. seealso::
|
| :meth:`.Executable.execution_options`
|
| options(self, *options: 'ExecutableOption') -> 'Self'
| Apply options to this statement.
|
| In the general sense, options are any kind of Python object
| that can be interpreted by the SQL compiler for the statement.
| These options can be consumed by specific dialects or specific kinds
| of compilers.
|
| The most commonly known kind of option are the ORM level options
| that apply "eager load" and other loading behaviors to an ORM
| query. However, options can theoretically be used for many other
| purposes.
|
| For background on specific kinds of options for specific kinds of
| statements, refer to the documentation for those option objects.
|
| .. versionchanged:: 1.4 - added :meth:`.Executable.options` to
| Core statement objects towards the goal of allowing unified
| Core / ORM querying capabilities.
|
| .. seealso::
|
| :ref:`loading_columns` - refers to options specific to the usage
| of ORM queries
|
| :ref:`relationship_loader_options` - refers to options specific
| to the usage of ORM queries
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.base.Executable:
|
| is_delete = False
|
| is_dml = False
|
| is_from_statement = False
|
| is_insert = False
|
| is_update = False
|
| supports_execution = True
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.AllowsLambdaRole:
|
| allows_lambda = True
|
| ----------------------------------------------------------------------
| Methods inherited from HasCTE:
|
| add_cte(self, *ctes: 'CTE', nest_here: 'bool' = False) -> 'Self'
| Add one or more :class:`_sql.CTE` constructs to this statement.
|
| This method will associate the given :class:`_sql.CTE` constructs with
| the parent statement such that they will each be unconditionally
| rendered in the WITH clause of the final statement, even if not
| referenced elsewhere within the statement or any sub-selects.
|
| The optional :paramref:`.HasCTE.add_cte.nest_here` parameter when set
| to True will have the effect that each given :class:`_sql.CTE` will
| render in a WITH clause rendered directly along with this statement,
| rather than being moved to the top of the ultimate rendered statement,
| even if this statement is rendered as a subquery within a larger
| statement.
|
| This method has two general uses. One is to embed CTE statements that
| serve some purpose without being referenced explicitly, such as the use
| case of embedding a DML statement such as an INSERT or UPDATE as a CTE
| inline with a primary statement that may draw from its results
| indirectly. The other is to provide control over the exact placement
| of a particular series of CTE constructs that should remain rendered
| directly in terms of a particular statement that may be nested in a
| larger statement.
|
| E.g.::
|
| from sqlalchemy import table, column, select
|
| t = table("t", column("c1"), column("c2"))
|
| ins = t.insert().values({"c1": "x", "c2": "y"}).cte()
|
| stmt = select(t).add_cte(ins)
|
| Would render:
|
| .. sourcecode:: sql
|
| WITH anon_1 AS (
| INSERT INTO t (c1, c2) VALUES (:param_1, :param_2)
| )
| SELECT t.c1, t.c2
| FROM t
|
| Above, the "anon_1" CTE is not referenced in the SELECT
| statement, however still accomplishes the task of running an INSERT
| statement.
|
| Similarly in a DML-related context, using the PostgreSQL
| :class:`_postgresql.Insert` construct to generate an "upsert"::
|
| from sqlalchemy import table, column
| from sqlalchemy.dialects.postgresql import insert
|
| t = table("t", column("c1"), column("c2"))
|
| delete_statement_cte = t.delete().where(t.c.c1 < 1).cte("deletions")
|
| insert_stmt = insert(t).values({"c1": 1, "c2": 2})
| update_statement = insert_stmt.on_conflict_do_update(
| index_elements=[t.c.c1],
| set_={
| "c1": insert_stmt.excluded.c1,
| "c2": insert_stmt.excluded.c2,
| },
| ).add_cte(delete_statement_cte)
|
| print(update_statement)
|
| The above statement renders as:
|
| .. sourcecode:: sql
|
| WITH deletions AS (
| DELETE FROM t WHERE t.c1 < %(c1_1)s
| )
| INSERT INTO t (c1, c2) VALUES (%(c1)s, %(c2)s)
| ON CONFLICT (c1) DO UPDATE SET c1 = excluded.c1, c2 = excluded.c2
|
| .. versionadded:: 1.4.21
|
| :param \*ctes: zero or more :class:`.CTE` constructs.
|
| .. versionchanged:: 2.0 Multiple CTE instances are accepted
|
| :param nest_here: if True, the given CTE or CTEs will be rendered
| as though they specified the :paramref:`.HasCTE.cte.nesting` flag
| to ``True`` when they were added to this :class:`.HasCTE`.
| Assuming the given CTEs are not referenced in an outer-enclosing
| statement as well, the CTEs given should render at the level of
| this statement when this flag is given.
|
| .. versionadded:: 2.0
|
| .. seealso::
|
| :paramref:`.HasCTE.cte.nesting`
|
| cte(self, name: 'Optional[str]' = None, recursive: 'bool' = False, nesting: 'bool' = False) -> 'CTE'
| Return a new :class:`_expression.CTE`,
| or Common Table Expression instance.
|
| Common table expressions are a SQL standard whereby SELECT
| statements can draw upon secondary statements specified along
| with the primary statement, using a clause called "WITH".
| Special semantics regarding UNION can also be employed to
| allow "recursive" queries, where a SELECT statement can draw
| upon the set of rows that have previously been selected.
|
| CTEs can also be applied to DML constructs UPDATE, INSERT
| and DELETE on some databases, both as a source of CTE rows
| when combined with RETURNING, as well as a consumer of
| CTE rows.
|
| SQLAlchemy detects :class:`_expression.CTE` objects, which are treated
| similarly to :class:`_expression.Alias` objects, as special elements
| to be delivered to the FROM clause of the statement as well
| as to a WITH clause at the top of the statement.
|
| For special prefixes such as PostgreSQL "MATERIALIZED" and
| "NOT MATERIALIZED", the :meth:`_expression.CTE.prefix_with`
| method may be
| used to establish these.
|
| .. versionchanged:: 1.3.13 Added support for prefixes.
| In particular - MATERIALIZED and NOT MATERIALIZED.
|
| :param name: name given to the common table expression. Like
| :meth:`_expression.FromClause.alias`, the name can be left as
| ``None`` in which case an anonymous symbol will be used at query
| compile time.
| :param recursive: if ``True``, will render ``WITH RECURSIVE``.
| A recursive common table expression is intended to be used in
| conjunction with UNION ALL in order to derive rows
| from those already selected.
| :param nesting: if ``True``, will render the CTE locally to the
| statement in which it is referenced. For more complex scenarios,
| the :meth:`.HasCTE.add_cte` method using the
| :paramref:`.HasCTE.add_cte.nest_here`
| parameter may also be used to more carefully
| control the exact placement of a particular CTE.
|
| .. versionadded:: 1.4.24
|
| .. seealso::
|
| :meth:`.HasCTE.add_cte`
|
| The following examples include two from PostgreSQL's documentation at
| https://www.postgresql.org/docs/current/static/queries-with.html,
| as well as additional examples.
|
| Example 1, non recursive::
|
| from sqlalchemy import (
| Table,
| Column,
| String,
| Integer,
| MetaData,
| select,
| func,
| )
|
| metadata = MetaData()
|
| orders = Table(
| "orders",
| metadata,
| Column("region", String),
| Column("amount", Integer),
| Column("product", String),
| Column("quantity", Integer),
| )
|
| regional_sales = (
| select(orders.c.region, func.sum(orders.c.amount).label("total_sales"))
| .group_by(orders.c.region)
| .cte("regional_sales")
| )
|
|
| top_regions = (
| select(regional_sales.c.region)
| .where(
| regional_sales.c.total_sales
| > select(func.sum(regional_sales.c.total_sales) / 10)
| )
| .cte("top_regions")
| )
|
| statement = (
| select(
| orders.c.region,
| orders.c.product,
| func.sum(orders.c.quantity).label("product_units"),
| func.sum(orders.c.amount).label("product_sales"),
| )
| .where(orders.c.region.in_(select(top_regions.c.region)))
| .group_by(orders.c.region, orders.c.product)
| )
|
| result = conn.execute(statement).fetchall()
|
| Example 2, WITH RECURSIVE::
|
| from sqlalchemy import (
| Table,
| Column,
| String,
| Integer,
| MetaData,
| select,
| func,
| )
|
| metadata = MetaData()
|
| parts = Table(
| "parts",
| metadata,
| Column("part", String),
| Column("sub_part", String),
| Column("quantity", Integer),
| )
|
| included_parts = (
| select(parts.c.sub_part, parts.c.part, parts.c.quantity)
| .where(parts.c.part == "our part")
| .cte(recursive=True)
| )
|
|
| incl_alias = included_parts.alias()
| parts_alias = parts.alias()
| included_parts = included_parts.union_all(
| select(
| parts_alias.c.sub_part, parts_alias.c.part, parts_alias.c.quantity
| ).where(parts_alias.c.part == incl_alias.c.sub_part)
| )
|
| statement = select(
| included_parts.c.sub_part,
| func.sum(included_parts.c.quantity).label("total_quantity"),
| ).group_by(included_parts.c.sub_part)
|
| result = conn.execute(statement).fetchall()
|
| Example 3, an upsert using UPDATE and INSERT with CTEs::
|
| from datetime import date
| from sqlalchemy import (
| MetaData,
| Table,
| Column,
| Integer,
| Date,
| select,
| literal,
| and_,
| exists,
| )
|
| metadata = MetaData()
|
| visitors = Table(
| "visitors",
| metadata,
| Column("product_id", Integer, primary_key=True),
| Column("date", Date, primary_key=True),
| Column("count", Integer),
| )
|
| # add 5 visitors for the product_id == 1
| product_id = 1
| day = date.today()
| count = 5
|
| update_cte = (
| visitors.update()
| .where(
| and_(visitors.c.product_id == product_id, visitors.c.date == day)
| )
| .values(count=visitors.c.count + count)
| .returning(literal(1))
| .cte("update_cte")
| )
|
| upsert = visitors.insert().from_select(
| [visitors.c.product_id, visitors.c.date, visitors.c.count],
| select(literal(product_id), literal(day), literal(count)).where(
| ~exists(update_cte.select())
| ),
| )
|
| connection.execute(upsert)
|
| Example 4, Nesting CTE (SQLAlchemy 1.4.24 and above)::
|
| value_a = select(literal("root").label("n")).cte("value_a")
|
| # A nested CTE with the same name as the root one
| value_a_nested = select(literal("nesting").label("n")).cte(
| "value_a", nesting=True
| )
|
| # Nesting CTEs takes ascendency locally
| # over the CTEs at a higher level
| value_b = select(value_a_nested.c.n).cte("value_b")
|
| value_ab = select(value_a.c.n.label("a"), value_b.c.n.label("b"))
|
| The above query will render the second CTE nested inside the first,
| shown with inline parameters below as:
|
| .. sourcecode:: sql
|
| WITH
| value_a AS
| (SELECT 'root' AS n),
| value_b AS
| (WITH value_a AS
| (SELECT 'nesting' AS n)
| SELECT value_a.n AS n FROM value_a)
| SELECT value_a.n AS a, value_b.n AS b
| FROM value_a, value_b
|
| The same CTE can be set up using the :meth:`.HasCTE.add_cte` method
| as follows (SQLAlchemy 2.0 and above)::
|
| value_a = select(literal("root").label("n")).cte("value_a")
|
| # A nested CTE with the same name as the root one
| value_a_nested = select(literal("nesting").label("n")).cte("value_a")
|
| # Nesting CTEs takes ascendency locally
| # over the CTEs at a higher level
| value_b = (
| select(value_a_nested.c.n)
| .add_cte(value_a_nested, nest_here=True)
| .cte("value_b")
| )
|
| value_ab = select(value_a.c.n.label("a"), value_b.c.n.label("b"))
|
| Example 5, Non-Linear CTE (SQLAlchemy 1.4.28 and above)::
|
| edge = Table(
| "edge",
| metadata,
| Column("id", Integer, primary_key=True),
| Column("left", Integer),
| Column("right", Integer),
| )
|
| root_node = select(literal(1).label("node")).cte("nodes", recursive=True)
|
| left_edge = select(edge.c.left).join(
| root_node, edge.c.right == root_node.c.node
| )
| right_edge = select(edge.c.right).join(
| root_node, edge.c.left == root_node.c.node
| )
|
| subgraph_cte = root_node.union(left_edge, right_edge)
|
| subgraph = select(subgraph_cte)
|
| The above query will render 2 UNIONs inside the recursive CTE:
|
| .. sourcecode:: sql
|
| WITH RECURSIVE nodes(node) AS (
| SELECT 1 AS node
| UNION
| SELECT edge."left" AS "left"
| FROM edge JOIN nodes ON edge."right" = nodes.node
| UNION
| SELECT edge."right" AS "right"
| FROM edge JOIN nodes ON edge."left" = nodes.node
| )
| SELECT nodes.node FROM nodes
|
| .. seealso::
|
| :meth:`_orm.Query.cte` - ORM version of
| :meth:`_expression.HasCTE.cte`.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from HasCTE:
|
| name_cte_columns = False
|
| ----------------------------------------------------------------------
| Methods inherited from Selectable:
|
| 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.
|
| 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`.
|
| .. deprecated:: 1.4 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.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from Selectable:
|
| is_selectable = True
|
| ----------------------------------------------------------------------
| Methods inherited from ReturnsRows:
|
| 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.
|
| ----------------------------------------------------------------------
| Readonly properties inherited from ReturnsRows:
|
| selectable
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.SQLRole:
|
| uses_inspection = False
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.elements.ClauseElement:
|
| __bool__(self)
|
| __getstate__(self)
| Helper for pickle.
|
| __invert__(self)
|
| __repr__(self)
| Return repr(self).
|
| compare(self, other: 'ClauseElement', **kw: 'Any') -> 'bool'
| Compare this :class:`_expression.ClauseElement` to
| the given :class:`_expression.ClauseElement`.
|
| Subclasses should override the default behavior, which is a
| straight identity comparison.
|
| \**kw are arguments consumed by subclass ``compare()`` methods and
| may be used to modify the criteria for comparison
| (see :class:`_expression.ColumnElement`).
|
| description(...)
|
| entity_namespace(...)
|
| params(self, _ClauseElement__optionaldict: 'Optional[Mapping[str, Any]]' = None, **kwargs: 'Any') -> 'Self'
| Return a copy with :func:`_expression.bindparam` elements
| replaced.
|
| Returns a copy of this ClauseElement with
| :func:`_expression.bindparam`
| elements replaced with values taken from the given dictionary::
|
| >>> clause = column("x") + bindparam("foo")
| >>> print(clause.compile().params)
| {'foo':None}
| >>> print(clause.params({"foo": 7}).compile().params)
| {'foo':7}
|
| self_group(self, against: 'Optional[OperatorType]' = None) -> 'ClauseElement'
| 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.
|
| unique_params(self, _ClauseElement__optionaldict: 'Optional[Dict[str, Any]]' = None, **kwargs: 'Any') -> 'Self'
| Return a copy with :func:`_expression.bindparam` elements
| replaced.
|
| Same functionality as :meth:`_expression.ClauseElement.params`,
| except adds `unique=True`
| to affected bind parameters so that multiple statements can be
| used.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.elements.ClauseElement:
|
| is_clause_element = True
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.cache_key.HasCacheKey:
|
| inherit_cache = None
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_instancemethod(fn: '_F') -> '_F'
| Decorate a method memoize its return value.
|
| :meta private:
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_attribute = <class 'sqlalchemy.util.langhelpers.HasMemoized.m...
| A read-only @property that is only evaluated once.
|
| :meta private:
|
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.visitors.HasTraverseInternals:
|
| get_children(self, *, omit_attrs: 'Tuple[str, ...]' = (), **kw: 'Any') -> 'Iterable[HasTraverseInternals]'
| Return immediate child :class:`.visitors.HasTraverseInternals`
| elements of this :class:`.visitors.HasTraverseInternals`.
|
| This is used for visit traversal.
|
| \**kw may contain flags that change the collection that is
| returned, for example to return a subset of items in order to
| cut down on larger traversals, or to return child items from a
| different context (such as schema-level collections instead of
| clause-level).
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.elements.CompilerElement:
|
| __str__(self) -> 'str'
| Return str(self).
|
| compile(self, bind: 'Optional[_HasDialect]' = None, dialect: 'Optional[Dialect]' = None, **kw: 'Any') -> 'Compiled'
| Compile this SQL expression.
|
| The return value is a :class:`~.Compiled` object.
| Calling ``str()`` or ``unicode()`` on the returned value will yield a
| string representation of the result. The
| :class:`~.Compiled` object also can return a
| dictionary of bind parameter names and values
| using the ``params`` accessor.
|
| :param bind: An :class:`.Connection` or :class:`.Engine` which
| can provide a :class:`.Dialect` in order to generate a
| :class:`.Compiled` object. If the ``bind`` and
| ``dialect`` parameters are both omitted, a default SQL compiler
| is used.
|
| :param column_keys: Used for INSERT and UPDATE statements, a list of
| column names which should be present in the VALUES clause of the
| compiled statement. If ``None``, all columns from the target table
| object are rendered.
|
| :param dialect: A :class:`.Dialect` instance which can generate
| a :class:`.Compiled` object. This argument takes precedence over
| the ``bind`` argument.
|
| :param compile_kwargs: optional dictionary of additional parameters
| that will be passed through to the compiler within all "visit"
| methods. This allows any custom flag to be passed through to
| a custom compilation construct, for example. It is also used
| for the case of passing the ``literal_binds`` flag through::
|
| from sqlalchemy.sql import table, column, select
|
| t = table("t", column("x"))
|
| s = select(t).where(t.c.x == 5)
|
| print(s.compile(compile_kwargs={"literal_binds": True}))
|
| .. seealso::
|
| :ref:`faq_sql_expression_string`
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.elements.CompilerElement:
|
| stringify_dialect = 'default'
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.visitors.Visitable:
|
| __class_getitem__(key: 'Any') -> 'Any'
|
| __init_subclass__() -> 'None'
| This method is called when a class is subclassed.
|
| The default implementation does nothing. It may be
| overridden to extend subclasses.
sqlalchemy.Time
Python Library Documentation: class Time in module sqlalchemy.sql.sqltypes
class Time(_RenderISO8601NoT, HasExpressionLookup, sqlalchemy.sql.type_api.TypeEngine)
| Time(timezone: 'bool' = False)
|
| A type for ``datetime.time()`` objects.
|
| Method resolution order:
| Time
| _RenderISO8601NoT
| HasExpressionLookup
| sqlalchemy.sql.type_api.TypeEngineMixin
| sqlalchemy.sql.type_api.TypeEngine
| sqlalchemy.sql.visitors.Visitable
| typing.Generic
| builtins.object
|
| Methods defined here:
|
| __init__(self, timezone: 'bool' = False)
| Initialize self. See help(type(self)) for accurate signature.
|
| get_dbapi_type(self, dbapi)
| Return the corresponding type object from the underlying DB-API, if
| any.
|
| This can be useful for calling ``setinputsizes()``, for example.
|
| literal_processor(self, dialect)
| Return a conversion function for processing literal values that are
| to be rendered directly without using binds.
|
| This function is used when the compiler makes use of the
| "literal_binds" flag, typically used in DDL generation as well
| as in certain scenarios where backends don't accept bound parameters.
|
| Returns a callable which will receive a literal Python value
| as the sole positional argument and will return a string representation
| to be rendered in a SQL statement.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.literal_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.literal_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_literal_param`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| ----------------------------------------------------------------------
| Readonly properties defined here:
|
| python_type
| Return the Python type object expected to be returned
| by instances of this type, if known.
|
| Basically, for those types which enforce a return type,
| or are known across the board to do such for all common
| DBAPIs (like ``int`` for example), will return that type.
|
| If a return type is not defined, raises
| ``NotImplementedError``.
|
| Note that any type also accommodates NULL in SQL which
| means you can also get back ``None`` from any type
| in practice.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| __parameters__ = ()
|
| __visit_name__ = 'time'
|
| ----------------------------------------------------------------------
| Data descriptors inherited from _RenderISO8601NoT:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from HasExpressionLookup:
|
| Comparator = <class 'sqlalchemy.sql.sqltypes.HasExpressionLookup.Compa...
|
| comparator_factory = <class 'sqlalchemy.sql.sqltypes.HasExpressionLook...
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.type_api.TypeEngine:
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| __str__(self) -> 'str'
| Return str(self).
|
| adapt(self, cls: 'Type[Union[TypeEngine[Any], TypeEngineMixin]]', **kw: 'Any') -> 'TypeEngine[Any]'
| Produce an "adapted" form of this type, given an "impl" class
| to work with.
|
| This method is used internally to associate generic
| types with "implementation" types that are specific to a particular
| dialect.
|
| as_generic(self, allow_nulltype: 'bool' = False) -> 'TypeEngine[_T]'
| Return an instance of the generic type corresponding to this type
| using heuristic rule. The method may be overridden if this
| heuristic rule is not sufficient.
|
| >>> from sqlalchemy.dialects.mysql import INTEGER
| >>> INTEGER(display_width=4).as_generic()
| Integer()
|
| >>> from sqlalchemy.dialects.mysql import NVARCHAR
| >>> NVARCHAR(length=100).as_generic()
| Unicode(length=100)
|
| .. versionadded:: 1.4.0b2
|
|
| .. seealso::
|
| :ref:`metadata_reflection_dbagnostic_types` - describes the
| use of :meth:`_types.TypeEngine.as_generic` in conjunction with
| the :meth:`_sql.DDLEvents.column_reflect` event, which is its
| intended use.
|
| bind_expression(self, bindvalue: 'BindParameter[_T]') -> 'Optional[ColumnElement[_T]]'
| Given a bind value (i.e. a :class:`.BindParameter` instance),
| return a SQL expression in its place.
|
| This is typically a SQL function that wraps the existing bound
| parameter within the statement. It is used for special data types
| that require literals being wrapped in some special database function
| in order to coerce an application-level value into a database-specific
| format. It is the SQL analogue of the
| :meth:`.TypeEngine.bind_processor` method.
|
| This method is called during the **SQL compilation** phase of a
| statement, when rendering a SQL string. It is **not** called
| against specific values.
|
| Note that this method, when implemented, should always return
| the exact same structure, without any conditional logic, as it
| may be used in an executemany() call against an arbitrary number
| of bound parameter sets.
|
| .. note::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.bind_expression`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.bind_expression`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.bind_expression`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| .. seealso::
|
| :ref:`types_sql_value_processing`
|
| bind_processor(self, dialect: 'Dialect') -> 'Optional[_BindProcessorType[_T]]'
| Return a conversion function for processing bind values.
|
| Returns a callable which will receive a bind parameter value
| as the sole positional argument and will return a value to
| send to the DB-API.
|
| If processing is not necessary, the method should return ``None``.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.bind_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.bind_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_bind_param`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
|
| :param dialect: Dialect instance in use.
|
| coerce_compared_value(self, op: 'Optional[OperatorType]', value: 'Any') -> 'TypeEngine[Any]'
| Suggest a type for a 'coerced' Python value in an expression.
|
| Given an operator and value, gives the type a chance
| to return a type which the value should be coerced into.
|
| The default behavior here is conservative; if the right-hand
| side is already coerced into a SQL type based on its
| Python type, it is usually left alone.
|
| End-user functionality extension here should generally be via
| :class:`.TypeDecorator`, which provides more liberal behavior in that
| it defaults to coercing the other side of the expression into this
| type, thus applying special Python conversions above and beyond those
| needed by the DBAPI to both ides. It also provides the public method
| :meth:`.TypeDecorator.coerce_compared_value` which is intended for
| end-user customization of this behavior.
|
| column_expression(self, colexpr: 'ColumnElement[_T]') -> 'Optional[ColumnElement[_T]]'
| Given a SELECT column expression, return a wrapping SQL expression.
|
| This is typically a SQL function that wraps a column expression
| as rendered in the columns clause of a SELECT statement.
| It is used for special data types that require
| columns to be wrapped in some special database function in order
| to coerce the value before being sent back to the application.
| It is the SQL analogue of the :meth:`.TypeEngine.result_processor`
| method.
|
| .. note:: The :func:`.TypeEngine.column_expression` method is applied
| only to the **outermost columns clause** of a SELECT statement, that
| is, the columns that are to be delivered directly into the returned
| result rows. It does **not** apply to the columns clause inside
| of subqueries. This necessarily avoids double conversions against
| the column and only runs the conversion when ready to be returned
| to the client.
|
| This method is called during the **SQL compilation** phase of a
| statement, when rendering a SQL string. It is **not** called
| against specific values.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.column_expression`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.column_expression`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.column_expression`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
|
| .. seealso::
|
| :ref:`types_sql_value_processing`
|
| compare_values(self, x: 'Any', y: 'Any') -> 'bool'
| Compare two values for equality.
|
| compile(self, dialect: 'Optional[Dialect]' = None) -> 'str'
| Produce a string-compiled form of this :class:`.TypeEngine`.
|
| When called with no arguments, uses a "default" dialect
| to produce a string result.
|
| :param dialect: a :class:`.Dialect` instance.
|
| copy(self, **kw: 'Any') -> 'Self'
|
| copy_value(self, value: 'Any') -> 'Any'
|
| dialect_impl(self, dialect: 'Dialect') -> 'TypeEngine[_T]'
| Return a dialect-specific implementation for this
| :class:`.TypeEngine`.
|
| evaluates_none(self) -> 'Self'
| Return a copy of this type which has the
| :attr:`.should_evaluate_none` flag set to True.
|
| E.g.::
|
| Table(
| "some_table",
| metadata,
| Column(
| String(50).evaluates_none(),
| nullable=True,
| server_default="no value",
| ),
| )
|
| The ORM uses this flag to indicate that a positive value of ``None``
| is passed to the column in an INSERT statement, rather than omitting
| the column from the INSERT statement which has the effect of firing
| off column-level defaults. It also allows for types which have
| special behavior associated with the Python None value to indicate
| that the value doesn't necessarily translate into SQL NULL; a
| prime example of this is a JSON type which may wish to persist the
| JSON value ``'null'``.
|
| In all cases, the actual NULL SQL value can be always be
| persisted in any column by using
| the :obj:`_expression.null` SQL construct in an INSERT statement
| or associated with an ORM-mapped attribute.
|
| .. note::
|
| The "evaluates none" flag does **not** apply to a value
| of ``None`` passed to :paramref:`_schema.Column.default` or
| :paramref:`_schema.Column.server_default`; in these cases,
| ``None``
| still means "no default".
|
| .. seealso::
|
| :ref:`session_forcing_null` - in the ORM documentation
|
| :paramref:`.postgresql.JSON.none_as_null` - PostgreSQL JSON
| interaction with this flag.
|
| :attr:`.TypeEngine.should_evaluate_none` - class-level flag
|
| result_processor(self, dialect: 'Dialect', coltype: 'object') -> 'Optional[_ResultProcessorType[_T]]'
| Return a conversion function for processing result row values.
|
| Returns a callable which will receive a result row column
| value as the sole positional argument and will return a value
| to return to the user.
|
| If processing is not necessary, the method should return ``None``.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.result_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.result_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_result_value`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| :param dialect: Dialect instance in use.
|
| :param coltype: DBAPI coltype argument received in cursor.description.
|
| with_variant(self, type_: '_TypeEngineArgument[Any]', *dialect_names: 'str') -> 'Self'
| Produce a copy of this type object that will utilize the given
| type when applied to the dialect of the given name.
|
| e.g.::
|
| from sqlalchemy.types import String
| from sqlalchemy.dialects import mysql
|
| string_type = String()
|
| string_type = string_type.with_variant(
| mysql.VARCHAR(collation="foo"), "mysql", "mariadb"
| )
|
| The variant mapping indicates that when this type is
| interpreted by a specific dialect, it will instead be
| transmuted into the given type, rather than using the
| primary type.
|
| .. versionchanged:: 2.0 the :meth:`_types.TypeEngine.with_variant`
| method now works with a :class:`_types.TypeEngine` object "in
| place", returning a copy of the original type rather than returning
| a wrapping object; the ``Variant`` class is no longer used.
|
| :param type\_: a :class:`.TypeEngine` that will be selected
| as a variant from the originating type, when a dialect
| of the given name is in use.
| :param \*dialect_names: one or more base names of the dialect which
| uses this type. (i.e. ``'postgresql'``, ``'mysql'``, etc.)
|
| .. versionchanged:: 2.0 multiple dialect names can be specified
| for one variant.
|
| .. seealso::
|
| :ref:`types_with_variant` - illustrates the use of
| :meth:`_types.TypeEngine.with_variant`.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.type_api.TypeEngine:
|
| __orig_bases__ = (<class 'sqlalchemy.sql.visitors.Visitable'>, typing....
|
| hashable = True
|
| render_bind_cast = False
|
| render_literal_cast = False
|
| should_evaluate_none = False
|
| sort_key_function = None
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.visitors.Visitable:
|
| __class_getitem__(key: 'Any') -> 'Any'
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__() -> 'None'
| This method is called when a class is subclassed.
|
| The default implementation does nothing. It may be
| overridden to extend subclasses.
sqlalchemy.Transaction
Python Library Documentation: class Transaction in module sqlalchemy.engine.base
class Transaction(sqlalchemy.engine.util.TransactionalContext)
| Transaction(connection: 'Connection')
|
| Represent a database transaction in progress.
|
| The :class:`.Transaction` object is procured by
| calling the :meth:`_engine.Connection.begin` method of
| :class:`_engine.Connection`::
|
| from sqlalchemy import create_engine
|
| engine = create_engine("postgresql+psycopg2://scott:tiger@localhost/test")
| connection = engine.connect()
| trans = connection.begin()
| connection.execute(text("insert into x (a, b) values (1, 2)"))
| trans.commit()
|
| The object provides :meth:`.rollback` and :meth:`.commit`
| methods in order to control transaction boundaries. It
| also implements a context manager interface so that
| the Python ``with`` statement can be used with the
| :meth:`_engine.Connection.begin` method::
|
| with connection.begin():
| connection.execute(text("insert into x (a, b) values (1, 2)"))
|
| The Transaction object is **not** threadsafe.
|
| .. seealso::
|
| :meth:`_engine.Connection.begin`
|
| :meth:`_engine.Connection.begin_twophase`
|
| :meth:`_engine.Connection.begin_nested`
|
| .. index::
| single: thread safety; Transaction
|
| Method resolution order:
| Transaction
| sqlalchemy.engine.util.TransactionalContext
| builtins.object
|
| Methods defined here:
|
| __init__(self, connection: 'Connection')
| Initialize self. See help(type(self)) for accurate signature.
|
| close(self) -> 'None'
| Close this :class:`.Transaction`.
|
| If this transaction is the base transaction in a begin/commit
| nesting, the transaction will rollback(). Otherwise, the
| method returns.
|
| This is used to cancel a Transaction without affecting the scope of
| an enclosing transaction.
|
| commit(self) -> 'None'
| Commit this :class:`.Transaction`.
|
| The implementation of this may vary based on the type of transaction in
| use:
|
| * For a simple database transaction (e.g. :class:`.RootTransaction`),
| it corresponds to a COMMIT.
|
| * For a :class:`.NestedTransaction`, it corresponds to a
| "RELEASE SAVEPOINT" operation.
|
| * For a :class:`.TwoPhaseTransaction`, DBAPI-specific methods for two
| phase transactions may be used.
|
| rollback(self) -> 'None'
| Roll back this :class:`.Transaction`.
|
| The implementation of this may vary based on the type of transaction in
| use:
|
| * For a simple database transaction (e.g. :class:`.RootTransaction`),
| it corresponds to a ROLLBACK.
|
| * For a :class:`.NestedTransaction`, it corresponds to a
| "ROLLBACK TO SAVEPOINT" operation.
|
| * For a :class:`.TwoPhaseTransaction`, DBAPI-specific methods for two
| phase transactions may be used.
|
| ----------------------------------------------------------------------
| Readonly properties defined here:
|
| is_valid
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'_is_root': 'bool', 'connection': 'Connection', 'is...
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.engine.util.TransactionalContext:
|
| __enter__(self) -> 'Self'
|
| __exit__(self, type_: 'Any', value: 'Any', traceback: 'Any') -> 'None'
|
| ----------------------------------------------------------------------
| Data descriptors inherited from sqlalchemy.engine.util.TransactionalContext:
|
| __weakref__
| list of weak references to the object
sqlalchemy.True_
Python Library Documentation: class True_ in module sqlalchemy.sql.elements
class True_(sqlalchemy.sql.base.SingletonConstant, sqlalchemy.sql.roles.ConstExprRole, ColumnElement)
| True_(*arg: 'Any', **kw: 'Any') -> '_T'
|
| Represent the ``true`` keyword, or equivalent, in a SQL statement.
|
| :class:`.True_` is accessed as a constant via the
| :func:`.true` function.
|
| Method resolution order:
| True_
| sqlalchemy.sql.base.SingletonConstant
| sqlalchemy.sql.base.Immutable
| sqlalchemy.sql.roles.ConstExprRole
| ColumnElement
| sqlalchemy.sql.roles.ColumnArgumentOrKeyRole
| sqlalchemy.sql.roles.ColumnArgumentRole
| sqlalchemy.sql.roles.StatementOptionRole
| sqlalchemy.sql.roles.WhereHavingRole
| sqlalchemy.sql.roles.OnClauseRole
| sqlalchemy.sql.roles.BinaryElementRole
| sqlalchemy.sql.roles.OrderByRole
| sqlalchemy.sql.roles.ColumnsClauseRole
| sqlalchemy.sql.roles.AllowsLambdaRole
| sqlalchemy.sql.roles.ByOfRole
| sqlalchemy.sql.roles.UsesInspection
| sqlalchemy.sql.roles.ColumnListRole
| sqlalchemy.sql.roles.LimitOffsetRole
| sqlalchemy.sql.roles.DMLColumnRole
| sqlalchemy.sql.roles.DDLConstraintColumnRole
| sqlalchemy.sql.roles.DDLExpressionRole
| sqlalchemy.sql.roles.StructuralRole
| SQLColumnExpression
| SQLCoreOperations
| sqlalchemy.sql.roles.ExpressionElementRole
| sqlalchemy.sql.roles.TypedColumnsClauseRole
| typing.Generic
| sqlalchemy.sql.operators.ColumnOperators
| sqlalchemy.sql.operators.Operators
| sqlalchemy.util.langhelpers.TypingOnly
| sqlalchemy.sql.roles.SQLRole
| DQLDMLClauseElement
| ClauseElement
| sqlalchemy.sql.annotation.SupportsWrappingAnnotations
| sqlalchemy.sql.annotation.SupportsAnnotations
| sqlalchemy.sql.cache_key.MemoizedHasCacheKey
| sqlalchemy.sql.cache_key.HasCacheKey
| sqlalchemy.util.langhelpers.HasMemoized
| sqlalchemy.sql.traversals.HasCopyInternals
| sqlalchemy.sql.visitors.ExternallyTraversible
| sqlalchemy.sql.visitors.HasTraverseInternals
| CompilerElement
| sqlalchemy.sql.visitors.Visitable
| builtins.object
|
| Methods defined here:
|
| type(...)
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'_singleton': 'True_', '_traverse_internals': '_Tra...
|
| __orig_bases__ = (<class 'sqlalchemy.sql.base.SingletonConstant'>, sql...
|
| __parameters__ = ()
|
| __visit_name__ = 'true'
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.base.SingletonConstant:
|
| proxy_set(...)
|
| ----------------------------------------------------------------------
| Static methods inherited from sqlalchemy.sql.base.SingletonConstant:
|
| __new__(cls: '_T', *arg: 'Any', **kw: 'Any') -> '_T'
| Create and return a new object. See help(type) for accurate signature.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from sqlalchemy.sql.base.SingletonConstant:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.base.Immutable:
|
| params(self, *optionaldict: 'Any', **kwargs: 'Any') -> 'NoReturn'
|
| unique_params(self, *optionaldict: 'Any', **kwargs: 'Any') -> 'NoReturn'
|
| ----------------------------------------------------------------------
| Methods inherited from ColumnElement:
|
| __getattr__(self, key: 'str') -> 'Any'
|
| __setstate__(self, state)
|
| base_columns(...)
|
| cast(self, type_: '_TypeEngineArgument[_OPT]') -> 'Cast[_OPT]'
| Produce a type cast, i.e. ``CAST(<expression> AS <type>)``.
|
| This is a shortcut to the :func:`_expression.cast` function.
|
| .. seealso::
|
| :ref:`tutorial_casts`
|
| :func:`_expression.cast`
|
| :func:`_expression.type_coerce`
|
| comparator(...)
|
| label(self, name: 'Optional[str]') -> 'Label[_T]'
| Produce a column label, i.e. ``<columnname> AS <name>``.
|
| This is a shortcut to the :func:`_expression.label` function.
|
| If 'name' is ``None``, an anonymous label name will be generated.
|
| operate(self, op: 'operators.OperatorType', *other: 'Any', **kwargs: 'Any') -> 'ColumnElement[Any]'
| Operate on an argument.
|
| This is the lowest level of operation, raises
| :class:`NotImplementedError` by default.
|
| Overriding this on a subclass can allow common
| behavior to be applied to all operations.
| For example, overriding :class:`.ColumnOperators`
| to apply ``func.lower()`` to the left and right
| side::
|
| class MyComparator(ColumnOperators):
| def operate(self, op, other, **kwargs):
| return op(func.lower(self), func.lower(other), **kwargs)
|
| :param op: Operator callable.
| :param \*other: the 'other' side of the operation. Will
| be a single scalar for most operations.
| :param \**kwargs: modifiers. These may be passed by special
| operators such as :meth:`ColumnOperators.contains`.
|
| reverse_operate(self, op: 'operators.OperatorType', other: 'Any', **kwargs: 'Any') -> 'ColumnElement[Any]'
| Reverse operate on an argument.
|
| Usage is the same as :meth:`operate`.
|
| self_group(self, against: 'Optional[OperatorType]' = None) -> 'ColumnElement[Any]'
| 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.
|
| shares_lineage(self, othercolumn: 'ColumnElement[Any]') -> 'bool'
| Return True if the given :class:`_expression.ColumnElement`
| has a common ancestor to this :class:`_expression.ColumnElement`.
|
| ----------------------------------------------------------------------
| Readonly properties inherited from ColumnElement:
|
| anon_key_label
| .. deprecated:: 1.4 The :attr:`_expression.ColumnElement.anon_key_label` attribute is now private, and the public accessor is deprecated.
|
| anon_label
| .. deprecated:: 1.4 The :attr:`_expression.ColumnElement.anon_label` attribute is now private, and the public accessor is deprecated.
|
| expression
| Return a column expression.
|
| Part of the inspection interface; returns self.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from ColumnElement:
|
| foreign_keys = frozenset()
|
| key = None
|
| primary_key = False
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.AllowsLambdaRole:
|
| allows_lambda = True
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.UsesInspection:
|
| uses_inspection = True
|
| ----------------------------------------------------------------------
| Class methods inherited from typing.Generic:
|
| __class_getitem__(...)
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__(...)
| Function to initialize subclasses.
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.operators.ColumnOperators:
|
| __add__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``+`` operator.
|
| In a column context, produces the clause ``a + b``
| if the parent object has non-string affinity.
| If the parent object has a string affinity,
| produces the concatenation operator, ``a || b`` -
| see :meth:`.ColumnOperators.concat`.
|
| __contains__(self, other: 'Any') -> 'ColumnOperators'
|
| __eq__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``==`` operator.
|
| In a column context, produces the clause ``a = b``.
| If the target is ``None``, produces ``a IS NULL``.
|
| __floordiv__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``//`` operator.
|
| In a column context, produces the clause ``a / b``,
| which is the same as "truediv", but considers the result
| type to be integer.
|
| .. versionadded:: 2.0
|
| __ge__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``>=`` operator.
|
| In a column context, produces the clause ``a >= b``.
|
| __getitem__(self, index: 'Any') -> 'ColumnOperators'
| Implement the [] operator.
|
| This can be used by some database-specific types
| such as PostgreSQL ARRAY and HSTORE.
|
| __gt__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``>`` operator.
|
| In a column context, produces the clause ``a > b``.
|
| __hash__(self, /) from builtins.object
| Return hash(self).
|
| __le__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``<=`` operator.
|
| In a column context, produces the clause ``a <= b``.
|
| __lshift__(self, other: 'Any') -> 'ColumnOperators'
| implement the << operator.
|
| Not used by SQLAlchemy core, this is provided
| for custom operator systems which want to use
| << as an extension point.
|
| __lt__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``<`` operator.
|
| In a column context, produces the clause ``a < b``.
|
| __mod__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``%`` operator.
|
| In a column context, produces the clause ``a % b``.
|
| __mul__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``*`` operator.
|
| In a column context, produces the clause ``a * b``.
|
| __ne__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``!=`` operator.
|
| In a column context, produces the clause ``a != b``.
| If the target is ``None``, produces ``a IS NOT NULL``.
|
| __neg__(self) -> 'ColumnOperators'
| Implement the ``-`` operator.
|
| In a column context, produces the clause ``-a``.
|
| __radd__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``+`` operator in reverse.
|
| See :meth:`.ColumnOperators.__add__`.
|
| __rfloordiv__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``//`` operator in reverse.
|
| See :meth:`.ColumnOperators.__floordiv__`.
|
| __rmod__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``%`` operator in reverse.
|
| See :meth:`.ColumnOperators.__mod__`.
|
| __rmul__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``*`` operator in reverse.
|
| See :meth:`.ColumnOperators.__mul__`.
|
| __rshift__(self, other: 'Any') -> 'ColumnOperators'
| implement the >> operator.
|
| Not used by SQLAlchemy core, this is provided
| for custom operator systems which want to use
| >> as an extension point.
|
| __rsub__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``-`` operator in reverse.
|
| See :meth:`.ColumnOperators.__sub__`.
|
| __rtruediv__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``/`` operator in reverse.
|
| See :meth:`.ColumnOperators.__truediv__`.
|
| __sub__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``-`` operator.
|
| In a column context, produces the clause ``a - b``.
|
| __truediv__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``/`` operator.
|
| In a column context, produces the clause ``a / b``, and
| considers the result type to be numeric.
|
| .. versionchanged:: 2.0 The truediv operator against two integers
| is now considered to return a numeric value. Behavior on specific
| backends may vary.
|
| all_(self) -> 'ColumnOperators'
| Produce an :func:`_expression.all_` clause against the
| parent object.
|
| See the documentation for :func:`_sql.all_` for examples.
|
| .. note:: be sure to not confuse the newer
| :meth:`_sql.ColumnOperators.all_` method with the **legacy**
| version of this method, the :meth:`_types.ARRAY.Comparator.all`
| method that's specific to :class:`_types.ARRAY`, which uses a
| different calling style.
|
| any_(self) -> 'ColumnOperators'
| Produce an :func:`_expression.any_` clause against the
| parent object.
|
| See the documentation for :func:`_sql.any_` for examples.
|
| .. note:: be sure to not confuse the newer
| :meth:`_sql.ColumnOperators.any_` method with the **legacy**
| version of this method, the :meth:`_types.ARRAY.Comparator.any`
| method that's specific to :class:`_types.ARRAY`, which uses a
| different calling style.
|
| asc(self) -> 'ColumnOperators'
| Produce a :func:`_expression.asc` clause against the
| parent object.
|
| between(self, cleft: 'Any', cright: 'Any', symmetric: 'bool' = False) -> 'ColumnOperators'
| Produce a :func:`_expression.between` clause against
| the parent object, given the lower and upper range.
|
| bitwise_and(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise AND operation, typically via the ``&``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_lshift(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise LSHIFT operation, typically via the ``<<``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_not(self) -> 'ColumnOperators'
| Produce a bitwise NOT operation, typically via the ``~``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_or(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise OR operation, typically via the ``|``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_rshift(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise RSHIFT operation, typically via the ``>>``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_xor(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise XOR operation, typically via the ``^``
| operator, or ``#`` for PostgreSQL.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| collate(self, collation: 'str') -> 'ColumnOperators'
| Produce a :func:`_expression.collate` clause against
| the parent object, given the collation string.
|
| .. seealso::
|
| :func:`_expression.collate`
|
| concat(self, other: 'Any') -> 'ColumnOperators'
| Implement the 'concat' operator.
|
| In a column context, produces the clause ``a || b``,
| or uses the ``concat()`` operator on MySQL.
|
| contains(self, other: 'Any', **kw: 'Any') -> 'ColumnOperators'
| Implement the 'contains' operator.
|
| Produces a LIKE expression that tests against a match for the middle
| of a string value:
|
| .. sourcecode:: sql
|
| column LIKE '%' || <other> || '%'
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.contains("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.contains.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.contains.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.contains.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.contains("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE '%' || :param || '%' ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.contains("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE '%' || :param || '%' ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.contains.autoescape`::
|
| somecolumn.contains("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.startswith`
|
| :meth:`.ColumnOperators.endswith`
|
| :meth:`.ColumnOperators.like`
|
| desc(self) -> 'ColumnOperators'
| Produce a :func:`_expression.desc` clause against the
| parent object.
|
| distinct(self) -> 'ColumnOperators'
| Produce a :func:`_expression.distinct` clause against the
| parent object.
|
| endswith(self, other: 'Any', escape: 'Optional[str]' = None, autoescape: 'bool' = False) -> 'ColumnOperators'
| Implement the 'endswith' operator.
|
| Produces a LIKE expression that tests against a match for the end
| of a string value:
|
| .. sourcecode:: sql
|
| column LIKE '%' || <other>
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.endswith("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.endswith.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.endswith.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.endswith.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.endswith("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE '%' || :param ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.endswith("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE '%' || :param ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.endswith.autoescape`::
|
| somecolumn.endswith("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.startswith`
|
| :meth:`.ColumnOperators.contains`
|
| :meth:`.ColumnOperators.like`
|
| icontains(self, other: 'Any', **kw: 'Any') -> 'ColumnOperators'
| Implement the ``icontains`` operator, e.g. case insensitive
| version of :meth:`.ColumnOperators.contains`.
|
| Produces a LIKE expression that tests against an insensitive match
| for the middle of a string value:
|
| .. sourcecode:: sql
|
| lower(column) LIKE '%' || lower(<other>) || '%'
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.icontains("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.icontains.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.icontains.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.icontains.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.icontains("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE '%' || lower(:param) || '%' ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.icontains("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE '%' || lower(:param) || '%' ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.contains.autoescape`::
|
| somecolumn.icontains("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.contains`
|
| iendswith(self, other: 'Any', escape: 'Optional[str]' = None, autoescape: 'bool' = False) -> 'ColumnOperators'
| Implement the ``iendswith`` operator, e.g. case insensitive
| version of :meth:`.ColumnOperators.endswith`.
|
| Produces a LIKE expression that tests against an insensitive match
| for the end of a string value:
|
| .. sourcecode:: sql
|
| lower(column) LIKE '%' || lower(<other>)
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.iendswith("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.iendswith.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.iendswith.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.iendswith.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.iendswith("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE '%' || lower(:param) ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.iendswith("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE '%' || lower(:param) ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.iendswith.autoescape`::
|
| somecolumn.endswith("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.endswith`
|
| ilike(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
| Implement the ``ilike`` operator, e.g. case insensitive LIKE.
|
| In a column context, produces an expression either of the form:
|
| .. sourcecode:: sql
|
| lower(a) LIKE lower(other)
|
| Or on backends that support the ILIKE operator:
|
| .. sourcecode:: sql
|
| a ILIKE other
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.ilike("%foobar%"))
|
| :param other: expression to be compared
| :param escape: optional escape character, renders the ``ESCAPE``
| keyword, e.g.::
|
| somecolumn.ilike("foo/%bar", escape="/")
|
| .. seealso::
|
| :meth:`.ColumnOperators.like`
|
| in_(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``in`` operator.
|
| In a column context, produces the clause ``column IN <other>``.
|
| The given parameter ``other`` may be:
|
| * A list of literal values,
| e.g.::
|
| stmt.where(column.in_([1, 2, 3]))
|
| In this calling form, the list of items is converted to a set of
| bound parameters the same length as the list given:
|
| .. sourcecode:: sql
|
| WHERE COL IN (?, ?, ?)
|
| * A list of tuples may be provided if the comparison is against a
| :func:`.tuple_` containing multiple expressions::
|
| from sqlalchemy import tuple_
|
| stmt.where(tuple_(col1, col2).in_([(1, 10), (2, 20), (3, 30)]))
|
| * An empty list,
| e.g.::
|
| stmt.where(column.in_([]))
|
| In this calling form, the expression renders an "empty set"
| expression. These expressions are tailored to individual backends
| and are generally trying to get an empty SELECT statement as a
| subquery. Such as on SQLite, the expression is:
|
| .. sourcecode:: sql
|
| WHERE col IN (SELECT 1 FROM (SELECT 1) WHERE 1!=1)
|
| .. versionchanged:: 1.4 empty IN expressions now use an
| execution-time generated SELECT subquery in all cases.
|
| * A bound parameter, e.g. :func:`.bindparam`, may be used if it
| includes the :paramref:`.bindparam.expanding` flag::
|
| stmt.where(column.in_(bindparam("value", expanding=True)))
|
| In this calling form, the expression renders a special non-SQL
| placeholder expression that looks like:
|
| .. sourcecode:: sql
|
| WHERE COL IN ([EXPANDING_value])
|
| This placeholder expression is intercepted at statement execution
| time to be converted into the variable number of bound parameter
| form illustrated earlier. If the statement were executed as::
|
| connection.execute(stmt, {"value": [1, 2, 3]})
|
| The database would be passed a bound parameter for each value:
|
| .. sourcecode:: sql
|
| WHERE COL IN (?, ?, ?)
|
| .. versionadded:: 1.2 added "expanding" bound parameters
|
| If an empty list is passed, a special "empty list" expression,
| which is specific to the database in use, is rendered. On
| SQLite this would be:
|
| .. sourcecode:: sql
|
| WHERE COL IN (SELECT 1 FROM (SELECT 1) WHERE 1!=1)
|
| .. versionadded:: 1.3 "expanding" bound parameters now support
| empty lists
|
| * a :func:`_expression.select` construct, which is usually a
| correlated scalar select::
|
| stmt.where(
| column.in_(select(othertable.c.y).where(table.c.x == othertable.c.x))
| )
|
| In this calling form, :meth:`.ColumnOperators.in_` renders as given:
|
| .. sourcecode:: sql
|
| WHERE COL IN (SELECT othertable.y
| FROM othertable WHERE othertable.x = table.x)
|
| :param other: a list of literals, a :func:`_expression.select`
| construct, or a :func:`.bindparam` construct that includes the
| :paramref:`.bindparam.expanding` flag set to True.
|
| is_(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``IS`` operator.
|
| Normally, ``IS`` is generated automatically when comparing to a
| value of ``None``, which resolves to ``NULL``. However, explicit
| usage of ``IS`` may be desirable if comparing to boolean values
| on certain platforms.
|
| .. seealso:: :meth:`.ColumnOperators.is_not`
|
| is_distinct_from(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``IS DISTINCT FROM`` operator.
|
| Renders "a IS DISTINCT FROM b" on most platforms;
| on some such as SQLite may render "a IS NOT b".
|
| is_not(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``IS NOT`` operator.
|
| Normally, ``IS NOT`` is generated automatically when comparing to a
| value of ``None``, which resolves to ``NULL``. However, explicit
| usage of ``IS NOT`` may be desirable if comparing to boolean values
| on certain platforms.
|
| .. versionchanged:: 1.4 The ``is_not()`` operator is renamed from
| ``isnot()`` in previous releases. The previous name remains
| available for backwards compatibility.
|
| .. seealso:: :meth:`.ColumnOperators.is_`
|
| is_not_distinct_from(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``IS NOT DISTINCT FROM`` operator.
|
| Renders "a IS NOT DISTINCT FROM b" on most platforms;
| on some such as SQLite may render "a IS b".
|
| .. versionchanged:: 1.4 The ``is_not_distinct_from()`` operator is
| renamed from ``isnot_distinct_from()`` in previous releases.
| The previous name remains available for backwards compatibility.
|
| isnot = is_not(self, other: 'Any') -> 'ColumnOperators'
|
| isnot_distinct_from = is_not_distinct_from(self, other: 'Any') -> 'ColumnOperators'
|
| istartswith(self, other: 'Any', escape: 'Optional[str]' = None, autoescape: 'bool' = False) -> 'ColumnOperators'
| Implement the ``istartswith`` operator, e.g. case insensitive
| version of :meth:`.ColumnOperators.startswith`.
|
| Produces a LIKE expression that tests against an insensitive
| match for the start of a string value:
|
| .. sourcecode:: sql
|
| lower(column) LIKE lower(<other>) || '%'
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.istartswith("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.istartswith.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.istartswith.escape` parameter will
| establish a given character as an escape character which can be of
| use when the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.istartswith.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.istartswith("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE lower(:param) || '%' ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.istartswith("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE lower(:param) || '%' ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.istartswith.autoescape`::
|
| somecolumn.istartswith("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.startswith`
|
| like(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
| Implement the ``like`` operator.
|
| In a column context, produces the expression:
|
| .. sourcecode:: sql
|
| a LIKE other
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.like("%foobar%"))
|
| :param other: expression to be compared
| :param escape: optional escape character, renders the ``ESCAPE``
| keyword, e.g.::
|
| somecolumn.like("foo/%bar", escape="/")
|
| .. seealso::
|
| :meth:`.ColumnOperators.ilike`
|
| match(self, other: 'Any', **kwargs: 'Any') -> 'ColumnOperators'
| Implements a database-specific 'match' operator.
|
| :meth:`_sql.ColumnOperators.match` attempts to resolve to
| a MATCH-like function or operator provided by the backend.
| Examples include:
|
| * PostgreSQL - renders ``x @@ plainto_tsquery(y)``
|
| .. versionchanged:: 2.0 ``plainto_tsquery()`` is used instead
| of ``to_tsquery()`` for PostgreSQL now; for compatibility with
| other forms, see :ref:`postgresql_match`.
|
|
| * MySQL - renders ``MATCH (x) AGAINST (y IN BOOLEAN MODE)``
|
| .. seealso::
|
| :class:`_mysql.match` - MySQL specific construct with
| additional features.
|
| * Oracle Database - renders ``CONTAINS(x, y)``
| * other backends may provide special implementations.
| * Backends without any special implementation will emit
| the operator as "MATCH". This is compatible with SQLite, for
| example.
|
| not_ilike(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
| implement the ``NOT ILIKE`` operator.
|
| This is equivalent to using negation with
| :meth:`.ColumnOperators.ilike`, i.e. ``~x.ilike(y)``.
|
| .. versionchanged:: 1.4 The ``not_ilike()`` operator is renamed from
| ``notilike()`` in previous releases. The previous name remains
| available for backwards compatibility.
|
| .. seealso::
|
| :meth:`.ColumnOperators.ilike`
|
| not_in(self, other: 'Any') -> 'ColumnOperators'
| implement the ``NOT IN`` operator.
|
| This is equivalent to using negation with
| :meth:`.ColumnOperators.in_`, i.e. ``~x.in_(y)``.
|
| In the case that ``other`` is an empty sequence, the compiler
| produces an "empty not in" expression. This defaults to the
| expression "1 = 1" to produce true in all cases. The
| :paramref:`_sa.create_engine.empty_in_strategy` may be used to
| alter this behavior.
|
| .. versionchanged:: 1.4 The ``not_in()`` operator is renamed from
| ``notin_()`` in previous releases. The previous name remains
| available for backwards compatibility.
|
| .. versionchanged:: 1.2 The :meth:`.ColumnOperators.in_` and
| :meth:`.ColumnOperators.not_in` operators
| now produce a "static" expression for an empty IN sequence
| by default.
|
| .. seealso::
|
| :meth:`.ColumnOperators.in_`
|
| not_like(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
| implement the ``NOT LIKE`` operator.
|
| This is equivalent to using negation with
| :meth:`.ColumnOperators.like`, i.e. ``~x.like(y)``.
|
| .. versionchanged:: 1.4 The ``not_like()`` operator is renamed from
| ``notlike()`` in previous releases. The previous name remains
| available for backwards compatibility.
|
| .. seealso::
|
| :meth:`.ColumnOperators.like`
|
| notilike = not_ilike(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
|
| notin_ = not_in(self, other: 'Any') -> 'ColumnOperators'
|
| notlike = not_like(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
|
| nulls_first(self) -> 'ColumnOperators'
| Produce a :func:`_expression.nulls_first` clause against the
| parent object.
|
| .. versionchanged:: 1.4 The ``nulls_first()`` operator is
| renamed from ``nullsfirst()`` in previous releases.
| The previous name remains available for backwards compatibility.
|
| nulls_last(self) -> 'ColumnOperators'
| Produce a :func:`_expression.nulls_last` clause against the
| parent object.
|
| .. versionchanged:: 1.4 The ``nulls_last()`` operator is
| renamed from ``nullslast()`` in previous releases.
| The previous name remains available for backwards compatibility.
|
| nullsfirst = nulls_first(self) -> 'ColumnOperators'
|
| nullslast = nulls_last(self) -> 'ColumnOperators'
|
| regexp_match(self, pattern: 'Any', flags: 'Optional[str]' = None) -> 'ColumnOperators'
| Implements a database-specific 'regexp match' operator.
|
| E.g.::
|
| stmt = select(table.c.some_column).where(
| table.c.some_column.regexp_match("^(b|c)")
| )
|
| :meth:`_sql.ColumnOperators.regexp_match` attempts to resolve to
| a REGEXP-like function or operator provided by the backend, however
| the specific regular expression syntax and flags available are
| **not backend agnostic**.
|
| Examples include:
|
| * PostgreSQL - renders ``x ~ y`` or ``x !~ y`` when negated.
| * Oracle Database - renders ``REGEXP_LIKE(x, y)``
| * SQLite - uses SQLite's ``REGEXP`` placeholder operator and calls into
| the Python ``re.match()`` builtin.
| * other backends may provide special implementations.
| * Backends without any special implementation will emit
| the operator as "REGEXP" or "NOT REGEXP". This is compatible with
| SQLite and MySQL, for example.
|
| Regular expression support is currently implemented for Oracle
| Database, PostgreSQL, MySQL and MariaDB. Partial support is available
| for SQLite. Support among third-party dialects may vary.
|
| :param pattern: The regular expression pattern string or column
| clause.
| :param flags: Any regular expression string flags to apply, passed as
| plain Python string only. These flags are backend specific.
| Some backends, like PostgreSQL and MariaDB, may alternatively
| specify the flags as part of the pattern.
| When using the ignore case flag 'i' in PostgreSQL, the ignore case
| regexp match operator ``~*`` or ``!~*`` will be used.
|
| .. versionadded:: 1.4
|
| .. versionchanged:: 1.4.48, 2.0.18 Note that due to an implementation
| error, the "flags" parameter previously accepted SQL expression
| objects such as column expressions in addition to plain Python
| strings. This implementation did not work correctly with caching
| and was removed; strings only should be passed for the "flags"
| parameter, as these flags are rendered as literal inline values
| within SQL expressions.
|
| .. seealso::
|
| :meth:`_sql.ColumnOperators.regexp_replace`
|
| regexp_replace(self, pattern: 'Any', replacement: 'Any', flags: 'Optional[str]' = None) -> 'ColumnOperators'
| Implements a database-specific 'regexp replace' operator.
|
| E.g.::
|
| stmt = select(
| table.c.some_column.regexp_replace("b(..)", "XY", flags="g")
| )
|
| :meth:`_sql.ColumnOperators.regexp_replace` attempts to resolve to
| a REGEXP_REPLACE-like function provided by the backend, that
| usually emit the function ``REGEXP_REPLACE()``. However,
| the specific regular expression syntax and flags available are
| **not backend agnostic**.
|
| Regular expression replacement support is currently implemented for
| Oracle Database, PostgreSQL, MySQL 8 or greater and MariaDB. Support
| among third-party dialects may vary.
|
| :param pattern: The regular expression pattern string or column
| clause.
| :param pattern: The replacement string or column clause.
| :param flags: Any regular expression string flags to apply, passed as
| plain Python string only. These flags are backend specific.
| Some backends, like PostgreSQL and MariaDB, may alternatively
| specify the flags as part of the pattern.
|
| .. versionadded:: 1.4
|
| .. versionchanged:: 1.4.48, 2.0.18 Note that due to an implementation
| error, the "flags" parameter previously accepted SQL expression
| objects such as column expressions in addition to plain Python
| strings. This implementation did not work correctly with caching
| and was removed; strings only should be passed for the "flags"
| parameter, as these flags are rendered as literal inline values
| within SQL expressions.
|
|
| .. seealso::
|
| :meth:`_sql.ColumnOperators.regexp_match`
|
| startswith(self, other: 'Any', escape: 'Optional[str]' = None, autoescape: 'bool' = False) -> 'ColumnOperators'
| Implement the ``startswith`` operator.
|
| Produces a LIKE expression that tests against a match for the start
| of a string value:
|
| .. sourcecode:: sql
|
| column LIKE <other> || '%'
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.startswith("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.startswith.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.startswith.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.startswith.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.startswith("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE :param || '%' ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.startswith("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE :param || '%' ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.startswith.autoescape`::
|
| somecolumn.startswith("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.endswith`
|
| :meth:`.ColumnOperators.contains`
|
| :meth:`.ColumnOperators.like`
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.operators.ColumnOperators:
|
| timetuple = None
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.operators.Operators:
|
| __and__(self, other: 'Any') -> 'Operators'
| Implement the ``&`` operator.
|
| When used with SQL expressions, results in an
| AND operation, equivalent to
| :func:`_expression.and_`, that is::
|
| a & b
|
| is equivalent to::
|
| from sqlalchemy import and_
|
| and_(a, b)
|
| Care should be taken when using ``&`` regarding
| operator precedence; the ``&`` operator has the highest precedence.
| The operands should be enclosed in parenthesis if they contain
| further sub expressions::
|
| (a == 2) & (b == 4)
|
| __invert__(self) -> 'Operators'
| Implement the ``~`` operator.
|
| When used with SQL expressions, results in a
| NOT operation, equivalent to
| :func:`_expression.not_`, that is::
|
| ~a
|
| is equivalent to::
|
| from sqlalchemy import not_
|
| not_(a)
|
| __or__(self, other: 'Any') -> 'Operators'
| Implement the ``|`` operator.
|
| When used with SQL expressions, results in an
| OR operation, equivalent to
| :func:`_expression.or_`, that is::
|
| a | b
|
| is equivalent to::
|
| from sqlalchemy import or_
|
| or_(a, b)
|
| Care should be taken when using ``|`` regarding
| operator precedence; the ``|`` operator has the highest precedence.
| The operands should be enclosed in parenthesis if they contain
| further sub expressions::
|
| (a == 2) | (b == 4)
|
| __sa_operate__ = operate(self, op: 'OperatorType', *other: 'Any', **kwargs: 'Any') -> 'Operators'
| Operate on an argument.
|
| This is the lowest level of operation, raises
| :class:`NotImplementedError` by default.
|
| Overriding this on a subclass can allow common
| behavior to be applied to all operations.
| For example, overriding :class:`.ColumnOperators`
| to apply ``func.lower()`` to the left and right
| side::
|
| class MyComparator(ColumnOperators):
| def operate(self, op, other, **kwargs):
| return op(func.lower(self), func.lower(other), **kwargs)
|
| :param op: Operator callable.
| :param \*other: the 'other' side of the operation. Will
| be a single scalar for most operations.
| :param \**kwargs: modifiers. These may be passed by special
| operators such as :meth:`ColumnOperators.contains`.
|
| bool_op(self, opstring: 'str', precedence: 'int' = 0, python_impl: 'Optional[Callable[..., Any]]' = None) -> 'Callable[[Any], Operators]'
| Return a custom boolean operator.
|
| This method is shorthand for calling
| :meth:`.Operators.op` and passing the
| :paramref:`.Operators.op.is_comparison`
| flag with True. A key advantage to using :meth:`.Operators.bool_op`
| is that when using column constructs, the "boolean" nature of the
| returned expression will be present for :pep:`484` purposes.
|
| .. seealso::
|
| :meth:`.Operators.op`
|
| op(self, opstring: 'str', precedence: 'int' = 0, is_comparison: 'bool' = False, return_type: 'Optional[Union[Type[TypeEngine[Any]], TypeEngine[Any]]]' = None, python_impl: 'Optional[Callable[..., Any]]' = None) -> 'Callable[[Any], Operators]'
| Produce a generic operator function.
|
| e.g.::
|
| somecolumn.op("*")(5)
|
| produces::
|
| somecolumn * 5
|
| This function can also be used to make bitwise operators explicit. For
| example::
|
| somecolumn.op("&")(0xFF)
|
| is a bitwise AND of the value in ``somecolumn``.
|
| :param opstring: a string which will be output as the infix operator
| between this element and the expression passed to the
| generated function.
|
| :param precedence: precedence which the database is expected to apply
| to the operator in SQL expressions. This integer value acts as a hint
| for the SQL compiler to know when explicit parenthesis should be
| rendered around a particular operation. A lower number will cause the
| expression to be parenthesized when applied against another operator
| with higher precedence. The default value of ``0`` is lower than all
| operators except for the comma (``,``) and ``AS`` operators. A value
| of 100 will be higher or equal to all operators, and -100 will be
| lower than or equal to all operators.
|
| .. seealso::
|
| :ref:`faq_sql_expression_op_parenthesis` - detailed description
| of how the SQLAlchemy SQL compiler renders parenthesis
|
| :param is_comparison: legacy; if True, the operator will be considered
| as a "comparison" operator, that is which evaluates to a boolean
| true/false value, like ``==``, ``>``, etc. This flag is provided
| so that ORM relationships can establish that the operator is a
| comparison operator when used in a custom join condition.
|
| Using the ``is_comparison`` parameter is superseded by using the
| :meth:`.Operators.bool_op` method instead; this more succinct
| operator sets this parameter automatically, but also provides
| correct :pep:`484` typing support as the returned object will
| express a "boolean" datatype, i.e. ``BinaryExpression[bool]``.
|
| :param return_type: a :class:`.TypeEngine` class or object that will
| force the return type of an expression produced by this operator
| to be of that type. By default, operators that specify
| :paramref:`.Operators.op.is_comparison` will resolve to
| :class:`.Boolean`, and those that do not will be of the same
| type as the left-hand operand.
|
| :param python_impl: an optional Python function that can evaluate
| two Python values in the same way as this operator works when
| run on the database server. Useful for in-Python SQL expression
| evaluation functions, such as for ORM hybrid attributes, and the
| ORM "evaluator" used to match objects in a session after a multi-row
| update or delete.
|
| e.g.::
|
| >>> expr = column("x").op("+", python_impl=lambda a, b: a + b)("y")
|
| The operator for the above expression will also work for non-SQL
| left and right objects::
|
| >>> expr.operator(5, 10)
| 15
|
| .. versionadded:: 2.0
|
|
| .. seealso::
|
| :meth:`.Operators.bool_op`
|
| :ref:`types_operators`
|
| :ref:`relationship_custom_operator`
|
| ----------------------------------------------------------------------
| Methods inherited from ClauseElement:
|
| __bool__(self)
|
| __getstate__(self)
| Helper for pickle.
|
| __repr__(self)
| Return repr(self).
|
| compare(self, other: 'ClauseElement', **kw: 'Any') -> 'bool'
| Compare this :class:`_expression.ClauseElement` to
| the given :class:`_expression.ClauseElement`.
|
| Subclasses should override the default behavior, which is a
| straight identity comparison.
|
| \**kw are arguments consumed by subclass ``compare()`` methods and
| may be used to modify the criteria for comparison
| (see :class:`_expression.ColumnElement`).
|
| description(...)
|
| entity_namespace(...)
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from ClauseElement:
|
| is_clause_element = True
|
| is_dml = False
|
| is_selectable = False
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.cache_key.HasCacheKey:
|
| inherit_cache = None
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_instancemethod(fn: '_F') -> '_F'
| Decorate a method memoize its return value.
|
| :meta private:
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_attribute = <class 'sqlalchemy.util.langhelpers.HasMemoized.m...
| A read-only @property that is only evaluated once.
|
| :meta private:
|
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.visitors.HasTraverseInternals:
|
| get_children(self, *, omit_attrs: 'Tuple[str, ...]' = (), **kw: 'Any') -> 'Iterable[HasTraverseInternals]'
| Return immediate child :class:`.visitors.HasTraverseInternals`
| elements of this :class:`.visitors.HasTraverseInternals`.
|
| This is used for visit traversal.
|
| \**kw may contain flags that change the collection that is
| returned, for example to return a subset of items in order to
| cut down on larger traversals, or to return child items from a
| different context (such as schema-level collections instead of
| clause-level).
|
| ----------------------------------------------------------------------
| Methods inherited from CompilerElement:
|
| __str__(self) -> 'str'
| Return str(self).
|
| compile(self, bind: 'Optional[_HasDialect]' = None, dialect: 'Optional[Dialect]' = None, **kw: 'Any') -> 'Compiled'
| Compile this SQL expression.
|
| The return value is a :class:`~.Compiled` object.
| Calling ``str()`` or ``unicode()`` on the returned value will yield a
| string representation of the result. The
| :class:`~.Compiled` object also can return a
| dictionary of bind parameter names and values
| using the ``params`` accessor.
|
| :param bind: An :class:`.Connection` or :class:`.Engine` which
| can provide a :class:`.Dialect` in order to generate a
| :class:`.Compiled` object. If the ``bind`` and
| ``dialect`` parameters are both omitted, a default SQL compiler
| is used.
|
| :param column_keys: Used for INSERT and UPDATE statements, a list of
| column names which should be present in the VALUES clause of the
| compiled statement. If ``None``, all columns from the target table
| object are rendered.
|
| :param dialect: A :class:`.Dialect` instance which can generate
| a :class:`.Compiled` object. This argument takes precedence over
| the ``bind`` argument.
|
| :param compile_kwargs: optional dictionary of additional parameters
| that will be passed through to the compiler within all "visit"
| methods. This allows any custom flag to be passed through to
| a custom compilation construct, for example. It is also used
| for the case of passing the ``literal_binds`` flag through::
|
| from sqlalchemy.sql import table, column, select
|
| t = table("t", column("x"))
|
| s = select(t).where(t.c.x == 5)
|
| print(s.compile(compile_kwargs={"literal_binds": True}))
|
| .. seealso::
|
| :ref:`faq_sql_expression_string`
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from CompilerElement:
|
| stringify_dialect = 'default'
|
| supports_execution = False
sqlalchemy.TryCast
Python Library Documentation: class TryCast in module sqlalchemy.sql.elements
class TryCast(Cast)
| TryCast(expression: '_ColumnExpressionArgument[Any]', type_: '_TypeEngineArgument[_T]')
|
| Represent a TRY_CAST expression.
|
| Details on :class:`.TryCast` usage is at :func:`.try_cast`.
|
| .. seealso::
|
| :func:`.try_cast`
|
| :ref:`tutorial_casts`
|
| Method resolution order:
| TryCast
| Cast
| WrapsColumnExpression
| ColumnElement
| sqlalchemy.sql.roles.ColumnArgumentOrKeyRole
| sqlalchemy.sql.roles.ColumnArgumentRole
| sqlalchemy.sql.roles.StatementOptionRole
| sqlalchemy.sql.roles.WhereHavingRole
| sqlalchemy.sql.roles.OnClauseRole
| sqlalchemy.sql.roles.BinaryElementRole
| sqlalchemy.sql.roles.OrderByRole
| sqlalchemy.sql.roles.ColumnsClauseRole
| sqlalchemy.sql.roles.AllowsLambdaRole
| sqlalchemy.sql.roles.ByOfRole
| sqlalchemy.sql.roles.UsesInspection
| sqlalchemy.sql.roles.ColumnListRole
| sqlalchemy.sql.roles.LimitOffsetRole
| sqlalchemy.sql.roles.DMLColumnRole
| sqlalchemy.sql.roles.DDLConstraintColumnRole
| sqlalchemy.sql.roles.DDLExpressionRole
| sqlalchemy.sql.roles.StructuralRole
| SQLColumnExpression
| SQLCoreOperations
| sqlalchemy.sql.roles.ExpressionElementRole
| sqlalchemy.sql.roles.TypedColumnsClauseRole
| typing.Generic
| sqlalchemy.sql.operators.ColumnOperators
| sqlalchemy.sql.operators.Operators
| sqlalchemy.util.langhelpers.TypingOnly
| sqlalchemy.sql.roles.SQLRole
| DQLDMLClauseElement
| ClauseElement
| sqlalchemy.sql.annotation.SupportsWrappingAnnotations
| sqlalchemy.sql.annotation.SupportsAnnotations
| sqlalchemy.sql.cache_key.MemoizedHasCacheKey
| sqlalchemy.sql.cache_key.HasCacheKey
| sqlalchemy.util.langhelpers.HasMemoized
| sqlalchemy.sql.traversals.HasCopyInternals
| sqlalchemy.sql.visitors.ExternallyTraversible
| sqlalchemy.sql.visitors.HasTraverseInternals
| CompilerElement
| sqlalchemy.sql.visitors.Visitable
| builtins.object
|
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| __orig_bases__ = (sqlalchemy.sql.elements.Cast[~_T],)
|
| __parameters__ = (~_T,)
|
| __visit_name__ = 'try_cast'
|
| inherit_cache = True
|
| ----------------------------------------------------------------------
| Methods inherited from Cast:
|
| __init__(self, expression: '_ColumnExpressionArgument[Any]', type_: '_TypeEngineArgument[_T]')
| Initialize self. See help(type(self)) for accurate signature.
|
| ----------------------------------------------------------------------
| Readonly properties inherited from Cast:
|
| wrapped_column_expression
|
| ----------------------------------------------------------------------
| Methods inherited from ColumnElement:
|
| __getattr__(self, key: 'str') -> 'Any'
|
| __setstate__(self, state)
|
| base_columns(...)
|
| cast(self, type_: '_TypeEngineArgument[_OPT]') -> 'Cast[_OPT]'
| Produce a type cast, i.e. ``CAST(<expression> AS <type>)``.
|
| This is a shortcut to the :func:`_expression.cast` function.
|
| .. seealso::
|
| :ref:`tutorial_casts`
|
| :func:`_expression.cast`
|
| :func:`_expression.type_coerce`
|
| comparator(...)
|
| label(self, name: 'Optional[str]') -> 'Label[_T]'
| Produce a column label, i.e. ``<columnname> AS <name>``.
|
| This is a shortcut to the :func:`_expression.label` function.
|
| If 'name' is ``None``, an anonymous label name will be generated.
|
| operate(self, op: 'operators.OperatorType', *other: 'Any', **kwargs: 'Any') -> 'ColumnElement[Any]'
| Operate on an argument.
|
| This is the lowest level of operation, raises
| :class:`NotImplementedError` by default.
|
| Overriding this on a subclass can allow common
| behavior to be applied to all operations.
| For example, overriding :class:`.ColumnOperators`
| to apply ``func.lower()`` to the left and right
| side::
|
| class MyComparator(ColumnOperators):
| def operate(self, op, other, **kwargs):
| return op(func.lower(self), func.lower(other), **kwargs)
|
| :param op: Operator callable.
| :param \*other: the 'other' side of the operation. Will
| be a single scalar for most operations.
| :param \**kwargs: modifiers. These may be passed by special
| operators such as :meth:`ColumnOperators.contains`.
|
| proxy_set(...)
| set of all columns we are proxying
|
| as of 2.0 this is explicitly deannotated columns. previously it was
| effectively deannotated columns but wasn't enforced. annotated
| columns should basically not go into sets if at all possible because
| their hashing behavior is very non-performant.
|
| reverse_operate(self, op: 'operators.OperatorType', other: 'Any', **kwargs: 'Any') -> 'ColumnElement[Any]'
| Reverse operate on an argument.
|
| Usage is the same as :meth:`operate`.
|
| self_group(self, against: 'Optional[OperatorType]' = None) -> 'ColumnElement[Any]'
| 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.
|
| shares_lineage(self, othercolumn: 'ColumnElement[Any]') -> 'bool'
| Return True if the given :class:`_expression.ColumnElement`
| has a common ancestor to this :class:`_expression.ColumnElement`.
|
| type(...)
|
| ----------------------------------------------------------------------
| Readonly properties inherited from ColumnElement:
|
| anon_key_label
| .. deprecated:: 1.4 The :attr:`_expression.ColumnElement.anon_key_label` attribute is now private, and the public accessor is deprecated.
|
| anon_label
| .. deprecated:: 1.4 The :attr:`_expression.ColumnElement.anon_label` attribute is now private, and the public accessor is deprecated.
|
| expression
| Return a column expression.
|
| Part of the inspection interface; returns self.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from ColumnElement:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from ColumnElement:
|
| foreign_keys = frozenset()
|
| key = None
|
| primary_key = False
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.AllowsLambdaRole:
|
| allows_lambda = True
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.UsesInspection:
|
| uses_inspection = True
|
| ----------------------------------------------------------------------
| Class methods inherited from typing.Generic:
|
| __class_getitem__(...)
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__(...)
| Function to initialize subclasses.
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.operators.ColumnOperators:
|
| __add__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``+`` operator.
|
| In a column context, produces the clause ``a + b``
| if the parent object has non-string affinity.
| If the parent object has a string affinity,
| produces the concatenation operator, ``a || b`` -
| see :meth:`.ColumnOperators.concat`.
|
| __contains__(self, other: 'Any') -> 'ColumnOperators'
|
| __eq__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``==`` operator.
|
| In a column context, produces the clause ``a = b``.
| If the target is ``None``, produces ``a IS NULL``.
|
| __floordiv__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``//`` operator.
|
| In a column context, produces the clause ``a / b``,
| which is the same as "truediv", but considers the result
| type to be integer.
|
| .. versionadded:: 2.0
|
| __ge__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``>=`` operator.
|
| In a column context, produces the clause ``a >= b``.
|
| __getitem__(self, index: 'Any') -> 'ColumnOperators'
| Implement the [] operator.
|
| This can be used by some database-specific types
| such as PostgreSQL ARRAY and HSTORE.
|
| __gt__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``>`` operator.
|
| In a column context, produces the clause ``a > b``.
|
| __hash__(self, /) from builtins.object
| Return hash(self).
|
| __le__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``<=`` operator.
|
| In a column context, produces the clause ``a <= b``.
|
| __lshift__(self, other: 'Any') -> 'ColumnOperators'
| implement the << operator.
|
| Not used by SQLAlchemy core, this is provided
| for custom operator systems which want to use
| << as an extension point.
|
| __lt__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``<`` operator.
|
| In a column context, produces the clause ``a < b``.
|
| __mod__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``%`` operator.
|
| In a column context, produces the clause ``a % b``.
|
| __mul__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``*`` operator.
|
| In a column context, produces the clause ``a * b``.
|
| __ne__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``!=`` operator.
|
| In a column context, produces the clause ``a != b``.
| If the target is ``None``, produces ``a IS NOT NULL``.
|
| __neg__(self) -> 'ColumnOperators'
| Implement the ``-`` operator.
|
| In a column context, produces the clause ``-a``.
|
| __radd__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``+`` operator in reverse.
|
| See :meth:`.ColumnOperators.__add__`.
|
| __rfloordiv__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``//`` operator in reverse.
|
| See :meth:`.ColumnOperators.__floordiv__`.
|
| __rmod__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``%`` operator in reverse.
|
| See :meth:`.ColumnOperators.__mod__`.
|
| __rmul__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``*`` operator in reverse.
|
| See :meth:`.ColumnOperators.__mul__`.
|
| __rshift__(self, other: 'Any') -> 'ColumnOperators'
| implement the >> operator.
|
| Not used by SQLAlchemy core, this is provided
| for custom operator systems which want to use
| >> as an extension point.
|
| __rsub__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``-`` operator in reverse.
|
| See :meth:`.ColumnOperators.__sub__`.
|
| __rtruediv__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``/`` operator in reverse.
|
| See :meth:`.ColumnOperators.__truediv__`.
|
| __sub__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``-`` operator.
|
| In a column context, produces the clause ``a - b``.
|
| __truediv__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``/`` operator.
|
| In a column context, produces the clause ``a / b``, and
| considers the result type to be numeric.
|
| .. versionchanged:: 2.0 The truediv operator against two integers
| is now considered to return a numeric value. Behavior on specific
| backends may vary.
|
| all_(self) -> 'ColumnOperators'
| Produce an :func:`_expression.all_` clause against the
| parent object.
|
| See the documentation for :func:`_sql.all_` for examples.
|
| .. note:: be sure to not confuse the newer
| :meth:`_sql.ColumnOperators.all_` method with the **legacy**
| version of this method, the :meth:`_types.ARRAY.Comparator.all`
| method that's specific to :class:`_types.ARRAY`, which uses a
| different calling style.
|
| any_(self) -> 'ColumnOperators'
| Produce an :func:`_expression.any_` clause against the
| parent object.
|
| See the documentation for :func:`_sql.any_` for examples.
|
| .. note:: be sure to not confuse the newer
| :meth:`_sql.ColumnOperators.any_` method with the **legacy**
| version of this method, the :meth:`_types.ARRAY.Comparator.any`
| method that's specific to :class:`_types.ARRAY`, which uses a
| different calling style.
|
| asc(self) -> 'ColumnOperators'
| Produce a :func:`_expression.asc` clause against the
| parent object.
|
| between(self, cleft: 'Any', cright: 'Any', symmetric: 'bool' = False) -> 'ColumnOperators'
| Produce a :func:`_expression.between` clause against
| the parent object, given the lower and upper range.
|
| bitwise_and(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise AND operation, typically via the ``&``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_lshift(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise LSHIFT operation, typically via the ``<<``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_not(self) -> 'ColumnOperators'
| Produce a bitwise NOT operation, typically via the ``~``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_or(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise OR operation, typically via the ``|``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_rshift(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise RSHIFT operation, typically via the ``>>``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_xor(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise XOR operation, typically via the ``^``
| operator, or ``#`` for PostgreSQL.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| collate(self, collation: 'str') -> 'ColumnOperators'
| Produce a :func:`_expression.collate` clause against
| the parent object, given the collation string.
|
| .. seealso::
|
| :func:`_expression.collate`
|
| concat(self, other: 'Any') -> 'ColumnOperators'
| Implement the 'concat' operator.
|
| In a column context, produces the clause ``a || b``,
| or uses the ``concat()`` operator on MySQL.
|
| contains(self, other: 'Any', **kw: 'Any') -> 'ColumnOperators'
| Implement the 'contains' operator.
|
| Produces a LIKE expression that tests against a match for the middle
| of a string value:
|
| .. sourcecode:: sql
|
| column LIKE '%' || <other> || '%'
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.contains("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.contains.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.contains.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.contains.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.contains("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE '%' || :param || '%' ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.contains("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE '%' || :param || '%' ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.contains.autoescape`::
|
| somecolumn.contains("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.startswith`
|
| :meth:`.ColumnOperators.endswith`
|
| :meth:`.ColumnOperators.like`
|
| desc(self) -> 'ColumnOperators'
| Produce a :func:`_expression.desc` clause against the
| parent object.
|
| distinct(self) -> 'ColumnOperators'
| Produce a :func:`_expression.distinct` clause against the
| parent object.
|
| endswith(self, other: 'Any', escape: 'Optional[str]' = None, autoescape: 'bool' = False) -> 'ColumnOperators'
| Implement the 'endswith' operator.
|
| Produces a LIKE expression that tests against a match for the end
| of a string value:
|
| .. sourcecode:: sql
|
| column LIKE '%' || <other>
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.endswith("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.endswith.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.endswith.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.endswith.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.endswith("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE '%' || :param ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.endswith("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE '%' || :param ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.endswith.autoescape`::
|
| somecolumn.endswith("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.startswith`
|
| :meth:`.ColumnOperators.contains`
|
| :meth:`.ColumnOperators.like`
|
| icontains(self, other: 'Any', **kw: 'Any') -> 'ColumnOperators'
| Implement the ``icontains`` operator, e.g. case insensitive
| version of :meth:`.ColumnOperators.contains`.
|
| Produces a LIKE expression that tests against an insensitive match
| for the middle of a string value:
|
| .. sourcecode:: sql
|
| lower(column) LIKE '%' || lower(<other>) || '%'
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.icontains("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.icontains.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.icontains.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.icontains.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.icontains("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE '%' || lower(:param) || '%' ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.icontains("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE '%' || lower(:param) || '%' ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.contains.autoescape`::
|
| somecolumn.icontains("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.contains`
|
| iendswith(self, other: 'Any', escape: 'Optional[str]' = None, autoescape: 'bool' = False) -> 'ColumnOperators'
| Implement the ``iendswith`` operator, e.g. case insensitive
| version of :meth:`.ColumnOperators.endswith`.
|
| Produces a LIKE expression that tests against an insensitive match
| for the end of a string value:
|
| .. sourcecode:: sql
|
| lower(column) LIKE '%' || lower(<other>)
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.iendswith("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.iendswith.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.iendswith.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.iendswith.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.iendswith("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE '%' || lower(:param) ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.iendswith("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE '%' || lower(:param) ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.iendswith.autoescape`::
|
| somecolumn.endswith("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.endswith`
|
| ilike(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
| Implement the ``ilike`` operator, e.g. case insensitive LIKE.
|
| In a column context, produces an expression either of the form:
|
| .. sourcecode:: sql
|
| lower(a) LIKE lower(other)
|
| Or on backends that support the ILIKE operator:
|
| .. sourcecode:: sql
|
| a ILIKE other
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.ilike("%foobar%"))
|
| :param other: expression to be compared
| :param escape: optional escape character, renders the ``ESCAPE``
| keyword, e.g.::
|
| somecolumn.ilike("foo/%bar", escape="/")
|
| .. seealso::
|
| :meth:`.ColumnOperators.like`
|
| in_(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``in`` operator.
|
| In a column context, produces the clause ``column IN <other>``.
|
| The given parameter ``other`` may be:
|
| * A list of literal values,
| e.g.::
|
| stmt.where(column.in_([1, 2, 3]))
|
| In this calling form, the list of items is converted to a set of
| bound parameters the same length as the list given:
|
| .. sourcecode:: sql
|
| WHERE COL IN (?, ?, ?)
|
| * A list of tuples may be provided if the comparison is against a
| :func:`.tuple_` containing multiple expressions::
|
| from sqlalchemy import tuple_
|
| stmt.where(tuple_(col1, col2).in_([(1, 10), (2, 20), (3, 30)]))
|
| * An empty list,
| e.g.::
|
| stmt.where(column.in_([]))
|
| In this calling form, the expression renders an "empty set"
| expression. These expressions are tailored to individual backends
| and are generally trying to get an empty SELECT statement as a
| subquery. Such as on SQLite, the expression is:
|
| .. sourcecode:: sql
|
| WHERE col IN (SELECT 1 FROM (SELECT 1) WHERE 1!=1)
|
| .. versionchanged:: 1.4 empty IN expressions now use an
| execution-time generated SELECT subquery in all cases.
|
| * A bound parameter, e.g. :func:`.bindparam`, may be used if it
| includes the :paramref:`.bindparam.expanding` flag::
|
| stmt.where(column.in_(bindparam("value", expanding=True)))
|
| In this calling form, the expression renders a special non-SQL
| placeholder expression that looks like:
|
| .. sourcecode:: sql
|
| WHERE COL IN ([EXPANDING_value])
|
| This placeholder expression is intercepted at statement execution
| time to be converted into the variable number of bound parameter
| form illustrated earlier. If the statement were executed as::
|
| connection.execute(stmt, {"value": [1, 2, 3]})
|
| The database would be passed a bound parameter for each value:
|
| .. sourcecode:: sql
|
| WHERE COL IN (?, ?, ?)
|
| .. versionadded:: 1.2 added "expanding" bound parameters
|
| If an empty list is passed, a special "empty list" expression,
| which is specific to the database in use, is rendered. On
| SQLite this would be:
|
| .. sourcecode:: sql
|
| WHERE COL IN (SELECT 1 FROM (SELECT 1) WHERE 1!=1)
|
| .. versionadded:: 1.3 "expanding" bound parameters now support
| empty lists
|
| * a :func:`_expression.select` construct, which is usually a
| correlated scalar select::
|
| stmt.where(
| column.in_(select(othertable.c.y).where(table.c.x == othertable.c.x))
| )
|
| In this calling form, :meth:`.ColumnOperators.in_` renders as given:
|
| .. sourcecode:: sql
|
| WHERE COL IN (SELECT othertable.y
| FROM othertable WHERE othertable.x = table.x)
|
| :param other: a list of literals, a :func:`_expression.select`
| construct, or a :func:`.bindparam` construct that includes the
| :paramref:`.bindparam.expanding` flag set to True.
|
| is_(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``IS`` operator.
|
| Normally, ``IS`` is generated automatically when comparing to a
| value of ``None``, which resolves to ``NULL``. However, explicit
| usage of ``IS`` may be desirable if comparing to boolean values
| on certain platforms.
|
| .. seealso:: :meth:`.ColumnOperators.is_not`
|
| is_distinct_from(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``IS DISTINCT FROM`` operator.
|
| Renders "a IS DISTINCT FROM b" on most platforms;
| on some such as SQLite may render "a IS NOT b".
|
| is_not(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``IS NOT`` operator.
|
| Normally, ``IS NOT`` is generated automatically when comparing to a
| value of ``None``, which resolves to ``NULL``. However, explicit
| usage of ``IS NOT`` may be desirable if comparing to boolean values
| on certain platforms.
|
| .. versionchanged:: 1.4 The ``is_not()`` operator is renamed from
| ``isnot()`` in previous releases. The previous name remains
| available for backwards compatibility.
|
| .. seealso:: :meth:`.ColumnOperators.is_`
|
| is_not_distinct_from(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``IS NOT DISTINCT FROM`` operator.
|
| Renders "a IS NOT DISTINCT FROM b" on most platforms;
| on some such as SQLite may render "a IS b".
|
| .. versionchanged:: 1.4 The ``is_not_distinct_from()`` operator is
| renamed from ``isnot_distinct_from()`` in previous releases.
| The previous name remains available for backwards compatibility.
|
| isnot = is_not(self, other: 'Any') -> 'ColumnOperators'
|
| isnot_distinct_from = is_not_distinct_from(self, other: 'Any') -> 'ColumnOperators'
|
| istartswith(self, other: 'Any', escape: 'Optional[str]' = None, autoescape: 'bool' = False) -> 'ColumnOperators'
| Implement the ``istartswith`` operator, e.g. case insensitive
| version of :meth:`.ColumnOperators.startswith`.
|
| Produces a LIKE expression that tests against an insensitive
| match for the start of a string value:
|
| .. sourcecode:: sql
|
| lower(column) LIKE lower(<other>) || '%'
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.istartswith("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.istartswith.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.istartswith.escape` parameter will
| establish a given character as an escape character which can be of
| use when the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.istartswith.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.istartswith("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE lower(:param) || '%' ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.istartswith("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE lower(:param) || '%' ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.istartswith.autoescape`::
|
| somecolumn.istartswith("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.startswith`
|
| like(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
| Implement the ``like`` operator.
|
| In a column context, produces the expression:
|
| .. sourcecode:: sql
|
| a LIKE other
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.like("%foobar%"))
|
| :param other: expression to be compared
| :param escape: optional escape character, renders the ``ESCAPE``
| keyword, e.g.::
|
| somecolumn.like("foo/%bar", escape="/")
|
| .. seealso::
|
| :meth:`.ColumnOperators.ilike`
|
| match(self, other: 'Any', **kwargs: 'Any') -> 'ColumnOperators'
| Implements a database-specific 'match' operator.
|
| :meth:`_sql.ColumnOperators.match` attempts to resolve to
| a MATCH-like function or operator provided by the backend.
| Examples include:
|
| * PostgreSQL - renders ``x @@ plainto_tsquery(y)``
|
| .. versionchanged:: 2.0 ``plainto_tsquery()`` is used instead
| of ``to_tsquery()`` for PostgreSQL now; for compatibility with
| other forms, see :ref:`postgresql_match`.
|
|
| * MySQL - renders ``MATCH (x) AGAINST (y IN BOOLEAN MODE)``
|
| .. seealso::
|
| :class:`_mysql.match` - MySQL specific construct with
| additional features.
|
| * Oracle Database - renders ``CONTAINS(x, y)``
| * other backends may provide special implementations.
| * Backends without any special implementation will emit
| the operator as "MATCH". This is compatible with SQLite, for
| example.
|
| not_ilike(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
| implement the ``NOT ILIKE`` operator.
|
| This is equivalent to using negation with
| :meth:`.ColumnOperators.ilike`, i.e. ``~x.ilike(y)``.
|
| .. versionchanged:: 1.4 The ``not_ilike()`` operator is renamed from
| ``notilike()`` in previous releases. The previous name remains
| available for backwards compatibility.
|
| .. seealso::
|
| :meth:`.ColumnOperators.ilike`
|
| not_in(self, other: 'Any') -> 'ColumnOperators'
| implement the ``NOT IN`` operator.
|
| This is equivalent to using negation with
| :meth:`.ColumnOperators.in_`, i.e. ``~x.in_(y)``.
|
| In the case that ``other`` is an empty sequence, the compiler
| produces an "empty not in" expression. This defaults to the
| expression "1 = 1" to produce true in all cases. The
| :paramref:`_sa.create_engine.empty_in_strategy` may be used to
| alter this behavior.
|
| .. versionchanged:: 1.4 The ``not_in()`` operator is renamed from
| ``notin_()`` in previous releases. The previous name remains
| available for backwards compatibility.
|
| .. versionchanged:: 1.2 The :meth:`.ColumnOperators.in_` and
| :meth:`.ColumnOperators.not_in` operators
| now produce a "static" expression for an empty IN sequence
| by default.
|
| .. seealso::
|
| :meth:`.ColumnOperators.in_`
|
| not_like(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
| implement the ``NOT LIKE`` operator.
|
| This is equivalent to using negation with
| :meth:`.ColumnOperators.like`, i.e. ``~x.like(y)``.
|
| .. versionchanged:: 1.4 The ``not_like()`` operator is renamed from
| ``notlike()`` in previous releases. The previous name remains
| available for backwards compatibility.
|
| .. seealso::
|
| :meth:`.ColumnOperators.like`
|
| notilike = not_ilike(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
|
| notin_ = not_in(self, other: 'Any') -> 'ColumnOperators'
|
| notlike = not_like(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
|
| nulls_first(self) -> 'ColumnOperators'
| Produce a :func:`_expression.nulls_first` clause against the
| parent object.
|
| .. versionchanged:: 1.4 The ``nulls_first()`` operator is
| renamed from ``nullsfirst()`` in previous releases.
| The previous name remains available for backwards compatibility.
|
| nulls_last(self) -> 'ColumnOperators'
| Produce a :func:`_expression.nulls_last` clause against the
| parent object.
|
| .. versionchanged:: 1.4 The ``nulls_last()`` operator is
| renamed from ``nullslast()`` in previous releases.
| The previous name remains available for backwards compatibility.
|
| nullsfirst = nulls_first(self) -> 'ColumnOperators'
|
| nullslast = nulls_last(self) -> 'ColumnOperators'
|
| regexp_match(self, pattern: 'Any', flags: 'Optional[str]' = None) -> 'ColumnOperators'
| Implements a database-specific 'regexp match' operator.
|
| E.g.::
|
| stmt = select(table.c.some_column).where(
| table.c.some_column.regexp_match("^(b|c)")
| )
|
| :meth:`_sql.ColumnOperators.regexp_match` attempts to resolve to
| a REGEXP-like function or operator provided by the backend, however
| the specific regular expression syntax and flags available are
| **not backend agnostic**.
|
| Examples include:
|
| * PostgreSQL - renders ``x ~ y`` or ``x !~ y`` when negated.
| * Oracle Database - renders ``REGEXP_LIKE(x, y)``
| * SQLite - uses SQLite's ``REGEXP`` placeholder operator and calls into
| the Python ``re.match()`` builtin.
| * other backends may provide special implementations.
| * Backends without any special implementation will emit
| the operator as "REGEXP" or "NOT REGEXP". This is compatible with
| SQLite and MySQL, for example.
|
| Regular expression support is currently implemented for Oracle
| Database, PostgreSQL, MySQL and MariaDB. Partial support is available
| for SQLite. Support among third-party dialects may vary.
|
| :param pattern: The regular expression pattern string or column
| clause.
| :param flags: Any regular expression string flags to apply, passed as
| plain Python string only. These flags are backend specific.
| Some backends, like PostgreSQL and MariaDB, may alternatively
| specify the flags as part of the pattern.
| When using the ignore case flag 'i' in PostgreSQL, the ignore case
| regexp match operator ``~*`` or ``!~*`` will be used.
|
| .. versionadded:: 1.4
|
| .. versionchanged:: 1.4.48, 2.0.18 Note that due to an implementation
| error, the "flags" parameter previously accepted SQL expression
| objects such as column expressions in addition to plain Python
| strings. This implementation did not work correctly with caching
| and was removed; strings only should be passed for the "flags"
| parameter, as these flags are rendered as literal inline values
| within SQL expressions.
|
| .. seealso::
|
| :meth:`_sql.ColumnOperators.regexp_replace`
|
| regexp_replace(self, pattern: 'Any', replacement: 'Any', flags: 'Optional[str]' = None) -> 'ColumnOperators'
| Implements a database-specific 'regexp replace' operator.
|
| E.g.::
|
| stmt = select(
| table.c.some_column.regexp_replace("b(..)", "XY", flags="g")
| )
|
| :meth:`_sql.ColumnOperators.regexp_replace` attempts to resolve to
| a REGEXP_REPLACE-like function provided by the backend, that
| usually emit the function ``REGEXP_REPLACE()``. However,
| the specific regular expression syntax and flags available are
| **not backend agnostic**.
|
| Regular expression replacement support is currently implemented for
| Oracle Database, PostgreSQL, MySQL 8 or greater and MariaDB. Support
| among third-party dialects may vary.
|
| :param pattern: The regular expression pattern string or column
| clause.
| :param pattern: The replacement string or column clause.
| :param flags: Any regular expression string flags to apply, passed as
| plain Python string only. These flags are backend specific.
| Some backends, like PostgreSQL and MariaDB, may alternatively
| specify the flags as part of the pattern.
|
| .. versionadded:: 1.4
|
| .. versionchanged:: 1.4.48, 2.0.18 Note that due to an implementation
| error, the "flags" parameter previously accepted SQL expression
| objects such as column expressions in addition to plain Python
| strings. This implementation did not work correctly with caching
| and was removed; strings only should be passed for the "flags"
| parameter, as these flags are rendered as literal inline values
| within SQL expressions.
|
|
| .. seealso::
|
| :meth:`_sql.ColumnOperators.regexp_match`
|
| startswith(self, other: 'Any', escape: 'Optional[str]' = None, autoescape: 'bool' = False) -> 'ColumnOperators'
| Implement the ``startswith`` operator.
|
| Produces a LIKE expression that tests against a match for the start
| of a string value:
|
| .. sourcecode:: sql
|
| column LIKE <other> || '%'
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.startswith("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.startswith.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.startswith.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.startswith.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.startswith("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE :param || '%' ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.startswith("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE :param || '%' ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.startswith.autoescape`::
|
| somecolumn.startswith("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.endswith`
|
| :meth:`.ColumnOperators.contains`
|
| :meth:`.ColumnOperators.like`
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.operators.ColumnOperators:
|
| timetuple = None
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.operators.Operators:
|
| __and__(self, other: 'Any') -> 'Operators'
| Implement the ``&`` operator.
|
| When used with SQL expressions, results in an
| AND operation, equivalent to
| :func:`_expression.and_`, that is::
|
| a & b
|
| is equivalent to::
|
| from sqlalchemy import and_
|
| and_(a, b)
|
| Care should be taken when using ``&`` regarding
| operator precedence; the ``&`` operator has the highest precedence.
| The operands should be enclosed in parenthesis if they contain
| further sub expressions::
|
| (a == 2) & (b == 4)
|
| __invert__(self) -> 'Operators'
| Implement the ``~`` operator.
|
| When used with SQL expressions, results in a
| NOT operation, equivalent to
| :func:`_expression.not_`, that is::
|
| ~a
|
| is equivalent to::
|
| from sqlalchemy import not_
|
| not_(a)
|
| __or__(self, other: 'Any') -> 'Operators'
| Implement the ``|`` operator.
|
| When used with SQL expressions, results in an
| OR operation, equivalent to
| :func:`_expression.or_`, that is::
|
| a | b
|
| is equivalent to::
|
| from sqlalchemy import or_
|
| or_(a, b)
|
| Care should be taken when using ``|`` regarding
| operator precedence; the ``|`` operator has the highest precedence.
| The operands should be enclosed in parenthesis if they contain
| further sub expressions::
|
| (a == 2) | (b == 4)
|
| __sa_operate__ = operate(self, op: 'OperatorType', *other: 'Any', **kwargs: 'Any') -> 'Operators'
| Operate on an argument.
|
| This is the lowest level of operation, raises
| :class:`NotImplementedError` by default.
|
| Overriding this on a subclass can allow common
| behavior to be applied to all operations.
| For example, overriding :class:`.ColumnOperators`
| to apply ``func.lower()`` to the left and right
| side::
|
| class MyComparator(ColumnOperators):
| def operate(self, op, other, **kwargs):
| return op(func.lower(self), func.lower(other), **kwargs)
|
| :param op: Operator callable.
| :param \*other: the 'other' side of the operation. Will
| be a single scalar for most operations.
| :param \**kwargs: modifiers. These may be passed by special
| operators such as :meth:`ColumnOperators.contains`.
|
| bool_op(self, opstring: 'str', precedence: 'int' = 0, python_impl: 'Optional[Callable[..., Any]]' = None) -> 'Callable[[Any], Operators]'
| Return a custom boolean operator.
|
| This method is shorthand for calling
| :meth:`.Operators.op` and passing the
| :paramref:`.Operators.op.is_comparison`
| flag with True. A key advantage to using :meth:`.Operators.bool_op`
| is that when using column constructs, the "boolean" nature of the
| returned expression will be present for :pep:`484` purposes.
|
| .. seealso::
|
| :meth:`.Operators.op`
|
| op(self, opstring: 'str', precedence: 'int' = 0, is_comparison: 'bool' = False, return_type: 'Optional[Union[Type[TypeEngine[Any]], TypeEngine[Any]]]' = None, python_impl: 'Optional[Callable[..., Any]]' = None) -> 'Callable[[Any], Operators]'
| Produce a generic operator function.
|
| e.g.::
|
| somecolumn.op("*")(5)
|
| produces::
|
| somecolumn * 5
|
| This function can also be used to make bitwise operators explicit. For
| example::
|
| somecolumn.op("&")(0xFF)
|
| is a bitwise AND of the value in ``somecolumn``.
|
| :param opstring: a string which will be output as the infix operator
| between this element and the expression passed to the
| generated function.
|
| :param precedence: precedence which the database is expected to apply
| to the operator in SQL expressions. This integer value acts as a hint
| for the SQL compiler to know when explicit parenthesis should be
| rendered around a particular operation. A lower number will cause the
| expression to be parenthesized when applied against another operator
| with higher precedence. The default value of ``0`` is lower than all
| operators except for the comma (``,``) and ``AS`` operators. A value
| of 100 will be higher or equal to all operators, and -100 will be
| lower than or equal to all operators.
|
| .. seealso::
|
| :ref:`faq_sql_expression_op_parenthesis` - detailed description
| of how the SQLAlchemy SQL compiler renders parenthesis
|
| :param is_comparison: legacy; if True, the operator will be considered
| as a "comparison" operator, that is which evaluates to a boolean
| true/false value, like ``==``, ``>``, etc. This flag is provided
| so that ORM relationships can establish that the operator is a
| comparison operator when used in a custom join condition.
|
| Using the ``is_comparison`` parameter is superseded by using the
| :meth:`.Operators.bool_op` method instead; this more succinct
| operator sets this parameter automatically, but also provides
| correct :pep:`484` typing support as the returned object will
| express a "boolean" datatype, i.e. ``BinaryExpression[bool]``.
|
| :param return_type: a :class:`.TypeEngine` class or object that will
| force the return type of an expression produced by this operator
| to be of that type. By default, operators that specify
| :paramref:`.Operators.op.is_comparison` will resolve to
| :class:`.Boolean`, and those that do not will be of the same
| type as the left-hand operand.
|
| :param python_impl: an optional Python function that can evaluate
| two Python values in the same way as this operator works when
| run on the database server. Useful for in-Python SQL expression
| evaluation functions, such as for ORM hybrid attributes, and the
| ORM "evaluator" used to match objects in a session after a multi-row
| update or delete.
|
| e.g.::
|
| >>> expr = column("x").op("+", python_impl=lambda a, b: a + b)("y")
|
| The operator for the above expression will also work for non-SQL
| left and right objects::
|
| >>> expr.operator(5, 10)
| 15
|
| .. versionadded:: 2.0
|
|
| .. seealso::
|
| :meth:`.Operators.bool_op`
|
| :ref:`types_operators`
|
| :ref:`relationship_custom_operator`
|
| ----------------------------------------------------------------------
| Methods inherited from ClauseElement:
|
| __bool__(self)
|
| __getstate__(self)
| Helper for pickle.
|
| __repr__(self)
| Return repr(self).
|
| compare(self, other: 'ClauseElement', **kw: 'Any') -> 'bool'
| Compare this :class:`_expression.ClauseElement` to
| the given :class:`_expression.ClauseElement`.
|
| Subclasses should override the default behavior, which is a
| straight identity comparison.
|
| \**kw are arguments consumed by subclass ``compare()`` methods and
| may be used to modify the criteria for comparison
| (see :class:`_expression.ColumnElement`).
|
| description(...)
|
| entity_namespace(...)
|
| params(self, _ClauseElement__optionaldict: 'Optional[Mapping[str, Any]]' = None, **kwargs: 'Any') -> 'Self'
| Return a copy with :func:`_expression.bindparam` elements
| replaced.
|
| Returns a copy of this ClauseElement with
| :func:`_expression.bindparam`
| elements replaced with values taken from the given dictionary::
|
| >>> clause = column("x") + bindparam("foo")
| >>> print(clause.compile().params)
| {'foo':None}
| >>> print(clause.params({"foo": 7}).compile().params)
| {'foo':7}
|
| unique_params(self, _ClauseElement__optionaldict: 'Optional[Dict[str, Any]]' = None, **kwargs: 'Any') -> 'Self'
| Return a copy with :func:`_expression.bindparam` elements
| replaced.
|
| Same functionality as :meth:`_expression.ClauseElement.params`,
| except adds `unique=True`
| to affected bind parameters so that multiple statements can be
| used.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from ClauseElement:
|
| is_clause_element = True
|
| is_dml = False
|
| is_selectable = False
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_instancemethod(fn: '_F') -> '_F'
| Decorate a method memoize its return value.
|
| :meta private:
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_attribute = <class 'sqlalchemy.util.langhelpers.HasMemoized.m...
| A read-only @property that is only evaluated once.
|
| :meta private:
|
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.visitors.HasTraverseInternals:
|
| get_children(self, *, omit_attrs: 'Tuple[str, ...]' = (), **kw: 'Any') -> 'Iterable[HasTraverseInternals]'
| Return immediate child :class:`.visitors.HasTraverseInternals`
| elements of this :class:`.visitors.HasTraverseInternals`.
|
| This is used for visit traversal.
|
| \**kw may contain flags that change the collection that is
| returned, for example to return a subset of items in order to
| cut down on larger traversals, or to return child items from a
| different context (such as schema-level collections instead of
| clause-level).
|
| ----------------------------------------------------------------------
| Methods inherited from CompilerElement:
|
| __str__(self) -> 'str'
| Return str(self).
|
| compile(self, bind: 'Optional[_HasDialect]' = None, dialect: 'Optional[Dialect]' = None, **kw: 'Any') -> 'Compiled'
| Compile this SQL expression.
|
| The return value is a :class:`~.Compiled` object.
| Calling ``str()`` or ``unicode()`` on the returned value will yield a
| string representation of the result. The
| :class:`~.Compiled` object also can return a
| dictionary of bind parameter names and values
| using the ``params`` accessor.
|
| :param bind: An :class:`.Connection` or :class:`.Engine` which
| can provide a :class:`.Dialect` in order to generate a
| :class:`.Compiled` object. If the ``bind`` and
| ``dialect`` parameters are both omitted, a default SQL compiler
| is used.
|
| :param column_keys: Used for INSERT and UPDATE statements, a list of
| column names which should be present in the VALUES clause of the
| compiled statement. If ``None``, all columns from the target table
| object are rendered.
|
| :param dialect: A :class:`.Dialect` instance which can generate
| a :class:`.Compiled` object. This argument takes precedence over
| the ``bind`` argument.
|
| :param compile_kwargs: optional dictionary of additional parameters
| that will be passed through to the compiler within all "visit"
| methods. This allows any custom flag to be passed through to
| a custom compilation construct, for example. It is also used
| for the case of passing the ``literal_binds`` flag through::
|
| from sqlalchemy.sql import table, column, select
|
| t = table("t", column("x"))
|
| s = select(t).where(t.c.x == 5)
|
| print(s.compile(compile_kwargs={"literal_binds": True}))
|
| .. seealso::
|
| :ref:`faq_sql_expression_string`
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from CompilerElement:
|
| stringify_dialect = 'default'
|
| supports_execution = False
sqlalchemy.Tuple
Python Library Documentation: class Tuple in module sqlalchemy.sql.elements
class Tuple(ClauseList, ColumnElement)
| Tuple(*clauses: '_ColumnExpressionArgument[Any]', types: 'Optional[Sequence[_TypeEngineArgument[Any]]]' = None)
|
| Represent a SQL tuple.
|
| Method resolution order:
| Tuple
| ClauseList
| sqlalchemy.sql.roles.InElementRole
| ColumnElement
| sqlalchemy.sql.roles.ColumnArgumentOrKeyRole
| sqlalchemy.sql.roles.ColumnArgumentRole
| sqlalchemy.sql.roles.StatementOptionRole
| sqlalchemy.sql.roles.WhereHavingRole
| sqlalchemy.sql.roles.OnClauseRole
| sqlalchemy.sql.roles.BinaryElementRole
| sqlalchemy.sql.roles.OrderByRole
| sqlalchemy.sql.roles.ColumnsClauseRole
| sqlalchemy.sql.roles.AllowsLambdaRole
| sqlalchemy.sql.roles.ByOfRole
| sqlalchemy.sql.roles.UsesInspection
| sqlalchemy.sql.roles.ColumnListRole
| sqlalchemy.sql.roles.LimitOffsetRole
| sqlalchemy.sql.roles.DMLColumnRole
| sqlalchemy.sql.roles.DDLConstraintColumnRole
| sqlalchemy.sql.roles.DDLExpressionRole
| sqlalchemy.sql.roles.StructuralRole
| SQLColumnExpression
| SQLCoreOperations
| sqlalchemy.sql.roles.ExpressionElementRole
| sqlalchemy.sql.roles.TypedColumnsClauseRole
| typing.Generic
| sqlalchemy.sql.operators.ColumnOperators
| sqlalchemy.sql.operators.Operators
| sqlalchemy.util.langhelpers.TypingOnly
| sqlalchemy.sql.roles.SQLRole
| DQLDMLClauseElement
| ClauseElement
| sqlalchemy.sql.annotation.SupportsWrappingAnnotations
| sqlalchemy.sql.annotation.SupportsAnnotations
| sqlalchemy.sql.cache_key.MemoizedHasCacheKey
| sqlalchemy.sql.cache_key.HasCacheKey
| sqlalchemy.util.langhelpers.HasMemoized
| sqlalchemy.sql.traversals.HasCopyInternals
| sqlalchemy.sql.visitors.ExternallyTraversible
| sqlalchemy.sql.visitors.HasTraverseInternals
| CompilerElement
| sqlalchemy.sql.visitors.Visitable
| builtins.object
|
| Methods defined here:
|
| __init__(self, *clauses: '_ColumnExpressionArgument[Any]', types: 'Optional[Sequence[_TypeEngineArgument[Any]]]' = None)
| Initialize self. See help(type(self)) for accurate signature.
|
| self_group(self, against: 'Optional[OperatorType]' = None) -> 'Self'
| 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.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'_traverse_internals': '_TraverseInternalsType', 't...
|
| __orig_bases__ = (<class 'sqlalchemy.sql.elements.ClauseList'>, sqlalc...
|
| __parameters__ = ()
|
| __visit_name__ = 'tuple'
|
| ----------------------------------------------------------------------
| Methods inherited from ClauseList:
|
| __iter__(self) -> 'Iterator[ColumnElement[Any]]'
|
| __len__(self) -> 'int'
|
| append(self, clause)
|
| ----------------------------------------------------------------------
| Data descriptors inherited from ClauseList:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Methods inherited from ColumnElement:
|
| __getattr__(self, key: 'str') -> 'Any'
|
| __setstate__(self, state)
|
| base_columns(...)
|
| cast(self, type_: '_TypeEngineArgument[_OPT]') -> 'Cast[_OPT]'
| Produce a type cast, i.e. ``CAST(<expression> AS <type>)``.
|
| This is a shortcut to the :func:`_expression.cast` function.
|
| .. seealso::
|
| :ref:`tutorial_casts`
|
| :func:`_expression.cast`
|
| :func:`_expression.type_coerce`
|
| comparator(...)
|
| label(self, name: 'Optional[str]') -> 'Label[_T]'
| Produce a column label, i.e. ``<columnname> AS <name>``.
|
| This is a shortcut to the :func:`_expression.label` function.
|
| If 'name' is ``None``, an anonymous label name will be generated.
|
| operate(self, op: 'operators.OperatorType', *other: 'Any', **kwargs: 'Any') -> 'ColumnElement[Any]'
| Operate on an argument.
|
| This is the lowest level of operation, raises
| :class:`NotImplementedError` by default.
|
| Overriding this on a subclass can allow common
| behavior to be applied to all operations.
| For example, overriding :class:`.ColumnOperators`
| to apply ``func.lower()`` to the left and right
| side::
|
| class MyComparator(ColumnOperators):
| def operate(self, op, other, **kwargs):
| return op(func.lower(self), func.lower(other), **kwargs)
|
| :param op: Operator callable.
| :param \*other: the 'other' side of the operation. Will
| be a single scalar for most operations.
| :param \**kwargs: modifiers. These may be passed by special
| operators such as :meth:`ColumnOperators.contains`.
|
| proxy_set(...)
| set of all columns we are proxying
|
| as of 2.0 this is explicitly deannotated columns. previously it was
| effectively deannotated columns but wasn't enforced. annotated
| columns should basically not go into sets if at all possible because
| their hashing behavior is very non-performant.
|
| reverse_operate(self, op: 'operators.OperatorType', other: 'Any', **kwargs: 'Any') -> 'ColumnElement[Any]'
| Reverse operate on an argument.
|
| Usage is the same as :meth:`operate`.
|
| shares_lineage(self, othercolumn: 'ColumnElement[Any]') -> 'bool'
| Return True if the given :class:`_expression.ColumnElement`
| has a common ancestor to this :class:`_expression.ColumnElement`.
|
| type(...)
|
| ----------------------------------------------------------------------
| Readonly properties inherited from ColumnElement:
|
| anon_key_label
| .. deprecated:: 1.4 The :attr:`_expression.ColumnElement.anon_key_label` attribute is now private, and the public accessor is deprecated.
|
| anon_label
| .. deprecated:: 1.4 The :attr:`_expression.ColumnElement.anon_label` attribute is now private, and the public accessor is deprecated.
|
| expression
| Return a column expression.
|
| Part of the inspection interface; returns self.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from ColumnElement:
|
| foreign_keys = frozenset()
|
| key = None
|
| primary_key = False
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.AllowsLambdaRole:
|
| allows_lambda = True
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.UsesInspection:
|
| uses_inspection = True
|
| ----------------------------------------------------------------------
| Class methods inherited from typing.Generic:
|
| __class_getitem__(...)
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__(...)
| Function to initialize subclasses.
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.operators.ColumnOperators:
|
| __add__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``+`` operator.
|
| In a column context, produces the clause ``a + b``
| if the parent object has non-string affinity.
| If the parent object has a string affinity,
| produces the concatenation operator, ``a || b`` -
| see :meth:`.ColumnOperators.concat`.
|
| __contains__(self, other: 'Any') -> 'ColumnOperators'
|
| __eq__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``==`` operator.
|
| In a column context, produces the clause ``a = b``.
| If the target is ``None``, produces ``a IS NULL``.
|
| __floordiv__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``//`` operator.
|
| In a column context, produces the clause ``a / b``,
| which is the same as "truediv", but considers the result
| type to be integer.
|
| .. versionadded:: 2.0
|
| __ge__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``>=`` operator.
|
| In a column context, produces the clause ``a >= b``.
|
| __getitem__(self, index: 'Any') -> 'ColumnOperators'
| Implement the [] operator.
|
| This can be used by some database-specific types
| such as PostgreSQL ARRAY and HSTORE.
|
| __gt__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``>`` operator.
|
| In a column context, produces the clause ``a > b``.
|
| __hash__(self, /) from builtins.object
| Return hash(self).
|
| __le__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``<=`` operator.
|
| In a column context, produces the clause ``a <= b``.
|
| __lshift__(self, other: 'Any') -> 'ColumnOperators'
| implement the << operator.
|
| Not used by SQLAlchemy core, this is provided
| for custom operator systems which want to use
| << as an extension point.
|
| __lt__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``<`` operator.
|
| In a column context, produces the clause ``a < b``.
|
| __mod__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``%`` operator.
|
| In a column context, produces the clause ``a % b``.
|
| __mul__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``*`` operator.
|
| In a column context, produces the clause ``a * b``.
|
| __ne__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``!=`` operator.
|
| In a column context, produces the clause ``a != b``.
| If the target is ``None``, produces ``a IS NOT NULL``.
|
| __neg__(self) -> 'ColumnOperators'
| Implement the ``-`` operator.
|
| In a column context, produces the clause ``-a``.
|
| __radd__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``+`` operator in reverse.
|
| See :meth:`.ColumnOperators.__add__`.
|
| __rfloordiv__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``//`` operator in reverse.
|
| See :meth:`.ColumnOperators.__floordiv__`.
|
| __rmod__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``%`` operator in reverse.
|
| See :meth:`.ColumnOperators.__mod__`.
|
| __rmul__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``*`` operator in reverse.
|
| See :meth:`.ColumnOperators.__mul__`.
|
| __rshift__(self, other: 'Any') -> 'ColumnOperators'
| implement the >> operator.
|
| Not used by SQLAlchemy core, this is provided
| for custom operator systems which want to use
| >> as an extension point.
|
| __rsub__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``-`` operator in reverse.
|
| See :meth:`.ColumnOperators.__sub__`.
|
| __rtruediv__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``/`` operator in reverse.
|
| See :meth:`.ColumnOperators.__truediv__`.
|
| __sub__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``-`` operator.
|
| In a column context, produces the clause ``a - b``.
|
| __truediv__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``/`` operator.
|
| In a column context, produces the clause ``a / b``, and
| considers the result type to be numeric.
|
| .. versionchanged:: 2.0 The truediv operator against two integers
| is now considered to return a numeric value. Behavior on specific
| backends may vary.
|
| all_(self) -> 'ColumnOperators'
| Produce an :func:`_expression.all_` clause against the
| parent object.
|
| See the documentation for :func:`_sql.all_` for examples.
|
| .. note:: be sure to not confuse the newer
| :meth:`_sql.ColumnOperators.all_` method with the **legacy**
| version of this method, the :meth:`_types.ARRAY.Comparator.all`
| method that's specific to :class:`_types.ARRAY`, which uses a
| different calling style.
|
| any_(self) -> 'ColumnOperators'
| Produce an :func:`_expression.any_` clause against the
| parent object.
|
| See the documentation for :func:`_sql.any_` for examples.
|
| .. note:: be sure to not confuse the newer
| :meth:`_sql.ColumnOperators.any_` method with the **legacy**
| version of this method, the :meth:`_types.ARRAY.Comparator.any`
| method that's specific to :class:`_types.ARRAY`, which uses a
| different calling style.
|
| asc(self) -> 'ColumnOperators'
| Produce a :func:`_expression.asc` clause against the
| parent object.
|
| between(self, cleft: 'Any', cright: 'Any', symmetric: 'bool' = False) -> 'ColumnOperators'
| Produce a :func:`_expression.between` clause against
| the parent object, given the lower and upper range.
|
| bitwise_and(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise AND operation, typically via the ``&``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_lshift(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise LSHIFT operation, typically via the ``<<``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_not(self) -> 'ColumnOperators'
| Produce a bitwise NOT operation, typically via the ``~``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_or(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise OR operation, typically via the ``|``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_rshift(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise RSHIFT operation, typically via the ``>>``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_xor(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise XOR operation, typically via the ``^``
| operator, or ``#`` for PostgreSQL.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| collate(self, collation: 'str') -> 'ColumnOperators'
| Produce a :func:`_expression.collate` clause against
| the parent object, given the collation string.
|
| .. seealso::
|
| :func:`_expression.collate`
|
| concat(self, other: 'Any') -> 'ColumnOperators'
| Implement the 'concat' operator.
|
| In a column context, produces the clause ``a || b``,
| or uses the ``concat()`` operator on MySQL.
|
| contains(self, other: 'Any', **kw: 'Any') -> 'ColumnOperators'
| Implement the 'contains' operator.
|
| Produces a LIKE expression that tests against a match for the middle
| of a string value:
|
| .. sourcecode:: sql
|
| column LIKE '%' || <other> || '%'
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.contains("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.contains.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.contains.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.contains.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.contains("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE '%' || :param || '%' ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.contains("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE '%' || :param || '%' ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.contains.autoescape`::
|
| somecolumn.contains("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.startswith`
|
| :meth:`.ColumnOperators.endswith`
|
| :meth:`.ColumnOperators.like`
|
| desc(self) -> 'ColumnOperators'
| Produce a :func:`_expression.desc` clause against the
| parent object.
|
| distinct(self) -> 'ColumnOperators'
| Produce a :func:`_expression.distinct` clause against the
| parent object.
|
| endswith(self, other: 'Any', escape: 'Optional[str]' = None, autoescape: 'bool' = False) -> 'ColumnOperators'
| Implement the 'endswith' operator.
|
| Produces a LIKE expression that tests against a match for the end
| of a string value:
|
| .. sourcecode:: sql
|
| column LIKE '%' || <other>
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.endswith("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.endswith.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.endswith.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.endswith.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.endswith("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE '%' || :param ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.endswith("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE '%' || :param ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.endswith.autoescape`::
|
| somecolumn.endswith("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.startswith`
|
| :meth:`.ColumnOperators.contains`
|
| :meth:`.ColumnOperators.like`
|
| icontains(self, other: 'Any', **kw: 'Any') -> 'ColumnOperators'
| Implement the ``icontains`` operator, e.g. case insensitive
| version of :meth:`.ColumnOperators.contains`.
|
| Produces a LIKE expression that tests against an insensitive match
| for the middle of a string value:
|
| .. sourcecode:: sql
|
| lower(column) LIKE '%' || lower(<other>) || '%'
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.icontains("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.icontains.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.icontains.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.icontains.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.icontains("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE '%' || lower(:param) || '%' ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.icontains("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE '%' || lower(:param) || '%' ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.contains.autoescape`::
|
| somecolumn.icontains("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.contains`
|
| iendswith(self, other: 'Any', escape: 'Optional[str]' = None, autoescape: 'bool' = False) -> 'ColumnOperators'
| Implement the ``iendswith`` operator, e.g. case insensitive
| version of :meth:`.ColumnOperators.endswith`.
|
| Produces a LIKE expression that tests against an insensitive match
| for the end of a string value:
|
| .. sourcecode:: sql
|
| lower(column) LIKE '%' || lower(<other>)
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.iendswith("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.iendswith.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.iendswith.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.iendswith.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.iendswith("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE '%' || lower(:param) ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.iendswith("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE '%' || lower(:param) ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.iendswith.autoescape`::
|
| somecolumn.endswith("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.endswith`
|
| ilike(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
| Implement the ``ilike`` operator, e.g. case insensitive LIKE.
|
| In a column context, produces an expression either of the form:
|
| .. sourcecode:: sql
|
| lower(a) LIKE lower(other)
|
| Or on backends that support the ILIKE operator:
|
| .. sourcecode:: sql
|
| a ILIKE other
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.ilike("%foobar%"))
|
| :param other: expression to be compared
| :param escape: optional escape character, renders the ``ESCAPE``
| keyword, e.g.::
|
| somecolumn.ilike("foo/%bar", escape="/")
|
| .. seealso::
|
| :meth:`.ColumnOperators.like`
|
| in_(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``in`` operator.
|
| In a column context, produces the clause ``column IN <other>``.
|
| The given parameter ``other`` may be:
|
| * A list of literal values,
| e.g.::
|
| stmt.where(column.in_([1, 2, 3]))
|
| In this calling form, the list of items is converted to a set of
| bound parameters the same length as the list given:
|
| .. sourcecode:: sql
|
| WHERE COL IN (?, ?, ?)
|
| * A list of tuples may be provided if the comparison is against a
| :func:`.tuple_` containing multiple expressions::
|
| from sqlalchemy import tuple_
|
| stmt.where(tuple_(col1, col2).in_([(1, 10), (2, 20), (3, 30)]))
|
| * An empty list,
| e.g.::
|
| stmt.where(column.in_([]))
|
| In this calling form, the expression renders an "empty set"
| expression. These expressions are tailored to individual backends
| and are generally trying to get an empty SELECT statement as a
| subquery. Such as on SQLite, the expression is:
|
| .. sourcecode:: sql
|
| WHERE col IN (SELECT 1 FROM (SELECT 1) WHERE 1!=1)
|
| .. versionchanged:: 1.4 empty IN expressions now use an
| execution-time generated SELECT subquery in all cases.
|
| * A bound parameter, e.g. :func:`.bindparam`, may be used if it
| includes the :paramref:`.bindparam.expanding` flag::
|
| stmt.where(column.in_(bindparam("value", expanding=True)))
|
| In this calling form, the expression renders a special non-SQL
| placeholder expression that looks like:
|
| .. sourcecode:: sql
|
| WHERE COL IN ([EXPANDING_value])
|
| This placeholder expression is intercepted at statement execution
| time to be converted into the variable number of bound parameter
| form illustrated earlier. If the statement were executed as::
|
| connection.execute(stmt, {"value": [1, 2, 3]})
|
| The database would be passed a bound parameter for each value:
|
| .. sourcecode:: sql
|
| WHERE COL IN (?, ?, ?)
|
| .. versionadded:: 1.2 added "expanding" bound parameters
|
| If an empty list is passed, a special "empty list" expression,
| which is specific to the database in use, is rendered. On
| SQLite this would be:
|
| .. sourcecode:: sql
|
| WHERE COL IN (SELECT 1 FROM (SELECT 1) WHERE 1!=1)
|
| .. versionadded:: 1.3 "expanding" bound parameters now support
| empty lists
|
| * a :func:`_expression.select` construct, which is usually a
| correlated scalar select::
|
| stmt.where(
| column.in_(select(othertable.c.y).where(table.c.x == othertable.c.x))
| )
|
| In this calling form, :meth:`.ColumnOperators.in_` renders as given:
|
| .. sourcecode:: sql
|
| WHERE COL IN (SELECT othertable.y
| FROM othertable WHERE othertable.x = table.x)
|
| :param other: a list of literals, a :func:`_expression.select`
| construct, or a :func:`.bindparam` construct that includes the
| :paramref:`.bindparam.expanding` flag set to True.
|
| is_(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``IS`` operator.
|
| Normally, ``IS`` is generated automatically when comparing to a
| value of ``None``, which resolves to ``NULL``. However, explicit
| usage of ``IS`` may be desirable if comparing to boolean values
| on certain platforms.
|
| .. seealso:: :meth:`.ColumnOperators.is_not`
|
| is_distinct_from(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``IS DISTINCT FROM`` operator.
|
| Renders "a IS DISTINCT FROM b" on most platforms;
| on some such as SQLite may render "a IS NOT b".
|
| is_not(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``IS NOT`` operator.
|
| Normally, ``IS NOT`` is generated automatically when comparing to a
| value of ``None``, which resolves to ``NULL``. However, explicit
| usage of ``IS NOT`` may be desirable if comparing to boolean values
| on certain platforms.
|
| .. versionchanged:: 1.4 The ``is_not()`` operator is renamed from
| ``isnot()`` in previous releases. The previous name remains
| available for backwards compatibility.
|
| .. seealso:: :meth:`.ColumnOperators.is_`
|
| is_not_distinct_from(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``IS NOT DISTINCT FROM`` operator.
|
| Renders "a IS NOT DISTINCT FROM b" on most platforms;
| on some such as SQLite may render "a IS b".
|
| .. versionchanged:: 1.4 The ``is_not_distinct_from()`` operator is
| renamed from ``isnot_distinct_from()`` in previous releases.
| The previous name remains available for backwards compatibility.
|
| isnot = is_not(self, other: 'Any') -> 'ColumnOperators'
|
| isnot_distinct_from = is_not_distinct_from(self, other: 'Any') -> 'ColumnOperators'
|
| istartswith(self, other: 'Any', escape: 'Optional[str]' = None, autoescape: 'bool' = False) -> 'ColumnOperators'
| Implement the ``istartswith`` operator, e.g. case insensitive
| version of :meth:`.ColumnOperators.startswith`.
|
| Produces a LIKE expression that tests against an insensitive
| match for the start of a string value:
|
| .. sourcecode:: sql
|
| lower(column) LIKE lower(<other>) || '%'
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.istartswith("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.istartswith.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.istartswith.escape` parameter will
| establish a given character as an escape character which can be of
| use when the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.istartswith.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.istartswith("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE lower(:param) || '%' ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.istartswith("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE lower(:param) || '%' ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.istartswith.autoescape`::
|
| somecolumn.istartswith("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.startswith`
|
| like(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
| Implement the ``like`` operator.
|
| In a column context, produces the expression:
|
| .. sourcecode:: sql
|
| a LIKE other
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.like("%foobar%"))
|
| :param other: expression to be compared
| :param escape: optional escape character, renders the ``ESCAPE``
| keyword, e.g.::
|
| somecolumn.like("foo/%bar", escape="/")
|
| .. seealso::
|
| :meth:`.ColumnOperators.ilike`
|
| match(self, other: 'Any', **kwargs: 'Any') -> 'ColumnOperators'
| Implements a database-specific 'match' operator.
|
| :meth:`_sql.ColumnOperators.match` attempts to resolve to
| a MATCH-like function or operator provided by the backend.
| Examples include:
|
| * PostgreSQL - renders ``x @@ plainto_tsquery(y)``
|
| .. versionchanged:: 2.0 ``plainto_tsquery()`` is used instead
| of ``to_tsquery()`` for PostgreSQL now; for compatibility with
| other forms, see :ref:`postgresql_match`.
|
|
| * MySQL - renders ``MATCH (x) AGAINST (y IN BOOLEAN MODE)``
|
| .. seealso::
|
| :class:`_mysql.match` - MySQL specific construct with
| additional features.
|
| * Oracle Database - renders ``CONTAINS(x, y)``
| * other backends may provide special implementations.
| * Backends without any special implementation will emit
| the operator as "MATCH". This is compatible with SQLite, for
| example.
|
| not_ilike(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
| implement the ``NOT ILIKE`` operator.
|
| This is equivalent to using negation with
| :meth:`.ColumnOperators.ilike`, i.e. ``~x.ilike(y)``.
|
| .. versionchanged:: 1.4 The ``not_ilike()`` operator is renamed from
| ``notilike()`` in previous releases. The previous name remains
| available for backwards compatibility.
|
| .. seealso::
|
| :meth:`.ColumnOperators.ilike`
|
| not_in(self, other: 'Any') -> 'ColumnOperators'
| implement the ``NOT IN`` operator.
|
| This is equivalent to using negation with
| :meth:`.ColumnOperators.in_`, i.e. ``~x.in_(y)``.
|
| In the case that ``other`` is an empty sequence, the compiler
| produces an "empty not in" expression. This defaults to the
| expression "1 = 1" to produce true in all cases. The
| :paramref:`_sa.create_engine.empty_in_strategy` may be used to
| alter this behavior.
|
| .. versionchanged:: 1.4 The ``not_in()`` operator is renamed from
| ``notin_()`` in previous releases. The previous name remains
| available for backwards compatibility.
|
| .. versionchanged:: 1.2 The :meth:`.ColumnOperators.in_` and
| :meth:`.ColumnOperators.not_in` operators
| now produce a "static" expression for an empty IN sequence
| by default.
|
| .. seealso::
|
| :meth:`.ColumnOperators.in_`
|
| not_like(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
| implement the ``NOT LIKE`` operator.
|
| This is equivalent to using negation with
| :meth:`.ColumnOperators.like`, i.e. ``~x.like(y)``.
|
| .. versionchanged:: 1.4 The ``not_like()`` operator is renamed from
| ``notlike()`` in previous releases. The previous name remains
| available for backwards compatibility.
|
| .. seealso::
|
| :meth:`.ColumnOperators.like`
|
| notilike = not_ilike(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
|
| notin_ = not_in(self, other: 'Any') -> 'ColumnOperators'
|
| notlike = not_like(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
|
| nulls_first(self) -> 'ColumnOperators'
| Produce a :func:`_expression.nulls_first` clause against the
| parent object.
|
| .. versionchanged:: 1.4 The ``nulls_first()`` operator is
| renamed from ``nullsfirst()`` in previous releases.
| The previous name remains available for backwards compatibility.
|
| nulls_last(self) -> 'ColumnOperators'
| Produce a :func:`_expression.nulls_last` clause against the
| parent object.
|
| .. versionchanged:: 1.4 The ``nulls_last()`` operator is
| renamed from ``nullslast()`` in previous releases.
| The previous name remains available for backwards compatibility.
|
| nullsfirst = nulls_first(self) -> 'ColumnOperators'
|
| nullslast = nulls_last(self) -> 'ColumnOperators'
|
| regexp_match(self, pattern: 'Any', flags: 'Optional[str]' = None) -> 'ColumnOperators'
| Implements a database-specific 'regexp match' operator.
|
| E.g.::
|
| stmt = select(table.c.some_column).where(
| table.c.some_column.regexp_match("^(b|c)")
| )
|
| :meth:`_sql.ColumnOperators.regexp_match` attempts to resolve to
| a REGEXP-like function or operator provided by the backend, however
| the specific regular expression syntax and flags available are
| **not backend agnostic**.
|
| Examples include:
|
| * PostgreSQL - renders ``x ~ y`` or ``x !~ y`` when negated.
| * Oracle Database - renders ``REGEXP_LIKE(x, y)``
| * SQLite - uses SQLite's ``REGEXP`` placeholder operator and calls into
| the Python ``re.match()`` builtin.
| * other backends may provide special implementations.
| * Backends without any special implementation will emit
| the operator as "REGEXP" or "NOT REGEXP". This is compatible with
| SQLite and MySQL, for example.
|
| Regular expression support is currently implemented for Oracle
| Database, PostgreSQL, MySQL and MariaDB. Partial support is available
| for SQLite. Support among third-party dialects may vary.
|
| :param pattern: The regular expression pattern string or column
| clause.
| :param flags: Any regular expression string flags to apply, passed as
| plain Python string only. These flags are backend specific.
| Some backends, like PostgreSQL and MariaDB, may alternatively
| specify the flags as part of the pattern.
| When using the ignore case flag 'i' in PostgreSQL, the ignore case
| regexp match operator ``~*`` or ``!~*`` will be used.
|
| .. versionadded:: 1.4
|
| .. versionchanged:: 1.4.48, 2.0.18 Note that due to an implementation
| error, the "flags" parameter previously accepted SQL expression
| objects such as column expressions in addition to plain Python
| strings. This implementation did not work correctly with caching
| and was removed; strings only should be passed for the "flags"
| parameter, as these flags are rendered as literal inline values
| within SQL expressions.
|
| .. seealso::
|
| :meth:`_sql.ColumnOperators.regexp_replace`
|
| regexp_replace(self, pattern: 'Any', replacement: 'Any', flags: 'Optional[str]' = None) -> 'ColumnOperators'
| Implements a database-specific 'regexp replace' operator.
|
| E.g.::
|
| stmt = select(
| table.c.some_column.regexp_replace("b(..)", "XY", flags="g")
| )
|
| :meth:`_sql.ColumnOperators.regexp_replace` attempts to resolve to
| a REGEXP_REPLACE-like function provided by the backend, that
| usually emit the function ``REGEXP_REPLACE()``. However,
| the specific regular expression syntax and flags available are
| **not backend agnostic**.
|
| Regular expression replacement support is currently implemented for
| Oracle Database, PostgreSQL, MySQL 8 or greater and MariaDB. Support
| among third-party dialects may vary.
|
| :param pattern: The regular expression pattern string or column
| clause.
| :param pattern: The replacement string or column clause.
| :param flags: Any regular expression string flags to apply, passed as
| plain Python string only. These flags are backend specific.
| Some backends, like PostgreSQL and MariaDB, may alternatively
| specify the flags as part of the pattern.
|
| .. versionadded:: 1.4
|
| .. versionchanged:: 1.4.48, 2.0.18 Note that due to an implementation
| error, the "flags" parameter previously accepted SQL expression
| objects such as column expressions in addition to plain Python
| strings. This implementation did not work correctly with caching
| and was removed; strings only should be passed for the "flags"
| parameter, as these flags are rendered as literal inline values
| within SQL expressions.
|
|
| .. seealso::
|
| :meth:`_sql.ColumnOperators.regexp_match`
|
| startswith(self, other: 'Any', escape: 'Optional[str]' = None, autoescape: 'bool' = False) -> 'ColumnOperators'
| Implement the ``startswith`` operator.
|
| Produces a LIKE expression that tests against a match for the start
| of a string value:
|
| .. sourcecode:: sql
|
| column LIKE <other> || '%'
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.startswith("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.startswith.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.startswith.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.startswith.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.startswith("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE :param || '%' ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.startswith("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE :param || '%' ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.startswith.autoescape`::
|
| somecolumn.startswith("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.endswith`
|
| :meth:`.ColumnOperators.contains`
|
| :meth:`.ColumnOperators.like`
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.operators.ColumnOperators:
|
| timetuple = None
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.operators.Operators:
|
| __and__(self, other: 'Any') -> 'Operators'
| Implement the ``&`` operator.
|
| When used with SQL expressions, results in an
| AND operation, equivalent to
| :func:`_expression.and_`, that is::
|
| a & b
|
| is equivalent to::
|
| from sqlalchemy import and_
|
| and_(a, b)
|
| Care should be taken when using ``&`` regarding
| operator precedence; the ``&`` operator has the highest precedence.
| The operands should be enclosed in parenthesis if they contain
| further sub expressions::
|
| (a == 2) & (b == 4)
|
| __invert__(self) -> 'Operators'
| Implement the ``~`` operator.
|
| When used with SQL expressions, results in a
| NOT operation, equivalent to
| :func:`_expression.not_`, that is::
|
| ~a
|
| is equivalent to::
|
| from sqlalchemy import not_
|
| not_(a)
|
| __or__(self, other: 'Any') -> 'Operators'
| Implement the ``|`` operator.
|
| When used with SQL expressions, results in an
| OR operation, equivalent to
| :func:`_expression.or_`, that is::
|
| a | b
|
| is equivalent to::
|
| from sqlalchemy import or_
|
| or_(a, b)
|
| Care should be taken when using ``|`` regarding
| operator precedence; the ``|`` operator has the highest precedence.
| The operands should be enclosed in parenthesis if they contain
| further sub expressions::
|
| (a == 2) | (b == 4)
|
| __sa_operate__ = operate(self, op: 'OperatorType', *other: 'Any', **kwargs: 'Any') -> 'Operators'
| Operate on an argument.
|
| This is the lowest level of operation, raises
| :class:`NotImplementedError` by default.
|
| Overriding this on a subclass can allow common
| behavior to be applied to all operations.
| For example, overriding :class:`.ColumnOperators`
| to apply ``func.lower()`` to the left and right
| side::
|
| class MyComparator(ColumnOperators):
| def operate(self, op, other, **kwargs):
| return op(func.lower(self), func.lower(other), **kwargs)
|
| :param op: Operator callable.
| :param \*other: the 'other' side of the operation. Will
| be a single scalar for most operations.
| :param \**kwargs: modifiers. These may be passed by special
| operators such as :meth:`ColumnOperators.contains`.
|
| bool_op(self, opstring: 'str', precedence: 'int' = 0, python_impl: 'Optional[Callable[..., Any]]' = None) -> 'Callable[[Any], Operators]'
| Return a custom boolean operator.
|
| This method is shorthand for calling
| :meth:`.Operators.op` and passing the
| :paramref:`.Operators.op.is_comparison`
| flag with True. A key advantage to using :meth:`.Operators.bool_op`
| is that when using column constructs, the "boolean" nature of the
| returned expression will be present for :pep:`484` purposes.
|
| .. seealso::
|
| :meth:`.Operators.op`
|
| op(self, opstring: 'str', precedence: 'int' = 0, is_comparison: 'bool' = False, return_type: 'Optional[Union[Type[TypeEngine[Any]], TypeEngine[Any]]]' = None, python_impl: 'Optional[Callable[..., Any]]' = None) -> 'Callable[[Any], Operators]'
| Produce a generic operator function.
|
| e.g.::
|
| somecolumn.op("*")(5)
|
| produces::
|
| somecolumn * 5
|
| This function can also be used to make bitwise operators explicit. For
| example::
|
| somecolumn.op("&")(0xFF)
|
| is a bitwise AND of the value in ``somecolumn``.
|
| :param opstring: a string which will be output as the infix operator
| between this element and the expression passed to the
| generated function.
|
| :param precedence: precedence which the database is expected to apply
| to the operator in SQL expressions. This integer value acts as a hint
| for the SQL compiler to know when explicit parenthesis should be
| rendered around a particular operation. A lower number will cause the
| expression to be parenthesized when applied against another operator
| with higher precedence. The default value of ``0`` is lower than all
| operators except for the comma (``,``) and ``AS`` operators. A value
| of 100 will be higher or equal to all operators, and -100 will be
| lower than or equal to all operators.
|
| .. seealso::
|
| :ref:`faq_sql_expression_op_parenthesis` - detailed description
| of how the SQLAlchemy SQL compiler renders parenthesis
|
| :param is_comparison: legacy; if True, the operator will be considered
| as a "comparison" operator, that is which evaluates to a boolean
| true/false value, like ``==``, ``>``, etc. This flag is provided
| so that ORM relationships can establish that the operator is a
| comparison operator when used in a custom join condition.
|
| Using the ``is_comparison`` parameter is superseded by using the
| :meth:`.Operators.bool_op` method instead; this more succinct
| operator sets this parameter automatically, but also provides
| correct :pep:`484` typing support as the returned object will
| express a "boolean" datatype, i.e. ``BinaryExpression[bool]``.
|
| :param return_type: a :class:`.TypeEngine` class or object that will
| force the return type of an expression produced by this operator
| to be of that type. By default, operators that specify
| :paramref:`.Operators.op.is_comparison` will resolve to
| :class:`.Boolean`, and those that do not will be of the same
| type as the left-hand operand.
|
| :param python_impl: an optional Python function that can evaluate
| two Python values in the same way as this operator works when
| run on the database server. Useful for in-Python SQL expression
| evaluation functions, such as for ORM hybrid attributes, and the
| ORM "evaluator" used to match objects in a session after a multi-row
| update or delete.
|
| e.g.::
|
| >>> expr = column("x").op("+", python_impl=lambda a, b: a + b)("y")
|
| The operator for the above expression will also work for non-SQL
| left and right objects::
|
| >>> expr.operator(5, 10)
| 15
|
| .. versionadded:: 2.0
|
|
| .. seealso::
|
| :meth:`.Operators.bool_op`
|
| :ref:`types_operators`
|
| :ref:`relationship_custom_operator`
|
| ----------------------------------------------------------------------
| Methods inherited from ClauseElement:
|
| __bool__(self)
|
| __getstate__(self)
| Helper for pickle.
|
| __repr__(self)
| Return repr(self).
|
| compare(self, other: 'ClauseElement', **kw: 'Any') -> 'bool'
| Compare this :class:`_expression.ClauseElement` to
| the given :class:`_expression.ClauseElement`.
|
| Subclasses should override the default behavior, which is a
| straight identity comparison.
|
| \**kw are arguments consumed by subclass ``compare()`` methods and
| may be used to modify the criteria for comparison
| (see :class:`_expression.ColumnElement`).
|
| description(...)
|
| entity_namespace(...)
|
| params(self, _ClauseElement__optionaldict: 'Optional[Mapping[str, Any]]' = None, **kwargs: 'Any') -> 'Self'
| Return a copy with :func:`_expression.bindparam` elements
| replaced.
|
| Returns a copy of this ClauseElement with
| :func:`_expression.bindparam`
| elements replaced with values taken from the given dictionary::
|
| >>> clause = column("x") + bindparam("foo")
| >>> print(clause.compile().params)
| {'foo':None}
| >>> print(clause.params({"foo": 7}).compile().params)
| {'foo':7}
|
| unique_params(self, _ClauseElement__optionaldict: 'Optional[Dict[str, Any]]' = None, **kwargs: 'Any') -> 'Self'
| Return a copy with :func:`_expression.bindparam` elements
| replaced.
|
| Same functionality as :meth:`_expression.ClauseElement.params`,
| except adds `unique=True`
| to affected bind parameters so that multiple statements can be
| used.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from ClauseElement:
|
| is_clause_element = True
|
| is_dml = False
|
| is_selectable = False
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.cache_key.HasCacheKey:
|
| inherit_cache = None
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_instancemethod(fn: '_F') -> '_F'
| Decorate a method memoize its return value.
|
| :meta private:
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_attribute = <class 'sqlalchemy.util.langhelpers.HasMemoized.m...
| A read-only @property that is only evaluated once.
|
| :meta private:
|
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.visitors.HasTraverseInternals:
|
| get_children(self, *, omit_attrs: 'Tuple[str, ...]' = (), **kw: 'Any') -> 'Iterable[HasTraverseInternals]'
| Return immediate child :class:`.visitors.HasTraverseInternals`
| elements of this :class:`.visitors.HasTraverseInternals`.
|
| This is used for visit traversal.
|
| \**kw may contain flags that change the collection that is
| returned, for example to return a subset of items in order to
| cut down on larger traversals, or to return child items from a
| different context (such as schema-level collections instead of
| clause-level).
|
| ----------------------------------------------------------------------
| Methods inherited from CompilerElement:
|
| __str__(self) -> 'str'
| Return str(self).
|
| compile(self, bind: 'Optional[_HasDialect]' = None, dialect: 'Optional[Dialect]' = None, **kw: 'Any') -> 'Compiled'
| Compile this SQL expression.
|
| The return value is a :class:`~.Compiled` object.
| Calling ``str()`` or ``unicode()`` on the returned value will yield a
| string representation of the result. The
| :class:`~.Compiled` object also can return a
| dictionary of bind parameter names and values
| using the ``params`` accessor.
|
| :param bind: An :class:`.Connection` or :class:`.Engine` which
| can provide a :class:`.Dialect` in order to generate a
| :class:`.Compiled` object. If the ``bind`` and
| ``dialect`` parameters are both omitted, a default SQL compiler
| is used.
|
| :param column_keys: Used for INSERT and UPDATE statements, a list of
| column names which should be present in the VALUES clause of the
| compiled statement. If ``None``, all columns from the target table
| object are rendered.
|
| :param dialect: A :class:`.Dialect` instance which can generate
| a :class:`.Compiled` object. This argument takes precedence over
| the ``bind`` argument.
|
| :param compile_kwargs: optional dictionary of additional parameters
| that will be passed through to the compiler within all "visit"
| methods. This allows any custom flag to be passed through to
| a custom compilation construct, for example. It is also used
| for the case of passing the ``literal_binds`` flag through::
|
| from sqlalchemy.sql import table, column, select
|
| t = table("t", column("x"))
|
| s = select(t).where(t.c.x == 5)
|
| print(s.compile(compile_kwargs={"literal_binds": True}))
|
| .. seealso::
|
| :ref:`faq_sql_expression_string`
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from CompilerElement:
|
| stringify_dialect = 'default'
|
| supports_execution = False
sqlalchemy.TupleType
Python Library Documentation: class TupleType in module sqlalchemy.sql.sqltypes
class TupleType(sqlalchemy.sql.type_api.TypeEngine)
| TupleType(*types: '_TypeEngineArgument[Any]')
|
| represent the composite type of a Tuple.
|
| Method resolution order:
| TupleType
| sqlalchemy.sql.type_api.TypeEngine
| sqlalchemy.sql.visitors.Visitable
| typing.Generic
| builtins.object
|
| Methods defined here:
|
| __init__(self, *types: '_TypeEngineArgument[Any]')
| Initialize self. See help(type(self)) for accurate signature.
|
| coerce_compared_value(self, op: 'Optional[OperatorType]', value: 'Any') -> 'TypeEngine[Any]'
| Suggest a type for a 'coerced' Python value in an expression.
|
| Given an operator and value, gives the type a chance
| to return a type which the value should be coerced into.
|
| The default behavior here is conservative; if the right-hand
| side is already coerced into a SQL type based on its
| Python type, it is usually left alone.
|
| End-user functionality extension here should generally be via
| :class:`.TypeDecorator`, which provides more liberal behavior in that
| it defaults to coercing the other side of the expression into this
| type, thus applying special Python conversions above and beyond those
| needed by the DBAPI to both ides. It also provides the public method
| :meth:`.TypeDecorator.coerce_compared_value` which is intended for
| end-user customization of this behavior.
|
| result_processor(self, dialect, coltype)
| Return a conversion function for processing result row values.
|
| Returns a callable which will receive a result row column
| value as the sole positional argument and will return a value
| to return to the user.
|
| If processing is not necessary, the method should return ``None``.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.result_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.result_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_result_value`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| :param dialect: Dialect instance in use.
|
| :param coltype: DBAPI coltype argument received in cursor.description.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'types': 'List[TypeEngine[Any]]'}
|
| __parameters__ = ()
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.type_api.TypeEngine:
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| __str__(self) -> 'str'
| Return str(self).
|
| adapt(self, cls: 'Type[Union[TypeEngine[Any], TypeEngineMixin]]', **kw: 'Any') -> 'TypeEngine[Any]'
| Produce an "adapted" form of this type, given an "impl" class
| to work with.
|
| This method is used internally to associate generic
| types with "implementation" types that are specific to a particular
| dialect.
|
| as_generic(self, allow_nulltype: 'bool' = False) -> 'TypeEngine[_T]'
| Return an instance of the generic type corresponding to this type
| using heuristic rule. The method may be overridden if this
| heuristic rule is not sufficient.
|
| >>> from sqlalchemy.dialects.mysql import INTEGER
| >>> INTEGER(display_width=4).as_generic()
| Integer()
|
| >>> from sqlalchemy.dialects.mysql import NVARCHAR
| >>> NVARCHAR(length=100).as_generic()
| Unicode(length=100)
|
| .. versionadded:: 1.4.0b2
|
|
| .. seealso::
|
| :ref:`metadata_reflection_dbagnostic_types` - describes the
| use of :meth:`_types.TypeEngine.as_generic` in conjunction with
| the :meth:`_sql.DDLEvents.column_reflect` event, which is its
| intended use.
|
| bind_expression(self, bindvalue: 'BindParameter[_T]') -> 'Optional[ColumnElement[_T]]'
| Given a bind value (i.e. a :class:`.BindParameter` instance),
| return a SQL expression in its place.
|
| This is typically a SQL function that wraps the existing bound
| parameter within the statement. It is used for special data types
| that require literals being wrapped in some special database function
| in order to coerce an application-level value into a database-specific
| format. It is the SQL analogue of the
| :meth:`.TypeEngine.bind_processor` method.
|
| This method is called during the **SQL compilation** phase of a
| statement, when rendering a SQL string. It is **not** called
| against specific values.
|
| Note that this method, when implemented, should always return
| the exact same structure, without any conditional logic, as it
| may be used in an executemany() call against an arbitrary number
| of bound parameter sets.
|
| .. note::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.bind_expression`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.bind_expression`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.bind_expression`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| .. seealso::
|
| :ref:`types_sql_value_processing`
|
| bind_processor(self, dialect: 'Dialect') -> 'Optional[_BindProcessorType[_T]]'
| Return a conversion function for processing bind values.
|
| Returns a callable which will receive a bind parameter value
| as the sole positional argument and will return a value to
| send to the DB-API.
|
| If processing is not necessary, the method should return ``None``.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.bind_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.bind_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_bind_param`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
|
| :param dialect: Dialect instance in use.
|
| column_expression(self, colexpr: 'ColumnElement[_T]') -> 'Optional[ColumnElement[_T]]'
| Given a SELECT column expression, return a wrapping SQL expression.
|
| This is typically a SQL function that wraps a column expression
| as rendered in the columns clause of a SELECT statement.
| It is used for special data types that require
| columns to be wrapped in some special database function in order
| to coerce the value before being sent back to the application.
| It is the SQL analogue of the :meth:`.TypeEngine.result_processor`
| method.
|
| .. note:: The :func:`.TypeEngine.column_expression` method is applied
| only to the **outermost columns clause** of a SELECT statement, that
| is, the columns that are to be delivered directly into the returned
| result rows. It does **not** apply to the columns clause inside
| of subqueries. This necessarily avoids double conversions against
| the column and only runs the conversion when ready to be returned
| to the client.
|
| This method is called during the **SQL compilation** phase of a
| statement, when rendering a SQL string. It is **not** called
| against specific values.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.column_expression`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.column_expression`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.column_expression`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
|
| .. seealso::
|
| :ref:`types_sql_value_processing`
|
| compare_values(self, x: 'Any', y: 'Any') -> 'bool'
| Compare two values for equality.
|
| compile(self, dialect: 'Optional[Dialect]' = None) -> 'str'
| Produce a string-compiled form of this :class:`.TypeEngine`.
|
| When called with no arguments, uses a "default" dialect
| to produce a string result.
|
| :param dialect: a :class:`.Dialect` instance.
|
| copy(self, **kw: 'Any') -> 'Self'
|
| copy_value(self, value: 'Any') -> 'Any'
|
| dialect_impl(self, dialect: 'Dialect') -> 'TypeEngine[_T]'
| Return a dialect-specific implementation for this
| :class:`.TypeEngine`.
|
| evaluates_none(self) -> 'Self'
| Return a copy of this type which has the
| :attr:`.should_evaluate_none` flag set to True.
|
| E.g.::
|
| Table(
| "some_table",
| metadata,
| Column(
| String(50).evaluates_none(),
| nullable=True,
| server_default="no value",
| ),
| )
|
| The ORM uses this flag to indicate that a positive value of ``None``
| is passed to the column in an INSERT statement, rather than omitting
| the column from the INSERT statement which has the effect of firing
| off column-level defaults. It also allows for types which have
| special behavior associated with the Python None value to indicate
| that the value doesn't necessarily translate into SQL NULL; a
| prime example of this is a JSON type which may wish to persist the
| JSON value ``'null'``.
|
| In all cases, the actual NULL SQL value can be always be
| persisted in any column by using
| the :obj:`_expression.null` SQL construct in an INSERT statement
| or associated with an ORM-mapped attribute.
|
| .. note::
|
| The "evaluates none" flag does **not** apply to a value
| of ``None`` passed to :paramref:`_schema.Column.default` or
| :paramref:`_schema.Column.server_default`; in these cases,
| ``None``
| still means "no default".
|
| .. seealso::
|
| :ref:`session_forcing_null` - in the ORM documentation
|
| :paramref:`.postgresql.JSON.none_as_null` - PostgreSQL JSON
| interaction with this flag.
|
| :attr:`.TypeEngine.should_evaluate_none` - class-level flag
|
| get_dbapi_type(self, dbapi: 'DBAPIModule') -> 'Optional[Any]'
| Return the corresponding type object from the underlying DB-API, if
| any.
|
| This can be useful for calling ``setinputsizes()``, for example.
|
| literal_processor(self, dialect: 'Dialect') -> 'Optional[_LiteralProcessorType[_T]]'
| Return a conversion function for processing literal values that are
| to be rendered directly without using binds.
|
| This function is used when the compiler makes use of the
| "literal_binds" flag, typically used in DDL generation as well
| as in certain scenarios where backends don't accept bound parameters.
|
| Returns a callable which will receive a literal Python value
| as the sole positional argument and will return a string representation
| to be rendered in a SQL statement.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.literal_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.literal_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_literal_param`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| with_variant(self, type_: '_TypeEngineArgument[Any]', *dialect_names: 'str') -> 'Self'
| Produce a copy of this type object that will utilize the given
| type when applied to the dialect of the given name.
|
| e.g.::
|
| from sqlalchemy.types import String
| from sqlalchemy.dialects import mysql
|
| string_type = String()
|
| string_type = string_type.with_variant(
| mysql.VARCHAR(collation="foo"), "mysql", "mariadb"
| )
|
| The variant mapping indicates that when this type is
| interpreted by a specific dialect, it will instead be
| transmuted into the given type, rather than using the
| primary type.
|
| .. versionchanged:: 2.0 the :meth:`_types.TypeEngine.with_variant`
| method now works with a :class:`_types.TypeEngine` object "in
| place", returning a copy of the original type rather than returning
| a wrapping object; the ``Variant`` class is no longer used.
|
| :param type\_: a :class:`.TypeEngine` that will be selected
| as a variant from the originating type, when a dialect
| of the given name is in use.
| :param \*dialect_names: one or more base names of the dialect which
| uses this type. (i.e. ``'postgresql'``, ``'mysql'``, etc.)
|
| .. versionchanged:: 2.0 multiple dialect names can be specified
| for one variant.
|
| .. seealso::
|
| :ref:`types_with_variant` - illustrates the use of
| :meth:`_types.TypeEngine.with_variant`.
|
| ----------------------------------------------------------------------
| Readonly properties inherited from sqlalchemy.sql.type_api.TypeEngine:
|
| python_type
| Return the Python type object expected to be returned
| by instances of this type, if known.
|
| Basically, for those types which enforce a return type,
| or are known across the board to do such for all common
| DBAPIs (like ``int`` for example), will return that type.
|
| If a return type is not defined, raises
| ``NotImplementedError``.
|
| Note that any type also accommodates NULL in SQL which
| means you can also get back ``None`` from any type
| in practice.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from sqlalchemy.sql.type_api.TypeEngine:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.type_api.TypeEngine:
|
| Comparator = <class 'sqlalchemy.sql.type_api.TypeEngine.Comparator'>
| Base class for custom comparison operations defined at the
| type level. See :attr:`.TypeEngine.comparator_factory`.
|
|
| __orig_bases__ = (<class 'sqlalchemy.sql.visitors.Visitable'>, typing....
|
| comparator_factory = <class 'sqlalchemy.sql.type_api.TypeEngine.Compar...
| Base class for custom comparison operations defined at the
| type level. See :attr:`.TypeEngine.comparator_factory`.
|
|
| hashable = True
|
| render_bind_cast = False
|
| render_literal_cast = False
|
| should_evaluate_none = False
|
| sort_key_function = None
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.visitors.Visitable:
|
| __class_getitem__(key: 'Any') -> 'Any'
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__() -> 'None'
| Function to initialize subclasses.
sqlalchemy.TwoPhaseTransaction
Python Library Documentation: class TwoPhaseTransaction in module sqlalchemy.engine.base
class TwoPhaseTransaction(RootTransaction)
| TwoPhaseTransaction(connection: 'Connection', xid: 'Any')
|
| Represent a two-phase transaction.
|
| A new :class:`.TwoPhaseTransaction` object may be procured
| using the :meth:`_engine.Connection.begin_twophase` method.
|
| The interface is the same as that of :class:`.Transaction`
| with the addition of the :meth:`prepare` method.
|
| Method resolution order:
| TwoPhaseTransaction
| RootTransaction
| Transaction
| sqlalchemy.engine.util.TransactionalContext
| builtins.object
|
| Methods defined here:
|
| __init__(self, connection: 'Connection', xid: 'Any')
| Initialize self. See help(type(self)) for accurate signature.
|
| prepare(self) -> 'None'
| Prepare this :class:`.TwoPhaseTransaction`.
|
| After a PREPARE, the transaction can be committed.
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| xid
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'xid': 'Any'}
|
| ----------------------------------------------------------------------
| Data descriptors inherited from RootTransaction:
|
| connection
|
| is_active
|
| ----------------------------------------------------------------------
| Methods inherited from Transaction:
|
| close(self) -> 'None'
| Close this :class:`.Transaction`.
|
| If this transaction is the base transaction in a begin/commit
| nesting, the transaction will rollback(). Otherwise, the
| method returns.
|
| This is used to cancel a Transaction without affecting the scope of
| an enclosing transaction.
|
| commit(self) -> 'None'
| Commit this :class:`.Transaction`.
|
| The implementation of this may vary based on the type of transaction in
| use:
|
| * For a simple database transaction (e.g. :class:`.RootTransaction`),
| it corresponds to a COMMIT.
|
| * For a :class:`.NestedTransaction`, it corresponds to a
| "RELEASE SAVEPOINT" operation.
|
| * For a :class:`.TwoPhaseTransaction`, DBAPI-specific methods for two
| phase transactions may be used.
|
| rollback(self) -> 'None'
| Roll back this :class:`.Transaction`.
|
| The implementation of this may vary based on the type of transaction in
| use:
|
| * For a simple database transaction (e.g. :class:`.RootTransaction`),
| it corresponds to a ROLLBACK.
|
| * For a :class:`.NestedTransaction`, it corresponds to a
| "ROLLBACK TO SAVEPOINT" operation.
|
| * For a :class:`.TwoPhaseTransaction`, DBAPI-specific methods for two
| phase transactions may be used.
|
| ----------------------------------------------------------------------
| Readonly properties inherited from Transaction:
|
| is_valid
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.engine.util.TransactionalContext:
|
| __enter__(self) -> 'Self'
|
| __exit__(self, type_: 'Any', value: 'Any', traceback: 'Any') -> 'None'
|
| ----------------------------------------------------------------------
| Data descriptors inherited from sqlalchemy.engine.util.TransactionalContext:
|
| __weakref__
| list of weak references to the object
sqlalchemy.TypeClause
Python Library Documentation: class TypeClause in module sqlalchemy.sql.elements
class TypeClause(DQLDMLClauseElement)
| TypeClause(type_: 'TypeEngine[Any]')
|
| Handle a type keyword in a SQL statement.
|
| Used by the ``Case`` statement.
|
| Method resolution order:
| TypeClause
| DQLDMLClauseElement
| ClauseElement
| sqlalchemy.sql.annotation.SupportsWrappingAnnotations
| sqlalchemy.sql.annotation.SupportsAnnotations
| sqlalchemy.sql.cache_key.MemoizedHasCacheKey
| sqlalchemy.sql.cache_key.HasCacheKey
| sqlalchemy.util.langhelpers.HasMemoized
| sqlalchemy.sql.traversals.HasCopyInternals
| sqlalchemy.sql.visitors.ExternallyTraversible
| sqlalchemy.sql.visitors.HasTraverseInternals
| CompilerElement
| sqlalchemy.sql.visitors.Visitable
| builtins.object
|
| Methods defined here:
|
| __init__(self, type_: 'TypeEngine[Any]')
| Initialize self. See help(type(self)) for accurate signature.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'_traverse_internals': '_TraverseInternalsType', 't...
|
| __visit_name__ = 'typeclause'
|
| ----------------------------------------------------------------------
| Methods inherited from ClauseElement:
|
| __bool__(self)
|
| __getstate__(self)
| Helper for pickle.
|
| __invert__(self)
|
| __repr__(self)
| Return repr(self).
|
| compare(self, other: 'ClauseElement', **kw: 'Any') -> 'bool'
| Compare this :class:`_expression.ClauseElement` to
| the given :class:`_expression.ClauseElement`.
|
| Subclasses should override the default behavior, which is a
| straight identity comparison.
|
| \**kw are arguments consumed by subclass ``compare()`` methods and
| may be used to modify the criteria for comparison
| (see :class:`_expression.ColumnElement`).
|
| description(...)
|
| entity_namespace(...)
|
| params(self, _ClauseElement__optionaldict: 'Optional[Mapping[str, Any]]' = None, **kwargs: 'Any') -> 'Self'
| Return a copy with :func:`_expression.bindparam` elements
| replaced.
|
| Returns a copy of this ClauseElement with
| :func:`_expression.bindparam`
| elements replaced with values taken from the given dictionary::
|
| >>> clause = column("x") + bindparam("foo")
| >>> print(clause.compile().params)
| {'foo':None}
| >>> print(clause.params({"foo": 7}).compile().params)
| {'foo':7}
|
| self_group(self, against: 'Optional[OperatorType]' = None) -> 'ClauseElement'
| 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.
|
| unique_params(self, _ClauseElement__optionaldict: 'Optional[Dict[str, Any]]' = None, **kwargs: 'Any') -> 'Self'
| Return a copy with :func:`_expression.bindparam` elements
| replaced.
|
| Same functionality as :meth:`_expression.ClauseElement.params`,
| except adds `unique=True`
| to affected bind parameters so that multiple statements can be
| used.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from ClauseElement:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from ClauseElement:
|
| is_clause_element = True
|
| is_dml = False
|
| is_selectable = False
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.cache_key.HasCacheKey:
|
| inherit_cache = None
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_instancemethod(fn: '_F') -> '_F'
| Decorate a method memoize its return value.
|
| :meta private:
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_attribute = <class 'sqlalchemy.util.langhelpers.HasMemoized.m...
| A read-only @property that is only evaluated once.
|
| :meta private:
|
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.visitors.HasTraverseInternals:
|
| get_children(self, *, omit_attrs: 'Tuple[str, ...]' = (), **kw: 'Any') -> 'Iterable[HasTraverseInternals]'
| Return immediate child :class:`.visitors.HasTraverseInternals`
| elements of this :class:`.visitors.HasTraverseInternals`.
|
| This is used for visit traversal.
|
| \**kw may contain flags that change the collection that is
| returned, for example to return a subset of items in order to
| cut down on larger traversals, or to return child items from a
| different context (such as schema-level collections instead of
| clause-level).
|
| ----------------------------------------------------------------------
| Methods inherited from CompilerElement:
|
| __str__(self) -> 'str'
| Return str(self).
|
| compile(self, bind: 'Optional[_HasDialect]' = None, dialect: 'Optional[Dialect]' = None, **kw: 'Any') -> 'Compiled'
| Compile this SQL expression.
|
| The return value is a :class:`~.Compiled` object.
| Calling ``str()`` or ``unicode()`` on the returned value will yield a
| string representation of the result. The
| :class:`~.Compiled` object also can return a
| dictionary of bind parameter names and values
| using the ``params`` accessor.
|
| :param bind: An :class:`.Connection` or :class:`.Engine` which
| can provide a :class:`.Dialect` in order to generate a
| :class:`.Compiled` object. If the ``bind`` and
| ``dialect`` parameters are both omitted, a default SQL compiler
| is used.
|
| :param column_keys: Used for INSERT and UPDATE statements, a list of
| column names which should be present in the VALUES clause of the
| compiled statement. If ``None``, all columns from the target table
| object are rendered.
|
| :param dialect: A :class:`.Dialect` instance which can generate
| a :class:`.Compiled` object. This argument takes precedence over
| the ``bind`` argument.
|
| :param compile_kwargs: optional dictionary of additional parameters
| that will be passed through to the compiler within all "visit"
| methods. This allows any custom flag to be passed through to
| a custom compilation construct, for example. It is also used
| for the case of passing the ``literal_binds`` flag through::
|
| from sqlalchemy.sql import table, column, select
|
| t = table("t", column("x"))
|
| s = select(t).where(t.c.x == 5)
|
| print(s.compile(compile_kwargs={"literal_binds": True}))
|
| .. seealso::
|
| :ref:`faq_sql_expression_string`
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from CompilerElement:
|
| stringify_dialect = 'default'
|
| supports_execution = False
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.visitors.Visitable:
|
| __class_getitem__(key: 'Any') -> 'Any'
|
| __init_subclass__() -> 'None'
| This method is called when a class is subclassed.
|
| The default implementation does nothing. It may be
| overridden to extend subclasses.
sqlalchemy.TypeCoerce
Python Library Documentation: class TypeCoerce in module sqlalchemy.sql.elements
class TypeCoerce(WrapsColumnExpression)
| TypeCoerce(expression: '_ColumnExpressionArgument[Any]', type_: '_TypeEngineArgument[_T]')
|
| Represent a Python-side type-coercion wrapper.
|
| :class:`.TypeCoerce` supplies the :func:`_expression.type_coerce`
| function; see that function for usage details.
|
| .. seealso::
|
| :func:`_expression.type_coerce`
|
| :func:`.cast`
|
| Method resolution order:
| TypeCoerce
| WrapsColumnExpression
| ColumnElement
| sqlalchemy.sql.roles.ColumnArgumentOrKeyRole
| sqlalchemy.sql.roles.ColumnArgumentRole
| sqlalchemy.sql.roles.StatementOptionRole
| sqlalchemy.sql.roles.WhereHavingRole
| sqlalchemy.sql.roles.OnClauseRole
| sqlalchemy.sql.roles.BinaryElementRole
| sqlalchemy.sql.roles.OrderByRole
| sqlalchemy.sql.roles.ColumnsClauseRole
| sqlalchemy.sql.roles.AllowsLambdaRole
| sqlalchemy.sql.roles.ByOfRole
| sqlalchemy.sql.roles.UsesInspection
| sqlalchemy.sql.roles.ColumnListRole
| sqlalchemy.sql.roles.LimitOffsetRole
| sqlalchemy.sql.roles.DMLColumnRole
| sqlalchemy.sql.roles.DDLConstraintColumnRole
| sqlalchemy.sql.roles.DDLExpressionRole
| sqlalchemy.sql.roles.StructuralRole
| SQLColumnExpression
| SQLCoreOperations
| sqlalchemy.sql.roles.ExpressionElementRole
| sqlalchemy.sql.roles.TypedColumnsClauseRole
| typing.Generic
| sqlalchemy.sql.operators.ColumnOperators
| sqlalchemy.sql.operators.Operators
| sqlalchemy.util.langhelpers.TypingOnly
| sqlalchemy.sql.roles.SQLRole
| DQLDMLClauseElement
| ClauseElement
| sqlalchemy.sql.annotation.SupportsWrappingAnnotations
| sqlalchemy.sql.annotation.SupportsAnnotations
| sqlalchemy.sql.cache_key.MemoizedHasCacheKey
| sqlalchemy.sql.cache_key.HasCacheKey
| sqlalchemy.util.langhelpers.HasMemoized
| sqlalchemy.sql.traversals.HasCopyInternals
| sqlalchemy.sql.visitors.ExternallyTraversible
| sqlalchemy.sql.visitors.HasTraverseInternals
| CompilerElement
| sqlalchemy.sql.visitors.Visitable
| builtins.object
|
| Methods defined here:
|
| __init__(self, expression: '_ColumnExpressionArgument[Any]', type_: '_TypeEngineArgument[_T]')
| Initialize self. See help(type(self)) for accurate signature.
|
| self_group(self, against: 'Optional[OperatorType]' = None) -> 'TypeCoerce[_T]'
| 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.
|
| typed_expression(...)
|
| ----------------------------------------------------------------------
| Readonly properties defined here:
|
| wrapped_column_expression
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'_traverse_internals': '_TraverseInternalsType', 'c...
|
| __orig_bases__ = (sqlalchemy.sql.elements.WrapsColumnExpression[~_T],)
|
| __parameters__ = (~_T,)
|
| __visit_name__ = 'type_coerce'
|
| ----------------------------------------------------------------------
| Methods inherited from ColumnElement:
|
| __getattr__(self, key: 'str') -> 'Any'
|
| __setstate__(self, state)
|
| base_columns(...)
|
| cast(self, type_: '_TypeEngineArgument[_OPT]') -> 'Cast[_OPT]'
| Produce a type cast, i.e. ``CAST(<expression> AS <type>)``.
|
| This is a shortcut to the :func:`_expression.cast` function.
|
| .. seealso::
|
| :ref:`tutorial_casts`
|
| :func:`_expression.cast`
|
| :func:`_expression.type_coerce`
|
| comparator(...)
|
| label(self, name: 'Optional[str]') -> 'Label[_T]'
| Produce a column label, i.e. ``<columnname> AS <name>``.
|
| This is a shortcut to the :func:`_expression.label` function.
|
| If 'name' is ``None``, an anonymous label name will be generated.
|
| operate(self, op: 'operators.OperatorType', *other: 'Any', **kwargs: 'Any') -> 'ColumnElement[Any]'
| Operate on an argument.
|
| This is the lowest level of operation, raises
| :class:`NotImplementedError` by default.
|
| Overriding this on a subclass can allow common
| behavior to be applied to all operations.
| For example, overriding :class:`.ColumnOperators`
| to apply ``func.lower()`` to the left and right
| side::
|
| class MyComparator(ColumnOperators):
| def operate(self, op, other, **kwargs):
| return op(func.lower(self), func.lower(other), **kwargs)
|
| :param op: Operator callable.
| :param \*other: the 'other' side of the operation. Will
| be a single scalar for most operations.
| :param \**kwargs: modifiers. These may be passed by special
| operators such as :meth:`ColumnOperators.contains`.
|
| proxy_set(...)
| set of all columns we are proxying
|
| as of 2.0 this is explicitly deannotated columns. previously it was
| effectively deannotated columns but wasn't enforced. annotated
| columns should basically not go into sets if at all possible because
| their hashing behavior is very non-performant.
|
| reverse_operate(self, op: 'operators.OperatorType', other: 'Any', **kwargs: 'Any') -> 'ColumnElement[Any]'
| Reverse operate on an argument.
|
| Usage is the same as :meth:`operate`.
|
| shares_lineage(self, othercolumn: 'ColumnElement[Any]') -> 'bool'
| Return True if the given :class:`_expression.ColumnElement`
| has a common ancestor to this :class:`_expression.ColumnElement`.
|
| type(...)
|
| ----------------------------------------------------------------------
| Readonly properties inherited from ColumnElement:
|
| anon_key_label
| .. deprecated:: 1.4 The :attr:`_expression.ColumnElement.anon_key_label` attribute is now private, and the public accessor is deprecated.
|
| anon_label
| .. deprecated:: 1.4 The :attr:`_expression.ColumnElement.anon_label` attribute is now private, and the public accessor is deprecated.
|
| expression
| Return a column expression.
|
| Part of the inspection interface; returns self.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from ColumnElement:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from ColumnElement:
|
| foreign_keys = frozenset()
|
| key = None
|
| primary_key = False
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.AllowsLambdaRole:
|
| allows_lambda = True
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.UsesInspection:
|
| uses_inspection = True
|
| ----------------------------------------------------------------------
| Class methods inherited from typing.Generic:
|
| __class_getitem__(...)
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__(...)
| Function to initialize subclasses.
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.operators.ColumnOperators:
|
| __add__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``+`` operator.
|
| In a column context, produces the clause ``a + b``
| if the parent object has non-string affinity.
| If the parent object has a string affinity,
| produces the concatenation operator, ``a || b`` -
| see :meth:`.ColumnOperators.concat`.
|
| __contains__(self, other: 'Any') -> 'ColumnOperators'
|
| __eq__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``==`` operator.
|
| In a column context, produces the clause ``a = b``.
| If the target is ``None``, produces ``a IS NULL``.
|
| __floordiv__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``//`` operator.
|
| In a column context, produces the clause ``a / b``,
| which is the same as "truediv", but considers the result
| type to be integer.
|
| .. versionadded:: 2.0
|
| __ge__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``>=`` operator.
|
| In a column context, produces the clause ``a >= b``.
|
| __getitem__(self, index: 'Any') -> 'ColumnOperators'
| Implement the [] operator.
|
| This can be used by some database-specific types
| such as PostgreSQL ARRAY and HSTORE.
|
| __gt__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``>`` operator.
|
| In a column context, produces the clause ``a > b``.
|
| __hash__(self, /) from builtins.object
| Return hash(self).
|
| __le__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``<=`` operator.
|
| In a column context, produces the clause ``a <= b``.
|
| __lshift__(self, other: 'Any') -> 'ColumnOperators'
| implement the << operator.
|
| Not used by SQLAlchemy core, this is provided
| for custom operator systems which want to use
| << as an extension point.
|
| __lt__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``<`` operator.
|
| In a column context, produces the clause ``a < b``.
|
| __mod__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``%`` operator.
|
| In a column context, produces the clause ``a % b``.
|
| __mul__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``*`` operator.
|
| In a column context, produces the clause ``a * b``.
|
| __ne__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``!=`` operator.
|
| In a column context, produces the clause ``a != b``.
| If the target is ``None``, produces ``a IS NOT NULL``.
|
| __neg__(self) -> 'ColumnOperators'
| Implement the ``-`` operator.
|
| In a column context, produces the clause ``-a``.
|
| __radd__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``+`` operator in reverse.
|
| See :meth:`.ColumnOperators.__add__`.
|
| __rfloordiv__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``//`` operator in reverse.
|
| See :meth:`.ColumnOperators.__floordiv__`.
|
| __rmod__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``%`` operator in reverse.
|
| See :meth:`.ColumnOperators.__mod__`.
|
| __rmul__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``*`` operator in reverse.
|
| See :meth:`.ColumnOperators.__mul__`.
|
| __rshift__(self, other: 'Any') -> 'ColumnOperators'
| implement the >> operator.
|
| Not used by SQLAlchemy core, this is provided
| for custom operator systems which want to use
| >> as an extension point.
|
| __rsub__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``-`` operator in reverse.
|
| See :meth:`.ColumnOperators.__sub__`.
|
| __rtruediv__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``/`` operator in reverse.
|
| See :meth:`.ColumnOperators.__truediv__`.
|
| __sub__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``-`` operator.
|
| In a column context, produces the clause ``a - b``.
|
| __truediv__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``/`` operator.
|
| In a column context, produces the clause ``a / b``, and
| considers the result type to be numeric.
|
| .. versionchanged:: 2.0 The truediv operator against two integers
| is now considered to return a numeric value. Behavior on specific
| backends may vary.
|
| all_(self) -> 'ColumnOperators'
| Produce an :func:`_expression.all_` clause against the
| parent object.
|
| See the documentation for :func:`_sql.all_` for examples.
|
| .. note:: be sure to not confuse the newer
| :meth:`_sql.ColumnOperators.all_` method with the **legacy**
| version of this method, the :meth:`_types.ARRAY.Comparator.all`
| method that's specific to :class:`_types.ARRAY`, which uses a
| different calling style.
|
| any_(self) -> 'ColumnOperators'
| Produce an :func:`_expression.any_` clause against the
| parent object.
|
| See the documentation for :func:`_sql.any_` for examples.
|
| .. note:: be sure to not confuse the newer
| :meth:`_sql.ColumnOperators.any_` method with the **legacy**
| version of this method, the :meth:`_types.ARRAY.Comparator.any`
| method that's specific to :class:`_types.ARRAY`, which uses a
| different calling style.
|
| asc(self) -> 'ColumnOperators'
| Produce a :func:`_expression.asc` clause against the
| parent object.
|
| between(self, cleft: 'Any', cright: 'Any', symmetric: 'bool' = False) -> 'ColumnOperators'
| Produce a :func:`_expression.between` clause against
| the parent object, given the lower and upper range.
|
| bitwise_and(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise AND operation, typically via the ``&``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_lshift(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise LSHIFT operation, typically via the ``<<``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_not(self) -> 'ColumnOperators'
| Produce a bitwise NOT operation, typically via the ``~``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_or(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise OR operation, typically via the ``|``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_rshift(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise RSHIFT operation, typically via the ``>>``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_xor(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise XOR operation, typically via the ``^``
| operator, or ``#`` for PostgreSQL.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| collate(self, collation: 'str') -> 'ColumnOperators'
| Produce a :func:`_expression.collate` clause against
| the parent object, given the collation string.
|
| .. seealso::
|
| :func:`_expression.collate`
|
| concat(self, other: 'Any') -> 'ColumnOperators'
| Implement the 'concat' operator.
|
| In a column context, produces the clause ``a || b``,
| or uses the ``concat()`` operator on MySQL.
|
| contains(self, other: 'Any', **kw: 'Any') -> 'ColumnOperators'
| Implement the 'contains' operator.
|
| Produces a LIKE expression that tests against a match for the middle
| of a string value:
|
| .. sourcecode:: sql
|
| column LIKE '%' || <other> || '%'
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.contains("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.contains.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.contains.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.contains.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.contains("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE '%' || :param || '%' ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.contains("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE '%' || :param || '%' ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.contains.autoescape`::
|
| somecolumn.contains("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.startswith`
|
| :meth:`.ColumnOperators.endswith`
|
| :meth:`.ColumnOperators.like`
|
| desc(self) -> 'ColumnOperators'
| Produce a :func:`_expression.desc` clause against the
| parent object.
|
| distinct(self) -> 'ColumnOperators'
| Produce a :func:`_expression.distinct` clause against the
| parent object.
|
| endswith(self, other: 'Any', escape: 'Optional[str]' = None, autoescape: 'bool' = False) -> 'ColumnOperators'
| Implement the 'endswith' operator.
|
| Produces a LIKE expression that tests against a match for the end
| of a string value:
|
| .. sourcecode:: sql
|
| column LIKE '%' || <other>
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.endswith("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.endswith.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.endswith.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.endswith.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.endswith("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE '%' || :param ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.endswith("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE '%' || :param ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.endswith.autoescape`::
|
| somecolumn.endswith("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.startswith`
|
| :meth:`.ColumnOperators.contains`
|
| :meth:`.ColumnOperators.like`
|
| icontains(self, other: 'Any', **kw: 'Any') -> 'ColumnOperators'
| Implement the ``icontains`` operator, e.g. case insensitive
| version of :meth:`.ColumnOperators.contains`.
|
| Produces a LIKE expression that tests against an insensitive match
| for the middle of a string value:
|
| .. sourcecode:: sql
|
| lower(column) LIKE '%' || lower(<other>) || '%'
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.icontains("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.icontains.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.icontains.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.icontains.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.icontains("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE '%' || lower(:param) || '%' ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.icontains("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE '%' || lower(:param) || '%' ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.contains.autoescape`::
|
| somecolumn.icontains("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.contains`
|
| iendswith(self, other: 'Any', escape: 'Optional[str]' = None, autoescape: 'bool' = False) -> 'ColumnOperators'
| Implement the ``iendswith`` operator, e.g. case insensitive
| version of :meth:`.ColumnOperators.endswith`.
|
| Produces a LIKE expression that tests against an insensitive match
| for the end of a string value:
|
| .. sourcecode:: sql
|
| lower(column) LIKE '%' || lower(<other>)
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.iendswith("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.iendswith.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.iendswith.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.iendswith.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.iendswith("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE '%' || lower(:param) ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.iendswith("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE '%' || lower(:param) ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.iendswith.autoescape`::
|
| somecolumn.endswith("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.endswith`
|
| ilike(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
| Implement the ``ilike`` operator, e.g. case insensitive LIKE.
|
| In a column context, produces an expression either of the form:
|
| .. sourcecode:: sql
|
| lower(a) LIKE lower(other)
|
| Or on backends that support the ILIKE operator:
|
| .. sourcecode:: sql
|
| a ILIKE other
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.ilike("%foobar%"))
|
| :param other: expression to be compared
| :param escape: optional escape character, renders the ``ESCAPE``
| keyword, e.g.::
|
| somecolumn.ilike("foo/%bar", escape="/")
|
| .. seealso::
|
| :meth:`.ColumnOperators.like`
|
| in_(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``in`` operator.
|
| In a column context, produces the clause ``column IN <other>``.
|
| The given parameter ``other`` may be:
|
| * A list of literal values,
| e.g.::
|
| stmt.where(column.in_([1, 2, 3]))
|
| In this calling form, the list of items is converted to a set of
| bound parameters the same length as the list given:
|
| .. sourcecode:: sql
|
| WHERE COL IN (?, ?, ?)
|
| * A list of tuples may be provided if the comparison is against a
| :func:`.tuple_` containing multiple expressions::
|
| from sqlalchemy import tuple_
|
| stmt.where(tuple_(col1, col2).in_([(1, 10), (2, 20), (3, 30)]))
|
| * An empty list,
| e.g.::
|
| stmt.where(column.in_([]))
|
| In this calling form, the expression renders an "empty set"
| expression. These expressions are tailored to individual backends
| and are generally trying to get an empty SELECT statement as a
| subquery. Such as on SQLite, the expression is:
|
| .. sourcecode:: sql
|
| WHERE col IN (SELECT 1 FROM (SELECT 1) WHERE 1!=1)
|
| .. versionchanged:: 1.4 empty IN expressions now use an
| execution-time generated SELECT subquery in all cases.
|
| * A bound parameter, e.g. :func:`.bindparam`, may be used if it
| includes the :paramref:`.bindparam.expanding` flag::
|
| stmt.where(column.in_(bindparam("value", expanding=True)))
|
| In this calling form, the expression renders a special non-SQL
| placeholder expression that looks like:
|
| .. sourcecode:: sql
|
| WHERE COL IN ([EXPANDING_value])
|
| This placeholder expression is intercepted at statement execution
| time to be converted into the variable number of bound parameter
| form illustrated earlier. If the statement were executed as::
|
| connection.execute(stmt, {"value": [1, 2, 3]})
|
| The database would be passed a bound parameter for each value:
|
| .. sourcecode:: sql
|
| WHERE COL IN (?, ?, ?)
|
| .. versionadded:: 1.2 added "expanding" bound parameters
|
| If an empty list is passed, a special "empty list" expression,
| which is specific to the database in use, is rendered. On
| SQLite this would be:
|
| .. sourcecode:: sql
|
| WHERE COL IN (SELECT 1 FROM (SELECT 1) WHERE 1!=1)
|
| .. versionadded:: 1.3 "expanding" bound parameters now support
| empty lists
|
| * a :func:`_expression.select` construct, which is usually a
| correlated scalar select::
|
| stmt.where(
| column.in_(select(othertable.c.y).where(table.c.x == othertable.c.x))
| )
|
| In this calling form, :meth:`.ColumnOperators.in_` renders as given:
|
| .. sourcecode:: sql
|
| WHERE COL IN (SELECT othertable.y
| FROM othertable WHERE othertable.x = table.x)
|
| :param other: a list of literals, a :func:`_expression.select`
| construct, or a :func:`.bindparam` construct that includes the
| :paramref:`.bindparam.expanding` flag set to True.
|
| is_(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``IS`` operator.
|
| Normally, ``IS`` is generated automatically when comparing to a
| value of ``None``, which resolves to ``NULL``. However, explicit
| usage of ``IS`` may be desirable if comparing to boolean values
| on certain platforms.
|
| .. seealso:: :meth:`.ColumnOperators.is_not`
|
| is_distinct_from(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``IS DISTINCT FROM`` operator.
|
| Renders "a IS DISTINCT FROM b" on most platforms;
| on some such as SQLite may render "a IS NOT b".
|
| is_not(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``IS NOT`` operator.
|
| Normally, ``IS NOT`` is generated automatically when comparing to a
| value of ``None``, which resolves to ``NULL``. However, explicit
| usage of ``IS NOT`` may be desirable if comparing to boolean values
| on certain platforms.
|
| .. versionchanged:: 1.4 The ``is_not()`` operator is renamed from
| ``isnot()`` in previous releases. The previous name remains
| available for backwards compatibility.
|
| .. seealso:: :meth:`.ColumnOperators.is_`
|
| is_not_distinct_from(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``IS NOT DISTINCT FROM`` operator.
|
| Renders "a IS NOT DISTINCT FROM b" on most platforms;
| on some such as SQLite may render "a IS b".
|
| .. versionchanged:: 1.4 The ``is_not_distinct_from()`` operator is
| renamed from ``isnot_distinct_from()`` in previous releases.
| The previous name remains available for backwards compatibility.
|
| isnot = is_not(self, other: 'Any') -> 'ColumnOperators'
|
| isnot_distinct_from = is_not_distinct_from(self, other: 'Any') -> 'ColumnOperators'
|
| istartswith(self, other: 'Any', escape: 'Optional[str]' = None, autoescape: 'bool' = False) -> 'ColumnOperators'
| Implement the ``istartswith`` operator, e.g. case insensitive
| version of :meth:`.ColumnOperators.startswith`.
|
| Produces a LIKE expression that tests against an insensitive
| match for the start of a string value:
|
| .. sourcecode:: sql
|
| lower(column) LIKE lower(<other>) || '%'
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.istartswith("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.istartswith.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.istartswith.escape` parameter will
| establish a given character as an escape character which can be of
| use when the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.istartswith.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.istartswith("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE lower(:param) || '%' ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.istartswith("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE lower(:param) || '%' ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.istartswith.autoescape`::
|
| somecolumn.istartswith("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.startswith`
|
| like(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
| Implement the ``like`` operator.
|
| In a column context, produces the expression:
|
| .. sourcecode:: sql
|
| a LIKE other
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.like("%foobar%"))
|
| :param other: expression to be compared
| :param escape: optional escape character, renders the ``ESCAPE``
| keyword, e.g.::
|
| somecolumn.like("foo/%bar", escape="/")
|
| .. seealso::
|
| :meth:`.ColumnOperators.ilike`
|
| match(self, other: 'Any', **kwargs: 'Any') -> 'ColumnOperators'
| Implements a database-specific 'match' operator.
|
| :meth:`_sql.ColumnOperators.match` attempts to resolve to
| a MATCH-like function or operator provided by the backend.
| Examples include:
|
| * PostgreSQL - renders ``x @@ plainto_tsquery(y)``
|
| .. versionchanged:: 2.0 ``plainto_tsquery()`` is used instead
| of ``to_tsquery()`` for PostgreSQL now; for compatibility with
| other forms, see :ref:`postgresql_match`.
|
|
| * MySQL - renders ``MATCH (x) AGAINST (y IN BOOLEAN MODE)``
|
| .. seealso::
|
| :class:`_mysql.match` - MySQL specific construct with
| additional features.
|
| * Oracle Database - renders ``CONTAINS(x, y)``
| * other backends may provide special implementations.
| * Backends without any special implementation will emit
| the operator as "MATCH". This is compatible with SQLite, for
| example.
|
| not_ilike(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
| implement the ``NOT ILIKE`` operator.
|
| This is equivalent to using negation with
| :meth:`.ColumnOperators.ilike`, i.e. ``~x.ilike(y)``.
|
| .. versionchanged:: 1.4 The ``not_ilike()`` operator is renamed from
| ``notilike()`` in previous releases. The previous name remains
| available for backwards compatibility.
|
| .. seealso::
|
| :meth:`.ColumnOperators.ilike`
|
| not_in(self, other: 'Any') -> 'ColumnOperators'
| implement the ``NOT IN`` operator.
|
| This is equivalent to using negation with
| :meth:`.ColumnOperators.in_`, i.e. ``~x.in_(y)``.
|
| In the case that ``other`` is an empty sequence, the compiler
| produces an "empty not in" expression. This defaults to the
| expression "1 = 1" to produce true in all cases. The
| :paramref:`_sa.create_engine.empty_in_strategy` may be used to
| alter this behavior.
|
| .. versionchanged:: 1.4 The ``not_in()`` operator is renamed from
| ``notin_()`` in previous releases. The previous name remains
| available for backwards compatibility.
|
| .. versionchanged:: 1.2 The :meth:`.ColumnOperators.in_` and
| :meth:`.ColumnOperators.not_in` operators
| now produce a "static" expression for an empty IN sequence
| by default.
|
| .. seealso::
|
| :meth:`.ColumnOperators.in_`
|
| not_like(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
| implement the ``NOT LIKE`` operator.
|
| This is equivalent to using negation with
| :meth:`.ColumnOperators.like`, i.e. ``~x.like(y)``.
|
| .. versionchanged:: 1.4 The ``not_like()`` operator is renamed from
| ``notlike()`` in previous releases. The previous name remains
| available for backwards compatibility.
|
| .. seealso::
|
| :meth:`.ColumnOperators.like`
|
| notilike = not_ilike(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
|
| notin_ = not_in(self, other: 'Any') -> 'ColumnOperators'
|
| notlike = not_like(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
|
| nulls_first(self) -> 'ColumnOperators'
| Produce a :func:`_expression.nulls_first` clause against the
| parent object.
|
| .. versionchanged:: 1.4 The ``nulls_first()`` operator is
| renamed from ``nullsfirst()`` in previous releases.
| The previous name remains available for backwards compatibility.
|
| nulls_last(self) -> 'ColumnOperators'
| Produce a :func:`_expression.nulls_last` clause against the
| parent object.
|
| .. versionchanged:: 1.4 The ``nulls_last()`` operator is
| renamed from ``nullslast()`` in previous releases.
| The previous name remains available for backwards compatibility.
|
| nullsfirst = nulls_first(self) -> 'ColumnOperators'
|
| nullslast = nulls_last(self) -> 'ColumnOperators'
|
| regexp_match(self, pattern: 'Any', flags: 'Optional[str]' = None) -> 'ColumnOperators'
| Implements a database-specific 'regexp match' operator.
|
| E.g.::
|
| stmt = select(table.c.some_column).where(
| table.c.some_column.regexp_match("^(b|c)")
| )
|
| :meth:`_sql.ColumnOperators.regexp_match` attempts to resolve to
| a REGEXP-like function or operator provided by the backend, however
| the specific regular expression syntax and flags available are
| **not backend agnostic**.
|
| Examples include:
|
| * PostgreSQL - renders ``x ~ y`` or ``x !~ y`` when negated.
| * Oracle Database - renders ``REGEXP_LIKE(x, y)``
| * SQLite - uses SQLite's ``REGEXP`` placeholder operator and calls into
| the Python ``re.match()`` builtin.
| * other backends may provide special implementations.
| * Backends without any special implementation will emit
| the operator as "REGEXP" or "NOT REGEXP". This is compatible with
| SQLite and MySQL, for example.
|
| Regular expression support is currently implemented for Oracle
| Database, PostgreSQL, MySQL and MariaDB. Partial support is available
| for SQLite. Support among third-party dialects may vary.
|
| :param pattern: The regular expression pattern string or column
| clause.
| :param flags: Any regular expression string flags to apply, passed as
| plain Python string only. These flags are backend specific.
| Some backends, like PostgreSQL and MariaDB, may alternatively
| specify the flags as part of the pattern.
| When using the ignore case flag 'i' in PostgreSQL, the ignore case
| regexp match operator ``~*`` or ``!~*`` will be used.
|
| .. versionadded:: 1.4
|
| .. versionchanged:: 1.4.48, 2.0.18 Note that due to an implementation
| error, the "flags" parameter previously accepted SQL expression
| objects such as column expressions in addition to plain Python
| strings. This implementation did not work correctly with caching
| and was removed; strings only should be passed for the "flags"
| parameter, as these flags are rendered as literal inline values
| within SQL expressions.
|
| .. seealso::
|
| :meth:`_sql.ColumnOperators.regexp_replace`
|
| regexp_replace(self, pattern: 'Any', replacement: 'Any', flags: 'Optional[str]' = None) -> 'ColumnOperators'
| Implements a database-specific 'regexp replace' operator.
|
| E.g.::
|
| stmt = select(
| table.c.some_column.regexp_replace("b(..)", "XY", flags="g")
| )
|
| :meth:`_sql.ColumnOperators.regexp_replace` attempts to resolve to
| a REGEXP_REPLACE-like function provided by the backend, that
| usually emit the function ``REGEXP_REPLACE()``. However,
| the specific regular expression syntax and flags available are
| **not backend agnostic**.
|
| Regular expression replacement support is currently implemented for
| Oracle Database, PostgreSQL, MySQL 8 or greater and MariaDB. Support
| among third-party dialects may vary.
|
| :param pattern: The regular expression pattern string or column
| clause.
| :param pattern: The replacement string or column clause.
| :param flags: Any regular expression string flags to apply, passed as
| plain Python string only. These flags are backend specific.
| Some backends, like PostgreSQL and MariaDB, may alternatively
| specify the flags as part of the pattern.
|
| .. versionadded:: 1.4
|
| .. versionchanged:: 1.4.48, 2.0.18 Note that due to an implementation
| error, the "flags" parameter previously accepted SQL expression
| objects such as column expressions in addition to plain Python
| strings. This implementation did not work correctly with caching
| and was removed; strings only should be passed for the "flags"
| parameter, as these flags are rendered as literal inline values
| within SQL expressions.
|
|
| .. seealso::
|
| :meth:`_sql.ColumnOperators.regexp_match`
|
| startswith(self, other: 'Any', escape: 'Optional[str]' = None, autoescape: 'bool' = False) -> 'ColumnOperators'
| Implement the ``startswith`` operator.
|
| Produces a LIKE expression that tests against a match for the start
| of a string value:
|
| .. sourcecode:: sql
|
| column LIKE <other> || '%'
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.startswith("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.startswith.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.startswith.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.startswith.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.startswith("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE :param || '%' ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.startswith("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE :param || '%' ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.startswith.autoescape`::
|
| somecolumn.startswith("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.endswith`
|
| :meth:`.ColumnOperators.contains`
|
| :meth:`.ColumnOperators.like`
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.operators.ColumnOperators:
|
| timetuple = None
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.operators.Operators:
|
| __and__(self, other: 'Any') -> 'Operators'
| Implement the ``&`` operator.
|
| When used with SQL expressions, results in an
| AND operation, equivalent to
| :func:`_expression.and_`, that is::
|
| a & b
|
| is equivalent to::
|
| from sqlalchemy import and_
|
| and_(a, b)
|
| Care should be taken when using ``&`` regarding
| operator precedence; the ``&`` operator has the highest precedence.
| The operands should be enclosed in parenthesis if they contain
| further sub expressions::
|
| (a == 2) & (b == 4)
|
| __invert__(self) -> 'Operators'
| Implement the ``~`` operator.
|
| When used with SQL expressions, results in a
| NOT operation, equivalent to
| :func:`_expression.not_`, that is::
|
| ~a
|
| is equivalent to::
|
| from sqlalchemy import not_
|
| not_(a)
|
| __or__(self, other: 'Any') -> 'Operators'
| Implement the ``|`` operator.
|
| When used with SQL expressions, results in an
| OR operation, equivalent to
| :func:`_expression.or_`, that is::
|
| a | b
|
| is equivalent to::
|
| from sqlalchemy import or_
|
| or_(a, b)
|
| Care should be taken when using ``|`` regarding
| operator precedence; the ``|`` operator has the highest precedence.
| The operands should be enclosed in parenthesis if they contain
| further sub expressions::
|
| (a == 2) | (b == 4)
|
| __sa_operate__ = operate(self, op: 'OperatorType', *other: 'Any', **kwargs: 'Any') -> 'Operators'
| Operate on an argument.
|
| This is the lowest level of operation, raises
| :class:`NotImplementedError` by default.
|
| Overriding this on a subclass can allow common
| behavior to be applied to all operations.
| For example, overriding :class:`.ColumnOperators`
| to apply ``func.lower()`` to the left and right
| side::
|
| class MyComparator(ColumnOperators):
| def operate(self, op, other, **kwargs):
| return op(func.lower(self), func.lower(other), **kwargs)
|
| :param op: Operator callable.
| :param \*other: the 'other' side of the operation. Will
| be a single scalar for most operations.
| :param \**kwargs: modifiers. These may be passed by special
| operators such as :meth:`ColumnOperators.contains`.
|
| bool_op(self, opstring: 'str', precedence: 'int' = 0, python_impl: 'Optional[Callable[..., Any]]' = None) -> 'Callable[[Any], Operators]'
| Return a custom boolean operator.
|
| This method is shorthand for calling
| :meth:`.Operators.op` and passing the
| :paramref:`.Operators.op.is_comparison`
| flag with True. A key advantage to using :meth:`.Operators.bool_op`
| is that when using column constructs, the "boolean" nature of the
| returned expression will be present for :pep:`484` purposes.
|
| .. seealso::
|
| :meth:`.Operators.op`
|
| op(self, opstring: 'str', precedence: 'int' = 0, is_comparison: 'bool' = False, return_type: 'Optional[Union[Type[TypeEngine[Any]], TypeEngine[Any]]]' = None, python_impl: 'Optional[Callable[..., Any]]' = None) -> 'Callable[[Any], Operators]'
| Produce a generic operator function.
|
| e.g.::
|
| somecolumn.op("*")(5)
|
| produces::
|
| somecolumn * 5
|
| This function can also be used to make bitwise operators explicit. For
| example::
|
| somecolumn.op("&")(0xFF)
|
| is a bitwise AND of the value in ``somecolumn``.
|
| :param opstring: a string which will be output as the infix operator
| between this element and the expression passed to the
| generated function.
|
| :param precedence: precedence which the database is expected to apply
| to the operator in SQL expressions. This integer value acts as a hint
| for the SQL compiler to know when explicit parenthesis should be
| rendered around a particular operation. A lower number will cause the
| expression to be parenthesized when applied against another operator
| with higher precedence. The default value of ``0`` is lower than all
| operators except for the comma (``,``) and ``AS`` operators. A value
| of 100 will be higher or equal to all operators, and -100 will be
| lower than or equal to all operators.
|
| .. seealso::
|
| :ref:`faq_sql_expression_op_parenthesis` - detailed description
| of how the SQLAlchemy SQL compiler renders parenthesis
|
| :param is_comparison: legacy; if True, the operator will be considered
| as a "comparison" operator, that is which evaluates to a boolean
| true/false value, like ``==``, ``>``, etc. This flag is provided
| so that ORM relationships can establish that the operator is a
| comparison operator when used in a custom join condition.
|
| Using the ``is_comparison`` parameter is superseded by using the
| :meth:`.Operators.bool_op` method instead; this more succinct
| operator sets this parameter automatically, but also provides
| correct :pep:`484` typing support as the returned object will
| express a "boolean" datatype, i.e. ``BinaryExpression[bool]``.
|
| :param return_type: a :class:`.TypeEngine` class or object that will
| force the return type of an expression produced by this operator
| to be of that type. By default, operators that specify
| :paramref:`.Operators.op.is_comparison` will resolve to
| :class:`.Boolean`, and those that do not will be of the same
| type as the left-hand operand.
|
| :param python_impl: an optional Python function that can evaluate
| two Python values in the same way as this operator works when
| run on the database server. Useful for in-Python SQL expression
| evaluation functions, such as for ORM hybrid attributes, and the
| ORM "evaluator" used to match objects in a session after a multi-row
| update or delete.
|
| e.g.::
|
| >>> expr = column("x").op("+", python_impl=lambda a, b: a + b)("y")
|
| The operator for the above expression will also work for non-SQL
| left and right objects::
|
| >>> expr.operator(5, 10)
| 15
|
| .. versionadded:: 2.0
|
|
| .. seealso::
|
| :meth:`.Operators.bool_op`
|
| :ref:`types_operators`
|
| :ref:`relationship_custom_operator`
|
| ----------------------------------------------------------------------
| Methods inherited from ClauseElement:
|
| __bool__(self)
|
| __getstate__(self)
| Helper for pickle.
|
| __repr__(self)
| Return repr(self).
|
| compare(self, other: 'ClauseElement', **kw: 'Any') -> 'bool'
| Compare this :class:`_expression.ClauseElement` to
| the given :class:`_expression.ClauseElement`.
|
| Subclasses should override the default behavior, which is a
| straight identity comparison.
|
| \**kw are arguments consumed by subclass ``compare()`` methods and
| may be used to modify the criteria for comparison
| (see :class:`_expression.ColumnElement`).
|
| description(...)
|
| entity_namespace(...)
|
| params(self, _ClauseElement__optionaldict: 'Optional[Mapping[str, Any]]' = None, **kwargs: 'Any') -> 'Self'
| Return a copy with :func:`_expression.bindparam` elements
| replaced.
|
| Returns a copy of this ClauseElement with
| :func:`_expression.bindparam`
| elements replaced with values taken from the given dictionary::
|
| >>> clause = column("x") + bindparam("foo")
| >>> print(clause.compile().params)
| {'foo':None}
| >>> print(clause.params({"foo": 7}).compile().params)
| {'foo':7}
|
| unique_params(self, _ClauseElement__optionaldict: 'Optional[Dict[str, Any]]' = None, **kwargs: 'Any') -> 'Self'
| Return a copy with :func:`_expression.bindparam` elements
| replaced.
|
| Same functionality as :meth:`_expression.ClauseElement.params`,
| except adds `unique=True`
| to affected bind parameters so that multiple statements can be
| used.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from ClauseElement:
|
| is_clause_element = True
|
| is_dml = False
|
| is_selectable = False
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.cache_key.HasCacheKey:
|
| inherit_cache = None
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_instancemethod(fn: '_F') -> '_F'
| Decorate a method memoize its return value.
|
| :meta private:
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_attribute = <class 'sqlalchemy.util.langhelpers.HasMemoized.m...
| A read-only @property that is only evaluated once.
|
| :meta private:
|
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.visitors.HasTraverseInternals:
|
| get_children(self, *, omit_attrs: 'Tuple[str, ...]' = (), **kw: 'Any') -> 'Iterable[HasTraverseInternals]'
| Return immediate child :class:`.visitors.HasTraverseInternals`
| elements of this :class:`.visitors.HasTraverseInternals`.
|
| This is used for visit traversal.
|
| \**kw may contain flags that change the collection that is
| returned, for example to return a subset of items in order to
| cut down on larger traversals, or to return child items from a
| different context (such as schema-level collections instead of
| clause-level).
|
| ----------------------------------------------------------------------
| Methods inherited from CompilerElement:
|
| __str__(self) -> 'str'
| Return str(self).
|
| compile(self, bind: 'Optional[_HasDialect]' = None, dialect: 'Optional[Dialect]' = None, **kw: 'Any') -> 'Compiled'
| Compile this SQL expression.
|
| The return value is a :class:`~.Compiled` object.
| Calling ``str()`` or ``unicode()`` on the returned value will yield a
| string representation of the result. The
| :class:`~.Compiled` object also can return a
| dictionary of bind parameter names and values
| using the ``params`` accessor.
|
| :param bind: An :class:`.Connection` or :class:`.Engine` which
| can provide a :class:`.Dialect` in order to generate a
| :class:`.Compiled` object. If the ``bind`` and
| ``dialect`` parameters are both omitted, a default SQL compiler
| is used.
|
| :param column_keys: Used for INSERT and UPDATE statements, a list of
| column names which should be present in the VALUES clause of the
| compiled statement. If ``None``, all columns from the target table
| object are rendered.
|
| :param dialect: A :class:`.Dialect` instance which can generate
| a :class:`.Compiled` object. This argument takes precedence over
| the ``bind`` argument.
|
| :param compile_kwargs: optional dictionary of additional parameters
| that will be passed through to the compiler within all "visit"
| methods. This allows any custom flag to be passed through to
| a custom compilation construct, for example. It is also used
| for the case of passing the ``literal_binds`` flag through::
|
| from sqlalchemy.sql import table, column, select
|
| t = table("t", column("x"))
|
| s = select(t).where(t.c.x == 5)
|
| print(s.compile(compile_kwargs={"literal_binds": True}))
|
| .. seealso::
|
| :ref:`faq_sql_expression_string`
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from CompilerElement:
|
| stringify_dialect = 'default'
|
| supports_execution = False
sqlalchemy.TypeCompiler
Python Library Documentation: class TypeCompiler in module sqlalchemy.sql.compiler
class TypeCompiler(sqlalchemy.util.langhelpers.EnsureKWArg)
| TypeCompiler(dialect: 'Dialect')
|
| Produces DDL specification for TypeEngine objects.
|
| Method resolution order:
| TypeCompiler
| sqlalchemy.util.langhelpers.EnsureKWArg
| builtins.object
|
| Methods defined here:
|
| __init__(self, dialect: 'Dialect')
| Initialize self. See help(type(self)) for accurate signature.
|
| process(self, type_: 'TypeEngine[Any]', **kw: 'Any') -> 'str'
|
| visit_unsupported_compilation(self, element: 'Any', err: 'Exception', **kw: 'Any') -> 'NoReturn'
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| ensure_kwarg = r'visit_\w+'
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.util.langhelpers.EnsureKWArg:
|
| __init_subclass__() -> 'None'
| This method is called when a class is subclassed.
|
| The default implementation does nothing. It may be
| overridden to extend subclasses.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from sqlalchemy.util.langhelpers.EnsureKWArg:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
sqlalchemy.TypeDecorator
Python Library Documentation: class TypeDecorator in module sqlalchemy.sql.type_api
class TypeDecorator(sqlalchemy.sql.base.SchemaEventTarget, ExternalType, TypeEngine)
| TypeDecorator(*args: 'Any', **kwargs: 'Any')
|
| Allows the creation of types which add additional functionality
| to an existing type.
|
| This method is preferred to direct subclassing of SQLAlchemy's
| built-in types as it ensures that all required functionality of
| the underlying type is kept in place.
|
| Typical usage::
|
| import sqlalchemy.types as types
|
|
| class MyType(types.TypeDecorator):
| """Prefixes Unicode values with "PREFIX:" on the way in and
| strips it off on the way out.
| """
|
| impl = types.Unicode
|
| cache_ok = True
|
| def process_bind_param(self, value, dialect):
| return "PREFIX:" + value
|
| def process_result_value(self, value, dialect):
| return value[7:]
|
| def copy(self, **kw):
| return MyType(self.impl.length)
|
| The class-level ``impl`` attribute is required, and can reference any
| :class:`.TypeEngine` class. Alternatively, the :meth:`load_dialect_impl`
| method can be used to provide different type classes based on the dialect
| given; in this case, the ``impl`` variable can reference
| ``TypeEngine`` as a placeholder.
|
| The :attr:`.TypeDecorator.cache_ok` class-level flag indicates if this
| custom :class:`.TypeDecorator` is safe to be used as part of a cache key.
| This flag defaults to ``None`` which will initially generate a warning
| when the SQL compiler attempts to generate a cache key for a statement
| that uses this type. If the :class:`.TypeDecorator` is not guaranteed
| to produce the same bind/result behavior and SQL generation
| every time, this flag should be set to ``False``; otherwise if the
| class produces the same behavior each time, it may be set to ``True``.
| See :attr:`.TypeDecorator.cache_ok` for further notes on how this works.
|
| Types that receive a Python type that isn't similar to the ultimate type
| used may want to define the :meth:`TypeDecorator.coerce_compared_value`
| method. This is used to give the expression system a hint when coercing
| Python objects into bind parameters within expressions. Consider this
| expression::
|
| mytable.c.somecol + datetime.date(2009, 5, 15)
|
| Above, if "somecol" is an ``Integer`` variant, it makes sense that
| we're doing date arithmetic, where above is usually interpreted
| by databases as adding a number of days to the given date.
| The expression system does the right thing by not attempting to
| coerce the "date()" value into an integer-oriented bind parameter.
|
| However, in the case of ``TypeDecorator``, we are usually changing an
| incoming Python type to something new - ``TypeDecorator`` by default will
| "coerce" the non-typed side to be the same type as itself. Such as below,
| we define an "epoch" type that stores a date value as an integer::
|
| class MyEpochType(types.TypeDecorator):
| impl = types.Integer
|
| cache_ok = True
|
| epoch = datetime.date(1970, 1, 1)
|
| def process_bind_param(self, value, dialect):
| return (value - self.epoch).days
|
| def process_result_value(self, value, dialect):
| return self.epoch + timedelta(days=value)
|
| Our expression of ``somecol + date`` with the above type will coerce the
| "date" on the right side to also be treated as ``MyEpochType``.
|
| This behavior can be overridden via the
| :meth:`~TypeDecorator.coerce_compared_value` method, which returns a type
| that should be used for the value of the expression. Below we set it such
| that an integer value will be treated as an ``Integer``, and any other
| value is assumed to be a date and will be treated as a ``MyEpochType``::
|
| def coerce_compared_value(self, op, value):
| if isinstance(value, int):
| return Integer()
| else:
| return self
|
| .. warning::
|
| Note that the **behavior of coerce_compared_value is not inherited
| by default from that of the base type**.
| If the :class:`.TypeDecorator` is augmenting a
| type that requires special logic for certain types of operators,
| this method **must** be overridden. A key example is when decorating
| the :class:`_postgresql.JSON` and :class:`_postgresql.JSONB` types;
| the default rules of :meth:`.TypeEngine.coerce_compared_value` should
| be used in order to deal with operators like index operations::
|
| from sqlalchemy import JSON
| from sqlalchemy import TypeDecorator
|
|
| class MyJsonType(TypeDecorator):
| impl = JSON
|
| cache_ok = True
|
| def coerce_compared_value(self, op, value):
| return self.impl.coerce_compared_value(op, value)
|
| Without the above step, index operations such as ``mycol['foo']``
| will cause the index value ``'foo'`` to be JSON encoded.
|
| Similarly, when working with the :class:`.ARRAY` datatype, the
| type coercion for index operations (e.g. ``mycol[5]``) is also
| handled by :meth:`.TypeDecorator.coerce_compared_value`, where
| again a simple override is sufficient unless special rules are needed
| for particular operators::
|
| from sqlalchemy import ARRAY
| from sqlalchemy import TypeDecorator
|
|
| class MyArrayType(TypeDecorator):
| impl = ARRAY
|
| cache_ok = True
|
| def coerce_compared_value(self, op, value):
| return self.impl.coerce_compared_value(op, value)
|
| Method resolution order:
| TypeDecorator
| sqlalchemy.sql.base.SchemaEventTarget
| sqlalchemy.event.registry.EventTarget
| ExternalType
| TypeEngineMixin
| TypeEngine
| sqlalchemy.sql.visitors.Visitable
| typing.Generic
| builtins.object
|
| Methods defined here:
|
| __getattr__(self, key: 'str') -> 'Any'
| Proxy all other undefined accessors to the underlying
| implementation.
|
| __init__(self, *args: 'Any', **kwargs: 'Any')
| Construct a :class:`.TypeDecorator`.
|
| Arguments sent here are passed to the constructor
| of the class assigned to the ``impl`` class level attribute,
| assuming the ``impl`` is a callable, and the resulting
| object is assigned to the ``self.impl`` instance attribute
| (thus overriding the class attribute of the same name).
|
| If the class level ``impl`` is not a callable (the unusual case),
| it will be assigned to the same instance attribute 'as-is',
| ignoring those arguments passed to the constructor.
|
| Subclasses can override this to customize the generation
| of ``self.impl`` entirely.
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| bind_expression(self, bindparam: 'BindParameter[_T]') -> 'Optional[ColumnElement[_T]]'
| Given a bind value (i.e. a :class:`.BindParameter` instance),
| return a SQL expression which will typically wrap the given parameter.
|
| .. note::
|
| This method is called during the **SQL compilation** phase of a
| statement, when rendering a SQL string. It is **not** necessarily
| called against specific values, and should not be confused with the
| :meth:`_types.TypeDecorator.process_bind_param` method, which is
| the more typical method that processes the actual value passed to a
| particular parameter at statement execution time.
|
| Subclasses of :class:`_types.TypeDecorator` can override this method
| to provide custom bind expression behavior for the type. This
| implementation will **replace** that of the underlying implementation
| type.
|
| bind_processor(self, dialect: 'Dialect') -> 'Optional[_BindProcessorType[_T]]'
| Provide a bound value processing function for the
| given :class:`.Dialect`.
|
| This is the method that fulfills the :class:`.TypeEngine`
| contract for bound value conversion which normally occurs via
| the :meth:`_types.TypeEngine.bind_processor` method.
|
| .. note::
|
| User-defined subclasses of :class:`_types.TypeDecorator` should
| **not** implement this method, and should instead implement
| :meth:`_types.TypeDecorator.process_bind_param` so that the "inner"
| processing provided by the implementing type is maintained.
|
| :param dialect: Dialect instance in use.
|
| coerce_compared_value(self, op: 'Optional[OperatorType]', value: 'Any') -> 'Any'
| Suggest a type for a 'coerced' Python value in an expression.
|
| By default, returns self. This method is called by
| the expression system when an object using this type is
| on the left or right side of an expression against a plain Python
| object which does not yet have a SQLAlchemy type assigned::
|
| expr = table.c.somecolumn + 35
|
| Where above, if ``somecolumn`` uses this type, this method will
| be called with the value ``operator.add``
| and ``35``. The return value is whatever SQLAlchemy type should
| be used for ``35`` for this particular operation.
|
| column_expression(self, column: 'ColumnElement[_T]') -> 'Optional[ColumnElement[_T]]'
| Given a SELECT column expression, return a wrapping SQL expression.
|
| .. note::
|
| This method is called during the **SQL compilation** phase of a
| statement, when rendering a SQL string. It is **not** called
| against specific values, and should not be confused with the
| :meth:`_types.TypeDecorator.process_result_value` method, which is
| the more typical method that processes the actual value returned
| in a result row subsequent to statement execution time.
|
| Subclasses of :class:`_types.TypeDecorator` can override this method
| to provide custom column expression behavior for the type. This
| implementation will **replace** that of the underlying implementation
| type.
|
| See the description of :meth:`_types.TypeEngine.column_expression`
| for a complete description of the method's use.
|
| compare_values(self, x: 'Any', y: 'Any') -> 'bool'
| Given two values, compare them for equality.
|
| By default this calls upon :meth:`.TypeEngine.compare_values`
| of the underlying "impl", which in turn usually
| uses the Python equals operator ``==``.
|
| This function is used by the ORM to compare
| an original-loaded value with an intercepted
| "changed" value, to determine if a net change
| has occurred.
|
| copy(self, **kw: 'Any') -> 'Self'
| Produce a copy of this :class:`.TypeDecorator` instance.
|
| This is a shallow copy and is provided to fulfill part of
| the :class:`.TypeEngine` contract. It usually does not
| need to be overridden unless the user-defined :class:`.TypeDecorator`
| has local state that should be deep-copied.
|
| get_dbapi_type(self, dbapi: 'DBAPIModule') -> 'Optional[Any]'
| Return the DBAPI type object represented by this
| :class:`.TypeDecorator`.
|
| By default this calls upon :meth:`.TypeEngine.get_dbapi_type` of the
| underlying "impl".
|
| impl_instance(...)
|
| literal_processor(self, dialect: 'Dialect') -> 'Optional[_LiteralProcessorType[_T]]'
| Provide a literal processing function for the given
| :class:`.Dialect`.
|
| This is the method that fulfills the :class:`.TypeEngine`
| contract for literal value conversion which normally occurs via
| the :meth:`_types.TypeEngine.literal_processor` method.
|
| .. note::
|
| User-defined subclasses of :class:`_types.TypeDecorator` should
| **not** implement this method, and should instead implement
| :meth:`_types.TypeDecorator.process_literal_param` so that the
| "inner" processing provided by the implementing type is maintained.
|
| load_dialect_impl(self, dialect: 'Dialect') -> 'TypeEngine[Any]'
| Return a :class:`.TypeEngine` object corresponding to a dialect.
|
| This is an end-user override hook that can be used to provide
| differing types depending on the given dialect. It is used
| by the :class:`.TypeDecorator` implementation of :meth:`type_engine`
| to help determine what type should ultimately be returned
| for a given :class:`.TypeDecorator`.
|
| By default returns ``self.impl``.
|
| process_bind_param(self, value: 'Optional[_T]', dialect: 'Dialect') -> 'Any'
| Receive a bound parameter value to be converted.
|
| Custom subclasses of :class:`_types.TypeDecorator` should override
| this method to provide custom behaviors for incoming data values.
| This method is called at **statement execution time** and is passed
| the literal Python data value which is to be associated with a bound
| parameter in the statement.
|
| The operation could be anything desired to perform custom
| behavior, such as transforming or serializing data.
| This could also be used as a hook for validating logic.
|
| :param value: Data to operate upon, of any type expected by
| this method in the subclass. Can be ``None``.
| :param dialect: the :class:`.Dialect` in use.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| :meth:`_types.TypeDecorator.process_result_value`
|
| process_literal_param(self, value: 'Optional[_T]', dialect: 'Dialect') -> 'str'
| Receive a literal parameter value to be rendered inline within
| a statement.
|
| .. note::
|
| This method is called during the **SQL compilation** phase of a
| statement, when rendering a SQL string. Unlike other SQL
| compilation methods, it is passed a specific Python value to be
| rendered as a string. However it should not be confused with the
| :meth:`_types.TypeDecorator.process_bind_param` method, which is
| the more typical method that processes the actual value passed to a
| particular parameter at statement execution time.
|
| Custom subclasses of :class:`_types.TypeDecorator` should override
| this method to provide custom behaviors for incoming data values
| that are in the special case of being rendered as literals.
|
| The returned string will be rendered into the output string.
|
| process_result_value(self, value: 'Optional[Any]', dialect: 'Dialect') -> 'Optional[_T]'
| Receive a result-row column value to be converted.
|
| Custom subclasses of :class:`_types.TypeDecorator` should override
| this method to provide custom behaviors for data values
| being received in result rows coming from the database.
| This method is called at **result fetching time** and is passed
| the literal Python data value that's extracted from a database result
| row.
|
| The operation could be anything desired to perform custom
| behavior, such as transforming or deserializing data.
|
| :param value: Data to operate upon, of any type expected by
| this method in the subclass. Can be ``None``.
| :param dialect: the :class:`.Dialect` in use.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| :meth:`_types.TypeDecorator.process_bind_param`
|
| result_processor(self, dialect: 'Dialect', coltype: 'Any') -> 'Optional[_ResultProcessorType[_T]]'
| Provide a result value processing function for the given
| :class:`.Dialect`.
|
| This is the method that fulfills the :class:`.TypeEngine`
| contract for bound value conversion which normally occurs via
| the :meth:`_types.TypeEngine.result_processor` method.
|
| .. note::
|
| User-defined subclasses of :class:`_types.TypeDecorator` should
| **not** implement this method, and should instead implement
| :meth:`_types.TypeDecorator.process_result_value` so that the
| "inner" processing provided by the implementing type is maintained.
|
| :param dialect: Dialect instance in use.
| :param coltype: A SQLAlchemy data type
|
| type_engine(self, dialect: 'Dialect') -> 'TypeEngine[Any]'
| Return a dialect-specific :class:`.TypeEngine` instance
| for this :class:`.TypeDecorator`.
|
| In most cases this returns a dialect-adapted form of
| the :class:`.TypeEngine` type represented by ``self.impl``.
| Makes usage of :meth:`dialect_impl`.
| Behavior can be customized here by overriding
| :meth:`load_dialect_impl`.
|
| ----------------------------------------------------------------------
| Readonly properties defined here:
|
| comparator_factory
| Base class for custom comparison operations defined at the
| type level. See :attr:`.TypeEngine.comparator_factory`.
|
| sort_key_function
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| Comparator = <class 'sqlalchemy.sql.type_api.TypeDecorator.Comparator'...
| A :class:`.TypeEngine.Comparator` that is specific to
| :class:`.TypeDecorator`.
|
| User-defined :class:`.TypeDecorator` classes should not typically
| need to modify this.
|
|
| __annotations__ = {'coerce_to_is_types': 'Sequence[Type[Any]]', 'impl'...
|
| __parameters__ = ()
|
| __visit_name__ = 'type_decorator'
|
| coerce_to_is_types = (<class 'NoneType'>,)
|
| ----------------------------------------------------------------------
| Data descriptors inherited from sqlalchemy.sql.base.SchemaEventTarget:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.base.SchemaEventTarget:
|
| dispatch = <sqlalchemy.event.base.DDLEventsDispatch object>
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from ExternalType:
|
| cache_ok = None
|
| ----------------------------------------------------------------------
| Methods inherited from TypeEngine:
|
| __str__(self) -> 'str'
| Return str(self).
|
| adapt(self, cls: 'Type[Union[TypeEngine[Any], TypeEngineMixin]]', **kw: 'Any') -> 'TypeEngine[Any]'
| Produce an "adapted" form of this type, given an "impl" class
| to work with.
|
| This method is used internally to associate generic
| types with "implementation" types that are specific to a particular
| dialect.
|
| as_generic(self, allow_nulltype: 'bool' = False) -> 'TypeEngine[_T]'
| Return an instance of the generic type corresponding to this type
| using heuristic rule. The method may be overridden if this
| heuristic rule is not sufficient.
|
| >>> from sqlalchemy.dialects.mysql import INTEGER
| >>> INTEGER(display_width=4).as_generic()
| Integer()
|
| >>> from sqlalchemy.dialects.mysql import NVARCHAR
| >>> NVARCHAR(length=100).as_generic()
| Unicode(length=100)
|
| .. versionadded:: 1.4.0b2
|
|
| .. seealso::
|
| :ref:`metadata_reflection_dbagnostic_types` - describes the
| use of :meth:`_types.TypeEngine.as_generic` in conjunction with
| the :meth:`_sql.DDLEvents.column_reflect` event, which is its
| intended use.
|
| compile(self, dialect: 'Optional[Dialect]' = None) -> 'str'
| Produce a string-compiled form of this :class:`.TypeEngine`.
|
| When called with no arguments, uses a "default" dialect
| to produce a string result.
|
| :param dialect: a :class:`.Dialect` instance.
|
| copy_value(self, value: 'Any') -> 'Any'
|
| dialect_impl(self, dialect: 'Dialect') -> 'TypeEngine[_T]'
| Return a dialect-specific implementation for this
| :class:`.TypeEngine`.
|
| evaluates_none(self) -> 'Self'
| Return a copy of this type which has the
| :attr:`.should_evaluate_none` flag set to True.
|
| E.g.::
|
| Table(
| "some_table",
| metadata,
| Column(
| String(50).evaluates_none(),
| nullable=True,
| server_default="no value",
| ),
| )
|
| The ORM uses this flag to indicate that a positive value of ``None``
| is passed to the column in an INSERT statement, rather than omitting
| the column from the INSERT statement which has the effect of firing
| off column-level defaults. It also allows for types which have
| special behavior associated with the Python None value to indicate
| that the value doesn't necessarily translate into SQL NULL; a
| prime example of this is a JSON type which may wish to persist the
| JSON value ``'null'``.
|
| In all cases, the actual NULL SQL value can be always be
| persisted in any column by using
| the :obj:`_expression.null` SQL construct in an INSERT statement
| or associated with an ORM-mapped attribute.
|
| .. note::
|
| The "evaluates none" flag does **not** apply to a value
| of ``None`` passed to :paramref:`_schema.Column.default` or
| :paramref:`_schema.Column.server_default`; in these cases,
| ``None``
| still means "no default".
|
| .. seealso::
|
| :ref:`session_forcing_null` - in the ORM documentation
|
| :paramref:`.postgresql.JSON.none_as_null` - PostgreSQL JSON
| interaction with this flag.
|
| :attr:`.TypeEngine.should_evaluate_none` - class-level flag
|
| with_variant(self, type_: '_TypeEngineArgument[Any]', *dialect_names: 'str') -> 'Self'
| Produce a copy of this type object that will utilize the given
| type when applied to the dialect of the given name.
|
| e.g.::
|
| from sqlalchemy.types import String
| from sqlalchemy.dialects import mysql
|
| string_type = String()
|
| string_type = string_type.with_variant(
| mysql.VARCHAR(collation="foo"), "mysql", "mariadb"
| )
|
| The variant mapping indicates that when this type is
| interpreted by a specific dialect, it will instead be
| transmuted into the given type, rather than using the
| primary type.
|
| .. versionchanged:: 2.0 the :meth:`_types.TypeEngine.with_variant`
| method now works with a :class:`_types.TypeEngine` object "in
| place", returning a copy of the original type rather than returning
| a wrapping object; the ``Variant`` class is no longer used.
|
| :param type\_: a :class:`.TypeEngine` that will be selected
| as a variant from the originating type, when a dialect
| of the given name is in use.
| :param \*dialect_names: one or more base names of the dialect which
| uses this type. (i.e. ``'postgresql'``, ``'mysql'``, etc.)
|
| .. versionchanged:: 2.0 multiple dialect names can be specified
| for one variant.
|
| .. seealso::
|
| :ref:`types_with_variant` - illustrates the use of
| :meth:`_types.TypeEngine.with_variant`.
|
| ----------------------------------------------------------------------
| Readonly properties inherited from TypeEngine:
|
| python_type
| Return the Python type object expected to be returned
| by instances of this type, if known.
|
| Basically, for those types which enforce a return type,
| or are known across the board to do such for all common
| DBAPIs (like ``int`` for example), will return that type.
|
| If a return type is not defined, raises
| ``NotImplementedError``.
|
| Note that any type also accommodates NULL in SQL which
| means you can also get back ``None`` from any type
| in practice.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from TypeEngine:
|
| __orig_bases__ = (<class 'sqlalchemy.sql.visitors.Visitable'>, typing....
|
| hashable = True
|
| render_bind_cast = False
|
| render_literal_cast = False
|
| should_evaluate_none = False
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.visitors.Visitable:
|
| __class_getitem__(key: 'Any') -> 'Any'
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__() -> 'None'
| This method is called when a class is subclassed.
|
| The default implementation does nothing. It may be
| overridden to extend subclasses.
sqlalchemy.URL
Python Library Documentation: class URL in module sqlalchemy.engine.url
class URL(builtins.tuple)
| URL(drivername: ForwardRef('str'), username: ForwardRef('Optional[str]'), password: ForwardRef('Optional[str]'), host: ForwardRef('Optional[str]'), port: ForwardRef('Optional[int]'), database: ForwardRef('Optional[str]'), query: ForwardRef('util.immutabledict[str, Union[Tuple[str, ...], str]]'))
|
| Represent the components of a URL used to connect to a database.
|
| URLs are typically constructed from a fully formatted URL string, where the
| :func:`.make_url` function is used internally by the
| :func:`_sa.create_engine` function in order to parse the URL string into
| its individual components, which are then used to construct a new
| :class:`.URL` object. When parsing from a formatted URL string, the parsing
| format generally follows
| `RFC-1738 <https://www.ietf.org/rfc/rfc1738.txt>`_, with some exceptions.
|
| A :class:`_engine.URL` object may also be produced directly, either by
| using the :func:`.make_url` function with a fully formed URL string, or
| by using the :meth:`_engine.URL.create` constructor in order
| to construct a :class:`_engine.URL` programmatically given individual
| fields. The resulting :class:`.URL` object may be passed directly to
| :func:`_sa.create_engine` in place of a string argument, which will bypass
| the usage of :func:`.make_url` within the engine's creation process.
|
| .. versionchanged:: 1.4
|
| The :class:`_engine.URL` object is now an immutable object. To
| create a URL, use the :func:`_engine.make_url` or
| :meth:`_engine.URL.create` function / method. To modify
| a :class:`_engine.URL`, use methods like
| :meth:`_engine.URL.set` and
| :meth:`_engine.URL.update_query_dict` to return a new
| :class:`_engine.URL` object with modifications. See notes for this
| change at :ref:`change_5526`.
|
| .. seealso::
|
| :ref:`database_urls`
|
| :class:`_engine.URL` contains the following attributes:
|
| * :attr:`_engine.URL.drivername`: database backend and driver name, such as
| ``postgresql+psycopg2``
| * :attr:`_engine.URL.username`: username string
| * :attr:`_engine.URL.password`: password string
| * :attr:`_engine.URL.host`: string hostname
| * :attr:`_engine.URL.port`: integer port number
| * :attr:`_engine.URL.database`: string database name
| * :attr:`_engine.URL.query`: an immutable mapping representing the query
| string. contains strings for keys and either strings or tuples of
| strings for values.
|
| Method resolution order:
| URL
| builtins.tuple
| builtins.object
|
| Methods defined here:
|
| __copy__(self) -> 'URL'
|
| __deepcopy__(self, memo: 'Any') -> 'URL'
|
| __eq__(self, other: 'Any') -> 'bool'
| Return self==value.
|
| __getnewargs__(self) from collections.URL
| Return self as a plain tuple. Used by copy and pickle.
|
| __hash__(self) -> 'int'
| Return hash(self).
|
| __ne__(self, other: 'Any') -> 'bool'
| Return self!=value.
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| __to_string__(self, hide_password: 'bool' = True) -> 'str'
| Render this :class:`_engine.URL` object as a string.
|
| .. deprecated:: 1.4 The :meth:`_engine.URL.__to_string__ method is deprecated and will be removed in a future release. Please use the :meth:`_engine.URL.render_as_string` method.
|
| :param hide_password: Defaults to True. The password is not shown
| in the string unless this is set to False.
|
| _asdict(self) from collections.URL
| Return a new dict which maps field names to their values.
|
| _assert_replace(self, **kw: 'Any') -> 'URL'
| argument checks before calling _replace()
|
| _get_entrypoint(self) -> 'Type[Dialect]'
| Return the "entry point" dialect class.
|
| This is normally the dialect itself except in the case when the
| returned class implements the get_dialect_cls() method.
|
| _instantiate_plugins(self, kwargs: 'Mapping[str, Any]') -> 'Tuple[URL, List[Any], Dict[str, Any]]'
|
| _replace(self, /, **kwds) from collections.URL
| Return a new URL object replacing specified fields with new values
|
| difference_update_query(self, names: 'Iterable[str]') -> 'URL'
| Remove the given names from the :attr:`_engine.URL.query` dictionary,
| returning the new :class:`_engine.URL`.
|
| E.g.::
|
| url = url.difference_update_query(["foo", "bar"])
|
| Equivalent to using :meth:`_engine.URL.set` as follows::
|
| url = url.set(
| query={
| key: url.query[key]
| for key in set(url.query).difference(["foo", "bar"])
| }
| )
|
| .. versionadded:: 1.4
|
| .. seealso::
|
| :attr:`_engine.URL.query`
|
| :meth:`_engine.URL.update_query_dict`
|
| :meth:`_engine.URL.set`
|
| get_backend_name(self) -> 'str'
| Return the backend name.
|
| This is the name that corresponds to the database backend in
| use, and is the portion of the :attr:`_engine.URL.drivername`
| that is to the left of the plus sign.
|
| get_dialect(self, _is_async: 'bool' = False) -> 'Type[Dialect]'
| Return the SQLAlchemy :class:`_engine.Dialect` class corresponding
| to this URL's driver name.
|
| get_driver_name(self) -> 'str'
| Return the backend name.
|
| This is the name that corresponds to the DBAPI driver in
| use, and is the portion of the :attr:`_engine.URL.drivername`
| that is to the right of the plus sign.
|
| If the :attr:`_engine.URL.drivername` does not include a plus sign,
| then the default :class:`_engine.Dialect` for this :class:`_engine.URL`
| is imported in order to get the driver name.
|
| render_as_string(self, hide_password: 'bool' = True) -> 'str'
| Render this :class:`_engine.URL` object as a string.
|
| This method is used when the ``__str__()`` or ``__repr__()``
| methods are used. The method directly includes additional options.
|
| :param hide_password: Defaults to True. The password is not shown
| in the string unless this is set to False.
|
| set(self, drivername: 'Optional[str]' = None, username: 'Optional[str]' = None, password: 'Optional[str]' = None, host: 'Optional[str]' = None, port: 'Optional[int]' = None, database: 'Optional[str]' = None, query: 'Optional[Mapping[str, Union[Sequence[str], str]]]' = None) -> 'URL'
| return a new :class:`_engine.URL` object with modifications.
|
| Values are used if they are non-None. To set a value to ``None``
| explicitly, use the :meth:`_engine.URL._replace` method adapted
| from ``namedtuple``.
|
| :param drivername: new drivername
| :param username: new username
| :param password: new password
| :param host: new hostname
| :param port: new port
| :param query: new query parameters, passed a dict of string keys
| referring to string or sequence of string values. Fully
| replaces the previous list of arguments.
|
| :return: new :class:`_engine.URL` object.
|
| .. versionadded:: 1.4
|
| .. seealso::
|
| :meth:`_engine.URL.update_query_dict`
|
| translate_connect_args(self, names: 'Optional[List[str]]' = None, **kw: 'Any') -> 'Dict[str, Any]'
| Translate url attributes into a dictionary of connection arguments.
|
| Returns attributes of this url (`host`, `database`, `username`,
| `password`, `port`) as a plain dictionary. The attribute names are
| used as the keys by default. Unset or false attributes are omitted
| from the final dictionary.
|
| :param \**kw: Optional, alternate key names for url attributes.
|
| :param names: Deprecated. Same purpose as the keyword-based alternate
| names, but correlates the name to the original positionally.
|
| update_query_dict(self, query_parameters: 'Mapping[str, Union[str, List[str]]]', append: 'bool' = False) -> 'URL'
| Return a new :class:`_engine.URL` object with the
| :attr:`_engine.URL.query` parameter dictionary updated by the given
| dictionary.
|
| The dictionary typically contains string keys and string values.
| In order to represent a query parameter that is expressed multiple
| times, pass a sequence of string values.
|
| E.g.::
|
|
| >>> from sqlalchemy.engine import make_url
| >>> url = make_url("postgresql+psycopg2://user:pass@host/dbname")
| >>> url = url.update_query_dict(
| ... {"alt_host": ["host1", "host2"], "ssl_cipher": "/path/to/crt"}
| ... )
| >>> str(url)
| 'postgresql+psycopg2://user:pass@host/dbname?alt_host=host1&alt_host=host2&ssl_cipher=%2Fpath%2Fto%2Fcrt'
|
|
| :param query_parameters: A dictionary with string keys and values
| that are either strings, or sequences of strings.
|
| :param append: if True, parameters in the existing query string will
| not be removed; new parameters will be in addition to those present.
| If left at its default of False, keys present in the given query
| parameters will replace those of the existing query string.
|
|
| .. versionadded:: 1.4
|
| .. seealso::
|
| :attr:`_engine.URL.query`
|
| :meth:`_engine.URL.update_query_string`
|
| :meth:`_engine.URL.update_query_pairs`
|
| :meth:`_engine.URL.difference_update_query`
|
| :meth:`_engine.URL.set`
|
| update_query_pairs(self, key_value_pairs: 'Iterable[Tuple[str, Union[str, List[str]]]]', append: 'bool' = False) -> 'URL'
| Return a new :class:`_engine.URL` object with the
| :attr:`_engine.URL.query`
| parameter dictionary updated by the given sequence of key/value pairs
|
| E.g.::
|
| >>> from sqlalchemy.engine import make_url
| >>> url = make_url("postgresql+psycopg2://user:pass@host/dbname")
| >>> url = url.update_query_pairs(
| ... [
| ... ("alt_host", "host1"),
| ... ("alt_host", "host2"),
| ... ("ssl_cipher", "/path/to/crt"),
| ... ]
| ... )
| >>> str(url)
| 'postgresql+psycopg2://user:pass@host/dbname?alt_host=host1&alt_host=host2&ssl_cipher=%2Fpath%2Fto%2Fcrt'
|
| :param key_value_pairs: A sequence of tuples containing two strings
| each.
|
| :param append: if True, parameters in the existing query string will
| not be removed; new parameters will be in addition to those present.
| If left at its default of False, keys present in the given query
| parameters will replace those of the existing query string.
|
| .. versionadded:: 1.4
|
| .. seealso::
|
| :attr:`_engine.URL.query`
|
| :meth:`_engine.URL.difference_update_query`
|
| :meth:`_engine.URL.set`
|
| update_query_string(self, query_string: 'str', append: 'bool' = False) -> 'URL'
| Return a new :class:`_engine.URL` object with the :attr:`_engine.URL.query`
| parameter dictionary updated by the given query string.
|
| E.g.::
|
| >>> from sqlalchemy.engine import make_url
| >>> url = make_url("postgresql+psycopg2://user:pass@host/dbname")
| >>> url = url.update_query_string(
| ... "alt_host=host1&alt_host=host2&ssl_cipher=%2Fpath%2Fto%2Fcrt"
| ... )
| >>> str(url)
| 'postgresql+psycopg2://user:pass@host/dbname?alt_host=host1&alt_host=host2&ssl_cipher=%2Fpath%2Fto%2Fcrt'
|
| :param query_string: a URL escaped query string, not including the
| question mark.
|
| :param append: if True, parameters in the existing query string will
| not be removed; new parameters will be in addition to those present.
| If left at its default of False, keys present in the given query
| parameters will replace those of the existing query string.
|
| .. versionadded:: 1.4
|
| .. seealso::
|
| :attr:`_engine.URL.query`
|
| :meth:`_engine.URL.update_query_dict`
|
| ----------------------------------------------------------------------
| Class methods defined here:
|
| _assert_none_str(v: 'Optional[str]', paramname: 'str') -> 'Optional[str]'
|
| _assert_port(port: 'Optional[int]') -> 'Optional[int]'
|
| _assert_str(v: 'str', paramname: 'str') -> 'str'
|
| _make(iterable) from collections.URL
| Make a new URL object from a sequence or iterable
|
| _str_dict(dict_: 'Optional[Union[Sequence[Tuple[str, Union[Sequence[str], str]]], Mapping[str, Union[Sequence[str], str]]]]') -> 'util.immutabledict[str, Union[Tuple[str, ...], str]]'
|
| create(drivername: 'str', username: 'Optional[str]' = None, password: 'Optional[str]' = None, host: 'Optional[str]' = None, port: 'Optional[int]' = None, database: 'Optional[str]' = None, query: 'Mapping[str, Union[Sequence[str], str]]' = immutabledict({})) -> 'URL'
| Create a new :class:`_engine.URL` object.
|
| .. seealso::
|
| :ref:`database_urls`
|
| :param drivername: the name of the database backend. This name will
| correspond to a module in sqlalchemy/databases or a third party
| plug-in.
| :param username: The user name.
| :param password: database password. Is typically a string, but may
| also be an object that can be stringified with ``str()``.
|
| .. note:: The password string should **not** be URL encoded when
| passed as an argument to :meth:`_engine.URL.create`; the string
| should contain the password characters exactly as they would be
| typed.
|
| .. note:: A password-producing object will be stringified only
| **once** per :class:`_engine.Engine` object. For dynamic password
| generation per connect, see :ref:`engines_dynamic_tokens`.
|
| :param host: The name of the host.
| :param port: The port number.
| :param database: The database name.
| :param query: A dictionary of string keys to string values to be passed
| to the dialect and/or the DBAPI upon connect. To specify non-string
| parameters to a Python DBAPI directly, use the
| :paramref:`_sa.create_engine.connect_args` parameter to
| :func:`_sa.create_engine`. See also
| :attr:`_engine.URL.normalized_query` for a dictionary that is
| consistently string->list of string.
| :return: new :class:`_engine.URL` object.
|
| .. versionadded:: 1.4
|
| The :class:`_engine.URL` object is now an **immutable named
| tuple**. In addition, the ``query`` dictionary is also immutable.
| To create a URL, use the :func:`_engine.url.make_url` or
| :meth:`_engine.URL.create` function/ method. To modify a
| :class:`_engine.URL`, use the :meth:`_engine.URL.set` and
| :meth:`_engine.URL.update_query` methods.
|
| ----------------------------------------------------------------------
| Static methods defined here:
|
| __new__(_cls, drivername: ForwardRef('str'), username: ForwardRef('Optional[str]'), password: ForwardRef('Optional[str]'), host: ForwardRef('Optional[str]'), port: ForwardRef('Optional[int]'), database: ForwardRef('Optional[str]'), query: ForwardRef('util.immutabledict[str, Union[Tuple[str, ...], str]]')) from namedtuple_URL.URL
| Create new instance of URL(drivername, username, password, host, port, database, query)
|
| ----------------------------------------------------------------------
| Readonly properties defined here:
|
| normalized_query
| Return the :attr:`_engine.URL.query` dictionary with values normalized
| into sequences.
|
| As the :attr:`_engine.URL.query` dictionary may contain either
| string values or sequences of string values to differentiate between
| parameters that are specified multiple times in the query string,
| code that needs to handle multiple parameters generically will wish
| to use this attribute so that all parameters present are presented
| as sequences. Inspiration is from Python's ``urllib.parse.parse_qs``
| function. E.g.::
|
|
| >>> from sqlalchemy.engine import make_url
| >>> url = make_url(
| ... "postgresql+psycopg2://user:pass@host/dbname?alt_host=host1&alt_host=host2&ssl_cipher=%2Fpath%2Fto%2Fcrt"
| ... )
| >>> url.query
| immutabledict({'alt_host': ('host1', 'host2'), 'ssl_cipher': '/path/to/crt'})
| >>> url.normalized_query
| immutabledict({'alt_host': ('host1', 'host2'), 'ssl_cipher': ('/path/to/crt',)})
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| drivername
| Alias for field number 0
|
| username
| Alias for field number 1
|
| password
| Alias for field number 2
|
| host
| Alias for field number 3
|
| port
| Alias for field number 4
|
| database
| Alias for field number 5
|
| query
| Alias for field number 6
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'database': ForwardRef('Optional[str]'), 'drivernam...
|
| __match_args__ = ('drivername', 'username', 'password', 'host', 'port'...
|
| __orig_bases__ = (<function NamedTuple>,)
|
| _field_defaults = {}
|
| _fields = ('drivername', 'username', 'password', 'host', 'port', 'data...
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.tuple:
|
| __add__(self, value, /)
| Return self+value.
|
| __contains__(self, key, /)
| Return bool(key in self).
|
| __ge__(self, value, /)
| Return self>=value.
|
| __getattribute__(self, name, /)
| Return getattr(self, name).
|
| __getitem__(self, key, /)
| Return self[key].
|
| __gt__(self, value, /)
| Return self>value.
|
| __iter__(self, /)
| Implement iter(self).
|
| __le__(self, value, /)
| Return self<=value.
|
| __len__(self, /)
| Return len(self).
|
| __lt__(self, value, /)
| Return self<value.
|
| __mul__(self, value, /)
| Return self*value.
|
| __rmul__(self, value, /)
| Return value*self.
|
| count(self, value, /)
| Return number of occurrences of value.
|
| index(self, value, start=0, stop=9223372036854775807, /)
| Return first index of value.
|
| Raises ValueError if the value is not present.
|
| ----------------------------------------------------------------------
| Class methods inherited from builtins.tuple:
|
| __class_getitem__(...)
| See PEP 585
sqlalchemy.UUID
Python Library Documentation: class UUID in module sqlalchemy.sql.sqltypes
class UUID(Uuid, sqlalchemy.sql.type_api.NativeForEmulated)
| UUID(as_uuid: 'bool' = True)
|
| Represent the SQL UUID type.
|
| This is the SQL-native form of the :class:`_types.Uuid` database agnostic
| datatype, and is backwards compatible with the previous PostgreSQL-only
| version of ``UUID``.
|
| The :class:`_sqltypes.UUID` datatype only works on databases that have a
| SQL datatype named ``UUID``. It will not function for backends which don't
| have this exact-named type, including SQL Server. For backend-agnostic UUID
| values with native support, including for SQL Server's ``UNIQUEIDENTIFIER``
| datatype, use the :class:`_sqltypes.Uuid` datatype.
|
| .. versionadded:: 2.0
|
| .. seealso::
|
| :class:`_sqltypes.Uuid`
|
| Method resolution order:
| UUID
| Uuid
| sqlalchemy.sql.type_api.Emulated
| sqlalchemy.sql.type_api.NativeForEmulated
| sqlalchemy.sql.type_api.TypeEngineMixin
| sqlalchemy.sql.type_api.TypeEngine
| sqlalchemy.sql.visitors.Visitable
| typing.Generic
| builtins.object
|
| Methods defined here:
|
| __init__(self, as_uuid: 'bool' = True)
| Construct a :class:`_sqltypes.UUID` type.
|
|
| :param as_uuid=True: if True, values will be interpreted
| as Python uuid objects, converting to/from string via the
| DBAPI.
|
| .. versionchanged: 2.0 ``as_uuid`` now defaults to ``True``.
|
| ----------------------------------------------------------------------
| Class methods defined here:
|
| adapt_emulated_to_native(impl, **kw)
| Given an impl, adapt this type's class to the impl assuming
| "native".
|
| The impl will be an :class:`.Emulated` class but not a
| :class:`.NativeForEmulated`.
|
| e.g.: postgresql.ENUM produces a type given an Enum instance.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| __parameters__ = ()
|
| __visit_name__ = 'UUID'
|
| ----------------------------------------------------------------------
| Methods inherited from Uuid:
|
| bind_processor(self, dialect: 'Dialect') -> 'Optional[_BindProcessorType[_UUID_RETURN]]'
| Return a conversion function for processing bind values.
|
| Returns a callable which will receive a bind parameter value
| as the sole positional argument and will return a value to
| send to the DB-API.
|
| If processing is not necessary, the method should return ``None``.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.bind_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.bind_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_bind_param`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
|
| :param dialect: Dialect instance in use.
|
| coerce_compared_value(self, op, value)
| See :meth:`.TypeEngine.coerce_compared_value` for a description.
|
| literal_processor(self, dialect)
| Return a conversion function for processing literal values that are
| to be rendered directly without using binds.
|
| This function is used when the compiler makes use of the
| "literal_binds" flag, typically used in DDL generation as well
| as in certain scenarios where backends don't accept bound parameters.
|
| Returns a callable which will receive a literal Python value
| as the sole positional argument and will return a string representation
| to be rendered in a SQL statement.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.literal_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.literal_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_literal_param`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| result_processor(self, dialect, coltype)
| Return a conversion function for processing result row values.
|
| Returns a callable which will receive a result row column
| value as the sole positional argument and will return a value
| to return to the user.
|
| If processing is not necessary, the method should return ``None``.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.result_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.result_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_result_value`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| :param dialect: Dialect instance in use.
|
| :param coltype: DBAPI coltype argument received in cursor.description.
|
| ----------------------------------------------------------------------
| Readonly properties inherited from Uuid:
|
| native
|
| python_type
| Return the Python type object expected to be returned
| by instances of this type, if known.
|
| Basically, for those types which enforce a return type,
| or are known across the board to do such for all common
| DBAPIs (like ``int`` for example), will return that type.
|
| If a return type is not defined, raises
| ``NotImplementedError``.
|
| Note that any type also accommodates NULL in SQL which
| means you can also get back ``None`` from any type
| in practice.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from Uuid:
|
| collation = None
|
| length = None
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.type_api.Emulated:
|
| adapt(self, cls: 'Type[Union[TypeEngine[Any], TypeEngineMixin]]', **kw: 'Any') -> 'TypeEngine[Any]'
|
| adapt_to_emulated(self, impltype: 'Type[Union[TypeEngine[Any], TypeEngineMixin]]', **kw: 'Any') -> 'TypeEngine[Any]'
| Given an impl class, adapt this type to the impl assuming
| "emulated".
|
| The impl should also be an "emulated" version of this type,
| most likely the same class as this type itself.
|
| e.g.: sqltypes.Enum adapts to the Enum class.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from sqlalchemy.sql.type_api.Emulated:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.type_api.NativeForEmulated:
|
| adapt_native_to_emulated(impl: 'Union[TypeEngine[Any], TypeEngineMixin]', **kw: 'Any') -> 'TypeEngine[Any]'
| Given an impl, adapt this type's class to the impl assuming
| "emulated".
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.type_api.TypeEngine:
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| __str__(self) -> 'str'
| Return str(self).
|
| as_generic(self, allow_nulltype: 'bool' = False) -> 'TypeEngine[_T]'
| Return an instance of the generic type corresponding to this type
| using heuristic rule. The method may be overridden if this
| heuristic rule is not sufficient.
|
| >>> from sqlalchemy.dialects.mysql import INTEGER
| >>> INTEGER(display_width=4).as_generic()
| Integer()
|
| >>> from sqlalchemy.dialects.mysql import NVARCHAR
| >>> NVARCHAR(length=100).as_generic()
| Unicode(length=100)
|
| .. versionadded:: 1.4.0b2
|
|
| .. seealso::
|
| :ref:`metadata_reflection_dbagnostic_types` - describes the
| use of :meth:`_types.TypeEngine.as_generic` in conjunction with
| the :meth:`_sql.DDLEvents.column_reflect` event, which is its
| intended use.
|
| bind_expression(self, bindvalue: 'BindParameter[_T]') -> 'Optional[ColumnElement[_T]]'
| Given a bind value (i.e. a :class:`.BindParameter` instance),
| return a SQL expression in its place.
|
| This is typically a SQL function that wraps the existing bound
| parameter within the statement. It is used for special data types
| that require literals being wrapped in some special database function
| in order to coerce an application-level value into a database-specific
| format. It is the SQL analogue of the
| :meth:`.TypeEngine.bind_processor` method.
|
| This method is called during the **SQL compilation** phase of a
| statement, when rendering a SQL string. It is **not** called
| against specific values.
|
| Note that this method, when implemented, should always return
| the exact same structure, without any conditional logic, as it
| may be used in an executemany() call against an arbitrary number
| of bound parameter sets.
|
| .. note::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.bind_expression`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.bind_expression`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.bind_expression`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| .. seealso::
|
| :ref:`types_sql_value_processing`
|
| column_expression(self, colexpr: 'ColumnElement[_T]') -> 'Optional[ColumnElement[_T]]'
| Given a SELECT column expression, return a wrapping SQL expression.
|
| This is typically a SQL function that wraps a column expression
| as rendered in the columns clause of a SELECT statement.
| It is used for special data types that require
| columns to be wrapped in some special database function in order
| to coerce the value before being sent back to the application.
| It is the SQL analogue of the :meth:`.TypeEngine.result_processor`
| method.
|
| .. note:: The :func:`.TypeEngine.column_expression` method is applied
| only to the **outermost columns clause** of a SELECT statement, that
| is, the columns that are to be delivered directly into the returned
| result rows. It does **not** apply to the columns clause inside
| of subqueries. This necessarily avoids double conversions against
| the column and only runs the conversion when ready to be returned
| to the client.
|
| This method is called during the **SQL compilation** phase of a
| statement, when rendering a SQL string. It is **not** called
| against specific values.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.column_expression`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.column_expression`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.column_expression`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
|
| .. seealso::
|
| :ref:`types_sql_value_processing`
|
| compare_values(self, x: 'Any', y: 'Any') -> 'bool'
| Compare two values for equality.
|
| compile(self, dialect: 'Optional[Dialect]' = None) -> 'str'
| Produce a string-compiled form of this :class:`.TypeEngine`.
|
| When called with no arguments, uses a "default" dialect
| to produce a string result.
|
| :param dialect: a :class:`.Dialect` instance.
|
| copy(self, **kw: 'Any') -> 'Self'
|
| copy_value(self, value: 'Any') -> 'Any'
|
| dialect_impl(self, dialect: 'Dialect') -> 'TypeEngine[_T]'
| Return a dialect-specific implementation for this
| :class:`.TypeEngine`.
|
| evaluates_none(self) -> 'Self'
| Return a copy of this type which has the
| :attr:`.should_evaluate_none` flag set to True.
|
| E.g.::
|
| Table(
| "some_table",
| metadata,
| Column(
| String(50).evaluates_none(),
| nullable=True,
| server_default="no value",
| ),
| )
|
| The ORM uses this flag to indicate that a positive value of ``None``
| is passed to the column in an INSERT statement, rather than omitting
| the column from the INSERT statement which has the effect of firing
| off column-level defaults. It also allows for types which have
| special behavior associated with the Python None value to indicate
| that the value doesn't necessarily translate into SQL NULL; a
| prime example of this is a JSON type which may wish to persist the
| JSON value ``'null'``.
|
| In all cases, the actual NULL SQL value can be always be
| persisted in any column by using
| the :obj:`_expression.null` SQL construct in an INSERT statement
| or associated with an ORM-mapped attribute.
|
| .. note::
|
| The "evaluates none" flag does **not** apply to a value
| of ``None`` passed to :paramref:`_schema.Column.default` or
| :paramref:`_schema.Column.server_default`; in these cases,
| ``None``
| still means "no default".
|
| .. seealso::
|
| :ref:`session_forcing_null` - in the ORM documentation
|
| :paramref:`.postgresql.JSON.none_as_null` - PostgreSQL JSON
| interaction with this flag.
|
| :attr:`.TypeEngine.should_evaluate_none` - class-level flag
|
| get_dbapi_type(self, dbapi: 'DBAPIModule') -> 'Optional[Any]'
| Return the corresponding type object from the underlying DB-API, if
| any.
|
| This can be useful for calling ``setinputsizes()``, for example.
|
| with_variant(self, type_: '_TypeEngineArgument[Any]', *dialect_names: 'str') -> 'Self'
| Produce a copy of this type object that will utilize the given
| type when applied to the dialect of the given name.
|
| e.g.::
|
| from sqlalchemy.types import String
| from sqlalchemy.dialects import mysql
|
| string_type = String()
|
| string_type = string_type.with_variant(
| mysql.VARCHAR(collation="foo"), "mysql", "mariadb"
| )
|
| The variant mapping indicates that when this type is
| interpreted by a specific dialect, it will instead be
| transmuted into the given type, rather than using the
| primary type.
|
| .. versionchanged:: 2.0 the :meth:`_types.TypeEngine.with_variant`
| method now works with a :class:`_types.TypeEngine` object "in
| place", returning a copy of the original type rather than returning
| a wrapping object; the ``Variant`` class is no longer used.
|
| :param type\_: a :class:`.TypeEngine` that will be selected
| as a variant from the originating type, when a dialect
| of the given name is in use.
| :param \*dialect_names: one or more base names of the dialect which
| uses this type. (i.e. ``'postgresql'``, ``'mysql'``, etc.)
|
| .. versionchanged:: 2.0 multiple dialect names can be specified
| for one variant.
|
| .. seealso::
|
| :ref:`types_with_variant` - illustrates the use of
| :meth:`_types.TypeEngine.with_variant`.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.type_api.TypeEngine:
|
| Comparator = <class 'sqlalchemy.sql.type_api.TypeEngine.Comparator'>
| Base class for custom comparison operations defined at the
| type level. See :attr:`.TypeEngine.comparator_factory`.
|
|
| __orig_bases__ = (<class 'sqlalchemy.sql.visitors.Visitable'>, typing....
|
| comparator_factory = <class 'sqlalchemy.sql.type_api.TypeEngine.Compar...
| Base class for custom comparison operations defined at the
| type level. See :attr:`.TypeEngine.comparator_factory`.
|
|
| hashable = True
|
| render_bind_cast = False
|
| render_literal_cast = False
|
| should_evaluate_none = False
|
| sort_key_function = None
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.visitors.Visitable:
|
| __class_getitem__(key: 'Any') -> 'Any'
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__() -> 'None'
| This method is called when a class is subclassed.
|
| The default implementation does nothing. It may be
| overridden to extend subclasses.
sqlalchemy.UnaryExpression
Python Library Documentation: class UnaryExpression in module sqlalchemy.sql.elements
class UnaryExpression(ColumnElement)
| UnaryExpression(element: 'ColumnElement[Any]', *, operator: 'Optional[OperatorType]' = None, modifier: 'Optional[OperatorType]' = None, type_: 'Optional[_TypeEngineArgument[_T]]' = None, wraps_column_expression: 'bool' = False)
|
| 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.
|
| :class:`.UnaryExpression` is the basis for several unary operators
| including those used by :func:`.desc`, :func:`.asc`, :func:`.distinct`,
| :func:`.nulls_first` and :func:`.nulls_last`.
|
| Method resolution order:
| UnaryExpression
| ColumnElement
| sqlalchemy.sql.roles.ColumnArgumentOrKeyRole
| sqlalchemy.sql.roles.ColumnArgumentRole
| sqlalchemy.sql.roles.StatementOptionRole
| sqlalchemy.sql.roles.WhereHavingRole
| sqlalchemy.sql.roles.OnClauseRole
| sqlalchemy.sql.roles.BinaryElementRole
| sqlalchemy.sql.roles.OrderByRole
| sqlalchemy.sql.roles.ColumnsClauseRole
| sqlalchemy.sql.roles.AllowsLambdaRole
| sqlalchemy.sql.roles.ByOfRole
| sqlalchemy.sql.roles.UsesInspection
| sqlalchemy.sql.roles.ColumnListRole
| sqlalchemy.sql.roles.LimitOffsetRole
| sqlalchemy.sql.roles.DMLColumnRole
| sqlalchemy.sql.roles.DDLConstraintColumnRole
| sqlalchemy.sql.roles.DDLExpressionRole
| sqlalchemy.sql.roles.StructuralRole
| SQLColumnExpression
| SQLCoreOperations
| sqlalchemy.sql.roles.ExpressionElementRole
| sqlalchemy.sql.roles.TypedColumnsClauseRole
| typing.Generic
| sqlalchemy.sql.operators.ColumnOperators
| sqlalchemy.sql.operators.Operators
| sqlalchemy.util.langhelpers.TypingOnly
| sqlalchemy.sql.roles.SQLRole
| DQLDMLClauseElement
| ClauseElement
| sqlalchemy.sql.annotation.SupportsWrappingAnnotations
| sqlalchemy.sql.annotation.SupportsAnnotations
| sqlalchemy.sql.cache_key.MemoizedHasCacheKey
| sqlalchemy.sql.cache_key.HasCacheKey
| sqlalchemy.util.langhelpers.HasMemoized
| sqlalchemy.sql.traversals.HasCopyInternals
| sqlalchemy.sql.visitors.ExternallyTraversible
| sqlalchemy.sql.visitors.HasTraverseInternals
| CompilerElement
| sqlalchemy.sql.visitors.Visitable
| builtins.object
|
| Methods defined here:
|
| __init__(self, element: 'ColumnElement[Any]', *, operator: 'Optional[OperatorType]' = None, modifier: 'Optional[OperatorType]' = None, type_: 'Optional[_TypeEngineArgument[_T]]' = None, wraps_column_expression: 'bool' = False)
| Initialize self. See help(type(self)) for accurate signature.
|
| self_group(self, against: 'Optional[OperatorType]' = None) -> 'Union[Self, Grouping[_T]]'
| 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.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'_traverse_internals': '_TraverseInternalsType', 'e...
|
| __orig_bases__ = (sqlalchemy.sql.elements.ColumnElement[~_T],)
|
| __parameters__ = (~_T,)
|
| __visit_name__ = 'unary'
|
| ----------------------------------------------------------------------
| Methods inherited from ColumnElement:
|
| __getattr__(self, key: 'str') -> 'Any'
|
| __setstate__(self, state)
|
| base_columns(...)
|
| cast(self, type_: '_TypeEngineArgument[_OPT]') -> 'Cast[_OPT]'
| Produce a type cast, i.e. ``CAST(<expression> AS <type>)``.
|
| This is a shortcut to the :func:`_expression.cast` function.
|
| .. seealso::
|
| :ref:`tutorial_casts`
|
| :func:`_expression.cast`
|
| :func:`_expression.type_coerce`
|
| comparator(...)
|
| label(self, name: 'Optional[str]') -> 'Label[_T]'
| Produce a column label, i.e. ``<columnname> AS <name>``.
|
| This is a shortcut to the :func:`_expression.label` function.
|
| If 'name' is ``None``, an anonymous label name will be generated.
|
| operate(self, op: 'operators.OperatorType', *other: 'Any', **kwargs: 'Any') -> 'ColumnElement[Any]'
| Operate on an argument.
|
| This is the lowest level of operation, raises
| :class:`NotImplementedError` by default.
|
| Overriding this on a subclass can allow common
| behavior to be applied to all operations.
| For example, overriding :class:`.ColumnOperators`
| to apply ``func.lower()`` to the left and right
| side::
|
| class MyComparator(ColumnOperators):
| def operate(self, op, other, **kwargs):
| return op(func.lower(self), func.lower(other), **kwargs)
|
| :param op: Operator callable.
| :param \*other: the 'other' side of the operation. Will
| be a single scalar for most operations.
| :param \**kwargs: modifiers. These may be passed by special
| operators such as :meth:`ColumnOperators.contains`.
|
| proxy_set(...)
| set of all columns we are proxying
|
| as of 2.0 this is explicitly deannotated columns. previously it was
| effectively deannotated columns but wasn't enforced. annotated
| columns should basically not go into sets if at all possible because
| their hashing behavior is very non-performant.
|
| reverse_operate(self, op: 'operators.OperatorType', other: 'Any', **kwargs: 'Any') -> 'ColumnElement[Any]'
| Reverse operate on an argument.
|
| Usage is the same as :meth:`operate`.
|
| shares_lineage(self, othercolumn: 'ColumnElement[Any]') -> 'bool'
| Return True if the given :class:`_expression.ColumnElement`
| has a common ancestor to this :class:`_expression.ColumnElement`.
|
| type(...)
|
| ----------------------------------------------------------------------
| Readonly properties inherited from ColumnElement:
|
| anon_key_label
| .. deprecated:: 1.4 The :attr:`_expression.ColumnElement.anon_key_label` attribute is now private, and the public accessor is deprecated.
|
| anon_label
| .. deprecated:: 1.4 The :attr:`_expression.ColumnElement.anon_label` attribute is now private, and the public accessor is deprecated.
|
| expression
| Return a column expression.
|
| Part of the inspection interface; returns self.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from ColumnElement:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from ColumnElement:
|
| foreign_keys = frozenset()
|
| key = None
|
| primary_key = False
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.AllowsLambdaRole:
|
| allows_lambda = True
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.UsesInspection:
|
| uses_inspection = True
|
| ----------------------------------------------------------------------
| Class methods inherited from typing.Generic:
|
| __class_getitem__(...)
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__(...)
| Function to initialize subclasses.
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.operators.ColumnOperators:
|
| __add__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``+`` operator.
|
| In a column context, produces the clause ``a + b``
| if the parent object has non-string affinity.
| If the parent object has a string affinity,
| produces the concatenation operator, ``a || b`` -
| see :meth:`.ColumnOperators.concat`.
|
| __contains__(self, other: 'Any') -> 'ColumnOperators'
|
| __eq__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``==`` operator.
|
| In a column context, produces the clause ``a = b``.
| If the target is ``None``, produces ``a IS NULL``.
|
| __floordiv__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``//`` operator.
|
| In a column context, produces the clause ``a / b``,
| which is the same as "truediv", but considers the result
| type to be integer.
|
| .. versionadded:: 2.0
|
| __ge__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``>=`` operator.
|
| In a column context, produces the clause ``a >= b``.
|
| __getitem__(self, index: 'Any') -> 'ColumnOperators'
| Implement the [] operator.
|
| This can be used by some database-specific types
| such as PostgreSQL ARRAY and HSTORE.
|
| __gt__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``>`` operator.
|
| In a column context, produces the clause ``a > b``.
|
| __hash__(self, /) from builtins.object
| Return hash(self).
|
| __le__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``<=`` operator.
|
| In a column context, produces the clause ``a <= b``.
|
| __lshift__(self, other: 'Any') -> 'ColumnOperators'
| implement the << operator.
|
| Not used by SQLAlchemy core, this is provided
| for custom operator systems which want to use
| << as an extension point.
|
| __lt__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``<`` operator.
|
| In a column context, produces the clause ``a < b``.
|
| __mod__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``%`` operator.
|
| In a column context, produces the clause ``a % b``.
|
| __mul__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``*`` operator.
|
| In a column context, produces the clause ``a * b``.
|
| __ne__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``!=`` operator.
|
| In a column context, produces the clause ``a != b``.
| If the target is ``None``, produces ``a IS NOT NULL``.
|
| __neg__(self) -> 'ColumnOperators'
| Implement the ``-`` operator.
|
| In a column context, produces the clause ``-a``.
|
| __radd__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``+`` operator in reverse.
|
| See :meth:`.ColumnOperators.__add__`.
|
| __rfloordiv__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``//`` operator in reverse.
|
| See :meth:`.ColumnOperators.__floordiv__`.
|
| __rmod__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``%`` operator in reverse.
|
| See :meth:`.ColumnOperators.__mod__`.
|
| __rmul__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``*`` operator in reverse.
|
| See :meth:`.ColumnOperators.__mul__`.
|
| __rshift__(self, other: 'Any') -> 'ColumnOperators'
| implement the >> operator.
|
| Not used by SQLAlchemy core, this is provided
| for custom operator systems which want to use
| >> as an extension point.
|
| __rsub__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``-`` operator in reverse.
|
| See :meth:`.ColumnOperators.__sub__`.
|
| __rtruediv__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``/`` operator in reverse.
|
| See :meth:`.ColumnOperators.__truediv__`.
|
| __sub__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``-`` operator.
|
| In a column context, produces the clause ``a - b``.
|
| __truediv__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``/`` operator.
|
| In a column context, produces the clause ``a / b``, and
| considers the result type to be numeric.
|
| .. versionchanged:: 2.0 The truediv operator against two integers
| is now considered to return a numeric value. Behavior on specific
| backends may vary.
|
| all_(self) -> 'ColumnOperators'
| Produce an :func:`_expression.all_` clause against the
| parent object.
|
| See the documentation for :func:`_sql.all_` for examples.
|
| .. note:: be sure to not confuse the newer
| :meth:`_sql.ColumnOperators.all_` method with the **legacy**
| version of this method, the :meth:`_types.ARRAY.Comparator.all`
| method that's specific to :class:`_types.ARRAY`, which uses a
| different calling style.
|
| any_(self) -> 'ColumnOperators'
| Produce an :func:`_expression.any_` clause against the
| parent object.
|
| See the documentation for :func:`_sql.any_` for examples.
|
| .. note:: be sure to not confuse the newer
| :meth:`_sql.ColumnOperators.any_` method with the **legacy**
| version of this method, the :meth:`_types.ARRAY.Comparator.any`
| method that's specific to :class:`_types.ARRAY`, which uses a
| different calling style.
|
| asc(self) -> 'ColumnOperators'
| Produce a :func:`_expression.asc` clause against the
| parent object.
|
| between(self, cleft: 'Any', cright: 'Any', symmetric: 'bool' = False) -> 'ColumnOperators'
| Produce a :func:`_expression.between` clause against
| the parent object, given the lower and upper range.
|
| bitwise_and(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise AND operation, typically via the ``&``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_lshift(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise LSHIFT operation, typically via the ``<<``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_not(self) -> 'ColumnOperators'
| Produce a bitwise NOT operation, typically via the ``~``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_or(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise OR operation, typically via the ``|``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_rshift(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise RSHIFT operation, typically via the ``>>``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_xor(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise XOR operation, typically via the ``^``
| operator, or ``#`` for PostgreSQL.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| collate(self, collation: 'str') -> 'ColumnOperators'
| Produce a :func:`_expression.collate` clause against
| the parent object, given the collation string.
|
| .. seealso::
|
| :func:`_expression.collate`
|
| concat(self, other: 'Any') -> 'ColumnOperators'
| Implement the 'concat' operator.
|
| In a column context, produces the clause ``a || b``,
| or uses the ``concat()`` operator on MySQL.
|
| contains(self, other: 'Any', **kw: 'Any') -> 'ColumnOperators'
| Implement the 'contains' operator.
|
| Produces a LIKE expression that tests against a match for the middle
| of a string value:
|
| .. sourcecode:: sql
|
| column LIKE '%' || <other> || '%'
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.contains("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.contains.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.contains.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.contains.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.contains("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE '%' || :param || '%' ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.contains("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE '%' || :param || '%' ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.contains.autoescape`::
|
| somecolumn.contains("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.startswith`
|
| :meth:`.ColumnOperators.endswith`
|
| :meth:`.ColumnOperators.like`
|
| desc(self) -> 'ColumnOperators'
| Produce a :func:`_expression.desc` clause against the
| parent object.
|
| distinct(self) -> 'ColumnOperators'
| Produce a :func:`_expression.distinct` clause against the
| parent object.
|
| endswith(self, other: 'Any', escape: 'Optional[str]' = None, autoescape: 'bool' = False) -> 'ColumnOperators'
| Implement the 'endswith' operator.
|
| Produces a LIKE expression that tests against a match for the end
| of a string value:
|
| .. sourcecode:: sql
|
| column LIKE '%' || <other>
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.endswith("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.endswith.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.endswith.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.endswith.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.endswith("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE '%' || :param ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.endswith("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE '%' || :param ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.endswith.autoescape`::
|
| somecolumn.endswith("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.startswith`
|
| :meth:`.ColumnOperators.contains`
|
| :meth:`.ColumnOperators.like`
|
| icontains(self, other: 'Any', **kw: 'Any') -> 'ColumnOperators'
| Implement the ``icontains`` operator, e.g. case insensitive
| version of :meth:`.ColumnOperators.contains`.
|
| Produces a LIKE expression that tests against an insensitive match
| for the middle of a string value:
|
| .. sourcecode:: sql
|
| lower(column) LIKE '%' || lower(<other>) || '%'
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.icontains("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.icontains.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.icontains.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.icontains.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.icontains("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE '%' || lower(:param) || '%' ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.icontains("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE '%' || lower(:param) || '%' ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.contains.autoescape`::
|
| somecolumn.icontains("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.contains`
|
| iendswith(self, other: 'Any', escape: 'Optional[str]' = None, autoescape: 'bool' = False) -> 'ColumnOperators'
| Implement the ``iendswith`` operator, e.g. case insensitive
| version of :meth:`.ColumnOperators.endswith`.
|
| Produces a LIKE expression that tests against an insensitive match
| for the end of a string value:
|
| .. sourcecode:: sql
|
| lower(column) LIKE '%' || lower(<other>)
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.iendswith("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.iendswith.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.iendswith.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.iendswith.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.iendswith("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE '%' || lower(:param) ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.iendswith("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE '%' || lower(:param) ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.iendswith.autoescape`::
|
| somecolumn.endswith("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.endswith`
|
| ilike(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
| Implement the ``ilike`` operator, e.g. case insensitive LIKE.
|
| In a column context, produces an expression either of the form:
|
| .. sourcecode:: sql
|
| lower(a) LIKE lower(other)
|
| Or on backends that support the ILIKE operator:
|
| .. sourcecode:: sql
|
| a ILIKE other
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.ilike("%foobar%"))
|
| :param other: expression to be compared
| :param escape: optional escape character, renders the ``ESCAPE``
| keyword, e.g.::
|
| somecolumn.ilike("foo/%bar", escape="/")
|
| .. seealso::
|
| :meth:`.ColumnOperators.like`
|
| in_(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``in`` operator.
|
| In a column context, produces the clause ``column IN <other>``.
|
| The given parameter ``other`` may be:
|
| * A list of literal values,
| e.g.::
|
| stmt.where(column.in_([1, 2, 3]))
|
| In this calling form, the list of items is converted to a set of
| bound parameters the same length as the list given:
|
| .. sourcecode:: sql
|
| WHERE COL IN (?, ?, ?)
|
| * A list of tuples may be provided if the comparison is against a
| :func:`.tuple_` containing multiple expressions::
|
| from sqlalchemy import tuple_
|
| stmt.where(tuple_(col1, col2).in_([(1, 10), (2, 20), (3, 30)]))
|
| * An empty list,
| e.g.::
|
| stmt.where(column.in_([]))
|
| In this calling form, the expression renders an "empty set"
| expression. These expressions are tailored to individual backends
| and are generally trying to get an empty SELECT statement as a
| subquery. Such as on SQLite, the expression is:
|
| .. sourcecode:: sql
|
| WHERE col IN (SELECT 1 FROM (SELECT 1) WHERE 1!=1)
|
| .. versionchanged:: 1.4 empty IN expressions now use an
| execution-time generated SELECT subquery in all cases.
|
| * A bound parameter, e.g. :func:`.bindparam`, may be used if it
| includes the :paramref:`.bindparam.expanding` flag::
|
| stmt.where(column.in_(bindparam("value", expanding=True)))
|
| In this calling form, the expression renders a special non-SQL
| placeholder expression that looks like:
|
| .. sourcecode:: sql
|
| WHERE COL IN ([EXPANDING_value])
|
| This placeholder expression is intercepted at statement execution
| time to be converted into the variable number of bound parameter
| form illustrated earlier. If the statement were executed as::
|
| connection.execute(stmt, {"value": [1, 2, 3]})
|
| The database would be passed a bound parameter for each value:
|
| .. sourcecode:: sql
|
| WHERE COL IN (?, ?, ?)
|
| .. versionadded:: 1.2 added "expanding" bound parameters
|
| If an empty list is passed, a special "empty list" expression,
| which is specific to the database in use, is rendered. On
| SQLite this would be:
|
| .. sourcecode:: sql
|
| WHERE COL IN (SELECT 1 FROM (SELECT 1) WHERE 1!=1)
|
| .. versionadded:: 1.3 "expanding" bound parameters now support
| empty lists
|
| * a :func:`_expression.select` construct, which is usually a
| correlated scalar select::
|
| stmt.where(
| column.in_(select(othertable.c.y).where(table.c.x == othertable.c.x))
| )
|
| In this calling form, :meth:`.ColumnOperators.in_` renders as given:
|
| .. sourcecode:: sql
|
| WHERE COL IN (SELECT othertable.y
| FROM othertable WHERE othertable.x = table.x)
|
| :param other: a list of literals, a :func:`_expression.select`
| construct, or a :func:`.bindparam` construct that includes the
| :paramref:`.bindparam.expanding` flag set to True.
|
| is_(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``IS`` operator.
|
| Normally, ``IS`` is generated automatically when comparing to a
| value of ``None``, which resolves to ``NULL``. However, explicit
| usage of ``IS`` may be desirable if comparing to boolean values
| on certain platforms.
|
| .. seealso:: :meth:`.ColumnOperators.is_not`
|
| is_distinct_from(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``IS DISTINCT FROM`` operator.
|
| Renders "a IS DISTINCT FROM b" on most platforms;
| on some such as SQLite may render "a IS NOT b".
|
| is_not(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``IS NOT`` operator.
|
| Normally, ``IS NOT`` is generated automatically when comparing to a
| value of ``None``, which resolves to ``NULL``. However, explicit
| usage of ``IS NOT`` may be desirable if comparing to boolean values
| on certain platforms.
|
| .. versionchanged:: 1.4 The ``is_not()`` operator is renamed from
| ``isnot()`` in previous releases. The previous name remains
| available for backwards compatibility.
|
| .. seealso:: :meth:`.ColumnOperators.is_`
|
| is_not_distinct_from(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``IS NOT DISTINCT FROM`` operator.
|
| Renders "a IS NOT DISTINCT FROM b" on most platforms;
| on some such as SQLite may render "a IS b".
|
| .. versionchanged:: 1.4 The ``is_not_distinct_from()`` operator is
| renamed from ``isnot_distinct_from()`` in previous releases.
| The previous name remains available for backwards compatibility.
|
| isnot = is_not(self, other: 'Any') -> 'ColumnOperators'
|
| isnot_distinct_from = is_not_distinct_from(self, other: 'Any') -> 'ColumnOperators'
|
| istartswith(self, other: 'Any', escape: 'Optional[str]' = None, autoescape: 'bool' = False) -> 'ColumnOperators'
| Implement the ``istartswith`` operator, e.g. case insensitive
| version of :meth:`.ColumnOperators.startswith`.
|
| Produces a LIKE expression that tests against an insensitive
| match for the start of a string value:
|
| .. sourcecode:: sql
|
| lower(column) LIKE lower(<other>) || '%'
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.istartswith("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.istartswith.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.istartswith.escape` parameter will
| establish a given character as an escape character which can be of
| use when the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.istartswith.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.istartswith("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE lower(:param) || '%' ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.istartswith("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE lower(:param) || '%' ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.istartswith.autoescape`::
|
| somecolumn.istartswith("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.startswith`
|
| like(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
| Implement the ``like`` operator.
|
| In a column context, produces the expression:
|
| .. sourcecode:: sql
|
| a LIKE other
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.like("%foobar%"))
|
| :param other: expression to be compared
| :param escape: optional escape character, renders the ``ESCAPE``
| keyword, e.g.::
|
| somecolumn.like("foo/%bar", escape="/")
|
| .. seealso::
|
| :meth:`.ColumnOperators.ilike`
|
| match(self, other: 'Any', **kwargs: 'Any') -> 'ColumnOperators'
| Implements a database-specific 'match' operator.
|
| :meth:`_sql.ColumnOperators.match` attempts to resolve to
| a MATCH-like function or operator provided by the backend.
| Examples include:
|
| * PostgreSQL - renders ``x @@ plainto_tsquery(y)``
|
| .. versionchanged:: 2.0 ``plainto_tsquery()`` is used instead
| of ``to_tsquery()`` for PostgreSQL now; for compatibility with
| other forms, see :ref:`postgresql_match`.
|
|
| * MySQL - renders ``MATCH (x) AGAINST (y IN BOOLEAN MODE)``
|
| .. seealso::
|
| :class:`_mysql.match` - MySQL specific construct with
| additional features.
|
| * Oracle Database - renders ``CONTAINS(x, y)``
| * other backends may provide special implementations.
| * Backends without any special implementation will emit
| the operator as "MATCH". This is compatible with SQLite, for
| example.
|
| not_ilike(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
| implement the ``NOT ILIKE`` operator.
|
| This is equivalent to using negation with
| :meth:`.ColumnOperators.ilike`, i.e. ``~x.ilike(y)``.
|
| .. versionchanged:: 1.4 The ``not_ilike()`` operator is renamed from
| ``notilike()`` in previous releases. The previous name remains
| available for backwards compatibility.
|
| .. seealso::
|
| :meth:`.ColumnOperators.ilike`
|
| not_in(self, other: 'Any') -> 'ColumnOperators'
| implement the ``NOT IN`` operator.
|
| This is equivalent to using negation with
| :meth:`.ColumnOperators.in_`, i.e. ``~x.in_(y)``.
|
| In the case that ``other`` is an empty sequence, the compiler
| produces an "empty not in" expression. This defaults to the
| expression "1 = 1" to produce true in all cases. The
| :paramref:`_sa.create_engine.empty_in_strategy` may be used to
| alter this behavior.
|
| .. versionchanged:: 1.4 The ``not_in()`` operator is renamed from
| ``notin_()`` in previous releases. The previous name remains
| available for backwards compatibility.
|
| .. versionchanged:: 1.2 The :meth:`.ColumnOperators.in_` and
| :meth:`.ColumnOperators.not_in` operators
| now produce a "static" expression for an empty IN sequence
| by default.
|
| .. seealso::
|
| :meth:`.ColumnOperators.in_`
|
| not_like(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
| implement the ``NOT LIKE`` operator.
|
| This is equivalent to using negation with
| :meth:`.ColumnOperators.like`, i.e. ``~x.like(y)``.
|
| .. versionchanged:: 1.4 The ``not_like()`` operator is renamed from
| ``notlike()`` in previous releases. The previous name remains
| available for backwards compatibility.
|
| .. seealso::
|
| :meth:`.ColumnOperators.like`
|
| notilike = not_ilike(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
|
| notin_ = not_in(self, other: 'Any') -> 'ColumnOperators'
|
| notlike = not_like(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
|
| nulls_first(self) -> 'ColumnOperators'
| Produce a :func:`_expression.nulls_first` clause against the
| parent object.
|
| .. versionchanged:: 1.4 The ``nulls_first()`` operator is
| renamed from ``nullsfirst()`` in previous releases.
| The previous name remains available for backwards compatibility.
|
| nulls_last(self) -> 'ColumnOperators'
| Produce a :func:`_expression.nulls_last` clause against the
| parent object.
|
| .. versionchanged:: 1.4 The ``nulls_last()`` operator is
| renamed from ``nullslast()`` in previous releases.
| The previous name remains available for backwards compatibility.
|
| nullsfirst = nulls_first(self) -> 'ColumnOperators'
|
| nullslast = nulls_last(self) -> 'ColumnOperators'
|
| regexp_match(self, pattern: 'Any', flags: 'Optional[str]' = None) -> 'ColumnOperators'
| Implements a database-specific 'regexp match' operator.
|
| E.g.::
|
| stmt = select(table.c.some_column).where(
| table.c.some_column.regexp_match("^(b|c)")
| )
|
| :meth:`_sql.ColumnOperators.regexp_match` attempts to resolve to
| a REGEXP-like function or operator provided by the backend, however
| the specific regular expression syntax and flags available are
| **not backend agnostic**.
|
| Examples include:
|
| * PostgreSQL - renders ``x ~ y`` or ``x !~ y`` when negated.
| * Oracle Database - renders ``REGEXP_LIKE(x, y)``
| * SQLite - uses SQLite's ``REGEXP`` placeholder operator and calls into
| the Python ``re.match()`` builtin.
| * other backends may provide special implementations.
| * Backends without any special implementation will emit
| the operator as "REGEXP" or "NOT REGEXP". This is compatible with
| SQLite and MySQL, for example.
|
| Regular expression support is currently implemented for Oracle
| Database, PostgreSQL, MySQL and MariaDB. Partial support is available
| for SQLite. Support among third-party dialects may vary.
|
| :param pattern: The regular expression pattern string or column
| clause.
| :param flags: Any regular expression string flags to apply, passed as
| plain Python string only. These flags are backend specific.
| Some backends, like PostgreSQL and MariaDB, may alternatively
| specify the flags as part of the pattern.
| When using the ignore case flag 'i' in PostgreSQL, the ignore case
| regexp match operator ``~*`` or ``!~*`` will be used.
|
| .. versionadded:: 1.4
|
| .. versionchanged:: 1.4.48, 2.0.18 Note that due to an implementation
| error, the "flags" parameter previously accepted SQL expression
| objects such as column expressions in addition to plain Python
| strings. This implementation did not work correctly with caching
| and was removed; strings only should be passed for the "flags"
| parameter, as these flags are rendered as literal inline values
| within SQL expressions.
|
| .. seealso::
|
| :meth:`_sql.ColumnOperators.regexp_replace`
|
| regexp_replace(self, pattern: 'Any', replacement: 'Any', flags: 'Optional[str]' = None) -> 'ColumnOperators'
| Implements a database-specific 'regexp replace' operator.
|
| E.g.::
|
| stmt = select(
| table.c.some_column.regexp_replace("b(..)", "XY", flags="g")
| )
|
| :meth:`_sql.ColumnOperators.regexp_replace` attempts to resolve to
| a REGEXP_REPLACE-like function provided by the backend, that
| usually emit the function ``REGEXP_REPLACE()``. However,
| the specific regular expression syntax and flags available are
| **not backend agnostic**.
|
| Regular expression replacement support is currently implemented for
| Oracle Database, PostgreSQL, MySQL 8 or greater and MariaDB. Support
| among third-party dialects may vary.
|
| :param pattern: The regular expression pattern string or column
| clause.
| :param pattern: The replacement string or column clause.
| :param flags: Any regular expression string flags to apply, passed as
| plain Python string only. These flags are backend specific.
| Some backends, like PostgreSQL and MariaDB, may alternatively
| specify the flags as part of the pattern.
|
| .. versionadded:: 1.4
|
| .. versionchanged:: 1.4.48, 2.0.18 Note that due to an implementation
| error, the "flags" parameter previously accepted SQL expression
| objects such as column expressions in addition to plain Python
| strings. This implementation did not work correctly with caching
| and was removed; strings only should be passed for the "flags"
| parameter, as these flags are rendered as literal inline values
| within SQL expressions.
|
|
| .. seealso::
|
| :meth:`_sql.ColumnOperators.regexp_match`
|
| startswith(self, other: 'Any', escape: 'Optional[str]' = None, autoescape: 'bool' = False) -> 'ColumnOperators'
| Implement the ``startswith`` operator.
|
| Produces a LIKE expression that tests against a match for the start
| of a string value:
|
| .. sourcecode:: sql
|
| column LIKE <other> || '%'
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.startswith("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.startswith.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.startswith.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.startswith.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.startswith("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE :param || '%' ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.startswith("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE :param || '%' ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.startswith.autoescape`::
|
| somecolumn.startswith("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.endswith`
|
| :meth:`.ColumnOperators.contains`
|
| :meth:`.ColumnOperators.like`
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.operators.ColumnOperators:
|
| timetuple = None
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.operators.Operators:
|
| __and__(self, other: 'Any') -> 'Operators'
| Implement the ``&`` operator.
|
| When used with SQL expressions, results in an
| AND operation, equivalent to
| :func:`_expression.and_`, that is::
|
| a & b
|
| is equivalent to::
|
| from sqlalchemy import and_
|
| and_(a, b)
|
| Care should be taken when using ``&`` regarding
| operator precedence; the ``&`` operator has the highest precedence.
| The operands should be enclosed in parenthesis if they contain
| further sub expressions::
|
| (a == 2) & (b == 4)
|
| __invert__(self) -> 'Operators'
| Implement the ``~`` operator.
|
| When used with SQL expressions, results in a
| NOT operation, equivalent to
| :func:`_expression.not_`, that is::
|
| ~a
|
| is equivalent to::
|
| from sqlalchemy import not_
|
| not_(a)
|
| __or__(self, other: 'Any') -> 'Operators'
| Implement the ``|`` operator.
|
| When used with SQL expressions, results in an
| OR operation, equivalent to
| :func:`_expression.or_`, that is::
|
| a | b
|
| is equivalent to::
|
| from sqlalchemy import or_
|
| or_(a, b)
|
| Care should be taken when using ``|`` regarding
| operator precedence; the ``|`` operator has the highest precedence.
| The operands should be enclosed in parenthesis if they contain
| further sub expressions::
|
| (a == 2) | (b == 4)
|
| __sa_operate__ = operate(self, op: 'OperatorType', *other: 'Any', **kwargs: 'Any') -> 'Operators'
| Operate on an argument.
|
| This is the lowest level of operation, raises
| :class:`NotImplementedError` by default.
|
| Overriding this on a subclass can allow common
| behavior to be applied to all operations.
| For example, overriding :class:`.ColumnOperators`
| to apply ``func.lower()`` to the left and right
| side::
|
| class MyComparator(ColumnOperators):
| def operate(self, op, other, **kwargs):
| return op(func.lower(self), func.lower(other), **kwargs)
|
| :param op: Operator callable.
| :param \*other: the 'other' side of the operation. Will
| be a single scalar for most operations.
| :param \**kwargs: modifiers. These may be passed by special
| operators such as :meth:`ColumnOperators.contains`.
|
| bool_op(self, opstring: 'str', precedence: 'int' = 0, python_impl: 'Optional[Callable[..., Any]]' = None) -> 'Callable[[Any], Operators]'
| Return a custom boolean operator.
|
| This method is shorthand for calling
| :meth:`.Operators.op` and passing the
| :paramref:`.Operators.op.is_comparison`
| flag with True. A key advantage to using :meth:`.Operators.bool_op`
| is that when using column constructs, the "boolean" nature of the
| returned expression will be present for :pep:`484` purposes.
|
| .. seealso::
|
| :meth:`.Operators.op`
|
| op(self, opstring: 'str', precedence: 'int' = 0, is_comparison: 'bool' = False, return_type: 'Optional[Union[Type[TypeEngine[Any]], TypeEngine[Any]]]' = None, python_impl: 'Optional[Callable[..., Any]]' = None) -> 'Callable[[Any], Operators]'
| Produce a generic operator function.
|
| e.g.::
|
| somecolumn.op("*")(5)
|
| produces::
|
| somecolumn * 5
|
| This function can also be used to make bitwise operators explicit. For
| example::
|
| somecolumn.op("&")(0xFF)
|
| is a bitwise AND of the value in ``somecolumn``.
|
| :param opstring: a string which will be output as the infix operator
| between this element and the expression passed to the
| generated function.
|
| :param precedence: precedence which the database is expected to apply
| to the operator in SQL expressions. This integer value acts as a hint
| for the SQL compiler to know when explicit parenthesis should be
| rendered around a particular operation. A lower number will cause the
| expression to be parenthesized when applied against another operator
| with higher precedence. The default value of ``0`` is lower than all
| operators except for the comma (``,``) and ``AS`` operators. A value
| of 100 will be higher or equal to all operators, and -100 will be
| lower than or equal to all operators.
|
| .. seealso::
|
| :ref:`faq_sql_expression_op_parenthesis` - detailed description
| of how the SQLAlchemy SQL compiler renders parenthesis
|
| :param is_comparison: legacy; if True, the operator will be considered
| as a "comparison" operator, that is which evaluates to a boolean
| true/false value, like ``==``, ``>``, etc. This flag is provided
| so that ORM relationships can establish that the operator is a
| comparison operator when used in a custom join condition.
|
| Using the ``is_comparison`` parameter is superseded by using the
| :meth:`.Operators.bool_op` method instead; this more succinct
| operator sets this parameter automatically, but also provides
| correct :pep:`484` typing support as the returned object will
| express a "boolean" datatype, i.e. ``BinaryExpression[bool]``.
|
| :param return_type: a :class:`.TypeEngine` class or object that will
| force the return type of an expression produced by this operator
| to be of that type. By default, operators that specify
| :paramref:`.Operators.op.is_comparison` will resolve to
| :class:`.Boolean`, and those that do not will be of the same
| type as the left-hand operand.
|
| :param python_impl: an optional Python function that can evaluate
| two Python values in the same way as this operator works when
| run on the database server. Useful for in-Python SQL expression
| evaluation functions, such as for ORM hybrid attributes, and the
| ORM "evaluator" used to match objects in a session after a multi-row
| update or delete.
|
| e.g.::
|
| >>> expr = column("x").op("+", python_impl=lambda a, b: a + b)("y")
|
| The operator for the above expression will also work for non-SQL
| left and right objects::
|
| >>> expr.operator(5, 10)
| 15
|
| .. versionadded:: 2.0
|
|
| .. seealso::
|
| :meth:`.Operators.bool_op`
|
| :ref:`types_operators`
|
| :ref:`relationship_custom_operator`
|
| ----------------------------------------------------------------------
| Methods inherited from ClauseElement:
|
| __bool__(self)
|
| __getstate__(self)
| Helper for pickle.
|
| __repr__(self)
| Return repr(self).
|
| compare(self, other: 'ClauseElement', **kw: 'Any') -> 'bool'
| Compare this :class:`_expression.ClauseElement` to
| the given :class:`_expression.ClauseElement`.
|
| Subclasses should override the default behavior, which is a
| straight identity comparison.
|
| \**kw are arguments consumed by subclass ``compare()`` methods and
| may be used to modify the criteria for comparison
| (see :class:`_expression.ColumnElement`).
|
| description(...)
|
| entity_namespace(...)
|
| params(self, _ClauseElement__optionaldict: 'Optional[Mapping[str, Any]]' = None, **kwargs: 'Any') -> 'Self'
| Return a copy with :func:`_expression.bindparam` elements
| replaced.
|
| Returns a copy of this ClauseElement with
| :func:`_expression.bindparam`
| elements replaced with values taken from the given dictionary::
|
| >>> clause = column("x") + bindparam("foo")
| >>> print(clause.compile().params)
| {'foo':None}
| >>> print(clause.params({"foo": 7}).compile().params)
| {'foo':7}
|
| unique_params(self, _ClauseElement__optionaldict: 'Optional[Dict[str, Any]]' = None, **kwargs: 'Any') -> 'Self'
| Return a copy with :func:`_expression.bindparam` elements
| replaced.
|
| Same functionality as :meth:`_expression.ClauseElement.params`,
| except adds `unique=True`
| to affected bind parameters so that multiple statements can be
| used.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from ClauseElement:
|
| is_clause_element = True
|
| is_dml = False
|
| is_selectable = False
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.cache_key.HasCacheKey:
|
| inherit_cache = None
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_instancemethod(fn: '_F') -> '_F'
| Decorate a method memoize its return value.
|
| :meta private:
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_attribute = <class 'sqlalchemy.util.langhelpers.HasMemoized.m...
| A read-only @property that is only evaluated once.
|
| :meta private:
|
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.visitors.HasTraverseInternals:
|
| get_children(self, *, omit_attrs: 'Tuple[str, ...]' = (), **kw: 'Any') -> 'Iterable[HasTraverseInternals]'
| Return immediate child :class:`.visitors.HasTraverseInternals`
| elements of this :class:`.visitors.HasTraverseInternals`.
|
| This is used for visit traversal.
|
| \**kw may contain flags that change the collection that is
| returned, for example to return a subset of items in order to
| cut down on larger traversals, or to return child items from a
| different context (such as schema-level collections instead of
| clause-level).
|
| ----------------------------------------------------------------------
| Methods inherited from CompilerElement:
|
| __str__(self) -> 'str'
| Return str(self).
|
| compile(self, bind: 'Optional[_HasDialect]' = None, dialect: 'Optional[Dialect]' = None, **kw: 'Any') -> 'Compiled'
| Compile this SQL expression.
|
| The return value is a :class:`~.Compiled` object.
| Calling ``str()`` or ``unicode()`` on the returned value will yield a
| string representation of the result. The
| :class:`~.Compiled` object also can return a
| dictionary of bind parameter names and values
| using the ``params`` accessor.
|
| :param bind: An :class:`.Connection` or :class:`.Engine` which
| can provide a :class:`.Dialect` in order to generate a
| :class:`.Compiled` object. If the ``bind`` and
| ``dialect`` parameters are both omitted, a default SQL compiler
| is used.
|
| :param column_keys: Used for INSERT and UPDATE statements, a list of
| column names which should be present in the VALUES clause of the
| compiled statement. If ``None``, all columns from the target table
| object are rendered.
|
| :param dialect: A :class:`.Dialect` instance which can generate
| a :class:`.Compiled` object. This argument takes precedence over
| the ``bind`` argument.
|
| :param compile_kwargs: optional dictionary of additional parameters
| that will be passed through to the compiler within all "visit"
| methods. This allows any custom flag to be passed through to
| a custom compilation construct, for example. It is also used
| for the case of passing the ``literal_binds`` flag through::
|
| from sqlalchemy.sql import table, column, select
|
| t = table("t", column("x"))
|
| s = select(t).where(t.c.x == 5)
|
| print(s.compile(compile_kwargs={"literal_binds": True}))
|
| .. seealso::
|
| :ref:`faq_sql_expression_string`
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from CompilerElement:
|
| stringify_dialect = 'default'
|
| supports_execution = False
sqlalchemy.Unicode
Python Library Documentation: class Unicode in module sqlalchemy.sql.sqltypes
class Unicode(String)
| Unicode(length: 'Optional[int]' = None, collation: 'Optional[str]' = None)
|
| A variable length Unicode string type.
|
| The :class:`.Unicode` type is a :class:`.String` subclass that assumes
| input and output strings that may contain non-ASCII characters, and for
| some backends implies an underlying column type that is explicitly
| supporting of non-ASCII data, such as ``NVARCHAR`` on Oracle Database and
| SQL Server. This will impact the output of ``CREATE TABLE`` statements and
| ``CAST`` functions at the dialect level.
|
| The character encoding used by the :class:`.Unicode` type that is used to
| transmit and receive data to the database is usually determined by the
| DBAPI itself. All modern DBAPIs accommodate non-ASCII strings but may have
| different methods of managing database encodings; if necessary, this
| encoding should be configured as detailed in the notes for the target DBAPI
| in the :ref:`dialect_toplevel` section.
|
| In modern SQLAlchemy, use of the :class:`.Unicode` datatype does not
| imply any encoding/decoding behavior within SQLAlchemy itself. In Python
| 3, all string objects are inherently Unicode capable, and SQLAlchemy
| does not produce bytestring objects nor does it accommodate a DBAPI that
| does not return Python Unicode objects in result sets for string values.
|
| .. warning:: Some database backends, particularly SQL Server with pyodbc,
| are known to have undesirable behaviors regarding data that is noted
| as being of ``NVARCHAR`` type as opposed to ``VARCHAR``, including
| datatype mismatch errors and non-use of indexes. See the section
| on :meth:`.DialectEvents.do_setinputsizes` for background on working
| around unicode character issues for backends like SQL Server with
| pyodbc as well as cx_Oracle.
|
| .. seealso::
|
| :class:`.UnicodeText` - unlengthed textual counterpart
| to :class:`.Unicode`.
|
| :meth:`.DialectEvents.do_setinputsizes`
|
| Method resolution order:
| Unicode
| String
| Concatenable
| sqlalchemy.sql.type_api.TypeEngineMixin
| sqlalchemy.sql.type_api.TypeEngine
| sqlalchemy.sql.visitors.Visitable
| typing.Generic
| builtins.object
|
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| __parameters__ = ()
|
| __visit_name__ = 'unicode'
|
| ----------------------------------------------------------------------
| Methods inherited from String:
|
| __init__(self, length: 'Optional[int]' = None, collation: 'Optional[str]' = None)
| Create a string-holding type.
|
| :param length: optional, a length for the column for use in
| DDL and CAST expressions. May be safely omitted if no ``CREATE
| TABLE`` will be issued. Certain databases may require a
| ``length`` for use in DDL, and will raise an exception when
| the ``CREATE TABLE`` DDL is issued if a ``VARCHAR``
| with no length is included. Whether the value is
| interpreted as bytes or characters is database specific.
|
| :param collation: Optional, a column-level collation for
| use in DDL and CAST expressions. Renders using the
| COLLATE keyword supported by SQLite, MySQL, and PostgreSQL.
| E.g.:
|
| .. sourcecode:: pycon+sql
|
| >>> from sqlalchemy import cast, select, String
| >>> print(select(cast("some string", String(collation="utf8"))))
| {printsql}SELECT CAST(:param_1 AS VARCHAR COLLATE utf8) AS anon_1
|
| .. note::
|
| In most cases, the :class:`.Unicode` or :class:`.UnicodeText`
| datatypes should be used for a :class:`_schema.Column` that expects
| to store non-ascii data. These datatypes will ensure that the
| correct types are used on the database.
|
| bind_processor(self, dialect: 'Dialect') -> 'Optional[_BindProcessorType[str]]'
| Return a conversion function for processing bind values.
|
| Returns a callable which will receive a bind parameter value
| as the sole positional argument and will return a value to
| send to the DB-API.
|
| If processing is not necessary, the method should return ``None``.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.bind_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.bind_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_bind_param`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
|
| :param dialect: Dialect instance in use.
|
| get_dbapi_type(self, dbapi)
| Return the corresponding type object from the underlying DB-API, if
| any.
|
| This can be useful for calling ``setinputsizes()``, for example.
|
| literal_processor(self, dialect)
| Return a conversion function for processing literal values that are
| to be rendered directly without using binds.
|
| This function is used when the compiler makes use of the
| "literal_binds" flag, typically used in DDL generation as well
| as in certain scenarios where backends don't accept bound parameters.
|
| Returns a callable which will receive a literal Python value
| as the sole positional argument and will return a string representation
| to be rendered in a SQL statement.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.literal_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.literal_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_literal_param`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| result_processor(self, dialect: 'Dialect', coltype: 'object') -> 'Optional[_ResultProcessorType[str]]'
| Return a conversion function for processing result row values.
|
| Returns a callable which will receive a result row column
| value as the sole positional argument and will return a value
| to return to the user.
|
| If processing is not necessary, the method should return ``None``.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.result_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.result_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_result_value`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| :param dialect: Dialect instance in use.
|
| :param coltype: DBAPI coltype argument received in cursor.description.
|
| ----------------------------------------------------------------------
| Readonly properties inherited from String:
|
| python_type
| Return the Python type object expected to be returned
| by instances of this type, if known.
|
| Basically, for those types which enforce a return type,
| or are known across the board to do such for all common
| DBAPIs (like ``int`` for example), will return that type.
|
| If a return type is not defined, raises
| ``NotImplementedError``.
|
| Note that any type also accommodates NULL in SQL which
| means you can also get back ``None`` from any type
| in practice.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from Concatenable:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from Concatenable:
|
| Comparator = <class 'sqlalchemy.sql.sqltypes.Concatenable.Comparator'>
|
| comparator_factory = <class 'sqlalchemy.sql.sqltypes.Concatenable.Comp...
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.type_api.TypeEngine:
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| __str__(self) -> 'str'
| Return str(self).
|
| adapt(self, cls: 'Type[Union[TypeEngine[Any], TypeEngineMixin]]', **kw: 'Any') -> 'TypeEngine[Any]'
| Produce an "adapted" form of this type, given an "impl" class
| to work with.
|
| This method is used internally to associate generic
| types with "implementation" types that are specific to a particular
| dialect.
|
| as_generic(self, allow_nulltype: 'bool' = False) -> 'TypeEngine[_T]'
| Return an instance of the generic type corresponding to this type
| using heuristic rule. The method may be overridden if this
| heuristic rule is not sufficient.
|
| >>> from sqlalchemy.dialects.mysql import INTEGER
| >>> INTEGER(display_width=4).as_generic()
| Integer()
|
| >>> from sqlalchemy.dialects.mysql import NVARCHAR
| >>> NVARCHAR(length=100).as_generic()
| Unicode(length=100)
|
| .. versionadded:: 1.4.0b2
|
|
| .. seealso::
|
| :ref:`metadata_reflection_dbagnostic_types` - describes the
| use of :meth:`_types.TypeEngine.as_generic` in conjunction with
| the :meth:`_sql.DDLEvents.column_reflect` event, which is its
| intended use.
|
| bind_expression(self, bindvalue: 'BindParameter[_T]') -> 'Optional[ColumnElement[_T]]'
| Given a bind value (i.e. a :class:`.BindParameter` instance),
| return a SQL expression in its place.
|
| This is typically a SQL function that wraps the existing bound
| parameter within the statement. It is used for special data types
| that require literals being wrapped in some special database function
| in order to coerce an application-level value into a database-specific
| format. It is the SQL analogue of the
| :meth:`.TypeEngine.bind_processor` method.
|
| This method is called during the **SQL compilation** phase of a
| statement, when rendering a SQL string. It is **not** called
| against specific values.
|
| Note that this method, when implemented, should always return
| the exact same structure, without any conditional logic, as it
| may be used in an executemany() call against an arbitrary number
| of bound parameter sets.
|
| .. note::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.bind_expression`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.bind_expression`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.bind_expression`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| .. seealso::
|
| :ref:`types_sql_value_processing`
|
| coerce_compared_value(self, op: 'Optional[OperatorType]', value: 'Any') -> 'TypeEngine[Any]'
| Suggest a type for a 'coerced' Python value in an expression.
|
| Given an operator and value, gives the type a chance
| to return a type which the value should be coerced into.
|
| The default behavior here is conservative; if the right-hand
| side is already coerced into a SQL type based on its
| Python type, it is usually left alone.
|
| End-user functionality extension here should generally be via
| :class:`.TypeDecorator`, which provides more liberal behavior in that
| it defaults to coercing the other side of the expression into this
| type, thus applying special Python conversions above and beyond those
| needed by the DBAPI to both ides. It also provides the public method
| :meth:`.TypeDecorator.coerce_compared_value` which is intended for
| end-user customization of this behavior.
|
| column_expression(self, colexpr: 'ColumnElement[_T]') -> 'Optional[ColumnElement[_T]]'
| Given a SELECT column expression, return a wrapping SQL expression.
|
| This is typically a SQL function that wraps a column expression
| as rendered in the columns clause of a SELECT statement.
| It is used for special data types that require
| columns to be wrapped in some special database function in order
| to coerce the value before being sent back to the application.
| It is the SQL analogue of the :meth:`.TypeEngine.result_processor`
| method.
|
| .. note:: The :func:`.TypeEngine.column_expression` method is applied
| only to the **outermost columns clause** of a SELECT statement, that
| is, the columns that are to be delivered directly into the returned
| result rows. It does **not** apply to the columns clause inside
| of subqueries. This necessarily avoids double conversions against
| the column and only runs the conversion when ready to be returned
| to the client.
|
| This method is called during the **SQL compilation** phase of a
| statement, when rendering a SQL string. It is **not** called
| against specific values.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.column_expression`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.column_expression`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.column_expression`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
|
| .. seealso::
|
| :ref:`types_sql_value_processing`
|
| compare_values(self, x: 'Any', y: 'Any') -> 'bool'
| Compare two values for equality.
|
| compile(self, dialect: 'Optional[Dialect]' = None) -> 'str'
| Produce a string-compiled form of this :class:`.TypeEngine`.
|
| When called with no arguments, uses a "default" dialect
| to produce a string result.
|
| :param dialect: a :class:`.Dialect` instance.
|
| copy(self, **kw: 'Any') -> 'Self'
|
| copy_value(self, value: 'Any') -> 'Any'
|
| dialect_impl(self, dialect: 'Dialect') -> 'TypeEngine[_T]'
| Return a dialect-specific implementation for this
| :class:`.TypeEngine`.
|
| evaluates_none(self) -> 'Self'
| Return a copy of this type which has the
| :attr:`.should_evaluate_none` flag set to True.
|
| E.g.::
|
| Table(
| "some_table",
| metadata,
| Column(
| String(50).evaluates_none(),
| nullable=True,
| server_default="no value",
| ),
| )
|
| The ORM uses this flag to indicate that a positive value of ``None``
| is passed to the column in an INSERT statement, rather than omitting
| the column from the INSERT statement which has the effect of firing
| off column-level defaults. It also allows for types which have
| special behavior associated with the Python None value to indicate
| that the value doesn't necessarily translate into SQL NULL; a
| prime example of this is a JSON type which may wish to persist the
| JSON value ``'null'``.
|
| In all cases, the actual NULL SQL value can be always be
| persisted in any column by using
| the :obj:`_expression.null` SQL construct in an INSERT statement
| or associated with an ORM-mapped attribute.
|
| .. note::
|
| The "evaluates none" flag does **not** apply to a value
| of ``None`` passed to :paramref:`_schema.Column.default` or
| :paramref:`_schema.Column.server_default`; in these cases,
| ``None``
| still means "no default".
|
| .. seealso::
|
| :ref:`session_forcing_null` - in the ORM documentation
|
| :paramref:`.postgresql.JSON.none_as_null` - PostgreSQL JSON
| interaction with this flag.
|
| :attr:`.TypeEngine.should_evaluate_none` - class-level flag
|
| with_variant(self, type_: '_TypeEngineArgument[Any]', *dialect_names: 'str') -> 'Self'
| Produce a copy of this type object that will utilize the given
| type when applied to the dialect of the given name.
|
| e.g.::
|
| from sqlalchemy.types import String
| from sqlalchemy.dialects import mysql
|
| string_type = String()
|
| string_type = string_type.with_variant(
| mysql.VARCHAR(collation="foo"), "mysql", "mariadb"
| )
|
| The variant mapping indicates that when this type is
| interpreted by a specific dialect, it will instead be
| transmuted into the given type, rather than using the
| primary type.
|
| .. versionchanged:: 2.0 the :meth:`_types.TypeEngine.with_variant`
| method now works with a :class:`_types.TypeEngine` object "in
| place", returning a copy of the original type rather than returning
| a wrapping object; the ``Variant`` class is no longer used.
|
| :param type\_: a :class:`.TypeEngine` that will be selected
| as a variant from the originating type, when a dialect
| of the given name is in use.
| :param \*dialect_names: one or more base names of the dialect which
| uses this type. (i.e. ``'postgresql'``, ``'mysql'``, etc.)
|
| .. versionchanged:: 2.0 multiple dialect names can be specified
| for one variant.
|
| .. seealso::
|
| :ref:`types_with_variant` - illustrates the use of
| :meth:`_types.TypeEngine.with_variant`.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.type_api.TypeEngine:
|
| __orig_bases__ = (<class 'sqlalchemy.sql.visitors.Visitable'>, typing....
|
| hashable = True
|
| render_bind_cast = False
|
| render_literal_cast = False
|
| should_evaluate_none = False
|
| sort_key_function = None
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.visitors.Visitable:
|
| __class_getitem__(key: 'Any') -> 'Any'
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__() -> 'None'
| This method is called when a class is subclassed.
|
| The default implementation does nothing. It may be
| overridden to extend subclasses.
sqlalchemy.UnicodeText
Python Library Documentation: class UnicodeText in module sqlalchemy.sql.sqltypes
class UnicodeText(Text)
| UnicodeText(length: 'Optional[int]' = None, collation: 'Optional[str]' = None)
|
| An unbounded-length Unicode string type.
|
| See :class:`.Unicode` for details on the unicode
| behavior of this object.
|
| Like :class:`.Unicode`, usage the :class:`.UnicodeText` type implies a
| unicode-capable type being used on the backend, such as
| ``NCLOB``, ``NTEXT``.
|
| Method resolution order:
| UnicodeText
| Text
| String
| Concatenable
| sqlalchemy.sql.type_api.TypeEngineMixin
| sqlalchemy.sql.type_api.TypeEngine
| sqlalchemy.sql.visitors.Visitable
| typing.Generic
| builtins.object
|
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| __parameters__ = ()
|
| __visit_name__ = 'unicode_text'
|
| ----------------------------------------------------------------------
| Methods inherited from String:
|
| __init__(self, length: 'Optional[int]' = None, collation: 'Optional[str]' = None)
| Create a string-holding type.
|
| :param length: optional, a length for the column for use in
| DDL and CAST expressions. May be safely omitted if no ``CREATE
| TABLE`` will be issued. Certain databases may require a
| ``length`` for use in DDL, and will raise an exception when
| the ``CREATE TABLE`` DDL is issued if a ``VARCHAR``
| with no length is included. Whether the value is
| interpreted as bytes or characters is database specific.
|
| :param collation: Optional, a column-level collation for
| use in DDL and CAST expressions. Renders using the
| COLLATE keyword supported by SQLite, MySQL, and PostgreSQL.
| E.g.:
|
| .. sourcecode:: pycon+sql
|
| >>> from sqlalchemy import cast, select, String
| >>> print(select(cast("some string", String(collation="utf8"))))
| {printsql}SELECT CAST(:param_1 AS VARCHAR COLLATE utf8) AS anon_1
|
| .. note::
|
| In most cases, the :class:`.Unicode` or :class:`.UnicodeText`
| datatypes should be used for a :class:`_schema.Column` that expects
| to store non-ascii data. These datatypes will ensure that the
| correct types are used on the database.
|
| bind_processor(self, dialect: 'Dialect') -> 'Optional[_BindProcessorType[str]]'
| Return a conversion function for processing bind values.
|
| Returns a callable which will receive a bind parameter value
| as the sole positional argument and will return a value to
| send to the DB-API.
|
| If processing is not necessary, the method should return ``None``.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.bind_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.bind_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_bind_param`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
|
| :param dialect: Dialect instance in use.
|
| get_dbapi_type(self, dbapi)
| Return the corresponding type object from the underlying DB-API, if
| any.
|
| This can be useful for calling ``setinputsizes()``, for example.
|
| literal_processor(self, dialect)
| Return a conversion function for processing literal values that are
| to be rendered directly without using binds.
|
| This function is used when the compiler makes use of the
| "literal_binds" flag, typically used in DDL generation as well
| as in certain scenarios where backends don't accept bound parameters.
|
| Returns a callable which will receive a literal Python value
| as the sole positional argument and will return a string representation
| to be rendered in a SQL statement.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.literal_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.literal_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_literal_param`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| result_processor(self, dialect: 'Dialect', coltype: 'object') -> 'Optional[_ResultProcessorType[str]]'
| Return a conversion function for processing result row values.
|
| Returns a callable which will receive a result row column
| value as the sole positional argument and will return a value
| to return to the user.
|
| If processing is not necessary, the method should return ``None``.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.result_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.result_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_result_value`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| :param dialect: Dialect instance in use.
|
| :param coltype: DBAPI coltype argument received in cursor.description.
|
| ----------------------------------------------------------------------
| Readonly properties inherited from String:
|
| python_type
| Return the Python type object expected to be returned
| by instances of this type, if known.
|
| Basically, for those types which enforce a return type,
| or are known across the board to do such for all common
| DBAPIs (like ``int`` for example), will return that type.
|
| If a return type is not defined, raises
| ``NotImplementedError``.
|
| Note that any type also accommodates NULL in SQL which
| means you can also get back ``None`` from any type
| in practice.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from Concatenable:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from Concatenable:
|
| Comparator = <class 'sqlalchemy.sql.sqltypes.Concatenable.Comparator'>
|
| comparator_factory = <class 'sqlalchemy.sql.sqltypes.Concatenable.Comp...
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.type_api.TypeEngine:
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| __str__(self) -> 'str'
| Return str(self).
|
| adapt(self, cls: 'Type[Union[TypeEngine[Any], TypeEngineMixin]]', **kw: 'Any') -> 'TypeEngine[Any]'
| Produce an "adapted" form of this type, given an "impl" class
| to work with.
|
| This method is used internally to associate generic
| types with "implementation" types that are specific to a particular
| dialect.
|
| as_generic(self, allow_nulltype: 'bool' = False) -> 'TypeEngine[_T]'
| Return an instance of the generic type corresponding to this type
| using heuristic rule. The method may be overridden if this
| heuristic rule is not sufficient.
|
| >>> from sqlalchemy.dialects.mysql import INTEGER
| >>> INTEGER(display_width=4).as_generic()
| Integer()
|
| >>> from sqlalchemy.dialects.mysql import NVARCHAR
| >>> NVARCHAR(length=100).as_generic()
| Unicode(length=100)
|
| .. versionadded:: 1.4.0b2
|
|
| .. seealso::
|
| :ref:`metadata_reflection_dbagnostic_types` - describes the
| use of :meth:`_types.TypeEngine.as_generic` in conjunction with
| the :meth:`_sql.DDLEvents.column_reflect` event, which is its
| intended use.
|
| bind_expression(self, bindvalue: 'BindParameter[_T]') -> 'Optional[ColumnElement[_T]]'
| Given a bind value (i.e. a :class:`.BindParameter` instance),
| return a SQL expression in its place.
|
| This is typically a SQL function that wraps the existing bound
| parameter within the statement. It is used for special data types
| that require literals being wrapped in some special database function
| in order to coerce an application-level value into a database-specific
| format. It is the SQL analogue of the
| :meth:`.TypeEngine.bind_processor` method.
|
| This method is called during the **SQL compilation** phase of a
| statement, when rendering a SQL string. It is **not** called
| against specific values.
|
| Note that this method, when implemented, should always return
| the exact same structure, without any conditional logic, as it
| may be used in an executemany() call against an arbitrary number
| of bound parameter sets.
|
| .. note::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.bind_expression`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.bind_expression`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.bind_expression`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| .. seealso::
|
| :ref:`types_sql_value_processing`
|
| coerce_compared_value(self, op: 'Optional[OperatorType]', value: 'Any') -> 'TypeEngine[Any]'
| Suggest a type for a 'coerced' Python value in an expression.
|
| Given an operator and value, gives the type a chance
| to return a type which the value should be coerced into.
|
| The default behavior here is conservative; if the right-hand
| side is already coerced into a SQL type based on its
| Python type, it is usually left alone.
|
| End-user functionality extension here should generally be via
| :class:`.TypeDecorator`, which provides more liberal behavior in that
| it defaults to coercing the other side of the expression into this
| type, thus applying special Python conversions above and beyond those
| needed by the DBAPI to both ides. It also provides the public method
| :meth:`.TypeDecorator.coerce_compared_value` which is intended for
| end-user customization of this behavior.
|
| column_expression(self, colexpr: 'ColumnElement[_T]') -> 'Optional[ColumnElement[_T]]'
| Given a SELECT column expression, return a wrapping SQL expression.
|
| This is typically a SQL function that wraps a column expression
| as rendered in the columns clause of a SELECT statement.
| It is used for special data types that require
| columns to be wrapped in some special database function in order
| to coerce the value before being sent back to the application.
| It is the SQL analogue of the :meth:`.TypeEngine.result_processor`
| method.
|
| .. note:: The :func:`.TypeEngine.column_expression` method is applied
| only to the **outermost columns clause** of a SELECT statement, that
| is, the columns that are to be delivered directly into the returned
| result rows. It does **not** apply to the columns clause inside
| of subqueries. This necessarily avoids double conversions against
| the column and only runs the conversion when ready to be returned
| to the client.
|
| This method is called during the **SQL compilation** phase of a
| statement, when rendering a SQL string. It is **not** called
| against specific values.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.column_expression`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.column_expression`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.column_expression`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
|
| .. seealso::
|
| :ref:`types_sql_value_processing`
|
| compare_values(self, x: 'Any', y: 'Any') -> 'bool'
| Compare two values for equality.
|
| compile(self, dialect: 'Optional[Dialect]' = None) -> 'str'
| Produce a string-compiled form of this :class:`.TypeEngine`.
|
| When called with no arguments, uses a "default" dialect
| to produce a string result.
|
| :param dialect: a :class:`.Dialect` instance.
|
| copy(self, **kw: 'Any') -> 'Self'
|
| copy_value(self, value: 'Any') -> 'Any'
|
| dialect_impl(self, dialect: 'Dialect') -> 'TypeEngine[_T]'
| Return a dialect-specific implementation for this
| :class:`.TypeEngine`.
|
| evaluates_none(self) -> 'Self'
| Return a copy of this type which has the
| :attr:`.should_evaluate_none` flag set to True.
|
| E.g.::
|
| Table(
| "some_table",
| metadata,
| Column(
| String(50).evaluates_none(),
| nullable=True,
| server_default="no value",
| ),
| )
|
| The ORM uses this flag to indicate that a positive value of ``None``
| is passed to the column in an INSERT statement, rather than omitting
| the column from the INSERT statement which has the effect of firing
| off column-level defaults. It also allows for types which have
| special behavior associated with the Python None value to indicate
| that the value doesn't necessarily translate into SQL NULL; a
| prime example of this is a JSON type which may wish to persist the
| JSON value ``'null'``.
|
| In all cases, the actual NULL SQL value can be always be
| persisted in any column by using
| the :obj:`_expression.null` SQL construct in an INSERT statement
| or associated with an ORM-mapped attribute.
|
| .. note::
|
| The "evaluates none" flag does **not** apply to a value
| of ``None`` passed to :paramref:`_schema.Column.default` or
| :paramref:`_schema.Column.server_default`; in these cases,
| ``None``
| still means "no default".
|
| .. seealso::
|
| :ref:`session_forcing_null` - in the ORM documentation
|
| :paramref:`.postgresql.JSON.none_as_null` - PostgreSQL JSON
| interaction with this flag.
|
| :attr:`.TypeEngine.should_evaluate_none` - class-level flag
|
| with_variant(self, type_: '_TypeEngineArgument[Any]', *dialect_names: 'str') -> 'Self'
| Produce a copy of this type object that will utilize the given
| type when applied to the dialect of the given name.
|
| e.g.::
|
| from sqlalchemy.types import String
| from sqlalchemy.dialects import mysql
|
| string_type = String()
|
| string_type = string_type.with_variant(
| mysql.VARCHAR(collation="foo"), "mysql", "mariadb"
| )
|
| The variant mapping indicates that when this type is
| interpreted by a specific dialect, it will instead be
| transmuted into the given type, rather than using the
| primary type.
|
| .. versionchanged:: 2.0 the :meth:`_types.TypeEngine.with_variant`
| method now works with a :class:`_types.TypeEngine` object "in
| place", returning a copy of the original type rather than returning
| a wrapping object; the ``Variant`` class is no longer used.
|
| :param type\_: a :class:`.TypeEngine` that will be selected
| as a variant from the originating type, when a dialect
| of the given name is in use.
| :param \*dialect_names: one or more base names of the dialect which
| uses this type. (i.e. ``'postgresql'``, ``'mysql'``, etc.)
|
| .. versionchanged:: 2.0 multiple dialect names can be specified
| for one variant.
|
| .. seealso::
|
| :ref:`types_with_variant` - illustrates the use of
| :meth:`_types.TypeEngine.with_variant`.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.type_api.TypeEngine:
|
| __orig_bases__ = (<class 'sqlalchemy.sql.visitors.Visitable'>, typing....
|
| hashable = True
|
| render_bind_cast = False
|
| render_literal_cast = False
|
| should_evaluate_none = False
|
| sort_key_function = None
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.visitors.Visitable:
|
| __class_getitem__(key: 'Any') -> 'Any'
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__() -> 'None'
| This method is called when a class is subclassed.
|
| The default implementation does nothing. It may be
| overridden to extend subclasses.
sqlalchemy.UniqueConstraint
Python Library Documentation: class UniqueConstraint in module sqlalchemy.sql.schema
class UniqueConstraint(ColumnCollectionConstraint)
| UniqueConstraint(*columns: '_DDLColumnArgument', name: '_ConstraintNameArgument' = None, deferrable: 'Optional[bool]' = None, initially: 'Optional[str]' = None, info: 'Optional[_InfoType]' = None, _autoattach: 'bool' = True, _column_flag: 'bool' = False, _gather_expressions: 'Optional[List[_DDLColumnArgument]]' = None, **dialect_kw: 'Any') -> 'None'
|
| A table-level UNIQUE constraint.
|
| Defines a single column or composite UNIQUE constraint. For a no-frills,
| single column constraint, adding ``unique=True`` to the ``Column``
| definition is a shorthand equivalent for an unnamed, single column
| UniqueConstraint.
|
| Method resolution order:
| UniqueConstraint
| ColumnCollectionConstraint
| ColumnCollectionMixin
| Constraint
| sqlalchemy.sql.base.DialectKWArgs
| HasConditionalDDL
| SchemaItem
| sqlalchemy.sql.base.SchemaVisitable
| sqlalchemy.sql.base.SchemaEventTarget
| sqlalchemy.event.registry.EventTarget
| sqlalchemy.sql.visitors.Visitable
| builtins.object
|
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| __visit_name__ = 'unique_constraint'
|
| ----------------------------------------------------------------------
| Methods inherited from ColumnCollectionConstraint:
|
| __contains__(self, x: 'Any') -> 'bool'
|
| __init__(self, *columns: '_DDLColumnArgument', name: '_ConstraintNameArgument' = None, deferrable: 'Optional[bool]' = None, initially: 'Optional[str]' = None, info: 'Optional[_InfoType]' = None, _autoattach: 'bool' = True, _column_flag: 'bool' = False, _gather_expressions: 'Optional[List[_DDLColumnArgument]]' = None, **dialect_kw: 'Any') -> 'None'
| :param \*columns:
| A sequence of column names or Column objects.
|
| :param name:
| Optional, the in-database name of this constraint.
|
| :param deferrable:
| Optional bool. If set, emit DEFERRABLE or NOT DEFERRABLE when
| issuing DDL for this constraint.
|
| :param initially:
| Optional string. If set, emit INITIALLY <value> when issuing DDL
| for this constraint.
|
| :param \**dialect_kw: other keyword arguments including
| dialect-specific arguments are propagated to the :class:`.Constraint`
| superclass.
|
| __iter__(self) -> 'Iterator[Column[Any]]'
|
| __len__(self) -> 'int'
|
| contains_column(self, col: 'Column[Any]') -> 'bool'
| Return True if this constraint contains the given column.
|
| Note that this object also contains an attribute ``.columns``
| which is a :class:`_expression.ColumnCollection` of
| :class:`_schema.Column` objects.
|
| copy(self, *, target_table: 'Optional[Table]' = None, **kw: 'Any') -> 'ColumnCollectionConstraint'
| .. deprecated:: 1.4 The :meth:`_schema.ColumnCollectionConstraint.copy` method is deprecated and will be removed in a future release.
|
| ----------------------------------------------------------------------
| Methods inherited from ColumnCollectionMixin:
|
| c(...)
|
| columns(...)
|
| ----------------------------------------------------------------------
| Data descriptors inherited from ColumnCollectionMixin:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Readonly properties inherited from Constraint:
|
| table
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.base.DialectKWArgs:
|
| dialect_options(...)
| A collection of keyword arguments specified as dialect-specific
| options to this construct.
|
| This is a two-level nested registry, keyed to ``<dialect_name>``
| and ``<argument_name>``. For example, the ``postgresql_where``
| argument would be locatable as::
|
| arg = my_object.dialect_options["postgresql"]["where"]
|
| .. versionadded:: 0.9.2
|
| .. seealso::
|
| :attr:`.DialectKWArgs.dialect_kwargs` - flat dictionary form
|
| get_dialect_option(self, dialect: 'Dialect', argument_name: 'str', *, else_: 'Any' = None, deprecated_fallback: 'Optional[str]' = None) -> 'Any'
| Return the value of a dialect-specific option, or *else_* if
| this dialect does not register the given argument.
|
| This is useful for DDL compilers that may be inherited by
| third-party dialects whose ``construct_arguments`` do not
| include the same set of keys as the parent dialect.
|
| :param dialect: The dialect for which to retrieve the option.
| :param argument_name: The name of the argument to retrieve.
| :param else\_: The value to return if the argument is not present.
| :param deprecated_fallback: Optional dialect name to fall back to
| if the argument is not present for the current dialect. If the
| argument is present for the fallback dialect but not the current
| dialect, a deprecation warning will be emitted.
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.base.DialectKWArgs:
|
| argument_for(dialect_name: 'str', argument_name: 'str', default: 'Any') -> 'None'
| Add a new kind of dialect-specific keyword argument for this class.
|
| E.g.::
|
| Index.argument_for("mydialect", "length", None)
|
| some_index = Index("a", "b", mydialect_length=5)
|
| The :meth:`.DialectKWArgs.argument_for` method is a per-argument
| way adding extra arguments to the
| :attr:`.DefaultDialect.construct_arguments` dictionary. This
| dictionary provides a list of argument names accepted by various
| schema-level constructs on behalf of a dialect.
|
| New dialects should typically specify this dictionary all at once as a
| data member of the dialect class. The use case for ad-hoc addition of
| argument names is typically for end-user code that is also using
| a custom compilation scheme which consumes the additional arguments.
|
| :param dialect_name: name of a dialect. The dialect must be
| locatable, else a :class:`.NoSuchModuleError` is raised. The
| dialect must also include an existing
| :attr:`.DefaultDialect.construct_arguments` collection, indicating
| that it participates in the keyword-argument validation and default
| system, else :class:`.ArgumentError` is raised. If the dialect does
| not include this collection, then any keyword argument can be
| specified on behalf of this dialect already. All dialects packaged
| within SQLAlchemy include this collection, however for third party
| dialects, support may vary.
|
| :param argument_name: name of the parameter.
|
| :param default: default value of the parameter.
|
| ----------------------------------------------------------------------
| Readonly properties inherited from sqlalchemy.sql.base.DialectKWArgs:
|
| dialect_kwargs
| A collection of keyword arguments specified as dialect-specific
| options to this construct.
|
| The arguments are present here in their original ``<dialect>_<kwarg>``
| format. Only arguments that were actually passed are included;
| unlike the :attr:`.DialectKWArgs.dialect_options` collection, which
| contains all options known by this dialect including defaults.
|
| The collection is also writable; keys are accepted of the
| form ``<dialect>_<kwarg>`` where the value will be assembled
| into the list of options.
|
| .. seealso::
|
| :attr:`.DialectKWArgs.dialect_options` - nested dictionary form
|
| kwargs
| A synonym for :attr:`.DialectKWArgs.dialect_kwargs`.
|
| ----------------------------------------------------------------------
| Methods inherited from HasConditionalDDL:
|
| ddl_if(self, dialect: 'Optional[str]' = None, callable_: 'Optional[ddl.DDLIfCallable]' = None, state: 'Optional[Any]' = None) -> 'Self'
| apply a conditional DDL rule to this schema item.
|
| These rules work in a similar manner to the
| :meth:`.ExecutableDDLElement.execute_if` callable, with the added
| feature that the criteria may be checked within the DDL compilation
| phase for a construct such as :class:`.CreateTable`.
| :meth:`.HasConditionalDDL.ddl_if` currently applies towards the
| :class:`.Index` construct as well as all :class:`.Constraint`
| constructs.
|
| :param dialect: string name of a dialect, or a tuple of string names
| to indicate multiple dialect types.
|
| :param callable\_: a callable that is constructed using the same form
| as that described in
| :paramref:`.ExecutableDDLElement.execute_if.callable_`.
|
| :param state: any arbitrary object that will be passed to the
| callable, if present.
|
| .. versionadded:: 2.0
|
| .. seealso::
|
| :ref:`schema_ddl_ddl_if` - background and usage examples
|
| ----------------------------------------------------------------------
| Methods inherited from SchemaItem:
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| info(...)
| Info dictionary associated with the object, allowing user-defined
| data to be associated with this :class:`.SchemaItem`.
|
| The dictionary is automatically generated when first accessed.
| It can also be specified in the constructor of some objects,
| such as :class:`_schema.Table` and :class:`_schema.Column`.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from SchemaItem:
|
| create_drop_stringify_dialect = 'default'
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.base.SchemaEventTarget:
|
| dispatch = <sqlalchemy.event.base.DDLEventsDispatch object>
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.visitors.Visitable:
|
| __class_getitem__(key: 'Any') -> 'Any'
|
| __init_subclass__() -> 'None'
| This method is called when a class is subclassed.
|
| The default implementation does nothing. It may be
| overridden to extend subclasses.
sqlalchemy.Update
Python Library Documentation: class Update in module sqlalchemy.sql.dml
class Update(DMLWhereBase, ValuesBase)
| Update(table: '_DMLTableArgument')
|
| Represent an Update construct.
|
| The :class:`_expression.Update` object is created using the
| :func:`_expression.update()` function.
|
| Method resolution order:
| Update
| DMLWhereBase
| ValuesBase
| UpdateBase
| sqlalchemy.sql.roles.DMLRole
| sqlalchemy.sql.selectable.HasCTE
| sqlalchemy.sql.roles.HasCTERole
| sqlalchemy.sql.selectable.SelectsRows
| sqlalchemy.sql.base.HasCompileState
| sqlalchemy.sql.base.DialectKWArgs
| sqlalchemy.sql.selectable.HasPrefixes
| sqlalchemy.sql.base.Generative
| sqlalchemy.sql.selectable.ExecutableReturnsRows
| sqlalchemy.sql.base.Executable
| sqlalchemy.sql.roles.StatementRole
| sqlalchemy.sql.selectable.ReturnsRows
| sqlalchemy.sql.roles.ReturnsRowsRole
| sqlalchemy.sql.roles.SQLRole
| sqlalchemy.sql.elements.DQLDMLClauseElement
| sqlalchemy.sql.elements.ClauseElement
| sqlalchemy.sql.annotation.SupportsWrappingAnnotations
| sqlalchemy.sql.annotation.SupportsAnnotations
| sqlalchemy.sql.cache_key.MemoizedHasCacheKey
| sqlalchemy.sql.cache_key.HasCacheKey
| sqlalchemy.util.langhelpers.HasMemoized
| sqlalchemy.sql.traversals.HasCopyInternals
| sqlalchemy.sql.visitors.ExternallyTraversible
| sqlalchemy.sql.visitors.HasTraverseInternals
| sqlalchemy.sql.elements.CompilerElement
| sqlalchemy.sql.visitors.Visitable
| builtins.object
|
| Methods defined here:
|
| __init__(self, table: '_DMLTableArgument')
| Initialize self. See help(type(self)) for accurate signature.
|
| inline(self) -> 'Self'
| Make this :class:`_expression.Update` construct "inline" .
|
| When set, SQL defaults present on :class:`_schema.Column`
| objects via the
| ``default`` keyword will be compiled 'inline' into the statement and
| not pre-executed. This means that their values will not be available
| in the dictionary returned from
| :meth:`_engine.CursorResult.last_updated_params`.
|
| .. versionchanged:: 1.4 the :paramref:`_expression.update.inline`
| parameter
| is now superseded by the :meth:`_expression.Update.inline` method.
|
| ordered_values(self, *args: 'Tuple[_DMLColumnArgument, Any]') -> 'Self'
| Specify the VALUES clause of this UPDATE statement with an explicit
| parameter ordering that will be maintained in the SET clause of the
| resulting UPDATE statement.
|
| E.g.::
|
| stmt = table.update().ordered_values(("name", "ed"), ("ident", "foo"))
|
| .. seealso::
|
| :ref:`tutorial_parameter_ordered_updates` - full example of the
| :meth:`_expression.Update.ordered_values` method.
|
| .. versionchanged:: 1.4 The :meth:`_expression.Update.ordered_values`
| method
| supersedes the
| :paramref:`_expression.update.preserve_parameter_order`
| parameter, which will be removed in SQLAlchemy 2.0.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| __visit_name__ = 'update'
|
| is_update = True
|
| ----------------------------------------------------------------------
| Methods inherited from DMLWhereBase:
|
| filter(self, *criteria: 'roles.ExpressionElementRole[Any]') -> 'Self'
| A synonym for the :meth:`_dml.DMLWhereBase.where` method.
|
| .. versionadded:: 1.4
|
| filter_by(self, **kwargs: 'Any') -> 'Self'
| apply the given filtering criterion as a WHERE clause
| to this select.
|
| where(self, *whereclause: '_ColumnExpressionArgument[bool]') -> 'Self'
| Return a new construct with the given expression(s) added to
| its WHERE clause, joined to the existing clause via AND, if any.
|
| Both :meth:`_dml.Update.where` and :meth:`_dml.Delete.where`
| support multiple-table forms, including database-specific
| ``UPDATE...FROM`` as well as ``DELETE..USING``. For backends that
| don't have multiple-table support, a backend agnostic approach
| to using multiple tables is to make use of correlated subqueries.
| See the linked tutorial sections below for examples.
|
| .. seealso::
|
| :ref:`tutorial_correlated_updates`
|
| :ref:`tutorial_update_from`
|
| :ref:`tutorial_multi_table_deletes`
|
| ----------------------------------------------------------------------
| Readonly properties inherited from DMLWhereBase:
|
| whereclause
| Return the completed WHERE clause for this :class:`.DMLWhereBase`
| statement.
|
| This assembles the current collection of WHERE criteria
| into a single :class:`_expression.BooleanClauseList` construct.
|
|
| .. versionadded:: 1.4
|
| ----------------------------------------------------------------------
| Data descriptors inherited from DMLWhereBase:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Methods inherited from ValuesBase:
|
| values(self, *args: 'Union[_DMLColumnKeyMapping[Any], Sequence[Any]]', **kwargs: 'Any') -> 'Self'
| Specify a fixed VALUES clause for an INSERT statement, or the SET
| clause for an UPDATE.
|
| Note that the :class:`_expression.Insert` and
| :class:`_expression.Update`
| constructs support
| per-execution time formatting of the VALUES and/or SET clauses,
| based on the arguments passed to :meth:`_engine.Connection.execute`.
| However, the :meth:`.ValuesBase.values` method can be used to "fix" a
| particular set of parameters into the statement.
|
| Multiple calls to :meth:`.ValuesBase.values` will produce a new
| construct, each one with the parameter list modified to include
| the new parameters sent. In the typical case of a single
| dictionary of parameters, the newly passed keys will replace
| the same keys in the previous construct. In the case of a list-based
| "multiple values" construct, each new list of values is extended
| onto the existing list of values.
|
| :param \**kwargs: key value pairs representing the string key
| of a :class:`_schema.Column`
| mapped to the value to be rendered into the
| VALUES or SET clause::
|
| users.insert().values(name="some name")
|
| users.update().where(users.c.id == 5).values(name="some name")
|
| :param \*args: As an alternative to passing key/value parameters,
| a dictionary, tuple, or list of dictionaries or tuples can be passed
| as a single positional argument in order to form the VALUES or
| SET clause of the statement. The forms that are accepted vary
| based on whether this is an :class:`_expression.Insert` or an
| :class:`_expression.Update` construct.
|
| For either an :class:`_expression.Insert` or
| :class:`_expression.Update`
| construct, a single dictionary can be passed, which works the same as
| that of the kwargs form::
|
| users.insert().values({"name": "some name"})
|
| users.update().values({"name": "some new name"})
|
| Also for either form but more typically for the
| :class:`_expression.Insert` construct, a tuple that contains an
| entry for every column in the table is also accepted::
|
| users.insert().values((5, "some name"))
|
| The :class:`_expression.Insert` construct also supports being
| passed a list of dictionaries or full-table-tuples, which on the
| server will render the less common SQL syntax of "multiple values" -
| this syntax is supported on backends such as SQLite, PostgreSQL,
| MySQL, but not necessarily others::
|
| users.insert().values(
| [
| {"name": "some name"},
| {"name": "some other name"},
| {"name": "yet another name"},
| ]
| )
|
| The above form would render a multiple VALUES statement similar to:
|
| .. sourcecode:: sql
|
| INSERT INTO users (name) VALUES
| (:name_1),
| (:name_2),
| (:name_3)
|
| It is essential to note that **passing multiple values is
| NOT the same as using traditional executemany() form**. The above
| syntax is a **special** syntax not typically used. To emit an
| INSERT statement against multiple rows, the normal method is
| to pass a multiple values list to the
| :meth:`_engine.Connection.execute`
| method, which is supported by all database backends and is generally
| more efficient for a very large number of parameters.
|
| .. seealso::
|
| :ref:`tutorial_multiple_parameters` - an introduction to
| the traditional Core method of multiple parameter set
| invocation for INSERTs and other statements.
|
| :ref:`tutorial_core_insert_values_clause` - Insert tutorial
| detailing alternatives to the multiple values syntax.
|
| The UPDATE construct also supports rendering the SET parameters
| in a specific order. For this feature refer to the
| :meth:`_expression.Update.ordered_values` method.
|
| .. seealso::
|
| :meth:`_expression.Update.ordered_values`
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from ValuesBase:
|
| select = None
|
| ----------------------------------------------------------------------
| Methods inherited from UpdateBase:
|
| corresponding_column(self, column: 'KeyedColumnElement[Any]', require_embedded: 'bool' = False) -> 'Optional[ColumnElement[Any]]'
|
| exported_columns(...)
| Return the RETURNING columns as a column collection for this
| statement.
|
| .. versionadded:: 1.4
|
| is_derived_from(self, fromclause: 'Optional[FromClause]') -> 'bool'
| Return ``True`` if this :class:`.ReturnsRows` is
| 'derived' from the given :class:`.FromClause`.
|
| Since these are DMLs, we dont want such statements ever being adapted
| so we return False for derives.
|
| params(self, *arg: 'Any', **kw: 'Any') -> 'NoReturn'
| Set the parameters for the statement.
|
| This method raises ``NotImplementedError`` on the base class,
| and is overridden by :class:`.ValuesBase` to provide the
| SET/VALUES clause of UPDATE and INSERT.
|
| return_defaults(self, *cols: '_DMLColumnArgument', supplemental_cols: 'Optional[Iterable[_DMLColumnArgument]]' = None, sort_by_parameter_order: 'bool' = False) -> 'Self'
| Make use of a :term:`RETURNING` clause for the purpose
| of fetching server-side expressions and defaults, for supporting
| backends only.
|
| .. deepalchemy::
|
| The :meth:`.UpdateBase.return_defaults` method is used by the ORM
| for its internal work in fetching newly generated primary key
| and server default values, in particular to provide the underlying
| implementation of the :paramref:`_orm.Mapper.eager_defaults`
| ORM feature as well as to allow RETURNING support with bulk
| ORM inserts. Its behavior is fairly idiosyncratic
| and is not really intended for general use. End users should
| stick with using :meth:`.UpdateBase.returning` in order to
| add RETURNING clauses to their INSERT, UPDATE and DELETE
| statements.
|
| Normally, a single row INSERT statement will automatically populate the
| :attr:`.CursorResult.inserted_primary_key` attribute when executed,
| which stores the primary key of the row that was just inserted in the
| form of a :class:`.Row` object with column names as named tuple keys
| (and the :attr:`.Row._mapping` view fully populated as well). The
| dialect in use chooses the strategy to use in order to populate this
| data; if it was generated using server-side defaults and / or SQL
| expressions, dialect-specific approaches such as ``cursor.lastrowid``
| or ``RETURNING`` are typically used to acquire the new primary key
| value.
|
| However, when the statement is modified by calling
| :meth:`.UpdateBase.return_defaults` before executing the statement,
| additional behaviors take place **only** for backends that support
| RETURNING and for :class:`.Table` objects that maintain the
| :paramref:`.Table.implicit_returning` parameter at its default value of
| ``True``. In these cases, when the :class:`.CursorResult` is returned
| from the statement's execution, not only will
| :attr:`.CursorResult.inserted_primary_key` be populated as always, the
| :attr:`.CursorResult.returned_defaults` attribute will also be
| populated with a :class:`.Row` named-tuple representing the full range
| of server generated
| values from that single row, including values for any columns that
| specify :paramref:`_schema.Column.server_default` or which make use of
| :paramref:`_schema.Column.default` using a SQL expression.
|
| When invoking INSERT statements with multiple rows using
| :ref:`insertmanyvalues <engine_insertmanyvalues>`, the
| :meth:`.UpdateBase.return_defaults` modifier will have the effect of
| the :attr:`_engine.CursorResult.inserted_primary_key_rows` and
| :attr:`_engine.CursorResult.returned_defaults_rows` attributes being
| fully populated with lists of :class:`.Row` objects representing newly
| inserted primary key values as well as newly inserted server generated
| values for each row inserted. The
| :attr:`.CursorResult.inserted_primary_key` and
| :attr:`.CursorResult.returned_defaults` attributes will also continue
| to be populated with the first row of these two collections.
|
| If the backend does not support RETURNING or the :class:`.Table` in use
| has disabled :paramref:`.Table.implicit_returning`, then no RETURNING
| clause is added and no additional data is fetched, however the
| INSERT, UPDATE or DELETE statement proceeds normally.
|
| E.g.::
|
| stmt = table.insert().values(data="newdata").return_defaults()
|
| result = connection.execute(stmt)
|
| server_created_at = result.returned_defaults["created_at"]
|
| When used against an UPDATE statement
| :meth:`.UpdateBase.return_defaults` instead looks for columns that
| include :paramref:`_schema.Column.onupdate` or
| :paramref:`_schema.Column.server_onupdate` parameters assigned, when
| constructing the columns that will be included in the RETURNING clause
| by default if explicit columns were not specified. When used against a
| DELETE statement, no columns are included in RETURNING by default, they
| instead must be specified explicitly as there are no columns that
| normally change values when a DELETE statement proceeds.
|
| .. versionadded:: 2.0 :meth:`.UpdateBase.return_defaults` is supported
| for DELETE statements also and has been moved from
| :class:`.ValuesBase` to :class:`.UpdateBase`.
|
| The :meth:`.UpdateBase.return_defaults` method is mutually exclusive
| against the :meth:`.UpdateBase.returning` method and errors will be
| raised during the SQL compilation process if both are used at the same
| time on one statement. The RETURNING clause of the INSERT, UPDATE or
| DELETE statement is therefore controlled by only one of these methods
| at a time.
|
| The :meth:`.UpdateBase.return_defaults` method differs from
| :meth:`.UpdateBase.returning` in these ways:
|
| 1. :meth:`.UpdateBase.return_defaults` method causes the
| :attr:`.CursorResult.returned_defaults` collection to be populated
| with the first row from the RETURNING result. This attribute is not
| populated when using :meth:`.UpdateBase.returning`.
|
| 2. :meth:`.UpdateBase.return_defaults` is compatible with existing
| logic used to fetch auto-generated primary key values that are then
| populated into the :attr:`.CursorResult.inserted_primary_key`
| attribute. By contrast, using :meth:`.UpdateBase.returning` will
| have the effect of the :attr:`.CursorResult.inserted_primary_key`
| attribute being left unpopulated.
|
| 3. :meth:`.UpdateBase.return_defaults` can be called against any
| backend. Backends that don't support RETURNING will skip the usage
| of the feature, rather than raising an exception, *unless*
| ``supplemental_cols`` is passed. The return value
| of :attr:`_engine.CursorResult.returned_defaults` will be ``None``
| for backends that don't support RETURNING or for which the target
| :class:`.Table` sets :paramref:`.Table.implicit_returning` to
| ``False``.
|
| 4. An INSERT statement invoked with executemany() is supported if the
| backend database driver supports the
| :ref:`insertmanyvalues <engine_insertmanyvalues>`
| feature which is now supported by most SQLAlchemy-included backends.
| When executemany is used, the
| :attr:`_engine.CursorResult.returned_defaults_rows` and
| :attr:`_engine.CursorResult.inserted_primary_key_rows` accessors
| will return the inserted defaults and primary keys.
|
| .. versionadded:: 1.4 Added
| :attr:`_engine.CursorResult.returned_defaults_rows` and
| :attr:`_engine.CursorResult.inserted_primary_key_rows` accessors.
| In version 2.0, the underlying implementation which fetches and
| populates the data for these attributes was generalized to be
| supported by most backends, whereas in 1.4 they were only
| supported by the ``psycopg2`` driver.
|
|
| :param cols: optional list of column key names or
| :class:`_schema.Column` that acts as a filter for those columns that
| will be fetched.
| :param supplemental_cols: optional list of RETURNING expressions,
| in the same form as one would pass to the
| :meth:`.UpdateBase.returning` method. When present, the additional
| columns will be included in the RETURNING clause, and the
| :class:`.CursorResult` object will be "rewound" when returned, so
| that methods like :meth:`.CursorResult.all` will return new rows
| mostly as though the statement used :meth:`.UpdateBase.returning`
| directly. However, unlike when using :meth:`.UpdateBase.returning`
| directly, the **order of the columns is undefined**, so can only be
| targeted using names or :attr:`.Row._mapping` keys; they cannot
| reliably be targeted positionally.
|
| .. versionadded:: 2.0
|
| :param sort_by_parameter_order: for a batch INSERT that is being
| executed against multiple parameter sets, organize the results of
| RETURNING so that the returned rows correspond to the order of
| parameter sets passed in. This applies only to an :term:`executemany`
| execution for supporting dialects and typically makes use of the
| :term:`insertmanyvalues` feature.
|
| .. versionadded:: 2.0.10
|
| .. seealso::
|
| :ref:`engine_insertmanyvalues_returning_order` - background on
| sorting of RETURNING rows for bulk INSERT
|
| .. seealso::
|
| :meth:`.UpdateBase.returning`
|
| :attr:`_engine.CursorResult.returned_defaults`
|
| :attr:`_engine.CursorResult.returned_defaults_rows`
|
| :attr:`_engine.CursorResult.inserted_primary_key`
|
| :attr:`_engine.CursorResult.inserted_primary_key_rows`
|
| returning(self, *cols: '_ColumnsClauseArgument[Any]', sort_by_parameter_order: 'bool' = False, **_UpdateBase__kw: 'Any') -> 'UpdateBase'
| Add a :term:`RETURNING` or equivalent clause to this statement.
|
| e.g.:
|
| .. sourcecode:: pycon+sql
|
| >>> stmt = (
| ... table.update()
| ... .where(table.c.data == "value")
| ... .values(status="X")
| ... .returning(table.c.server_flag, table.c.updated_timestamp)
| ... )
| >>> print(stmt)
| {printsql}UPDATE some_table SET status=:status
| WHERE some_table.data = :data_1
| RETURNING some_table.server_flag, some_table.updated_timestamp
|
| The method may be invoked multiple times to add new entries to the
| list of expressions to be returned.
|
| .. versionadded:: 1.4.0b2 The method may be invoked multiple times to
| add new entries to the list of expressions to be returned.
|
| The given collection of column expressions should be derived from the
| table that is the target of the INSERT, UPDATE, or DELETE. While
| :class:`_schema.Column` objects are typical, the elements can also be
| expressions:
|
| .. sourcecode:: pycon+sql
|
| >>> stmt = table.insert().returning(
| ... (table.c.first_name + " " + table.c.last_name).label("fullname")
| ... )
| >>> print(stmt)
| {printsql}INSERT INTO some_table (first_name, last_name)
| VALUES (:first_name, :last_name)
| RETURNING some_table.first_name || :first_name_1 || some_table.last_name AS fullname
|
| Upon compilation, a RETURNING clause, or database equivalent,
| will be rendered within the statement. For INSERT and UPDATE,
| the values are the newly inserted/updated values. For DELETE,
| the values are those of the rows which were deleted.
|
| Upon execution, the values of the columns to be returned are made
| available via the result set and can be iterated using
| :meth:`_engine.CursorResult.fetchone` and similar.
| For DBAPIs which do not
| natively support returning values (i.e. cx_oracle), SQLAlchemy will
| approximate this behavior at the result level so that a reasonable
| amount of behavioral neutrality is provided.
|
| Note that not all databases/DBAPIs
| support RETURNING. For those backends with no support,
| an exception is raised upon compilation and/or execution.
| For those who do support it, the functionality across backends
| varies greatly, including restrictions on executemany()
| and other statements which return multiple rows. Please
| read the documentation notes for the database in use in
| order to determine the availability of RETURNING.
|
| :param \*cols: series of columns, SQL expressions, or whole tables
| entities to be returned.
| :param sort_by_parameter_order: for a batch INSERT that is being
| executed against multiple parameter sets, organize the results of
| RETURNING so that the returned rows correspond to the order of
| parameter sets passed in. This applies only to an :term:`executemany`
| execution for supporting dialects and typically makes use of the
| :term:`insertmanyvalues` feature.
|
| .. versionadded:: 2.0.10
|
| .. seealso::
|
| :ref:`engine_insertmanyvalues_returning_order` - background on
| sorting of RETURNING rows for bulk INSERT (Core level discussion)
|
| :ref:`orm_queryguide_bulk_insert_returning_ordered` - example of
| use with :ref:`orm_queryguide_bulk_insert` (ORM level discussion)
|
| .. seealso::
|
| :meth:`.UpdateBase.return_defaults` - an alternative method tailored
| towards efficient fetching of server-side defaults and triggers
| for single-row INSERTs or UPDATEs.
|
| :ref:`tutorial_insert_returning` - in the :ref:`unified_tutorial`
|
| with_dialect_options(self, **opt: 'Any') -> 'Self'
| Add dialect options to this INSERT/UPDATE/DELETE object.
|
| e.g.::
|
| upd = table.update().dialect_options(mysql_limit=10)
|
| .. versionadded: 1.4 - this method supersedes the dialect options
| associated with the constructor.
|
| with_hint(self, text: 'str', selectable: 'Optional[_DMLTableArgument]' = None, dialect_name: 'str' = '*') -> 'Self'
| Add a table hint for a single table to this
| INSERT/UPDATE/DELETE statement.
|
| .. note::
|
| :meth:`.UpdateBase.with_hint` currently applies only to
| Microsoft SQL Server. For MySQL INSERT/UPDATE/DELETE hints, use
| :meth:`.UpdateBase.prefix_with`.
|
| The text of the hint is rendered in the appropriate
| location for the database backend in use, relative
| to the :class:`_schema.Table` that is the subject of this
| statement, or optionally to that of the given
| :class:`_schema.Table` passed as the ``selectable`` argument.
|
| The ``dialect_name`` option will limit the rendering of a particular
| hint to a particular backend. Such as, to add a hint
| that only takes effect for SQL Server::
|
| mytable.insert().with_hint("WITH (PAGLOCK)", dialect_name="mssql")
|
| :param text: Text of the hint.
| :param selectable: optional :class:`_schema.Table` that specifies
| an element of the FROM clause within an UPDATE or DELETE
| to be the subject of the hint - applies only to certain backends.
| :param dialect_name: defaults to ``*``, if specified as the name
| of a particular dialect, will apply these hints only when
| that dialect is in use.
|
| ----------------------------------------------------------------------
| Readonly properties inherited from UpdateBase:
|
| entity_description
| Return a :term:`plugin-enabled` description of the table and/or
| entity which this DML construct is operating against.
|
| This attribute is generally useful when using the ORM, as an
| extended structure which includes information about mapped
| entities is returned. The section :ref:`queryguide_inspection`
| contains more background.
|
| For a Core statement, the structure returned by this accessor
| is derived from the :attr:`.UpdateBase.table` attribute, and
| refers to the :class:`.Table` being inserted, updated, or deleted::
|
| >>> stmt = insert(user_table)
| >>> stmt.entity_description
| {
| "name": "user_table",
| "table": Table("user_table", ...)
| }
|
| .. versionadded:: 1.4.33
|
| .. seealso::
|
| :attr:`.UpdateBase.returning_column_descriptions`
|
| :attr:`.Select.column_descriptions` - entity information for
| a :func:`.select` construct
|
| :ref:`queryguide_inspection` - ORM background
|
| returning_column_descriptions
| Return a :term:`plugin-enabled` description of the columns
| which this DML construct is RETURNING against, in other words
| the expressions established as part of :meth:`.UpdateBase.returning`.
|
| This attribute is generally useful when using the ORM, as an
| extended structure which includes information about mapped
| entities is returned. The section :ref:`queryguide_inspection`
| contains more background.
|
| For a Core statement, the structure returned by this accessor is
| derived from the same objects that are returned by the
| :attr:`.UpdateBase.exported_columns` accessor::
|
| >>> stmt = insert(user_table).returning(user_table.c.id, user_table.c.name)
| >>> stmt.entity_description
| [
| {
| "name": "id",
| "type": Integer,
| "expr": Column("id", Integer(), table=<user>, ...)
| },
| {
| "name": "name",
| "type": String(),
| "expr": Column("name", String(), table=<user>, ...)
| },
| ]
|
| .. versionadded:: 1.4.33
|
| .. seealso::
|
| :attr:`.UpdateBase.entity_description`
|
| :attr:`.Select.column_descriptions` - entity information for
| a :func:`.select` construct
|
| :ref:`queryguide_inspection` - ORM background
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from UpdateBase:
|
| is_dml = True
|
| named_with_column = False
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.selectable.HasCTE:
|
| add_cte(self, *ctes: 'CTE', nest_here: 'bool' = False) -> 'Self'
| Add one or more :class:`_sql.CTE` constructs to this statement.
|
| This method will associate the given :class:`_sql.CTE` constructs with
| the parent statement such that they will each be unconditionally
| rendered in the WITH clause of the final statement, even if not
| referenced elsewhere within the statement or any sub-selects.
|
| The optional :paramref:`.HasCTE.add_cte.nest_here` parameter when set
| to True will have the effect that each given :class:`_sql.CTE` will
| render in a WITH clause rendered directly along with this statement,
| rather than being moved to the top of the ultimate rendered statement,
| even if this statement is rendered as a subquery within a larger
| statement.
|
| This method has two general uses. One is to embed CTE statements that
| serve some purpose without being referenced explicitly, such as the use
| case of embedding a DML statement such as an INSERT or UPDATE as a CTE
| inline with a primary statement that may draw from its results
| indirectly. The other is to provide control over the exact placement
| of a particular series of CTE constructs that should remain rendered
| directly in terms of a particular statement that may be nested in a
| larger statement.
|
| E.g.::
|
| from sqlalchemy import table, column, select
|
| t = table("t", column("c1"), column("c2"))
|
| ins = t.insert().values({"c1": "x", "c2": "y"}).cte()
|
| stmt = select(t).add_cte(ins)
|
| Would render:
|
| .. sourcecode:: sql
|
| WITH anon_1 AS (
| INSERT INTO t (c1, c2) VALUES (:param_1, :param_2)
| )
| SELECT t.c1, t.c2
| FROM t
|
| Above, the "anon_1" CTE is not referenced in the SELECT
| statement, however still accomplishes the task of running an INSERT
| statement.
|
| Similarly in a DML-related context, using the PostgreSQL
| :class:`_postgresql.Insert` construct to generate an "upsert"::
|
| from sqlalchemy import table, column
| from sqlalchemy.dialects.postgresql import insert
|
| t = table("t", column("c1"), column("c2"))
|
| delete_statement_cte = t.delete().where(t.c.c1 < 1).cte("deletions")
|
| insert_stmt = insert(t).values({"c1": 1, "c2": 2})
| update_statement = insert_stmt.on_conflict_do_update(
| index_elements=[t.c.c1],
| set_={
| "c1": insert_stmt.excluded.c1,
| "c2": insert_stmt.excluded.c2,
| },
| ).add_cte(delete_statement_cte)
|
| print(update_statement)
|
| The above statement renders as:
|
| .. sourcecode:: sql
|
| WITH deletions AS (
| DELETE FROM t WHERE t.c1 < %(c1_1)s
| )
| INSERT INTO t (c1, c2) VALUES (%(c1)s, %(c2)s)
| ON CONFLICT (c1) DO UPDATE SET c1 = excluded.c1, c2 = excluded.c2
|
| .. versionadded:: 1.4.21
|
| :param \*ctes: zero or more :class:`.CTE` constructs.
|
| .. versionchanged:: 2.0 Multiple CTE instances are accepted
|
| :param nest_here: if True, the given CTE or CTEs will be rendered
| as though they specified the :paramref:`.HasCTE.cte.nesting` flag
| to ``True`` when they were added to this :class:`.HasCTE`.
| Assuming the given CTEs are not referenced in an outer-enclosing
| statement as well, the CTEs given should render at the level of
| this statement when this flag is given.
|
| .. versionadded:: 2.0
|
| .. seealso::
|
| :paramref:`.HasCTE.cte.nesting`
|
| cte(self, name: 'Optional[str]' = None, recursive: 'bool' = False, nesting: 'bool' = False) -> 'CTE'
| Return a new :class:`_expression.CTE`,
| or Common Table Expression instance.
|
| Common table expressions are a SQL standard whereby SELECT
| statements can draw upon secondary statements specified along
| with the primary statement, using a clause called "WITH".
| Special semantics regarding UNION can also be employed to
| allow "recursive" queries, where a SELECT statement can draw
| upon the set of rows that have previously been selected.
|
| CTEs can also be applied to DML constructs UPDATE, INSERT
| and DELETE on some databases, both as a source of CTE rows
| when combined with RETURNING, as well as a consumer of
| CTE rows.
|
| SQLAlchemy detects :class:`_expression.CTE` objects, which are treated
| similarly to :class:`_expression.Alias` objects, as special elements
| to be delivered to the FROM clause of the statement as well
| as to a WITH clause at the top of the statement.
|
| For special prefixes such as PostgreSQL "MATERIALIZED" and
| "NOT MATERIALIZED", the :meth:`_expression.CTE.prefix_with`
| method may be
| used to establish these.
|
| .. versionchanged:: 1.3.13 Added support for prefixes.
| In particular - MATERIALIZED and NOT MATERIALIZED.
|
| :param name: name given to the common table expression. Like
| :meth:`_expression.FromClause.alias`, the name can be left as
| ``None`` in which case an anonymous symbol will be used at query
| compile time.
| :param recursive: if ``True``, will render ``WITH RECURSIVE``.
| A recursive common table expression is intended to be used in
| conjunction with UNION ALL in order to derive rows
| from those already selected.
| :param nesting: if ``True``, will render the CTE locally to the
| statement in which it is referenced. For more complex scenarios,
| the :meth:`.HasCTE.add_cte` method using the
| :paramref:`.HasCTE.add_cte.nest_here`
| parameter may also be used to more carefully
| control the exact placement of a particular CTE.
|
| .. versionadded:: 1.4.24
|
| .. seealso::
|
| :meth:`.HasCTE.add_cte`
|
| The following examples include two from PostgreSQL's documentation at
| https://www.postgresql.org/docs/current/static/queries-with.html,
| as well as additional examples.
|
| Example 1, non recursive::
|
| from sqlalchemy import (
| Table,
| Column,
| String,
| Integer,
| MetaData,
| select,
| func,
| )
|
| metadata = MetaData()
|
| orders = Table(
| "orders",
| metadata,
| Column("region", String),
| Column("amount", Integer),
| Column("product", String),
| Column("quantity", Integer),
| )
|
| regional_sales = (
| select(orders.c.region, func.sum(orders.c.amount).label("total_sales"))
| .group_by(orders.c.region)
| .cte("regional_sales")
| )
|
|
| top_regions = (
| select(regional_sales.c.region)
| .where(
| regional_sales.c.total_sales
| > select(func.sum(regional_sales.c.total_sales) / 10)
| )
| .cte("top_regions")
| )
|
| statement = (
| select(
| orders.c.region,
| orders.c.product,
| func.sum(orders.c.quantity).label("product_units"),
| func.sum(orders.c.amount).label("product_sales"),
| )
| .where(orders.c.region.in_(select(top_regions.c.region)))
| .group_by(orders.c.region, orders.c.product)
| )
|
| result = conn.execute(statement).fetchall()
|
| Example 2, WITH RECURSIVE::
|
| from sqlalchemy import (
| Table,
| Column,
| String,
| Integer,
| MetaData,
| select,
| func,
| )
|
| metadata = MetaData()
|
| parts = Table(
| "parts",
| metadata,
| Column("part", String),
| Column("sub_part", String),
| Column("quantity", Integer),
| )
|
| included_parts = (
| select(parts.c.sub_part, parts.c.part, parts.c.quantity)
| .where(parts.c.part == "our part")
| .cte(recursive=True)
| )
|
|
| incl_alias = included_parts.alias()
| parts_alias = parts.alias()
| included_parts = included_parts.union_all(
| select(
| parts_alias.c.sub_part, parts_alias.c.part, parts_alias.c.quantity
| ).where(parts_alias.c.part == incl_alias.c.sub_part)
| )
|
| statement = select(
| included_parts.c.sub_part,
| func.sum(included_parts.c.quantity).label("total_quantity"),
| ).group_by(included_parts.c.sub_part)
|
| result = conn.execute(statement).fetchall()
|
| Example 3, an upsert using UPDATE and INSERT with CTEs::
|
| from datetime import date
| from sqlalchemy import (
| MetaData,
| Table,
| Column,
| Integer,
| Date,
| select,
| literal,
| and_,
| exists,
| )
|
| metadata = MetaData()
|
| visitors = Table(
| "visitors",
| metadata,
| Column("product_id", Integer, primary_key=True),
| Column("date", Date, primary_key=True),
| Column("count", Integer),
| )
|
| # add 5 visitors for the product_id == 1
| product_id = 1
| day = date.today()
| count = 5
|
| update_cte = (
| visitors.update()
| .where(
| and_(visitors.c.product_id == product_id, visitors.c.date == day)
| )
| .values(count=visitors.c.count + count)
| .returning(literal(1))
| .cte("update_cte")
| )
|
| upsert = visitors.insert().from_select(
| [visitors.c.product_id, visitors.c.date, visitors.c.count],
| select(literal(product_id), literal(day), literal(count)).where(
| ~exists(update_cte.select())
| ),
| )
|
| connection.execute(upsert)
|
| Example 4, Nesting CTE (SQLAlchemy 1.4.24 and above)::
|
| value_a = select(literal("root").label("n")).cte("value_a")
|
| # A nested CTE with the same name as the root one
| value_a_nested = select(literal("nesting").label("n")).cte(
| "value_a", nesting=True
| )
|
| # Nesting CTEs takes ascendency locally
| # over the CTEs at a higher level
| value_b = select(value_a_nested.c.n).cte("value_b")
|
| value_ab = select(value_a.c.n.label("a"), value_b.c.n.label("b"))
|
| The above query will render the second CTE nested inside the first,
| shown with inline parameters below as:
|
| .. sourcecode:: sql
|
| WITH
| value_a AS
| (SELECT 'root' AS n),
| value_b AS
| (WITH value_a AS
| (SELECT 'nesting' AS n)
| SELECT value_a.n AS n FROM value_a)
| SELECT value_a.n AS a, value_b.n AS b
| FROM value_a, value_b
|
| The same CTE can be set up using the :meth:`.HasCTE.add_cte` method
| as follows (SQLAlchemy 2.0 and above)::
|
| value_a = select(literal("root").label("n")).cte("value_a")
|
| # A nested CTE with the same name as the root one
| value_a_nested = select(literal("nesting").label("n")).cte("value_a")
|
| # Nesting CTEs takes ascendency locally
| # over the CTEs at a higher level
| value_b = (
| select(value_a_nested.c.n)
| .add_cte(value_a_nested, nest_here=True)
| .cte("value_b")
| )
|
| value_ab = select(value_a.c.n.label("a"), value_b.c.n.label("b"))
|
| Example 5, Non-Linear CTE (SQLAlchemy 1.4.28 and above)::
|
| edge = Table(
| "edge",
| metadata,
| Column("id", Integer, primary_key=True),
| Column("left", Integer),
| Column("right", Integer),
| )
|
| root_node = select(literal(1).label("node")).cte("nodes", recursive=True)
|
| left_edge = select(edge.c.left).join(
| root_node, edge.c.right == root_node.c.node
| )
| right_edge = select(edge.c.right).join(
| root_node, edge.c.left == root_node.c.node
| )
|
| subgraph_cte = root_node.union(left_edge, right_edge)
|
| subgraph = select(subgraph_cte)
|
| The above query will render 2 UNIONs inside the recursive CTE:
|
| .. sourcecode:: sql
|
| WITH RECURSIVE nodes(node) AS (
| SELECT 1 AS node
| UNION
| SELECT edge."left" AS "left"
| FROM edge JOIN nodes ON edge."right" = nodes.node
| UNION
| SELECT edge."right" AS "right"
| FROM edge JOIN nodes ON edge."left" = nodes.node
| )
| SELECT nodes.node FROM nodes
|
| .. seealso::
|
| :meth:`_orm.Query.cte` - ORM version of
| :meth:`_expression.HasCTE.cte`.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.selectable.HasCTE:
|
| name_cte_columns = False
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.base.DialectKWArgs:
|
| dialect_options(...)
| A collection of keyword arguments specified as dialect-specific
| options to this construct.
|
| This is a two-level nested registry, keyed to ``<dialect_name>``
| and ``<argument_name>``. For example, the ``postgresql_where``
| argument would be locatable as::
|
| arg = my_object.dialect_options["postgresql"]["where"]
|
| .. versionadded:: 0.9.2
|
| .. seealso::
|
| :attr:`.DialectKWArgs.dialect_kwargs` - flat dictionary form
|
| get_dialect_option(self, dialect: 'Dialect', argument_name: 'str', *, else_: 'Any' = None, deprecated_fallback: 'Optional[str]' = None) -> 'Any'
| Return the value of a dialect-specific option, or *else_* if
| this dialect does not register the given argument.
|
| This is useful for DDL compilers that may be inherited by
| third-party dialects whose ``construct_arguments`` do not
| include the same set of keys as the parent dialect.
|
| :param dialect: The dialect for which to retrieve the option.
| :param argument_name: The name of the argument to retrieve.
| :param else\_: The value to return if the argument is not present.
| :param deprecated_fallback: Optional dialect name to fall back to
| if the argument is not present for the current dialect. If the
| argument is present for the fallback dialect but not the current
| dialect, a deprecation warning will be emitted.
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.base.DialectKWArgs:
|
| argument_for(dialect_name: 'str', argument_name: 'str', default: 'Any') -> 'None'
| Add a new kind of dialect-specific keyword argument for this class.
|
| E.g.::
|
| Index.argument_for("mydialect", "length", None)
|
| some_index = Index("a", "b", mydialect_length=5)
|
| The :meth:`.DialectKWArgs.argument_for` method is a per-argument
| way adding extra arguments to the
| :attr:`.DefaultDialect.construct_arguments` dictionary. This
| dictionary provides a list of argument names accepted by various
| schema-level constructs on behalf of a dialect.
|
| New dialects should typically specify this dictionary all at once as a
| data member of the dialect class. The use case for ad-hoc addition of
| argument names is typically for end-user code that is also using
| a custom compilation scheme which consumes the additional arguments.
|
| :param dialect_name: name of a dialect. The dialect must be
| locatable, else a :class:`.NoSuchModuleError` is raised. The
| dialect must also include an existing
| :attr:`.DefaultDialect.construct_arguments` collection, indicating
| that it participates in the keyword-argument validation and default
| system, else :class:`.ArgumentError` is raised. If the dialect does
| not include this collection, then any keyword argument can be
| specified on behalf of this dialect already. All dialects packaged
| within SQLAlchemy include this collection, however for third party
| dialects, support may vary.
|
| :param argument_name: name of the parameter.
|
| :param default: default value of the parameter.
|
| ----------------------------------------------------------------------
| Readonly properties inherited from sqlalchemy.sql.base.DialectKWArgs:
|
| dialect_kwargs
| A collection of keyword arguments specified as dialect-specific
| options to this construct.
|
| The arguments are present here in their original ``<dialect>_<kwarg>``
| format. Only arguments that were actually passed are included;
| unlike the :attr:`.DialectKWArgs.dialect_options` collection, which
| contains all options known by this dialect including defaults.
|
| The collection is also writable; keys are accepted of the
| form ``<dialect>_<kwarg>`` where the value will be assembled
| into the list of options.
|
| .. seealso::
|
| :attr:`.DialectKWArgs.dialect_options` - nested dictionary form
|
| kwargs
| A synonym for :attr:`.DialectKWArgs.dialect_kwargs`.
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.selectable.HasPrefixes:
|
| prefix_with(self, *prefixes: '_TextCoercedExpressionArgument[Any]', dialect: 'str' = '*') -> 'Self'
| 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.
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.base.Executable:
|
| execution_options(self, **kw: 'Any') -> 'Self'
| Set non-SQL options for the statement which take effect during
| execution.
|
| Execution options can be set at many scopes, including per-statement,
| per-connection, or per execution, using methods such as
| :meth:`_engine.Connection.execution_options` and parameters which
| accept a dictionary of options such as
| :paramref:`_engine.Connection.execute.execution_options` and
| :paramref:`_orm.Session.execute.execution_options`.
|
| The primary characteristic of an execution option, as opposed to
| other kinds of options such as ORM loader options, is that
| **execution options never affect the compiled SQL of a query, only
| things that affect how the SQL statement itself is invoked or how
| results are fetched**. That is, execution options are not part of
| what's accommodated by SQL compilation nor are they considered part of
| the cached state of a statement.
|
| The :meth:`_sql.Executable.execution_options` method is
| :term:`generative`, as
| is the case for the method as applied to the :class:`_engine.Engine`
| and :class:`_orm.Query` objects, which means when the method is called,
| a copy of the object is returned, which applies the given parameters to
| that new copy, but leaves the original unchanged::
|
| statement = select(table.c.x, table.c.y)
| new_statement = statement.execution_options(my_option=True)
|
| An exception to this behavior is the :class:`_engine.Connection`
| object, where the :meth:`_engine.Connection.execution_options` method
| is explicitly **not** generative.
|
| The kinds of options that may be passed to
| :meth:`_sql.Executable.execution_options` and other related methods and
| parameter dictionaries include parameters that are explicitly consumed
| by SQLAlchemy Core or ORM, as well as arbitrary keyword arguments not
| defined by SQLAlchemy, which means the methods and/or parameter
| dictionaries may be used for user-defined parameters that interact with
| custom code, which may access the parameters using methods such as
| :meth:`_sql.Executable.get_execution_options` and
| :meth:`_engine.Connection.get_execution_options`, or within selected
| event hooks using a dedicated ``execution_options`` event parameter
| such as
| :paramref:`_events.ConnectionEvents.before_execute.execution_options`
| or :attr:`_orm.ORMExecuteState.execution_options`, e.g.::
|
| from sqlalchemy import event
|
|
| @event.listens_for(some_engine, "before_execute")
| def _process_opt(conn, statement, multiparams, params, execution_options):
| "run a SQL function before invoking a statement"
|
| if execution_options.get("do_special_thing", False):
| conn.exec_driver_sql("run_special_function()")
|
| Within the scope of options that are explicitly recognized by
| SQLAlchemy, most apply to specific classes of objects and not others.
| The most common execution options include:
|
| * :paramref:`_engine.Connection.execution_options.isolation_level` -
| sets the isolation level for a connection or a class of connections
| via an :class:`_engine.Engine`. This option is accepted only
| by :class:`_engine.Connection` or :class:`_engine.Engine`.
|
| * :paramref:`_engine.Connection.execution_options.stream_results` -
| indicates results should be fetched using a server side cursor;
| this option is accepted by :class:`_engine.Connection`, by the
| :paramref:`_engine.Connection.execute.execution_options` parameter
| on :meth:`_engine.Connection.execute`, and additionally by
| :meth:`_sql.Executable.execution_options` on a SQL statement object,
| as well as by ORM constructs like :meth:`_orm.Session.execute`.
|
| * :paramref:`_engine.Connection.execution_options.compiled_cache` -
| indicates a dictionary that will serve as the
| :ref:`SQL compilation cache <sql_caching>`
| for a :class:`_engine.Connection` or :class:`_engine.Engine`, as
| well as for ORM methods like :meth:`_orm.Session.execute`.
| Can be passed as ``None`` to disable caching for statements.
| This option is not accepted by
| :meth:`_sql.Executable.execution_options` as it is inadvisable to
| carry along a compilation cache within a statement object.
|
| * :paramref:`_engine.Connection.execution_options.schema_translate_map`
| - a mapping of schema names used by the
| :ref:`Schema Translate Map <schema_translating>` feature, accepted
| by :class:`_engine.Connection`, :class:`_engine.Engine`,
| :class:`_sql.Executable`, as well as by ORM constructs
| like :meth:`_orm.Session.execute`.
|
| .. seealso::
|
| :meth:`_engine.Connection.execution_options`
|
| :paramref:`_engine.Connection.execute.execution_options`
|
| :paramref:`_orm.Session.execute.execution_options`
|
| :ref:`orm_queryguide_execution_options` - documentation on all
| ORM-specific execution options
|
| get_execution_options(self) -> '_ExecuteOptions'
| Get the non-SQL options which will take effect during execution.
|
| .. versionadded:: 1.3
|
| .. seealso::
|
| :meth:`.Executable.execution_options`
|
| options(self, *options: 'ExecutableOption') -> 'Self'
| Apply options to this statement.
|
| In the general sense, options are any kind of Python object
| that can be interpreted by the SQL compiler for the statement.
| These options can be consumed by specific dialects or specific kinds
| of compilers.
|
| The most commonly known kind of option are the ORM level options
| that apply "eager load" and other loading behaviors to an ORM
| query. However, options can theoretically be used for many other
| purposes.
|
| For background on specific kinds of options for specific kinds of
| statements, refer to the documentation for those option objects.
|
| .. versionchanged:: 1.4 - added :meth:`.Executable.options` to
| Core statement objects towards the goal of allowing unified
| Core / ORM querying capabilities.
|
| .. seealso::
|
| :ref:`loading_columns` - refers to options specific to the usage
| of ORM queries
|
| :ref:`relationship_loader_options` - refers to options specific
| to the usage of ORM queries
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.base.Executable:
|
| is_delete = False
|
| is_from_statement = False
|
| is_insert = False
|
| is_select = False
|
| is_text = False
|
| supports_execution = True
|
| ----------------------------------------------------------------------
| Readonly properties inherited from sqlalchemy.sql.selectable.ReturnsRows:
|
| selectable
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.SQLRole:
|
| allows_lambda = False
|
| uses_inspection = False
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.elements.ClauseElement:
|
| __bool__(self)
|
| __getstate__(self)
| Helper for pickle.
|
| __invert__(self)
|
| __repr__(self)
| Return repr(self).
|
| compare(self, other: 'ClauseElement', **kw: 'Any') -> 'bool'
| Compare this :class:`_expression.ClauseElement` to
| the given :class:`_expression.ClauseElement`.
|
| Subclasses should override the default behavior, which is a
| straight identity comparison.
|
| \**kw are arguments consumed by subclass ``compare()`` methods and
| may be used to modify the criteria for comparison
| (see :class:`_expression.ColumnElement`).
|
| description(...)
|
| entity_namespace(...)
|
| self_group(self, against: 'Optional[OperatorType]' = None) -> 'ClauseElement'
| 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.
|
| unique_params(self, _ClauseElement__optionaldict: 'Optional[Dict[str, Any]]' = None, **kwargs: 'Any') -> 'Self'
| Return a copy with :func:`_expression.bindparam` elements
| replaced.
|
| Same functionality as :meth:`_expression.ClauseElement.params`,
| except adds `unique=True`
| to affected bind parameters so that multiple statements can be
| used.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.elements.ClauseElement:
|
| is_clause_element = True
|
| is_selectable = False
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.cache_key.HasCacheKey:
|
| inherit_cache = None
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_instancemethod(fn: '_F') -> '_F'
| Decorate a method memoize its return value.
|
| :meta private:
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_attribute = <class 'sqlalchemy.util.langhelpers.HasMemoized.m...
| A read-only @property that is only evaluated once.
|
| :meta private:
|
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.visitors.HasTraverseInternals:
|
| get_children(self, *, omit_attrs: 'Tuple[str, ...]' = (), **kw: 'Any') -> 'Iterable[HasTraverseInternals]'
| Return immediate child :class:`.visitors.HasTraverseInternals`
| elements of this :class:`.visitors.HasTraverseInternals`.
|
| This is used for visit traversal.
|
| \**kw may contain flags that change the collection that is
| returned, for example to return a subset of items in order to
| cut down on larger traversals, or to return child items from a
| different context (such as schema-level collections instead of
| clause-level).
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.elements.CompilerElement:
|
| __str__(self) -> 'str'
| Return str(self).
|
| compile(self, bind: 'Optional[_HasDialect]' = None, dialect: 'Optional[Dialect]' = None, **kw: 'Any') -> 'Compiled'
| Compile this SQL expression.
|
| The return value is a :class:`~.Compiled` object.
| Calling ``str()`` or ``unicode()`` on the returned value will yield a
| string representation of the result. The
| :class:`~.Compiled` object also can return a
| dictionary of bind parameter names and values
| using the ``params`` accessor.
|
| :param bind: An :class:`.Connection` or :class:`.Engine` which
| can provide a :class:`.Dialect` in order to generate a
| :class:`.Compiled` object. If the ``bind`` and
| ``dialect`` parameters are both omitted, a default SQL compiler
| is used.
|
| :param column_keys: Used for INSERT and UPDATE statements, a list of
| column names which should be present in the VALUES clause of the
| compiled statement. If ``None``, all columns from the target table
| object are rendered.
|
| :param dialect: A :class:`.Dialect` instance which can generate
| a :class:`.Compiled` object. This argument takes precedence over
| the ``bind`` argument.
|
| :param compile_kwargs: optional dictionary of additional parameters
| that will be passed through to the compiler within all "visit"
| methods. This allows any custom flag to be passed through to
| a custom compilation construct, for example. It is also used
| for the case of passing the ``literal_binds`` flag through::
|
| from sqlalchemy.sql import table, column, select
|
| t = table("t", column("x"))
|
| s = select(t).where(t.c.x == 5)
|
| print(s.compile(compile_kwargs={"literal_binds": True}))
|
| .. seealso::
|
| :ref:`faq_sql_expression_string`
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.elements.CompilerElement:
|
| stringify_dialect = 'default'
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.visitors.Visitable:
|
| __class_getitem__(key: 'Any') -> 'Any'
|
| __init_subclass__() -> 'None'
| This method is called when a class is subclassed.
|
| The default implementation does nothing. It may be
| overridden to extend subclasses.
sqlalchemy.UpdateBase
Python Library Documentation: class UpdateBase in module sqlalchemy.sql.dml
class UpdateBase(sqlalchemy.sql.roles.DMLRole, sqlalchemy.sql.selectable.HasCTE, sqlalchemy.sql.base.HasCompileState, sqlalchemy.sql.base.DialectKWArgs, sqlalchemy.sql.selectable.HasPrefixes, sqlalchemy.sql.base.Generative, sqlalchemy.sql.selectable.ExecutableReturnsRows, sqlalchemy.sql.elements.ClauseElement)
| Form the base for ``INSERT``, ``UPDATE``, and ``DELETE`` statements.
|
| Method resolution order:
| UpdateBase
| sqlalchemy.sql.roles.DMLRole
| sqlalchemy.sql.selectable.HasCTE
| sqlalchemy.sql.roles.HasCTERole
| sqlalchemy.sql.selectable.SelectsRows
| sqlalchemy.sql.base.HasCompileState
| sqlalchemy.sql.base.DialectKWArgs
| sqlalchemy.sql.selectable.HasPrefixes
| sqlalchemy.sql.base.Generative
| sqlalchemy.sql.selectable.ExecutableReturnsRows
| sqlalchemy.sql.base.Executable
| sqlalchemy.sql.roles.StatementRole
| sqlalchemy.sql.selectable.ReturnsRows
| sqlalchemy.sql.roles.ReturnsRowsRole
| sqlalchemy.sql.roles.SQLRole
| sqlalchemy.sql.elements.DQLDMLClauseElement
| sqlalchemy.sql.elements.ClauseElement
| sqlalchemy.sql.annotation.SupportsWrappingAnnotations
| sqlalchemy.sql.annotation.SupportsAnnotations
| sqlalchemy.sql.cache_key.MemoizedHasCacheKey
| sqlalchemy.sql.cache_key.HasCacheKey
| sqlalchemy.util.langhelpers.HasMemoized
| sqlalchemy.sql.traversals.HasCopyInternals
| sqlalchemy.sql.visitors.ExternallyTraversible
| sqlalchemy.sql.visitors.HasTraverseInternals
| sqlalchemy.sql.elements.CompilerElement
| sqlalchemy.sql.visitors.Visitable
| builtins.object
|
| Methods defined here:
|
| corresponding_column(self, column: 'KeyedColumnElement[Any]', require_embedded: 'bool' = False) -> 'Optional[ColumnElement[Any]]'
|
| exported_columns(...)
| Return the RETURNING columns as a column collection for this
| statement.
|
| .. versionadded:: 1.4
|
| is_derived_from(self, fromclause: 'Optional[FromClause]') -> 'bool'
| Return ``True`` if this :class:`.ReturnsRows` is
| 'derived' from the given :class:`.FromClause`.
|
| Since these are DMLs, we dont want such statements ever being adapted
| so we return False for derives.
|
| params(self, *arg: 'Any', **kw: 'Any') -> 'NoReturn'
| Set the parameters for the statement.
|
| This method raises ``NotImplementedError`` on the base class,
| and is overridden by :class:`.ValuesBase` to provide the
| SET/VALUES clause of UPDATE and INSERT.
|
| return_defaults(self, *cols: '_DMLColumnArgument', supplemental_cols: 'Optional[Iterable[_DMLColumnArgument]]' = None, sort_by_parameter_order: 'bool' = False) -> 'Self'
| Make use of a :term:`RETURNING` clause for the purpose
| of fetching server-side expressions and defaults, for supporting
| backends only.
|
| .. deepalchemy::
|
| The :meth:`.UpdateBase.return_defaults` method is used by the ORM
| for its internal work in fetching newly generated primary key
| and server default values, in particular to provide the underlying
| implementation of the :paramref:`_orm.Mapper.eager_defaults`
| ORM feature as well as to allow RETURNING support with bulk
| ORM inserts. Its behavior is fairly idiosyncratic
| and is not really intended for general use. End users should
| stick with using :meth:`.UpdateBase.returning` in order to
| add RETURNING clauses to their INSERT, UPDATE and DELETE
| statements.
|
| Normally, a single row INSERT statement will automatically populate the
| :attr:`.CursorResult.inserted_primary_key` attribute when executed,
| which stores the primary key of the row that was just inserted in the
| form of a :class:`.Row` object with column names as named tuple keys
| (and the :attr:`.Row._mapping` view fully populated as well). The
| dialect in use chooses the strategy to use in order to populate this
| data; if it was generated using server-side defaults and / or SQL
| expressions, dialect-specific approaches such as ``cursor.lastrowid``
| or ``RETURNING`` are typically used to acquire the new primary key
| value.
|
| However, when the statement is modified by calling
| :meth:`.UpdateBase.return_defaults` before executing the statement,
| additional behaviors take place **only** for backends that support
| RETURNING and for :class:`.Table` objects that maintain the
| :paramref:`.Table.implicit_returning` parameter at its default value of
| ``True``. In these cases, when the :class:`.CursorResult` is returned
| from the statement's execution, not only will
| :attr:`.CursorResult.inserted_primary_key` be populated as always, the
| :attr:`.CursorResult.returned_defaults` attribute will also be
| populated with a :class:`.Row` named-tuple representing the full range
| of server generated
| values from that single row, including values for any columns that
| specify :paramref:`_schema.Column.server_default` or which make use of
| :paramref:`_schema.Column.default` using a SQL expression.
|
| When invoking INSERT statements with multiple rows using
| :ref:`insertmanyvalues <engine_insertmanyvalues>`, the
| :meth:`.UpdateBase.return_defaults` modifier will have the effect of
| the :attr:`_engine.CursorResult.inserted_primary_key_rows` and
| :attr:`_engine.CursorResult.returned_defaults_rows` attributes being
| fully populated with lists of :class:`.Row` objects representing newly
| inserted primary key values as well as newly inserted server generated
| values for each row inserted. The
| :attr:`.CursorResult.inserted_primary_key` and
| :attr:`.CursorResult.returned_defaults` attributes will also continue
| to be populated with the first row of these two collections.
|
| If the backend does not support RETURNING or the :class:`.Table` in use
| has disabled :paramref:`.Table.implicit_returning`, then no RETURNING
| clause is added and no additional data is fetched, however the
| INSERT, UPDATE or DELETE statement proceeds normally.
|
| E.g.::
|
| stmt = table.insert().values(data="newdata").return_defaults()
|
| result = connection.execute(stmt)
|
| server_created_at = result.returned_defaults["created_at"]
|
| When used against an UPDATE statement
| :meth:`.UpdateBase.return_defaults` instead looks for columns that
| include :paramref:`_schema.Column.onupdate` or
| :paramref:`_schema.Column.server_onupdate` parameters assigned, when
| constructing the columns that will be included in the RETURNING clause
| by default if explicit columns were not specified. When used against a
| DELETE statement, no columns are included in RETURNING by default, they
| instead must be specified explicitly as there are no columns that
| normally change values when a DELETE statement proceeds.
|
| .. versionadded:: 2.0 :meth:`.UpdateBase.return_defaults` is supported
| for DELETE statements also and has been moved from
| :class:`.ValuesBase` to :class:`.UpdateBase`.
|
| The :meth:`.UpdateBase.return_defaults` method is mutually exclusive
| against the :meth:`.UpdateBase.returning` method and errors will be
| raised during the SQL compilation process if both are used at the same
| time on one statement. The RETURNING clause of the INSERT, UPDATE or
| DELETE statement is therefore controlled by only one of these methods
| at a time.
|
| The :meth:`.UpdateBase.return_defaults` method differs from
| :meth:`.UpdateBase.returning` in these ways:
|
| 1. :meth:`.UpdateBase.return_defaults` method causes the
| :attr:`.CursorResult.returned_defaults` collection to be populated
| with the first row from the RETURNING result. This attribute is not
| populated when using :meth:`.UpdateBase.returning`.
|
| 2. :meth:`.UpdateBase.return_defaults` is compatible with existing
| logic used to fetch auto-generated primary key values that are then
| populated into the :attr:`.CursorResult.inserted_primary_key`
| attribute. By contrast, using :meth:`.UpdateBase.returning` will
| have the effect of the :attr:`.CursorResult.inserted_primary_key`
| attribute being left unpopulated.
|
| 3. :meth:`.UpdateBase.return_defaults` can be called against any
| backend. Backends that don't support RETURNING will skip the usage
| of the feature, rather than raising an exception, *unless*
| ``supplemental_cols`` is passed. The return value
| of :attr:`_engine.CursorResult.returned_defaults` will be ``None``
| for backends that don't support RETURNING or for which the target
| :class:`.Table` sets :paramref:`.Table.implicit_returning` to
| ``False``.
|
| 4. An INSERT statement invoked with executemany() is supported if the
| backend database driver supports the
| :ref:`insertmanyvalues <engine_insertmanyvalues>`
| feature which is now supported by most SQLAlchemy-included backends.
| When executemany is used, the
| :attr:`_engine.CursorResult.returned_defaults_rows` and
| :attr:`_engine.CursorResult.inserted_primary_key_rows` accessors
| will return the inserted defaults and primary keys.
|
| .. versionadded:: 1.4 Added
| :attr:`_engine.CursorResult.returned_defaults_rows` and
| :attr:`_engine.CursorResult.inserted_primary_key_rows` accessors.
| In version 2.0, the underlying implementation which fetches and
| populates the data for these attributes was generalized to be
| supported by most backends, whereas in 1.4 they were only
| supported by the ``psycopg2`` driver.
|
|
| :param cols: optional list of column key names or
| :class:`_schema.Column` that acts as a filter for those columns that
| will be fetched.
| :param supplemental_cols: optional list of RETURNING expressions,
| in the same form as one would pass to the
| :meth:`.UpdateBase.returning` method. When present, the additional
| columns will be included in the RETURNING clause, and the
| :class:`.CursorResult` object will be "rewound" when returned, so
| that methods like :meth:`.CursorResult.all` will return new rows
| mostly as though the statement used :meth:`.UpdateBase.returning`
| directly. However, unlike when using :meth:`.UpdateBase.returning`
| directly, the **order of the columns is undefined**, so can only be
| targeted using names or :attr:`.Row._mapping` keys; they cannot
| reliably be targeted positionally.
|
| .. versionadded:: 2.0
|
| :param sort_by_parameter_order: for a batch INSERT that is being
| executed against multiple parameter sets, organize the results of
| RETURNING so that the returned rows correspond to the order of
| parameter sets passed in. This applies only to an :term:`executemany`
| execution for supporting dialects and typically makes use of the
| :term:`insertmanyvalues` feature.
|
| .. versionadded:: 2.0.10
|
| .. seealso::
|
| :ref:`engine_insertmanyvalues_returning_order` - background on
| sorting of RETURNING rows for bulk INSERT
|
| .. seealso::
|
| :meth:`.UpdateBase.returning`
|
| :attr:`_engine.CursorResult.returned_defaults`
|
| :attr:`_engine.CursorResult.returned_defaults_rows`
|
| :attr:`_engine.CursorResult.inserted_primary_key`
|
| :attr:`_engine.CursorResult.inserted_primary_key_rows`
|
| returning(self, *cols: '_ColumnsClauseArgument[Any]', sort_by_parameter_order: 'bool' = False, **_UpdateBase__kw: 'Any') -> 'UpdateBase'
| Add a :term:`RETURNING` or equivalent clause to this statement.
|
| e.g.:
|
| .. sourcecode:: pycon+sql
|
| >>> stmt = (
| ... table.update()
| ... .where(table.c.data == "value")
| ... .values(status="X")
| ... .returning(table.c.server_flag, table.c.updated_timestamp)
| ... )
| >>> print(stmt)
| {printsql}UPDATE some_table SET status=:status
| WHERE some_table.data = :data_1
| RETURNING some_table.server_flag, some_table.updated_timestamp
|
| The method may be invoked multiple times to add new entries to the
| list of expressions to be returned.
|
| .. versionadded:: 1.4.0b2 The method may be invoked multiple times to
| add new entries to the list of expressions to be returned.
|
| The given collection of column expressions should be derived from the
| table that is the target of the INSERT, UPDATE, or DELETE. While
| :class:`_schema.Column` objects are typical, the elements can also be
| expressions:
|
| .. sourcecode:: pycon+sql
|
| >>> stmt = table.insert().returning(
| ... (table.c.first_name + " " + table.c.last_name).label("fullname")
| ... )
| >>> print(stmt)
| {printsql}INSERT INTO some_table (first_name, last_name)
| VALUES (:first_name, :last_name)
| RETURNING some_table.first_name || :first_name_1 || some_table.last_name AS fullname
|
| Upon compilation, a RETURNING clause, or database equivalent,
| will be rendered within the statement. For INSERT and UPDATE,
| the values are the newly inserted/updated values. For DELETE,
| the values are those of the rows which were deleted.
|
| Upon execution, the values of the columns to be returned are made
| available via the result set and can be iterated using
| :meth:`_engine.CursorResult.fetchone` and similar.
| For DBAPIs which do not
| natively support returning values (i.e. cx_oracle), SQLAlchemy will
| approximate this behavior at the result level so that a reasonable
| amount of behavioral neutrality is provided.
|
| Note that not all databases/DBAPIs
| support RETURNING. For those backends with no support,
| an exception is raised upon compilation and/or execution.
| For those who do support it, the functionality across backends
| varies greatly, including restrictions on executemany()
| and other statements which return multiple rows. Please
| read the documentation notes for the database in use in
| order to determine the availability of RETURNING.
|
| :param \*cols: series of columns, SQL expressions, or whole tables
| entities to be returned.
| :param sort_by_parameter_order: for a batch INSERT that is being
| executed against multiple parameter sets, organize the results of
| RETURNING so that the returned rows correspond to the order of
| parameter sets passed in. This applies only to an :term:`executemany`
| execution for supporting dialects and typically makes use of the
| :term:`insertmanyvalues` feature.
|
| .. versionadded:: 2.0.10
|
| .. seealso::
|
| :ref:`engine_insertmanyvalues_returning_order` - background on
| sorting of RETURNING rows for bulk INSERT (Core level discussion)
|
| :ref:`orm_queryguide_bulk_insert_returning_ordered` - example of
| use with :ref:`orm_queryguide_bulk_insert` (ORM level discussion)
|
| .. seealso::
|
| :meth:`.UpdateBase.return_defaults` - an alternative method tailored
| towards efficient fetching of server-side defaults and triggers
| for single-row INSERTs or UPDATEs.
|
| :ref:`tutorial_insert_returning` - in the :ref:`unified_tutorial`
|
| with_dialect_options(self, **opt: 'Any') -> 'Self'
| Add dialect options to this INSERT/UPDATE/DELETE object.
|
| e.g.::
|
| upd = table.update().dialect_options(mysql_limit=10)
|
| .. versionadded: 1.4 - this method supersedes the dialect options
| associated with the constructor.
|
| with_hint(self, text: 'str', selectable: 'Optional[_DMLTableArgument]' = None, dialect_name: 'str' = '*') -> 'Self'
| Add a table hint for a single table to this
| INSERT/UPDATE/DELETE statement.
|
| .. note::
|
| :meth:`.UpdateBase.with_hint` currently applies only to
| Microsoft SQL Server. For MySQL INSERT/UPDATE/DELETE hints, use
| :meth:`.UpdateBase.prefix_with`.
|
| The text of the hint is rendered in the appropriate
| location for the database backend in use, relative
| to the :class:`_schema.Table` that is the subject of this
| statement, or optionally to that of the given
| :class:`_schema.Table` passed as the ``selectable`` argument.
|
| The ``dialect_name`` option will limit the rendering of a particular
| hint to a particular backend. Such as, to add a hint
| that only takes effect for SQL Server::
|
| mytable.insert().with_hint("WITH (PAGLOCK)", dialect_name="mssql")
|
| :param text: Text of the hint.
| :param selectable: optional :class:`_schema.Table` that specifies
| an element of the FROM clause within an UPDATE or DELETE
| to be the subject of the hint - applies only to certain backends.
| :param dialect_name: defaults to ``*``, if specified as the name
| of a particular dialect, will apply these hints only when
| that dialect is in use.
|
| ----------------------------------------------------------------------
| Readonly properties defined here:
|
| entity_description
| Return a :term:`plugin-enabled` description of the table and/or
| entity which this DML construct is operating against.
|
| This attribute is generally useful when using the ORM, as an
| extended structure which includes information about mapped
| entities is returned. The section :ref:`queryguide_inspection`
| contains more background.
|
| For a Core statement, the structure returned by this accessor
| is derived from the :attr:`.UpdateBase.table` attribute, and
| refers to the :class:`.Table` being inserted, updated, or deleted::
|
| >>> stmt = insert(user_table)
| >>> stmt.entity_description
| {
| "name": "user_table",
| "table": Table("user_table", ...)
| }
|
| .. versionadded:: 1.4.33
|
| .. seealso::
|
| :attr:`.UpdateBase.returning_column_descriptions`
|
| :attr:`.Select.column_descriptions` - entity information for
| a :func:`.select` construct
|
| :ref:`queryguide_inspection` - ORM background
|
| returning_column_descriptions
| Return a :term:`plugin-enabled` description of the columns
| which this DML construct is RETURNING against, in other words
| the expressions established as part of :meth:`.UpdateBase.returning`.
|
| This attribute is generally useful when using the ORM, as an
| extended structure which includes information about mapped
| entities is returned. The section :ref:`queryguide_inspection`
| contains more background.
|
| For a Core statement, the structure returned by this accessor is
| derived from the same objects that are returned by the
| :attr:`.UpdateBase.exported_columns` accessor::
|
| >>> stmt = insert(user_table).returning(user_table.c.id, user_table.c.name)
| >>> stmt.entity_description
| [
| {
| "name": "id",
| "type": Integer,
| "expr": Column("id", Integer(), table=<user>, ...)
| },
| {
| "name": "name",
| "type": String(),
| "expr": Column("name", String(), table=<user>, ...)
| },
| ]
|
| .. versionadded:: 1.4.33
|
| .. seealso::
|
| :attr:`.UpdateBase.entity_description`
|
| :attr:`.Select.column_descriptions` - entity information for
| a :func:`.select` construct
|
| :ref:`queryguide_inspection` - ORM background
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'_hints': 'util.immutabledict[Tuple[_DMLTableElemen...
|
| __visit_name__ = 'update_base'
|
| is_dml = True
|
| named_with_column = False
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.selectable.HasCTE:
|
| add_cte(self, *ctes: 'CTE', nest_here: 'bool' = False) -> 'Self'
| Add one or more :class:`_sql.CTE` constructs to this statement.
|
| This method will associate the given :class:`_sql.CTE` constructs with
| the parent statement such that they will each be unconditionally
| rendered in the WITH clause of the final statement, even if not
| referenced elsewhere within the statement or any sub-selects.
|
| The optional :paramref:`.HasCTE.add_cte.nest_here` parameter when set
| to True will have the effect that each given :class:`_sql.CTE` will
| render in a WITH clause rendered directly along with this statement,
| rather than being moved to the top of the ultimate rendered statement,
| even if this statement is rendered as a subquery within a larger
| statement.
|
| This method has two general uses. One is to embed CTE statements that
| serve some purpose without being referenced explicitly, such as the use
| case of embedding a DML statement such as an INSERT or UPDATE as a CTE
| inline with a primary statement that may draw from its results
| indirectly. The other is to provide control over the exact placement
| of a particular series of CTE constructs that should remain rendered
| directly in terms of a particular statement that may be nested in a
| larger statement.
|
| E.g.::
|
| from sqlalchemy import table, column, select
|
| t = table("t", column("c1"), column("c2"))
|
| ins = t.insert().values({"c1": "x", "c2": "y"}).cte()
|
| stmt = select(t).add_cte(ins)
|
| Would render:
|
| .. sourcecode:: sql
|
| WITH anon_1 AS (
| INSERT INTO t (c1, c2) VALUES (:param_1, :param_2)
| )
| SELECT t.c1, t.c2
| FROM t
|
| Above, the "anon_1" CTE is not referenced in the SELECT
| statement, however still accomplishes the task of running an INSERT
| statement.
|
| Similarly in a DML-related context, using the PostgreSQL
| :class:`_postgresql.Insert` construct to generate an "upsert"::
|
| from sqlalchemy import table, column
| from sqlalchemy.dialects.postgresql import insert
|
| t = table("t", column("c1"), column("c2"))
|
| delete_statement_cte = t.delete().where(t.c.c1 < 1).cte("deletions")
|
| insert_stmt = insert(t).values({"c1": 1, "c2": 2})
| update_statement = insert_stmt.on_conflict_do_update(
| index_elements=[t.c.c1],
| set_={
| "c1": insert_stmt.excluded.c1,
| "c2": insert_stmt.excluded.c2,
| },
| ).add_cte(delete_statement_cte)
|
| print(update_statement)
|
| The above statement renders as:
|
| .. sourcecode:: sql
|
| WITH deletions AS (
| DELETE FROM t WHERE t.c1 < %(c1_1)s
| )
| INSERT INTO t (c1, c2) VALUES (%(c1)s, %(c2)s)
| ON CONFLICT (c1) DO UPDATE SET c1 = excluded.c1, c2 = excluded.c2
|
| .. versionadded:: 1.4.21
|
| :param \*ctes: zero or more :class:`.CTE` constructs.
|
| .. versionchanged:: 2.0 Multiple CTE instances are accepted
|
| :param nest_here: if True, the given CTE or CTEs will be rendered
| as though they specified the :paramref:`.HasCTE.cte.nesting` flag
| to ``True`` when they were added to this :class:`.HasCTE`.
| Assuming the given CTEs are not referenced in an outer-enclosing
| statement as well, the CTEs given should render at the level of
| this statement when this flag is given.
|
| .. versionadded:: 2.0
|
| .. seealso::
|
| :paramref:`.HasCTE.cte.nesting`
|
| cte(self, name: 'Optional[str]' = None, recursive: 'bool' = False, nesting: 'bool' = False) -> 'CTE'
| Return a new :class:`_expression.CTE`,
| or Common Table Expression instance.
|
| Common table expressions are a SQL standard whereby SELECT
| statements can draw upon secondary statements specified along
| with the primary statement, using a clause called "WITH".
| Special semantics regarding UNION can also be employed to
| allow "recursive" queries, where a SELECT statement can draw
| upon the set of rows that have previously been selected.
|
| CTEs can also be applied to DML constructs UPDATE, INSERT
| and DELETE on some databases, both as a source of CTE rows
| when combined with RETURNING, as well as a consumer of
| CTE rows.
|
| SQLAlchemy detects :class:`_expression.CTE` objects, which are treated
| similarly to :class:`_expression.Alias` objects, as special elements
| to be delivered to the FROM clause of the statement as well
| as to a WITH clause at the top of the statement.
|
| For special prefixes such as PostgreSQL "MATERIALIZED" and
| "NOT MATERIALIZED", the :meth:`_expression.CTE.prefix_with`
| method may be
| used to establish these.
|
| .. versionchanged:: 1.3.13 Added support for prefixes.
| In particular - MATERIALIZED and NOT MATERIALIZED.
|
| :param name: name given to the common table expression. Like
| :meth:`_expression.FromClause.alias`, the name can be left as
| ``None`` in which case an anonymous symbol will be used at query
| compile time.
| :param recursive: if ``True``, will render ``WITH RECURSIVE``.
| A recursive common table expression is intended to be used in
| conjunction with UNION ALL in order to derive rows
| from those already selected.
| :param nesting: if ``True``, will render the CTE locally to the
| statement in which it is referenced. For more complex scenarios,
| the :meth:`.HasCTE.add_cte` method using the
| :paramref:`.HasCTE.add_cte.nest_here`
| parameter may also be used to more carefully
| control the exact placement of a particular CTE.
|
| .. versionadded:: 1.4.24
|
| .. seealso::
|
| :meth:`.HasCTE.add_cte`
|
| The following examples include two from PostgreSQL's documentation at
| https://www.postgresql.org/docs/current/static/queries-with.html,
| as well as additional examples.
|
| Example 1, non recursive::
|
| from sqlalchemy import (
| Table,
| Column,
| String,
| Integer,
| MetaData,
| select,
| func,
| )
|
| metadata = MetaData()
|
| orders = Table(
| "orders",
| metadata,
| Column("region", String),
| Column("amount", Integer),
| Column("product", String),
| Column("quantity", Integer),
| )
|
| regional_sales = (
| select(orders.c.region, func.sum(orders.c.amount).label("total_sales"))
| .group_by(orders.c.region)
| .cte("regional_sales")
| )
|
|
| top_regions = (
| select(regional_sales.c.region)
| .where(
| regional_sales.c.total_sales
| > select(func.sum(regional_sales.c.total_sales) / 10)
| )
| .cte("top_regions")
| )
|
| statement = (
| select(
| orders.c.region,
| orders.c.product,
| func.sum(orders.c.quantity).label("product_units"),
| func.sum(orders.c.amount).label("product_sales"),
| )
| .where(orders.c.region.in_(select(top_regions.c.region)))
| .group_by(orders.c.region, orders.c.product)
| )
|
| result = conn.execute(statement).fetchall()
|
| Example 2, WITH RECURSIVE::
|
| from sqlalchemy import (
| Table,
| Column,
| String,
| Integer,
| MetaData,
| select,
| func,
| )
|
| metadata = MetaData()
|
| parts = Table(
| "parts",
| metadata,
| Column("part", String),
| Column("sub_part", String),
| Column("quantity", Integer),
| )
|
| included_parts = (
| select(parts.c.sub_part, parts.c.part, parts.c.quantity)
| .where(parts.c.part == "our part")
| .cte(recursive=True)
| )
|
|
| incl_alias = included_parts.alias()
| parts_alias = parts.alias()
| included_parts = included_parts.union_all(
| select(
| parts_alias.c.sub_part, parts_alias.c.part, parts_alias.c.quantity
| ).where(parts_alias.c.part == incl_alias.c.sub_part)
| )
|
| statement = select(
| included_parts.c.sub_part,
| func.sum(included_parts.c.quantity).label("total_quantity"),
| ).group_by(included_parts.c.sub_part)
|
| result = conn.execute(statement).fetchall()
|
| Example 3, an upsert using UPDATE and INSERT with CTEs::
|
| from datetime import date
| from sqlalchemy import (
| MetaData,
| Table,
| Column,
| Integer,
| Date,
| select,
| literal,
| and_,
| exists,
| )
|
| metadata = MetaData()
|
| visitors = Table(
| "visitors",
| metadata,
| Column("product_id", Integer, primary_key=True),
| Column("date", Date, primary_key=True),
| Column("count", Integer),
| )
|
| # add 5 visitors for the product_id == 1
| product_id = 1
| day = date.today()
| count = 5
|
| update_cte = (
| visitors.update()
| .where(
| and_(visitors.c.product_id == product_id, visitors.c.date == day)
| )
| .values(count=visitors.c.count + count)
| .returning(literal(1))
| .cte("update_cte")
| )
|
| upsert = visitors.insert().from_select(
| [visitors.c.product_id, visitors.c.date, visitors.c.count],
| select(literal(product_id), literal(day), literal(count)).where(
| ~exists(update_cte.select())
| ),
| )
|
| connection.execute(upsert)
|
| Example 4, Nesting CTE (SQLAlchemy 1.4.24 and above)::
|
| value_a = select(literal("root").label("n")).cte("value_a")
|
| # A nested CTE with the same name as the root one
| value_a_nested = select(literal("nesting").label("n")).cte(
| "value_a", nesting=True
| )
|
| # Nesting CTEs takes ascendency locally
| # over the CTEs at a higher level
| value_b = select(value_a_nested.c.n).cte("value_b")
|
| value_ab = select(value_a.c.n.label("a"), value_b.c.n.label("b"))
|
| The above query will render the second CTE nested inside the first,
| shown with inline parameters below as:
|
| .. sourcecode:: sql
|
| WITH
| value_a AS
| (SELECT 'root' AS n),
| value_b AS
| (WITH value_a AS
| (SELECT 'nesting' AS n)
| SELECT value_a.n AS n FROM value_a)
| SELECT value_a.n AS a, value_b.n AS b
| FROM value_a, value_b
|
| The same CTE can be set up using the :meth:`.HasCTE.add_cte` method
| as follows (SQLAlchemy 2.0 and above)::
|
| value_a = select(literal("root").label("n")).cte("value_a")
|
| # A nested CTE with the same name as the root one
| value_a_nested = select(literal("nesting").label("n")).cte("value_a")
|
| # Nesting CTEs takes ascendency locally
| # over the CTEs at a higher level
| value_b = (
| select(value_a_nested.c.n)
| .add_cte(value_a_nested, nest_here=True)
| .cte("value_b")
| )
|
| value_ab = select(value_a.c.n.label("a"), value_b.c.n.label("b"))
|
| Example 5, Non-Linear CTE (SQLAlchemy 1.4.28 and above)::
|
| edge = Table(
| "edge",
| metadata,
| Column("id", Integer, primary_key=True),
| Column("left", Integer),
| Column("right", Integer),
| )
|
| root_node = select(literal(1).label("node")).cte("nodes", recursive=True)
|
| left_edge = select(edge.c.left).join(
| root_node, edge.c.right == root_node.c.node
| )
| right_edge = select(edge.c.right).join(
| root_node, edge.c.left == root_node.c.node
| )
|
| subgraph_cte = root_node.union(left_edge, right_edge)
|
| subgraph = select(subgraph_cte)
|
| The above query will render 2 UNIONs inside the recursive CTE:
|
| .. sourcecode:: sql
|
| WITH RECURSIVE nodes(node) AS (
| SELECT 1 AS node
| UNION
| SELECT edge."left" AS "left"
| FROM edge JOIN nodes ON edge."right" = nodes.node
| UNION
| SELECT edge."right" AS "right"
| FROM edge JOIN nodes ON edge."left" = nodes.node
| )
| SELECT nodes.node FROM nodes
|
| .. seealso::
|
| :meth:`_orm.Query.cte` - ORM version of
| :meth:`_expression.HasCTE.cte`.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.selectable.HasCTE:
|
| name_cte_columns = False
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.base.DialectKWArgs:
|
| dialect_options(...)
| A collection of keyword arguments specified as dialect-specific
| options to this construct.
|
| This is a two-level nested registry, keyed to ``<dialect_name>``
| and ``<argument_name>``. For example, the ``postgresql_where``
| argument would be locatable as::
|
| arg = my_object.dialect_options["postgresql"]["where"]
|
| .. versionadded:: 0.9.2
|
| .. seealso::
|
| :attr:`.DialectKWArgs.dialect_kwargs` - flat dictionary form
|
| get_dialect_option(self, dialect: 'Dialect', argument_name: 'str', *, else_: 'Any' = None, deprecated_fallback: 'Optional[str]' = None) -> 'Any'
| Return the value of a dialect-specific option, or *else_* if
| this dialect does not register the given argument.
|
| This is useful for DDL compilers that may be inherited by
| third-party dialects whose ``construct_arguments`` do not
| include the same set of keys as the parent dialect.
|
| :param dialect: The dialect for which to retrieve the option.
| :param argument_name: The name of the argument to retrieve.
| :param else\_: The value to return if the argument is not present.
| :param deprecated_fallback: Optional dialect name to fall back to
| if the argument is not present for the current dialect. If the
| argument is present for the fallback dialect but not the current
| dialect, a deprecation warning will be emitted.
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.base.DialectKWArgs:
|
| argument_for(dialect_name: 'str', argument_name: 'str', default: 'Any') -> 'None'
| Add a new kind of dialect-specific keyword argument for this class.
|
| E.g.::
|
| Index.argument_for("mydialect", "length", None)
|
| some_index = Index("a", "b", mydialect_length=5)
|
| The :meth:`.DialectKWArgs.argument_for` method is a per-argument
| way adding extra arguments to the
| :attr:`.DefaultDialect.construct_arguments` dictionary. This
| dictionary provides a list of argument names accepted by various
| schema-level constructs on behalf of a dialect.
|
| New dialects should typically specify this dictionary all at once as a
| data member of the dialect class. The use case for ad-hoc addition of
| argument names is typically for end-user code that is also using
| a custom compilation scheme which consumes the additional arguments.
|
| :param dialect_name: name of a dialect. The dialect must be
| locatable, else a :class:`.NoSuchModuleError` is raised. The
| dialect must also include an existing
| :attr:`.DefaultDialect.construct_arguments` collection, indicating
| that it participates in the keyword-argument validation and default
| system, else :class:`.ArgumentError` is raised. If the dialect does
| not include this collection, then any keyword argument can be
| specified on behalf of this dialect already. All dialects packaged
| within SQLAlchemy include this collection, however for third party
| dialects, support may vary.
|
| :param argument_name: name of the parameter.
|
| :param default: default value of the parameter.
|
| ----------------------------------------------------------------------
| Readonly properties inherited from sqlalchemy.sql.base.DialectKWArgs:
|
| dialect_kwargs
| A collection of keyword arguments specified as dialect-specific
| options to this construct.
|
| The arguments are present here in their original ``<dialect>_<kwarg>``
| format. Only arguments that were actually passed are included;
| unlike the :attr:`.DialectKWArgs.dialect_options` collection, which
| contains all options known by this dialect including defaults.
|
| The collection is also writable; keys are accepted of the
| form ``<dialect>_<kwarg>`` where the value will be assembled
| into the list of options.
|
| .. seealso::
|
| :attr:`.DialectKWArgs.dialect_options` - nested dictionary form
|
| kwargs
| A synonym for :attr:`.DialectKWArgs.dialect_kwargs`.
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.selectable.HasPrefixes:
|
| prefix_with(self, *prefixes: '_TextCoercedExpressionArgument[Any]', dialect: 'str' = '*') -> 'Self'
| 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.
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.base.Executable:
|
| execution_options(self, **kw: 'Any') -> 'Self'
| Set non-SQL options for the statement which take effect during
| execution.
|
| Execution options can be set at many scopes, including per-statement,
| per-connection, or per execution, using methods such as
| :meth:`_engine.Connection.execution_options` and parameters which
| accept a dictionary of options such as
| :paramref:`_engine.Connection.execute.execution_options` and
| :paramref:`_orm.Session.execute.execution_options`.
|
| The primary characteristic of an execution option, as opposed to
| other kinds of options such as ORM loader options, is that
| **execution options never affect the compiled SQL of a query, only
| things that affect how the SQL statement itself is invoked or how
| results are fetched**. That is, execution options are not part of
| what's accommodated by SQL compilation nor are they considered part of
| the cached state of a statement.
|
| The :meth:`_sql.Executable.execution_options` method is
| :term:`generative`, as
| is the case for the method as applied to the :class:`_engine.Engine`
| and :class:`_orm.Query` objects, which means when the method is called,
| a copy of the object is returned, which applies the given parameters to
| that new copy, but leaves the original unchanged::
|
| statement = select(table.c.x, table.c.y)
| new_statement = statement.execution_options(my_option=True)
|
| An exception to this behavior is the :class:`_engine.Connection`
| object, where the :meth:`_engine.Connection.execution_options` method
| is explicitly **not** generative.
|
| The kinds of options that may be passed to
| :meth:`_sql.Executable.execution_options` and other related methods and
| parameter dictionaries include parameters that are explicitly consumed
| by SQLAlchemy Core or ORM, as well as arbitrary keyword arguments not
| defined by SQLAlchemy, which means the methods and/or parameter
| dictionaries may be used for user-defined parameters that interact with
| custom code, which may access the parameters using methods such as
| :meth:`_sql.Executable.get_execution_options` and
| :meth:`_engine.Connection.get_execution_options`, or within selected
| event hooks using a dedicated ``execution_options`` event parameter
| such as
| :paramref:`_events.ConnectionEvents.before_execute.execution_options`
| or :attr:`_orm.ORMExecuteState.execution_options`, e.g.::
|
| from sqlalchemy import event
|
|
| @event.listens_for(some_engine, "before_execute")
| def _process_opt(conn, statement, multiparams, params, execution_options):
| "run a SQL function before invoking a statement"
|
| if execution_options.get("do_special_thing", False):
| conn.exec_driver_sql("run_special_function()")
|
| Within the scope of options that are explicitly recognized by
| SQLAlchemy, most apply to specific classes of objects and not others.
| The most common execution options include:
|
| * :paramref:`_engine.Connection.execution_options.isolation_level` -
| sets the isolation level for a connection or a class of connections
| via an :class:`_engine.Engine`. This option is accepted only
| by :class:`_engine.Connection` or :class:`_engine.Engine`.
|
| * :paramref:`_engine.Connection.execution_options.stream_results` -
| indicates results should be fetched using a server side cursor;
| this option is accepted by :class:`_engine.Connection`, by the
| :paramref:`_engine.Connection.execute.execution_options` parameter
| on :meth:`_engine.Connection.execute`, and additionally by
| :meth:`_sql.Executable.execution_options` on a SQL statement object,
| as well as by ORM constructs like :meth:`_orm.Session.execute`.
|
| * :paramref:`_engine.Connection.execution_options.compiled_cache` -
| indicates a dictionary that will serve as the
| :ref:`SQL compilation cache <sql_caching>`
| for a :class:`_engine.Connection` or :class:`_engine.Engine`, as
| well as for ORM methods like :meth:`_orm.Session.execute`.
| Can be passed as ``None`` to disable caching for statements.
| This option is not accepted by
| :meth:`_sql.Executable.execution_options` as it is inadvisable to
| carry along a compilation cache within a statement object.
|
| * :paramref:`_engine.Connection.execution_options.schema_translate_map`
| - a mapping of schema names used by the
| :ref:`Schema Translate Map <schema_translating>` feature, accepted
| by :class:`_engine.Connection`, :class:`_engine.Engine`,
| :class:`_sql.Executable`, as well as by ORM constructs
| like :meth:`_orm.Session.execute`.
|
| .. seealso::
|
| :meth:`_engine.Connection.execution_options`
|
| :paramref:`_engine.Connection.execute.execution_options`
|
| :paramref:`_orm.Session.execute.execution_options`
|
| :ref:`orm_queryguide_execution_options` - documentation on all
| ORM-specific execution options
|
| get_execution_options(self) -> '_ExecuteOptions'
| Get the non-SQL options which will take effect during execution.
|
| .. versionadded:: 1.3
|
| .. seealso::
|
| :meth:`.Executable.execution_options`
|
| options(self, *options: 'ExecutableOption') -> 'Self'
| Apply options to this statement.
|
| In the general sense, options are any kind of Python object
| that can be interpreted by the SQL compiler for the statement.
| These options can be consumed by specific dialects or specific kinds
| of compilers.
|
| The most commonly known kind of option are the ORM level options
| that apply "eager load" and other loading behaviors to an ORM
| query. However, options can theoretically be used for many other
| purposes.
|
| For background on specific kinds of options for specific kinds of
| statements, refer to the documentation for those option objects.
|
| .. versionchanged:: 1.4 - added :meth:`.Executable.options` to
| Core statement objects towards the goal of allowing unified
| Core / ORM querying capabilities.
|
| .. seealso::
|
| :ref:`loading_columns` - refers to options specific to the usage
| of ORM queries
|
| :ref:`relationship_loader_options` - refers to options specific
| to the usage of ORM queries
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.base.Executable:
|
| is_delete = False
|
| is_from_statement = False
|
| is_insert = False
|
| is_select = False
|
| is_text = False
|
| is_update = False
|
| supports_execution = True
|
| ----------------------------------------------------------------------
| Readonly properties inherited from sqlalchemy.sql.selectable.ReturnsRows:
|
| selectable
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.SQLRole:
|
| allows_lambda = False
|
| uses_inspection = False
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.elements.ClauseElement:
|
| __bool__(self)
|
| __getstate__(self)
| Helper for pickle.
|
| __invert__(self)
|
| __repr__(self)
| Return repr(self).
|
| compare(self, other: 'ClauseElement', **kw: 'Any') -> 'bool'
| Compare this :class:`_expression.ClauseElement` to
| the given :class:`_expression.ClauseElement`.
|
| Subclasses should override the default behavior, which is a
| straight identity comparison.
|
| \**kw are arguments consumed by subclass ``compare()`` methods and
| may be used to modify the criteria for comparison
| (see :class:`_expression.ColumnElement`).
|
| description(...)
|
| entity_namespace(...)
|
| self_group(self, against: 'Optional[OperatorType]' = None) -> 'ClauseElement'
| 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.
|
| unique_params(self, _ClauseElement__optionaldict: 'Optional[Dict[str, Any]]' = None, **kwargs: 'Any') -> 'Self'
| Return a copy with :func:`_expression.bindparam` elements
| replaced.
|
| Same functionality as :meth:`_expression.ClauseElement.params`,
| except adds `unique=True`
| to affected bind parameters so that multiple statements can be
| used.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.elements.ClauseElement:
|
| is_clause_element = True
|
| is_selectable = False
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.cache_key.HasCacheKey:
|
| inherit_cache = None
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_instancemethod(fn: '_F') -> '_F'
| Decorate a method memoize its return value.
|
| :meta private:
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_attribute = <class 'sqlalchemy.util.langhelpers.HasMemoized.m...
| A read-only @property that is only evaluated once.
|
| :meta private:
|
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.visitors.HasTraverseInternals:
|
| get_children(self, *, omit_attrs: 'Tuple[str, ...]' = (), **kw: 'Any') -> 'Iterable[HasTraverseInternals]'
| Return immediate child :class:`.visitors.HasTraverseInternals`
| elements of this :class:`.visitors.HasTraverseInternals`.
|
| This is used for visit traversal.
|
| \**kw may contain flags that change the collection that is
| returned, for example to return a subset of items in order to
| cut down on larger traversals, or to return child items from a
| different context (such as schema-level collections instead of
| clause-level).
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.elements.CompilerElement:
|
| __str__(self) -> 'str'
| Return str(self).
|
| compile(self, bind: 'Optional[_HasDialect]' = None, dialect: 'Optional[Dialect]' = None, **kw: 'Any') -> 'Compiled'
| Compile this SQL expression.
|
| The return value is a :class:`~.Compiled` object.
| Calling ``str()`` or ``unicode()`` on the returned value will yield a
| string representation of the result. The
| :class:`~.Compiled` object also can return a
| dictionary of bind parameter names and values
| using the ``params`` accessor.
|
| :param bind: An :class:`.Connection` or :class:`.Engine` which
| can provide a :class:`.Dialect` in order to generate a
| :class:`.Compiled` object. If the ``bind`` and
| ``dialect`` parameters are both omitted, a default SQL compiler
| is used.
|
| :param column_keys: Used for INSERT and UPDATE statements, a list of
| column names which should be present in the VALUES clause of the
| compiled statement. If ``None``, all columns from the target table
| object are rendered.
|
| :param dialect: A :class:`.Dialect` instance which can generate
| a :class:`.Compiled` object. This argument takes precedence over
| the ``bind`` argument.
|
| :param compile_kwargs: optional dictionary of additional parameters
| that will be passed through to the compiler within all "visit"
| methods. This allows any custom flag to be passed through to
| a custom compilation construct, for example. It is also used
| for the case of passing the ``literal_binds`` flag through::
|
| from sqlalchemy.sql import table, column, select
|
| t = table("t", column("x"))
|
| s = select(t).where(t.c.x == 5)
|
| print(s.compile(compile_kwargs={"literal_binds": True}))
|
| .. seealso::
|
| :ref:`faq_sql_expression_string`
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.elements.CompilerElement:
|
| stringify_dialect = 'default'
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.visitors.Visitable:
|
| __class_getitem__(key: 'Any') -> 'Any'
|
| __init_subclass__() -> 'None'
| This method is called when a class is subclassed.
|
| The default implementation does nothing. It may be
| overridden to extend subclasses.
sqlalchemy.Uuid
Python Library Documentation: class Uuid in module sqlalchemy.sql.sqltypes
class Uuid(sqlalchemy.sql.type_api.Emulated, sqlalchemy.sql.type_api.TypeEngine)
| Uuid(as_uuid: 'bool' = True, native_uuid: 'bool' = True)
|
| Represent a database agnostic UUID datatype.
|
| For backends that have no "native" UUID datatype, the value will
| make use of ``CHAR(32)`` and store the UUID as a 32-character alphanumeric
| hex string.
|
| For backends which are known to support ``UUID`` directly or a similar
| uuid-storing datatype such as SQL Server's ``UNIQUEIDENTIFIER``, a
| "native" mode enabled by default allows these types will be used on those
| backends.
|
| In its default mode of use, the :class:`_sqltypes.Uuid` datatype expects
| **Python uuid objects**, from the Python
| `uuid <https://docs.python.org/3/library/uuid.html>`_
| module::
|
| import uuid
|
| from sqlalchemy import Uuid
| from sqlalchemy import Table, Column, MetaData, String
|
| metadata_obj = MetaData()
|
| t = Table(
| "t",
| metadata_obj,
| Column("uuid_data", Uuid, primary_key=True),
| Column("other_data", String),
| )
|
| with engine.begin() as conn:
| conn.execute(
| t.insert(), {"uuid_data": uuid.uuid4(), "other_data": "some data"}
| )
|
| To have the :class:`_sqltypes.Uuid` datatype work with string-based
| Uuids (e.g. 32 character hexadecimal strings), pass the
| :paramref:`_sqltypes.Uuid.as_uuid` parameter with the value ``False``.
|
| .. versionadded:: 2.0
|
| .. seealso::
|
| :class:`_sqltypes.UUID` - represents exactly the ``UUID`` datatype
| without any backend-agnostic behaviors.
|
| Method resolution order:
| Uuid
| sqlalchemy.sql.type_api.Emulated
| sqlalchemy.sql.type_api.TypeEngineMixin
| sqlalchemy.sql.type_api.TypeEngine
| sqlalchemy.sql.visitors.Visitable
| typing.Generic
| builtins.object
|
| Methods defined here:
|
| __init__(self, as_uuid: 'bool' = True, native_uuid: 'bool' = True)
| Construct a :class:`_sqltypes.Uuid` type.
|
| :param as_uuid=True: if True, values will be interpreted
| as Python uuid objects, converting to/from string via the
| DBAPI.
|
| .. versionchanged: 2.0 ``as_uuid`` now defaults to ``True``.
|
| :param native_uuid=True: if True, backends that support either the
| ``UUID`` datatype directly, or a UUID-storing value
| (such as SQL Server's ``UNIQUEIDENTIFIER`` will be used by those
| backends. If False, a ``CHAR(32)`` datatype will be used for
| all backends regardless of native support.
|
| bind_processor(self, dialect: 'Dialect') -> 'Optional[_BindProcessorType[_UUID_RETURN]]'
| Return a conversion function for processing bind values.
|
| Returns a callable which will receive a bind parameter value
| as the sole positional argument and will return a value to
| send to the DB-API.
|
| If processing is not necessary, the method should return ``None``.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.bind_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.bind_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_bind_param`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
|
| :param dialect: Dialect instance in use.
|
| coerce_compared_value(self, op, value)
| See :meth:`.TypeEngine.coerce_compared_value` for a description.
|
| literal_processor(self, dialect)
| Return a conversion function for processing literal values that are
| to be rendered directly without using binds.
|
| This function is used when the compiler makes use of the
| "literal_binds" flag, typically used in DDL generation as well
| as in certain scenarios where backends don't accept bound parameters.
|
| Returns a callable which will receive a literal Python value
| as the sole positional argument and will return a string representation
| to be rendered in a SQL statement.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.literal_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.literal_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_literal_param`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| result_processor(self, dialect, coltype)
| Return a conversion function for processing result row values.
|
| Returns a callable which will receive a result row column
| value as the sole positional argument and will return a value
| to return to the user.
|
| If processing is not necessary, the method should return ``None``.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.result_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.result_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_result_value`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| :param dialect: Dialect instance in use.
|
| :param coltype: DBAPI coltype argument received in cursor.description.
|
| ----------------------------------------------------------------------
| Readonly properties defined here:
|
| native
|
| python_type
| Return the Python type object expected to be returned
| by instances of this type, if known.
|
| Basically, for those types which enforce a return type,
| or are known across the board to do such for all common
| DBAPIs (like ``int`` for example), will return that type.
|
| If a return type is not defined, raises
| ``NotImplementedError``.
|
| Note that any type also accommodates NULL in SQL which
| means you can also get back ``None`` from any type
| in practice.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'collation': 'Optional[str]', 'length': 'Optional[i...
|
| __parameters__ = ()
|
| __visit_name__ = 'uuid'
|
| collation = None
|
| length = None
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.type_api.Emulated:
|
| adapt(self, cls: 'Type[Union[TypeEngine[Any], TypeEngineMixin]]', **kw: 'Any') -> 'TypeEngine[Any]'
|
| adapt_to_emulated(self, impltype: 'Type[Union[TypeEngine[Any], TypeEngineMixin]]', **kw: 'Any') -> 'TypeEngine[Any]'
| Given an impl class, adapt this type to the impl assuming
| "emulated".
|
| The impl should also be an "emulated" version of this type,
| most likely the same class as this type itself.
|
| e.g.: sqltypes.Enum adapts to the Enum class.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from sqlalchemy.sql.type_api.Emulated:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.type_api.TypeEngine:
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| __str__(self) -> 'str'
| Return str(self).
|
| as_generic(self, allow_nulltype: 'bool' = False) -> 'TypeEngine[_T]'
| Return an instance of the generic type corresponding to this type
| using heuristic rule. The method may be overridden if this
| heuristic rule is not sufficient.
|
| >>> from sqlalchemy.dialects.mysql import INTEGER
| >>> INTEGER(display_width=4).as_generic()
| Integer()
|
| >>> from sqlalchemy.dialects.mysql import NVARCHAR
| >>> NVARCHAR(length=100).as_generic()
| Unicode(length=100)
|
| .. versionadded:: 1.4.0b2
|
|
| .. seealso::
|
| :ref:`metadata_reflection_dbagnostic_types` - describes the
| use of :meth:`_types.TypeEngine.as_generic` in conjunction with
| the :meth:`_sql.DDLEvents.column_reflect` event, which is its
| intended use.
|
| bind_expression(self, bindvalue: 'BindParameter[_T]') -> 'Optional[ColumnElement[_T]]'
| Given a bind value (i.e. a :class:`.BindParameter` instance),
| return a SQL expression in its place.
|
| This is typically a SQL function that wraps the existing bound
| parameter within the statement. It is used for special data types
| that require literals being wrapped in some special database function
| in order to coerce an application-level value into a database-specific
| format. It is the SQL analogue of the
| :meth:`.TypeEngine.bind_processor` method.
|
| This method is called during the **SQL compilation** phase of a
| statement, when rendering a SQL string. It is **not** called
| against specific values.
|
| Note that this method, when implemented, should always return
| the exact same structure, without any conditional logic, as it
| may be used in an executemany() call against an arbitrary number
| of bound parameter sets.
|
| .. note::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.bind_expression`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.bind_expression`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.bind_expression`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| .. seealso::
|
| :ref:`types_sql_value_processing`
|
| column_expression(self, colexpr: 'ColumnElement[_T]') -> 'Optional[ColumnElement[_T]]'
| Given a SELECT column expression, return a wrapping SQL expression.
|
| This is typically a SQL function that wraps a column expression
| as rendered in the columns clause of a SELECT statement.
| It is used for special data types that require
| columns to be wrapped in some special database function in order
| to coerce the value before being sent back to the application.
| It is the SQL analogue of the :meth:`.TypeEngine.result_processor`
| method.
|
| .. note:: The :func:`.TypeEngine.column_expression` method is applied
| only to the **outermost columns clause** of a SELECT statement, that
| is, the columns that are to be delivered directly into the returned
| result rows. It does **not** apply to the columns clause inside
| of subqueries. This necessarily avoids double conversions against
| the column and only runs the conversion when ready to be returned
| to the client.
|
| This method is called during the **SQL compilation** phase of a
| statement, when rendering a SQL string. It is **not** called
| against specific values.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.column_expression`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.column_expression`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.column_expression`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
|
| .. seealso::
|
| :ref:`types_sql_value_processing`
|
| compare_values(self, x: 'Any', y: 'Any') -> 'bool'
| Compare two values for equality.
|
| compile(self, dialect: 'Optional[Dialect]' = None) -> 'str'
| Produce a string-compiled form of this :class:`.TypeEngine`.
|
| When called with no arguments, uses a "default" dialect
| to produce a string result.
|
| :param dialect: a :class:`.Dialect` instance.
|
| copy(self, **kw: 'Any') -> 'Self'
|
| copy_value(self, value: 'Any') -> 'Any'
|
| dialect_impl(self, dialect: 'Dialect') -> 'TypeEngine[_T]'
| Return a dialect-specific implementation for this
| :class:`.TypeEngine`.
|
| evaluates_none(self) -> 'Self'
| Return a copy of this type which has the
| :attr:`.should_evaluate_none` flag set to True.
|
| E.g.::
|
| Table(
| "some_table",
| metadata,
| Column(
| String(50).evaluates_none(),
| nullable=True,
| server_default="no value",
| ),
| )
|
| The ORM uses this flag to indicate that a positive value of ``None``
| is passed to the column in an INSERT statement, rather than omitting
| the column from the INSERT statement which has the effect of firing
| off column-level defaults. It also allows for types which have
| special behavior associated with the Python None value to indicate
| that the value doesn't necessarily translate into SQL NULL; a
| prime example of this is a JSON type which may wish to persist the
| JSON value ``'null'``.
|
| In all cases, the actual NULL SQL value can be always be
| persisted in any column by using
| the :obj:`_expression.null` SQL construct in an INSERT statement
| or associated with an ORM-mapped attribute.
|
| .. note::
|
| The "evaluates none" flag does **not** apply to a value
| of ``None`` passed to :paramref:`_schema.Column.default` or
| :paramref:`_schema.Column.server_default`; in these cases,
| ``None``
| still means "no default".
|
| .. seealso::
|
| :ref:`session_forcing_null` - in the ORM documentation
|
| :paramref:`.postgresql.JSON.none_as_null` - PostgreSQL JSON
| interaction with this flag.
|
| :attr:`.TypeEngine.should_evaluate_none` - class-level flag
|
| get_dbapi_type(self, dbapi: 'DBAPIModule') -> 'Optional[Any]'
| Return the corresponding type object from the underlying DB-API, if
| any.
|
| This can be useful for calling ``setinputsizes()``, for example.
|
| with_variant(self, type_: '_TypeEngineArgument[Any]', *dialect_names: 'str') -> 'Self'
| Produce a copy of this type object that will utilize the given
| type when applied to the dialect of the given name.
|
| e.g.::
|
| from sqlalchemy.types import String
| from sqlalchemy.dialects import mysql
|
| string_type = String()
|
| string_type = string_type.with_variant(
| mysql.VARCHAR(collation="foo"), "mysql", "mariadb"
| )
|
| The variant mapping indicates that when this type is
| interpreted by a specific dialect, it will instead be
| transmuted into the given type, rather than using the
| primary type.
|
| .. versionchanged:: 2.0 the :meth:`_types.TypeEngine.with_variant`
| method now works with a :class:`_types.TypeEngine` object "in
| place", returning a copy of the original type rather than returning
| a wrapping object; the ``Variant`` class is no longer used.
|
| :param type\_: a :class:`.TypeEngine` that will be selected
| as a variant from the originating type, when a dialect
| of the given name is in use.
| :param \*dialect_names: one or more base names of the dialect which
| uses this type. (i.e. ``'postgresql'``, ``'mysql'``, etc.)
|
| .. versionchanged:: 2.0 multiple dialect names can be specified
| for one variant.
|
| .. seealso::
|
| :ref:`types_with_variant` - illustrates the use of
| :meth:`_types.TypeEngine.with_variant`.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.type_api.TypeEngine:
|
| Comparator = <class 'sqlalchemy.sql.type_api.TypeEngine.Comparator'>
| Base class for custom comparison operations defined at the
| type level. See :attr:`.TypeEngine.comparator_factory`.
|
|
| __orig_bases__ = (<class 'sqlalchemy.sql.visitors.Visitable'>, typing....
|
| comparator_factory = <class 'sqlalchemy.sql.type_api.TypeEngine.Compar...
| Base class for custom comparison operations defined at the
| type level. See :attr:`.TypeEngine.comparator_factory`.
|
|
| hashable = True
|
| render_bind_cast = False
|
| render_literal_cast = False
|
| should_evaluate_none = False
|
| sort_key_function = None
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.visitors.Visitable:
|
| __class_getitem__(key: 'Any') -> 'Any'
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__() -> 'None'
| This method is called when a class is subclassed.
|
| The default implementation does nothing. It may be
| overridden to extend subclasses.
sqlalchemy.VARBINARY
Python Library Documentation: class VARBINARY in module sqlalchemy.sql.sqltypes
class VARBINARY(_Binary)
| VARBINARY(length: 'Optional[int]' = None)
|
| The SQL VARBINARY type.
|
| Method resolution order:
| VARBINARY
| _Binary
| sqlalchemy.sql.type_api.TypeEngine
| sqlalchemy.sql.visitors.Visitable
| typing.Generic
| builtins.object
|
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| __parameters__ = ()
|
| __visit_name__ = 'VARBINARY'
|
| ----------------------------------------------------------------------
| Methods inherited from _Binary:
|
| __init__(self, length: 'Optional[int]' = None)
| Initialize self. See help(type(self)) for accurate signature.
|
| bind_processor(self, dialect)
| Return a conversion function for processing bind values.
|
| Returns a callable which will receive a bind parameter value
| as the sole positional argument and will return a value to
| send to the DB-API.
|
| If processing is not necessary, the method should return ``None``.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.bind_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.bind_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_bind_param`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
|
| :param dialect: Dialect instance in use.
|
| coerce_compared_value(self, op, value)
| See :meth:`.TypeEngine.coerce_compared_value` for a description.
|
| get_dbapi_type(self, dbapi)
| Return the corresponding type object from the underlying DB-API, if
| any.
|
| This can be useful for calling ``setinputsizes()``, for example.
|
| literal_processor(self, dialect)
| Return a conversion function for processing literal values that are
| to be rendered directly without using binds.
|
| This function is used when the compiler makes use of the
| "literal_binds" flag, typically used in DDL generation as well
| as in certain scenarios where backends don't accept bound parameters.
|
| Returns a callable which will receive a literal Python value
| as the sole positional argument and will return a string representation
| to be rendered in a SQL statement.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.literal_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.literal_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_literal_param`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| result_processor(self, dialect, coltype)
| Return a conversion function for processing result row values.
|
| Returns a callable which will receive a result row column
| value as the sole positional argument and will return a value
| to return to the user.
|
| If processing is not necessary, the method should return ``None``.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.result_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.result_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_result_value`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| :param dialect: Dialect instance in use.
|
| :param coltype: DBAPI coltype argument received in cursor.description.
|
| ----------------------------------------------------------------------
| Readonly properties inherited from _Binary:
|
| python_type
| Return the Python type object expected to be returned
| by instances of this type, if known.
|
| Basically, for those types which enforce a return type,
| or are known across the board to do such for all common
| DBAPIs (like ``int`` for example), will return that type.
|
| If a return type is not defined, raises
| ``NotImplementedError``.
|
| Note that any type also accommodates NULL in SQL which
| means you can also get back ``None`` from any type
| in practice.
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.type_api.TypeEngine:
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| __str__(self) -> 'str'
| Return str(self).
|
| adapt(self, cls: 'Type[Union[TypeEngine[Any], TypeEngineMixin]]', **kw: 'Any') -> 'TypeEngine[Any]'
| Produce an "adapted" form of this type, given an "impl" class
| to work with.
|
| This method is used internally to associate generic
| types with "implementation" types that are specific to a particular
| dialect.
|
| as_generic(self, allow_nulltype: 'bool' = False) -> 'TypeEngine[_T]'
| Return an instance of the generic type corresponding to this type
| using heuristic rule. The method may be overridden if this
| heuristic rule is not sufficient.
|
| >>> from sqlalchemy.dialects.mysql import INTEGER
| >>> INTEGER(display_width=4).as_generic()
| Integer()
|
| >>> from sqlalchemy.dialects.mysql import NVARCHAR
| >>> NVARCHAR(length=100).as_generic()
| Unicode(length=100)
|
| .. versionadded:: 1.4.0b2
|
|
| .. seealso::
|
| :ref:`metadata_reflection_dbagnostic_types` - describes the
| use of :meth:`_types.TypeEngine.as_generic` in conjunction with
| the :meth:`_sql.DDLEvents.column_reflect` event, which is its
| intended use.
|
| bind_expression(self, bindvalue: 'BindParameter[_T]') -> 'Optional[ColumnElement[_T]]'
| Given a bind value (i.e. a :class:`.BindParameter` instance),
| return a SQL expression in its place.
|
| This is typically a SQL function that wraps the existing bound
| parameter within the statement. It is used for special data types
| that require literals being wrapped in some special database function
| in order to coerce an application-level value into a database-specific
| format. It is the SQL analogue of the
| :meth:`.TypeEngine.bind_processor` method.
|
| This method is called during the **SQL compilation** phase of a
| statement, when rendering a SQL string. It is **not** called
| against specific values.
|
| Note that this method, when implemented, should always return
| the exact same structure, without any conditional logic, as it
| may be used in an executemany() call against an arbitrary number
| of bound parameter sets.
|
| .. note::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.bind_expression`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.bind_expression`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.bind_expression`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| .. seealso::
|
| :ref:`types_sql_value_processing`
|
| column_expression(self, colexpr: 'ColumnElement[_T]') -> 'Optional[ColumnElement[_T]]'
| Given a SELECT column expression, return a wrapping SQL expression.
|
| This is typically a SQL function that wraps a column expression
| as rendered in the columns clause of a SELECT statement.
| It is used for special data types that require
| columns to be wrapped in some special database function in order
| to coerce the value before being sent back to the application.
| It is the SQL analogue of the :meth:`.TypeEngine.result_processor`
| method.
|
| .. note:: The :func:`.TypeEngine.column_expression` method is applied
| only to the **outermost columns clause** of a SELECT statement, that
| is, the columns that are to be delivered directly into the returned
| result rows. It does **not** apply to the columns clause inside
| of subqueries. This necessarily avoids double conversions against
| the column and only runs the conversion when ready to be returned
| to the client.
|
| This method is called during the **SQL compilation** phase of a
| statement, when rendering a SQL string. It is **not** called
| against specific values.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.column_expression`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.column_expression`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.column_expression`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
|
| .. seealso::
|
| :ref:`types_sql_value_processing`
|
| compare_values(self, x: 'Any', y: 'Any') -> 'bool'
| Compare two values for equality.
|
| compile(self, dialect: 'Optional[Dialect]' = None) -> 'str'
| Produce a string-compiled form of this :class:`.TypeEngine`.
|
| When called with no arguments, uses a "default" dialect
| to produce a string result.
|
| :param dialect: a :class:`.Dialect` instance.
|
| copy(self, **kw: 'Any') -> 'Self'
|
| copy_value(self, value: 'Any') -> 'Any'
|
| dialect_impl(self, dialect: 'Dialect') -> 'TypeEngine[_T]'
| Return a dialect-specific implementation for this
| :class:`.TypeEngine`.
|
| evaluates_none(self) -> 'Self'
| Return a copy of this type which has the
| :attr:`.should_evaluate_none` flag set to True.
|
| E.g.::
|
| Table(
| "some_table",
| metadata,
| Column(
| String(50).evaluates_none(),
| nullable=True,
| server_default="no value",
| ),
| )
|
| The ORM uses this flag to indicate that a positive value of ``None``
| is passed to the column in an INSERT statement, rather than omitting
| the column from the INSERT statement which has the effect of firing
| off column-level defaults. It also allows for types which have
| special behavior associated with the Python None value to indicate
| that the value doesn't necessarily translate into SQL NULL; a
| prime example of this is a JSON type which may wish to persist the
| JSON value ``'null'``.
|
| In all cases, the actual NULL SQL value can be always be
| persisted in any column by using
| the :obj:`_expression.null` SQL construct in an INSERT statement
| or associated with an ORM-mapped attribute.
|
| .. note::
|
| The "evaluates none" flag does **not** apply to a value
| of ``None`` passed to :paramref:`_schema.Column.default` or
| :paramref:`_schema.Column.server_default`; in these cases,
| ``None``
| still means "no default".
|
| .. seealso::
|
| :ref:`session_forcing_null` - in the ORM documentation
|
| :paramref:`.postgresql.JSON.none_as_null` - PostgreSQL JSON
| interaction with this flag.
|
| :attr:`.TypeEngine.should_evaluate_none` - class-level flag
|
| with_variant(self, type_: '_TypeEngineArgument[Any]', *dialect_names: 'str') -> 'Self'
| Produce a copy of this type object that will utilize the given
| type when applied to the dialect of the given name.
|
| e.g.::
|
| from sqlalchemy.types import String
| from sqlalchemy.dialects import mysql
|
| string_type = String()
|
| string_type = string_type.with_variant(
| mysql.VARCHAR(collation="foo"), "mysql", "mariadb"
| )
|
| The variant mapping indicates that when this type is
| interpreted by a specific dialect, it will instead be
| transmuted into the given type, rather than using the
| primary type.
|
| .. versionchanged:: 2.0 the :meth:`_types.TypeEngine.with_variant`
| method now works with a :class:`_types.TypeEngine` object "in
| place", returning a copy of the original type rather than returning
| a wrapping object; the ``Variant`` class is no longer used.
|
| :param type\_: a :class:`.TypeEngine` that will be selected
| as a variant from the originating type, when a dialect
| of the given name is in use.
| :param \*dialect_names: one or more base names of the dialect which
| uses this type. (i.e. ``'postgresql'``, ``'mysql'``, etc.)
|
| .. versionchanged:: 2.0 multiple dialect names can be specified
| for one variant.
|
| .. seealso::
|
| :ref:`types_with_variant` - illustrates the use of
| :meth:`_types.TypeEngine.with_variant`.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from sqlalchemy.sql.type_api.TypeEngine:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.type_api.TypeEngine:
|
| Comparator = <class 'sqlalchemy.sql.type_api.TypeEngine.Comparator'>
| Base class for custom comparison operations defined at the
| type level. See :attr:`.TypeEngine.comparator_factory`.
|
|
| __orig_bases__ = (<class 'sqlalchemy.sql.visitors.Visitable'>, typing....
|
| comparator_factory = <class 'sqlalchemy.sql.type_api.TypeEngine.Compar...
| Base class for custom comparison operations defined at the
| type level. See :attr:`.TypeEngine.comparator_factory`.
|
|
| hashable = True
|
| render_bind_cast = False
|
| render_literal_cast = False
|
| should_evaluate_none = False
|
| sort_key_function = None
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.visitors.Visitable:
|
| __class_getitem__(key: 'Any') -> 'Any'
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__() -> 'None'
| Function to initialize subclasses.
sqlalchemy.VARCHAR
Python Library Documentation: class VARCHAR in module sqlalchemy.sql.sqltypes
class VARCHAR(String)
| VARCHAR(length: 'Optional[int]' = None, collation: 'Optional[str]' = None)
|
| The SQL VARCHAR type.
|
| Method resolution order:
| VARCHAR
| String
| Concatenable
| sqlalchemy.sql.type_api.TypeEngineMixin
| sqlalchemy.sql.type_api.TypeEngine
| sqlalchemy.sql.visitors.Visitable
| typing.Generic
| builtins.object
|
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| __parameters__ = ()
|
| __visit_name__ = 'VARCHAR'
|
| ----------------------------------------------------------------------
| Methods inherited from String:
|
| __init__(self, length: 'Optional[int]' = None, collation: 'Optional[str]' = None)
| Create a string-holding type.
|
| :param length: optional, a length for the column for use in
| DDL and CAST expressions. May be safely omitted if no ``CREATE
| TABLE`` will be issued. Certain databases may require a
| ``length`` for use in DDL, and will raise an exception when
| the ``CREATE TABLE`` DDL is issued if a ``VARCHAR``
| with no length is included. Whether the value is
| interpreted as bytes or characters is database specific.
|
| :param collation: Optional, a column-level collation for
| use in DDL and CAST expressions. Renders using the
| COLLATE keyword supported by SQLite, MySQL, and PostgreSQL.
| E.g.:
|
| .. sourcecode:: pycon+sql
|
| >>> from sqlalchemy import cast, select, String
| >>> print(select(cast("some string", String(collation="utf8"))))
| {printsql}SELECT CAST(:param_1 AS VARCHAR COLLATE utf8) AS anon_1
|
| .. note::
|
| In most cases, the :class:`.Unicode` or :class:`.UnicodeText`
| datatypes should be used for a :class:`_schema.Column` that expects
| to store non-ascii data. These datatypes will ensure that the
| correct types are used on the database.
|
| bind_processor(self, dialect: 'Dialect') -> 'Optional[_BindProcessorType[str]]'
| Return a conversion function for processing bind values.
|
| Returns a callable which will receive a bind parameter value
| as the sole positional argument and will return a value to
| send to the DB-API.
|
| If processing is not necessary, the method should return ``None``.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.bind_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.bind_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_bind_param`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
|
| :param dialect: Dialect instance in use.
|
| get_dbapi_type(self, dbapi)
| Return the corresponding type object from the underlying DB-API, if
| any.
|
| This can be useful for calling ``setinputsizes()``, for example.
|
| literal_processor(self, dialect)
| Return a conversion function for processing literal values that are
| to be rendered directly without using binds.
|
| This function is used when the compiler makes use of the
| "literal_binds" flag, typically used in DDL generation as well
| as in certain scenarios where backends don't accept bound parameters.
|
| Returns a callable which will receive a literal Python value
| as the sole positional argument and will return a string representation
| to be rendered in a SQL statement.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.literal_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.literal_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_literal_param`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| result_processor(self, dialect: 'Dialect', coltype: 'object') -> 'Optional[_ResultProcessorType[str]]'
| Return a conversion function for processing result row values.
|
| Returns a callable which will receive a result row column
| value as the sole positional argument and will return a value
| to return to the user.
|
| If processing is not necessary, the method should return ``None``.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.result_processor`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.result_processor`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.process_result_value`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| :param dialect: Dialect instance in use.
|
| :param coltype: DBAPI coltype argument received in cursor.description.
|
| ----------------------------------------------------------------------
| Readonly properties inherited from String:
|
| python_type
| Return the Python type object expected to be returned
| by instances of this type, if known.
|
| Basically, for those types which enforce a return type,
| or are known across the board to do such for all common
| DBAPIs (like ``int`` for example), will return that type.
|
| If a return type is not defined, raises
| ``NotImplementedError``.
|
| Note that any type also accommodates NULL in SQL which
| means you can also get back ``None`` from any type
| in practice.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from Concatenable:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from Concatenable:
|
| Comparator = <class 'sqlalchemy.sql.sqltypes.Concatenable.Comparator'>
|
| comparator_factory = <class 'sqlalchemy.sql.sqltypes.Concatenable.Comp...
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.type_api.TypeEngine:
|
| __repr__(self) -> 'str'
| Return repr(self).
|
| __str__(self) -> 'str'
| Return str(self).
|
| adapt(self, cls: 'Type[Union[TypeEngine[Any], TypeEngineMixin]]', **kw: 'Any') -> 'TypeEngine[Any]'
| Produce an "adapted" form of this type, given an "impl" class
| to work with.
|
| This method is used internally to associate generic
| types with "implementation" types that are specific to a particular
| dialect.
|
| as_generic(self, allow_nulltype: 'bool' = False) -> 'TypeEngine[_T]'
| Return an instance of the generic type corresponding to this type
| using heuristic rule. The method may be overridden if this
| heuristic rule is not sufficient.
|
| >>> from sqlalchemy.dialects.mysql import INTEGER
| >>> INTEGER(display_width=4).as_generic()
| Integer()
|
| >>> from sqlalchemy.dialects.mysql import NVARCHAR
| >>> NVARCHAR(length=100).as_generic()
| Unicode(length=100)
|
| .. versionadded:: 1.4.0b2
|
|
| .. seealso::
|
| :ref:`metadata_reflection_dbagnostic_types` - describes the
| use of :meth:`_types.TypeEngine.as_generic` in conjunction with
| the :meth:`_sql.DDLEvents.column_reflect` event, which is its
| intended use.
|
| bind_expression(self, bindvalue: 'BindParameter[_T]') -> 'Optional[ColumnElement[_T]]'
| Given a bind value (i.e. a :class:`.BindParameter` instance),
| return a SQL expression in its place.
|
| This is typically a SQL function that wraps the existing bound
| parameter within the statement. It is used for special data types
| that require literals being wrapped in some special database function
| in order to coerce an application-level value into a database-specific
| format. It is the SQL analogue of the
| :meth:`.TypeEngine.bind_processor` method.
|
| This method is called during the **SQL compilation** phase of a
| statement, when rendering a SQL string. It is **not** called
| against specific values.
|
| Note that this method, when implemented, should always return
| the exact same structure, without any conditional logic, as it
| may be used in an executemany() call against an arbitrary number
| of bound parameter sets.
|
| .. note::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.bind_expression`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.bind_expression`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.bind_expression`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
| .. seealso::
|
| :ref:`types_sql_value_processing`
|
| coerce_compared_value(self, op: 'Optional[OperatorType]', value: 'Any') -> 'TypeEngine[Any]'
| Suggest a type for a 'coerced' Python value in an expression.
|
| Given an operator and value, gives the type a chance
| to return a type which the value should be coerced into.
|
| The default behavior here is conservative; if the right-hand
| side is already coerced into a SQL type based on its
| Python type, it is usually left alone.
|
| End-user functionality extension here should generally be via
| :class:`.TypeDecorator`, which provides more liberal behavior in that
| it defaults to coercing the other side of the expression into this
| type, thus applying special Python conversions above and beyond those
| needed by the DBAPI to both ides. It also provides the public method
| :meth:`.TypeDecorator.coerce_compared_value` which is intended for
| end-user customization of this behavior.
|
| column_expression(self, colexpr: 'ColumnElement[_T]') -> 'Optional[ColumnElement[_T]]'
| Given a SELECT column expression, return a wrapping SQL expression.
|
| This is typically a SQL function that wraps a column expression
| as rendered in the columns clause of a SELECT statement.
| It is used for special data types that require
| columns to be wrapped in some special database function in order
| to coerce the value before being sent back to the application.
| It is the SQL analogue of the :meth:`.TypeEngine.result_processor`
| method.
|
| .. note:: The :func:`.TypeEngine.column_expression` method is applied
| only to the **outermost columns clause** of a SELECT statement, that
| is, the columns that are to be delivered directly into the returned
| result rows. It does **not** apply to the columns clause inside
| of subqueries. This necessarily avoids double conversions against
| the column and only runs the conversion when ready to be returned
| to the client.
|
| This method is called during the **SQL compilation** phase of a
| statement, when rendering a SQL string. It is **not** called
| against specific values.
|
| .. tip::
|
| This method is only called relative to a **dialect specific type
| object**, which is often **private to a dialect in use** and is not
| the same type object as the public facing one, which means it's not
| feasible to subclass a :class:`.types.TypeEngine` class in order to
| provide an alternate :meth:`_types.TypeEngine.column_expression`
| method, unless subclassing the :class:`_types.UserDefinedType`
| class explicitly.
|
| To provide alternate behavior for
| :meth:`_types.TypeEngine.column_expression`, implement a
| :class:`_types.TypeDecorator` class and provide an implementation
| of :meth:`_types.TypeDecorator.column_expression`.
|
| .. seealso::
|
| :ref:`types_typedecorator`
|
|
| .. seealso::
|
| :ref:`types_sql_value_processing`
|
| compare_values(self, x: 'Any', y: 'Any') -> 'bool'
| Compare two values for equality.
|
| compile(self, dialect: 'Optional[Dialect]' = None) -> 'str'
| Produce a string-compiled form of this :class:`.TypeEngine`.
|
| When called with no arguments, uses a "default" dialect
| to produce a string result.
|
| :param dialect: a :class:`.Dialect` instance.
|
| copy(self, **kw: 'Any') -> 'Self'
|
| copy_value(self, value: 'Any') -> 'Any'
|
| dialect_impl(self, dialect: 'Dialect') -> 'TypeEngine[_T]'
| Return a dialect-specific implementation for this
| :class:`.TypeEngine`.
|
| evaluates_none(self) -> 'Self'
| Return a copy of this type which has the
| :attr:`.should_evaluate_none` flag set to True.
|
| E.g.::
|
| Table(
| "some_table",
| metadata,
| Column(
| String(50).evaluates_none(),
| nullable=True,
| server_default="no value",
| ),
| )
|
| The ORM uses this flag to indicate that a positive value of ``None``
| is passed to the column in an INSERT statement, rather than omitting
| the column from the INSERT statement which has the effect of firing
| off column-level defaults. It also allows for types which have
| special behavior associated with the Python None value to indicate
| that the value doesn't necessarily translate into SQL NULL; a
| prime example of this is a JSON type which may wish to persist the
| JSON value ``'null'``.
|
| In all cases, the actual NULL SQL value can be always be
| persisted in any column by using
| the :obj:`_expression.null` SQL construct in an INSERT statement
| or associated with an ORM-mapped attribute.
|
| .. note::
|
| The "evaluates none" flag does **not** apply to a value
| of ``None`` passed to :paramref:`_schema.Column.default` or
| :paramref:`_schema.Column.server_default`; in these cases,
| ``None``
| still means "no default".
|
| .. seealso::
|
| :ref:`session_forcing_null` - in the ORM documentation
|
| :paramref:`.postgresql.JSON.none_as_null` - PostgreSQL JSON
| interaction with this flag.
|
| :attr:`.TypeEngine.should_evaluate_none` - class-level flag
|
| with_variant(self, type_: '_TypeEngineArgument[Any]', *dialect_names: 'str') -> 'Self'
| Produce a copy of this type object that will utilize the given
| type when applied to the dialect of the given name.
|
| e.g.::
|
| from sqlalchemy.types import String
| from sqlalchemy.dialects import mysql
|
| string_type = String()
|
| string_type = string_type.with_variant(
| mysql.VARCHAR(collation="foo"), "mysql", "mariadb"
| )
|
| The variant mapping indicates that when this type is
| interpreted by a specific dialect, it will instead be
| transmuted into the given type, rather than using the
| primary type.
|
| .. versionchanged:: 2.0 the :meth:`_types.TypeEngine.with_variant`
| method now works with a :class:`_types.TypeEngine` object "in
| place", returning a copy of the original type rather than returning
| a wrapping object; the ``Variant`` class is no longer used.
|
| :param type\_: a :class:`.TypeEngine` that will be selected
| as a variant from the originating type, when a dialect
| of the given name is in use.
| :param \*dialect_names: one or more base names of the dialect which
| uses this type. (i.e. ``'postgresql'``, ``'mysql'``, etc.)
|
| .. versionchanged:: 2.0 multiple dialect names can be specified
| for one variant.
|
| .. seealso::
|
| :ref:`types_with_variant` - illustrates the use of
| :meth:`_types.TypeEngine.with_variant`.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.type_api.TypeEngine:
|
| __orig_bases__ = (<class 'sqlalchemy.sql.visitors.Visitable'>, typing....
|
| hashable = True
|
| render_bind_cast = False
|
| render_literal_cast = False
|
| should_evaluate_none = False
|
| sort_key_function = None
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.visitors.Visitable:
|
| __class_getitem__(key: 'Any') -> 'Any'
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__() -> 'None'
| This method is called when a class is subclassed.
|
| The default implementation does nothing. It may be
| overridden to extend subclasses.
sqlalchemy.Values
Python Library Documentation: class Values in module sqlalchemy.sql.selectable
class Values(sqlalchemy.sql.roles.InElementRole, HasCTE, sqlalchemy.sql.base.Generative, LateralFromClause)
| Values(*columns: '_OnlyColumnArgument[Any]', name: 'Optional[str]' = None, literal_binds: 'bool' = False)
|
| Represent a ``VALUES`` construct that can be used as a FROM element
| in a statement.
|
| The :class:`_expression.Values` object is created from the
| :func:`_expression.values` function.
|
| .. versionadded:: 1.4
|
| Method resolution order:
| Values
| sqlalchemy.sql.roles.InElementRole
| HasCTE
| sqlalchemy.sql.roles.HasCTERole
| SelectsRows
| sqlalchemy.sql.base.Generative
| LateralFromClause
| NamedFromClause
| FromClause
| sqlalchemy.sql.roles.AnonymizedFromClauseRole
| sqlalchemy.sql.roles.StrictFromClauseRole
| sqlalchemy.sql.roles.FromClauseRole
| sqlalchemy.sql.roles.ColumnsClauseRole
| sqlalchemy.sql.roles.JoinTargetRole
| sqlalchemy.sql.roles.AllowsLambdaRole
| sqlalchemy.sql.roles.UsesInspection
| sqlalchemy.sql.roles.ColumnListRole
| sqlalchemy.sql.roles.StructuralRole
| Selectable
| ReturnsRows
| sqlalchemy.sql.roles.ReturnsRowsRole
| sqlalchemy.sql.roles.SQLRole
| sqlalchemy.sql.elements.DQLDMLClauseElement
| sqlalchemy.sql.elements.ClauseElement
| sqlalchemy.sql.annotation.SupportsWrappingAnnotations
| sqlalchemy.sql.annotation.SupportsAnnotations
| sqlalchemy.sql.cache_key.MemoizedHasCacheKey
| sqlalchemy.sql.cache_key.HasCacheKey
| sqlalchemy.util.langhelpers.HasMemoized
| sqlalchemy.sql.traversals.HasCopyInternals
| sqlalchemy.sql.visitors.ExternallyTraversible
| sqlalchemy.sql.visitors.HasTraverseInternals
| sqlalchemy.sql.elements.CompilerElement
| sqlalchemy.sql.visitors.Visitable
| builtins.object
|
| Methods defined here:
|
| __init__(self, *columns: '_OnlyColumnArgument[Any]', name: 'Optional[str]' = None, literal_binds: 'bool' = False)
| Initialize self. See help(type(self)) for accurate signature.
|
| alias(self, name: 'Optional[str]' = None, flat: 'bool' = False) -> 'Self'
| Return a new :class:`_expression.Values`
| construct that is a copy of this
| one with the given name.
|
| This method is a VALUES-specific specialization of the
| :meth:`_expression.FromClause.alias` method.
|
| .. seealso::
|
| :ref:`tutorial_using_aliases`
|
| :func:`_expression.alias`
|
| data(self, values: 'Sequence[Tuple[Any, ...]]') -> 'Self'
| Return a new :class:`_expression.Values` construct,
| adding the given data to the data list.
|
| E.g.::
|
| my_values = my_values.data([(1, "value 1"), (2, "value2")])
|
| :param values: a sequence (i.e. list) of tuples that map to the
| column expressions given in the :class:`_expression.Values`
| constructor.
|
| lateral(self, name: 'Optional[str]' = None) -> 'Self'
| Return a new :class:`_expression.Values` with the lateral flag set,
| so that
| it renders as LATERAL.
|
| .. seealso::
|
| :func:`_expression.lateral`
|
| scalar_values(self) -> 'ScalarValues'
| Returns a scalar ``VALUES`` construct that can be used as a
| COLUMN element in a statement.
|
| .. versionadded:: 2.0.0b4
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'_column_args': 'Tuple[NamedColumn[Any], ...]', '_d...
|
| __visit_name__ = 'values'
|
| name_cte_columns = True
|
| ----------------------------------------------------------------------
| Methods inherited from HasCTE:
|
| add_cte(self, *ctes: 'CTE', nest_here: 'bool' = False) -> 'Self'
| Add one or more :class:`_sql.CTE` constructs to this statement.
|
| This method will associate the given :class:`_sql.CTE` constructs with
| the parent statement such that they will each be unconditionally
| rendered in the WITH clause of the final statement, even if not
| referenced elsewhere within the statement or any sub-selects.
|
| The optional :paramref:`.HasCTE.add_cte.nest_here` parameter when set
| to True will have the effect that each given :class:`_sql.CTE` will
| render in a WITH clause rendered directly along with this statement,
| rather than being moved to the top of the ultimate rendered statement,
| even if this statement is rendered as a subquery within a larger
| statement.
|
| This method has two general uses. One is to embed CTE statements that
| serve some purpose without being referenced explicitly, such as the use
| case of embedding a DML statement such as an INSERT or UPDATE as a CTE
| inline with a primary statement that may draw from its results
| indirectly. The other is to provide control over the exact placement
| of a particular series of CTE constructs that should remain rendered
| directly in terms of a particular statement that may be nested in a
| larger statement.
|
| E.g.::
|
| from sqlalchemy import table, column, select
|
| t = table("t", column("c1"), column("c2"))
|
| ins = t.insert().values({"c1": "x", "c2": "y"}).cte()
|
| stmt = select(t).add_cte(ins)
|
| Would render:
|
| .. sourcecode:: sql
|
| WITH anon_1 AS (
| INSERT INTO t (c1, c2) VALUES (:param_1, :param_2)
| )
| SELECT t.c1, t.c2
| FROM t
|
| Above, the "anon_1" CTE is not referenced in the SELECT
| statement, however still accomplishes the task of running an INSERT
| statement.
|
| Similarly in a DML-related context, using the PostgreSQL
| :class:`_postgresql.Insert` construct to generate an "upsert"::
|
| from sqlalchemy import table, column
| from sqlalchemy.dialects.postgresql import insert
|
| t = table("t", column("c1"), column("c2"))
|
| delete_statement_cte = t.delete().where(t.c.c1 < 1).cte("deletions")
|
| insert_stmt = insert(t).values({"c1": 1, "c2": 2})
| update_statement = insert_stmt.on_conflict_do_update(
| index_elements=[t.c.c1],
| set_={
| "c1": insert_stmt.excluded.c1,
| "c2": insert_stmt.excluded.c2,
| },
| ).add_cte(delete_statement_cte)
|
| print(update_statement)
|
| The above statement renders as:
|
| .. sourcecode:: sql
|
| WITH deletions AS (
| DELETE FROM t WHERE t.c1 < %(c1_1)s
| )
| INSERT INTO t (c1, c2) VALUES (%(c1)s, %(c2)s)
| ON CONFLICT (c1) DO UPDATE SET c1 = excluded.c1, c2 = excluded.c2
|
| .. versionadded:: 1.4.21
|
| :param \*ctes: zero or more :class:`.CTE` constructs.
|
| .. versionchanged:: 2.0 Multiple CTE instances are accepted
|
| :param nest_here: if True, the given CTE or CTEs will be rendered
| as though they specified the :paramref:`.HasCTE.cte.nesting` flag
| to ``True`` when they were added to this :class:`.HasCTE`.
| Assuming the given CTEs are not referenced in an outer-enclosing
| statement as well, the CTEs given should render at the level of
| this statement when this flag is given.
|
| .. versionadded:: 2.0
|
| .. seealso::
|
| :paramref:`.HasCTE.cte.nesting`
|
| cte(self, name: 'Optional[str]' = None, recursive: 'bool' = False, nesting: 'bool' = False) -> 'CTE'
| Return a new :class:`_expression.CTE`,
| or Common Table Expression instance.
|
| Common table expressions are a SQL standard whereby SELECT
| statements can draw upon secondary statements specified along
| with the primary statement, using a clause called "WITH".
| Special semantics regarding UNION can also be employed to
| allow "recursive" queries, where a SELECT statement can draw
| upon the set of rows that have previously been selected.
|
| CTEs can also be applied to DML constructs UPDATE, INSERT
| and DELETE on some databases, both as a source of CTE rows
| when combined with RETURNING, as well as a consumer of
| CTE rows.
|
| SQLAlchemy detects :class:`_expression.CTE` objects, which are treated
| similarly to :class:`_expression.Alias` objects, as special elements
| to be delivered to the FROM clause of the statement as well
| as to a WITH clause at the top of the statement.
|
| For special prefixes such as PostgreSQL "MATERIALIZED" and
| "NOT MATERIALIZED", the :meth:`_expression.CTE.prefix_with`
| method may be
| used to establish these.
|
| .. versionchanged:: 1.3.13 Added support for prefixes.
| In particular - MATERIALIZED and NOT MATERIALIZED.
|
| :param name: name given to the common table expression. Like
| :meth:`_expression.FromClause.alias`, the name can be left as
| ``None`` in which case an anonymous symbol will be used at query
| compile time.
| :param recursive: if ``True``, will render ``WITH RECURSIVE``.
| A recursive common table expression is intended to be used in
| conjunction with UNION ALL in order to derive rows
| from those already selected.
| :param nesting: if ``True``, will render the CTE locally to the
| statement in which it is referenced. For more complex scenarios,
| the :meth:`.HasCTE.add_cte` method using the
| :paramref:`.HasCTE.add_cte.nest_here`
| parameter may also be used to more carefully
| control the exact placement of a particular CTE.
|
| .. versionadded:: 1.4.24
|
| .. seealso::
|
| :meth:`.HasCTE.add_cte`
|
| The following examples include two from PostgreSQL's documentation at
| https://www.postgresql.org/docs/current/static/queries-with.html,
| as well as additional examples.
|
| Example 1, non recursive::
|
| from sqlalchemy import (
| Table,
| Column,
| String,
| Integer,
| MetaData,
| select,
| func,
| )
|
| metadata = MetaData()
|
| orders = Table(
| "orders",
| metadata,
| Column("region", String),
| Column("amount", Integer),
| Column("product", String),
| Column("quantity", Integer),
| )
|
| regional_sales = (
| select(orders.c.region, func.sum(orders.c.amount).label("total_sales"))
| .group_by(orders.c.region)
| .cte("regional_sales")
| )
|
|
| top_regions = (
| select(regional_sales.c.region)
| .where(
| regional_sales.c.total_sales
| > select(func.sum(regional_sales.c.total_sales) / 10)
| )
| .cte("top_regions")
| )
|
| statement = (
| select(
| orders.c.region,
| orders.c.product,
| func.sum(orders.c.quantity).label("product_units"),
| func.sum(orders.c.amount).label("product_sales"),
| )
| .where(orders.c.region.in_(select(top_regions.c.region)))
| .group_by(orders.c.region, orders.c.product)
| )
|
| result = conn.execute(statement).fetchall()
|
| Example 2, WITH RECURSIVE::
|
| from sqlalchemy import (
| Table,
| Column,
| String,
| Integer,
| MetaData,
| select,
| func,
| )
|
| metadata = MetaData()
|
| parts = Table(
| "parts",
| metadata,
| Column("part", String),
| Column("sub_part", String),
| Column("quantity", Integer),
| )
|
| included_parts = (
| select(parts.c.sub_part, parts.c.part, parts.c.quantity)
| .where(parts.c.part == "our part")
| .cte(recursive=True)
| )
|
|
| incl_alias = included_parts.alias()
| parts_alias = parts.alias()
| included_parts = included_parts.union_all(
| select(
| parts_alias.c.sub_part, parts_alias.c.part, parts_alias.c.quantity
| ).where(parts_alias.c.part == incl_alias.c.sub_part)
| )
|
| statement = select(
| included_parts.c.sub_part,
| func.sum(included_parts.c.quantity).label("total_quantity"),
| ).group_by(included_parts.c.sub_part)
|
| result = conn.execute(statement).fetchall()
|
| Example 3, an upsert using UPDATE and INSERT with CTEs::
|
| from datetime import date
| from sqlalchemy import (
| MetaData,
| Table,
| Column,
| Integer,
| Date,
| select,
| literal,
| and_,
| exists,
| )
|
| metadata = MetaData()
|
| visitors = Table(
| "visitors",
| metadata,
| Column("product_id", Integer, primary_key=True),
| Column("date", Date, primary_key=True),
| Column("count", Integer),
| )
|
| # add 5 visitors for the product_id == 1
| product_id = 1
| day = date.today()
| count = 5
|
| update_cte = (
| visitors.update()
| .where(
| and_(visitors.c.product_id == product_id, visitors.c.date == day)
| )
| .values(count=visitors.c.count + count)
| .returning(literal(1))
| .cte("update_cte")
| )
|
| upsert = visitors.insert().from_select(
| [visitors.c.product_id, visitors.c.date, visitors.c.count],
| select(literal(product_id), literal(day), literal(count)).where(
| ~exists(update_cte.select())
| ),
| )
|
| connection.execute(upsert)
|
| Example 4, Nesting CTE (SQLAlchemy 1.4.24 and above)::
|
| value_a = select(literal("root").label("n")).cte("value_a")
|
| # A nested CTE with the same name as the root one
| value_a_nested = select(literal("nesting").label("n")).cte(
| "value_a", nesting=True
| )
|
| # Nesting CTEs takes ascendency locally
| # over the CTEs at a higher level
| value_b = select(value_a_nested.c.n).cte("value_b")
|
| value_ab = select(value_a.c.n.label("a"), value_b.c.n.label("b"))
|
| The above query will render the second CTE nested inside the first,
| shown with inline parameters below as:
|
| .. sourcecode:: sql
|
| WITH
| value_a AS
| (SELECT 'root' AS n),
| value_b AS
| (WITH value_a AS
| (SELECT 'nesting' AS n)
| SELECT value_a.n AS n FROM value_a)
| SELECT value_a.n AS a, value_b.n AS b
| FROM value_a, value_b
|
| The same CTE can be set up using the :meth:`.HasCTE.add_cte` method
| as follows (SQLAlchemy 2.0 and above)::
|
| value_a = select(literal("root").label("n")).cte("value_a")
|
| # A nested CTE with the same name as the root one
| value_a_nested = select(literal("nesting").label("n")).cte("value_a")
|
| # Nesting CTEs takes ascendency locally
| # over the CTEs at a higher level
| value_b = (
| select(value_a_nested.c.n)
| .add_cte(value_a_nested, nest_here=True)
| .cte("value_b")
| )
|
| value_ab = select(value_a.c.n.label("a"), value_b.c.n.label("b"))
|
| Example 5, Non-Linear CTE (SQLAlchemy 1.4.28 and above)::
|
| edge = Table(
| "edge",
| metadata,
| Column("id", Integer, primary_key=True),
| Column("left", Integer),
| Column("right", Integer),
| )
|
| root_node = select(literal(1).label("node")).cte("nodes", recursive=True)
|
| left_edge = select(edge.c.left).join(
| root_node, edge.c.right == root_node.c.node
| )
| right_edge = select(edge.c.right).join(
| root_node, edge.c.left == root_node.c.node
| )
|
| subgraph_cte = root_node.union(left_edge, right_edge)
|
| subgraph = select(subgraph_cte)
|
| The above query will render 2 UNIONs inside the recursive CTE:
|
| .. sourcecode:: sql
|
| WITH RECURSIVE nodes(node) AS (
| SELECT 1 AS node
| UNION
| SELECT edge."left" AS "left"
| FROM edge JOIN nodes ON edge."right" = nodes.node
| UNION
| SELECT edge."right" AS "right"
| FROM edge JOIN nodes ON edge."left" = nodes.node
| )
| SELECT nodes.node FROM nodes
|
| .. seealso::
|
| :meth:`_orm.Query.cte` - ORM version of
| :meth:`_expression.HasCTE.cte`.
|
| ----------------------------------------------------------------------
| Methods inherited from NamedFromClause:
|
| table_valued(self) -> 'TableValuedColumn[Any]'
| Return a :class:`_sql.TableValuedColumn` object for this
| :class:`_expression.FromClause`.
|
| A :class:`_sql.TableValuedColumn` is a :class:`_sql.ColumnElement` that
| represents a complete row in a table. Support for this construct is
| backend dependent, and is supported in various forms by backends
| such as PostgreSQL, Oracle Database and SQL Server.
|
| E.g.:
|
| .. sourcecode:: pycon+sql
|
| >>> from sqlalchemy import select, column, func, table
| >>> a = table("a", column("id"), column("x"), column("y"))
| >>> stmt = select(func.row_to_json(a.table_valued()))
| >>> print(stmt)
| {printsql}SELECT row_to_json(a) AS row_to_json_1
| FROM a
|
| .. versionadded:: 1.4.0b2
|
| .. seealso::
|
| :ref:`tutorial_functions` - in the :ref:`unified_tutorial`
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from NamedFromClause:
|
| named_with_column = True
|
| ----------------------------------------------------------------------
| Methods inherited from FromClause:
|
| c(...)
| A synonym for :attr:`.FromClause.columns`
|
| :return: a :class:`.ColumnCollection`
|
| columns(...)
| 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.
|
| description(...)
| A brief description of this :class:`_expression.FromClause`.
|
| Used primarily for error message formatting.
|
| entity_namespace(...)
| 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.
|
| exported_columns(...)
| A :class:`_expression.ColumnCollection`
| that represents the "exported"
| columns of this :class:`_expression.Selectable`.
|
| 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`
|
| foreign_keys(...)
| Return the collection of :class:`_schema.ForeignKey` marker objects
| which this FromClause references.
|
| Each :class:`_schema.ForeignKey` is a member of a
| :class:`_schema.Table`-wide
| :class:`_schema.ForeignKeyConstraint`.
|
| .. seealso::
|
| :attr:`_schema.Table.foreign_key_constraints`
|
| 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.
|
| 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
|
| 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`
|
| primary_key(...)
| 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.
|
| select(self) -> 'Select[Any]'
| 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.
|
| 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
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from FromClause:
|
| is_selectable = True
|
| schema = None
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.AllowsLambdaRole:
|
| allows_lambda = True
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.UsesInspection:
|
| uses_inspection = True
|
| ----------------------------------------------------------------------
| Methods inherited from Selectable:
|
| 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.
|
| 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`.
|
| .. deprecated:: 1.4 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.
|
| ----------------------------------------------------------------------
| Readonly properties inherited from ReturnsRows:
|
| selectable
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.elements.ClauseElement:
|
| __bool__(self)
|
| __getstate__(self)
| Helper for pickle.
|
| __invert__(self)
|
| __repr__(self)
| Return repr(self).
|
| compare(self, other: 'ClauseElement', **kw: 'Any') -> 'bool'
| Compare this :class:`_expression.ClauseElement` to
| the given :class:`_expression.ClauseElement`.
|
| Subclasses should override the default behavior, which is a
| straight identity comparison.
|
| \**kw are arguments consumed by subclass ``compare()`` methods and
| may be used to modify the criteria for comparison
| (see :class:`_expression.ColumnElement`).
|
| params(self, _ClauseElement__optionaldict: 'Optional[Mapping[str, Any]]' = None, **kwargs: 'Any') -> 'Self'
| Return a copy with :func:`_expression.bindparam` elements
| replaced.
|
| Returns a copy of this ClauseElement with
| :func:`_expression.bindparam`
| elements replaced with values taken from the given dictionary::
|
| >>> clause = column("x") + bindparam("foo")
| >>> print(clause.compile().params)
| {'foo':None}
| >>> print(clause.params({"foo": 7}).compile().params)
| {'foo':7}
|
| self_group(self, against: 'Optional[OperatorType]' = None) -> 'ClauseElement'
| 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.
|
| unique_params(self, _ClauseElement__optionaldict: 'Optional[Dict[str, Any]]' = None, **kwargs: 'Any') -> 'Self'
| Return a copy with :func:`_expression.bindparam` elements
| replaced.
|
| Same functionality as :meth:`_expression.ClauseElement.params`,
| except adds `unique=True`
| to affected bind parameters so that multiple statements can be
| used.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.elements.ClauseElement:
|
| is_clause_element = True
|
| is_dml = False
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.cache_key.HasCacheKey:
|
| inherit_cache = None
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_instancemethod(fn: '_F') -> '_F'
| Decorate a method memoize its return value.
|
| :meta private:
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_attribute = <class 'sqlalchemy.util.langhelpers.HasMemoized.m...
| A read-only @property that is only evaluated once.
|
| :meta private:
|
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.visitors.HasTraverseInternals:
|
| get_children(self, *, omit_attrs: 'Tuple[str, ...]' = (), **kw: 'Any') -> 'Iterable[HasTraverseInternals]'
| Return immediate child :class:`.visitors.HasTraverseInternals`
| elements of this :class:`.visitors.HasTraverseInternals`.
|
| This is used for visit traversal.
|
| \**kw may contain flags that change the collection that is
| returned, for example to return a subset of items in order to
| cut down on larger traversals, or to return child items from a
| different context (such as schema-level collections instead of
| clause-level).
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.elements.CompilerElement:
|
| __str__(self) -> 'str'
| Return str(self).
|
| compile(self, bind: 'Optional[_HasDialect]' = None, dialect: 'Optional[Dialect]' = None, **kw: 'Any') -> 'Compiled'
| Compile this SQL expression.
|
| The return value is a :class:`~.Compiled` object.
| Calling ``str()`` or ``unicode()`` on the returned value will yield a
| string representation of the result. The
| :class:`~.Compiled` object also can return a
| dictionary of bind parameter names and values
| using the ``params`` accessor.
|
| :param bind: An :class:`.Connection` or :class:`.Engine` which
| can provide a :class:`.Dialect` in order to generate a
| :class:`.Compiled` object. If the ``bind`` and
| ``dialect`` parameters are both omitted, a default SQL compiler
| is used.
|
| :param column_keys: Used for INSERT and UPDATE statements, a list of
| column names which should be present in the VALUES clause of the
| compiled statement. If ``None``, all columns from the target table
| object are rendered.
|
| :param dialect: A :class:`.Dialect` instance which can generate
| a :class:`.Compiled` object. This argument takes precedence over
| the ``bind`` argument.
|
| :param compile_kwargs: optional dictionary of additional parameters
| that will be passed through to the compiler within all "visit"
| methods. This allows any custom flag to be passed through to
| a custom compilation construct, for example. It is also used
| for the case of passing the ``literal_binds`` flag through::
|
| from sqlalchemy.sql import table, column, select
|
| t = table("t", column("x"))
|
| s = select(t).where(t.c.x == 5)
|
| print(s.compile(compile_kwargs={"literal_binds": True}))
|
| .. seealso::
|
| :ref:`faq_sql_expression_string`
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.elements.CompilerElement:
|
| stringify_dialect = 'default'
|
| supports_execution = False
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.visitors.Visitable:
|
| __class_getitem__(key: 'Any') -> 'Any'
|
| __init_subclass__() -> 'None'
| This method is called when a class is subclassed.
|
| The default implementation does nothing. It may be
| overridden to extend subclasses.
sqlalchemy.ValuesBase
Python Library Documentation: class ValuesBase in module sqlalchemy.sql.dml
class ValuesBase(UpdateBase)
| ValuesBase(table: '_DMLTableArgument')
|
| Supplies support for :meth:`.ValuesBase.values` to
| INSERT and UPDATE constructs.
|
| Method resolution order:
| ValuesBase
| UpdateBase
| sqlalchemy.sql.roles.DMLRole
| sqlalchemy.sql.selectable.HasCTE
| sqlalchemy.sql.roles.HasCTERole
| sqlalchemy.sql.selectable.SelectsRows
| sqlalchemy.sql.base.HasCompileState
| sqlalchemy.sql.base.DialectKWArgs
| sqlalchemy.sql.selectable.HasPrefixes
| sqlalchemy.sql.base.Generative
| sqlalchemy.sql.selectable.ExecutableReturnsRows
| sqlalchemy.sql.base.Executable
| sqlalchemy.sql.roles.StatementRole
| sqlalchemy.sql.selectable.ReturnsRows
| sqlalchemy.sql.roles.ReturnsRowsRole
| sqlalchemy.sql.roles.SQLRole
| sqlalchemy.sql.elements.DQLDMLClauseElement
| sqlalchemy.sql.elements.ClauseElement
| sqlalchemy.sql.annotation.SupportsWrappingAnnotations
| sqlalchemy.sql.annotation.SupportsAnnotations
| sqlalchemy.sql.cache_key.MemoizedHasCacheKey
| sqlalchemy.sql.cache_key.HasCacheKey
| sqlalchemy.util.langhelpers.HasMemoized
| sqlalchemy.sql.traversals.HasCopyInternals
| sqlalchemy.sql.visitors.ExternallyTraversible
| sqlalchemy.sql.visitors.HasTraverseInternals
| sqlalchemy.sql.elements.CompilerElement
| sqlalchemy.sql.visitors.Visitable
| builtins.object
|
| Methods defined here:
|
| __init__(self, table: '_DMLTableArgument')
| Initialize self. See help(type(self)) for accurate signature.
|
| values(self, *args: 'Union[_DMLColumnKeyMapping[Any], Sequence[Any]]', **kwargs: 'Any') -> 'Self'
| Specify a fixed VALUES clause for an INSERT statement, or the SET
| clause for an UPDATE.
|
| Note that the :class:`_expression.Insert` and
| :class:`_expression.Update`
| constructs support
| per-execution time formatting of the VALUES and/or SET clauses,
| based on the arguments passed to :meth:`_engine.Connection.execute`.
| However, the :meth:`.ValuesBase.values` method can be used to "fix" a
| particular set of parameters into the statement.
|
| Multiple calls to :meth:`.ValuesBase.values` will produce a new
| construct, each one with the parameter list modified to include
| the new parameters sent. In the typical case of a single
| dictionary of parameters, the newly passed keys will replace
| the same keys in the previous construct. In the case of a list-based
| "multiple values" construct, each new list of values is extended
| onto the existing list of values.
|
| :param \**kwargs: key value pairs representing the string key
| of a :class:`_schema.Column`
| mapped to the value to be rendered into the
| VALUES or SET clause::
|
| users.insert().values(name="some name")
|
| users.update().where(users.c.id == 5).values(name="some name")
|
| :param \*args: As an alternative to passing key/value parameters,
| a dictionary, tuple, or list of dictionaries or tuples can be passed
| as a single positional argument in order to form the VALUES or
| SET clause of the statement. The forms that are accepted vary
| based on whether this is an :class:`_expression.Insert` or an
| :class:`_expression.Update` construct.
|
| For either an :class:`_expression.Insert` or
| :class:`_expression.Update`
| construct, a single dictionary can be passed, which works the same as
| that of the kwargs form::
|
| users.insert().values({"name": "some name"})
|
| users.update().values({"name": "some new name"})
|
| Also for either form but more typically for the
| :class:`_expression.Insert` construct, a tuple that contains an
| entry for every column in the table is also accepted::
|
| users.insert().values((5, "some name"))
|
| The :class:`_expression.Insert` construct also supports being
| passed a list of dictionaries or full-table-tuples, which on the
| server will render the less common SQL syntax of "multiple values" -
| this syntax is supported on backends such as SQLite, PostgreSQL,
| MySQL, but not necessarily others::
|
| users.insert().values(
| [
| {"name": "some name"},
| {"name": "some other name"},
| {"name": "yet another name"},
| ]
| )
|
| The above form would render a multiple VALUES statement similar to:
|
| .. sourcecode:: sql
|
| INSERT INTO users (name) VALUES
| (:name_1),
| (:name_2),
| (:name_3)
|
| It is essential to note that **passing multiple values is
| NOT the same as using traditional executemany() form**. The above
| syntax is a **special** syntax not typically used. To emit an
| INSERT statement against multiple rows, the normal method is
| to pass a multiple values list to the
| :meth:`_engine.Connection.execute`
| method, which is supported by all database backends and is generally
| more efficient for a very large number of parameters.
|
| .. seealso::
|
| :ref:`tutorial_multiple_parameters` - an introduction to
| the traditional Core method of multiple parameter set
| invocation for INSERTs and other statements.
|
| :ref:`tutorial_core_insert_values_clause` - Insert tutorial
| detailing alternatives to the multiple values syntax.
|
| The UPDATE construct also supports rendering the SET parameters
| in a specific order. For this feature refer to the
| :meth:`_expression.Update.ordered_values` method.
|
| .. seealso::
|
| :meth:`_expression.Update.ordered_values`
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'_inline': 'bool', '_multi_values': 'Tuple[Union[Se...
|
| __visit_name__ = 'values_base'
|
| select = None
|
| ----------------------------------------------------------------------
| Methods inherited from UpdateBase:
|
| corresponding_column(self, column: 'KeyedColumnElement[Any]', require_embedded: 'bool' = False) -> 'Optional[ColumnElement[Any]]'
|
| exported_columns(...)
| Return the RETURNING columns as a column collection for this
| statement.
|
| .. versionadded:: 1.4
|
| is_derived_from(self, fromclause: 'Optional[FromClause]') -> 'bool'
| Return ``True`` if this :class:`.ReturnsRows` is
| 'derived' from the given :class:`.FromClause`.
|
| Since these are DMLs, we dont want such statements ever being adapted
| so we return False for derives.
|
| params(self, *arg: 'Any', **kw: 'Any') -> 'NoReturn'
| Set the parameters for the statement.
|
| This method raises ``NotImplementedError`` on the base class,
| and is overridden by :class:`.ValuesBase` to provide the
| SET/VALUES clause of UPDATE and INSERT.
|
| return_defaults(self, *cols: '_DMLColumnArgument', supplemental_cols: 'Optional[Iterable[_DMLColumnArgument]]' = None, sort_by_parameter_order: 'bool' = False) -> 'Self'
| Make use of a :term:`RETURNING` clause for the purpose
| of fetching server-side expressions and defaults, for supporting
| backends only.
|
| .. deepalchemy::
|
| The :meth:`.UpdateBase.return_defaults` method is used by the ORM
| for its internal work in fetching newly generated primary key
| and server default values, in particular to provide the underlying
| implementation of the :paramref:`_orm.Mapper.eager_defaults`
| ORM feature as well as to allow RETURNING support with bulk
| ORM inserts. Its behavior is fairly idiosyncratic
| and is not really intended for general use. End users should
| stick with using :meth:`.UpdateBase.returning` in order to
| add RETURNING clauses to their INSERT, UPDATE and DELETE
| statements.
|
| Normally, a single row INSERT statement will automatically populate the
| :attr:`.CursorResult.inserted_primary_key` attribute when executed,
| which stores the primary key of the row that was just inserted in the
| form of a :class:`.Row` object with column names as named tuple keys
| (and the :attr:`.Row._mapping` view fully populated as well). The
| dialect in use chooses the strategy to use in order to populate this
| data; if it was generated using server-side defaults and / or SQL
| expressions, dialect-specific approaches such as ``cursor.lastrowid``
| or ``RETURNING`` are typically used to acquire the new primary key
| value.
|
| However, when the statement is modified by calling
| :meth:`.UpdateBase.return_defaults` before executing the statement,
| additional behaviors take place **only** for backends that support
| RETURNING and for :class:`.Table` objects that maintain the
| :paramref:`.Table.implicit_returning` parameter at its default value of
| ``True``. In these cases, when the :class:`.CursorResult` is returned
| from the statement's execution, not only will
| :attr:`.CursorResult.inserted_primary_key` be populated as always, the
| :attr:`.CursorResult.returned_defaults` attribute will also be
| populated with a :class:`.Row` named-tuple representing the full range
| of server generated
| values from that single row, including values for any columns that
| specify :paramref:`_schema.Column.server_default` or which make use of
| :paramref:`_schema.Column.default` using a SQL expression.
|
| When invoking INSERT statements with multiple rows using
| :ref:`insertmanyvalues <engine_insertmanyvalues>`, the
| :meth:`.UpdateBase.return_defaults` modifier will have the effect of
| the :attr:`_engine.CursorResult.inserted_primary_key_rows` and
| :attr:`_engine.CursorResult.returned_defaults_rows` attributes being
| fully populated with lists of :class:`.Row` objects representing newly
| inserted primary key values as well as newly inserted server generated
| values for each row inserted. The
| :attr:`.CursorResult.inserted_primary_key` and
| :attr:`.CursorResult.returned_defaults` attributes will also continue
| to be populated with the first row of these two collections.
|
| If the backend does not support RETURNING or the :class:`.Table` in use
| has disabled :paramref:`.Table.implicit_returning`, then no RETURNING
| clause is added and no additional data is fetched, however the
| INSERT, UPDATE or DELETE statement proceeds normally.
|
| E.g.::
|
| stmt = table.insert().values(data="newdata").return_defaults()
|
| result = connection.execute(stmt)
|
| server_created_at = result.returned_defaults["created_at"]
|
| When used against an UPDATE statement
| :meth:`.UpdateBase.return_defaults` instead looks for columns that
| include :paramref:`_schema.Column.onupdate` or
| :paramref:`_schema.Column.server_onupdate` parameters assigned, when
| constructing the columns that will be included in the RETURNING clause
| by default if explicit columns were not specified. When used against a
| DELETE statement, no columns are included in RETURNING by default, they
| instead must be specified explicitly as there are no columns that
| normally change values when a DELETE statement proceeds.
|
| .. versionadded:: 2.0 :meth:`.UpdateBase.return_defaults` is supported
| for DELETE statements also and has been moved from
| :class:`.ValuesBase` to :class:`.UpdateBase`.
|
| The :meth:`.UpdateBase.return_defaults` method is mutually exclusive
| against the :meth:`.UpdateBase.returning` method and errors will be
| raised during the SQL compilation process if both are used at the same
| time on one statement. The RETURNING clause of the INSERT, UPDATE or
| DELETE statement is therefore controlled by only one of these methods
| at a time.
|
| The :meth:`.UpdateBase.return_defaults` method differs from
| :meth:`.UpdateBase.returning` in these ways:
|
| 1. :meth:`.UpdateBase.return_defaults` method causes the
| :attr:`.CursorResult.returned_defaults` collection to be populated
| with the first row from the RETURNING result. This attribute is not
| populated when using :meth:`.UpdateBase.returning`.
|
| 2. :meth:`.UpdateBase.return_defaults` is compatible with existing
| logic used to fetch auto-generated primary key values that are then
| populated into the :attr:`.CursorResult.inserted_primary_key`
| attribute. By contrast, using :meth:`.UpdateBase.returning` will
| have the effect of the :attr:`.CursorResult.inserted_primary_key`
| attribute being left unpopulated.
|
| 3. :meth:`.UpdateBase.return_defaults` can be called against any
| backend. Backends that don't support RETURNING will skip the usage
| of the feature, rather than raising an exception, *unless*
| ``supplemental_cols`` is passed. The return value
| of :attr:`_engine.CursorResult.returned_defaults` will be ``None``
| for backends that don't support RETURNING or for which the target
| :class:`.Table` sets :paramref:`.Table.implicit_returning` to
| ``False``.
|
| 4. An INSERT statement invoked with executemany() is supported if the
| backend database driver supports the
| :ref:`insertmanyvalues <engine_insertmanyvalues>`
| feature which is now supported by most SQLAlchemy-included backends.
| When executemany is used, the
| :attr:`_engine.CursorResult.returned_defaults_rows` and
| :attr:`_engine.CursorResult.inserted_primary_key_rows` accessors
| will return the inserted defaults and primary keys.
|
| .. versionadded:: 1.4 Added
| :attr:`_engine.CursorResult.returned_defaults_rows` and
| :attr:`_engine.CursorResult.inserted_primary_key_rows` accessors.
| In version 2.0, the underlying implementation which fetches and
| populates the data for these attributes was generalized to be
| supported by most backends, whereas in 1.4 they were only
| supported by the ``psycopg2`` driver.
|
|
| :param cols: optional list of column key names or
| :class:`_schema.Column` that acts as a filter for those columns that
| will be fetched.
| :param supplemental_cols: optional list of RETURNING expressions,
| in the same form as one would pass to the
| :meth:`.UpdateBase.returning` method. When present, the additional
| columns will be included in the RETURNING clause, and the
| :class:`.CursorResult` object will be "rewound" when returned, so
| that methods like :meth:`.CursorResult.all` will return new rows
| mostly as though the statement used :meth:`.UpdateBase.returning`
| directly. However, unlike when using :meth:`.UpdateBase.returning`
| directly, the **order of the columns is undefined**, so can only be
| targeted using names or :attr:`.Row._mapping` keys; they cannot
| reliably be targeted positionally.
|
| .. versionadded:: 2.0
|
| :param sort_by_parameter_order: for a batch INSERT that is being
| executed against multiple parameter sets, organize the results of
| RETURNING so that the returned rows correspond to the order of
| parameter sets passed in. This applies only to an :term:`executemany`
| execution for supporting dialects and typically makes use of the
| :term:`insertmanyvalues` feature.
|
| .. versionadded:: 2.0.10
|
| .. seealso::
|
| :ref:`engine_insertmanyvalues_returning_order` - background on
| sorting of RETURNING rows for bulk INSERT
|
| .. seealso::
|
| :meth:`.UpdateBase.returning`
|
| :attr:`_engine.CursorResult.returned_defaults`
|
| :attr:`_engine.CursorResult.returned_defaults_rows`
|
| :attr:`_engine.CursorResult.inserted_primary_key`
|
| :attr:`_engine.CursorResult.inserted_primary_key_rows`
|
| returning(self, *cols: '_ColumnsClauseArgument[Any]', sort_by_parameter_order: 'bool' = False, **_UpdateBase__kw: 'Any') -> 'UpdateBase'
| Add a :term:`RETURNING` or equivalent clause to this statement.
|
| e.g.:
|
| .. sourcecode:: pycon+sql
|
| >>> stmt = (
| ... table.update()
| ... .where(table.c.data == "value")
| ... .values(status="X")
| ... .returning(table.c.server_flag, table.c.updated_timestamp)
| ... )
| >>> print(stmt)
| {printsql}UPDATE some_table SET status=:status
| WHERE some_table.data = :data_1
| RETURNING some_table.server_flag, some_table.updated_timestamp
|
| The method may be invoked multiple times to add new entries to the
| list of expressions to be returned.
|
| .. versionadded:: 1.4.0b2 The method may be invoked multiple times to
| add new entries to the list of expressions to be returned.
|
| The given collection of column expressions should be derived from the
| table that is the target of the INSERT, UPDATE, or DELETE. While
| :class:`_schema.Column` objects are typical, the elements can also be
| expressions:
|
| .. sourcecode:: pycon+sql
|
| >>> stmt = table.insert().returning(
| ... (table.c.first_name + " " + table.c.last_name).label("fullname")
| ... )
| >>> print(stmt)
| {printsql}INSERT INTO some_table (first_name, last_name)
| VALUES (:first_name, :last_name)
| RETURNING some_table.first_name || :first_name_1 || some_table.last_name AS fullname
|
| Upon compilation, a RETURNING clause, or database equivalent,
| will be rendered within the statement. For INSERT and UPDATE,
| the values are the newly inserted/updated values. For DELETE,
| the values are those of the rows which were deleted.
|
| Upon execution, the values of the columns to be returned are made
| available via the result set and can be iterated using
| :meth:`_engine.CursorResult.fetchone` and similar.
| For DBAPIs which do not
| natively support returning values (i.e. cx_oracle), SQLAlchemy will
| approximate this behavior at the result level so that a reasonable
| amount of behavioral neutrality is provided.
|
| Note that not all databases/DBAPIs
| support RETURNING. For those backends with no support,
| an exception is raised upon compilation and/or execution.
| For those who do support it, the functionality across backends
| varies greatly, including restrictions on executemany()
| and other statements which return multiple rows. Please
| read the documentation notes for the database in use in
| order to determine the availability of RETURNING.
|
| :param \*cols: series of columns, SQL expressions, or whole tables
| entities to be returned.
| :param sort_by_parameter_order: for a batch INSERT that is being
| executed against multiple parameter sets, organize the results of
| RETURNING so that the returned rows correspond to the order of
| parameter sets passed in. This applies only to an :term:`executemany`
| execution for supporting dialects and typically makes use of the
| :term:`insertmanyvalues` feature.
|
| .. versionadded:: 2.0.10
|
| .. seealso::
|
| :ref:`engine_insertmanyvalues_returning_order` - background on
| sorting of RETURNING rows for bulk INSERT (Core level discussion)
|
| :ref:`orm_queryguide_bulk_insert_returning_ordered` - example of
| use with :ref:`orm_queryguide_bulk_insert` (ORM level discussion)
|
| .. seealso::
|
| :meth:`.UpdateBase.return_defaults` - an alternative method tailored
| towards efficient fetching of server-side defaults and triggers
| for single-row INSERTs or UPDATEs.
|
| :ref:`tutorial_insert_returning` - in the :ref:`unified_tutorial`
|
| with_dialect_options(self, **opt: 'Any') -> 'Self'
| Add dialect options to this INSERT/UPDATE/DELETE object.
|
| e.g.::
|
| upd = table.update().dialect_options(mysql_limit=10)
|
| .. versionadded: 1.4 - this method supersedes the dialect options
| associated with the constructor.
|
| with_hint(self, text: 'str', selectable: 'Optional[_DMLTableArgument]' = None, dialect_name: 'str' = '*') -> 'Self'
| Add a table hint for a single table to this
| INSERT/UPDATE/DELETE statement.
|
| .. note::
|
| :meth:`.UpdateBase.with_hint` currently applies only to
| Microsoft SQL Server. For MySQL INSERT/UPDATE/DELETE hints, use
| :meth:`.UpdateBase.prefix_with`.
|
| The text of the hint is rendered in the appropriate
| location for the database backend in use, relative
| to the :class:`_schema.Table` that is the subject of this
| statement, or optionally to that of the given
| :class:`_schema.Table` passed as the ``selectable`` argument.
|
| The ``dialect_name`` option will limit the rendering of a particular
| hint to a particular backend. Such as, to add a hint
| that only takes effect for SQL Server::
|
| mytable.insert().with_hint("WITH (PAGLOCK)", dialect_name="mssql")
|
| :param text: Text of the hint.
| :param selectable: optional :class:`_schema.Table` that specifies
| an element of the FROM clause within an UPDATE or DELETE
| to be the subject of the hint - applies only to certain backends.
| :param dialect_name: defaults to ``*``, if specified as the name
| of a particular dialect, will apply these hints only when
| that dialect is in use.
|
| ----------------------------------------------------------------------
| Readonly properties inherited from UpdateBase:
|
| entity_description
| Return a :term:`plugin-enabled` description of the table and/or
| entity which this DML construct is operating against.
|
| This attribute is generally useful when using the ORM, as an
| extended structure which includes information about mapped
| entities is returned. The section :ref:`queryguide_inspection`
| contains more background.
|
| For a Core statement, the structure returned by this accessor
| is derived from the :attr:`.UpdateBase.table` attribute, and
| refers to the :class:`.Table` being inserted, updated, or deleted::
|
| >>> stmt = insert(user_table)
| >>> stmt.entity_description
| {
| "name": "user_table",
| "table": Table("user_table", ...)
| }
|
| .. versionadded:: 1.4.33
|
| .. seealso::
|
| :attr:`.UpdateBase.returning_column_descriptions`
|
| :attr:`.Select.column_descriptions` - entity information for
| a :func:`.select` construct
|
| :ref:`queryguide_inspection` - ORM background
|
| returning_column_descriptions
| Return a :term:`plugin-enabled` description of the columns
| which this DML construct is RETURNING against, in other words
| the expressions established as part of :meth:`.UpdateBase.returning`.
|
| This attribute is generally useful when using the ORM, as an
| extended structure which includes information about mapped
| entities is returned. The section :ref:`queryguide_inspection`
| contains more background.
|
| For a Core statement, the structure returned by this accessor is
| derived from the same objects that are returned by the
| :attr:`.UpdateBase.exported_columns` accessor::
|
| >>> stmt = insert(user_table).returning(user_table.c.id, user_table.c.name)
| >>> stmt.entity_description
| [
| {
| "name": "id",
| "type": Integer,
| "expr": Column("id", Integer(), table=<user>, ...)
| },
| {
| "name": "name",
| "type": String(),
| "expr": Column("name", String(), table=<user>, ...)
| },
| ]
|
| .. versionadded:: 1.4.33
|
| .. seealso::
|
| :attr:`.UpdateBase.entity_description`
|
| :attr:`.Select.column_descriptions` - entity information for
| a :func:`.select` construct
|
| :ref:`queryguide_inspection` - ORM background
|
| ----------------------------------------------------------------------
| Data descriptors inherited from UpdateBase:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from UpdateBase:
|
| is_dml = True
|
| named_with_column = False
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.selectable.HasCTE:
|
| add_cte(self, *ctes: 'CTE', nest_here: 'bool' = False) -> 'Self'
| Add one or more :class:`_sql.CTE` constructs to this statement.
|
| This method will associate the given :class:`_sql.CTE` constructs with
| the parent statement such that they will each be unconditionally
| rendered in the WITH clause of the final statement, even if not
| referenced elsewhere within the statement or any sub-selects.
|
| The optional :paramref:`.HasCTE.add_cte.nest_here` parameter when set
| to True will have the effect that each given :class:`_sql.CTE` will
| render in a WITH clause rendered directly along with this statement,
| rather than being moved to the top of the ultimate rendered statement,
| even if this statement is rendered as a subquery within a larger
| statement.
|
| This method has two general uses. One is to embed CTE statements that
| serve some purpose without being referenced explicitly, such as the use
| case of embedding a DML statement such as an INSERT or UPDATE as a CTE
| inline with a primary statement that may draw from its results
| indirectly. The other is to provide control over the exact placement
| of a particular series of CTE constructs that should remain rendered
| directly in terms of a particular statement that may be nested in a
| larger statement.
|
| E.g.::
|
| from sqlalchemy import table, column, select
|
| t = table("t", column("c1"), column("c2"))
|
| ins = t.insert().values({"c1": "x", "c2": "y"}).cte()
|
| stmt = select(t).add_cte(ins)
|
| Would render:
|
| .. sourcecode:: sql
|
| WITH anon_1 AS (
| INSERT INTO t (c1, c2) VALUES (:param_1, :param_2)
| )
| SELECT t.c1, t.c2
| FROM t
|
| Above, the "anon_1" CTE is not referenced in the SELECT
| statement, however still accomplishes the task of running an INSERT
| statement.
|
| Similarly in a DML-related context, using the PostgreSQL
| :class:`_postgresql.Insert` construct to generate an "upsert"::
|
| from sqlalchemy import table, column
| from sqlalchemy.dialects.postgresql import insert
|
| t = table("t", column("c1"), column("c2"))
|
| delete_statement_cte = t.delete().where(t.c.c1 < 1).cte("deletions")
|
| insert_stmt = insert(t).values({"c1": 1, "c2": 2})
| update_statement = insert_stmt.on_conflict_do_update(
| index_elements=[t.c.c1],
| set_={
| "c1": insert_stmt.excluded.c1,
| "c2": insert_stmt.excluded.c2,
| },
| ).add_cte(delete_statement_cte)
|
| print(update_statement)
|
| The above statement renders as:
|
| .. sourcecode:: sql
|
| WITH deletions AS (
| DELETE FROM t WHERE t.c1 < %(c1_1)s
| )
| INSERT INTO t (c1, c2) VALUES (%(c1)s, %(c2)s)
| ON CONFLICT (c1) DO UPDATE SET c1 = excluded.c1, c2 = excluded.c2
|
| .. versionadded:: 1.4.21
|
| :param \*ctes: zero or more :class:`.CTE` constructs.
|
| .. versionchanged:: 2.0 Multiple CTE instances are accepted
|
| :param nest_here: if True, the given CTE or CTEs will be rendered
| as though they specified the :paramref:`.HasCTE.cte.nesting` flag
| to ``True`` when they were added to this :class:`.HasCTE`.
| Assuming the given CTEs are not referenced in an outer-enclosing
| statement as well, the CTEs given should render at the level of
| this statement when this flag is given.
|
| .. versionadded:: 2.0
|
| .. seealso::
|
| :paramref:`.HasCTE.cte.nesting`
|
| cte(self, name: 'Optional[str]' = None, recursive: 'bool' = False, nesting: 'bool' = False) -> 'CTE'
| Return a new :class:`_expression.CTE`,
| or Common Table Expression instance.
|
| Common table expressions are a SQL standard whereby SELECT
| statements can draw upon secondary statements specified along
| with the primary statement, using a clause called "WITH".
| Special semantics regarding UNION can also be employed to
| allow "recursive" queries, where a SELECT statement can draw
| upon the set of rows that have previously been selected.
|
| CTEs can also be applied to DML constructs UPDATE, INSERT
| and DELETE on some databases, both as a source of CTE rows
| when combined with RETURNING, as well as a consumer of
| CTE rows.
|
| SQLAlchemy detects :class:`_expression.CTE` objects, which are treated
| similarly to :class:`_expression.Alias` objects, as special elements
| to be delivered to the FROM clause of the statement as well
| as to a WITH clause at the top of the statement.
|
| For special prefixes such as PostgreSQL "MATERIALIZED" and
| "NOT MATERIALIZED", the :meth:`_expression.CTE.prefix_with`
| method may be
| used to establish these.
|
| .. versionchanged:: 1.3.13 Added support for prefixes.
| In particular - MATERIALIZED and NOT MATERIALIZED.
|
| :param name: name given to the common table expression. Like
| :meth:`_expression.FromClause.alias`, the name can be left as
| ``None`` in which case an anonymous symbol will be used at query
| compile time.
| :param recursive: if ``True``, will render ``WITH RECURSIVE``.
| A recursive common table expression is intended to be used in
| conjunction with UNION ALL in order to derive rows
| from those already selected.
| :param nesting: if ``True``, will render the CTE locally to the
| statement in which it is referenced. For more complex scenarios,
| the :meth:`.HasCTE.add_cte` method using the
| :paramref:`.HasCTE.add_cte.nest_here`
| parameter may also be used to more carefully
| control the exact placement of a particular CTE.
|
| .. versionadded:: 1.4.24
|
| .. seealso::
|
| :meth:`.HasCTE.add_cte`
|
| The following examples include two from PostgreSQL's documentation at
| https://www.postgresql.org/docs/current/static/queries-with.html,
| as well as additional examples.
|
| Example 1, non recursive::
|
| from sqlalchemy import (
| Table,
| Column,
| String,
| Integer,
| MetaData,
| select,
| func,
| )
|
| metadata = MetaData()
|
| orders = Table(
| "orders",
| metadata,
| Column("region", String),
| Column("amount", Integer),
| Column("product", String),
| Column("quantity", Integer),
| )
|
| regional_sales = (
| select(orders.c.region, func.sum(orders.c.amount).label("total_sales"))
| .group_by(orders.c.region)
| .cte("regional_sales")
| )
|
|
| top_regions = (
| select(regional_sales.c.region)
| .where(
| regional_sales.c.total_sales
| > select(func.sum(regional_sales.c.total_sales) / 10)
| )
| .cte("top_regions")
| )
|
| statement = (
| select(
| orders.c.region,
| orders.c.product,
| func.sum(orders.c.quantity).label("product_units"),
| func.sum(orders.c.amount).label("product_sales"),
| )
| .where(orders.c.region.in_(select(top_regions.c.region)))
| .group_by(orders.c.region, orders.c.product)
| )
|
| result = conn.execute(statement).fetchall()
|
| Example 2, WITH RECURSIVE::
|
| from sqlalchemy import (
| Table,
| Column,
| String,
| Integer,
| MetaData,
| select,
| func,
| )
|
| metadata = MetaData()
|
| parts = Table(
| "parts",
| metadata,
| Column("part", String),
| Column("sub_part", String),
| Column("quantity", Integer),
| )
|
| included_parts = (
| select(parts.c.sub_part, parts.c.part, parts.c.quantity)
| .where(parts.c.part == "our part")
| .cte(recursive=True)
| )
|
|
| incl_alias = included_parts.alias()
| parts_alias = parts.alias()
| included_parts = included_parts.union_all(
| select(
| parts_alias.c.sub_part, parts_alias.c.part, parts_alias.c.quantity
| ).where(parts_alias.c.part == incl_alias.c.sub_part)
| )
|
| statement = select(
| included_parts.c.sub_part,
| func.sum(included_parts.c.quantity).label("total_quantity"),
| ).group_by(included_parts.c.sub_part)
|
| result = conn.execute(statement).fetchall()
|
| Example 3, an upsert using UPDATE and INSERT with CTEs::
|
| from datetime import date
| from sqlalchemy import (
| MetaData,
| Table,
| Column,
| Integer,
| Date,
| select,
| literal,
| and_,
| exists,
| )
|
| metadata = MetaData()
|
| visitors = Table(
| "visitors",
| metadata,
| Column("product_id", Integer, primary_key=True),
| Column("date", Date, primary_key=True),
| Column("count", Integer),
| )
|
| # add 5 visitors for the product_id == 1
| product_id = 1
| day = date.today()
| count = 5
|
| update_cte = (
| visitors.update()
| .where(
| and_(visitors.c.product_id == product_id, visitors.c.date == day)
| )
| .values(count=visitors.c.count + count)
| .returning(literal(1))
| .cte("update_cte")
| )
|
| upsert = visitors.insert().from_select(
| [visitors.c.product_id, visitors.c.date, visitors.c.count],
| select(literal(product_id), literal(day), literal(count)).where(
| ~exists(update_cte.select())
| ),
| )
|
| connection.execute(upsert)
|
| Example 4, Nesting CTE (SQLAlchemy 1.4.24 and above)::
|
| value_a = select(literal("root").label("n")).cte("value_a")
|
| # A nested CTE with the same name as the root one
| value_a_nested = select(literal("nesting").label("n")).cte(
| "value_a", nesting=True
| )
|
| # Nesting CTEs takes ascendency locally
| # over the CTEs at a higher level
| value_b = select(value_a_nested.c.n).cte("value_b")
|
| value_ab = select(value_a.c.n.label("a"), value_b.c.n.label("b"))
|
| The above query will render the second CTE nested inside the first,
| shown with inline parameters below as:
|
| .. sourcecode:: sql
|
| WITH
| value_a AS
| (SELECT 'root' AS n),
| value_b AS
| (WITH value_a AS
| (SELECT 'nesting' AS n)
| SELECT value_a.n AS n FROM value_a)
| SELECT value_a.n AS a, value_b.n AS b
| FROM value_a, value_b
|
| The same CTE can be set up using the :meth:`.HasCTE.add_cte` method
| as follows (SQLAlchemy 2.0 and above)::
|
| value_a = select(literal("root").label("n")).cte("value_a")
|
| # A nested CTE with the same name as the root one
| value_a_nested = select(literal("nesting").label("n")).cte("value_a")
|
| # Nesting CTEs takes ascendency locally
| # over the CTEs at a higher level
| value_b = (
| select(value_a_nested.c.n)
| .add_cte(value_a_nested, nest_here=True)
| .cte("value_b")
| )
|
| value_ab = select(value_a.c.n.label("a"), value_b.c.n.label("b"))
|
| Example 5, Non-Linear CTE (SQLAlchemy 1.4.28 and above)::
|
| edge = Table(
| "edge",
| metadata,
| Column("id", Integer, primary_key=True),
| Column("left", Integer),
| Column("right", Integer),
| )
|
| root_node = select(literal(1).label("node")).cte("nodes", recursive=True)
|
| left_edge = select(edge.c.left).join(
| root_node, edge.c.right == root_node.c.node
| )
| right_edge = select(edge.c.right).join(
| root_node, edge.c.left == root_node.c.node
| )
|
| subgraph_cte = root_node.union(left_edge, right_edge)
|
| subgraph = select(subgraph_cte)
|
| The above query will render 2 UNIONs inside the recursive CTE:
|
| .. sourcecode:: sql
|
| WITH RECURSIVE nodes(node) AS (
| SELECT 1 AS node
| UNION
| SELECT edge."left" AS "left"
| FROM edge JOIN nodes ON edge."right" = nodes.node
| UNION
| SELECT edge."right" AS "right"
| FROM edge JOIN nodes ON edge."left" = nodes.node
| )
| SELECT nodes.node FROM nodes
|
| .. seealso::
|
| :meth:`_orm.Query.cte` - ORM version of
| :meth:`_expression.HasCTE.cte`.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.selectable.HasCTE:
|
| name_cte_columns = False
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.base.DialectKWArgs:
|
| dialect_options(...)
| A collection of keyword arguments specified as dialect-specific
| options to this construct.
|
| This is a two-level nested registry, keyed to ``<dialect_name>``
| and ``<argument_name>``. For example, the ``postgresql_where``
| argument would be locatable as::
|
| arg = my_object.dialect_options["postgresql"]["where"]
|
| .. versionadded:: 0.9.2
|
| .. seealso::
|
| :attr:`.DialectKWArgs.dialect_kwargs` - flat dictionary form
|
| get_dialect_option(self, dialect: 'Dialect', argument_name: 'str', *, else_: 'Any' = None, deprecated_fallback: 'Optional[str]' = None) -> 'Any'
| Return the value of a dialect-specific option, or *else_* if
| this dialect does not register the given argument.
|
| This is useful for DDL compilers that may be inherited by
| third-party dialects whose ``construct_arguments`` do not
| include the same set of keys as the parent dialect.
|
| :param dialect: The dialect for which to retrieve the option.
| :param argument_name: The name of the argument to retrieve.
| :param else\_: The value to return if the argument is not present.
| :param deprecated_fallback: Optional dialect name to fall back to
| if the argument is not present for the current dialect. If the
| argument is present for the fallback dialect but not the current
| dialect, a deprecation warning will be emitted.
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.base.DialectKWArgs:
|
| argument_for(dialect_name: 'str', argument_name: 'str', default: 'Any') -> 'None'
| Add a new kind of dialect-specific keyword argument for this class.
|
| E.g.::
|
| Index.argument_for("mydialect", "length", None)
|
| some_index = Index("a", "b", mydialect_length=5)
|
| The :meth:`.DialectKWArgs.argument_for` method is a per-argument
| way adding extra arguments to the
| :attr:`.DefaultDialect.construct_arguments` dictionary. This
| dictionary provides a list of argument names accepted by various
| schema-level constructs on behalf of a dialect.
|
| New dialects should typically specify this dictionary all at once as a
| data member of the dialect class. The use case for ad-hoc addition of
| argument names is typically for end-user code that is also using
| a custom compilation scheme which consumes the additional arguments.
|
| :param dialect_name: name of a dialect. The dialect must be
| locatable, else a :class:`.NoSuchModuleError` is raised. The
| dialect must also include an existing
| :attr:`.DefaultDialect.construct_arguments` collection, indicating
| that it participates in the keyword-argument validation and default
| system, else :class:`.ArgumentError` is raised. If the dialect does
| not include this collection, then any keyword argument can be
| specified on behalf of this dialect already. All dialects packaged
| within SQLAlchemy include this collection, however for third party
| dialects, support may vary.
|
| :param argument_name: name of the parameter.
|
| :param default: default value of the parameter.
|
| ----------------------------------------------------------------------
| Readonly properties inherited from sqlalchemy.sql.base.DialectKWArgs:
|
| dialect_kwargs
| A collection of keyword arguments specified as dialect-specific
| options to this construct.
|
| The arguments are present here in their original ``<dialect>_<kwarg>``
| format. Only arguments that were actually passed are included;
| unlike the :attr:`.DialectKWArgs.dialect_options` collection, which
| contains all options known by this dialect including defaults.
|
| The collection is also writable; keys are accepted of the
| form ``<dialect>_<kwarg>`` where the value will be assembled
| into the list of options.
|
| .. seealso::
|
| :attr:`.DialectKWArgs.dialect_options` - nested dictionary form
|
| kwargs
| A synonym for :attr:`.DialectKWArgs.dialect_kwargs`.
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.selectable.HasPrefixes:
|
| prefix_with(self, *prefixes: '_TextCoercedExpressionArgument[Any]', dialect: 'str' = '*') -> 'Self'
| 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.
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.base.Executable:
|
| execution_options(self, **kw: 'Any') -> 'Self'
| Set non-SQL options for the statement which take effect during
| execution.
|
| Execution options can be set at many scopes, including per-statement,
| per-connection, or per execution, using methods such as
| :meth:`_engine.Connection.execution_options` and parameters which
| accept a dictionary of options such as
| :paramref:`_engine.Connection.execute.execution_options` and
| :paramref:`_orm.Session.execute.execution_options`.
|
| The primary characteristic of an execution option, as opposed to
| other kinds of options such as ORM loader options, is that
| **execution options never affect the compiled SQL of a query, only
| things that affect how the SQL statement itself is invoked or how
| results are fetched**. That is, execution options are not part of
| what's accommodated by SQL compilation nor are they considered part of
| the cached state of a statement.
|
| The :meth:`_sql.Executable.execution_options` method is
| :term:`generative`, as
| is the case for the method as applied to the :class:`_engine.Engine`
| and :class:`_orm.Query` objects, which means when the method is called,
| a copy of the object is returned, which applies the given parameters to
| that new copy, but leaves the original unchanged::
|
| statement = select(table.c.x, table.c.y)
| new_statement = statement.execution_options(my_option=True)
|
| An exception to this behavior is the :class:`_engine.Connection`
| object, where the :meth:`_engine.Connection.execution_options` method
| is explicitly **not** generative.
|
| The kinds of options that may be passed to
| :meth:`_sql.Executable.execution_options` and other related methods and
| parameter dictionaries include parameters that are explicitly consumed
| by SQLAlchemy Core or ORM, as well as arbitrary keyword arguments not
| defined by SQLAlchemy, which means the methods and/or parameter
| dictionaries may be used for user-defined parameters that interact with
| custom code, which may access the parameters using methods such as
| :meth:`_sql.Executable.get_execution_options` and
| :meth:`_engine.Connection.get_execution_options`, or within selected
| event hooks using a dedicated ``execution_options`` event parameter
| such as
| :paramref:`_events.ConnectionEvents.before_execute.execution_options`
| or :attr:`_orm.ORMExecuteState.execution_options`, e.g.::
|
| from sqlalchemy import event
|
|
| @event.listens_for(some_engine, "before_execute")
| def _process_opt(conn, statement, multiparams, params, execution_options):
| "run a SQL function before invoking a statement"
|
| if execution_options.get("do_special_thing", False):
| conn.exec_driver_sql("run_special_function()")
|
| Within the scope of options that are explicitly recognized by
| SQLAlchemy, most apply to specific classes of objects and not others.
| The most common execution options include:
|
| * :paramref:`_engine.Connection.execution_options.isolation_level` -
| sets the isolation level for a connection or a class of connections
| via an :class:`_engine.Engine`. This option is accepted only
| by :class:`_engine.Connection` or :class:`_engine.Engine`.
|
| * :paramref:`_engine.Connection.execution_options.stream_results` -
| indicates results should be fetched using a server side cursor;
| this option is accepted by :class:`_engine.Connection`, by the
| :paramref:`_engine.Connection.execute.execution_options` parameter
| on :meth:`_engine.Connection.execute`, and additionally by
| :meth:`_sql.Executable.execution_options` on a SQL statement object,
| as well as by ORM constructs like :meth:`_orm.Session.execute`.
|
| * :paramref:`_engine.Connection.execution_options.compiled_cache` -
| indicates a dictionary that will serve as the
| :ref:`SQL compilation cache <sql_caching>`
| for a :class:`_engine.Connection` or :class:`_engine.Engine`, as
| well as for ORM methods like :meth:`_orm.Session.execute`.
| Can be passed as ``None`` to disable caching for statements.
| This option is not accepted by
| :meth:`_sql.Executable.execution_options` as it is inadvisable to
| carry along a compilation cache within a statement object.
|
| * :paramref:`_engine.Connection.execution_options.schema_translate_map`
| - a mapping of schema names used by the
| :ref:`Schema Translate Map <schema_translating>` feature, accepted
| by :class:`_engine.Connection`, :class:`_engine.Engine`,
| :class:`_sql.Executable`, as well as by ORM constructs
| like :meth:`_orm.Session.execute`.
|
| .. seealso::
|
| :meth:`_engine.Connection.execution_options`
|
| :paramref:`_engine.Connection.execute.execution_options`
|
| :paramref:`_orm.Session.execute.execution_options`
|
| :ref:`orm_queryguide_execution_options` - documentation on all
| ORM-specific execution options
|
| get_execution_options(self) -> '_ExecuteOptions'
| Get the non-SQL options which will take effect during execution.
|
| .. versionadded:: 1.3
|
| .. seealso::
|
| :meth:`.Executable.execution_options`
|
| options(self, *options: 'ExecutableOption') -> 'Self'
| Apply options to this statement.
|
| In the general sense, options are any kind of Python object
| that can be interpreted by the SQL compiler for the statement.
| These options can be consumed by specific dialects or specific kinds
| of compilers.
|
| The most commonly known kind of option are the ORM level options
| that apply "eager load" and other loading behaviors to an ORM
| query. However, options can theoretically be used for many other
| purposes.
|
| For background on specific kinds of options for specific kinds of
| statements, refer to the documentation for those option objects.
|
| .. versionchanged:: 1.4 - added :meth:`.Executable.options` to
| Core statement objects towards the goal of allowing unified
| Core / ORM querying capabilities.
|
| .. seealso::
|
| :ref:`loading_columns` - refers to options specific to the usage
| of ORM queries
|
| :ref:`relationship_loader_options` - refers to options specific
| to the usage of ORM queries
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.base.Executable:
|
| is_delete = False
|
| is_from_statement = False
|
| is_insert = False
|
| is_select = False
|
| is_text = False
|
| is_update = False
|
| supports_execution = True
|
| ----------------------------------------------------------------------
| Readonly properties inherited from sqlalchemy.sql.selectable.ReturnsRows:
|
| selectable
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.SQLRole:
|
| allows_lambda = False
|
| uses_inspection = False
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.elements.ClauseElement:
|
| __bool__(self)
|
| __getstate__(self)
| Helper for pickle.
|
| __invert__(self)
|
| __repr__(self)
| Return repr(self).
|
| compare(self, other: 'ClauseElement', **kw: 'Any') -> 'bool'
| Compare this :class:`_expression.ClauseElement` to
| the given :class:`_expression.ClauseElement`.
|
| Subclasses should override the default behavior, which is a
| straight identity comparison.
|
| \**kw are arguments consumed by subclass ``compare()`` methods and
| may be used to modify the criteria for comparison
| (see :class:`_expression.ColumnElement`).
|
| description(...)
|
| entity_namespace(...)
|
| self_group(self, against: 'Optional[OperatorType]' = None) -> 'ClauseElement'
| 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.
|
| unique_params(self, _ClauseElement__optionaldict: 'Optional[Dict[str, Any]]' = None, **kwargs: 'Any') -> 'Self'
| Return a copy with :func:`_expression.bindparam` elements
| replaced.
|
| Same functionality as :meth:`_expression.ClauseElement.params`,
| except adds `unique=True`
| to affected bind parameters so that multiple statements can be
| used.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.elements.ClauseElement:
|
| is_clause_element = True
|
| is_selectable = False
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.cache_key.HasCacheKey:
|
| inherit_cache = None
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_instancemethod(fn: '_F') -> '_F'
| Decorate a method memoize its return value.
|
| :meta private:
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_attribute = <class 'sqlalchemy.util.langhelpers.HasMemoized.m...
| A read-only @property that is only evaluated once.
|
| :meta private:
|
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.visitors.HasTraverseInternals:
|
| get_children(self, *, omit_attrs: 'Tuple[str, ...]' = (), **kw: 'Any') -> 'Iterable[HasTraverseInternals]'
| Return immediate child :class:`.visitors.HasTraverseInternals`
| elements of this :class:`.visitors.HasTraverseInternals`.
|
| This is used for visit traversal.
|
| \**kw may contain flags that change the collection that is
| returned, for example to return a subset of items in order to
| cut down on larger traversals, or to return child items from a
| different context (such as schema-level collections instead of
| clause-level).
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.elements.CompilerElement:
|
| __str__(self) -> 'str'
| Return str(self).
|
| compile(self, bind: 'Optional[_HasDialect]' = None, dialect: 'Optional[Dialect]' = None, **kw: 'Any') -> 'Compiled'
| Compile this SQL expression.
|
| The return value is a :class:`~.Compiled` object.
| Calling ``str()`` or ``unicode()`` on the returned value will yield a
| string representation of the result. The
| :class:`~.Compiled` object also can return a
| dictionary of bind parameter names and values
| using the ``params`` accessor.
|
| :param bind: An :class:`.Connection` or :class:`.Engine` which
| can provide a :class:`.Dialect` in order to generate a
| :class:`.Compiled` object. If the ``bind`` and
| ``dialect`` parameters are both omitted, a default SQL compiler
| is used.
|
| :param column_keys: Used for INSERT and UPDATE statements, a list of
| column names which should be present in the VALUES clause of the
| compiled statement. If ``None``, all columns from the target table
| object are rendered.
|
| :param dialect: A :class:`.Dialect` instance which can generate
| a :class:`.Compiled` object. This argument takes precedence over
| the ``bind`` argument.
|
| :param compile_kwargs: optional dictionary of additional parameters
| that will be passed through to the compiler within all "visit"
| methods. This allows any custom flag to be passed through to
| a custom compilation construct, for example. It is also used
| for the case of passing the ``literal_binds`` flag through::
|
| from sqlalchemy.sql import table, column, select
|
| t = table("t", column("x"))
|
| s = select(t).where(t.c.x == 5)
|
| print(s.compile(compile_kwargs={"literal_binds": True}))
|
| .. seealso::
|
| :ref:`faq_sql_expression_string`
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.elements.CompilerElement:
|
| stringify_dialect = 'default'
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.sql.visitors.Visitable:
|
| __class_getitem__(key: 'Any') -> 'Any'
|
| __init_subclass__() -> 'None'
| This method is called when a class is subclassed.
|
| The default implementation does nothing. It may be
| overridden to extend subclasses.
sqlalchemy.Visitable
Python Library Documentation: class Visitable in module sqlalchemy.sql.visitors
class Visitable(builtins.object)
| Base class for visitable objects.
|
| :class:`.Visitable` is used to implement the SQL compiler dispatch
| functions. Other forms of traversal such as for cache key generation
| are implemented separately using the :class:`.HasTraverseInternals`
| interface.
|
| .. versionchanged:: 2.0 The :class:`.Visitable` class was named
| :class:`.Traversible` in the 1.4 series; the name is changed back
| to :class:`.Visitable` in 2.0 which is what it was prior to 1.4.
|
| Both names remain importable in both 1.4 and 2.0 versions.
|
| Class methods defined here:
|
| __class_getitem__(key: 'Any') -> 'Any'
|
| __init_subclass__() -> 'None'
| This method is called when a class is subclassed.
|
| The default implementation does nothing. It may be
| overridden to extend subclasses.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'__visit_name__': 'str', '_original_compiler_dispat...
sqlalchemy.WithinGroup
Python Library Documentation: class WithinGroup in module sqlalchemy.sql.elements
class WithinGroup(ColumnElement)
| WithinGroup(element: 'Union[FunctionElement[_T], FunctionFilter[_T]]', *order_by: '_ColumnExpressionArgument[Any]')
|
| Represent a WITHIN GROUP (ORDER BY) clause.
|
| This is a special operator against so-called
| "ordered set aggregate" and "hypothetical
| set aggregate" functions, including ``percentile_cont()``,
| ``rank()``, ``dense_rank()``, etc.
|
| It's supported only by certain database backends, such as PostgreSQL,
| Oracle Database and MS SQL Server.
|
| The :class:`.WithinGroup` construct extracts its type from the
| method :meth:`.FunctionElement.within_group_type`. If this returns
| ``None``, the function's ``.type`` is used.
|
| Method resolution order:
| WithinGroup
| ColumnElement
| sqlalchemy.sql.roles.ColumnArgumentOrKeyRole
| sqlalchemy.sql.roles.ColumnArgumentRole
| sqlalchemy.sql.roles.StatementOptionRole
| sqlalchemy.sql.roles.WhereHavingRole
| sqlalchemy.sql.roles.OnClauseRole
| sqlalchemy.sql.roles.BinaryElementRole
| sqlalchemy.sql.roles.OrderByRole
| sqlalchemy.sql.roles.ColumnsClauseRole
| sqlalchemy.sql.roles.AllowsLambdaRole
| sqlalchemy.sql.roles.ByOfRole
| sqlalchemy.sql.roles.UsesInspection
| sqlalchemy.sql.roles.ColumnListRole
| sqlalchemy.sql.roles.LimitOffsetRole
| sqlalchemy.sql.roles.DMLColumnRole
| sqlalchemy.sql.roles.DDLConstraintColumnRole
| sqlalchemy.sql.roles.DDLExpressionRole
| sqlalchemy.sql.roles.StructuralRole
| SQLColumnExpression
| SQLCoreOperations
| sqlalchemy.sql.roles.ExpressionElementRole
| sqlalchemy.sql.roles.TypedColumnsClauseRole
| typing.Generic
| sqlalchemy.sql.operators.ColumnOperators
| sqlalchemy.sql.operators.Operators
| sqlalchemy.util.langhelpers.TypingOnly
| sqlalchemy.sql.roles.SQLRole
| DQLDMLClauseElement
| ClauseElement
| sqlalchemy.sql.annotation.SupportsWrappingAnnotations
| sqlalchemy.sql.annotation.SupportsAnnotations
| sqlalchemy.sql.cache_key.MemoizedHasCacheKey
| sqlalchemy.sql.cache_key.HasCacheKey
| sqlalchemy.util.langhelpers.HasMemoized
| sqlalchemy.sql.traversals.HasCopyInternals
| sqlalchemy.sql.visitors.ExternallyTraversible
| sqlalchemy.sql.visitors.HasTraverseInternals
| CompilerElement
| sqlalchemy.sql.visitors.Visitable
| builtins.object
|
| Methods defined here:
|
| __init__(self, element: 'Union[FunctionElement[_T], FunctionFilter[_T]]', *order_by: '_ColumnExpressionArgument[Any]')
| Initialize self. See help(type(self)) for accurate signature.
|
| __reduce__(self)
| Helper for pickle.
|
| filter(self, *criterion: '_ColumnExpressionArgument[bool]') -> 'Union[Self, FunctionFilter[_T]]'
| Produce a FILTER clause against this function.
|
| over(self, *, partition_by: 'Optional[_ByArgument]' = None, order_by: 'Optional[_ByArgument]' = None, rows: 'Optional[typing_Tuple[Optional[int], Optional[int]]]' = None, range_: 'Optional[typing_Tuple[Optional[int], Optional[int]]]' = None, groups: 'Optional[typing_Tuple[Optional[int], Optional[int]]]' = None) -> 'Over[_T]'
| Produce an OVER clause against this :class:`.WithinGroup`
| construct.
|
| This function has the same signature as that of
| :meth:`.FunctionElement.over`.
|
| type(...)
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'_traverse_internals': '_TraverseInternalsType', 'o...
|
| __orig_bases__ = (sqlalchemy.sql.elements.ColumnElement[~_T],)
|
| __parameters__ = (~_T,)
|
| __visit_name__ = 'withingroup'
|
| order_by = None
|
| ----------------------------------------------------------------------
| Methods inherited from ColumnElement:
|
| __getattr__(self, key: 'str') -> 'Any'
|
| __setstate__(self, state)
|
| base_columns(...)
|
| cast(self, type_: '_TypeEngineArgument[_OPT]') -> 'Cast[_OPT]'
| Produce a type cast, i.e. ``CAST(<expression> AS <type>)``.
|
| This is a shortcut to the :func:`_expression.cast` function.
|
| .. seealso::
|
| :ref:`tutorial_casts`
|
| :func:`_expression.cast`
|
| :func:`_expression.type_coerce`
|
| comparator(...)
|
| label(self, name: 'Optional[str]') -> 'Label[_T]'
| Produce a column label, i.e. ``<columnname> AS <name>``.
|
| This is a shortcut to the :func:`_expression.label` function.
|
| If 'name' is ``None``, an anonymous label name will be generated.
|
| operate(self, op: 'operators.OperatorType', *other: 'Any', **kwargs: 'Any') -> 'ColumnElement[Any]'
| Operate on an argument.
|
| This is the lowest level of operation, raises
| :class:`NotImplementedError` by default.
|
| Overriding this on a subclass can allow common
| behavior to be applied to all operations.
| For example, overriding :class:`.ColumnOperators`
| to apply ``func.lower()`` to the left and right
| side::
|
| class MyComparator(ColumnOperators):
| def operate(self, op, other, **kwargs):
| return op(func.lower(self), func.lower(other), **kwargs)
|
| :param op: Operator callable.
| :param \*other: the 'other' side of the operation. Will
| be a single scalar for most operations.
| :param \**kwargs: modifiers. These may be passed by special
| operators such as :meth:`ColumnOperators.contains`.
|
| proxy_set(...)
| set of all columns we are proxying
|
| as of 2.0 this is explicitly deannotated columns. previously it was
| effectively deannotated columns but wasn't enforced. annotated
| columns should basically not go into sets if at all possible because
| their hashing behavior is very non-performant.
|
| reverse_operate(self, op: 'operators.OperatorType', other: 'Any', **kwargs: 'Any') -> 'ColumnElement[Any]'
| Reverse operate on an argument.
|
| Usage is the same as :meth:`operate`.
|
| self_group(self, against: 'Optional[OperatorType]' = None) -> 'ColumnElement[Any]'
| 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.
|
| shares_lineage(self, othercolumn: 'ColumnElement[Any]') -> 'bool'
| Return True if the given :class:`_expression.ColumnElement`
| has a common ancestor to this :class:`_expression.ColumnElement`.
|
| ----------------------------------------------------------------------
| Readonly properties inherited from ColumnElement:
|
| anon_key_label
| .. deprecated:: 1.4 The :attr:`_expression.ColumnElement.anon_key_label` attribute is now private, and the public accessor is deprecated.
|
| anon_label
| .. deprecated:: 1.4 The :attr:`_expression.ColumnElement.anon_label` attribute is now private, and the public accessor is deprecated.
|
| expression
| Return a column expression.
|
| Part of the inspection interface; returns self.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from ColumnElement:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from ColumnElement:
|
| foreign_keys = frozenset()
|
| key = None
|
| primary_key = False
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.AllowsLambdaRole:
|
| allows_lambda = True
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.roles.UsesInspection:
|
| uses_inspection = True
|
| ----------------------------------------------------------------------
| Class methods inherited from typing.Generic:
|
| __class_getitem__(...)
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__(...)
| Function to initialize subclasses.
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.operators.ColumnOperators:
|
| __add__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``+`` operator.
|
| In a column context, produces the clause ``a + b``
| if the parent object has non-string affinity.
| If the parent object has a string affinity,
| produces the concatenation operator, ``a || b`` -
| see :meth:`.ColumnOperators.concat`.
|
| __contains__(self, other: 'Any') -> 'ColumnOperators'
|
| __eq__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``==`` operator.
|
| In a column context, produces the clause ``a = b``.
| If the target is ``None``, produces ``a IS NULL``.
|
| __floordiv__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``//`` operator.
|
| In a column context, produces the clause ``a / b``,
| which is the same as "truediv", but considers the result
| type to be integer.
|
| .. versionadded:: 2.0
|
| __ge__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``>=`` operator.
|
| In a column context, produces the clause ``a >= b``.
|
| __getitem__(self, index: 'Any') -> 'ColumnOperators'
| Implement the [] operator.
|
| This can be used by some database-specific types
| such as PostgreSQL ARRAY and HSTORE.
|
| __gt__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``>`` operator.
|
| In a column context, produces the clause ``a > b``.
|
| __hash__(self, /) from builtins.object
| Return hash(self).
|
| __le__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``<=`` operator.
|
| In a column context, produces the clause ``a <= b``.
|
| __lshift__(self, other: 'Any') -> 'ColumnOperators'
| implement the << operator.
|
| Not used by SQLAlchemy core, this is provided
| for custom operator systems which want to use
| << as an extension point.
|
| __lt__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``<`` operator.
|
| In a column context, produces the clause ``a < b``.
|
| __mod__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``%`` operator.
|
| In a column context, produces the clause ``a % b``.
|
| __mul__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``*`` operator.
|
| In a column context, produces the clause ``a * b``.
|
| __ne__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``!=`` operator.
|
| In a column context, produces the clause ``a != b``.
| If the target is ``None``, produces ``a IS NOT NULL``.
|
| __neg__(self) -> 'ColumnOperators'
| Implement the ``-`` operator.
|
| In a column context, produces the clause ``-a``.
|
| __radd__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``+`` operator in reverse.
|
| See :meth:`.ColumnOperators.__add__`.
|
| __rfloordiv__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``//`` operator in reverse.
|
| See :meth:`.ColumnOperators.__floordiv__`.
|
| __rmod__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``%`` operator in reverse.
|
| See :meth:`.ColumnOperators.__mod__`.
|
| __rmul__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``*`` operator in reverse.
|
| See :meth:`.ColumnOperators.__mul__`.
|
| __rshift__(self, other: 'Any') -> 'ColumnOperators'
| implement the >> operator.
|
| Not used by SQLAlchemy core, this is provided
| for custom operator systems which want to use
| >> as an extension point.
|
| __rsub__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``-`` operator in reverse.
|
| See :meth:`.ColumnOperators.__sub__`.
|
| __rtruediv__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``/`` operator in reverse.
|
| See :meth:`.ColumnOperators.__truediv__`.
|
| __sub__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``-`` operator.
|
| In a column context, produces the clause ``a - b``.
|
| __truediv__(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``/`` operator.
|
| In a column context, produces the clause ``a / b``, and
| considers the result type to be numeric.
|
| .. versionchanged:: 2.0 The truediv operator against two integers
| is now considered to return a numeric value. Behavior on specific
| backends may vary.
|
| all_(self) -> 'ColumnOperators'
| Produce an :func:`_expression.all_` clause against the
| parent object.
|
| See the documentation for :func:`_sql.all_` for examples.
|
| .. note:: be sure to not confuse the newer
| :meth:`_sql.ColumnOperators.all_` method with the **legacy**
| version of this method, the :meth:`_types.ARRAY.Comparator.all`
| method that's specific to :class:`_types.ARRAY`, which uses a
| different calling style.
|
| any_(self) -> 'ColumnOperators'
| Produce an :func:`_expression.any_` clause against the
| parent object.
|
| See the documentation for :func:`_sql.any_` for examples.
|
| .. note:: be sure to not confuse the newer
| :meth:`_sql.ColumnOperators.any_` method with the **legacy**
| version of this method, the :meth:`_types.ARRAY.Comparator.any`
| method that's specific to :class:`_types.ARRAY`, which uses a
| different calling style.
|
| asc(self) -> 'ColumnOperators'
| Produce a :func:`_expression.asc` clause against the
| parent object.
|
| between(self, cleft: 'Any', cright: 'Any', symmetric: 'bool' = False) -> 'ColumnOperators'
| Produce a :func:`_expression.between` clause against
| the parent object, given the lower and upper range.
|
| bitwise_and(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise AND operation, typically via the ``&``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_lshift(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise LSHIFT operation, typically via the ``<<``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_not(self) -> 'ColumnOperators'
| Produce a bitwise NOT operation, typically via the ``~``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_or(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise OR operation, typically via the ``|``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_rshift(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise RSHIFT operation, typically via the ``>>``
| operator.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| bitwise_xor(self, other: 'Any') -> 'ColumnOperators'
| Produce a bitwise XOR operation, typically via the ``^``
| operator, or ``#`` for PostgreSQL.
|
| .. versionadded:: 2.0.2
|
| .. seealso::
|
| :ref:`operators_bitwise`
|
| collate(self, collation: 'str') -> 'ColumnOperators'
| Produce a :func:`_expression.collate` clause against
| the parent object, given the collation string.
|
| .. seealso::
|
| :func:`_expression.collate`
|
| concat(self, other: 'Any') -> 'ColumnOperators'
| Implement the 'concat' operator.
|
| In a column context, produces the clause ``a || b``,
| or uses the ``concat()`` operator on MySQL.
|
| contains(self, other: 'Any', **kw: 'Any') -> 'ColumnOperators'
| Implement the 'contains' operator.
|
| Produces a LIKE expression that tests against a match for the middle
| of a string value:
|
| .. sourcecode:: sql
|
| column LIKE '%' || <other> || '%'
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.contains("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.contains.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.contains.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.contains.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.contains("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE '%' || :param || '%' ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.contains("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE '%' || :param || '%' ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.contains.autoescape`::
|
| somecolumn.contains("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.startswith`
|
| :meth:`.ColumnOperators.endswith`
|
| :meth:`.ColumnOperators.like`
|
| desc(self) -> 'ColumnOperators'
| Produce a :func:`_expression.desc` clause against the
| parent object.
|
| distinct(self) -> 'ColumnOperators'
| Produce a :func:`_expression.distinct` clause against the
| parent object.
|
| endswith(self, other: 'Any', escape: 'Optional[str]' = None, autoescape: 'bool' = False) -> 'ColumnOperators'
| Implement the 'endswith' operator.
|
| Produces a LIKE expression that tests against a match for the end
| of a string value:
|
| .. sourcecode:: sql
|
| column LIKE '%' || <other>
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.endswith("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.endswith.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.endswith.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.endswith.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.endswith("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE '%' || :param ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.endswith("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE '%' || :param ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.endswith.autoescape`::
|
| somecolumn.endswith("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.startswith`
|
| :meth:`.ColumnOperators.contains`
|
| :meth:`.ColumnOperators.like`
|
| icontains(self, other: 'Any', **kw: 'Any') -> 'ColumnOperators'
| Implement the ``icontains`` operator, e.g. case insensitive
| version of :meth:`.ColumnOperators.contains`.
|
| Produces a LIKE expression that tests against an insensitive match
| for the middle of a string value:
|
| .. sourcecode:: sql
|
| lower(column) LIKE '%' || lower(<other>) || '%'
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.icontains("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.icontains.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.icontains.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.icontains.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.icontains("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE '%' || lower(:param) || '%' ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.icontains("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE '%' || lower(:param) || '%' ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.contains.autoescape`::
|
| somecolumn.icontains("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.contains`
|
| iendswith(self, other: 'Any', escape: 'Optional[str]' = None, autoescape: 'bool' = False) -> 'ColumnOperators'
| Implement the ``iendswith`` operator, e.g. case insensitive
| version of :meth:`.ColumnOperators.endswith`.
|
| Produces a LIKE expression that tests against an insensitive match
| for the end of a string value:
|
| .. sourcecode:: sql
|
| lower(column) LIKE '%' || lower(<other>)
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.iendswith("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.iendswith.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.iendswith.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.iendswith.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.iendswith("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE '%' || lower(:param) ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.iendswith("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE '%' || lower(:param) ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.iendswith.autoescape`::
|
| somecolumn.endswith("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.endswith`
|
| ilike(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
| Implement the ``ilike`` operator, e.g. case insensitive LIKE.
|
| In a column context, produces an expression either of the form:
|
| .. sourcecode:: sql
|
| lower(a) LIKE lower(other)
|
| Or on backends that support the ILIKE operator:
|
| .. sourcecode:: sql
|
| a ILIKE other
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.ilike("%foobar%"))
|
| :param other: expression to be compared
| :param escape: optional escape character, renders the ``ESCAPE``
| keyword, e.g.::
|
| somecolumn.ilike("foo/%bar", escape="/")
|
| .. seealso::
|
| :meth:`.ColumnOperators.like`
|
| in_(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``in`` operator.
|
| In a column context, produces the clause ``column IN <other>``.
|
| The given parameter ``other`` may be:
|
| * A list of literal values,
| e.g.::
|
| stmt.where(column.in_([1, 2, 3]))
|
| In this calling form, the list of items is converted to a set of
| bound parameters the same length as the list given:
|
| .. sourcecode:: sql
|
| WHERE COL IN (?, ?, ?)
|
| * A list of tuples may be provided if the comparison is against a
| :func:`.tuple_` containing multiple expressions::
|
| from sqlalchemy import tuple_
|
| stmt.where(tuple_(col1, col2).in_([(1, 10), (2, 20), (3, 30)]))
|
| * An empty list,
| e.g.::
|
| stmt.where(column.in_([]))
|
| In this calling form, the expression renders an "empty set"
| expression. These expressions are tailored to individual backends
| and are generally trying to get an empty SELECT statement as a
| subquery. Such as on SQLite, the expression is:
|
| .. sourcecode:: sql
|
| WHERE col IN (SELECT 1 FROM (SELECT 1) WHERE 1!=1)
|
| .. versionchanged:: 1.4 empty IN expressions now use an
| execution-time generated SELECT subquery in all cases.
|
| * A bound parameter, e.g. :func:`.bindparam`, may be used if it
| includes the :paramref:`.bindparam.expanding` flag::
|
| stmt.where(column.in_(bindparam("value", expanding=True)))
|
| In this calling form, the expression renders a special non-SQL
| placeholder expression that looks like:
|
| .. sourcecode:: sql
|
| WHERE COL IN ([EXPANDING_value])
|
| This placeholder expression is intercepted at statement execution
| time to be converted into the variable number of bound parameter
| form illustrated earlier. If the statement were executed as::
|
| connection.execute(stmt, {"value": [1, 2, 3]})
|
| The database would be passed a bound parameter for each value:
|
| .. sourcecode:: sql
|
| WHERE COL IN (?, ?, ?)
|
| .. versionadded:: 1.2 added "expanding" bound parameters
|
| If an empty list is passed, a special "empty list" expression,
| which is specific to the database in use, is rendered. On
| SQLite this would be:
|
| .. sourcecode:: sql
|
| WHERE COL IN (SELECT 1 FROM (SELECT 1) WHERE 1!=1)
|
| .. versionadded:: 1.3 "expanding" bound parameters now support
| empty lists
|
| * a :func:`_expression.select` construct, which is usually a
| correlated scalar select::
|
| stmt.where(
| column.in_(select(othertable.c.y).where(table.c.x == othertable.c.x))
| )
|
| In this calling form, :meth:`.ColumnOperators.in_` renders as given:
|
| .. sourcecode:: sql
|
| WHERE COL IN (SELECT othertable.y
| FROM othertable WHERE othertable.x = table.x)
|
| :param other: a list of literals, a :func:`_expression.select`
| construct, or a :func:`.bindparam` construct that includes the
| :paramref:`.bindparam.expanding` flag set to True.
|
| is_(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``IS`` operator.
|
| Normally, ``IS`` is generated automatically when comparing to a
| value of ``None``, which resolves to ``NULL``. However, explicit
| usage of ``IS`` may be desirable if comparing to boolean values
| on certain platforms.
|
| .. seealso:: :meth:`.ColumnOperators.is_not`
|
| is_distinct_from(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``IS DISTINCT FROM`` operator.
|
| Renders "a IS DISTINCT FROM b" on most platforms;
| on some such as SQLite may render "a IS NOT b".
|
| is_not(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``IS NOT`` operator.
|
| Normally, ``IS NOT`` is generated automatically when comparing to a
| value of ``None``, which resolves to ``NULL``. However, explicit
| usage of ``IS NOT`` may be desirable if comparing to boolean values
| on certain platforms.
|
| .. versionchanged:: 1.4 The ``is_not()`` operator is renamed from
| ``isnot()`` in previous releases. The previous name remains
| available for backwards compatibility.
|
| .. seealso:: :meth:`.ColumnOperators.is_`
|
| is_not_distinct_from(self, other: 'Any') -> 'ColumnOperators'
| Implement the ``IS NOT DISTINCT FROM`` operator.
|
| Renders "a IS NOT DISTINCT FROM b" on most platforms;
| on some such as SQLite may render "a IS b".
|
| .. versionchanged:: 1.4 The ``is_not_distinct_from()`` operator is
| renamed from ``isnot_distinct_from()`` in previous releases.
| The previous name remains available for backwards compatibility.
|
| isnot = is_not(self, other: 'Any') -> 'ColumnOperators'
|
| isnot_distinct_from = is_not_distinct_from(self, other: 'Any') -> 'ColumnOperators'
|
| istartswith(self, other: 'Any', escape: 'Optional[str]' = None, autoescape: 'bool' = False) -> 'ColumnOperators'
| Implement the ``istartswith`` operator, e.g. case insensitive
| version of :meth:`.ColumnOperators.startswith`.
|
| Produces a LIKE expression that tests against an insensitive
| match for the start of a string value:
|
| .. sourcecode:: sql
|
| lower(column) LIKE lower(<other>) || '%'
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.istartswith("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.istartswith.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.istartswith.escape` parameter will
| establish a given character as an escape character which can be of
| use when the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.istartswith.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.istartswith("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE lower(:param) || '%' ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.istartswith("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| lower(somecolumn) LIKE lower(:param) || '%' ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.istartswith.autoescape`::
|
| somecolumn.istartswith("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.startswith`
|
| like(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
| Implement the ``like`` operator.
|
| In a column context, produces the expression:
|
| .. sourcecode:: sql
|
| a LIKE other
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.like("%foobar%"))
|
| :param other: expression to be compared
| :param escape: optional escape character, renders the ``ESCAPE``
| keyword, e.g.::
|
| somecolumn.like("foo/%bar", escape="/")
|
| .. seealso::
|
| :meth:`.ColumnOperators.ilike`
|
| match(self, other: 'Any', **kwargs: 'Any') -> 'ColumnOperators'
| Implements a database-specific 'match' operator.
|
| :meth:`_sql.ColumnOperators.match` attempts to resolve to
| a MATCH-like function or operator provided by the backend.
| Examples include:
|
| * PostgreSQL - renders ``x @@ plainto_tsquery(y)``
|
| .. versionchanged:: 2.0 ``plainto_tsquery()`` is used instead
| of ``to_tsquery()`` for PostgreSQL now; for compatibility with
| other forms, see :ref:`postgresql_match`.
|
|
| * MySQL - renders ``MATCH (x) AGAINST (y IN BOOLEAN MODE)``
|
| .. seealso::
|
| :class:`_mysql.match` - MySQL specific construct with
| additional features.
|
| * Oracle Database - renders ``CONTAINS(x, y)``
| * other backends may provide special implementations.
| * Backends without any special implementation will emit
| the operator as "MATCH". This is compatible with SQLite, for
| example.
|
| not_ilike(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
| implement the ``NOT ILIKE`` operator.
|
| This is equivalent to using negation with
| :meth:`.ColumnOperators.ilike`, i.e. ``~x.ilike(y)``.
|
| .. versionchanged:: 1.4 The ``not_ilike()`` operator is renamed from
| ``notilike()`` in previous releases. The previous name remains
| available for backwards compatibility.
|
| .. seealso::
|
| :meth:`.ColumnOperators.ilike`
|
| not_in(self, other: 'Any') -> 'ColumnOperators'
| implement the ``NOT IN`` operator.
|
| This is equivalent to using negation with
| :meth:`.ColumnOperators.in_`, i.e. ``~x.in_(y)``.
|
| In the case that ``other`` is an empty sequence, the compiler
| produces an "empty not in" expression. This defaults to the
| expression "1 = 1" to produce true in all cases. The
| :paramref:`_sa.create_engine.empty_in_strategy` may be used to
| alter this behavior.
|
| .. versionchanged:: 1.4 The ``not_in()`` operator is renamed from
| ``notin_()`` in previous releases. The previous name remains
| available for backwards compatibility.
|
| .. versionchanged:: 1.2 The :meth:`.ColumnOperators.in_` and
| :meth:`.ColumnOperators.not_in` operators
| now produce a "static" expression for an empty IN sequence
| by default.
|
| .. seealso::
|
| :meth:`.ColumnOperators.in_`
|
| not_like(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
| implement the ``NOT LIKE`` operator.
|
| This is equivalent to using negation with
| :meth:`.ColumnOperators.like`, i.e. ``~x.like(y)``.
|
| .. versionchanged:: 1.4 The ``not_like()`` operator is renamed from
| ``notlike()`` in previous releases. The previous name remains
| available for backwards compatibility.
|
| .. seealso::
|
| :meth:`.ColumnOperators.like`
|
| notilike = not_ilike(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
|
| notin_ = not_in(self, other: 'Any') -> 'ColumnOperators'
|
| notlike = not_like(self, other: 'Any', escape: 'Optional[str]' = None) -> 'ColumnOperators'
|
| nulls_first(self) -> 'ColumnOperators'
| Produce a :func:`_expression.nulls_first` clause against the
| parent object.
|
| .. versionchanged:: 1.4 The ``nulls_first()`` operator is
| renamed from ``nullsfirst()`` in previous releases.
| The previous name remains available for backwards compatibility.
|
| nulls_last(self) -> 'ColumnOperators'
| Produce a :func:`_expression.nulls_last` clause against the
| parent object.
|
| .. versionchanged:: 1.4 The ``nulls_last()`` operator is
| renamed from ``nullslast()`` in previous releases.
| The previous name remains available for backwards compatibility.
|
| nullsfirst = nulls_first(self) -> 'ColumnOperators'
|
| nullslast = nulls_last(self) -> 'ColumnOperators'
|
| regexp_match(self, pattern: 'Any', flags: 'Optional[str]' = None) -> 'ColumnOperators'
| Implements a database-specific 'regexp match' operator.
|
| E.g.::
|
| stmt = select(table.c.some_column).where(
| table.c.some_column.regexp_match("^(b|c)")
| )
|
| :meth:`_sql.ColumnOperators.regexp_match` attempts to resolve to
| a REGEXP-like function or operator provided by the backend, however
| the specific regular expression syntax and flags available are
| **not backend agnostic**.
|
| Examples include:
|
| * PostgreSQL - renders ``x ~ y`` or ``x !~ y`` when negated.
| * Oracle Database - renders ``REGEXP_LIKE(x, y)``
| * SQLite - uses SQLite's ``REGEXP`` placeholder operator and calls into
| the Python ``re.match()`` builtin.
| * other backends may provide special implementations.
| * Backends without any special implementation will emit
| the operator as "REGEXP" or "NOT REGEXP". This is compatible with
| SQLite and MySQL, for example.
|
| Regular expression support is currently implemented for Oracle
| Database, PostgreSQL, MySQL and MariaDB. Partial support is available
| for SQLite. Support among third-party dialects may vary.
|
| :param pattern: The regular expression pattern string or column
| clause.
| :param flags: Any regular expression string flags to apply, passed as
| plain Python string only. These flags are backend specific.
| Some backends, like PostgreSQL and MariaDB, may alternatively
| specify the flags as part of the pattern.
| When using the ignore case flag 'i' in PostgreSQL, the ignore case
| regexp match operator ``~*`` or ``!~*`` will be used.
|
| .. versionadded:: 1.4
|
| .. versionchanged:: 1.4.48, 2.0.18 Note that due to an implementation
| error, the "flags" parameter previously accepted SQL expression
| objects such as column expressions in addition to plain Python
| strings. This implementation did not work correctly with caching
| and was removed; strings only should be passed for the "flags"
| parameter, as these flags are rendered as literal inline values
| within SQL expressions.
|
| .. seealso::
|
| :meth:`_sql.ColumnOperators.regexp_replace`
|
| regexp_replace(self, pattern: 'Any', replacement: 'Any', flags: 'Optional[str]' = None) -> 'ColumnOperators'
| Implements a database-specific 'regexp replace' operator.
|
| E.g.::
|
| stmt = select(
| table.c.some_column.regexp_replace("b(..)", "XY", flags="g")
| )
|
| :meth:`_sql.ColumnOperators.regexp_replace` attempts to resolve to
| a REGEXP_REPLACE-like function provided by the backend, that
| usually emit the function ``REGEXP_REPLACE()``. However,
| the specific regular expression syntax and flags available are
| **not backend agnostic**.
|
| Regular expression replacement support is currently implemented for
| Oracle Database, PostgreSQL, MySQL 8 or greater and MariaDB. Support
| among third-party dialects may vary.
|
| :param pattern: The regular expression pattern string or column
| clause.
| :param pattern: The replacement string or column clause.
| :param flags: Any regular expression string flags to apply, passed as
| plain Python string only. These flags are backend specific.
| Some backends, like PostgreSQL and MariaDB, may alternatively
| specify the flags as part of the pattern.
|
| .. versionadded:: 1.4
|
| .. versionchanged:: 1.4.48, 2.0.18 Note that due to an implementation
| error, the "flags" parameter previously accepted SQL expression
| objects such as column expressions in addition to plain Python
| strings. This implementation did not work correctly with caching
| and was removed; strings only should be passed for the "flags"
| parameter, as these flags are rendered as literal inline values
| within SQL expressions.
|
|
| .. seealso::
|
| :meth:`_sql.ColumnOperators.regexp_match`
|
| startswith(self, other: 'Any', escape: 'Optional[str]' = None, autoescape: 'bool' = False) -> 'ColumnOperators'
| Implement the ``startswith`` operator.
|
| Produces a LIKE expression that tests against a match for the start
| of a string value:
|
| .. sourcecode:: sql
|
| column LIKE <other> || '%'
|
| E.g.::
|
| stmt = select(sometable).where(sometable.c.column.startswith("foobar"))
|
| Since the operator uses ``LIKE``, wildcard characters
| ``"%"`` and ``"_"`` that are present inside the <other> expression
| will behave like wildcards as well. For literal string
| values, the :paramref:`.ColumnOperators.startswith.autoescape` flag
| may be set to ``True`` to apply escaping to occurrences of these
| characters within the string value so that they match as themselves
| and not as wildcard characters. Alternatively, the
| :paramref:`.ColumnOperators.startswith.escape` parameter will establish
| a given character as an escape character which can be of use when
| the target expression is not a literal string.
|
| :param other: expression to be compared. This is usually a plain
| string value, but can also be an arbitrary SQL expression. LIKE
| wildcard characters ``%`` and ``_`` are not escaped by default unless
| the :paramref:`.ColumnOperators.startswith.autoescape` flag is
| set to True.
|
| :param autoescape: boolean; when True, establishes an escape character
| within the LIKE expression, then applies it to all occurrences of
| ``"%"``, ``"_"`` and the escape character itself within the
| comparison value, which is assumed to be a literal string and not a
| SQL expression.
|
| An expression such as::
|
| somecolumn.startswith("foo%bar", autoescape=True)
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE :param || '%' ESCAPE '/'
|
| With the value of ``:param`` as ``"foo/%bar"``.
|
| :param escape: a character which when given will render with the
| ``ESCAPE`` keyword to establish that character as the escape
| character. This character can then be placed preceding occurrences
| of ``%`` and ``_`` to allow them to act as themselves and not
| wildcard characters.
|
| An expression such as::
|
| somecolumn.startswith("foo/%bar", escape="^")
|
| Will render as:
|
| .. sourcecode:: sql
|
| somecolumn LIKE :param || '%' ESCAPE '^'
|
| The parameter may also be combined with
| :paramref:`.ColumnOperators.startswith.autoescape`::
|
| somecolumn.startswith("foo%bar^bat", escape="^", autoescape=True)
|
| Where above, the given literal parameter will be converted to
| ``"foo^%bar^^bat"`` before being passed to the database.
|
| .. seealso::
|
| :meth:`.ColumnOperators.endswith`
|
| :meth:`.ColumnOperators.contains`
|
| :meth:`.ColumnOperators.like`
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.operators.ColumnOperators:
|
| timetuple = None
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.operators.Operators:
|
| __and__(self, other: 'Any') -> 'Operators'
| Implement the ``&`` operator.
|
| When used with SQL expressions, results in an
| AND operation, equivalent to
| :func:`_expression.and_`, that is::
|
| a & b
|
| is equivalent to::
|
| from sqlalchemy import and_
|
| and_(a, b)
|
| Care should be taken when using ``&`` regarding
| operator precedence; the ``&`` operator has the highest precedence.
| The operands should be enclosed in parenthesis if they contain
| further sub expressions::
|
| (a == 2) & (b == 4)
|
| __invert__(self) -> 'Operators'
| Implement the ``~`` operator.
|
| When used with SQL expressions, results in a
| NOT operation, equivalent to
| :func:`_expression.not_`, that is::
|
| ~a
|
| is equivalent to::
|
| from sqlalchemy import not_
|
| not_(a)
|
| __or__(self, other: 'Any') -> 'Operators'
| Implement the ``|`` operator.
|
| When used with SQL expressions, results in an
| OR operation, equivalent to
| :func:`_expression.or_`, that is::
|
| a | b
|
| is equivalent to::
|
| from sqlalchemy import or_
|
| or_(a, b)
|
| Care should be taken when using ``|`` regarding
| operator precedence; the ``|`` operator has the highest precedence.
| The operands should be enclosed in parenthesis if they contain
| further sub expressions::
|
| (a == 2) | (b == 4)
|
| __sa_operate__ = operate(self, op: 'OperatorType', *other: 'Any', **kwargs: 'Any') -> 'Operators'
| Operate on an argument.
|
| This is the lowest level of operation, raises
| :class:`NotImplementedError` by default.
|
| Overriding this on a subclass can allow common
| behavior to be applied to all operations.
| For example, overriding :class:`.ColumnOperators`
| to apply ``func.lower()`` to the left and right
| side::
|
| class MyComparator(ColumnOperators):
| def operate(self, op, other, **kwargs):
| return op(func.lower(self), func.lower(other), **kwargs)
|
| :param op: Operator callable.
| :param \*other: the 'other' side of the operation. Will
| be a single scalar for most operations.
| :param \**kwargs: modifiers. These may be passed by special
| operators such as :meth:`ColumnOperators.contains`.
|
| bool_op(self, opstring: 'str', precedence: 'int' = 0, python_impl: 'Optional[Callable[..., Any]]' = None) -> 'Callable[[Any], Operators]'
| Return a custom boolean operator.
|
| This method is shorthand for calling
| :meth:`.Operators.op` and passing the
| :paramref:`.Operators.op.is_comparison`
| flag with True. A key advantage to using :meth:`.Operators.bool_op`
| is that when using column constructs, the "boolean" nature of the
| returned expression will be present for :pep:`484` purposes.
|
| .. seealso::
|
| :meth:`.Operators.op`
|
| op(self, opstring: 'str', precedence: 'int' = 0, is_comparison: 'bool' = False, return_type: 'Optional[Union[Type[TypeEngine[Any]], TypeEngine[Any]]]' = None, python_impl: 'Optional[Callable[..., Any]]' = None) -> 'Callable[[Any], Operators]'
| Produce a generic operator function.
|
| e.g.::
|
| somecolumn.op("*")(5)
|
| produces::
|
| somecolumn * 5
|
| This function can also be used to make bitwise operators explicit. For
| example::
|
| somecolumn.op("&")(0xFF)
|
| is a bitwise AND of the value in ``somecolumn``.
|
| :param opstring: a string which will be output as the infix operator
| between this element and the expression passed to the
| generated function.
|
| :param precedence: precedence which the database is expected to apply
| to the operator in SQL expressions. This integer value acts as a hint
| for the SQL compiler to know when explicit parenthesis should be
| rendered around a particular operation. A lower number will cause the
| expression to be parenthesized when applied against another operator
| with higher precedence. The default value of ``0`` is lower than all
| operators except for the comma (``,``) and ``AS`` operators. A value
| of 100 will be higher or equal to all operators, and -100 will be
| lower than or equal to all operators.
|
| .. seealso::
|
| :ref:`faq_sql_expression_op_parenthesis` - detailed description
| of how the SQLAlchemy SQL compiler renders parenthesis
|
| :param is_comparison: legacy; if True, the operator will be considered
| as a "comparison" operator, that is which evaluates to a boolean
| true/false value, like ``==``, ``>``, etc. This flag is provided
| so that ORM relationships can establish that the operator is a
| comparison operator when used in a custom join condition.
|
| Using the ``is_comparison`` parameter is superseded by using the
| :meth:`.Operators.bool_op` method instead; this more succinct
| operator sets this parameter automatically, but also provides
| correct :pep:`484` typing support as the returned object will
| express a "boolean" datatype, i.e. ``BinaryExpression[bool]``.
|
| :param return_type: a :class:`.TypeEngine` class or object that will
| force the return type of an expression produced by this operator
| to be of that type. By default, operators that specify
| :paramref:`.Operators.op.is_comparison` will resolve to
| :class:`.Boolean`, and those that do not will be of the same
| type as the left-hand operand.
|
| :param python_impl: an optional Python function that can evaluate
| two Python values in the same way as this operator works when
| run on the database server. Useful for in-Python SQL expression
| evaluation functions, such as for ORM hybrid attributes, and the
| ORM "evaluator" used to match objects in a session after a multi-row
| update or delete.
|
| e.g.::
|
| >>> expr = column("x").op("+", python_impl=lambda a, b: a + b)("y")
|
| The operator for the above expression will also work for non-SQL
| left and right objects::
|
| >>> expr.operator(5, 10)
| 15
|
| .. versionadded:: 2.0
|
|
| .. seealso::
|
| :meth:`.Operators.bool_op`
|
| :ref:`types_operators`
|
| :ref:`relationship_custom_operator`
|
| ----------------------------------------------------------------------
| Methods inherited from ClauseElement:
|
| __bool__(self)
|
| __getstate__(self)
| Helper for pickle.
|
| __repr__(self)
| Return repr(self).
|
| compare(self, other: 'ClauseElement', **kw: 'Any') -> 'bool'
| Compare this :class:`_expression.ClauseElement` to
| the given :class:`_expression.ClauseElement`.
|
| Subclasses should override the default behavior, which is a
| straight identity comparison.
|
| \**kw are arguments consumed by subclass ``compare()`` methods and
| may be used to modify the criteria for comparison
| (see :class:`_expression.ColumnElement`).
|
| description(...)
|
| entity_namespace(...)
|
| params(self, _ClauseElement__optionaldict: 'Optional[Mapping[str, Any]]' = None, **kwargs: 'Any') -> 'Self'
| Return a copy with :func:`_expression.bindparam` elements
| replaced.
|
| Returns a copy of this ClauseElement with
| :func:`_expression.bindparam`
| elements replaced with values taken from the given dictionary::
|
| >>> clause = column("x") + bindparam("foo")
| >>> print(clause.compile().params)
| {'foo':None}
| >>> print(clause.params({"foo": 7}).compile().params)
| {'foo':7}
|
| unique_params(self, _ClauseElement__optionaldict: 'Optional[Dict[str, Any]]' = None, **kwargs: 'Any') -> 'Self'
| Return a copy with :func:`_expression.bindparam` elements
| replaced.
|
| Same functionality as :meth:`_expression.ClauseElement.params`,
| except adds `unique=True`
| to affected bind parameters so that multiple statements can be
| used.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from ClauseElement:
|
| is_clause_element = True
|
| is_dml = False
|
| is_selectable = False
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.sql.cache_key.HasCacheKey:
|
| inherit_cache = None
|
| ----------------------------------------------------------------------
| Class methods inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_instancemethod(fn: '_F') -> '_F'
| Decorate a method memoize its return value.
|
| :meta private:
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from sqlalchemy.util.langhelpers.HasMemoized:
|
| memoized_attribute = <class 'sqlalchemy.util.langhelpers.HasMemoized.m...
| A read-only @property that is only evaluated once.
|
| :meta private:
|
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.sql.visitors.HasTraverseInternals:
|
| get_children(self, *, omit_attrs: 'Tuple[str, ...]' = (), **kw: 'Any') -> 'Iterable[HasTraverseInternals]'
| Return immediate child :class:`.visitors.HasTraverseInternals`
| elements of this :class:`.visitors.HasTraverseInternals`.
|
| This is used for visit traversal.
|
| \**kw may contain flags that change the collection that is
| returned, for example to return a subset of items in order to
| cut down on larger traversals, or to return child items from a
| different context (such as schema-level collections instead of
| clause-level).
|
| ----------------------------------------------------------------------
| Methods inherited from CompilerElement:
|
| __str__(self) -> 'str'
| Return str(self).
|
| compile(self, bind: 'Optional[_HasDialect]' = None, dialect: 'Optional[Dialect]' = None, **kw: 'Any') -> 'Compiled'
| Compile this SQL expression.
|
| The return value is a :class:`~.Compiled` object.
| Calling ``str()`` or ``unicode()`` on the returned value will yield a
| string representation of the result. The
| :class:`~.Compiled` object also can return a
| dictionary of bind parameter names and values
| using the ``params`` accessor.
|
| :param bind: An :class:`.Connection` or :class:`.Engine` which
| can provide a :class:`.Dialect` in order to generate a
| :class:`.Compiled` object. If the ``bind`` and
| ``dialect`` parameters are both omitted, a default SQL compiler
| is used.
|
| :param column_keys: Used for INSERT and UPDATE statements, a list of
| column names which should be present in the VALUES clause of the
| compiled statement. If ``None``, all columns from the target table
| object are rendered.
|
| :param dialect: A :class:`.Dialect` instance which can generate
| a :class:`.Compiled` object. This argument takes precedence over
| the ``bind`` argument.
|
| :param compile_kwargs: optional dictionary of additional parameters
| that will be passed through to the compiler within all "visit"
| methods. This allows any custom flag to be passed through to
| a custom compilation construct, for example. It is also used
| for the case of passing the ``literal_binds`` flag through::
|
| from sqlalchemy.sql import table, column, select
|
| t = table("t", column("x"))
|
| s = select(t).where(t.c.x == 5)
|
| print(s.compile(compile_kwargs={"literal_binds": True}))
|
| .. seealso::
|
| :ref:`faq_sql_expression_string`
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from CompilerElement:
|
| stringify_dialect = 'default'
|
| supports_execution = False
sqlalchemy.alias
Python Library Documentation: function alias in module sqlalchemy.sql._selectable_constructors
alias(selectable: 'FromClause', name: 'Optional[str]' = None, flat: 'bool' = False) -> 'NamedFromClause'
Return a named alias of the given :class:`.FromClause`.
For :class:`.Table` and :class:`.Join` objects, the return type is the
:class:`_expression.Alias` object. Other kinds of :class:`.NamedFromClause`
objects may be returned for other kinds of :class:`.FromClause` objects.
The named alias represents any :class:`_expression.FromClause` with an
alternate name assigned within SQL, typically using the ``AS`` clause when
generated, e.g. ``SELECT * FROM table AS aliasname``.
Equivalent functionality is available via the
:meth:`_expression.FromClause.alias`
method available on all :class:`_expression.FromClause` objects.
:param selectable: any :class:`_expression.FromClause` subclass,
such as a table, select statement, etc.
:param name: string name to be assigned as the alias.
If ``None``, a name will be deterministically generated at compile
time. Deterministic means the name is guaranteed to be unique against
other constructs used in the same statement, and will also be the same
name for each successive compilation of the same statement object.
:param flat: Will be passed through to if the given selectable
is an instance of :class:`_expression.Join` - see
:meth:`_expression.Join.alias` for details.
sqlalchemy.all_
Python Library Documentation: function all_ in module sqlalchemy.sql._elements_constructors
all_(expr: '_ColumnExpressionArgument[_T]') -> 'CollectionAggregate[bool]'
Produce an ALL expression.
For dialects such as that of PostgreSQL, this operator applies
to usage of the :class:`_types.ARRAY` datatype, for that of
MySQL, it may apply to a subquery. e.g.::
# renders on PostgreSQL:
# '5 = ALL (somearray)'
expr = 5 == all_(mytable.c.somearray)
# renders on MySQL:
# '5 = ALL (SELECT value FROM table)'
expr = 5 == all_(select(table.c.value))
Comparison to NULL may work using ``None``::
None == all_(mytable.c.somearray)
The any_() / all_() operators also feature a special "operand flipping"
behavior such that if any_() / all_() are used on the left side of a
comparison using a standalone operator such as ``==``, ``!=``, etc.
(not including operator methods such as
:meth:`_sql.ColumnOperators.is_`) the rendered expression is flipped::
# would render '5 = ALL (column)`
all_(mytable.c.column) == 5
Or with ``None``, which note will not perform
the usual step of rendering "IS" as is normally the case for NULL::
# would render 'NULL = ALL(somearray)'
all_(mytable.c.somearray) == None
.. versionchanged:: 1.4.26 repaired the use of any_() / all_()
comparing to NULL on the right side to be flipped to the left.
The column-level :meth:`_sql.ColumnElement.all_` method (not to be
confused with :class:`_types.ARRAY` level
:meth:`_types.ARRAY.Comparator.all`) is shorthand for
``all_(col)``::
5 == mytable.c.somearray.all_()
.. seealso::
:meth:`_sql.ColumnOperators.all_`
:func:`_expression.any_`
sqlalchemy.and_
Python Library Documentation: function and_ in module sqlalchemy.sql._elements_constructors
and_(*clauses)
Produce a conjunction of expressions joined by ``AND``.
E.g.::
from sqlalchemy import and_
stmt = select(users_table).where(
and_(users_table.c.name == "wendy", users_table.c.enrolled == True)
)
The :func:`.and_` conjunction is also available using the
Python ``&`` operator (though note that compound expressions
need to be parenthesized in order to function with Python
operator precedence behavior)::
stmt = select(users_table).where(
(users_table.c.name == "wendy") & (users_table.c.enrolled == True)
)
The :func:`.and_` operation is also implicit in some cases;
the :meth:`_expression.Select.where`
method for example can be invoked multiple
times against a statement, which will have the effect of each
clause being combined using :func:`.and_`::
stmt = (
select(users_table)
.where(users_table.c.name == "wendy")
.where(users_table.c.enrolled == True)
)
The :func:`.and_` construct must be given at least one positional
argument in order to be valid; a :func:`.and_` construct with no
arguments is ambiguous. To produce an "empty" or dynamically
generated :func:`.and_` expression, from a given list of expressions,
a "default" element of :func:`_sql.true` (or just ``True``) should be
specified::
from sqlalchemy import true
criteria = and_(true(), *expressions)
The above expression will compile to SQL as the expression ``true``
or ``1 = 1``, depending on backend, if no other expressions are
present. If expressions are present, then the :func:`_sql.true` value
is ignored as it does not affect the outcome of an AND expression that
has other elements.
.. deprecated:: 1.4 The :func:`.and_` element now requires that at
least one argument is passed; creating the :func:`.and_` construct
with no arguments is deprecated, and will emit a deprecation warning
while continuing to produce a blank SQL string.
.. seealso::
:func:`.or_`
sqlalchemy.annotations
Python Library Documentation: _Feature in module __future__ object class _Feature(builtins.object) | _Feature(optionalRelease, mandatoryRelease, compiler_flag) | | Methods defined here: | | __init__(self, optionalRelease, mandatoryRelease, compiler_flag) | Initialize self. See help(type(self)) for accurate signature. | | __repr__(self) | Return repr(self). | | getMandatoryRelease(self) | Return release in which this feature will become mandatory. | | This is a 5-tuple, of the same form as sys.version_info, or, if | the feature was dropped, or the release date is undetermined, is None. | | getOptionalRelease(self) | Return first release in which this feature was recognized. | | This is a 5-tuple, of the same form as sys.version_info. | | ---------------------------------------------------------------------- | Data descriptors defined here: | | __dict__ | dictionary for instance variables | | __weakref__ | list of weak references to the object
sqlalchemy.any_
Python Library Documentation: function any_ in module sqlalchemy.sql._elements_constructors
any_(expr: '_ColumnExpressionArgument[_T]') -> 'CollectionAggregate[bool]'
Produce an ANY expression.
For dialects such as that of PostgreSQL, this operator applies
to usage of the :class:`_types.ARRAY` datatype, for that of
MySQL, it may apply to a subquery. e.g.::
# renders on PostgreSQL:
# '5 = ANY (somearray)'
expr = 5 == any_(mytable.c.somearray)
# renders on MySQL:
# '5 = ANY (SELECT value FROM table)'
expr = 5 == any_(select(table.c.value))
Comparison to NULL may work using ``None`` or :func:`_sql.null`::
None == any_(mytable.c.somearray)
The any_() / all_() operators also feature a special "operand flipping"
behavior such that if any_() / all_() are used on the left side of a
comparison using a standalone operator such as ``==``, ``!=``, etc.
(not including operator methods such as
:meth:`_sql.ColumnOperators.is_`) the rendered expression is flipped::
# would render '5 = ANY (column)`
any_(mytable.c.column) == 5
Or with ``None``, which note will not perform
the usual step of rendering "IS" as is normally the case for NULL::
# would render 'NULL = ANY(somearray)'
any_(mytable.c.somearray) == None
.. versionchanged:: 1.4.26 repaired the use of any_() / all_()
comparing to NULL on the right side to be flipped to the left.
The column-level :meth:`_sql.ColumnElement.any_` method (not to be
confused with :class:`_types.ARRAY` level
:meth:`_types.ARRAY.Comparator.any`) is shorthand for
``any_(col)``::
5 = mytable.c.somearray.any_()
.. seealso::
:meth:`_sql.ColumnOperators.any_`
:func:`_expression.all_`
sqlalchemy.asc
Python Library Documentation: function asc in module sqlalchemy.sql._elements_constructors
asc(column: '_ColumnExpressionOrStrLabelArgument[_T]') -> 'UnaryExpression[_T]'
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:
.. sourcecode:: sql
SELECT id, name FROM user ORDER BY name ASC
The :func:`.asc` function is a standalone version of the
:meth:`_expression.ColumnElement.asc`
method available on all SQL expressions,
e.g.::
stmt = select(users_table).order_by(users_table.c.name.asc())
:param column: A :class:`_expression.ColumnElement` (e.g.
scalar SQL expression)
with which to apply the :func:`.asc` operation.
.. seealso::
:func:`.desc`
:func:`.nulls_first`
:func:`.nulls_last`
:meth:`_expression.Select.order_by`
sqlalchemy.between
Python Library Documentation: function between in module sqlalchemy.sql._elements_constructors
between(expr: '_ColumnExpressionOrLiteralArgument[_T]', lower_bound: 'Any', upper_bound: 'Any', symmetric: 'bool' = False) -> 'BinaryExpression[bool]'
Produce a ``BETWEEN`` predicate clause.
E.g.::
from sqlalchemy import between
stmt = select(users_table).where(between(users_table.c.id, 5, 7))
Would produce SQL resembling:
.. sourcecode:: sql
SELECT id, name FROM user WHERE id BETWEEN :id_1 AND :id_2
The :func:`.between` function is a standalone version of the
:meth:`_expression.ColumnElement.between` method available on all
SQL expressions, as in::
stmt = select(users_table).where(users_table.c.id.between(5, 7))
All arguments passed to :func:`.between`, including the left side
column expression, are coerced from Python scalar values if a
the value is not a :class:`_expression.ColumnElement` subclass.
For example,
three fixed values can be compared as in::
print(between(5, 3, 7))
Which would produce::
:param_1 BETWEEN :param_2 AND :param_3
:param expr: a column expression, typically a
:class:`_expression.ColumnElement`
instance or alternatively a Python scalar expression to be coerced
into a column expression, serving as the left side of the ``BETWEEN``
expression.
:param lower_bound: a column or Python scalar expression serving as the
lower bound of the right side of the ``BETWEEN`` expression.
:param upper_bound: a column or Python scalar expression serving as the
upper bound of the right side of the ``BETWEEN`` expression.
:param symmetric: if True, will render " BETWEEN SYMMETRIC ". Note
that not all databases support this syntax.
.. seealso::
:meth:`_expression.ColumnElement.between`
sqlalchemy.bindparam
Python Library Documentation: function bindparam in module sqlalchemy.sql._elements_constructors
bindparam(key: 'Optional[str]', value: 'Any' = _NoArg.NO_ARG, type_: 'Optional[_TypeEngineArgument[_T]]' = None, unique: 'bool' = False, required: 'Union[bool, Literal[_NoArg.NO_ARG]]' = _NoArg.NO_ARG, quote: 'Optional[bool]' = None, callable_: 'Optional[Callable[[], Any]]' = None, expanding: 'bool' = False, isoutparam: 'bool' = False, literal_execute: 'bool' = False) -> 'BindParameter[_T]'
Produce a "bound expression".
The return value is an instance of :class:`.BindParameter`; this
is a :class:`_expression.ColumnElement`
subclass which represents a so-called
"placeholder" value in a SQL expression, the value of which is
supplied at the point at which the statement in executed against a
database connection.
In SQLAlchemy, the :func:`.bindparam` construct has
the ability to carry along the actual value that will be ultimately
used at expression time. In this way, it serves not just as
a "placeholder" for eventual population, but also as a means of
representing so-called "unsafe" values which should not be rendered
directly in a SQL statement, but rather should be passed along
to the :term:`DBAPI` as values which need to be correctly escaped
and potentially handled for type-safety.
When using :func:`.bindparam` explicitly, the use case is typically
one of traditional deferment of parameters; the :func:`.bindparam`
construct accepts a name which can then be referred to at execution
time::
from sqlalchemy import bindparam
stmt = select(users_table).where(
users_table.c.name == bindparam("username")
)
The above statement, when rendered, will produce SQL similar to:
.. sourcecode:: sql
SELECT id, name FROM user WHERE name = :username
In order to populate the value of ``:username`` above, the value
would typically be applied at execution time to a method
like :meth:`_engine.Connection.execute`::
result = connection.execute(stmt, {"username": "wendy"})
Explicit use of :func:`.bindparam` is also common when producing
UPDATE or DELETE statements that are to be invoked multiple times,
where the WHERE criterion of the statement is to change on each
invocation, such as::
stmt = (
users_table.update()
.where(user_table.c.name == bindparam("username"))
.values(fullname=bindparam("fullname"))
)
connection.execute(
stmt,
[
{"username": "wendy", "fullname": "Wendy Smith"},
{"username": "jack", "fullname": "Jack Jones"},
],
)
SQLAlchemy's Core expression system makes wide use of
:func:`.bindparam` in an implicit sense. It is typical that Python
literal values passed to virtually all SQL expression functions are
coerced into fixed :func:`.bindparam` constructs. For example, given
a comparison operation such as::
expr = users_table.c.name == "Wendy"
The above expression will produce a :class:`.BinaryExpression`
construct, where the left side is the :class:`_schema.Column` object
representing the ``name`` column, and the right side is a
:class:`.BindParameter` representing the literal value::
print(repr(expr.right))
BindParameter("%(4327771088 name)s", "Wendy", type_=String())
The expression above will render SQL such as:
.. sourcecode:: sql
user.name = :name_1
Where the ``:name_1`` parameter name is an anonymous name. The
actual string ``Wendy`` is not in the rendered string, but is carried
along where it is later used within statement execution. If we
invoke a statement like the following::
stmt = select(users_table).where(users_table.c.name == "Wendy")
result = connection.execute(stmt)
We would see SQL logging output as:
.. sourcecode:: sql
SELECT "user".id, "user".name
FROM "user"
WHERE "user".name = %(name_1)s
{'name_1': 'Wendy'}
Above, we see that ``Wendy`` is passed as a parameter to the database,
while the placeholder ``:name_1`` is rendered in the appropriate form
for the target database, in this case the PostgreSQL database.
Similarly, :func:`.bindparam` is invoked automatically when working
with :term:`CRUD` statements as far as the "VALUES" portion is
concerned. The :func:`_expression.insert` construct produces an
``INSERT`` expression which will, at statement execution time, generate
bound placeholders based on the arguments passed, as in::
stmt = users_table.insert()
result = connection.execute(stmt, {"name": "Wendy"})
The above will produce SQL output as:
.. sourcecode:: sql
INSERT INTO "user" (name) VALUES (%(name)s)
{'name': 'Wendy'}
The :class:`_expression.Insert` construct, at
compilation/execution time, rendered a single :func:`.bindparam`
mirroring the column name ``name`` as a result of the single ``name``
parameter we passed to the :meth:`_engine.Connection.execute` method.
:param key:
the key (e.g. the name) for this bind param.
Will be used in the generated
SQL statement for dialects that use named parameters. This
value may be modified when part of a compilation operation,
if other :class:`BindParameter` objects exist with the same
key, or if its length is too long and truncation is
required.
If omitted, an "anonymous" name is generated for the bound parameter;
when given a value to bind, the end result is equivalent to calling upon
the :func:`.literal` function with a value to bind, particularly
if the :paramref:`.bindparam.unique` parameter is also provided.
:param value:
Initial value for this bind param. Will be used at statement
execution time as the value for this parameter passed to the
DBAPI, if no other value is indicated to the statement execution
method for this particular parameter name. Defaults to ``None``.
:param callable\_:
A callable function that takes the place of "value". The function
will be called at statement execution time to determine the
ultimate value. Used for scenarios where the actual bind
value cannot be determined at the point at which the clause
construct is created, but embedded bind values are still desirable.
:param type\_:
A :class:`.TypeEngine` class or instance representing an optional
datatype for this :func:`.bindparam`. If not passed, a type
may be determined automatically for the bind, based on the given
value; for example, trivial Python types such as ``str``,
``int``, ``bool``
may result in the :class:`.String`, :class:`.Integer` or
:class:`.Boolean` types being automatically selected.
The type of a :func:`.bindparam` is significant especially in that
the type will apply pre-processing to the value before it is
passed to the database. For example, a :func:`.bindparam` which
refers to a datetime value, and is specified as holding the
:class:`.DateTime` type, may apply conversion needed to the
value (such as stringification on SQLite) before passing the value
to the database.
:param unique:
if True, the key name of this :class:`.BindParameter` will be
modified if another :class:`.BindParameter` of the same name
already has been located within the containing
expression. This flag is used generally by the internals
when producing so-called "anonymous" bound expressions, it
isn't generally applicable to explicitly-named :func:`.bindparam`
constructs.
:param required:
If ``True``, a value is required at execution time. If not passed,
it defaults to ``True`` if neither :paramref:`.bindparam.value`
or :paramref:`.bindparam.callable` were passed. If either of these
parameters are present, then :paramref:`.bindparam.required`
defaults to ``False``.
:param quote:
True if this parameter name requires quoting and is not
currently known as a SQLAlchemy reserved word; this currently
only applies to the Oracle Database backends, where bound names must
sometimes be quoted.
:param isoutparam:
if True, the parameter should be treated like a stored procedure
"OUT" parameter. This applies to backends such as Oracle Database which
support OUT parameters.
:param expanding:
if True, this parameter will be treated as an "expanding" parameter
at execution time; the parameter value is expected to be a sequence,
rather than a scalar value, and the string SQL statement will
be transformed on a per-execution basis to accommodate the sequence
with a variable number of parameter slots passed to the DBAPI.
This is to allow statement caching to be used in conjunction with
an IN clause.
.. seealso::
:meth:`.ColumnOperators.in_`
:ref:`baked_in` - with baked queries
.. note:: The "expanding" feature does not support "executemany"-
style parameter sets.
.. versionadded:: 1.2
.. versionchanged:: 1.3 the "expanding" bound parameter feature now
supports empty lists.
:param literal_execute:
if True, the bound parameter will be rendered in the compile phase
with a special "POSTCOMPILE" token, and the SQLAlchemy compiler will
render the final value of the parameter into the SQL statement at
statement execution time, omitting the value from the parameter
dictionary / list passed to DBAPI ``cursor.execute()``. This
produces a similar effect as that of using the ``literal_binds``,
compilation flag, however takes place as the statement is sent to
the DBAPI ``cursor.execute()`` method, rather than when the statement
is compiled. The primary use of this
capability is for rendering LIMIT / OFFSET clauses for database
drivers that can't accommodate for bound parameters in these
contexts, while allowing SQL constructs to be cacheable at the
compilation level.
.. versionadded:: 1.4 Added "post compile" bound parameters
.. seealso::
:ref:`change_4808`.
.. seealso::
:ref:`tutorial_sending_parameters` - in the
:ref:`unified_tutorial`
sqlalchemy.bitwise_not
Python Library Documentation: function bitwise_not in module sqlalchemy.sql._elements_constructors
bitwise_not(expr: '_ColumnExpressionArgument[_T]') -> 'UnaryExpression[_T]'
Produce a unary bitwise NOT clause, typically via the ``~`` operator.
Not to be confused with boolean negation :func:`_sql.not_`.
.. versionadded:: 2.0.2
.. seealso::
:ref:`operators_bitwise`
sqlalchemy.case
Python Library Documentation: function case in module sqlalchemy.sql._elements_constructors
case(*whens: 'Union[typing_Tuple[_ColumnExpressionArgument[bool], Any], Mapping[Any, Any]]', value: 'Optional[Any]' = None, else_: 'Optional[Any]' = None) -> 'Case[Any]'
Produce a ``CASE`` expression.
The ``CASE`` construct in SQL is a conditional object that
acts somewhat analogously to an "if/then" construct in other
languages. It returns an instance of :class:`.Case`.
:func:`.case` in its usual form is passed a series of "when"
constructs, that is, a list of conditions and results as tuples::
from sqlalchemy import case
stmt = select(users_table).where(
case(
(users_table.c.name == "wendy", "W"),
(users_table.c.name == "jack", "J"),
else_="E",
)
)
The above statement will produce SQL resembling:
.. sourcecode:: sql
SELECT id, name FROM user
WHERE CASE
WHEN (name = :name_1) THEN :param_1
WHEN (name = :name_2) THEN :param_2
ELSE :param_3
END
When simple equality expressions of several values against a single
parent column are needed, :func:`.case` also has a "shorthand" format
used via the
:paramref:`.case.value` parameter, which is passed a column
expression to be compared. In this form, the :paramref:`.case.whens`
parameter is passed as a dictionary containing expressions to be
compared against keyed to result expressions. The statement below is
equivalent to the preceding statement::
stmt = select(users_table).where(
case({"wendy": "W", "jack": "J"}, value=users_table.c.name, else_="E")
)
The values which are accepted as result values in
:paramref:`.case.whens` as well as with :paramref:`.case.else_` are
coerced from Python literals into :func:`.bindparam` constructs.
SQL expressions, e.g. :class:`_expression.ColumnElement` constructs,
are accepted
as well. To coerce a literal string expression into a constant
expression rendered inline, use the :func:`_expression.literal_column`
construct,
as in::
from sqlalchemy import case, literal_column
case(
(orderline.c.qty > 100, literal_column("'greaterthan100'")),
(orderline.c.qty > 10, literal_column("'greaterthan10'")),
else_=literal_column("'lessthan10'"),
)
The above will render the given constants without using bound
parameters for the result values (but still for the comparison
values), as in:
.. sourcecode:: sql
CASE
WHEN (orderline.qty > :qty_1) THEN 'greaterthan100'
WHEN (orderline.qty > :qty_2) THEN 'greaterthan10'
ELSE 'lessthan10'
END
:param \*whens: The criteria to be compared against,
:paramref:`.case.whens` accepts two different forms, based on
whether or not :paramref:`.case.value` is used.
.. versionchanged:: 1.4 the :func:`_sql.case`
function now accepts the series of WHEN conditions positionally
In the first form, it accepts multiple 2-tuples passed as positional
arguments; each 2-tuple consists of ``(<sql expression>, <value>)``,
where the SQL expression is a boolean expression and "value" is a
resulting value, e.g.::
case(
(users_table.c.name == "wendy", "W"),
(users_table.c.name == "jack", "J"),
)
In the second form, it accepts a Python dictionary of comparison
values mapped to a resulting value; this form requires
:paramref:`.case.value` to be present, and values will be compared
using the ``==`` operator, e.g.::
case({"wendy": "W", "jack": "J"}, value=users_table.c.name)
:param value: An optional SQL expression which will be used as a
fixed "comparison point" for candidate values within a dictionary
passed to :paramref:`.case.whens`.
:param else\_: An optional SQL expression which will be the evaluated
result of the ``CASE`` construct if all expressions within
:paramref:`.case.whens` evaluate to false. When omitted, most
databases will produce a result of NULL if none of the "when"
expressions evaluate to true.
sqlalchemy.cast
Python Library Documentation: function cast in module sqlalchemy.sql._elements_constructors
cast(expression: '_ColumnExpressionOrLiteralArgument[Any]', type_: '_TypeEngineArgument[_T]') -> 'Cast[_T]'
Produce a ``CAST`` expression.
:func:`.cast` returns an instance of :class:`.Cast`.
E.g.::
from sqlalchemy import cast, Numeric
stmt = select(cast(product_table.c.unit_price, Numeric(10, 4)))
The above statement will produce SQL resembling:
.. sourcecode:: sql
SELECT CAST(unit_price AS NUMERIC(10, 4)) FROM product
The :func:`.cast` function performs two distinct functions when
used. The first is that it renders the ``CAST`` expression within
the resulting SQL string. The second is that it associates the given
type (e.g. :class:`.TypeEngine` class or instance) with the column
expression on the Python side, which means the expression will take
on the expression operator behavior associated with that type,
as well as the bound-value handling and result-row-handling behavior
of the type.
An alternative to :func:`.cast` is the :func:`.type_coerce` function.
This function performs the second task of associating an expression
with a specific type, but does not render the ``CAST`` expression
in SQL.
:param expression: A SQL expression, such as a
:class:`_expression.ColumnElement`
expression or a Python string which will be coerced into a bound
literal value.
:param type\_: A :class:`.TypeEngine` class or instance indicating
the type to which the ``CAST`` should apply.
.. seealso::
:ref:`tutorial_casts`
:func:`.try_cast` - an alternative to CAST that results in
NULLs when the cast fails, instead of raising an error.
Only supported by some dialects.
:func:`.type_coerce` - an alternative to CAST that coerces the type
on the Python side only, which is often sufficient to generate the
correct SQL and data coercion.
sqlalchemy.collate
Python Library Documentation: function collate in module sqlalchemy.sql._elements_constructors
collate(expression: '_ColumnExpressionArgument[str]', collation: 'str') -> 'BinaryExpression[str]'
Return the clause ``expression COLLATE collation``.
e.g.::
collate(mycolumn, "utf8_bin")
produces:
.. sourcecode:: sql
mycolumn COLLATE utf8_bin
The collation expression is also quoted if it is a case sensitive
identifier, e.g. contains uppercase characters.
.. versionchanged:: 1.2 quoting is automatically applied to COLLATE
expressions if they are case sensitive.
sqlalchemy.column
Python Library Documentation: function column in module sqlalchemy.sql._elements_constructors
column(text: 'str', type_: 'Optional[_TypeEngineArgument[_T]]' = None, is_literal: 'bool' = False, _selectable: 'Optional[FromClause]' = None) -> 'ColumnClause[_T]'
Produce a :class:`.ColumnClause` object.
The :class:`.ColumnClause` is a lightweight analogue to the
:class:`_schema.Column` class. The :func:`_expression.column`
function can
be invoked with just a name alone, as in::
from sqlalchemy import column
id, name = column("id"), column("name")
stmt = select(id, name).select_from("user")
The above statement would produce SQL like:
.. sourcecode:: sql
SELECT id, name FROM user
Once constructed, :func:`_expression.column`
may be used like any other SQL
expression element such as within :func:`_expression.select`
constructs::
from sqlalchemy.sql import column
id, name = column("id"), column("name")
stmt = select(id, name).select_from("user")
The text handled by :func:`_expression.column`
is assumed to be handled
like the name of a database column; if the string contains mixed case,
special characters, or matches a known reserved word on the target
backend, the column expression will render using the quoting
behavior determined by the backend. To produce a textual SQL
expression that is rendered exactly without any quoting,
use :func:`_expression.literal_column` instead,
or pass ``True`` as the
value of :paramref:`_expression.column.is_literal`. Additionally,
full SQL
statements are best handled using the :func:`_expression.text`
construct.
:func:`_expression.column` can be used in a table-like
fashion by combining it with the :func:`.table` function
(which is the lightweight analogue to :class:`_schema.Table`
) to produce
a working table construct with minimal boilerplate::
from sqlalchemy import table, column, select
user = table(
"user",
column("id"),
column("name"),
column("description"),
)
stmt = select(user.c.description).where(user.c.name == "wendy")
A :func:`_expression.column` / :func:`.table`
construct like that illustrated
above can be created in an
ad-hoc fashion and is not associated with any
:class:`_schema.MetaData`, DDL, or events, unlike its
:class:`_schema.Table` counterpart.
:param text: the text of the element.
:param type: :class:`_types.TypeEngine` object which can associate
this :class:`.ColumnClause` with a type.
:param is_literal: if True, the :class:`.ColumnClause` is assumed to
be an exact expression that will be delivered to the output with no
quoting rules applied regardless of case sensitive settings. the
:func:`_expression.literal_column()` function essentially invokes
:func:`_expression.column` while passing ``is_literal=True``.
.. seealso::
:class:`_schema.Column`
:func:`_expression.literal_column`
:func:`.table`
:func:`_expression.text`
:ref:`tutorial_select_arbitrary_text`
sqlalchemy.create_engine
Python Library Documentation: function create_engine in module sqlalchemy.engine.create
create_engine(url: 'Union[str, _url.URL]', **kwargs: 'Any') -> 'Engine'
Create a new :class:`_engine.Engine` instance.
The standard calling form is to send the :ref:`URL <database_urls>` as the
first positional argument, usually a string
that indicates database dialect and connection arguments::
engine = create_engine("postgresql+psycopg2://scott:tiger@localhost/test")
.. note::
Please review :ref:`database_urls` for general guidelines in composing
URL strings. In particular, special characters, such as those often
part of passwords, must be URL encoded to be properly parsed.
Additional keyword arguments may then follow it which
establish various options on the resulting :class:`_engine.Engine`
and its underlying :class:`.Dialect` and :class:`_pool.Pool`
constructs::
engine = create_engine(
"mysql+mysqldb://scott:tiger@hostname/dbname",
pool_recycle=3600,
echo=True,
)
The string form of the URL is
``dialect[+driver]://user:password@host/dbname[?key=value..]``, where
``dialect`` is a database name such as ``mysql``, ``oracle``,
``postgresql``, etc., and ``driver`` the name of a DBAPI, such as
``psycopg2``, ``pyodbc``, ``cx_oracle``, etc. Alternatively,
the URL can be an instance of :class:`~sqlalchemy.engine.url.URL`.
``**kwargs`` takes a wide variety of options which are routed
towards their appropriate components. Arguments may be specific to
the :class:`_engine.Engine`, the underlying :class:`.Dialect`,
as well as the
:class:`_pool.Pool`. Specific dialects also accept keyword arguments that
are unique to that dialect. Here, we describe the parameters
that are common to most :func:`_sa.create_engine()` usage.
Once established, the newly resulting :class:`_engine.Engine` will
request a connection from the underlying :class:`_pool.Pool` once
:meth:`_engine.Engine.connect` is called, or a method which depends on it
such as :meth:`_engine.Engine.execute` is invoked. The
:class:`_pool.Pool` in turn
will establish the first actual DBAPI connection when this request
is received. The :func:`_sa.create_engine` call itself does **not**
establish any actual DBAPI connections directly.
.. seealso::
:doc:`/core/engines`
:doc:`/dialects/index`
:ref:`connections_toplevel`
:param connect_args: a dictionary of options which will be
passed directly to the DBAPI's ``connect()`` method as
additional keyword arguments. See the example
at :ref:`custom_dbapi_args`.
:param creator: a callable which returns a DBAPI connection.
This creation function will be passed to the underlying
connection pool and will be used to create all new database
connections. Usage of this function causes connection
parameters specified in the URL argument to be bypassed.
This hook is not as flexible as the newer
:meth:`_events.DialectEvents.do_connect` hook which allows complete
control over how a connection is made to the database, given the full
set of URL arguments and state beforehand.
.. seealso::
:meth:`_events.DialectEvents.do_connect` - event hook that allows
full control over DBAPI connection mechanics.
:ref:`custom_dbapi_args`
:param echo=False: if True, the Engine will log all statements
as well as a ``repr()`` of their parameter lists to the default log
handler, which defaults to ``sys.stdout`` for output. If set to the
string ``"debug"``, result rows will be printed to the standard output
as well. The ``echo`` attribute of ``Engine`` can be modified at any
time to turn logging on and off; direct control of logging is also
available using the standard Python ``logging`` module.
.. seealso::
:ref:`dbengine_logging` - further detail on how to configure
logging.
:param echo_pool=False: if True, the connection pool will log
informational output such as when connections are invalidated
as well as when connections are recycled to the default log handler,
which defaults to ``sys.stdout`` for output. If set to the string
``"debug"``, the logging will include pool checkouts and checkins.
Direct control of logging is also available using the standard Python
``logging`` module.
.. seealso::
:ref:`dbengine_logging` - further detail on how to configure
logging.
:param empty_in_strategy: No longer used; SQLAlchemy now uses
"empty set" behavior for IN in all cases.
.. deprecated:: 1.4 The :paramref:`_sa.create_engine.empty_in_strategy` keyword is deprecated, and no longer has any effect. All IN expressions are now rendered using the "expanding parameter" strategy which renders a set of boundexpressions, or an "empty set" SELECT, at statement executiontime.
:param enable_from_linting: defaults to True. Will emit a warning
if a given SELECT statement is found to have un-linked FROM elements
which would cause a cartesian product.
.. versionadded:: 1.4
.. seealso::
:ref:`change_4737`
:param execution_options: Dictionary execution options which will
be applied to all connections. See
:meth:`~sqlalchemy.engine.Connection.execution_options`
:param future: Use the 2.0 style :class:`_engine.Engine` and
:class:`_engine.Connection` API.
As of SQLAlchemy 2.0, this parameter is present for backwards
compatibility only and must remain at its default value of ``True``.
The :paramref:`_sa.create_engine.future` parameter will be
deprecated in a subsequent 2.x release and eventually removed.
.. versionadded:: 1.4
.. versionchanged:: 2.0 All :class:`_engine.Engine` objects are
"future" style engines and there is no longer a ``future=False``
mode of operation.
.. seealso::
:ref:`migration_20_toplevel`
:param hide_parameters: Boolean, when set to True, SQL statement parameters
will not be displayed in INFO logging nor will they be formatted into
the string representation of :class:`.StatementError` objects.
.. versionadded:: 1.3.8
.. seealso::
:ref:`dbengine_logging` - further detail on how to configure
logging.
:param implicit_returning=True: Legacy parameter that may only be set
to True. In SQLAlchemy 2.0, this parameter does nothing. In order to
disable "implicit returning" for statements invoked by the ORM,
configure this on a per-table basis using the
:paramref:`.Table.implicit_returning` parameter.
:param insertmanyvalues_page_size: number of rows to format into an
INSERT statement when the statement uses "insertmanyvalues" mode, which is
a paged form of bulk insert that is used for many backends when using
:term:`executemany` execution typically in conjunction with RETURNING.
Defaults to 1000, but may also be subject to dialect-specific limiting
factors which may override this value on a per-statement basis.
.. versionadded:: 2.0
.. seealso::
:ref:`engine_insertmanyvalues`
:ref:`engine_insertmanyvalues_page_size`
:paramref:`_engine.Connection.execution_options.insertmanyvalues_page_size`
:param isolation_level: optional string name of an isolation level
which will be set on all new connections unconditionally.
Isolation levels are typically some subset of the string names
``"SERIALIZABLE"``, ``"REPEATABLE READ"``,
``"READ COMMITTED"``, ``"READ UNCOMMITTED"`` and ``"AUTOCOMMIT"``
based on backend.
The :paramref:`_sa.create_engine.isolation_level` parameter is
in contrast to the
:paramref:`.Connection.execution_options.isolation_level`
execution option, which may be set on an individual
:class:`.Connection`, as well as the same parameter passed to
:meth:`.Engine.execution_options`, where it may be used to create
multiple engines with different isolation levels that share a common
connection pool and dialect.
.. versionchanged:: 2.0 The
:paramref:`_sa.create_engine.isolation_level`
parameter has been generalized to work on all dialects which support
the concept of isolation level, and is provided as a more succinct,
up front configuration switch in contrast to the execution option
which is more of an ad-hoc programmatic option.
.. seealso::
:ref:`dbapi_autocommit`
:param json_deserializer: for dialects that support the
:class:`_types.JSON`
datatype, this is a Python callable that will convert a JSON string
to a Python object. By default, the Python ``json.loads`` function is
used.
.. versionchanged:: 1.3.7 The SQLite dialect renamed this from
``_json_deserializer``.
:param json_serializer: for dialects that support the :class:`_types.JSON`
datatype, this is a Python callable that will render a given object
as JSON. By default, the Python ``json.dumps`` function is used.
.. versionchanged:: 1.3.7 The SQLite dialect renamed this from
``_json_serializer``.
:param label_length=None: optional integer value which limits
the size of dynamically generated column labels to that many
characters. If less than 6, labels are generated as
"_(counter)". If ``None``, the value of
``dialect.max_identifier_length``, which may be affected via the
:paramref:`_sa.create_engine.max_identifier_length` parameter,
is used instead. The value of
:paramref:`_sa.create_engine.label_length`
may not be larger than that of
:paramref:`_sa.create_engine.max_identfier_length`.
.. seealso::
:paramref:`_sa.create_engine.max_identifier_length`
:param logging_name: String identifier which will be used within
the "name" field of logging records generated within the
"sqlalchemy.engine" logger. Defaults to a hexstring of the
object's id.
.. seealso::
:ref:`dbengine_logging` - further detail on how to configure
logging.
:paramref:`_engine.Connection.execution_options.logging_token`
:param max_identifier_length: integer; override the max_identifier_length
determined by the dialect. if ``None`` or zero, has no effect. This
is the database's configured maximum number of characters that may be
used in a SQL identifier such as a table name, column name, or label
name. All dialects determine this value automatically, however in the
case of a new database version for which this value has changed but
SQLAlchemy's dialect has not been adjusted, the value may be passed
here.
.. versionadded:: 1.3.9
.. seealso::
:paramref:`_sa.create_engine.label_length`
:param max_overflow=10: the number of connections to allow in
connection pool "overflow", that is connections that can be
opened above and beyond the pool_size setting, which defaults
to five. this is only used with :class:`~sqlalchemy.pool.QueuePool`.
:param module=None: reference to a Python module object (the module
itself, not its string name). Specifies an alternate DBAPI module to
be used by the engine's dialect. Each sub-dialect references a
specific DBAPI which will be imported before first connect. This
parameter causes the import to be bypassed, and the given module to
be used instead. Can be used for testing of DBAPIs as well as to
inject "mock" DBAPI implementations into the :class:`_engine.Engine`.
:param paramstyle=None: The `paramstyle <https://legacy.python.org/dev/peps/pep-0249/#paramstyle>`_
to use when rendering bound parameters. This style defaults to the
one recommended by the DBAPI itself, which is retrieved from the
``.paramstyle`` attribute of the DBAPI. However, most DBAPIs accept
more than one paramstyle, and in particular it may be desirable
to change a "named" paramstyle into a "positional" one, or vice versa.
When this attribute is passed, it should be one of the values
``"qmark"``, ``"numeric"``, ``"named"``, ``"format"`` or
``"pyformat"``, and should correspond to a parameter style known
to be supported by the DBAPI in use.
:param pool=None: an already-constructed instance of
:class:`~sqlalchemy.pool.Pool`, such as a
:class:`~sqlalchemy.pool.QueuePool` instance. If non-None, this
pool will be used directly as the underlying connection pool
for the engine, bypassing whatever connection parameters are
present in the URL argument. For information on constructing
connection pools manually, see :ref:`pooling_toplevel`.
:param poolclass=None: a :class:`~sqlalchemy.pool.Pool`
subclass, which will be used to create a connection pool
instance using the connection parameters given in the URL. Note
this differs from ``pool`` in that you don't actually
instantiate the pool in this case, you just indicate what type
of pool to be used.
:param pool_logging_name: String identifier which will be used within
the "name" field of logging records generated within the
"sqlalchemy.pool" logger. Defaults to a hexstring of the object's
id.
.. seealso::
:ref:`dbengine_logging` - further detail on how to configure
logging.
:param pool_pre_ping: boolean, if True will enable the connection pool
"pre-ping" feature that tests connections for liveness upon
each checkout.
.. versionadded:: 1.2
.. seealso::
:ref:`pool_disconnects_pessimistic`
:param pool_size=5: the number of connections to keep open
inside the connection pool. This used with
:class:`~sqlalchemy.pool.QueuePool` as
well as :class:`~sqlalchemy.pool.SingletonThreadPool`. With
:class:`~sqlalchemy.pool.QueuePool`, a ``pool_size`` setting
of 0 indicates no limit; to disable pooling, set ``poolclass`` to
:class:`~sqlalchemy.pool.NullPool` instead.
:param pool_recycle=-1: this setting causes the pool to recycle
connections after the given number of seconds has passed. It
defaults to -1, or no timeout. For example, setting to 3600
means connections will be recycled after one hour. Note that
MySQL in particular will disconnect automatically if no
activity is detected on a connection for eight hours (although
this is configurable with the MySQLDB connection itself and the
server configuration as well).
.. seealso::
:ref:`pool_setting_recycle`
:param pool_reset_on_return='rollback': set the
:paramref:`_pool.Pool.reset_on_return` parameter of the underlying
:class:`_pool.Pool` object, which can be set to the values
``"rollback"``, ``"commit"``, or ``None``.
.. seealso::
:ref:`pool_reset_on_return`
:ref:`dbapi_autocommit_skip_rollback` - a more modern approach
to using connections with no transactional instructions
:param pool_timeout=30: number of seconds to wait before giving
up on getting a connection from the pool. This is only used
with :class:`~sqlalchemy.pool.QueuePool`. This can be a float but is
subject to the limitations of Python time functions which may not be
reliable in the tens of milliseconds.
.. note: don't use 30.0 above, it seems to break with the :param tag
:param pool_use_lifo=False: use LIFO (last-in-first-out) when retrieving
connections from :class:`.QueuePool` instead of FIFO
(first-in-first-out). Using LIFO, a server-side timeout scheme can
reduce the number of connections used during non- peak periods of
use. When planning for server-side timeouts, ensure that a recycle or
pre-ping strategy is in use to gracefully handle stale connections.
.. versionadded:: 1.3
.. seealso::
:ref:`pool_use_lifo`
:ref:`pool_disconnects`
:param plugins: string list of plugin names to load. See
:class:`.CreateEnginePlugin` for background.
.. versionadded:: 1.2.3
:param query_cache_size: size of the cache used to cache the SQL string
form of queries. Set to zero to disable caching.
The cache is pruned of its least recently used items when its size reaches
N * 1.5. Defaults to 500, meaning the cache will always store at least
500 SQL statements when filled, and will grow up to 750 items at which
point it is pruned back down to 500 by removing the 250 least recently
used items.
Caching is accomplished on a per-statement basis by generating a
cache key that represents the statement's structure, then generating
string SQL for the current dialect only if that key is not present
in the cache. All statements support caching, however some features
such as an INSERT with a large set of parameters will intentionally
bypass the cache. SQL logging will indicate statistics for each
statement whether or not it were pull from the cache.
.. note:: some ORM functions related to unit-of-work persistence as well
as some attribute loading strategies will make use of individual
per-mapper caches outside of the main cache.
.. seealso::
:ref:`sql_caching`
.. versionadded:: 1.4
:param skip_autocommit_rollback: When True, the dialect will
unconditionally skip all calls to the DBAPI ``connection.rollback()``
method if the DBAPI connection is confirmed to be in "autocommit" mode.
The availability of this feature is dialect specific; if not available,
a ``NotImplementedError`` is raised by the dialect when rollback occurs.
.. seealso::
:ref:`dbapi_autocommit_skip_rollback`
.. versionadded:: 2.0.43
:param use_insertmanyvalues: True by default, use the "insertmanyvalues"
execution style for INSERT..RETURNING statements by default.
.. versionadded:: 2.0
.. seealso::
:ref:`engine_insertmanyvalues`
sqlalchemy.create_mock_engine
Python Library Documentation: function create_mock_engine in module sqlalchemy.engine.mock
create_mock_engine(url: 'Union[str, URL]', executor: 'Any', **kw: 'Any') -> 'MockConnection'
Create a "mock" engine used for echoing DDL.
This is a utility function used for debugging or storing the output of DDL
sequences as generated by :meth:`_schema.MetaData.create_all`
and related methods.
The function accepts a URL which is used only to determine the kind of
dialect to be used, as well as an "executor" callable function which
will receive a SQL expression object and parameters, which can then be
echoed or otherwise printed. The executor's return value is not handled,
nor does the engine allow regular string statements to be invoked, and
is therefore only useful for DDL that is sent to the database without
receiving any results.
E.g.::
from sqlalchemy import create_mock_engine
def dump(sql, *multiparams, **params):
print(sql.compile(dialect=engine.dialect))
engine = create_mock_engine("postgresql+psycopg2://", dump)
metadata.create_all(engine, checkfirst=False)
:param url: A string URL which typically needs to contain only the
database backend name.
:param executor: a callable which receives the arguments ``sql``,
``*multiparams`` and ``**params``. The ``sql`` parameter is typically
an instance of :class:`.ExecutableDDLElement`, which can then be compiled
into a string using :meth:`.ExecutableDDLElement.compile`.
.. versionadded:: 1.4 - the :func:`.create_mock_engine` function replaces
the previous "mock" engine strategy used with
:func:`_sa.create_engine`.
.. seealso::
:ref:`faq_ddl_as_string`
sqlalchemy.create_pool_from_url
Python Library Documentation: function create_pool_from_url in module sqlalchemy.engine.create
create_pool_from_url(url: 'Union[str, URL]', **kwargs: 'Any') -> 'Pool'
Create a pool instance from the given url.
If ``poolclass`` is not provided the pool class used
is selected using the dialect specified in the URL.
The arguments passed to :func:`_sa.create_pool_from_url` are
identical to the pool argument passed to the :func:`_sa.create_engine`
function.
.. versionadded:: 2.0.10
sqlalchemy.cte
Python Library Documentation: function cte in module sqlalchemy.sql._selectable_constructors
cte(selectable: 'HasCTE', name: 'Optional[str]' = None, recursive: 'bool' = False) -> 'CTE'
Return a new :class:`_expression.CTE`,
or Common Table Expression instance.
Please see :meth:`_expression.HasCTE.cte` for detail on CTE usage.
sqlalchemy.custom_op
Python Library Documentation: class custom_op in module sqlalchemy.sql.operators
class custom_op(OperatorType, typing.Generic)
| custom_op(opstring: 'str', precedence: 'int' = 0, is_comparison: 'bool' = False, return_type: 'Optional[Union[Type[TypeEngine[_T]], TypeEngine[_T]]]' = None, natural_self_precedent: 'bool' = False, eager_grouping: 'bool' = False, python_impl: 'Optional[Callable[..., Any]]' = None)
|
| Represent a 'custom' operator.
|
| :class:`.custom_op` is normally instantiated when the
| :meth:`.Operators.op` or :meth:`.Operators.bool_op` methods
| are used to create a custom operator callable. The class can also be
| used directly when programmatically constructing expressions. E.g.
| to represent the "factorial" operation::
|
| from sqlalchemy.sql import UnaryExpression
| from sqlalchemy.sql import operators
| from sqlalchemy import Numeric
|
| unary = UnaryExpression(
| table.c.somecolumn, modifier=operators.custom_op("!"), type_=Numeric
| )
|
| .. seealso::
|
| :meth:`.Operators.op`
|
| :meth:`.Operators.bool_op`
|
| Method resolution order:
| custom_op
| OperatorType
| typing_extensions.Protocol
| typing.Generic
| builtins.object
|
| Methods defined here:
|
| __call__(self, left: 'Any', right: 'Optional[Any]' = None, *other: 'Any', **kwargs: 'Any') -> 'Operators'
| Call self as a function.
|
| __eq__(self, other: 'Any') -> 'bool'
| Return self==value.
|
| __hash__(self) -> 'int'
| Return hash(self).
|
| __init__(self, opstring: 'str', precedence: 'int' = 0, is_comparison: 'bool' = False, return_type: 'Optional[Union[Type[TypeEngine[_T]], TypeEngine[_T]]]' = None, natural_self_precedent: 'bool' = False, eager_grouping: 'bool' = False, python_impl: 'Optional[Callable[..., Any]]' = None)
| Initialize self. See help(type(self)) for accurate signature.
|
| ----------------------------------------------------------------------
| Class methods defined here:
|
| __subclasshook__ = _proto_hook(other) from typing_extensions
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| eager_grouping
|
| is_comparison
|
| natural_self_precedent
|
| opstring
|
| precedence
|
| python_impl
|
| return_type
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __abstractmethods__ = frozenset()
|
| __annotations__ = {}
|
| __orig_bases__ = (<class 'sqlalchemy.sql.operators.OperatorType'>, typ...
|
| __parameters__ = (~_T,)
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from OperatorType:
|
| __protocol_attrs__ = {'__call__', '__name__'}
|
| ----------------------------------------------------------------------
| Class methods inherited from typing_extensions.Protocol:
|
| __init_subclass__(*args, **kwargs)
| Function to initialize subclasses.
|
| ----------------------------------------------------------------------
| Class methods inherited from typing.Generic:
|
| __class_getitem__(...)
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
sqlalchemy.cyextension
Python Library Documentation: package sqlalchemy.cyextension in sqlalchemy
NAME
sqlalchemy.cyextension
DESCRIPTION
# cyextension/__init__.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
PACKAGE CONTENTS
collections
immutabledict
processors
resultproxy
util
FILE
c:\users\youse\appdata\local\programs\python\python312\lib\site-packages\sqlalchemy\cyextension\__init__.py
sqlalchemy.delete
Python Library Documentation: function delete in module sqlalchemy.sql._dml_constructors
delete(table: '_DMLTableArgument') -> 'Delete'
Construct :class:`_expression.Delete` object.
E.g.::
from sqlalchemy import delete
stmt = delete(user_table).where(user_table.c.id == 5)
Similar functionality is available via the
:meth:`_expression.TableClause.delete` method on
:class:`_schema.Table`.
:param table: The table to delete rows from.
.. seealso::
:ref:`tutorial_core_update_delete` - in the :ref:`unified_tutorial`
sqlalchemy.desc
Python Library Documentation: function desc in module sqlalchemy.sql._elements_constructors
desc(column: '_ColumnExpressionOrStrLabelArgument[_T]') -> 'UnaryExpression[_T]'
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:
.. sourcecode:: sql
SELECT id, name FROM user ORDER BY name DESC
The :func:`.desc` function is a standalone version of the
:meth:`_expression.ColumnElement.desc`
method available on all SQL expressions,
e.g.::
stmt = select(users_table).order_by(users_table.c.name.desc())
:param column: A :class:`_expression.ColumnElement` (e.g.
scalar SQL expression)
with which to apply the :func:`.desc` operation.
.. seealso::
:func:`.asc`
:func:`.nulls_first`
:func:`.nulls_last`
:meth:`_expression.Select.order_by`
sqlalchemy.dialects
Python Library Documentation: package sqlalchemy.dialects in sqlalchemy
NAME
sqlalchemy.dialects
DESCRIPTION
# dialects/__init__.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
PACKAGE CONTENTS
_typing
mssql (package)
mysql (package)
oracle (package)
postgresql (package)
sqlite (package)
DATA
__all__ = ('mssql', 'mysql', 'oracle', 'postgresql', 'sqlite')
FILE
c:\users\youse\appdata\local\programs\python\python312\lib\site-packages\sqlalchemy\dialects\__init__.py
sqlalchemy.distinct
Python Library Documentation: function distinct in module sqlalchemy.sql._elements_constructors
distinct(expr: '_ColumnExpressionArgument[_T]') -> 'UnaryExpression[_T]'
Produce an column-expression-level unary ``DISTINCT`` clause.
This applies the ``DISTINCT`` keyword to an **individual column
expression** (e.g. not the whole statement), and renders **specifically
in that column position**; this is used for containment within
an aggregate function, as in::
from sqlalchemy import distinct, func
stmt = select(users_table.c.id, func.count(distinct(users_table.c.name)))
The above would produce an statement resembling:
.. sourcecode:: sql
SELECT user.id, count(DISTINCT user.name) FROM user
.. tip:: The :func:`_sql.distinct` function does **not** apply DISTINCT
to the full SELECT statement, instead applying a DISTINCT modifier
to **individual column expressions**. For general ``SELECT DISTINCT``
support, use the
:meth:`_sql.Select.distinct` method on :class:`_sql.Select`.
The :func:`.distinct` function is also available as a column-level
method, e.g. :meth:`_expression.ColumnElement.distinct`, as in::
stmt = select(func.count(users_table.c.name.distinct()))
The :func:`.distinct` operator is different from the
:meth:`_expression.Select.distinct` method of
:class:`_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.
.. seealso::
:meth:`_expression.ColumnElement.distinct`
:meth:`_expression.Select.distinct`
:data:`.func`
sqlalchemy.engine
Python Library Documentation: package sqlalchemy.engine in sqlalchemy
NAME
sqlalchemy.engine - SQL connections, SQL execution and high-level DB-API interface.
DESCRIPTION
The engine package defines the basic components used to interface
DB-API modules with higher-level statement construction,
connection-management, execution and result contexts. The primary
"entry point" class into this package is the Engine and its public
constructor ``create_engine()``.
PACKAGE CONTENTS
_py_processors
_py_row
_py_util
base
characteristics
create
cursor
default
events
interfaces
mock
processors
reflection
result
row
strategies
url
util
DATA
ConnectArgsType = typing.Tuple[typing.Sequence[str], typing.MutableMap...
FILE
c:\users\youse\appdata\local\programs\python\python312\lib\site-packages\sqlalchemy\engine\__init__.py
sqlalchemy.engine_from_config
Python Library Documentation: function engine_from_config in module sqlalchemy.engine.create
engine_from_config(configuration: 'Dict[str, Any]', prefix: 'str' = 'sqlalchemy.', **kwargs: 'Any') -> 'Engine'
Create a new Engine instance using a configuration dictionary.
The dictionary is typically produced from a config file.
The keys of interest to ``engine_from_config()`` should be prefixed, e.g.
``sqlalchemy.url``, ``sqlalchemy.echo``, etc. The 'prefix' argument
indicates the prefix to be searched for. Each matching key (after the
prefix is stripped) is treated as though it were the corresponding keyword
argument to a :func:`_sa.create_engine` call.
The only required key is (assuming the default prefix) ``sqlalchemy.url``,
which provides the :ref:`database URL <database_urls>`.
A select set of keyword arguments will be "coerced" to their
expected type based on string values. The set of arguments
is extensible per-dialect using the ``engine_config_types`` accessor.
:param configuration: A dictionary (typically produced from a config file,
but this is not a requirement). Items whose keys start with the value
of 'prefix' will have that prefix stripped, and will then be passed to
:func:`_sa.create_engine`.
:param prefix: Prefix to match and then strip from keys
in 'configuration'.
:param kwargs: Each keyword argument to ``engine_from_config()`` itself
overrides the corresponding item taken from the 'configuration'
dictionary. Keyword arguments should *not* be prefixed.
sqlalchemy.event
Python Library Documentation: package sqlalchemy.event in sqlalchemy
NAME
sqlalchemy.event
DESCRIPTION
# event/__init__.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
PACKAGE CONTENTS
api
attr
base
legacy
registry
DATA
CANCEL = symbol('CANCEL')
NO_RETVAL = symbol('NO_RETVAL')
FILE
c:\users\youse\appdata\local\programs\python\python312\lib\site-packages\sqlalchemy\event\__init__.py
sqlalchemy.exc
Python Library Documentation: module sqlalchemy.exc in sqlalchemy
NAME
sqlalchemy.exc - Exceptions used with SQLAlchemy.
DESCRIPTION
The base exception class is :exc:`.SQLAlchemyError`. Exceptions which are
raised as a result of DBAPI exceptions are all subclasses of
:exc:`.DBAPIError`.
CLASSES
builtins.PendingDeprecationWarning(builtins.Warning)
SAPendingDeprecationWarning
builtins.Warning(builtins.Exception)
SATestSuiteWarning
builtins.object
DontWrapMixin
HasDescriptionCode
SADeprecationWarning(HasDescriptionCode, builtins.DeprecationWarning)
Base20DeprecationWarning
LegacyAPIWarning
MovedIn20Warning
SAWarning(HasDescriptionCode, builtins.RuntimeWarning)
SQLAlchemyError(HasDescriptionCode, builtins.Exception)
ArgumentError
AmbiguousForeignKeysError
ConstraintColumnNotFoundError
DuplicateColumnError
NoForeignKeysError
NoSuchModuleError
ObjectNotExecutableError
CircularDependencyError
CompileError
UnsupportedCompilationError
DisconnectionError
InvalidatePoolError
IdentifierError
InvalidRequestError
AwaitRequired
IllegalStateChangeError
MissingGreenlet
MultipleResultsFound
NoInspectionAvailable
NoReferenceError
NoReferencedColumnError
NoReferencedTableError
NoResultFound
NoSuchColumnError(InvalidRequestError, builtins.KeyError)
NoSuchTableError
PendingRollbackError
ResourceClosedError
UnboundExecutionError
UnreflectableTableError
StatementError
DBAPIError
DatabaseError
DataError
IntegrityError
InternalError
NotSupportedError
OperationalError
ProgrammingError
InterfaceError
TimeoutError
class AmbiguousForeignKeysError(ArgumentError)
| AmbiguousForeignKeysError(*arg: 'Any', **kw: 'Any')
|
| Raised when more than one foreign key matching can be located
| between two selectables during a join.
|
| Method resolution order:
| AmbiguousForeignKeysError
| ArgumentError
| SQLAlchemyError
| HasDescriptionCode
| builtins.Exception
| builtins.BaseException
| builtins.object
|
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| ----------------------------------------------------------------------
| Methods inherited from SQLAlchemyError:
|
| __str__(self) -> 'str'
| Return str(self).
|
| ----------------------------------------------------------------------
| Data descriptors inherited from SQLAlchemyError:
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Methods inherited from HasDescriptionCode:
|
| __init__(self, *arg: 'Any', **kw: 'Any')
| Initialize self. See help(type(self)) for accurate signature.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from HasDescriptionCode:
|
| __dict__
| dictionary for instance variables
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from HasDescriptionCode:
|
| code = None
|
| ----------------------------------------------------------------------
| Static methods inherited from builtins.Exception:
|
| __new__(*args, **kwargs) class method of builtins.Exception
| Create and return a new object. See help(type) for accurate signature.
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.BaseException:
|
| __getattribute__(self, name, /)
| Return getattr(self, name).
|
| __reduce__(...)
| Helper for pickle.
|
| __repr__(self, /)
| Return repr(self).
|
| __setstate__(...)
|
| add_note(...)
| Exception.add_note(note) --
| add a note to the exception
|
| with_traceback(...)
| Exception.with_traceback(tb) --
| set self.__traceback__ to tb and return self.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from builtins.BaseException:
|
| __cause__
| exception cause
|
| __context__
| exception context
|
| __suppress_context__
|
| __traceback__
|
| args
class ArgumentError(SQLAlchemyError)
| ArgumentError(*arg: 'Any', **kw: 'Any')
|
| Raised when an invalid or conflicting function argument is supplied.
|
| This error generally corresponds to construction time state errors.
|
| Method resolution order:
| ArgumentError
| SQLAlchemyError
| HasDescriptionCode
| builtins.Exception
| builtins.BaseException
| builtins.object
|
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| ----------------------------------------------------------------------
| Methods inherited from SQLAlchemyError:
|
| __str__(self) -> 'str'
| Return str(self).
|
| ----------------------------------------------------------------------
| Data descriptors inherited from SQLAlchemyError:
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Methods inherited from HasDescriptionCode:
|
| __init__(self, *arg: 'Any', **kw: 'Any')
| Initialize self. See help(type(self)) for accurate signature.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from HasDescriptionCode:
|
| __dict__
| dictionary for instance variables
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from HasDescriptionCode:
|
| code = None
|
| ----------------------------------------------------------------------
| Static methods inherited from builtins.Exception:
|
| __new__(*args, **kwargs) class method of builtins.Exception
| Create and return a new object. See help(type) for accurate signature.
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.BaseException:
|
| __getattribute__(self, name, /)
| Return getattr(self, name).
|
| __reduce__(...)
| Helper for pickle.
|
| __repr__(self, /)
| Return repr(self).
|
| __setstate__(...)
|
| add_note(...)
| Exception.add_note(note) --
| add a note to the exception
|
| with_traceback(...)
| Exception.with_traceback(tb) --
| set self.__traceback__ to tb and return self.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from builtins.BaseException:
|
| __cause__
| exception cause
|
| __context__
| exception context
|
| __suppress_context__
|
| __traceback__
|
| args
class AwaitRequired(InvalidRequestError)
| AwaitRequired(*arg: 'Any', **kw: 'Any')
|
| Error raised by the async greenlet spawn if no async operation
| was awaited when it required one.
|
| Method resolution order:
| AwaitRequired
| InvalidRequestError
| SQLAlchemyError
| HasDescriptionCode
| builtins.Exception
| builtins.BaseException
| builtins.object
|
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| code = 'xd1r'
|
| ----------------------------------------------------------------------
| Methods inherited from SQLAlchemyError:
|
| __str__(self) -> 'str'
| Return str(self).
|
| ----------------------------------------------------------------------
| Data descriptors inherited from SQLAlchemyError:
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Methods inherited from HasDescriptionCode:
|
| __init__(self, *arg: 'Any', **kw: 'Any')
| Initialize self. See help(type(self)) for accurate signature.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from HasDescriptionCode:
|
| __dict__
| dictionary for instance variables
|
| ----------------------------------------------------------------------
| Static methods inherited from builtins.Exception:
|
| __new__(*args, **kwargs) class method of builtins.Exception
| Create and return a new object. See help(type) for accurate signature.
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.BaseException:
|
| __getattribute__(self, name, /)
| Return getattr(self, name).
|
| __reduce__(...)
| Helper for pickle.
|
| __repr__(self, /)
| Return repr(self).
|
| __setstate__(...)
|
| add_note(...)
| Exception.add_note(note) --
| add a note to the exception
|
| with_traceback(...)
| Exception.with_traceback(tb) --
| set self.__traceback__ to tb and return self.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from builtins.BaseException:
|
| __cause__
| exception cause
|
| __context__
| exception context
|
| __suppress_context__
|
| __traceback__
|
| args
class Base20DeprecationWarning(SADeprecationWarning)
| Base20DeprecationWarning(*arg: 'Any', **kw: 'Any')
|
| Issued for usage of APIs specifically deprecated or legacy in
| SQLAlchemy 2.0.
|
| .. seealso::
|
| :ref:`error_b8d9`.
|
| :ref:`deprecation_20_mode`
|
| Method resolution order:
| Base20DeprecationWarning
| SADeprecationWarning
| HasDescriptionCode
| builtins.DeprecationWarning
| builtins.Warning
| builtins.Exception
| builtins.BaseException
| builtins.object
|
| Methods defined here:
|
| __str__(self) -> 'str'
| Return str(self).
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'deprecated_since': 'Optional[str]'}
|
| deprecated_since = '1.4'
|
| ----------------------------------------------------------------------
| Data descriptors inherited from SADeprecationWarning:
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Methods inherited from HasDescriptionCode:
|
| __init__(self, *arg: 'Any', **kw: 'Any')
| Initialize self. See help(type(self)) for accurate signature.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from HasDescriptionCode:
|
| __dict__
| dictionary for instance variables
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from HasDescriptionCode:
|
| code = None
|
| ----------------------------------------------------------------------
| Static methods inherited from builtins.DeprecationWarning:
|
| __new__(*args, **kwargs) class method of builtins.DeprecationWarning
| Create and return a new object. See help(type) for accurate signature.
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.BaseException:
|
| __getattribute__(self, name, /)
| Return getattr(self, name).
|
| __reduce__(...)
| Helper for pickle.
|
| __repr__(self, /)
| Return repr(self).
|
| __setstate__(...)
|
| add_note(...)
| Exception.add_note(note) --
| add a note to the exception
|
| with_traceback(...)
| Exception.with_traceback(tb) --
| set self.__traceback__ to tb and return self.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from builtins.BaseException:
|
| __cause__
| exception cause
|
| __context__
| exception context
|
| __suppress_context__
|
| __traceback__
|
| args
class CircularDependencyError(SQLAlchemyError)
| CircularDependencyError(message: 'str', cycles: 'Any', edges: 'Any', msg: 'Optional[str]' = None, code: 'Optional[str]' = None)
|
| Raised by topological sorts when a circular dependency is detected.
|
| There are two scenarios where this error occurs:
|
| * In a Session flush operation, if two objects are mutually dependent
| on each other, they can not be inserted or deleted via INSERT or
| DELETE statements alone; an UPDATE will be needed to post-associate
| or pre-deassociate one of the foreign key constrained values.
| The ``post_update`` flag described at :ref:`post_update` can resolve
| this cycle.
| * In a :attr:`_schema.MetaData.sorted_tables` operation, two
| :class:`_schema.ForeignKey`
| or :class:`_schema.ForeignKeyConstraint` objects mutually refer to each
| other. Apply the ``use_alter=True`` flag to one or both,
| see :ref:`use_alter`.
|
| Method resolution order:
| CircularDependencyError
| SQLAlchemyError
| HasDescriptionCode
| builtins.Exception
| builtins.BaseException
| builtins.object
|
| Methods defined here:
|
| __init__(self, message: 'str', cycles: 'Any', edges: 'Any', msg: 'Optional[str]' = None, code: 'Optional[str]' = None)
| Initialize self. See help(type(self)) for accurate signature.
|
| __reduce__(self) -> 'Union[str, Tuple[Any, ...]]'
| Helper for pickle.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| ----------------------------------------------------------------------
| Methods inherited from SQLAlchemyError:
|
| __str__(self) -> 'str'
| Return str(self).
|
| ----------------------------------------------------------------------
| Data descriptors inherited from SQLAlchemyError:
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data descriptors inherited from HasDescriptionCode:
|
| __dict__
| dictionary for instance variables
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from HasDescriptionCode:
|
| code = None
|
| ----------------------------------------------------------------------
| Static methods inherited from builtins.Exception:
|
| __new__(*args, **kwargs) class method of builtins.Exception
| Create and return a new object. See help(type) for accurate signature.
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.BaseException:
|
| __getattribute__(self, name, /)
| Return getattr(self, name).
|
| __repr__(self, /)
| Return repr(self).
|
| __setstate__(...)
|
| add_note(...)
| Exception.add_note(note) --
| add a note to the exception
|
| with_traceback(...)
| Exception.with_traceback(tb) --
| set self.__traceback__ to tb and return self.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from builtins.BaseException:
|
| __cause__
| exception cause
|
| __context__
| exception context
|
| __suppress_context__
|
| __traceback__
|
| args
class CompileError(SQLAlchemyError)
| CompileError(*arg: 'Any', **kw: 'Any')
|
| Raised when an error occurs during SQL compilation
|
| Method resolution order:
| CompileError
| SQLAlchemyError
| HasDescriptionCode
| builtins.Exception
| builtins.BaseException
| builtins.object
|
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| ----------------------------------------------------------------------
| Methods inherited from SQLAlchemyError:
|
| __str__(self) -> 'str'
| Return str(self).
|
| ----------------------------------------------------------------------
| Data descriptors inherited from SQLAlchemyError:
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Methods inherited from HasDescriptionCode:
|
| __init__(self, *arg: 'Any', **kw: 'Any')
| Initialize self. See help(type(self)) for accurate signature.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from HasDescriptionCode:
|
| __dict__
| dictionary for instance variables
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from HasDescriptionCode:
|
| code = None
|
| ----------------------------------------------------------------------
| Static methods inherited from builtins.Exception:
|
| __new__(*args, **kwargs) class method of builtins.Exception
| Create and return a new object. See help(type) for accurate signature.
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.BaseException:
|
| __getattribute__(self, name, /)
| Return getattr(self, name).
|
| __reduce__(...)
| Helper for pickle.
|
| __repr__(self, /)
| Return repr(self).
|
| __setstate__(...)
|
| add_note(...)
| Exception.add_note(note) --
| add a note to the exception
|
| with_traceback(...)
| Exception.with_traceback(tb) --
| set self.__traceback__ to tb and return self.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from builtins.BaseException:
|
| __cause__
| exception cause
|
| __context__
| exception context
|
| __suppress_context__
|
| __traceback__
|
| args
class ConstraintColumnNotFoundError(ArgumentError)
| ConstraintColumnNotFoundError(*arg: 'Any', **kw: 'Any')
|
| raised when a constraint refers to a string column name that
| is not present in the table being constrained.
|
| .. versionadded:: 2.0
|
| Method resolution order:
| ConstraintColumnNotFoundError
| ArgumentError
| SQLAlchemyError
| HasDescriptionCode
| builtins.Exception
| builtins.BaseException
| builtins.object
|
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| ----------------------------------------------------------------------
| Methods inherited from SQLAlchemyError:
|
| __str__(self) -> 'str'
| Return str(self).
|
| ----------------------------------------------------------------------
| Data descriptors inherited from SQLAlchemyError:
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Methods inherited from HasDescriptionCode:
|
| __init__(self, *arg: 'Any', **kw: 'Any')
| Initialize self. See help(type(self)) for accurate signature.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from HasDescriptionCode:
|
| __dict__
| dictionary for instance variables
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from HasDescriptionCode:
|
| code = None
|
| ----------------------------------------------------------------------
| Static methods inherited from builtins.Exception:
|
| __new__(*args, **kwargs) class method of builtins.Exception
| Create and return a new object. See help(type) for accurate signature.
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.BaseException:
|
| __getattribute__(self, name, /)
| Return getattr(self, name).
|
| __reduce__(...)
| Helper for pickle.
|
| __repr__(self, /)
| Return repr(self).
|
| __setstate__(...)
|
| add_note(...)
| Exception.add_note(note) --
| add a note to the exception
|
| with_traceback(...)
| Exception.with_traceback(tb) --
| set self.__traceback__ to tb and return self.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from builtins.BaseException:
|
| __cause__
| exception cause
|
| __context__
| exception context
|
| __suppress_context__
|
| __traceback__
|
| args
class DBAPIError(StatementError)
| DBAPIError(statement: 'Optional[str]', params: 'Optional[_AnyExecuteParams]', orig: 'BaseException', hide_parameters: 'bool' = False, connection_invalidated: 'bool' = False, code: 'Optional[str]' = None, ismulti: 'Optional[bool]' = None)
|
| Raised when the execution of a database operation fails.
|
| Wraps exceptions raised by the DB-API underlying the
| database operation. Driver-specific implementations of the standard
| DB-API exception types are wrapped by matching sub-types of SQLAlchemy's
| :class:`DBAPIError` when possible. DB-API's ``Error`` type maps to
| :class:`DBAPIError` in SQLAlchemy, otherwise the names are identical. Note
| that there is no guarantee that different DB-API implementations will
| raise the same exception type for any given error condition.
|
| :class:`DBAPIError` features :attr:`~.StatementError.statement`
| and :attr:`~.StatementError.params` attributes which supply context
| regarding the specifics of the statement which had an issue, for the
| typical case when the error was raised within the context of
| emitting a SQL statement.
|
| The wrapped exception object is available in the
| :attr:`~.StatementError.orig` attribute. Its type and properties are
| DB-API implementation specific.
|
| Method resolution order:
| DBAPIError
| StatementError
| SQLAlchemyError
| HasDescriptionCode
| builtins.Exception
| builtins.BaseException
| builtins.object
|
| Methods defined here:
|
| __init__(self, statement: 'Optional[str]', params: 'Optional[_AnyExecuteParams]', orig: 'BaseException', hide_parameters: 'bool' = False, connection_invalidated: 'bool' = False, code: 'Optional[str]' = None, ismulti: 'Optional[bool]' = None)
| Initialize self. See help(type(self)) for accurate signature.
|
| __reduce__(self) -> 'Union[str, Tuple[Any, ...]]'
| Helper for pickle.
|
| ----------------------------------------------------------------------
| Class methods defined here:
|
| instance(statement: 'Optional[str]', params: 'Optional[_AnyExecuteParams]', orig: 'Union[BaseException, DontWrapMixin]', dbapi_base_err: 'Type[Exception]', hide_parameters: 'bool' = False, connection_invalidated: 'bool' = False, dialect: 'Optional[Dialect]' = None, ismulti: 'Optional[bool]' = None) -> 'Union[BaseException, DontWrapMixin]'
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| code = 'dbapi'
|
| ----------------------------------------------------------------------
| Methods inherited from StatementError:
|
| add_detail(self, msg: 'str') -> 'None'
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from StatementError:
|
| connection_invalidated = False
|
| ismulti = None
|
| orig = None
|
| params = None
|
| statement = None
|
| ----------------------------------------------------------------------
| Methods inherited from SQLAlchemyError:
|
| __str__(self) -> 'str'
| Return str(self).
|
| ----------------------------------------------------------------------
| Data descriptors inherited from SQLAlchemyError:
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data descriptors inherited from HasDescriptionCode:
|
| __dict__
| dictionary for instance variables
|
| ----------------------------------------------------------------------
| Static methods inherited from builtins.Exception:
|
| __new__(*args, **kwargs) class method of builtins.Exception
| Create and return a new object. See help(type) for accurate signature.
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.BaseException:
|
| __getattribute__(self, name, /)
| Return getattr(self, name).
|
| __repr__(self, /)
| Return repr(self).
|
| __setstate__(...)
|
| add_note(...)
| Exception.add_note(note) --
| add a note to the exception
|
| with_traceback(...)
| Exception.with_traceback(tb) --
| set self.__traceback__ to tb and return self.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from builtins.BaseException:
|
| __cause__
| exception cause
|
| __context__
| exception context
|
| __suppress_context__
|
| __traceback__
|
| args
class DataError(DatabaseError)
| DataError(statement: 'Optional[str]', params: 'Optional[_AnyExecuteParams]', orig: 'BaseException', hide_parameters: 'bool' = False, connection_invalidated: 'bool' = False, code: 'Optional[str]' = None, ismulti: 'Optional[bool]' = None)
|
| Wraps a DB-API DataError.
|
| Method resolution order:
| DataError
| DatabaseError
| DBAPIError
| StatementError
| SQLAlchemyError
| HasDescriptionCode
| builtins.Exception
| builtins.BaseException
| builtins.object
|
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| code = '9h9h'
|
| ----------------------------------------------------------------------
| Methods inherited from DBAPIError:
|
| __init__(self, statement: 'Optional[str]', params: 'Optional[_AnyExecuteParams]', orig: 'BaseException', hide_parameters: 'bool' = False, connection_invalidated: 'bool' = False, code: 'Optional[str]' = None, ismulti: 'Optional[bool]' = None)
| Initialize self. See help(type(self)) for accurate signature.
|
| __reduce__(self) -> 'Union[str, Tuple[Any, ...]]'
| Helper for pickle.
|
| ----------------------------------------------------------------------
| Class methods inherited from DBAPIError:
|
| instance(statement: 'Optional[str]', params: 'Optional[_AnyExecuteParams]', orig: 'Union[BaseException, DontWrapMixin]', dbapi_base_err: 'Type[Exception]', hide_parameters: 'bool' = False, connection_invalidated: 'bool' = False, dialect: 'Optional[Dialect]' = None, ismulti: 'Optional[bool]' = None) -> 'Union[BaseException, DontWrapMixin]'
|
| ----------------------------------------------------------------------
| Methods inherited from StatementError:
|
| add_detail(self, msg: 'str') -> 'None'
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from StatementError:
|
| connection_invalidated = False
|
| ismulti = None
|
| orig = None
|
| params = None
|
| statement = None
|
| ----------------------------------------------------------------------
| Methods inherited from SQLAlchemyError:
|
| __str__(self) -> 'str'
| Return str(self).
|
| ----------------------------------------------------------------------
| Data descriptors inherited from SQLAlchemyError:
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data descriptors inherited from HasDescriptionCode:
|
| __dict__
| dictionary for instance variables
|
| ----------------------------------------------------------------------
| Static methods inherited from builtins.Exception:
|
| __new__(*args, **kwargs) class method of builtins.Exception
| Create and return a new object. See help(type) for accurate signature.
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.BaseException:
|
| __getattribute__(self, name, /)
| Return getattr(self, name).
|
| __repr__(self, /)
| Return repr(self).
|
| __setstate__(...)
|
| add_note(...)
| Exception.add_note(note) --
| add a note to the exception
|
| with_traceback(...)
| Exception.with_traceback(tb) --
| set self.__traceback__ to tb and return self.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from builtins.BaseException:
|
| __cause__
| exception cause
|
| __context__
| exception context
|
| __suppress_context__
|
| __traceback__
|
| args
class DatabaseError(DBAPIError)
| DatabaseError(statement: 'Optional[str]', params: 'Optional[_AnyExecuteParams]', orig: 'BaseException', hide_parameters: 'bool' = False, connection_invalidated: 'bool' = False, code: 'Optional[str]' = None, ismulti: 'Optional[bool]' = None)
|
| Wraps a DB-API DatabaseError.
|
| Method resolution order:
| DatabaseError
| DBAPIError
| StatementError
| SQLAlchemyError
| HasDescriptionCode
| builtins.Exception
| builtins.BaseException
| builtins.object
|
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| code = '4xp6'
|
| ----------------------------------------------------------------------
| Methods inherited from DBAPIError:
|
| __init__(self, statement: 'Optional[str]', params: 'Optional[_AnyExecuteParams]', orig: 'BaseException', hide_parameters: 'bool' = False, connection_invalidated: 'bool' = False, code: 'Optional[str]' = None, ismulti: 'Optional[bool]' = None)
| Initialize self. See help(type(self)) for accurate signature.
|
| __reduce__(self) -> 'Union[str, Tuple[Any, ...]]'
| Helper for pickle.
|
| ----------------------------------------------------------------------
| Class methods inherited from DBAPIError:
|
| instance(statement: 'Optional[str]', params: 'Optional[_AnyExecuteParams]', orig: 'Union[BaseException, DontWrapMixin]', dbapi_base_err: 'Type[Exception]', hide_parameters: 'bool' = False, connection_invalidated: 'bool' = False, dialect: 'Optional[Dialect]' = None, ismulti: 'Optional[bool]' = None) -> 'Union[BaseException, DontWrapMixin]'
|
| ----------------------------------------------------------------------
| Methods inherited from StatementError:
|
| add_detail(self, msg: 'str') -> 'None'
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from StatementError:
|
| connection_invalidated = False
|
| ismulti = None
|
| orig = None
|
| params = None
|
| statement = None
|
| ----------------------------------------------------------------------
| Methods inherited from SQLAlchemyError:
|
| __str__(self) -> 'str'
| Return str(self).
|
| ----------------------------------------------------------------------
| Data descriptors inherited from SQLAlchemyError:
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data descriptors inherited from HasDescriptionCode:
|
| __dict__
| dictionary for instance variables
|
| ----------------------------------------------------------------------
| Static methods inherited from builtins.Exception:
|
| __new__(*args, **kwargs) class method of builtins.Exception
| Create and return a new object. See help(type) for accurate signature.
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.BaseException:
|
| __getattribute__(self, name, /)
| Return getattr(self, name).
|
| __repr__(self, /)
| Return repr(self).
|
| __setstate__(...)
|
| add_note(...)
| Exception.add_note(note) --
| add a note to the exception
|
| with_traceback(...)
| Exception.with_traceback(tb) --
| set self.__traceback__ to tb and return self.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from builtins.BaseException:
|
| __cause__
| exception cause
|
| __context__
| exception context
|
| __suppress_context__
|
| __traceback__
|
| args
class DisconnectionError(SQLAlchemyError)
| DisconnectionError(*arg: 'Any', **kw: 'Any')
|
| A disconnect is detected on a raw DB-API connection.
|
| This error is raised and consumed internally by a connection pool. It can
| be raised by the :meth:`_events.PoolEvents.checkout`
| event so that the host pool
| forces a retry; the exception will be caught three times in a row before
| the pool gives up and raises :class:`~sqlalchemy.exc.InvalidRequestError`
| regarding the connection attempt.
|
| Method resolution order:
| DisconnectionError
| SQLAlchemyError
| HasDescriptionCode
| builtins.Exception
| builtins.BaseException
| builtins.object
|
| Data and other attributes defined here:
|
| __annotations__ = {'invalidate_pool': 'bool'}
|
| invalidate_pool = False
|
| ----------------------------------------------------------------------
| Methods inherited from SQLAlchemyError:
|
| __str__(self) -> 'str'
| Return str(self).
|
| ----------------------------------------------------------------------
| Data descriptors inherited from SQLAlchemyError:
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Methods inherited from HasDescriptionCode:
|
| __init__(self, *arg: 'Any', **kw: 'Any')
| Initialize self. See help(type(self)) for accurate signature.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from HasDescriptionCode:
|
| __dict__
| dictionary for instance variables
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from HasDescriptionCode:
|
| code = None
|
| ----------------------------------------------------------------------
| Static methods inherited from builtins.Exception:
|
| __new__(*args, **kwargs) class method of builtins.Exception
| Create and return a new object. See help(type) for accurate signature.
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.BaseException:
|
| __getattribute__(self, name, /)
| Return getattr(self, name).
|
| __reduce__(...)
| Helper for pickle.
|
| __repr__(self, /)
| Return repr(self).
|
| __setstate__(...)
|
| add_note(...)
| Exception.add_note(note) --
| add a note to the exception
|
| with_traceback(...)
| Exception.with_traceback(tb) --
| set self.__traceback__ to tb and return self.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from builtins.BaseException:
|
| __cause__
| exception cause
|
| __context__
| exception context
|
| __suppress_context__
|
| __traceback__
|
| args
class DontWrapMixin(builtins.object)
| A mixin class which, when applied to a user-defined Exception class,
| will not be wrapped inside of :exc:`.StatementError` if the error is
| emitted within the process of executing a statement.
|
| E.g.::
|
| from sqlalchemy.exc import DontWrapMixin
|
|
| class MyCustomException(Exception, DontWrapMixin):
| pass
|
|
| class MySpecialType(TypeDecorator):
| impl = String
|
| def process_bind_param(self, value, dialect):
| if value == "invalid":
| raise MyCustomException("invalid!")
|
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
class DuplicateColumnError(ArgumentError)
| DuplicateColumnError(*arg: 'Any', **kw: 'Any')
|
| a Column is being added to a Table that would replace another
| Column, without appropriate parameters to allow this in place.
|
| .. versionadded:: 2.0.0b4
|
| Method resolution order:
| DuplicateColumnError
| ArgumentError
| SQLAlchemyError
| HasDescriptionCode
| builtins.Exception
| builtins.BaseException
| builtins.object
|
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| ----------------------------------------------------------------------
| Methods inherited from SQLAlchemyError:
|
| __str__(self) -> 'str'
| Return str(self).
|
| ----------------------------------------------------------------------
| Data descriptors inherited from SQLAlchemyError:
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Methods inherited from HasDescriptionCode:
|
| __init__(self, *arg: 'Any', **kw: 'Any')
| Initialize self. See help(type(self)) for accurate signature.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from HasDescriptionCode:
|
| __dict__
| dictionary for instance variables
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from HasDescriptionCode:
|
| code = None
|
| ----------------------------------------------------------------------
| Static methods inherited from builtins.Exception:
|
| __new__(*args, **kwargs) class method of builtins.Exception
| Create and return a new object. See help(type) for accurate signature.
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.BaseException:
|
| __getattribute__(self, name, /)
| Return getattr(self, name).
|
| __reduce__(...)
| Helper for pickle.
|
| __repr__(self, /)
| Return repr(self).
|
| __setstate__(...)
|
| add_note(...)
| Exception.add_note(note) --
| add a note to the exception
|
| with_traceback(...)
| Exception.with_traceback(tb) --
| set self.__traceback__ to tb and return self.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from builtins.BaseException:
|
| __cause__
| exception cause
|
| __context__
| exception context
|
| __suppress_context__
|
| __traceback__
|
| args
class HasDescriptionCode(builtins.object)
| HasDescriptionCode(*arg: 'Any', **kw: 'Any')
|
| helper which adds 'code' as an attribute and '_code_str' as a method
|
| Methods defined here:
|
| __init__(self, *arg: 'Any', **kw: 'Any')
| Initialize self. See help(type(self)) for accurate signature.
|
| __str__(self) -> 'str'
| Return str(self).
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'code': 'Optional[str]'}
|
| code = None
class IdentifierError(SQLAlchemyError)
| IdentifierError(*arg: 'Any', **kw: 'Any')
|
| Raised when a schema name is beyond the max character limit
|
| Method resolution order:
| IdentifierError
| SQLAlchemyError
| HasDescriptionCode
| builtins.Exception
| builtins.BaseException
| builtins.object
|
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| ----------------------------------------------------------------------
| Methods inherited from SQLAlchemyError:
|
| __str__(self) -> 'str'
| Return str(self).
|
| ----------------------------------------------------------------------
| Data descriptors inherited from SQLAlchemyError:
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Methods inherited from HasDescriptionCode:
|
| __init__(self, *arg: 'Any', **kw: 'Any')
| Initialize self. See help(type(self)) for accurate signature.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from HasDescriptionCode:
|
| __dict__
| dictionary for instance variables
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from HasDescriptionCode:
|
| code = None
|
| ----------------------------------------------------------------------
| Static methods inherited from builtins.Exception:
|
| __new__(*args, **kwargs) class method of builtins.Exception
| Create and return a new object. See help(type) for accurate signature.
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.BaseException:
|
| __getattribute__(self, name, /)
| Return getattr(self, name).
|
| __reduce__(...)
| Helper for pickle.
|
| __repr__(self, /)
| Return repr(self).
|
| __setstate__(...)
|
| add_note(...)
| Exception.add_note(note) --
| add a note to the exception
|
| with_traceback(...)
| Exception.with_traceback(tb) --
| set self.__traceback__ to tb and return self.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from builtins.BaseException:
|
| __cause__
| exception cause
|
| __context__
| exception context
|
| __suppress_context__
|
| __traceback__
|
| args
class IllegalStateChangeError(InvalidRequestError)
| IllegalStateChangeError(*arg: 'Any', **kw: 'Any')
|
| An object that tracks state encountered an illegal state change
| of some kind.
|
| .. versionadded:: 2.0
|
| Method resolution order:
| IllegalStateChangeError
| InvalidRequestError
| SQLAlchemyError
| HasDescriptionCode
| builtins.Exception
| builtins.BaseException
| builtins.object
|
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| ----------------------------------------------------------------------
| Methods inherited from SQLAlchemyError:
|
| __str__(self) -> 'str'
| Return str(self).
|
| ----------------------------------------------------------------------
| Data descriptors inherited from SQLAlchemyError:
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Methods inherited from HasDescriptionCode:
|
| __init__(self, *arg: 'Any', **kw: 'Any')
| Initialize self. See help(type(self)) for accurate signature.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from HasDescriptionCode:
|
| __dict__
| dictionary for instance variables
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from HasDescriptionCode:
|
| code = None
|
| ----------------------------------------------------------------------
| Static methods inherited from builtins.Exception:
|
| __new__(*args, **kwargs) class method of builtins.Exception
| Create and return a new object. See help(type) for accurate signature.
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.BaseException:
|
| __getattribute__(self, name, /)
| Return getattr(self, name).
|
| __reduce__(...)
| Helper for pickle.
|
| __repr__(self, /)
| Return repr(self).
|
| __setstate__(...)
|
| add_note(...)
| Exception.add_note(note) --
| add a note to the exception
|
| with_traceback(...)
| Exception.with_traceback(tb) --
| set self.__traceback__ to tb and return self.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from builtins.BaseException:
|
| __cause__
| exception cause
|
| __context__
| exception context
|
| __suppress_context__
|
| __traceback__
|
| args
class IntegrityError(DatabaseError)
| IntegrityError(statement: 'Optional[str]', params: 'Optional[_AnyExecuteParams]', orig: 'BaseException', hide_parameters: 'bool' = False, connection_invalidated: 'bool' = False, code: 'Optional[str]' = None, ismulti: 'Optional[bool]' = None)
|
| Wraps a DB-API IntegrityError.
|
| Method resolution order:
| IntegrityError
| DatabaseError
| DBAPIError
| StatementError
| SQLAlchemyError
| HasDescriptionCode
| builtins.Exception
| builtins.BaseException
| builtins.object
|
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| code = 'gkpj'
|
| ----------------------------------------------------------------------
| Methods inherited from DBAPIError:
|
| __init__(self, statement: 'Optional[str]', params: 'Optional[_AnyExecuteParams]', orig: 'BaseException', hide_parameters: 'bool' = False, connection_invalidated: 'bool' = False, code: 'Optional[str]' = None, ismulti: 'Optional[bool]' = None)
| Initialize self. See help(type(self)) for accurate signature.
|
| __reduce__(self) -> 'Union[str, Tuple[Any, ...]]'
| Helper for pickle.
|
| ----------------------------------------------------------------------
| Class methods inherited from DBAPIError:
|
| instance(statement: 'Optional[str]', params: 'Optional[_AnyExecuteParams]', orig: 'Union[BaseException, DontWrapMixin]', dbapi_base_err: 'Type[Exception]', hide_parameters: 'bool' = False, connection_invalidated: 'bool' = False, dialect: 'Optional[Dialect]' = None, ismulti: 'Optional[bool]' = None) -> 'Union[BaseException, DontWrapMixin]'
|
| ----------------------------------------------------------------------
| Methods inherited from StatementError:
|
| add_detail(self, msg: 'str') -> 'None'
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from StatementError:
|
| connection_invalidated = False
|
| ismulti = None
|
| orig = None
|
| params = None
|
| statement = None
|
| ----------------------------------------------------------------------
| Methods inherited from SQLAlchemyError:
|
| __str__(self) -> 'str'
| Return str(self).
|
| ----------------------------------------------------------------------
| Data descriptors inherited from SQLAlchemyError:
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data descriptors inherited from HasDescriptionCode:
|
| __dict__
| dictionary for instance variables
|
| ----------------------------------------------------------------------
| Static methods inherited from builtins.Exception:
|
| __new__(*args, **kwargs) class method of builtins.Exception
| Create and return a new object. See help(type) for accurate signature.
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.BaseException:
|
| __getattribute__(self, name, /)
| Return getattr(self, name).
|
| __repr__(self, /)
| Return repr(self).
|
| __setstate__(...)
|
| add_note(...)
| Exception.add_note(note) --
| add a note to the exception
|
| with_traceback(...)
| Exception.with_traceback(tb) --
| set self.__traceback__ to tb and return self.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from builtins.BaseException:
|
| __cause__
| exception cause
|
| __context__
| exception context
|
| __suppress_context__
|
| __traceback__
|
| args
class InterfaceError(DBAPIError)
| InterfaceError(statement: 'Optional[str]', params: 'Optional[_AnyExecuteParams]', orig: 'BaseException', hide_parameters: 'bool' = False, connection_invalidated: 'bool' = False, code: 'Optional[str]' = None, ismulti: 'Optional[bool]' = None)
|
| Wraps a DB-API InterfaceError.
|
| Method resolution order:
| InterfaceError
| DBAPIError
| StatementError
| SQLAlchemyError
| HasDescriptionCode
| builtins.Exception
| builtins.BaseException
| builtins.object
|
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| code = 'rvf5'
|
| ----------------------------------------------------------------------
| Methods inherited from DBAPIError:
|
| __init__(self, statement: 'Optional[str]', params: 'Optional[_AnyExecuteParams]', orig: 'BaseException', hide_parameters: 'bool' = False, connection_invalidated: 'bool' = False, code: 'Optional[str]' = None, ismulti: 'Optional[bool]' = None)
| Initialize self. See help(type(self)) for accurate signature.
|
| __reduce__(self) -> 'Union[str, Tuple[Any, ...]]'
| Helper for pickle.
|
| ----------------------------------------------------------------------
| Class methods inherited from DBAPIError:
|
| instance(statement: 'Optional[str]', params: 'Optional[_AnyExecuteParams]', orig: 'Union[BaseException, DontWrapMixin]', dbapi_base_err: 'Type[Exception]', hide_parameters: 'bool' = False, connection_invalidated: 'bool' = False, dialect: 'Optional[Dialect]' = None, ismulti: 'Optional[bool]' = None) -> 'Union[BaseException, DontWrapMixin]'
|
| ----------------------------------------------------------------------
| Methods inherited from StatementError:
|
| add_detail(self, msg: 'str') -> 'None'
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from StatementError:
|
| connection_invalidated = False
|
| ismulti = None
|
| orig = None
|
| params = None
|
| statement = None
|
| ----------------------------------------------------------------------
| Methods inherited from SQLAlchemyError:
|
| __str__(self) -> 'str'
| Return str(self).
|
| ----------------------------------------------------------------------
| Data descriptors inherited from SQLAlchemyError:
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data descriptors inherited from HasDescriptionCode:
|
| __dict__
| dictionary for instance variables
|
| ----------------------------------------------------------------------
| Static methods inherited from builtins.Exception:
|
| __new__(*args, **kwargs) class method of builtins.Exception
| Create and return a new object. See help(type) for accurate signature.
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.BaseException:
|
| __getattribute__(self, name, /)
| Return getattr(self, name).
|
| __repr__(self, /)
| Return repr(self).
|
| __setstate__(...)
|
| add_note(...)
| Exception.add_note(note) --
| add a note to the exception
|
| with_traceback(...)
| Exception.with_traceback(tb) --
| set self.__traceback__ to tb and return self.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from builtins.BaseException:
|
| __cause__
| exception cause
|
| __context__
| exception context
|
| __suppress_context__
|
| __traceback__
|
| args
class InternalError(DatabaseError)
| InternalError(statement: 'Optional[str]', params: 'Optional[_AnyExecuteParams]', orig: 'BaseException', hide_parameters: 'bool' = False, connection_invalidated: 'bool' = False, code: 'Optional[str]' = None, ismulti: 'Optional[bool]' = None)
|
| Wraps a DB-API InternalError.
|
| Method resolution order:
| InternalError
| DatabaseError
| DBAPIError
| StatementError
| SQLAlchemyError
| HasDescriptionCode
| builtins.Exception
| builtins.BaseException
| builtins.object
|
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| code = '2j85'
|
| ----------------------------------------------------------------------
| Methods inherited from DBAPIError:
|
| __init__(self, statement: 'Optional[str]', params: 'Optional[_AnyExecuteParams]', orig: 'BaseException', hide_parameters: 'bool' = False, connection_invalidated: 'bool' = False, code: 'Optional[str]' = None, ismulti: 'Optional[bool]' = None)
| Initialize self. See help(type(self)) for accurate signature.
|
| __reduce__(self) -> 'Union[str, Tuple[Any, ...]]'
| Helper for pickle.
|
| ----------------------------------------------------------------------
| Class methods inherited from DBAPIError:
|
| instance(statement: 'Optional[str]', params: 'Optional[_AnyExecuteParams]', orig: 'Union[BaseException, DontWrapMixin]', dbapi_base_err: 'Type[Exception]', hide_parameters: 'bool' = False, connection_invalidated: 'bool' = False, dialect: 'Optional[Dialect]' = None, ismulti: 'Optional[bool]' = None) -> 'Union[BaseException, DontWrapMixin]'
|
| ----------------------------------------------------------------------
| Methods inherited from StatementError:
|
| add_detail(self, msg: 'str') -> 'None'
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from StatementError:
|
| connection_invalidated = False
|
| ismulti = None
|
| orig = None
|
| params = None
|
| statement = None
|
| ----------------------------------------------------------------------
| Methods inherited from SQLAlchemyError:
|
| __str__(self) -> 'str'
| Return str(self).
|
| ----------------------------------------------------------------------
| Data descriptors inherited from SQLAlchemyError:
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data descriptors inherited from HasDescriptionCode:
|
| __dict__
| dictionary for instance variables
|
| ----------------------------------------------------------------------
| Static methods inherited from builtins.Exception:
|
| __new__(*args, **kwargs) class method of builtins.Exception
| Create and return a new object. See help(type) for accurate signature.
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.BaseException:
|
| __getattribute__(self, name, /)
| Return getattr(self, name).
|
| __repr__(self, /)
| Return repr(self).
|
| __setstate__(...)
|
| add_note(...)
| Exception.add_note(note) --
| add a note to the exception
|
| with_traceback(...)
| Exception.with_traceback(tb) --
| set self.__traceback__ to tb and return self.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from builtins.BaseException:
|
| __cause__
| exception cause
|
| __context__
| exception context
|
| __suppress_context__
|
| __traceback__
|
| args
class InvalidRequestError(SQLAlchemyError)
| InvalidRequestError(*arg: 'Any', **kw: 'Any')
|
| SQLAlchemy was asked to do something it can't do.
|
| This error generally corresponds to runtime state errors.
|
| Method resolution order:
| InvalidRequestError
| SQLAlchemyError
| HasDescriptionCode
| builtins.Exception
| builtins.BaseException
| builtins.object
|
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| ----------------------------------------------------------------------
| Methods inherited from SQLAlchemyError:
|
| __str__(self) -> 'str'
| Return str(self).
|
| ----------------------------------------------------------------------
| Data descriptors inherited from SQLAlchemyError:
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Methods inherited from HasDescriptionCode:
|
| __init__(self, *arg: 'Any', **kw: 'Any')
| Initialize self. See help(type(self)) for accurate signature.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from HasDescriptionCode:
|
| __dict__
| dictionary for instance variables
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from HasDescriptionCode:
|
| code = None
|
| ----------------------------------------------------------------------
| Static methods inherited from builtins.Exception:
|
| __new__(*args, **kwargs) class method of builtins.Exception
| Create and return a new object. See help(type) for accurate signature.
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.BaseException:
|
| __getattribute__(self, name, /)
| Return getattr(self, name).
|
| __reduce__(...)
| Helper for pickle.
|
| __repr__(self, /)
| Return repr(self).
|
| __setstate__(...)
|
| add_note(...)
| Exception.add_note(note) --
| add a note to the exception
|
| with_traceback(...)
| Exception.with_traceback(tb) --
| set self.__traceback__ to tb and return self.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from builtins.BaseException:
|
| __cause__
| exception cause
|
| __context__
| exception context
|
| __suppress_context__
|
| __traceback__
|
| args
class InvalidatePoolError(DisconnectionError)
| InvalidatePoolError(*arg: 'Any', **kw: 'Any')
|
| Raised when the connection pool should invalidate all stale connections.
|
| A subclass of :class:`_exc.DisconnectionError` that indicates that the
| disconnect situation encountered on the connection probably means the
| entire pool should be invalidated, as the database has been restarted.
|
| This exception will be handled otherwise the same way as
| :class:`_exc.DisconnectionError`, allowing three attempts to reconnect
| before giving up.
|
| .. versionadded:: 1.2
|
| Method resolution order:
| InvalidatePoolError
| DisconnectionError
| SQLAlchemyError
| HasDescriptionCode
| builtins.Exception
| builtins.BaseException
| builtins.object
|
| Data and other attributes defined here:
|
| __annotations__ = {'invalidate_pool': 'bool'}
|
| invalidate_pool = True
|
| ----------------------------------------------------------------------
| Methods inherited from SQLAlchemyError:
|
| __str__(self) -> 'str'
| Return str(self).
|
| ----------------------------------------------------------------------
| Data descriptors inherited from SQLAlchemyError:
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Methods inherited from HasDescriptionCode:
|
| __init__(self, *arg: 'Any', **kw: 'Any')
| Initialize self. See help(type(self)) for accurate signature.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from HasDescriptionCode:
|
| __dict__
| dictionary for instance variables
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from HasDescriptionCode:
|
| code = None
|
| ----------------------------------------------------------------------
| Static methods inherited from builtins.Exception:
|
| __new__(*args, **kwargs) class method of builtins.Exception
| Create and return a new object. See help(type) for accurate signature.
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.BaseException:
|
| __getattribute__(self, name, /)
| Return getattr(self, name).
|
| __reduce__(...)
| Helper for pickle.
|
| __repr__(self, /)
| Return repr(self).
|
| __setstate__(...)
|
| add_note(...)
| Exception.add_note(note) --
| add a note to the exception
|
| with_traceback(...)
| Exception.with_traceback(tb) --
| set self.__traceback__ to tb and return self.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from builtins.BaseException:
|
| __cause__
| exception cause
|
| __context__
| exception context
|
| __suppress_context__
|
| __traceback__
|
| args
class LegacyAPIWarning(Base20DeprecationWarning)
| LegacyAPIWarning(*arg: 'Any', **kw: 'Any')
|
| indicates an API that is in 'legacy' status, a long term deprecation.
|
| Method resolution order:
| LegacyAPIWarning
| Base20DeprecationWarning
| SADeprecationWarning
| HasDescriptionCode
| builtins.DeprecationWarning
| builtins.Warning
| builtins.Exception
| builtins.BaseException
| builtins.object
|
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| ----------------------------------------------------------------------
| Methods inherited from Base20DeprecationWarning:
|
| __str__(self) -> 'str'
| Return str(self).
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from Base20DeprecationWarning:
|
| deprecated_since = '1.4'
|
| ----------------------------------------------------------------------
| Data descriptors inherited from SADeprecationWarning:
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Methods inherited from HasDescriptionCode:
|
| __init__(self, *arg: 'Any', **kw: 'Any')
| Initialize self. See help(type(self)) for accurate signature.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from HasDescriptionCode:
|
| __dict__
| dictionary for instance variables
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from HasDescriptionCode:
|
| code = None
|
| ----------------------------------------------------------------------
| Static methods inherited from builtins.DeprecationWarning:
|
| __new__(*args, **kwargs) class method of builtins.DeprecationWarning
| Create and return a new object. See help(type) for accurate signature.
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.BaseException:
|
| __getattribute__(self, name, /)
| Return getattr(self, name).
|
| __reduce__(...)
| Helper for pickle.
|
| __repr__(self, /)
| Return repr(self).
|
| __setstate__(...)
|
| add_note(...)
| Exception.add_note(note) --
| add a note to the exception
|
| with_traceback(...)
| Exception.with_traceback(tb) --
| set self.__traceback__ to tb and return self.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from builtins.BaseException:
|
| __cause__
| exception cause
|
| __context__
| exception context
|
| __suppress_context__
|
| __traceback__
|
| args
class MissingGreenlet(InvalidRequestError)
| MissingGreenlet(*arg: 'Any', **kw: 'Any')
|
| Error raised by the async greenlet await\_ if called while not inside
| the greenlet spawn context.
|
| Method resolution order:
| MissingGreenlet
| InvalidRequestError
| SQLAlchemyError
| HasDescriptionCode
| builtins.Exception
| builtins.BaseException
| builtins.object
|
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| code = 'xd2s'
|
| ----------------------------------------------------------------------
| Methods inherited from SQLAlchemyError:
|
| __str__(self) -> 'str'
| Return str(self).
|
| ----------------------------------------------------------------------
| Data descriptors inherited from SQLAlchemyError:
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Methods inherited from HasDescriptionCode:
|
| __init__(self, *arg: 'Any', **kw: 'Any')
| Initialize self. See help(type(self)) for accurate signature.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from HasDescriptionCode:
|
| __dict__
| dictionary for instance variables
|
| ----------------------------------------------------------------------
| Static methods inherited from builtins.Exception:
|
| __new__(*args, **kwargs) class method of builtins.Exception
| Create and return a new object. See help(type) for accurate signature.
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.BaseException:
|
| __getattribute__(self, name, /)
| Return getattr(self, name).
|
| __reduce__(...)
| Helper for pickle.
|
| __repr__(self, /)
| Return repr(self).
|
| __setstate__(...)
|
| add_note(...)
| Exception.add_note(note) --
| add a note to the exception
|
| with_traceback(...)
| Exception.with_traceback(tb) --
| set self.__traceback__ to tb and return self.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from builtins.BaseException:
|
| __cause__
| exception cause
|
| __context__
| exception context
|
| __suppress_context__
|
| __traceback__
|
| args
class MovedIn20Warning(Base20DeprecationWarning)
| MovedIn20Warning(*arg: 'Any', **kw: 'Any')
|
| Subtype of RemovedIn20Warning to indicate an API that moved only.
|
| Method resolution order:
| MovedIn20Warning
| Base20DeprecationWarning
| SADeprecationWarning
| HasDescriptionCode
| builtins.DeprecationWarning
| builtins.Warning
| builtins.Exception
| builtins.BaseException
| builtins.object
|
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| ----------------------------------------------------------------------
| Methods inherited from Base20DeprecationWarning:
|
| __str__(self) -> 'str'
| Return str(self).
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from Base20DeprecationWarning:
|
| deprecated_since = '1.4'
|
| ----------------------------------------------------------------------
| Data descriptors inherited from SADeprecationWarning:
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Methods inherited from HasDescriptionCode:
|
| __init__(self, *arg: 'Any', **kw: 'Any')
| Initialize self. See help(type(self)) for accurate signature.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from HasDescriptionCode:
|
| __dict__
| dictionary for instance variables
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from HasDescriptionCode:
|
| code = None
|
| ----------------------------------------------------------------------
| Static methods inherited from builtins.DeprecationWarning:
|
| __new__(*args, **kwargs) class method of builtins.DeprecationWarning
| Create and return a new object. See help(type) for accurate signature.
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.BaseException:
|
| __getattribute__(self, name, /)
| Return getattr(self, name).
|
| __reduce__(...)
| Helper for pickle.
|
| __repr__(self, /)
| Return repr(self).
|
| __setstate__(...)
|
| add_note(...)
| Exception.add_note(note) --
| add a note to the exception
|
| with_traceback(...)
| Exception.with_traceback(tb) --
| set self.__traceback__ to tb and return self.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from builtins.BaseException:
|
| __cause__
| exception cause
|
| __context__
| exception context
|
| __suppress_context__
|
| __traceback__
|
| args
class MultipleResultsFound(InvalidRequestError)
| MultipleResultsFound(*arg: 'Any', **kw: 'Any')
|
| A single database result was required but more than one were found.
|
| .. versionchanged:: 1.4 This exception is now part of the
| ``sqlalchemy.exc`` module in Core, moved from the ORM. The symbol
| remains importable from ``sqlalchemy.orm.exc``.
|
| Method resolution order:
| MultipleResultsFound
| InvalidRequestError
| SQLAlchemyError
| HasDescriptionCode
| builtins.Exception
| builtins.BaseException
| builtins.object
|
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| ----------------------------------------------------------------------
| Methods inherited from SQLAlchemyError:
|
| __str__(self) -> 'str'
| Return str(self).
|
| ----------------------------------------------------------------------
| Data descriptors inherited from SQLAlchemyError:
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Methods inherited from HasDescriptionCode:
|
| __init__(self, *arg: 'Any', **kw: 'Any')
| Initialize self. See help(type(self)) for accurate signature.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from HasDescriptionCode:
|
| __dict__
| dictionary for instance variables
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from HasDescriptionCode:
|
| code = None
|
| ----------------------------------------------------------------------
| Static methods inherited from builtins.Exception:
|
| __new__(*args, **kwargs) class method of builtins.Exception
| Create and return a new object. See help(type) for accurate signature.
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.BaseException:
|
| __getattribute__(self, name, /)
| Return getattr(self, name).
|
| __reduce__(...)
| Helper for pickle.
|
| __repr__(self, /)
| Return repr(self).
|
| __setstate__(...)
|
| add_note(...)
| Exception.add_note(note) --
| add a note to the exception
|
| with_traceback(...)
| Exception.with_traceback(tb) --
| set self.__traceback__ to tb and return self.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from builtins.BaseException:
|
| __cause__
| exception cause
|
| __context__
| exception context
|
| __suppress_context__
|
| __traceback__
|
| args
class NoForeignKeysError(ArgumentError)
| NoForeignKeysError(*arg: 'Any', **kw: 'Any')
|
| Raised when no foreign keys can be located between two selectables
| during a join.
|
| Method resolution order:
| NoForeignKeysError
| ArgumentError
| SQLAlchemyError
| HasDescriptionCode
| builtins.Exception
| builtins.BaseException
| builtins.object
|
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| ----------------------------------------------------------------------
| Methods inherited from SQLAlchemyError:
|
| __str__(self) -> 'str'
| Return str(self).
|
| ----------------------------------------------------------------------
| Data descriptors inherited from SQLAlchemyError:
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Methods inherited from HasDescriptionCode:
|
| __init__(self, *arg: 'Any', **kw: 'Any')
| Initialize self. See help(type(self)) for accurate signature.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from HasDescriptionCode:
|
| __dict__
| dictionary for instance variables
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from HasDescriptionCode:
|
| code = None
|
| ----------------------------------------------------------------------
| Static methods inherited from builtins.Exception:
|
| __new__(*args, **kwargs) class method of builtins.Exception
| Create and return a new object. See help(type) for accurate signature.
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.BaseException:
|
| __getattribute__(self, name, /)
| Return getattr(self, name).
|
| __reduce__(...)
| Helper for pickle.
|
| __repr__(self, /)
| Return repr(self).
|
| __setstate__(...)
|
| add_note(...)
| Exception.add_note(note) --
| add a note to the exception
|
| with_traceback(...)
| Exception.with_traceback(tb) --
| set self.__traceback__ to tb and return self.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from builtins.BaseException:
|
| __cause__
| exception cause
|
| __context__
| exception context
|
| __suppress_context__
|
| __traceback__
|
| args
class NoInspectionAvailable(InvalidRequestError)
| NoInspectionAvailable(*arg: 'Any', **kw: 'Any')
|
| A subject passed to :func:`sqlalchemy.inspection.inspect` produced
| no context for inspection.
|
| Method resolution order:
| NoInspectionAvailable
| InvalidRequestError
| SQLAlchemyError
| HasDescriptionCode
| builtins.Exception
| builtins.BaseException
| builtins.object
|
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| ----------------------------------------------------------------------
| Methods inherited from SQLAlchemyError:
|
| __str__(self) -> 'str'
| Return str(self).
|
| ----------------------------------------------------------------------
| Data descriptors inherited from SQLAlchemyError:
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Methods inherited from HasDescriptionCode:
|
| __init__(self, *arg: 'Any', **kw: 'Any')
| Initialize self. See help(type(self)) for accurate signature.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from HasDescriptionCode:
|
| __dict__
| dictionary for instance variables
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from HasDescriptionCode:
|
| code = None
|
| ----------------------------------------------------------------------
| Static methods inherited from builtins.Exception:
|
| __new__(*args, **kwargs) class method of builtins.Exception
| Create and return a new object. See help(type) for accurate signature.
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.BaseException:
|
| __getattribute__(self, name, /)
| Return getattr(self, name).
|
| __reduce__(...)
| Helper for pickle.
|
| __repr__(self, /)
| Return repr(self).
|
| __setstate__(...)
|
| add_note(...)
| Exception.add_note(note) --
| add a note to the exception
|
| with_traceback(...)
| Exception.with_traceback(tb) --
| set self.__traceback__ to tb and return self.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from builtins.BaseException:
|
| __cause__
| exception cause
|
| __context__
| exception context
|
| __suppress_context__
|
| __traceback__
|
| args
class NoReferenceError(InvalidRequestError)
| NoReferenceError(*arg: 'Any', **kw: 'Any')
|
| Raised by ``ForeignKey`` to indicate a reference cannot be resolved.
|
| Method resolution order:
| NoReferenceError
| InvalidRequestError
| SQLAlchemyError
| HasDescriptionCode
| builtins.Exception
| builtins.BaseException
| builtins.object
|
| Data and other attributes defined here:
|
| __annotations__ = {'table_name': 'str'}
|
| ----------------------------------------------------------------------
| Methods inherited from SQLAlchemyError:
|
| __str__(self) -> 'str'
| Return str(self).
|
| ----------------------------------------------------------------------
| Data descriptors inherited from SQLAlchemyError:
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Methods inherited from HasDescriptionCode:
|
| __init__(self, *arg: 'Any', **kw: 'Any')
| Initialize self. See help(type(self)) for accurate signature.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from HasDescriptionCode:
|
| __dict__
| dictionary for instance variables
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from HasDescriptionCode:
|
| code = None
|
| ----------------------------------------------------------------------
| Static methods inherited from builtins.Exception:
|
| __new__(*args, **kwargs) class method of builtins.Exception
| Create and return a new object. See help(type) for accurate signature.
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.BaseException:
|
| __getattribute__(self, name, /)
| Return getattr(self, name).
|
| __reduce__(...)
| Helper for pickle.
|
| __repr__(self, /)
| Return repr(self).
|
| __setstate__(...)
|
| add_note(...)
| Exception.add_note(note) --
| add a note to the exception
|
| with_traceback(...)
| Exception.with_traceback(tb) --
| set self.__traceback__ to tb and return self.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from builtins.BaseException:
|
| __cause__
| exception cause
|
| __context__
| exception context
|
| __suppress_context__
|
| __traceback__
|
| args
class NoReferencedColumnError(NoReferenceError)
| NoReferencedColumnError(message: 'str', tname: 'str', cname: 'str')
|
| Raised by ``ForeignKey`` when the referred ``Column`` cannot be
| located.
|
| Method resolution order:
| NoReferencedColumnError
| NoReferenceError
| InvalidRequestError
| SQLAlchemyError
| HasDescriptionCode
| builtins.Exception
| builtins.BaseException
| builtins.object
|
| Methods defined here:
|
| __init__(self, message: 'str', tname: 'str', cname: 'str')
| Initialize self. See help(type(self)) for accurate signature.
|
| __reduce__(self) -> 'Union[str, Tuple[Any, ...]]'
| Helper for pickle.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| ----------------------------------------------------------------------
| Methods inherited from SQLAlchemyError:
|
| __str__(self) -> 'str'
| Return str(self).
|
| ----------------------------------------------------------------------
| Data descriptors inherited from SQLAlchemyError:
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data descriptors inherited from HasDescriptionCode:
|
| __dict__
| dictionary for instance variables
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from HasDescriptionCode:
|
| code = None
|
| ----------------------------------------------------------------------
| Static methods inherited from builtins.Exception:
|
| __new__(*args, **kwargs) class method of builtins.Exception
| Create and return a new object. See help(type) for accurate signature.
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.BaseException:
|
| __getattribute__(self, name, /)
| Return getattr(self, name).
|
| __repr__(self, /)
| Return repr(self).
|
| __setstate__(...)
|
| add_note(...)
| Exception.add_note(note) --
| add a note to the exception
|
| with_traceback(...)
| Exception.with_traceback(tb) --
| set self.__traceback__ to tb and return self.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from builtins.BaseException:
|
| __cause__
| exception cause
|
| __context__
| exception context
|
| __suppress_context__
|
| __traceback__
|
| args
class NoReferencedTableError(NoReferenceError)
| NoReferencedTableError(message: 'str', tname: 'str')
|
| Raised by ``ForeignKey`` when the referred ``Table`` cannot be
| located.
|
| Method resolution order:
| NoReferencedTableError
| NoReferenceError
| InvalidRequestError
| SQLAlchemyError
| HasDescriptionCode
| builtins.Exception
| builtins.BaseException
| builtins.object
|
| Methods defined here:
|
| __init__(self, message: 'str', tname: 'str')
| Initialize self. See help(type(self)) for accurate signature.
|
| __reduce__(self) -> 'Union[str, Tuple[Any, ...]]'
| Helper for pickle.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| ----------------------------------------------------------------------
| Methods inherited from SQLAlchemyError:
|
| __str__(self) -> 'str'
| Return str(self).
|
| ----------------------------------------------------------------------
| Data descriptors inherited from SQLAlchemyError:
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data descriptors inherited from HasDescriptionCode:
|
| __dict__
| dictionary for instance variables
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from HasDescriptionCode:
|
| code = None
|
| ----------------------------------------------------------------------
| Static methods inherited from builtins.Exception:
|
| __new__(*args, **kwargs) class method of builtins.Exception
| Create and return a new object. See help(type) for accurate signature.
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.BaseException:
|
| __getattribute__(self, name, /)
| Return getattr(self, name).
|
| __repr__(self, /)
| Return repr(self).
|
| __setstate__(...)
|
| add_note(...)
| Exception.add_note(note) --
| add a note to the exception
|
| with_traceback(...)
| Exception.with_traceback(tb) --
| set self.__traceback__ to tb and return self.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from builtins.BaseException:
|
| __cause__
| exception cause
|
| __context__
| exception context
|
| __suppress_context__
|
| __traceback__
|
| args
class NoResultFound(InvalidRequestError)
| NoResultFound(*arg: 'Any', **kw: 'Any')
|
| A database result was required but none was found.
|
|
| .. versionchanged:: 1.4 This exception is now part of the
| ``sqlalchemy.exc`` module in Core, moved from the ORM. The symbol
| remains importable from ``sqlalchemy.orm.exc``.
|
| Method resolution order:
| NoResultFound
| InvalidRequestError
| SQLAlchemyError
| HasDescriptionCode
| builtins.Exception
| builtins.BaseException
| builtins.object
|
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| ----------------------------------------------------------------------
| Methods inherited from SQLAlchemyError:
|
| __str__(self) -> 'str'
| Return str(self).
|
| ----------------------------------------------------------------------
| Data descriptors inherited from SQLAlchemyError:
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Methods inherited from HasDescriptionCode:
|
| __init__(self, *arg: 'Any', **kw: 'Any')
| Initialize self. See help(type(self)) for accurate signature.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from HasDescriptionCode:
|
| __dict__
| dictionary for instance variables
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from HasDescriptionCode:
|
| code = None
|
| ----------------------------------------------------------------------
| Static methods inherited from builtins.Exception:
|
| __new__(*args, **kwargs) class method of builtins.Exception
| Create and return a new object. See help(type) for accurate signature.
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.BaseException:
|
| __getattribute__(self, name, /)
| Return getattr(self, name).
|
| __reduce__(...)
| Helper for pickle.
|
| __repr__(self, /)
| Return repr(self).
|
| __setstate__(...)
|
| add_note(...)
| Exception.add_note(note) --
| add a note to the exception
|
| with_traceback(...)
| Exception.with_traceback(tb) --
| set self.__traceback__ to tb and return self.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from builtins.BaseException:
|
| __cause__
| exception cause
|
| __context__
| exception context
|
| __suppress_context__
|
| __traceback__
|
| args
class NoSuchColumnError(InvalidRequestError, builtins.KeyError)
| NoSuchColumnError(*arg: 'Any', **kw: 'Any')
|
| A nonexistent column is requested from a ``Row``.
|
| Method resolution order:
| NoSuchColumnError
| InvalidRequestError
| SQLAlchemyError
| HasDescriptionCode
| builtins.KeyError
| builtins.LookupError
| builtins.Exception
| builtins.BaseException
| builtins.object
|
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| ----------------------------------------------------------------------
| Methods inherited from SQLAlchemyError:
|
| __str__(self) -> 'str'
| Return str(self).
|
| ----------------------------------------------------------------------
| Data descriptors inherited from SQLAlchemyError:
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Methods inherited from HasDescriptionCode:
|
| __init__(self, *arg: 'Any', **kw: 'Any')
| Initialize self. See help(type(self)) for accurate signature.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from HasDescriptionCode:
|
| __dict__
| dictionary for instance variables
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from HasDescriptionCode:
|
| code = None
|
| ----------------------------------------------------------------------
| Static methods inherited from builtins.LookupError:
|
| __new__(*args, **kwargs) class method of builtins.LookupError
| Create and return a new object. See help(type) for accurate signature.
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.BaseException:
|
| __getattribute__(self, name, /)
| Return getattr(self, name).
|
| __reduce__(...)
| Helper for pickle.
|
| __repr__(self, /)
| Return repr(self).
|
| __setstate__(...)
|
| add_note(...)
| Exception.add_note(note) --
| add a note to the exception
|
| with_traceback(...)
| Exception.with_traceback(tb) --
| set self.__traceback__ to tb and return self.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from builtins.BaseException:
|
| __cause__
| exception cause
|
| __context__
| exception context
|
| __suppress_context__
|
| __traceback__
|
| args
class NoSuchModuleError(ArgumentError)
| NoSuchModuleError(*arg: 'Any', **kw: 'Any')
|
| Raised when a dynamically-loaded module (usually a database dialect)
| of a particular name cannot be located.
|
| Method resolution order:
| NoSuchModuleError
| ArgumentError
| SQLAlchemyError
| HasDescriptionCode
| builtins.Exception
| builtins.BaseException
| builtins.object
|
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| ----------------------------------------------------------------------
| Methods inherited from SQLAlchemyError:
|
| __str__(self) -> 'str'
| Return str(self).
|
| ----------------------------------------------------------------------
| Data descriptors inherited from SQLAlchemyError:
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Methods inherited from HasDescriptionCode:
|
| __init__(self, *arg: 'Any', **kw: 'Any')
| Initialize self. See help(type(self)) for accurate signature.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from HasDescriptionCode:
|
| __dict__
| dictionary for instance variables
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from HasDescriptionCode:
|
| code = None
|
| ----------------------------------------------------------------------
| Static methods inherited from builtins.Exception:
|
| __new__(*args, **kwargs) class method of builtins.Exception
| Create and return a new object. See help(type) for accurate signature.
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.BaseException:
|
| __getattribute__(self, name, /)
| Return getattr(self, name).
|
| __reduce__(...)
| Helper for pickle.
|
| __repr__(self, /)
| Return repr(self).
|
| __setstate__(...)
|
| add_note(...)
| Exception.add_note(note) --
| add a note to the exception
|
| with_traceback(...)
| Exception.with_traceback(tb) --
| set self.__traceback__ to tb and return self.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from builtins.BaseException:
|
| __cause__
| exception cause
|
| __context__
| exception context
|
| __suppress_context__
|
| __traceback__
|
| args
class NoSuchTableError(InvalidRequestError)
| NoSuchTableError(*arg: 'Any', **kw: 'Any')
|
| Table does not exist or is not visible to a connection.
|
| Method resolution order:
| NoSuchTableError
| InvalidRequestError
| SQLAlchemyError
| HasDescriptionCode
| builtins.Exception
| builtins.BaseException
| builtins.object
|
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| ----------------------------------------------------------------------
| Methods inherited from SQLAlchemyError:
|
| __str__(self) -> 'str'
| Return str(self).
|
| ----------------------------------------------------------------------
| Data descriptors inherited from SQLAlchemyError:
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Methods inherited from HasDescriptionCode:
|
| __init__(self, *arg: 'Any', **kw: 'Any')
| Initialize self. See help(type(self)) for accurate signature.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from HasDescriptionCode:
|
| __dict__
| dictionary for instance variables
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from HasDescriptionCode:
|
| code = None
|
| ----------------------------------------------------------------------
| Static methods inherited from builtins.Exception:
|
| __new__(*args, **kwargs) class method of builtins.Exception
| Create and return a new object. See help(type) for accurate signature.
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.BaseException:
|
| __getattribute__(self, name, /)
| Return getattr(self, name).
|
| __reduce__(...)
| Helper for pickle.
|
| __repr__(self, /)
| Return repr(self).
|
| __setstate__(...)
|
| add_note(...)
| Exception.add_note(note) --
| add a note to the exception
|
| with_traceback(...)
| Exception.with_traceback(tb) --
| set self.__traceback__ to tb and return self.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from builtins.BaseException:
|
| __cause__
| exception cause
|
| __context__
| exception context
|
| __suppress_context__
|
| __traceback__
|
| args
class NotSupportedError(DatabaseError)
| NotSupportedError(statement: 'Optional[str]', params: 'Optional[_AnyExecuteParams]', orig: 'BaseException', hide_parameters: 'bool' = False, connection_invalidated: 'bool' = False, code: 'Optional[str]' = None, ismulti: 'Optional[bool]' = None)
|
| Wraps a DB-API NotSupportedError.
|
| Method resolution order:
| NotSupportedError
| DatabaseError
| DBAPIError
| StatementError
| SQLAlchemyError
| HasDescriptionCode
| builtins.Exception
| builtins.BaseException
| builtins.object
|
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| code = 'tw8g'
|
| ----------------------------------------------------------------------
| Methods inherited from DBAPIError:
|
| __init__(self, statement: 'Optional[str]', params: 'Optional[_AnyExecuteParams]', orig: 'BaseException', hide_parameters: 'bool' = False, connection_invalidated: 'bool' = False, code: 'Optional[str]' = None, ismulti: 'Optional[bool]' = None)
| Initialize self. See help(type(self)) for accurate signature.
|
| __reduce__(self) -> 'Union[str, Tuple[Any, ...]]'
| Helper for pickle.
|
| ----------------------------------------------------------------------
| Class methods inherited from DBAPIError:
|
| instance(statement: 'Optional[str]', params: 'Optional[_AnyExecuteParams]', orig: 'Union[BaseException, DontWrapMixin]', dbapi_base_err: 'Type[Exception]', hide_parameters: 'bool' = False, connection_invalidated: 'bool' = False, dialect: 'Optional[Dialect]' = None, ismulti: 'Optional[bool]' = None) -> 'Union[BaseException, DontWrapMixin]'
|
| ----------------------------------------------------------------------
| Methods inherited from StatementError:
|
| add_detail(self, msg: 'str') -> 'None'
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from StatementError:
|
| connection_invalidated = False
|
| ismulti = None
|
| orig = None
|
| params = None
|
| statement = None
|
| ----------------------------------------------------------------------
| Methods inherited from SQLAlchemyError:
|
| __str__(self) -> 'str'
| Return str(self).
|
| ----------------------------------------------------------------------
| Data descriptors inherited from SQLAlchemyError:
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data descriptors inherited from HasDescriptionCode:
|
| __dict__
| dictionary for instance variables
|
| ----------------------------------------------------------------------
| Static methods inherited from builtins.Exception:
|
| __new__(*args, **kwargs) class method of builtins.Exception
| Create and return a new object. See help(type) for accurate signature.
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.BaseException:
|
| __getattribute__(self, name, /)
| Return getattr(self, name).
|
| __repr__(self, /)
| Return repr(self).
|
| __setstate__(...)
|
| add_note(...)
| Exception.add_note(note) --
| add a note to the exception
|
| with_traceback(...)
| Exception.with_traceback(tb) --
| set self.__traceback__ to tb and return self.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from builtins.BaseException:
|
| __cause__
| exception cause
|
| __context__
| exception context
|
| __suppress_context__
|
| __traceback__
|
| args
class ObjectNotExecutableError(ArgumentError)
| ObjectNotExecutableError(target: 'Any')
|
| Raised when an object is passed to .execute() that can't be
| executed as SQL.
|
| Method resolution order:
| ObjectNotExecutableError
| ArgumentError
| SQLAlchemyError
| HasDescriptionCode
| builtins.Exception
| builtins.BaseException
| builtins.object
|
| Methods defined here:
|
| __init__(self, target: 'Any')
| Initialize self. See help(type(self)) for accurate signature.
|
| __reduce__(self) -> 'Union[str, Tuple[Any, ...]]'
| Helper for pickle.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| ----------------------------------------------------------------------
| Methods inherited from SQLAlchemyError:
|
| __str__(self) -> 'str'
| Return str(self).
|
| ----------------------------------------------------------------------
| Data descriptors inherited from SQLAlchemyError:
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data descriptors inherited from HasDescriptionCode:
|
| __dict__
| dictionary for instance variables
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from HasDescriptionCode:
|
| code = None
|
| ----------------------------------------------------------------------
| Static methods inherited from builtins.Exception:
|
| __new__(*args, **kwargs) class method of builtins.Exception
| Create and return a new object. See help(type) for accurate signature.
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.BaseException:
|
| __getattribute__(self, name, /)
| Return getattr(self, name).
|
| __repr__(self, /)
| Return repr(self).
|
| __setstate__(...)
|
| add_note(...)
| Exception.add_note(note) --
| add a note to the exception
|
| with_traceback(...)
| Exception.with_traceback(tb) --
| set self.__traceback__ to tb and return self.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from builtins.BaseException:
|
| __cause__
| exception cause
|
| __context__
| exception context
|
| __suppress_context__
|
| __traceback__
|
| args
class OperationalError(DatabaseError)
| OperationalError(statement: 'Optional[str]', params: 'Optional[_AnyExecuteParams]', orig: 'BaseException', hide_parameters: 'bool' = False, connection_invalidated: 'bool' = False, code: 'Optional[str]' = None, ismulti: 'Optional[bool]' = None)
|
| Wraps a DB-API OperationalError.
|
| Method resolution order:
| OperationalError
| DatabaseError
| DBAPIError
| StatementError
| SQLAlchemyError
| HasDescriptionCode
| builtins.Exception
| builtins.BaseException
| builtins.object
|
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| code = 'e3q8'
|
| ----------------------------------------------------------------------
| Methods inherited from DBAPIError:
|
| __init__(self, statement: 'Optional[str]', params: 'Optional[_AnyExecuteParams]', orig: 'BaseException', hide_parameters: 'bool' = False, connection_invalidated: 'bool' = False, code: 'Optional[str]' = None, ismulti: 'Optional[bool]' = None)
| Initialize self. See help(type(self)) for accurate signature.
|
| __reduce__(self) -> 'Union[str, Tuple[Any, ...]]'
| Helper for pickle.
|
| ----------------------------------------------------------------------
| Class methods inherited from DBAPIError:
|
| instance(statement: 'Optional[str]', params: 'Optional[_AnyExecuteParams]', orig: 'Union[BaseException, DontWrapMixin]', dbapi_base_err: 'Type[Exception]', hide_parameters: 'bool' = False, connection_invalidated: 'bool' = False, dialect: 'Optional[Dialect]' = None, ismulti: 'Optional[bool]' = None) -> 'Union[BaseException, DontWrapMixin]'
|
| ----------------------------------------------------------------------
| Methods inherited from StatementError:
|
| add_detail(self, msg: 'str') -> 'None'
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from StatementError:
|
| connection_invalidated = False
|
| ismulti = None
|
| orig = None
|
| params = None
|
| statement = None
|
| ----------------------------------------------------------------------
| Methods inherited from SQLAlchemyError:
|
| __str__(self) -> 'str'
| Return str(self).
|
| ----------------------------------------------------------------------
| Data descriptors inherited from SQLAlchemyError:
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data descriptors inherited from HasDescriptionCode:
|
| __dict__
| dictionary for instance variables
|
| ----------------------------------------------------------------------
| Static methods inherited from builtins.Exception:
|
| __new__(*args, **kwargs) class method of builtins.Exception
| Create and return a new object. See help(type) for accurate signature.
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.BaseException:
|
| __getattribute__(self, name, /)
| Return getattr(self, name).
|
| __repr__(self, /)
| Return repr(self).
|
| __setstate__(...)
|
| add_note(...)
| Exception.add_note(note) --
| add a note to the exception
|
| with_traceback(...)
| Exception.with_traceback(tb) --
| set self.__traceback__ to tb and return self.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from builtins.BaseException:
|
| __cause__
| exception cause
|
| __context__
| exception context
|
| __suppress_context__
|
| __traceback__
|
| args
class PendingRollbackError(InvalidRequestError)
| PendingRollbackError(*arg: 'Any', **kw: 'Any')
|
| A transaction has failed and needs to be rolled back before
| continuing.
|
| .. versionadded:: 1.4
|
| Method resolution order:
| PendingRollbackError
| InvalidRequestError
| SQLAlchemyError
| HasDescriptionCode
| builtins.Exception
| builtins.BaseException
| builtins.object
|
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| ----------------------------------------------------------------------
| Methods inherited from SQLAlchemyError:
|
| __str__(self) -> 'str'
| Return str(self).
|
| ----------------------------------------------------------------------
| Data descriptors inherited from SQLAlchemyError:
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Methods inherited from HasDescriptionCode:
|
| __init__(self, *arg: 'Any', **kw: 'Any')
| Initialize self. See help(type(self)) for accurate signature.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from HasDescriptionCode:
|
| __dict__
| dictionary for instance variables
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from HasDescriptionCode:
|
| code = None
|
| ----------------------------------------------------------------------
| Static methods inherited from builtins.Exception:
|
| __new__(*args, **kwargs) class method of builtins.Exception
| Create and return a new object. See help(type) for accurate signature.
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.BaseException:
|
| __getattribute__(self, name, /)
| Return getattr(self, name).
|
| __reduce__(...)
| Helper for pickle.
|
| __repr__(self, /)
| Return repr(self).
|
| __setstate__(...)
|
| add_note(...)
| Exception.add_note(note) --
| add a note to the exception
|
| with_traceback(...)
| Exception.with_traceback(tb) --
| set self.__traceback__ to tb and return self.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from builtins.BaseException:
|
| __cause__
| exception cause
|
| __context__
| exception context
|
| __suppress_context__
|
| __traceback__
|
| args
class ProgrammingError(DatabaseError)
| ProgrammingError(statement: 'Optional[str]', params: 'Optional[_AnyExecuteParams]', orig: 'BaseException', hide_parameters: 'bool' = False, connection_invalidated: 'bool' = False, code: 'Optional[str]' = None, ismulti: 'Optional[bool]' = None)
|
| Wraps a DB-API ProgrammingError.
|
| Method resolution order:
| ProgrammingError
| DatabaseError
| DBAPIError
| StatementError
| SQLAlchemyError
| HasDescriptionCode
| builtins.Exception
| builtins.BaseException
| builtins.object
|
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| code = 'f405'
|
| ----------------------------------------------------------------------
| Methods inherited from DBAPIError:
|
| __init__(self, statement: 'Optional[str]', params: 'Optional[_AnyExecuteParams]', orig: 'BaseException', hide_parameters: 'bool' = False, connection_invalidated: 'bool' = False, code: 'Optional[str]' = None, ismulti: 'Optional[bool]' = None)
| Initialize self. See help(type(self)) for accurate signature.
|
| __reduce__(self) -> 'Union[str, Tuple[Any, ...]]'
| Helper for pickle.
|
| ----------------------------------------------------------------------
| Class methods inherited from DBAPIError:
|
| instance(statement: 'Optional[str]', params: 'Optional[_AnyExecuteParams]', orig: 'Union[BaseException, DontWrapMixin]', dbapi_base_err: 'Type[Exception]', hide_parameters: 'bool' = False, connection_invalidated: 'bool' = False, dialect: 'Optional[Dialect]' = None, ismulti: 'Optional[bool]' = None) -> 'Union[BaseException, DontWrapMixin]'
|
| ----------------------------------------------------------------------
| Methods inherited from StatementError:
|
| add_detail(self, msg: 'str') -> 'None'
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from StatementError:
|
| connection_invalidated = False
|
| ismulti = None
|
| orig = None
|
| params = None
|
| statement = None
|
| ----------------------------------------------------------------------
| Methods inherited from SQLAlchemyError:
|
| __str__(self) -> 'str'
| Return str(self).
|
| ----------------------------------------------------------------------
| Data descriptors inherited from SQLAlchemyError:
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data descriptors inherited from HasDescriptionCode:
|
| __dict__
| dictionary for instance variables
|
| ----------------------------------------------------------------------
| Static methods inherited from builtins.Exception:
|
| __new__(*args, **kwargs) class method of builtins.Exception
| Create and return a new object. See help(type) for accurate signature.
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.BaseException:
|
| __getattribute__(self, name, /)
| Return getattr(self, name).
|
| __repr__(self, /)
| Return repr(self).
|
| __setstate__(...)
|
| add_note(...)
| Exception.add_note(note) --
| add a note to the exception
|
| with_traceback(...)
| Exception.with_traceback(tb) --
| set self.__traceback__ to tb and return self.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from builtins.BaseException:
|
| __cause__
| exception cause
|
| __context__
| exception context
|
| __suppress_context__
|
| __traceback__
|
| args
class ResourceClosedError(InvalidRequestError)
| ResourceClosedError(*arg: 'Any', **kw: 'Any')
|
| An operation was requested from a connection, cursor, or other
| object that's in a closed state.
|
| Method resolution order:
| ResourceClosedError
| InvalidRequestError
| SQLAlchemyError
| HasDescriptionCode
| builtins.Exception
| builtins.BaseException
| builtins.object
|
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| ----------------------------------------------------------------------
| Methods inherited from SQLAlchemyError:
|
| __str__(self) -> 'str'
| Return str(self).
|
| ----------------------------------------------------------------------
| Data descriptors inherited from SQLAlchemyError:
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Methods inherited from HasDescriptionCode:
|
| __init__(self, *arg: 'Any', **kw: 'Any')
| Initialize self. See help(type(self)) for accurate signature.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from HasDescriptionCode:
|
| __dict__
| dictionary for instance variables
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from HasDescriptionCode:
|
| code = None
|
| ----------------------------------------------------------------------
| Static methods inherited from builtins.Exception:
|
| __new__(*args, **kwargs) class method of builtins.Exception
| Create and return a new object. See help(type) for accurate signature.
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.BaseException:
|
| __getattribute__(self, name, /)
| Return getattr(self, name).
|
| __reduce__(...)
| Helper for pickle.
|
| __repr__(self, /)
| Return repr(self).
|
| __setstate__(...)
|
| add_note(...)
| Exception.add_note(note) --
| add a note to the exception
|
| with_traceback(...)
| Exception.with_traceback(tb) --
| set self.__traceback__ to tb and return self.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from builtins.BaseException:
|
| __cause__
| exception cause
|
| __context__
| exception context
|
| __suppress_context__
|
| __traceback__
|
| args
class SADeprecationWarning(HasDescriptionCode, builtins.DeprecationWarning)
| SADeprecationWarning(*arg: 'Any', **kw: 'Any')
|
| Issued for usage of deprecated APIs.
|
| Method resolution order:
| SADeprecationWarning
| HasDescriptionCode
| builtins.DeprecationWarning
| builtins.Warning
| builtins.Exception
| builtins.BaseException
| builtins.object
|
| Data descriptors defined here:
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'deprecated_since': 'Optional[str]'}
|
| deprecated_since = None
|
| ----------------------------------------------------------------------
| Methods inherited from HasDescriptionCode:
|
| __init__(self, *arg: 'Any', **kw: 'Any')
| Initialize self. See help(type(self)) for accurate signature.
|
| __str__(self) -> 'str'
| Return str(self).
|
| ----------------------------------------------------------------------
| Data descriptors inherited from HasDescriptionCode:
|
| __dict__
| dictionary for instance variables
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from HasDescriptionCode:
|
| code = None
|
| ----------------------------------------------------------------------
| Static methods inherited from builtins.DeprecationWarning:
|
| __new__(*args, **kwargs) class method of builtins.DeprecationWarning
| Create and return a new object. See help(type) for accurate signature.
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.BaseException:
|
| __getattribute__(self, name, /)
| Return getattr(self, name).
|
| __reduce__(...)
| Helper for pickle.
|
| __repr__(self, /)
| Return repr(self).
|
| __setstate__(...)
|
| add_note(...)
| Exception.add_note(note) --
| add a note to the exception
|
| with_traceback(...)
| Exception.with_traceback(tb) --
| set self.__traceback__ to tb and return self.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from builtins.BaseException:
|
| __cause__
| exception cause
|
| __context__
| exception context
|
| __suppress_context__
|
| __traceback__
|
| args
class SAPendingDeprecationWarning(builtins.PendingDeprecationWarning)
| A similar warning as :class:`_exc.SADeprecationWarning`, this warning
| is not used in modern versions of SQLAlchemy.
|
| Method resolution order:
| SAPendingDeprecationWarning
| builtins.PendingDeprecationWarning
| builtins.Warning
| builtins.Exception
| builtins.BaseException
| builtins.object
|
| Data descriptors defined here:
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'deprecated_since': 'Optional[str]'}
|
| deprecated_since = None
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.PendingDeprecationWarning:
|
| __init__(self, /, *args, **kwargs)
| Initialize self. See help(type(self)) for accurate signature.
|
| ----------------------------------------------------------------------
| Static methods inherited from builtins.PendingDeprecationWarning:
|
| __new__(*args, **kwargs) class method of builtins.PendingDeprecationWarning
| Create and return a new object. See help(type) for accurate signature.
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.BaseException:
|
| __getattribute__(self, name, /)
| Return getattr(self, name).
|
| __reduce__(...)
| Helper for pickle.
|
| __repr__(self, /)
| Return repr(self).
|
| __setstate__(...)
|
| __str__(self, /)
| Return str(self).
|
| add_note(...)
| Exception.add_note(note) --
| add a note to the exception
|
| with_traceback(...)
| Exception.with_traceback(tb) --
| set self.__traceback__ to tb and return self.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from builtins.BaseException:
|
| __cause__
| exception cause
|
| __context__
| exception context
|
| __dict__
|
| __suppress_context__
|
| __traceback__
|
| args
class SATestSuiteWarning(builtins.Warning)
| warning for a condition detected during tests that is non-fatal
|
| Currently outside of SAWarning so that we can work around tools like
| Alembic doing the wrong thing with warnings.
|
| Method resolution order:
| SATestSuiteWarning
| builtins.Warning
| builtins.Exception
| builtins.BaseException
| builtins.object
|
| Data descriptors defined here:
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.Warning:
|
| __init__(self, /, *args, **kwargs)
| Initialize self. See help(type(self)) for accurate signature.
|
| ----------------------------------------------------------------------
| Static methods inherited from builtins.Warning:
|
| __new__(*args, **kwargs) class method of builtins.Warning
| Create and return a new object. See help(type) for accurate signature.
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.BaseException:
|
| __getattribute__(self, name, /)
| Return getattr(self, name).
|
| __reduce__(...)
| Helper for pickle.
|
| __repr__(self, /)
| Return repr(self).
|
| __setstate__(...)
|
| __str__(self, /)
| Return str(self).
|
| add_note(...)
| Exception.add_note(note) --
| add a note to the exception
|
| with_traceback(...)
| Exception.with_traceback(tb) --
| set self.__traceback__ to tb and return self.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from builtins.BaseException:
|
| __cause__
| exception cause
|
| __context__
| exception context
|
| __dict__
|
| __suppress_context__
|
| __traceback__
|
| args
class SAWarning(HasDescriptionCode, builtins.RuntimeWarning)
| SAWarning(*arg: 'Any', **kw: 'Any')
|
| Issued at runtime.
|
| Method resolution order:
| SAWarning
| HasDescriptionCode
| builtins.RuntimeWarning
| builtins.Warning
| builtins.Exception
| builtins.BaseException
| builtins.object
|
| Data descriptors defined here:
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| ----------------------------------------------------------------------
| Methods inherited from HasDescriptionCode:
|
| __init__(self, *arg: 'Any', **kw: 'Any')
| Initialize self. See help(type(self)) for accurate signature.
|
| __str__(self) -> 'str'
| Return str(self).
|
| ----------------------------------------------------------------------
| Data descriptors inherited from HasDescriptionCode:
|
| __dict__
| dictionary for instance variables
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from HasDescriptionCode:
|
| code = None
|
| ----------------------------------------------------------------------
| Static methods inherited from builtins.RuntimeWarning:
|
| __new__(*args, **kwargs) class method of builtins.RuntimeWarning
| Create and return a new object. See help(type) for accurate signature.
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.BaseException:
|
| __getattribute__(self, name, /)
| Return getattr(self, name).
|
| __reduce__(...)
| Helper for pickle.
|
| __repr__(self, /)
| Return repr(self).
|
| __setstate__(...)
|
| add_note(...)
| Exception.add_note(note) --
| add a note to the exception
|
| with_traceback(...)
| Exception.with_traceback(tb) --
| set self.__traceback__ to tb and return self.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from builtins.BaseException:
|
| __cause__
| exception cause
|
| __context__
| exception context
|
| __suppress_context__
|
| __traceback__
|
| args
class SQLAlchemyError(HasDescriptionCode, builtins.Exception)
| SQLAlchemyError(*arg: 'Any', **kw: 'Any')
|
| Generic error class.
|
| Method resolution order:
| SQLAlchemyError
| HasDescriptionCode
| builtins.Exception
| builtins.BaseException
| builtins.object
|
| Methods defined here:
|
| __str__(self) -> 'str'
| Return str(self).
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| ----------------------------------------------------------------------
| Methods inherited from HasDescriptionCode:
|
| __init__(self, *arg: 'Any', **kw: 'Any')
| Initialize self. See help(type(self)) for accurate signature.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from HasDescriptionCode:
|
| __dict__
| dictionary for instance variables
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from HasDescriptionCode:
|
| code = None
|
| ----------------------------------------------------------------------
| Static methods inherited from builtins.Exception:
|
| __new__(*args, **kwargs) class method of builtins.Exception
| Create and return a new object. See help(type) for accurate signature.
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.BaseException:
|
| __getattribute__(self, name, /)
| Return getattr(self, name).
|
| __reduce__(...)
| Helper for pickle.
|
| __repr__(self, /)
| Return repr(self).
|
| __setstate__(...)
|
| add_note(...)
| Exception.add_note(note) --
| add a note to the exception
|
| with_traceback(...)
| Exception.with_traceback(tb) --
| set self.__traceback__ to tb and return self.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from builtins.BaseException:
|
| __cause__
| exception cause
|
| __context__
| exception context
|
| __suppress_context__
|
| __traceback__
|
| args
class StatementError(SQLAlchemyError)
| StatementError(message: 'str', statement: 'Optional[str]', params: 'Optional[_AnyExecuteParams]', orig: 'Optional[BaseException]', hide_parameters: 'bool' = False, code: 'Optional[str]' = None, ismulti: 'Optional[bool]' = None)
|
| An error occurred during execution of a SQL statement.
|
| :class:`StatementError` wraps the exception raised
| during execution, and features :attr:`.statement`
| and :attr:`.params` attributes which supply context regarding
| the specifics of the statement which had an issue.
|
| The wrapped exception object is available in
| the :attr:`.orig` attribute.
|
| Method resolution order:
| StatementError
| SQLAlchemyError
| HasDescriptionCode
| builtins.Exception
| builtins.BaseException
| builtins.object
|
| Methods defined here:
|
| __init__(self, message: 'str', statement: 'Optional[str]', params: 'Optional[_AnyExecuteParams]', orig: 'Optional[BaseException]', hide_parameters: 'bool' = False, code: 'Optional[str]' = None, ismulti: 'Optional[bool]' = None)
| Initialize self. See help(type(self)) for accurate signature.
|
| __reduce__(self) -> 'Union[str, Tuple[Any, ...]]'
| Helper for pickle.
|
| add_detail(self, msg: 'str') -> 'None'
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'connection_invalidated': 'bool', 'ismulti': 'Optio...
|
| connection_invalidated = False
|
| ismulti = None
|
| orig = None
|
| params = None
|
| statement = None
|
| ----------------------------------------------------------------------
| Methods inherited from SQLAlchemyError:
|
| __str__(self) -> 'str'
| Return str(self).
|
| ----------------------------------------------------------------------
| Data descriptors inherited from SQLAlchemyError:
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data descriptors inherited from HasDescriptionCode:
|
| __dict__
| dictionary for instance variables
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from HasDescriptionCode:
|
| code = None
|
| ----------------------------------------------------------------------
| Static methods inherited from builtins.Exception:
|
| __new__(*args, **kwargs) class method of builtins.Exception
| Create and return a new object. See help(type) for accurate signature.
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.BaseException:
|
| __getattribute__(self, name, /)
| Return getattr(self, name).
|
| __repr__(self, /)
| Return repr(self).
|
| __setstate__(...)
|
| add_note(...)
| Exception.add_note(note) --
| add a note to the exception
|
| with_traceback(...)
| Exception.with_traceback(tb) --
| set self.__traceback__ to tb and return self.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from builtins.BaseException:
|
| __cause__
| exception cause
|
| __context__
| exception context
|
| __suppress_context__
|
| __traceback__
|
| args
class TimeoutError(SQLAlchemyError)
| TimeoutError(*arg: 'Any', **kw: 'Any')
|
| Raised when a connection pool times out on getting a connection.
|
| Method resolution order:
| TimeoutError
| SQLAlchemyError
| HasDescriptionCode
| builtins.Exception
| builtins.BaseException
| builtins.object
|
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| ----------------------------------------------------------------------
| Methods inherited from SQLAlchemyError:
|
| __str__(self) -> 'str'
| Return str(self).
|
| ----------------------------------------------------------------------
| Data descriptors inherited from SQLAlchemyError:
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Methods inherited from HasDescriptionCode:
|
| __init__(self, *arg: 'Any', **kw: 'Any')
| Initialize self. See help(type(self)) for accurate signature.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from HasDescriptionCode:
|
| __dict__
| dictionary for instance variables
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from HasDescriptionCode:
|
| code = None
|
| ----------------------------------------------------------------------
| Static methods inherited from builtins.Exception:
|
| __new__(*args, **kwargs) class method of builtins.Exception
| Create and return a new object. See help(type) for accurate signature.
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.BaseException:
|
| __getattribute__(self, name, /)
| Return getattr(self, name).
|
| __reduce__(...)
| Helper for pickle.
|
| __repr__(self, /)
| Return repr(self).
|
| __setstate__(...)
|
| add_note(...)
| Exception.add_note(note) --
| add a note to the exception
|
| with_traceback(...)
| Exception.with_traceback(tb) --
| set self.__traceback__ to tb and return self.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from builtins.BaseException:
|
| __cause__
| exception cause
|
| __context__
| exception context
|
| __suppress_context__
|
| __traceback__
|
| args
class UnboundExecutionError(InvalidRequestError)
| UnboundExecutionError(*arg: 'Any', **kw: 'Any')
|
| SQL was attempted without a database connection to execute it on.
|
| Method resolution order:
| UnboundExecutionError
| InvalidRequestError
| SQLAlchemyError
| HasDescriptionCode
| builtins.Exception
| builtins.BaseException
| builtins.object
|
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| ----------------------------------------------------------------------
| Methods inherited from SQLAlchemyError:
|
| __str__(self) -> 'str'
| Return str(self).
|
| ----------------------------------------------------------------------
| Data descriptors inherited from SQLAlchemyError:
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Methods inherited from HasDescriptionCode:
|
| __init__(self, *arg: 'Any', **kw: 'Any')
| Initialize self. See help(type(self)) for accurate signature.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from HasDescriptionCode:
|
| __dict__
| dictionary for instance variables
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from HasDescriptionCode:
|
| code = None
|
| ----------------------------------------------------------------------
| Static methods inherited from builtins.Exception:
|
| __new__(*args, **kwargs) class method of builtins.Exception
| Create and return a new object. See help(type) for accurate signature.
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.BaseException:
|
| __getattribute__(self, name, /)
| Return getattr(self, name).
|
| __reduce__(...)
| Helper for pickle.
|
| __repr__(self, /)
| Return repr(self).
|
| __setstate__(...)
|
| add_note(...)
| Exception.add_note(note) --
| add a note to the exception
|
| with_traceback(...)
| Exception.with_traceback(tb) --
| set self.__traceback__ to tb and return self.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from builtins.BaseException:
|
| __cause__
| exception cause
|
| __context__
| exception context
|
| __suppress_context__
|
| __traceback__
|
| args
class UnreflectableTableError(InvalidRequestError)
| UnreflectableTableError(*arg: 'Any', **kw: 'Any')
|
| Table exists but can't be reflected for some reason.
|
| .. versionadded:: 1.2
|
| Method resolution order:
| UnreflectableTableError
| InvalidRequestError
| SQLAlchemyError
| HasDescriptionCode
| builtins.Exception
| builtins.BaseException
| builtins.object
|
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| ----------------------------------------------------------------------
| Methods inherited from SQLAlchemyError:
|
| __str__(self) -> 'str'
| Return str(self).
|
| ----------------------------------------------------------------------
| Data descriptors inherited from SQLAlchemyError:
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Methods inherited from HasDescriptionCode:
|
| __init__(self, *arg: 'Any', **kw: 'Any')
| Initialize self. See help(type(self)) for accurate signature.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from HasDescriptionCode:
|
| __dict__
| dictionary for instance variables
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from HasDescriptionCode:
|
| code = None
|
| ----------------------------------------------------------------------
| Static methods inherited from builtins.Exception:
|
| __new__(*args, **kwargs) class method of builtins.Exception
| Create and return a new object. See help(type) for accurate signature.
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.BaseException:
|
| __getattribute__(self, name, /)
| Return getattr(self, name).
|
| __reduce__(...)
| Helper for pickle.
|
| __repr__(self, /)
| Return repr(self).
|
| __setstate__(...)
|
| add_note(...)
| Exception.add_note(note) --
| add a note to the exception
|
| with_traceback(...)
| Exception.with_traceback(tb) --
| set self.__traceback__ to tb and return self.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from builtins.BaseException:
|
| __cause__
| exception cause
|
| __context__
| exception context
|
| __suppress_context__
|
| __traceback__
|
| args
class UnsupportedCompilationError(CompileError)
| UnsupportedCompilationError(compiler: 'Union[Compiled, TypeCompiler]', element_type: 'Type[ClauseElement]', message: 'Optional[str]' = None)
|
| Raised when an operation is not supported by the given compiler.
|
| .. seealso::
|
| :ref:`faq_sql_expression_string`
|
| :ref:`error_l7de`
|
| Method resolution order:
| UnsupportedCompilationError
| CompileError
| SQLAlchemyError
| HasDescriptionCode
| builtins.Exception
| builtins.BaseException
| builtins.object
|
| Methods defined here:
|
| __init__(self, compiler: 'Union[Compiled, TypeCompiler]', element_type: 'Type[ClauseElement]', message: 'Optional[str]' = None)
| Initialize self. See help(type(self)) for accurate signature.
|
| __reduce__(self) -> 'Union[str, Tuple[Any, ...]]'
| Helper for pickle.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| code = 'l7de'
|
| ----------------------------------------------------------------------
| Methods inherited from SQLAlchemyError:
|
| __str__(self) -> 'str'
| Return str(self).
|
| ----------------------------------------------------------------------
| Data descriptors inherited from SQLAlchemyError:
|
| __weakref__
| list of weak references to the object
|
| ----------------------------------------------------------------------
| Data descriptors inherited from HasDescriptionCode:
|
| __dict__
| dictionary for instance variables
|
| ----------------------------------------------------------------------
| Static methods inherited from builtins.Exception:
|
| __new__(*args, **kwargs) class method of builtins.Exception
| Create and return a new object. See help(type) for accurate signature.
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.BaseException:
|
| __getattribute__(self, name, /)
| Return getattr(self, name).
|
| __repr__(self, /)
| Return repr(self).
|
| __setstate__(...)
|
| add_note(...)
| Exception.add_note(note) --
| add a note to the exception
|
| with_traceback(...)
| Exception.with_traceback(tb) --
| set self.__traceback__ to tb and return self.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from builtins.BaseException:
|
| __cause__
| exception cause
|
| __context__
| exception context
|
| __suppress_context__
|
| __traceback__
|
| args
DATA
List = typing.List
A generic version of list.
Optional = typing.Optional
Optional[X] is equivalent to Union[X, None].
Tuple = typing.Tuple
Deprecated alias to builtins.tuple.
Tuple[X, Y] is the cross-product type of X and Y.
Example: Tuple[T1, T2] is a tuple of two elements corresponding
to type variables T1 and T2. Tuple[int, float, str] is a tuple
of an int, a float and a string.
To specify a variable-length tuple of homogeneous type, use Tuple[T, ...].
Type = typing.Type
Deprecated alias to builtins.type.
builtins.type or typing.Type can be used to annotate class objects.
For example, suppose we have the following classes::
class User: ... # Abstract base for User classes
class BasicUser(User): ...
class ProUser(User): ...
class TeamUser(User): ...
And a function that takes a class argument that's a subclass of
User and returns an instance of the corresponding class::
def new_user[U](user_class: Type[U]) -> U:
user = user_class()
# (Here we could write the user object to a database)
return user
joe = new_user(BasicUser)
At this point the type checker knows that joe has type BasicUser.
Union = typing.Union
Union type; Union[X, Y] means either X or Y.
On Python 3.10 and higher, the | operator
can also be used to denote unions;
X | Y means the same thing to the type checker as Union[X, Y].
To define a union, use e.g. Union[int, str]. Details:
- The arguments must be types and there must be at least one.
- None as an argument is a special case and is replaced by
type(None).
- Unions of unions are flattened, e.g.::
assert Union[Union[int, str], float] == Union[int, str, float]
- Unions of a single argument vanish, e.g.::
assert Union[int] == int # The constructor actually returns int
- Redundant arguments are skipped, e.g.::
assert Union[int, str, int] == Union[int, str]
- When comparing unions, the argument order is ignored, e.g.::
assert Union[int, str] == Union[str, int]
- You cannot subclass or instantiate a union.
- You can use Optional[X] as a shorthand for Union[X, None].
__annotations__ = {}
FILE
c:\users\youse\appdata\local\programs\python\python312\lib\site-packages\sqlalchemy\exc.py
sqlalchemy.except_
Python Library Documentation: function except_ in module sqlalchemy.sql._selectable_constructors
except_(*selects: '_SelectStatementForCompoundArgument[_TP]') -> 'CompoundSelect[_TP]'
Return an ``EXCEPT`` of multiple selectables.
The returned object is an instance of
:class:`_expression.CompoundSelect`.
:param \*selects:
a list of :class:`_expression.Select` instances.
sqlalchemy.except_all
Python Library Documentation: function except_all in module sqlalchemy.sql._selectable_constructors
except_all(*selects: '_SelectStatementForCompoundArgument[_TP]') -> 'CompoundSelect[_TP]'
Return an ``EXCEPT ALL`` of multiple selectables.
The returned object is an instance of
:class:`_expression.CompoundSelect`.
:param \*selects:
a list of :class:`_expression.Select` instances.
sqlalchemy.exists
Python Library Documentation: function exists in module sqlalchemy.sql._selectable_constructors
exists(__argument: 'Optional[Union[_ColumnsClauseArgument[Any], SelectBase, ScalarSelect[Any]]]' = None) -> 'Exists'
Construct a new :class:`_expression.Exists` construct.
The :func:`_sql.exists` can be invoked by itself to produce an
:class:`_sql.Exists` construct, which will accept simple WHERE
criteria::
exists_criteria = exists().where(table1.c.col1 == table2.c.col2)
However, for greater flexibility in constructing the SELECT, an
existing :class:`_sql.Select` construct may be converted to an
:class:`_sql.Exists`, most conveniently by making use of the
:meth:`_sql.SelectBase.exists` method::
exists_criteria = (
select(table2.c.col2).where(table1.c.col1 == table2.c.col2).exists()
)
The EXISTS criteria is then used inside of an enclosing SELECT::
stmt = select(table1.c.col1).where(exists_criteria)
The above statement will then be of the form:
.. sourcecode:: sql
SELECT col1 FROM table1 WHERE EXISTS
(SELECT table2.col2 FROM table2 WHERE table2.col2 = table1.col1)
.. seealso::
:ref:`tutorial_exists` - in the :term:`2.0 style` tutorial.
:meth:`_sql.SelectBase.exists` - method to transform a ``SELECT`` to an
``EXISTS`` clause.
sqlalchemy.extract
Python Library Documentation: function extract in module sqlalchemy.sql._elements_constructors
extract(field: 'str', expr: '_ColumnExpressionArgument[Any]') -> 'Extract'
Return a :class:`.Extract` construct.
This is typically available as :func:`.extract`
as well as ``func.extract`` from the
:data:`.func` namespace.
:param field: The field to extract.
.. warning:: This field is used as a literal SQL string.
**DO NOT PASS UNTRUSTED INPUT TO THIS STRING**.
:param expr: A column or Python scalar expression serving as the
right side of the ``EXTRACT`` expression.
E.g.::
from sqlalchemy import extract
from sqlalchemy import table, column
logged_table = table(
"user",
column("id"),
column("date_created"),
)
stmt = select(logged_table.c.id).where(
extract("YEAR", logged_table.c.date_created) == 2021
)
In the above example, the statement is used to select ids from the
database where the ``YEAR`` component matches a specific value.
Similarly, one can also select an extracted component::
stmt = select(extract("YEAR", logged_table.c.date_created)).where(
logged_table.c.id == 1
)
The implementation of ``EXTRACT`` may vary across database backends.
Users are reminded to consult their database documentation.
sqlalchemy.false
Python Library Documentation: function false in module sqlalchemy.sql._elements_constructors
false() -> 'False_'
Return a :class:`.False_` construct.
E.g.:
.. sourcecode:: pycon+sql
>>> from sqlalchemy import false
>>> print(select(t.c.x).where(false()))
{printsql}SELECT x FROM t WHERE false
A backend which does not support true/false constants will render as
an expression against 1 or 0:
.. sourcecode:: pycon+sql
>>> print(select(t.c.x).where(false()))
{printsql}SELECT x FROM t WHERE 0 = 1
The :func:`.true` and :func:`.false` constants also feature
"short circuit" operation within an :func:`.and_` or :func:`.or_`
conjunction:
.. sourcecode:: pycon+sql
>>> print(select(t.c.x).where(or_(t.c.x > 5, true())))
{printsql}SELECT x FROM t WHERE true{stop}
>>> print(select(t.c.x).where(and_(t.c.x > 5, false())))
{printsql}SELECT x FROM t WHERE false{stop}
.. seealso::
:func:`.true`
sqlalchemy.func
Python Library Documentation: _FunctionGenerator in module sqlalchemy.sql.functions object
class _FunctionGenerator(builtins.object)
| _FunctionGenerator(**opts: 'Any') -> 'None'
|
| Generate SQL function expressions.
|
| :data:`.func` is a special object instance which generates SQL
| functions based on name-based attributes, e.g.:
|
| .. sourcecode:: pycon+sql
|
| >>> print(func.count(1))
| {printsql}count(:param_1)
|
| The returned object is an instance of :class:`.Function`, and is a
| column-oriented SQL element like any other, and is used in that way:
|
| .. sourcecode:: pycon+sql
|
| >>> print(select(func.count(table.c.id)))
| {printsql}SELECT count(sometable.id) FROM sometable
|
| Any name can be given to :data:`.func`. If the function name is unknown to
| SQLAlchemy, it will be rendered exactly as is. For common SQL functions
| which SQLAlchemy is aware of, the name may be interpreted as a *generic
| function* which will be compiled appropriately to the target database:
|
| .. sourcecode:: pycon+sql
|
| >>> print(func.current_timestamp())
| {printsql}CURRENT_TIMESTAMP
|
| To call functions which are present in dot-separated packages,
| specify them in the same manner:
|
| .. sourcecode:: pycon+sql
|
| >>> print(func.stats.yield_curve(5, 10))
| {printsql}stats.yield_curve(:yield_curve_1, :yield_curve_2)
|
| SQLAlchemy can be made aware of the return type of functions to enable
| type-specific lexical and result-based behavior. For example, to ensure
| that a string-based function returns a Unicode value and is similarly
| treated as a string in expressions, specify
| :class:`~sqlalchemy.types.Unicode` as the type:
|
| .. sourcecode:: pycon+sql
|
| >>> print(
| ... func.my_string("hi", type_=Unicode)
| ... + " "
| ... + func.my_string("there", type_=Unicode)
| ... )
| {printsql}my_string(:my_string_1) || :my_string_2 || my_string(:my_string_3)
|
| The object returned by a :data:`.func` call is usually an instance of
| :class:`.Function`.
| This object meets the "column" interface, including comparison and labeling
| functions. The object can also be passed the :meth:`~.Connectable.execute`
| method of a :class:`_engine.Connection` or :class:`_engine.Engine`,
| where it will be
| wrapped inside of a SELECT statement first::
|
| print(connection.execute(func.current_timestamp()).scalar())
|
| In a few exception cases, the :data:`.func` accessor
| will redirect a name to a built-in expression such as :func:`.cast`
| or :func:`.extract`, as these names have well-known meaning
| but are not exactly the same as "functions" from a SQLAlchemy
| perspective.
|
| Functions which are interpreted as "generic" functions know how to
| calculate their return type automatically. For a listing of known generic
| functions, see :ref:`generic_functions`.
|
| .. note::
|
| The :data:`.func` construct has only limited support for calling
| standalone "stored procedures", especially those with special
| parameterization concerns.
|
| See the section :ref:`stored_procedures` for details on how to use
| the DBAPI-level ``callproc()`` method for fully traditional stored
| procedures.
|
| .. seealso::
|
| :ref:`tutorial_functions` - in the :ref:`unified_tutorial`
|
| :class:`.Function`
|
| Methods defined here:
|
| __call__(self, *c: 'Any', **kwargs: 'Any') -> 'Function[Any]'
| Call self as a function.
|
| __getattr__(self, name: 'str') -> '_FunctionGenerator'
|
| __init__(self, **opts: 'Any') -> 'None'
| Initialize self. See help(type(self)) for accurate signature.
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
sqlalchemy.funcfilter
Python Library Documentation: function funcfilter in module sqlalchemy.sql._elements_constructors
funcfilter(func: 'FunctionElement[_T]', *criterion: '_ColumnExpressionArgument[bool]') -> 'FunctionFilter[_T]'
Produce a :class:`.FunctionFilter` object against a function.
Used against aggregate and window functions,
for database backends that support the "FILTER" clause.
E.g.::
from sqlalchemy import funcfilter
funcfilter(func.count(1), MyClass.name == "some name")
Would produce "COUNT(1) FILTER (WHERE myclass.name = 'some name')".
This function is also available from the :data:`~.expression.func`
construct itself via the :meth:`.FunctionElement.filter` method.
.. seealso::
:ref:`tutorial_functions_within_group` - in the
:ref:`unified_tutorial`
:meth:`.FunctionElement.filter`
sqlalchemy.insert
Python Library Documentation: function insert in module sqlalchemy.sql._dml_constructors
insert(table: '_DMLTableArgument') -> 'Insert'
Construct an :class:`_expression.Insert` object.
E.g.::
from sqlalchemy import insert
stmt = insert(user_table).values(name="username", fullname="Full Username")
Similar functionality is available via the
:meth:`_expression.TableClause.insert` method on
:class:`_schema.Table`.
.. seealso::
:ref:`tutorial_core_insert` - in the :ref:`unified_tutorial`
:param table: :class:`_expression.TableClause`
which is the subject of the
insert.
:param values: collection of values to be inserted; see
:meth:`_expression.Insert.values`
for a description of allowed formats here.
Can be omitted entirely; a :class:`_expression.Insert` construct
will also dynamically render the VALUES clause at execution time
based on the parameters passed to :meth:`_engine.Connection.execute`.
:param inline: if True, no attempt will be made to retrieve the
SQL-generated default values to be provided within the statement;
in particular,
this allows SQL expressions to be rendered 'inline' within the
statement without the need to pre-execute them beforehand; for
backends that support "returning", this turns off the "implicit
returning" feature for the statement.
If both :paramref:`_expression.insert.values` and compile-time bind
parameters are present, the compile-time bind parameters override the
information specified within :paramref:`_expression.insert.values` on a
per-key basis.
The keys within :paramref:`_expression.Insert.values` can be either
:class:`~sqlalchemy.schema.Column` objects or their string
identifiers. Each key may reference one of:
* a literal data value (i.e. string, number, etc.);
* a Column object;
* a SELECT statement.
If a ``SELECT`` statement is specified which references this
``INSERT`` statement's table, the statement will be correlated
against the ``INSERT`` statement.
.. seealso::
:ref:`tutorial_core_insert` - in the :ref:`unified_tutorial`
sqlalchemy.insert_sentinel
Python Library Documentation: function insert_sentinel in module sqlalchemy.sql.schema
insert_sentinel(name: 'Optional[str]' = None, type_: 'Optional[_TypeEngineArgument[_T]]' = None, *, default: 'Optional[Any]' = None, omit_from_statements: 'bool' = True) -> 'Column[Any]'
Provides a surrogate :class:`_schema.Column` that will act as a
dedicated insert :term:`sentinel` column, allowing efficient bulk
inserts with deterministic RETURNING sorting for tables that
don't otherwise have qualifying primary key configurations.
Adding this column to a :class:`.Table` object requires that a
corresponding database table actually has this column present, so if adding
it to an existing model, existing database tables would need to be migrated
(e.g. using ALTER TABLE or similar) to include this column.
For background on how this object is used, see the section
:ref:`engine_insertmanyvalues_sentinel_columns` as part of the
section :ref:`engine_insertmanyvalues`.
The :class:`_schema.Column` returned will be a nullable integer column by
default and make use of a sentinel-specific default generator used only in
"insertmanyvalues" operations.
.. seealso::
:func:`_orm.orm_insert_sentinel`
:paramref:`_schema.Column.insert_sentinel`
:ref:`engine_insertmanyvalues`
:ref:`engine_insertmanyvalues_sentinel_columns`
.. versionadded:: 2.0.10
sqlalchemy.inspect
Python Library Documentation: function inspect in module sqlalchemy.inspection
inspect(subject: 'Any', raiseerr: 'bool' = True) -> 'Any'
Produce an inspection object for the given target.
The returned value in some cases may be the
same object as the one given, such as if a
:class:`_orm.Mapper` object is passed. In other
cases, it will be an instance of the registered
inspection type for the given object, such as
if an :class:`_engine.Engine` is passed, an
:class:`_reflection.Inspector` object is returned.
:param subject: the subject to be inspected.
:param raiseerr: When ``True``, if the given subject
does not
correspond to a known SQLAlchemy inspected type,
:class:`sqlalchemy.exc.NoInspectionAvailable`
is raised. If ``False``, ``None`` is returned.
sqlalchemy.inspection
Python Library Documentation: module sqlalchemy.inspection in sqlalchemy
NAME
sqlalchemy.inspection
DESCRIPTION
The inspection module provides the :func:`_sa.inspect` function,
which delivers runtime information about a wide variety
of SQLAlchemy objects, both within the Core as well as the
ORM.
The :func:`_sa.inspect` function is the entry point to SQLAlchemy's
public API for viewing the configuration and construction
of in-memory objects. Depending on the type of object
passed to :func:`_sa.inspect`, the return value will either be
a related object which provides a known interface, or in many
cases it will return the object itself.
The rationale for :func:`_sa.inspect` is twofold. One is that
it replaces the need to be aware of a large variety of "information
getting" functions in SQLAlchemy, such as
:meth:`_reflection.Inspector.from_engine` (deprecated in 1.4),
:func:`.orm.attributes.instance_state`, :func:`_orm.class_mapper`,
and others. The other is that the return value of :func:`_sa.inspect`
is guaranteed to obey a documented API, thus allowing third party
tools which build on top of SQLAlchemy configurations to be constructed
in a forwards-compatible way.
CLASSES
typing.Generic(builtins.object)
Inspectable
class Inspectable(typing.Generic)
| define a class as inspectable.
|
| This allows typing to set up a linkage between an object that
| can be inspected and the type of inspection it returns.
|
| Unfortunately we cannot at the moment get all classes that are
| returned by inspection to suit this interface as we get into
| MRO issues.
|
| Method resolution order:
| Inspectable
| typing.Generic
| builtins.object
|
| Data and other attributes defined here:
|
| __annotations__ = {}
|
| __orig_bases__ = (typing.Generic[~_T],)
|
| __parameters__ = (~_T,)
|
| ----------------------------------------------------------------------
| Class methods inherited from typing.Generic:
|
| __class_getitem__(...)
| Parameterizes a generic class.
|
| At least, parameterizing a generic class is the *main* thing this
| method does. For example, for some generic class `Foo`, this is called
| when we do `Foo[int]` - there, with `cls=Foo` and `params=int`.
|
| However, note that this method is also called when defining generic
| classes in the first place with `class Foo[T]: ...`.
|
| __init_subclass__(...)
| Function to initialize subclasses.
FUNCTIONS
inspect(subject: 'Any', raiseerr: 'bool' = True) -> 'Any'
Produce an inspection object for the given target.
The returned value in some cases may be the
same object as the one given, such as if a
:class:`_orm.Mapper` object is passed. In other
cases, it will be an instance of the registered
inspection type for the given object, such as
if an :class:`_engine.Engine` is passed, an
:class:`_reflection.Inspector` object is returned.
:param subject: the subject to be inspected.
:param raiseerr: When ``True``, if the given subject
does not
correspond to a known SQLAlchemy inspected type,
:class:`sqlalchemy.exc.NoInspectionAvailable`
is raised. If ``False``, ``None`` is returned.
DATA
Callable = typing.Callable
Deprecated alias to collections.abc.Callable.
Callable[[int], str] signifies a function that takes a single
parameter of type int and returns a str.
The subscription syntax must always be used with exactly two
values: the argument list and the return type.
The argument list must be a list of types, a ParamSpec,
Concatenate or ellipsis. The return type must be a single type.
There is no syntax to indicate optional or keyword arguments;
such function types are rarely used as callback types.
Dict = typing.Dict
A generic version of dict.
Literal = typing.Literal
Special typing form to define literal types (a.k.a. value types).
This form can be used to indicate to type checkers that the corresponding
variable or function parameter has a value equivalent to the provided
literal (or one of several literals)::
def validate_simple(data: Any) -> Literal[True]: # always returns True
...
MODE = Literal['r', 'rb', 'w', 'wb']
def open_helper(file: str, mode: MODE) -> str:
...
open_helper('/some/path', 'r') # Passes type check
open_helper('/other/path', 'typo') # Error in type checker
Literal[...] cannot be subclassed. At runtime, an arbitrary value
is allowed as type argument to Literal[...], but type checkers may
impose restrictions.
Optional = typing.Optional
Optional[X] is equivalent to Union[X, None].
Type = typing.Type
Deprecated alias to builtins.type.
builtins.type or typing.Type can be used to annotate class objects.
For example, suppose we have the following classes::
class User: ... # Abstract base for User classes
class BasicUser(User): ...
class ProUser(User): ...
class TeamUser(User): ...
And a function that takes a class argument that's a subclass of
User and returns an instance of the corresponding class::
def new_user[U](user_class: Type[U]) -> U:
user = user_class()
# (Here we could write the user object to a database)
return user
joe = new_user(BasicUser)
At this point the type checker knows that joe has type BasicUser.
Union = typing.Union
Union type; Union[X, Y] means either X or Y.
On Python 3.10 and higher, the | operator
can also be used to denote unions;
X | Y means the same thing to the type checker as Union[X, Y].
To define a union, use e.g. Union[int, str]. Details:
- The arguments must be types and there must be at least one.
- None as an argument is a special case and is replaced by
type(None).
- Unions of unions are flattened, e.g.::
assert Union[Union[int, str], float] == Union[int, str, float]
- Unions of a single argument vanish, e.g.::
assert Union[int] == int # The constructor actually returns int
- Redundant arguments are skipped, e.g.::
assert Union[int, str, int] == Union[int, str]
- When comparing unions, the argument order is ignored, e.g.::
assert Union[int, str] == Union[str, int]
- You cannot subclass or instantiate a union.
- You can use Optional[X] as a shorthand for Union[X, None].
__annotations__ = {'_registrars': 'Dict[type, Union[Literal[True], Cal...
FILE
c:\users\youse\appdata\local\programs\python\python312\lib\site-packages\sqlalchemy\inspection.py
sqlalchemy.intersect
Python Library Documentation: function intersect in module sqlalchemy.sql._selectable_constructors
intersect(*selects: '_SelectStatementForCompoundArgument[_TP]') -> 'CompoundSelect[_TP]'
Return an ``INTERSECT`` of multiple selectables.
The returned object is an instance of
:class:`_expression.CompoundSelect`.
:param \*selects:
a list of :class:`_expression.Select` instances.
sqlalchemy.intersect_all
Python Library Documentation: function intersect_all in module sqlalchemy.sql._selectable_constructors
intersect_all(*selects: '_SelectStatementForCompoundArgument[_TP]') -> 'CompoundSelect[_TP]'
Return an ``INTERSECT ALL`` of multiple selectables.
The returned object is an instance of
:class:`_expression.CompoundSelect`.
:param \*selects:
a list of :class:`_expression.Select` instances.
sqlalchemy.join
Python Library Documentation: function join in module sqlalchemy.sql._selectable_constructors
join(left: '_FromClauseArgument', right: '_FromClauseArgument', onclause: 'Optional[_OnClauseArgument]' = None, isouter: 'bool' = False, full: 'bool' = False) -> 'Join'
Produce a :class:`_expression.Join` object, given two
:class:`_expression.FromClause`
expressions.
E.g.::
j = join(
user_table, 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
Similar functionality is available given any
:class:`_expression.FromClause` object (e.g. such as a
:class:`_schema.Table`) using
the :meth:`_expression.FromClause.join` method.
:param left: The left side of the join.
: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 JOIN.
.. seealso::
:meth:`_expression.FromClause.join` - method form,
based on a given left side.
:class:`_expression.Join` - the type of object produced.
sqlalchemy.label
Python Library Documentation: function label in module sqlalchemy.sql._elements_constructors
label(name: 'str', element: '_ColumnExpressionArgument[_T]', type_: 'Optional[_TypeEngineArgument[_T]]' = None) -> 'Label[_T]'
Return a :class:`Label` object for the
given :class:`_expression.ColumnElement`.
A label changes the name of an element in the columns clause of a
``SELECT`` statement, typically via the ``AS`` SQL keyword.
This functionality is more conveniently available via the
:meth:`_expression.ColumnElement.label` method on
:class:`_expression.ColumnElement`.
:param name: label name
:param obj: a :class:`_expression.ColumnElement`.
sqlalchemy.lambda_stmt
Python Library Documentation: function lambda_stmt in module sqlalchemy.sql.lambdas
lambda_stmt(lmb: '_StmtLambdaType', enable_tracking: 'bool' = True, track_closure_variables: 'bool' = True, track_on: 'Optional[object]' = None, global_track_bound_values: 'bool' = True, track_bound_values: 'bool' = True, lambda_cache: 'Optional[_LambdaCacheType]' = None) -> 'StatementLambdaElement'
Produce a SQL statement that is cached as a lambda.
The Python code object within the lambda is scanned for both Python
literals that will become bound parameters as well as closure variables
that refer to Core or ORM constructs that may vary. The lambda itself
will be invoked only once per particular set of constructs detected.
E.g.::
from sqlalchemy import lambda_stmt
stmt = lambda_stmt(lambda: table.select())
stmt += lambda s: s.where(table.c.id == 5)
result = connection.execute(stmt)
The object returned is an instance of :class:`_sql.StatementLambdaElement`.
.. versionadded:: 1.4
:param lmb: a Python function, typically a lambda, which takes no arguments
and returns a SQL expression construct
:param enable_tracking: when False, all scanning of the given lambda for
changes in closure variables or bound parameters is disabled. Use for
a lambda that produces the identical results in all cases with no
parameterization.
:param track_closure_variables: when False, changes in closure variables
within the lambda will not be scanned. Use for a lambda where the
state of its closure variables will never change the SQL structure
returned by the lambda.
:param track_bound_values: when False, bound parameter tracking will
be disabled for the given lambda. Use for a lambda that either does
not produce any bound values, or where the initial bound values never
change.
:param global_track_bound_values: when False, bound parameter tracking
will be disabled for the entire statement including additional links
added via the :meth:`_sql.StatementLambdaElement.add_criteria` method.
:param lambda_cache: a dictionary or other mapping-like object where
information about the lambda's Python code as well as the tracked closure
variables in the lambda itself will be stored. Defaults
to a global LRU cache. This cache is independent of the "compiled_cache"
used by the :class:`_engine.Connection` object.
.. seealso::
:ref:`engine_lambda_caching`
sqlalchemy.lateral
Python Library Documentation: function lateral in module sqlalchemy.sql._selectable_constructors
lateral(selectable: 'Union[SelectBase, _FromClauseArgument]', name: 'Optional[str]' = None) -> 'LateralFromClause'
Return a :class:`_expression.Lateral` object.
:class:`_expression.Lateral` is an :class:`_expression.Alias`
subclass that represents
a subquery with the LATERAL keyword applied to it.
The special behavior of a LATERAL subquery is that it appears in the
FROM clause of an enclosing SELECT, but may correlate to other
FROM clauses of that SELECT. It is a special case of subquery
only supported by a small number of backends, currently more recent
PostgreSQL versions.
.. seealso::
:ref:`tutorial_lateral_correlation` - overview of usage.
sqlalchemy.literal
Python Library Documentation: function literal in module sqlalchemy.sql.elements
literal(value: 'Any', type_: 'Optional[_TypeEngineArgument[Any]]' = None, literal_execute: 'bool' = False) -> 'BindParameter[Any]'
Return a literal clause, bound to a bind parameter.
Literal clauses are created automatically when non-
:class:`_expression.ClauseElement` objects (such as strings, ints, dates,
etc.) are
used in a comparison operation with a :class:`_expression.ColumnElement`
subclass,
such as a :class:`~sqlalchemy.schema.Column` object. Use this function
to force the generation of a literal clause, which will be created as a
:class:`BindParameter` with a bound value.
:param value: the value to be bound. Can be any Python object supported by
the underlying DB-API, or is translatable via the given type argument.
:param type\_: an optional :class:`~sqlalchemy.types.TypeEngine` which will
provide bind-parameter translation for this literal.
:param literal_execute: optional bool, when True, the SQL engine will
attempt to render the bound value directly in the SQL statement at
execution time rather than providing as a parameter value.
.. versionadded:: 2.0
sqlalchemy.literal_column
Python Library Documentation: function literal_column in module sqlalchemy.sql.elements
literal_column(text: 'str', type_: 'Optional[_TypeEngineArgument[_T]]' = None) -> 'ColumnClause[_T]'
Produce a :class:`.ColumnClause` object that has the
:paramref:`_expression.column.is_literal` flag set to True.
:func:`_expression.literal_column` is similar to
:func:`_expression.column`, except that
it is more often used as a "standalone" column expression that renders
exactly as stated; while :func:`_expression.column`
stores a string name that
will be assumed to be part of a table and may be quoted as such,
:func:`_expression.literal_column` can be that,
or any other arbitrary column-oriented
expression.
:param text: the text of the expression; can be any SQL expression.
Quoting rules will not be applied. To specify a column-name expression
which should be subject to quoting rules, use the :func:`column`
function.
:param type\_: an optional :class:`~sqlalchemy.types.TypeEngine`
object which will
provide result-set translation and additional expression semantics for
this column. If left as ``None`` the type will be :class:`.NullType`.
.. seealso::
:func:`_expression.column`
:func:`_expression.text`
:ref:`tutorial_select_arbitrary_text`
sqlalchemy.log
Python Library Documentation: module sqlalchemy.log in sqlalchemy
NAME
sqlalchemy.log - Logging control and utilities.
DESCRIPTION
Control of logging for SA can be performed from the regular python logging
module. The regular dotted module namespace is used, starting at
'sqlalchemy'. For class-level logging, the class name is appended.
The "echo" keyword parameter, available on SQLA :class:`_engine.Engine`
and :class:`_pool.Pool` objects, corresponds to a logger specific to that
instance only.
CLASSES
builtins.object
Identified
InstanceLogger
echo_property
class Identified(builtins.object)
| Data and other attributes defined here:
|
| __annotations__ = {'_echo': '_EchoFlagType', 'logger': '_IdentifiedLog...
|
| logging_name = None
class InstanceLogger(builtins.object)
| InstanceLogger(echo: '_EchoFlagType', name: 'str')
|
| A logger adapter (wrapper) for :class:`.Identified` subclasses.
|
| This allows multiple instances (e.g. Engine or Pool instances)
| to share a logger, but have its verbosity controlled on a
| per-instance basis.
|
| The basic functionality is to return a logging level
| which is based on an instance's echo setting.
|
| Default implementation is:
|
| 'debug' -> logging.DEBUG
| True -> logging.INFO
| False -> Effective level of underlying logger (
| logging.WARNING by default)
| None -> same as False
|
| Methods defined here:
|
| __init__(self, echo: '_EchoFlagType', name: 'str')
| Initialize self. See help(type(self)) for accurate signature.
|
| critical(self, msg: 'str', *args: 'Any', **kwargs: 'Any') -> 'None'
| Delegate a critical call to the underlying logger.
|
| debug(self, msg: 'str', *args: 'Any', **kwargs: 'Any') -> 'None'
| Delegate a debug call to the underlying logger.
|
| error(self, msg: 'str', *args: 'Any', **kwargs: 'Any') -> 'None'
| Delegate an error call to the underlying logger.
|
| exception(self, msg: 'str', *args: 'Any', **kwargs: 'Any') -> 'None'
| Delegate an exception call to the underlying logger.
|
| getEffectiveLevel(self) -> 'int'
| What's the effective level for this logger?
|
| info(self, msg: 'str', *args: 'Any', **kwargs: 'Any') -> 'None'
| Delegate an info call to the underlying logger.
|
| isEnabledFor(self, level: 'int') -> 'bool'
| Is this logger enabled for level 'level'?
|
| log(self, level: 'int', msg: 'str', *args: 'Any', **kwargs: 'Any') -> 'None'
| Delegate a log call to the underlying logger.
|
| The level here is determined by the echo
| flag as well as that of the underlying logger, and
| logger._log() is called directly.
|
| warn = warning(self, msg: 'str', *args: 'Any', **kwargs: 'Any') -> 'None'
|
| warning(self, msg: 'str', *args: 'Any', **kwargs: 'Any') -> 'None'
| Delegate a warning call to the underlying logger.
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| echo
|
| logger
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'_echo': '_EchoFlagType'}
class echo_property(builtins.object)
| When ``True``, enable log output for this element.
|
| This has the effect of setting the Python logging level for the namespace
| of this element's class and object reference. A value of boolean ``True``
| indicates that the loglevel ``logging.INFO`` will be set for the logger,
| whereas the string value ``debug`` will set the loglevel to
| ``logging.DEBUG``.
|
| Methods defined here:
|
| __get__(self, instance: 'Optional[Identified]', owner: 'Type[Identified]') -> 'Union[echo_property, _EchoFlagType]'
|
| __set__(self, instance: 'Identified', value: '_EchoFlagType') -> 'None'
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
FUNCTIONS
class_logger(cls: 'Type[_IT]') -> 'Type[_IT]'
instance_logger(instance: 'Identified', echoflag: '_EchoFlagType' = None) -> 'None'
create a logger for an instance that implements :class:`.Identified`.
DATA
Literal = typing.Literal
Special typing form to define literal types (a.k.a. value types).
This form can be used to indicate to type checkers that the corresponding
variable or function parameter has a value equivalent to the provided
literal (or one of several literals)::
def validate_simple(data: Any) -> Literal[True]: # always returns True
...
MODE = Literal['r', 'rb', 'w', 'wb']
def open_helper(file: str, mode: MODE) -> str:
...
open_helper('/some/path', 'r') # Passes type check
open_helper('/other/path', 'typo') # Error in type checker
Literal[...] cannot be subclassed. At runtime, an arbitrary value
is allowed as type argument to Literal[...], but type checkers may
impose restrictions.
Optional = typing.Optional
Optional[X] is equivalent to Union[X, None].
STACKLEVEL = True
STACKLEVEL_OFFSET = 2
Set = typing.Set
A generic version of set.
Type = typing.Type
Deprecated alias to builtins.type.
builtins.type or typing.Type can be used to annotate class objects.
For example, suppose we have the following classes::
class User: ... # Abstract base for User classes
class BasicUser(User): ...
class ProUser(User): ...
class TeamUser(User): ...
And a function that takes a class argument that's a subclass of
User and returns an instance of the corresponding class::
def new_user[U](user_class: Type[U]) -> U:
user = user_class()
# (Here we could write the user object to a database)
return user
joe = new_user(BasicUser)
At this point the type checker knows that joe has type BasicUser.
Union = typing.Union
Union type; Union[X, Y] means either X or Y.
On Python 3.10 and higher, the | operator
can also be used to denote unions;
X | Y means the same thing to the type checker as Union[X, Y].
To define a union, use e.g. Union[int, str]. Details:
- The arguments must be types and there must be at least one.
- None as an argument is a special case and is replaced by
type(None).
- Unions of unions are flattened, e.g.::
assert Union[Union[int, str], float] == Union[int, str, float]
- Unions of a single argument vanish, e.g.::
assert Union[int] == int # The constructor actually returns int
- Redundant arguments are skipped, e.g.::
assert Union[int, str, int] == Union[int, str]
- When comparing unions, the argument order is ignored, e.g.::
assert Union[int, str] == Union[str, int]
- You cannot subclass or instantiate a union.
- You can use Optional[X] as a shorthand for Union[X, None].
__annotations__ = {'_logged_classes': 'Set[Type[Identified]]'}
py311 = True
py38 = True
rootlogger = <Logger sqlalchemy (WARNING)>
FILE
c:\users\youse\appdata\local\programs\python\python312\lib\site-packages\sqlalchemy\log.py
sqlalchemy.make_url
Python Library Documentation: function make_url in module sqlalchemy.engine.url
make_url(name_or_url: 'Union[str, URL]') -> 'URL'
Given a string, produce a new URL instance.
The format of the URL generally follows `RFC-1738
<https://www.ietf.org/rfc/rfc1738.txt>`_, with some exceptions, including
that underscores, and not dashes or periods, are accepted within the
"scheme" portion.
If a :class:`.URL` object is passed, it is returned as is.
.. seealso::
:ref:`database_urls`
sqlalchemy.modifier
Python Library Documentation: _FunctionGenerator in module sqlalchemy.sql.functions object
class _FunctionGenerator(builtins.object)
| _FunctionGenerator(**opts: 'Any') -> 'None'
|
| Generate SQL function expressions.
|
| :data:`.func` is a special object instance which generates SQL
| functions based on name-based attributes, e.g.:
|
| .. sourcecode:: pycon+sql
|
| >>> print(func.count(1))
| {printsql}count(:param_1)
|
| The returned object is an instance of :class:`.Function`, and is a
| column-oriented SQL element like any other, and is used in that way:
|
| .. sourcecode:: pycon+sql
|
| >>> print(select(func.count(table.c.id)))
| {printsql}SELECT count(sometable.id) FROM sometable
|
| Any name can be given to :data:`.func`. If the function name is unknown to
| SQLAlchemy, it will be rendered exactly as is. For common SQL functions
| which SQLAlchemy is aware of, the name may be interpreted as a *generic
| function* which will be compiled appropriately to the target database:
|
| .. sourcecode:: pycon+sql
|
| >>> print(func.current_timestamp())
| {printsql}CURRENT_TIMESTAMP
|
| To call functions which are present in dot-separated packages,
| specify them in the same manner:
|
| .. sourcecode:: pycon+sql
|
| >>> print(func.stats.yield_curve(5, 10))
| {printsql}stats.yield_curve(:yield_curve_1, :yield_curve_2)
|
| SQLAlchemy can be made aware of the return type of functions to enable
| type-specific lexical and result-based behavior. For example, to ensure
| that a string-based function returns a Unicode value and is similarly
| treated as a string in expressions, specify
| :class:`~sqlalchemy.types.Unicode` as the type:
|
| .. sourcecode:: pycon+sql
|
| >>> print(
| ... func.my_string("hi", type_=Unicode)
| ... + " "
| ... + func.my_string("there", type_=Unicode)
| ... )
| {printsql}my_string(:my_string_1) || :my_string_2 || my_string(:my_string_3)
|
| The object returned by a :data:`.func` call is usually an instance of
| :class:`.Function`.
| This object meets the "column" interface, including comparison and labeling
| functions. The object can also be passed the :meth:`~.Connectable.execute`
| method of a :class:`_engine.Connection` or :class:`_engine.Engine`,
| where it will be
| wrapped inside of a SELECT statement first::
|
| print(connection.execute(func.current_timestamp()).scalar())
|
| In a few exception cases, the :data:`.func` accessor
| will redirect a name to a built-in expression such as :func:`.cast`
| or :func:`.extract`, as these names have well-known meaning
| but are not exactly the same as "functions" from a SQLAlchemy
| perspective.
|
| Functions which are interpreted as "generic" functions know how to
| calculate their return type automatically. For a listing of known generic
| functions, see :ref:`generic_functions`.
|
| .. note::
|
| The :data:`.func` construct has only limited support for calling
| standalone "stored procedures", especially those with special
| parameterization concerns.
|
| See the section :ref:`stored_procedures` for details on how to use
| the DBAPI-level ``callproc()`` method for fully traditional stored
| procedures.
|
| .. seealso::
|
| :ref:`tutorial_functions` - in the :ref:`unified_tutorial`
|
| :class:`.Function`
|
| Methods defined here:
|
| __call__(self, *c: 'Any', **kwargs: 'Any') -> 'Function[Any]'
| Call self as a function.
|
| __getattr__(self, name: 'str') -> '_FunctionGenerator'
|
| __init__(self, **opts: 'Any') -> 'None'
| Initialize self. See help(type(self)) for accurate signature.
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object
sqlalchemy.not_
Python Library Documentation: function not_ in module sqlalchemy.sql._elements_constructors
not_(clause: '_ColumnExpressionArgument[_T]') -> 'ColumnElement[_T]'
Return a negation of the given clause, i.e. ``NOT(clause)``.
The ``~`` operator is also overloaded on all
:class:`_expression.ColumnElement` subclasses to produce the
same result.
sqlalchemy.null
Python Library Documentation: function null in module sqlalchemy.sql._elements_constructors
null() -> 'Null'
Return a constant :class:`.Null` construct.
sqlalchemy.nulls_first
Python Library Documentation: function nulls_first in module sqlalchemy.sql._elements_constructors
nulls_first(column: '_ColumnExpressionArgument[_T]') -> 'UnaryExpression[_T]'
Produce the ``NULLS FIRST`` modifier for an ``ORDER BY`` expression.
:func:`.nulls_first` is intended to modify the expression produced
by :func:`.asc` or :func:`.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:
.. sourcecode:: sql
SELECT id, name FROM user ORDER BY name DESC NULLS FIRST
Like :func:`.asc` and :func:`.desc`, :func:`.nulls_first` is typically
invoked from the column expression itself using
:meth:`_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()
)
.. versionchanged:: 1.4 :func:`.nulls_first` is renamed from
:func:`.nullsfirst` in previous releases.
The previous name remains available for backwards compatibility.
.. seealso::
:func:`.asc`
:func:`.desc`
:func:`.nulls_last`
:meth:`_expression.Select.order_by`
sqlalchemy.nulls_last
Python Library Documentation: function nulls_last in module sqlalchemy.sql._elements_constructors
nulls_last(column: '_ColumnExpressionArgument[_T]') -> 'UnaryExpression[_T]'
Produce the ``NULLS LAST`` modifier for an ``ORDER BY`` expression.
:func:`.nulls_last` is intended to modify the expression produced
by :func:`.asc` or :func:`.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:
.. sourcecode:: sql
SELECT id, name FROM user ORDER BY name DESC NULLS LAST
Like :func:`.asc` and :func:`.desc`, :func:`.nulls_last` is typically
invoked from the column expression itself using
:meth:`_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())
.. versionchanged:: 1.4 :func:`.nulls_last` is renamed from
:func:`.nullslast` in previous releases.
The previous name remains available for backwards compatibility.
.. seealso::
:func:`.asc`
:func:`.desc`
:func:`.nulls_first`
:meth:`_expression.Select.order_by`
sqlalchemy.nullsfirst
Python Library Documentation: function nulls_first in module sqlalchemy.sql._elements_constructors
nulls_first(column: '_ColumnExpressionArgument[_T]') -> 'UnaryExpression[_T]'
Produce the ``NULLS FIRST`` modifier for an ``ORDER BY`` expression.
:func:`.nulls_first` is intended to modify the expression produced
by :func:`.asc` or :func:`.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:
.. sourcecode:: sql
SELECT id, name FROM user ORDER BY name DESC NULLS FIRST
Like :func:`.asc` and :func:`.desc`, :func:`.nulls_first` is typically
invoked from the column expression itself using
:meth:`_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()
)
.. versionchanged:: 1.4 :func:`.nulls_first` is renamed from
:func:`.nullsfirst` in previous releases.
The previous name remains available for backwards compatibility.
.. seealso::
:func:`.asc`
:func:`.desc`
:func:`.nulls_last`
:meth:`_expression.Select.order_by`
sqlalchemy.nullslast
Python Library Documentation: function nulls_last in module sqlalchemy.sql._elements_constructors
nulls_last(column: '_ColumnExpressionArgument[_T]') -> 'UnaryExpression[_T]'
Produce the ``NULLS LAST`` modifier for an ``ORDER BY`` expression.
:func:`.nulls_last` is intended to modify the expression produced
by :func:`.asc` or :func:`.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:
.. sourcecode:: sql
SELECT id, name FROM user ORDER BY name DESC NULLS LAST
Like :func:`.asc` and :func:`.desc`, :func:`.nulls_last` is typically
invoked from the column expression itself using
:meth:`_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())
.. versionchanged:: 1.4 :func:`.nulls_last` is renamed from
:func:`.nullslast` in previous releases.
The previous name remains available for backwards compatibility.
.. seealso::
:func:`.asc`
:func:`.desc`
:func:`.nulls_first`
:meth:`_expression.Select.order_by`
sqlalchemy.or_
Python Library Documentation: function or_ in module sqlalchemy.sql._elements_constructors
or_(*clauses)
Produce a conjunction of expressions joined by ``OR``.
E.g.::
from sqlalchemy import or_
stmt = select(users_table).where(
or_(users_table.c.name == "wendy", users_table.c.name == "jack")
)
The :func:`.or_` conjunction is also available using the
Python ``|`` operator (though note that compound expressions
need to be parenthesized in order to function with Python
operator precedence behavior)::
stmt = select(users_table).where(
(users_table.c.name == "wendy") | (users_table.c.name == "jack")
)
The :func:`.or_` construct must be given at least one positional
argument in order to be valid; a :func:`.or_` construct with no
arguments is ambiguous. To produce an "empty" or dynamically
generated :func:`.or_` expression, from a given list of expressions,
a "default" element of :func:`_sql.false` (or just ``False``) should be
specified::
from sqlalchemy import false
or_criteria = or_(false(), *expressions)
The above expression will compile to SQL as the expression ``false``
or ``0 = 1``, depending on backend, if no other expressions are
present. If expressions are present, then the :func:`_sql.false` value
is ignored as it does not affect the outcome of an OR expression which
has other elements.
.. deprecated:: 1.4 The :func:`.or_` element now requires that at
least one argument is passed; creating the :func:`.or_` construct
with no arguments is deprecated, and will emit a deprecation warning
while continuing to produce a blank SQL string.
.. seealso::
:func:`.and_`
sqlalchemy.outerjoin
Python Library Documentation: function outerjoin in module sqlalchemy.sql._selectable_constructors
outerjoin(left: '_FromClauseArgument', right: '_FromClauseArgument', onclause: 'Optional[_OnClauseArgument]' = None, full: 'bool' = False) -> 'Join'
Return an ``OUTER JOIN`` clause element.
The returned object is an instance of :class:`_expression.Join`.
Similar functionality is also available via the
:meth:`_expression.FromClause.outerjoin` method on any
:class:`_expression.FromClause`.
:param left: The left side of the join.
:param right: The right side of the join.
:param onclause: Optional criterion for the ``ON`` clause, is
derived from foreign key relationships established between
left and right otherwise.
To chain joins together, use the :meth:`_expression.FromClause.join`
or
:meth:`_expression.FromClause.outerjoin` methods on the resulting
:class:`_expression.Join` object.
sqlalchemy.outparam
Python Library Documentation: function outparam in module sqlalchemy.sql._elements_constructors
outparam(key: 'str', type_: 'Optional[TypeEngine[_T]]' = None) -> 'BindParameter[_T]'
Create an 'OUT' parameter for usage in functions (stored procedures),
for databases which support them.
The ``outparam`` can be used like a regular function parameter.
The "output" value will be available from the
:class:`~sqlalchemy.engine.CursorResult` object via its ``out_parameters``
attribute, which returns a dictionary containing the values.
sqlalchemy.over
Python Library Documentation: function over in module sqlalchemy.sql._elements_constructors
over(element: 'FunctionElement[_T]', partition_by: 'Optional[_ByArgument]' = None, order_by: 'Optional[_ByArgument]' = None, range_: 'Optional[typing_Tuple[Optional[int], Optional[int]]]' = None, rows: 'Optional[typing_Tuple[Optional[int], Optional[int]]]' = None, groups: 'Optional[typing_Tuple[Optional[int], Optional[int]]]' = None) -> 'Over[_T]'
Produce an :class:`.Over` object against a function.
Used against aggregate or so-called "window" functions,
for database backends that support window functions.
:func:`_expression.over` is usually called using
the :meth:`.FunctionElement.over` method, e.g.::
func.row_number().over(order_by=mytable.c.some_column)
Would produce:
.. sourcecode:: sql
ROW_NUMBER() OVER(ORDER BY some_column)
Ranges are also possible using the :paramref:`.expression.over.range_`,
:paramref:`.expression.over.rows`, and :paramref:`.expression.over.groups`
parameters. These
mutually-exclusive parameters each accept a 2-tuple, which contains
a combination of integers and None::
func.row_number().over(order_by=my_table.c.some_column, range_=(None, 0))
The above would produce:
.. sourcecode:: sql
ROW_NUMBER() OVER(ORDER BY some_column
RANGE BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW)
A value of ``None`` indicates "unbounded", a
value of zero indicates "current row", and negative / positive
integers indicate "preceding" and "following":
* RANGE BETWEEN 5 PRECEDING AND 10 FOLLOWING::
func.row_number().over(order_by="x", range_=(-5, 10))
* ROWS BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW::
func.row_number().over(order_by="x", rows=(None, 0))
* RANGE BETWEEN 2 PRECEDING AND UNBOUNDED FOLLOWING::
func.row_number().over(order_by="x", range_=(-2, None))
* RANGE BETWEEN 1 FOLLOWING AND 3 FOLLOWING::
func.row_number().over(order_by="x", range_=(1, 3))
* GROUPS BETWEEN 1 FOLLOWING AND 3 FOLLOWING::
func.row_number().over(order_by="x", groups=(1, 3))
:param element: a :class:`.FunctionElement`, :class:`.WithinGroup`,
or other compatible construct.
:param partition_by: a column element or string, or a list
of such, that will be used as the PARTITION BY clause
of the OVER construct.
:param order_by: a column element or string, or a list
of such, that will be used as the ORDER BY clause
of the OVER construct.
:param range\_: optional range clause for the window. This is a
tuple value which can contain integer values or ``None``,
and will render a RANGE BETWEEN PRECEDING / FOLLOWING clause.
:param rows: optional rows clause for the window. This is a tuple
value which can contain integer values or None, and will render
a ROWS BETWEEN PRECEDING / FOLLOWING clause.
:param groups: optional groups clause for the window. This is a
tuple value which can contain integer values or ``None``,
and will render a GROUPS BETWEEN PRECEDING / FOLLOWING clause.
.. versionadded:: 2.0.40
This function is also available from the :data:`~.expression.func`
construct itself via the :meth:`.FunctionElement.over` method.
.. seealso::
:ref:`tutorial_window_functions` - in the :ref:`unified_tutorial`
:data:`.expression.func`
:func:`_expression.within_group`
sqlalchemy.pool
Python Library Documentation: package sqlalchemy.pool in sqlalchemy
NAME
sqlalchemy.pool - Connection pooling for DB-API connections.
DESCRIPTION
Provides a number of connection pool implementations for a variety of
usage scenarios and thread behavior requirements imposed by the
application, DB-API or database itself.
Also provides a DB-API 2.0 connection proxying mechanism allowing
regular DB-API connect() methods to be transparently managed by a
SQLAlchemy connection pool.
PACKAGE CONTENTS
base
events
impl
DATA
reset_commit = <ResetStyle.reset_commit: 1>
reset_none = <ResetStyle.reset_none: 2>
reset_rollback = <ResetStyle.reset_rollback: 0>
FILE
c:\users\youse\appdata\local\programs\python\python312\lib\site-packages\sqlalchemy\pool\__init__.py
sqlalchemy.quoted_name
Python Library Documentation: class quoted_name in module sqlalchemy.sql.elements
class quoted_name(sqlalchemy.util.langhelpers.MemoizedSlots, builtins.str)
| quoted_name(value: 'str', quote: 'Optional[bool]') -> 'quoted_name'
|
| Represent a SQL identifier combined with quoting preferences.
|
| :class:`.quoted_name` is a Python unicode/str subclass which
| represents a particular identifier name along with a
| ``quote`` flag. This ``quote`` flag, when set to
| ``True`` or ``False``, overrides automatic quoting behavior
| for this identifier in order to either unconditionally quote
| or to not quote the name. If left at its default of ``None``,
| quoting behavior is applied to the identifier on a per-backend basis
| based on an examination of the token itself.
|
| A :class:`.quoted_name` object with ``quote=True`` is also
| prevented from being modified in the case of a so-called
| "name normalize" option. Certain database backends, such as
| Oracle Database, Firebird, and DB2 "normalize" case-insensitive names
| as uppercase. The SQLAlchemy dialects for these backends
| convert from SQLAlchemy's lower-case-means-insensitive convention
| to the upper-case-means-insensitive conventions of those backends.
| The ``quote=True`` flag here will prevent this conversion from occurring
| to support an identifier that's quoted as all lower case against
| such a backend.
|
| The :class:`.quoted_name` object is normally created automatically
| when specifying the name for key schema constructs such as
| :class:`_schema.Table`, :class:`_schema.Column`, and others.
| The class can also be
| passed explicitly as the name to any function that receives a name which
| can be quoted, such as :meth:`.Inspector.has_table` with an
| unconditionally quoted name::
|
| from sqlalchemy import create_engine
| from sqlalchemy import inspect
| from sqlalchemy.sql import quoted_name
|
| engine = create_engine("oracle+oracledb://some_dsn")
| print(inspect(engine).has_table(quoted_name("some_table", True)))
|
| The above logic will run the "has table" logic against the Oracle Database
| backend, passing the name exactly as ``"some_table"`` without converting to
| upper case.
|
| A :class:`.quoted_name` object with ``quote=False`` may be passed to APIs
| that apply automatic quoting in order to keep the given name unquoted,
| such as when a PostgreSQL ``INHERITS`` option refers to a schema-qualified
| table name like ``my_schema.some_table``.
|
| .. versionchanged:: 1.2 The :class:`.quoted_name` construct is now
| importable from ``sqlalchemy.sql``, in addition to the previous
| location of ``sqlalchemy.sql.elements``.
|
| Method resolution order:
| quoted_name
| sqlalchemy.util.langhelpers.MemoizedSlots
| builtins.str
| builtins.object
|
| Methods defined here:
|
| __reduce__(self)
| Helper for pickle.
|
| ----------------------------------------------------------------------
| Class methods defined here:
|
| construct(value: 'Optional[str]', quote: 'Optional[bool]') -> 'Optional[quoted_name]'
|
| ----------------------------------------------------------------------
| Static methods defined here:
|
| __new__(cls, value: 'str', quote: 'Optional[bool]') -> 'quoted_name'
| Create and return a new object. See help(type) for accurate signature.
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| lower
| Return a copy of the string converted to lowercase.
|
| quote
|
| upper
| Return a copy of the string converted to uppercase.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __annotations__ = {'quote': 'Optional[bool]'}
|
| ----------------------------------------------------------------------
| Methods inherited from sqlalchemy.util.langhelpers.MemoizedSlots:
|
| __getattr__(self, key: 'str') -> 'Any'
|
| ----------------------------------------------------------------------
| Methods inherited from builtins.str:
|
| __add__(self, value, /)
| Return self+value.
|
| __contains__(self, key, /)
| Return bool(key in self).
|
| __eq__(self, value, /)
| Return self==value.
|
| __format__(self, format_spec, /)
| Return a formatted version of the string as described by format_spec.
|
| __ge__(self, value, /)
| Return self>=value.
|
| __getitem__(self, key, /)
| Return self[key].
|
| __getnewargs__(...)
|
| __gt__(self, value, /)
| Return self>value.
|
| __hash__(self, /)
| Return hash(self).
|
| __iter__(self, /)
| Implement iter(self).
|
| __le__(self, value, /)
| Return self<=value.
|
| __len__(self, /)
| Return len(self).
|
| __lt__(self, value, /)
| Return self<value.
|
| __mod__(self, value, /)
| Return self%value.
|
| __mul__(self, value, /)
| Return self*value.
|
| __ne__(self, value, /)
| Return self!=value.
|
| __repr__(self, /)
| Return repr(self).
|
| __rmod__(self, value, /)
| Return value%self.
|
| __rmul__(self, value, /)
| Return value*self.
|
| __sizeof__(self, /)
| Return the size of the string in memory, in bytes.
|
| __str__(self, /)
| Return str(self).
|
| capitalize(self, /)
| Return a capitalized version of the string.
|
| More specifically, make the first character have upper case and the rest lower
| case.
|
| casefold(self, /)
| Return a version of the string suitable for caseless comparisons.
|
| center(self, width, fillchar=' ', /)
| Return a centered string of length width.
|
| Padding is done using the specified fill character (default is a space).
|
| count(...)
| S.count(sub[, start[, end]]) -> int
|
| Return the number of non-overlapping occurrences of substring sub in
| string S[start:end]. Optional arguments start and end are
| interpreted as in slice notation.
|
| encode(self, /, encoding='utf-8', errors='strict')
| Encode the string using the codec registered for encoding.
|
| encoding
| The encoding in which to encode the string.
| errors
| The error handling scheme to use for encoding errors.
| The default is 'strict' meaning that encoding errors raise a
| UnicodeEncodeError. Other possible values are 'ignore', 'replace' and
| 'xmlcharrefreplace' as well as any other name registered with
| codecs.register_error that can handle UnicodeEncodeErrors.
|
| endswith(...)
| S.endswith(suffix[, start[, end]]) -> bool
|
| Return True if S ends with the specified suffix, False otherwise.
| With optional start, test S beginning at that position.
| With optional end, stop comparing S at that position.
| suffix can also be a tuple of strings to try.
|
| expandtabs(self, /, tabsize=8)
| Return a copy where all tab characters are expanded using spaces.
|
| If tabsize is not given, a tab size of 8 characters is assumed.
|
| find(...)
| S.find(sub[, start[, end]]) -> int
|
| Return the lowest index in S where substring sub is found,
| such that sub is contained within S[start:end]. Optional
| arguments start and end are interpreted as in slice notation.
|
| Return -1 on failure.
|
| format(...)
| S.format(*args, **kwargs) -> str
|
| Return a formatted version of S, using substitutions from args and kwargs.
| The substitutions are identified by braces ('{' and '}').
|
| format_map(...)
| S.format_map(mapping) -> str
|
| Return a formatted version of S, using substitutions from mapping.
| The substitutions are identified by braces ('{' and '}').
|
| index(...)
| S.index(sub[, start[, end]]) -> int
|
| Return the lowest index in S where substring sub is found,
| such that sub is contained within S[start:end]. Optional
| arguments start and end are interpreted as in slice notation.
|
| Raises ValueError when the substring is not found.
|
| isalnum(self, /)
| Return True if the string is an alpha-numeric string, False otherwise.
|
| A string is alpha-numeric if all characters in the string are alpha-numeric and
| there is at least one character in the string.
|
| isalpha(self, /)
| Return True if the string is an alphabetic string, False otherwise.
|
| A string is alphabetic if all characters in the string are alphabetic and there
| is at least one character in the string.
|
| isascii(self, /)
| Return True if all characters in the string are ASCII, False otherwise.
|
| ASCII characters have code points in the range U+0000-U+007F.
| Empty string is ASCII too.
|
| isdecimal(self, /)
| Return True if the string is a decimal string, False otherwise.
|
| A string is a decimal string if all characters in the string are decimal and
| there is at least one character in the string.
|
| isdigit(self, /)
| Return True if the string is a digit string, False otherwise.
|
| A string is a digit string if all characters in the string are digits and there
| is at least one character in the string.
|
| isidentifier(self, /)
| Return True if the string is a valid Python identifier, False otherwise.
|
| Call keyword.iskeyword(s) to test whether string s is a reserved identifier,
| such as "def" or "class".
|
| islower(self, /)
| Return True if the string is a lowercase string, False otherwise.
|
| A string is lowercase if all cased characters in the string are lowercase and
| there is at least one cased character in the string.
|
| isnumeric(self, /)
| Return True if the string is a numeric string, False otherwise.
|
| A string is numeric if all characters in the string are numeric and there is at
| least one character in the string.
|
| isprintable(self, /)
| Return True if the string is printable, False otherwise.
|
| A string is printable if all of its characters are considered printable in
| repr() or if it is empty.
|
| isspace(self, /)
| Return True if the string is a whitespace string, False otherwise.
|
| A string is whitespace if all characters in the string are whitespace and there
| is at least one character in the string.
|
| istitle(self, /)
| Return True if the string is a title-cased string, False otherwise.
|
| In a title-cased string, upper- and title-case characters may only
| follow uncased characters and lowercase characters only cased ones.
|
| isupper(self, /)
| Return True if the string is an uppercase string, False otherwise.
|
| A string is uppercase if all cased characters in the string are uppercase and
| there is at least one cased character in the string.
|
| join(self, iterable, /)
| Concatenate any number of strings.
|
| The string whose method is called is inserted in between each given string.
| The result is returned as a new string.
|
| Example: '.'.join(['ab', 'pq', 'rs']) -> 'ab.pq.rs'
|
| ljust(self, width, fillchar=' ', /)
| Return a left-justified string of length width.
|
| Padding is done using the specified fill character (default is a space).
|
| lstrip(self, chars=None, /)
| Return a copy of the string with leading whitespace removed.
|
| If chars is given and not None, remove characters in chars instead.
|
| partition(self, sep, /)
| Partition the string into three parts using the given separator.
|
| This will search for the separator in the string. If the separator is found,
| returns a 3-tuple containing the part before the separator, the separator
| itself, and the part after it.
|
| If the separator is not found, returns a 3-tuple containing the original string
| and two empty strings.
|
| removeprefix(self, prefix, /)
| Return a str with the given prefix string removed if present.
|
| If the string starts with the prefix string, return string[len(prefix):].
| Otherwise, return a copy of the original string.
|
| removesuffix(self, suffix, /)
| Return a str with the given suffix string removed if present.
|
| If the string ends with the suffix string and that suffix is not empty,
| return string[:-len(suffix)]. Otherwise, return a copy of the original
| string.
|
| replace(self, old, new, count=-1, /)
| Return a copy with all occurrences of substring old replaced by new.
|
| count
| Maximum number of occurrences to replace.
| -1 (the default value) means replace all occurrences.
|
| If the optional argument count is given, only the first count occurrences are
| replaced.
|
| rfind(...)
| S.rfind(sub[, start[, end]]) -> int
|
| Return the highest index in S where substring sub is found,
| such that sub is contained within S[start:end]. Optional
| arguments start and end are interpreted as in slice notation.
|
| Return -1 on failure.
|
| rindex(...)
| S.rindex(sub[, start[, end]]) -> int
|
| Return the highest index in S where substring sub is found,
| such that sub is contained within S[start:end]. Optional
| arguments start and end are interpreted as in slice notation.
|
| Raises ValueError when the substring is not found.
|
| rjust(self, width, fillchar=' ', /)
| Return a right-justified string of length width.
|
| Padding is done using the specified fill character (default is a space).
|
| rpartition(self, sep, /)
| Partition the string into three parts using the given separator.
|
| This will search for the separator in the string, starting at the end. If
| the separator is found, returns a 3-tuple containing the part before the
| separator, the separator itself, and the part after it.
|
| If the separator is not found, returns a 3-tuple containing two empty strings
| and the original string.
|
| rsplit(self, /, sep=None, maxsplit=-1)
| Return a list of the substrings in the string, using sep as the separator string.
|
| sep
| The separator used to split the string.
|
| When set to None (the default value), will split on any whitespace
| character (including \n \r \t \f and spaces) and will discard
| empty strings from the result.
| maxsplit
| Maximum number of splits.
| -1 (the default value) means no limit.
|
| Splitting starts at the end of the string and works to the front.
|
| rstrip(self, chars=None, /)
| Return a copy of the string with trailing whitespace removed.
|
| If chars is given and not None, remove characters in chars instead.
|
| split(self, /, sep=None, maxsplit=-1)
| Return a list of the substrings in the string, using sep as the separator string.
|
| sep
| The separator used to split the string.
|
| When set to None (the default value), will split on any whitespace
| character (including \n \r \t \f and spaces) and will discard
| empty strings from the result.
| maxsplit
| Maximum number of splits.
| -1 (the default value) means no limit.
|
| Splitting starts at the front of the string and works to the end.
|
| Note, str.split() is mainly useful for data that has been intentionally
| delimited. With natural text that includes punctuation, consider using
| the regular expression module.
|
| splitlines(self, /, keepends=False)
| Return a list of the lines in the string, breaking at line boundaries.
|
| Line breaks are not included in the resulting list unless keepends is given and
| true.
|
| startswith(...)
| S.startswith(prefix[, start[, end]]) -> bool
|
| Return True if S starts with the specified prefix, False otherwise.
| With optional start, test S beginning at that position.
| With optional end, stop comparing S at that position.
| prefix can also be a tuple of strings to try.
|
| strip(self, chars=None, /)
| Return a copy of the string with leading and trailing whitespace removed.
|
| If chars is given and not None, remove characters in chars instead.
|
| swapcase(self, /)
| Convert uppercase characters to lowercase and lowercase characters to uppercase.
|
| title(self, /)
| Return a version of the string where each word is titlecased.
|
| More specifically, words start with uppercased characters and all remaining
| cased characters have lower case.
|
| translate(self, table, /)
| Replace each character in the string using the given translation table.
|
| table
| Translation table, which must be a mapping of Unicode ordinals to
| Unicode ordinals, strings, or None.
|
| The table must implement lookup/indexing via __getitem__, for instance a
| dictionary or list. If this operation raises LookupError, the character is
| left untouched. Characters mapped to None are deleted.
|
| zfill(self, width, /)
| Pad a numeric string with zeros on the left, to fill a field of the given width.
|
| The string is never truncated.
|
| ----------------------------------------------------------------------
| Static methods inherited from builtins.str:
|
| maketrans(...)
| Return a translation table usable for str.translate().
|
| If there is only one argument, it must be a dictionary mapping Unicode
| ordinals (integers) or characters to Unicode ordinals, strings or None.
| Character keys will be then converted to ordinals.
| If there are two arguments, they must be strings of equal length, and
| in the resulting dictionary, each character in x will be mapped to the
| character at the same position in y. If there is a third argument, it
| must be a string, whose characters will be mapped to None in the result.
sqlalchemy.result_tuple
Python Library Documentation: function result_tuple in module sqlalchemy.engine.result result_tuple(fields: 'Sequence[str]', extra: 'Optional[Any]' = None) -> 'Callable[[Iterable[Any]], Row[Any]]'
sqlalchemy.schema
Python Library Documentation: module sqlalchemy.schema in sqlalchemy
NAME
sqlalchemy.schema - Compatibility namespace for sqlalchemy.sql.schema and related.
DATA
BLANK_SCHEMA = <SchemaConst.BLANK_SCHEMA: 2>
FILE
c:\users\youse\appdata\local\programs\python\python312\lib\site-packages\sqlalchemy\schema.py
sqlalchemy.select
Python Library Documentation: function select in module sqlalchemy.sql._selectable_constructors
select(*entities: '_ColumnsClauseArgument[Any]', **__kw: 'Any') -> 'Select[Any]'
Construct a new :class:`_expression.Select`.
.. versionadded:: 1.4 - The :func:`_sql.select` function now accepts
column arguments positionally. The top-level :func:`_sql.select`
function will automatically use the 1.x or 2.x style API based on
the incoming arguments; using :func:`_sql.select` from the
``sqlalchemy.future`` module will enforce that only the 2.x style
constructor is used.
Similar functionality is also available via the
:meth:`_expression.FromClause.select` method on any
:class:`_expression.FromClause`.
.. seealso::
:ref:`tutorial_selecting_data` - in the :ref:`unified_tutorial`
:param \*entities:
Entities to SELECT from. For Core usage, this is typically a series
of :class:`_expression.ColumnElement` and / or
:class:`_expression.FromClause`
objects which will form the columns clause of the resulting
statement. For those objects that are instances of
:class:`_expression.FromClause` (typically :class:`_schema.Table`
or :class:`_expression.Alias`
objects), the :attr:`_expression.FromClause.c`
collection is extracted
to form a collection of :class:`_expression.ColumnElement` objects.
This parameter will also accept :class:`_expression.TextClause`
constructs as
given, as well as ORM-mapped classes.
sqlalchemy.sql
Python Library Documentation: package sqlalchemy.sql in sqlalchemy
NAME
sqlalchemy.sql
DESCRIPTION
# sql/__init__.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
PACKAGE CONTENTS
_dml_constructors
_elements_constructors
_orm_types
_py_util
_selectable_constructors
_typing
annotation
base
cache_key
coercions
compiler
crud
ddl
default_comparator
dml
elements
events
expression
functions
lambdas
naming
operators
roles
schema
selectable
sqltypes
traversals
type_api
util
visitors
DATA
COLLECT_CARTESIAN_PRODUCTS = <Linting.COLLECT_CARTESIAN_PRODUCTS: 1>
ColumnExpressionArgument = typing.Union[ForwardRef('ColumnElement[_T]'...
FROM_LINTING = <Linting.FROM_LINTING: 3>
LABEL_STYLE_DEFAULT = <SelectLabelStyle.LABEL_STYLE_DISAMBIGUATE_ONLY:...
LABEL_STYLE_DISAMBIGUATE_ONLY = <SelectLabelStyle.LABEL_STYLE_DISAMBIG...
LABEL_STYLE_NONE = <SelectLabelStyle.LABEL_STYLE_NONE: 0>
LABEL_STYLE_TABLENAME_PLUS_COL = <SelectLabelStyle.LABEL_STYLE_TABLENA...
NO_LINTING = <Linting.NO_LINTING: 0>
TYPE_CHECKING = False
WARN_LINTING = <Linting.WARN_LINTING: 2>
func = <sqlalchemy.sql.functions._FunctionGenerator object>
modifier = <sqlalchemy.sql.functions._FunctionGenerator object>
FILE
c:\users\youse\appdata\local\programs\python\python312\lib\site-packages\sqlalchemy\sql\__init__.py
sqlalchemy.table
Python Library Documentation: function table in module sqlalchemy.sql._selectable_constructors
table(name: 'str', *columns: 'ColumnClause[Any]', **kw: 'Any') -> 'TableClause'
Produce a new :class:`_expression.TableClause`.
The object returned is an instance of
:class:`_expression.TableClause`, which
represents the "syntactical" portion of the schema-level
:class:`_schema.Table` object.
It may be used to construct lightweight table constructs.
:param name: Name of the table.
:param columns: A collection of :func:`_expression.column` constructs.
:param schema: The schema name for this table.
.. versionadded:: 1.3.18 :func:`_expression.table` can now
accept a ``schema`` argument.
sqlalchemy.tablesample
Python Library Documentation: function tablesample in module sqlalchemy.sql._selectable_constructors
tablesample(selectable: '_FromClauseArgument', sampling: 'Union[float, Function[Any]]', name: 'Optional[str]' = None, seed: 'Optional[roles.ExpressionElementRole[Any]]' = None) -> 'TableSample'
Return a :class:`_expression.TableSample` object.
:class:`_expression.TableSample` is an :class:`_expression.Alias`
subclass that represents
a table with the TABLESAMPLE clause applied to it.
:func:`_expression.tablesample`
is also available from the :class:`_expression.FromClause`
class via the
:meth:`_expression.FromClause.tablesample` method.
The TABLESAMPLE clause allows selecting a randomly selected approximate
percentage of rows from a table. It supports multiple sampling methods,
most commonly BERNOULLI and SYSTEM.
e.g.::
from sqlalchemy import func
selectable = people.tablesample(
func.bernoulli(1), name="alias", seed=func.random()
)
stmt = select(selectable.c.people_id)
Assuming ``people`` with a column ``people_id``, the above
statement would render as:
.. sourcecode:: sql
SELECT alias.people_id FROM
people AS alias TABLESAMPLE bernoulli(:bernoulli_1)
REPEATABLE (random())
:param sampling: a ``float`` percentage between 0 and 100 or
:class:`_functions.Function`.
:param name: optional alias name
:param seed: any real-valued SQL expression. When specified, the
REPEATABLE sub-clause is also rendered.
sqlalchemy.text
Python Library Documentation: function text in module sqlalchemy.sql._elements_constructors
text(text: 'str') -> 'TextClause'
Construct a new :class:`_expression.TextClause` clause,
representing
a textual SQL string directly.
E.g.::
from sqlalchemy import text
t = text("SELECT * FROM users")
result = connection.execute(t)
The advantages :func:`_expression.text`
provides over a plain string are
backend-neutral support for bind parameters, per-statement
execution options, as well as
bind parameter and result-column typing behavior, allowing
SQLAlchemy type constructs to play a role when executing
a statement that is specified literally. The construct can also
be provided with a ``.c`` collection of column elements, allowing
it to be embedded in other SQL expression constructs as a subquery.
Bind parameters are specified by name, using the format ``:name``.
E.g.::
t = text("SELECT * FROM users WHERE id=:user_id")
result = connection.execute(t, {"user_id": 12})
For SQL statements where a colon is required verbatim, as within
an inline string, use a backslash to escape::
t = text(r"SELECT * FROM users WHERE name='\:username'")
The :class:`_expression.TextClause`
construct includes methods which can
provide information about the bound parameters as well as the column
values which would be returned from the textual statement, assuming
it's an executable SELECT type of statement. The
:meth:`_expression.TextClause.bindparams`
method is used to provide bound
parameter detail, and :meth:`_expression.TextClause.columns`
method allows
specification of return columns including names and types::
t = (
text("SELECT * FROM users WHERE id=:user_id")
.bindparams(user_id=7)
.columns(id=Integer, name=String)
)
for id, name in connection.execute(t):
print(id, name)
The :func:`_expression.text` construct is used in cases when
a literal string SQL fragment is specified as part of a larger query,
such as for the WHERE clause of a SELECT statement::
s = select(users.c.id, users.c.name).where(text("id=:user_id"))
result = connection.execute(s, {"user_id": 12})
:func:`_expression.text` is also used for the construction
of a full, standalone statement using plain text.
As such, SQLAlchemy refers
to it as an :class:`.Executable` object and may be used
like any other statement passed to an ``.execute()`` method.
:param text:
the text of the SQL statement to be created. Use ``:<param>``
to specify bind parameters; they will be compiled to their
engine-specific format.
.. warning:: The :paramref:`.text.text` argument to :func:`.text` can be passed as a Python string argument, which will be treated as **trusted SQL text** and rendered as given. **DO NOT PASS UNTRUSTED INPUT TO THIS PARAMETER**.
.. seealso::
:ref:`tutorial_select_arbitrary_text`
sqlalchemy.true
Python Library Documentation: function true in module sqlalchemy.sql._elements_constructors
true() -> 'True_'
Return a constant :class:`.True_` construct.
E.g.:
.. sourcecode:: pycon+sql
>>> from sqlalchemy import true
>>> print(select(t.c.x).where(true()))
{printsql}SELECT x FROM t WHERE true
A backend which does not support true/false constants will render as
an expression against 1 or 0:
.. sourcecode:: pycon+sql
>>> print(select(t.c.x).where(true()))
{printsql}SELECT x FROM t WHERE 1 = 1
The :func:`.true` and :func:`.false` constants also feature
"short circuit" operation within an :func:`.and_` or :func:`.or_`
conjunction:
.. sourcecode:: pycon+sql
>>> print(select(t.c.x).where(or_(t.c.x > 5, true())))
{printsql}SELECT x FROM t WHERE true{stop}
>>> print(select(t.c.x).where(and_(t.c.x > 5, false())))
{printsql}SELECT x FROM t WHERE false{stop}
.. seealso::
:func:`.false`
sqlalchemy.try_cast
Python Library Documentation: function try_cast in module sqlalchemy.sql._elements_constructors
try_cast(expression: '_ColumnExpressionOrLiteralArgument[Any]', type_: '_TypeEngineArgument[_T]') -> 'TryCast[_T]'
Produce a ``TRY_CAST`` expression for backends which support it;
this is a ``CAST`` which returns NULL for un-castable conversions.
In SQLAlchemy, this construct is supported **only** by the SQL Server
dialect, and will raise a :class:`.CompileError` if used on other
included backends. However, third party backends may also support
this construct.
.. tip:: As :func:`_sql.try_cast` originates from the SQL Server dialect,
it's importable both from ``sqlalchemy.`` as well as from
``sqlalchemy.dialects.mssql``.
:func:`_sql.try_cast` returns an instance of :class:`.TryCast` and
generally behaves similarly to the :class:`.Cast` construct;
at the SQL level, the difference between ``CAST`` and ``TRY_CAST``
is that ``TRY_CAST`` returns NULL for an un-castable expression,
such as attempting to cast a string ``"hi"`` to an integer value.
E.g.::
from sqlalchemy import select, try_cast, Numeric
stmt = select(try_cast(product_table.c.unit_price, Numeric(10, 4)))
The above would render on Microsoft SQL Server as:
.. sourcecode:: sql
SELECT TRY_CAST (product_table.unit_price AS NUMERIC(10, 4))
FROM product_table
.. versionadded:: 2.0.14 :func:`.try_cast` has been
generalized from the SQL Server dialect into a general use
construct that may be supported by additional dialects.
sqlalchemy.tuple_
Python Library Documentation: function tuple_ in module sqlalchemy.sql._elements_constructors
tuple_(*clauses: '_ColumnExpressionArgument[Any]', types: 'Optional[Sequence[_TypeEngineArgument[Any]]]' = None) -> 'Tuple'
Return a :class:`.Tuple`.
Main usage is to produce a composite IN construct using
:meth:`.ColumnOperators.in_` ::
from sqlalchemy import tuple_
tuple_(table.c.col1, table.c.col2).in_([(1, 2), (5, 12), (10, 19)])
.. versionchanged:: 1.3.6 Added support for SQLite IN tuples.
.. warning::
The composite IN construct is not supported by all backends, and is
currently known to work on PostgreSQL, MySQL, and SQLite.
Unsupported backends will raise a subclass of
:class:`~sqlalchemy.exc.DBAPIError` when such an expression is
invoked.
sqlalchemy.type_coerce
Python Library Documentation: function type_coerce in module sqlalchemy.sql._elements_constructors
type_coerce(expression: '_ColumnExpressionOrLiteralArgument[Any]', type_: '_TypeEngineArgument[_T]') -> 'TypeCoerce[_T]'
Associate a SQL expression with a particular type, without rendering
``CAST``.
E.g.::
from sqlalchemy import type_coerce
stmt = select(type_coerce(log_table.date_string, StringDateTime()))
The above construct will produce a :class:`.TypeCoerce` object, which
does not modify the rendering in any way on the SQL side, with the
possible exception of a generated label if used in a columns clause
context:
.. sourcecode:: sql
SELECT date_string AS date_string FROM log
When result rows are fetched, the ``StringDateTime`` type processor
will be applied to result rows on behalf of the ``date_string`` column.
.. note:: the :func:`.type_coerce` construct does not render any
SQL syntax of its own, including that it does not imply
parenthesization. Please use :meth:`.TypeCoerce.self_group`
if explicit parenthesization is required.
In order to provide a named label for the expression, use
:meth:`_expression.ColumnElement.label`::
stmt = select(
type_coerce(log_table.date_string, StringDateTime()).label("date")
)
A type that features bound-value handling will also have that behavior
take effect when literal values or :func:`.bindparam` constructs are
passed to :func:`.type_coerce` as targets.
For example, if a type implements the
:meth:`.TypeEngine.bind_expression`
method or :meth:`.TypeEngine.bind_processor` method or equivalent,
these functions will take effect at statement compilation/execution
time when a literal value is passed, as in::
# bound-value handling of MyStringType will be applied to the
# literal value "some string"
stmt = select(type_coerce("some string", MyStringType))
When using :func:`.type_coerce` with composed expressions, note that
**parenthesis are not applied**. If :func:`.type_coerce` is being
used in an operator context where the parenthesis normally present from
CAST are necessary, use the :meth:`.TypeCoerce.self_group` method:
.. sourcecode:: pycon+sql
>>> some_integer = column("someint", Integer)
>>> some_string = column("somestr", String)
>>> expr = type_coerce(some_integer + 5, String) + some_string
>>> print(expr)
{printsql}someint + :someint_1 || somestr{stop}
>>> expr = type_coerce(some_integer + 5, String).self_group() + some_string
>>> print(expr)
{printsql}(someint + :someint_1) || somestr{stop}
:param expression: A SQL expression, such as a
:class:`_expression.ColumnElement`
expression or a Python string which will be coerced into a bound
literal value.
:param type\_: A :class:`.TypeEngine` class or instance indicating
the type to which the expression is coerced.
.. seealso::
:ref:`tutorial_casts`
:func:`.cast`
sqlalchemy.types
Python Library Documentation: module sqlalchemy.types in sqlalchemy
NAME
sqlalchemy.types - Compatibility namespace for sqlalchemy.sql.types.
DATA
NULLTYPE = NullType()
STRINGTYPE = String()
FILE
c:\users\youse\appdata\local\programs\python\python312\lib\site-packages\sqlalchemy\types.py
sqlalchemy.union
Python Library Documentation: function union in module sqlalchemy.sql._selectable_constructors
union(*selects: '_SelectStatementForCompoundArgument[_TP]') -> 'CompoundSelect[_TP]'
Return a ``UNION`` of multiple selectables.
The returned object is an instance of
:class:`_expression.CompoundSelect`.
A similar :func:`union()` method is available on all
:class:`_expression.FromClause` subclasses.
:param \*selects:
a list of :class:`_expression.Select` instances.
:param \**kwargs:
available keyword arguments are the same as those of
:func:`select`.
sqlalchemy.union_all
Python Library Documentation: function union_all in module sqlalchemy.sql._selectable_constructors
union_all(*selects: '_SelectStatementForCompoundArgument[_TP]') -> 'CompoundSelect[_TP]'
Return a ``UNION ALL`` of multiple selectables.
The returned object is an instance of
:class:`_expression.CompoundSelect`.
A similar :func:`union_all()` method is available on all
:class:`_expression.FromClause` subclasses.
:param \*selects:
a list of :class:`_expression.Select` instances.
sqlalchemy.update
Python Library Documentation: function update in module sqlalchemy.sql._dml_constructors
update(table: '_DMLTableArgument') -> 'Update'
Construct an :class:`_expression.Update` object.
E.g.::
from sqlalchemy import update
stmt = (
update(user_table).where(user_table.c.id == 5).values(name="user #5")
)
Similar functionality is available via the
:meth:`_expression.TableClause.update` method on
:class:`_schema.Table`.
:param table: A :class:`_schema.Table`
object representing the database
table to be updated.
.. seealso::
:ref:`tutorial_core_update_delete` - in the :ref:`unified_tutorial`
sqlalchemy.util
Python Library Documentation: package sqlalchemy.util in sqlalchemy
NAME
sqlalchemy.util
DESCRIPTION
# util/__init__.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
PACKAGE CONTENTS
_collections
_concurrency_py3k
_has_cy
_py_collections
compat
concurrency
deprecations
langhelpers
preloaded
queue
tool_support
topological
typing
FUNCTIONS
anext_ = anext(...)
async anext(aiterator[, default])
Return the next item from the async iterator. If default is given and the async
iterator is exhausted, it is returned instead of raising StopAsyncIteration.
DATA
EMPTY_DICT = immutabledict({})
EMPTY_SET = frozenset()
NONE_SET = frozenset({None})
arm = False
cpython = True
freethreading = False
has_refcount_gc = True
is64bit = True
mini_gil = <contextlib.nullcontext object>
osx = False
py310 = True
py311 = True
py312 = True
py313 = False
py314 = False
py38 = True
py39 = True
pypy = False
win32 = True
FILE
c:\users\youse\appdata\local\programs\python\python312\lib\site-packages\sqlalchemy\util\__init__.py
sqlalchemy.values
Python Library Documentation: function values in module sqlalchemy.sql._selectable_constructors
values(*columns: '_OnlyColumnArgument[Any]', name: 'Optional[str]' = None, literal_binds: 'bool' = False) -> 'Values'
Construct a :class:`_expression.Values` construct representing the
SQL ``VALUES`` clause.
The column expressions and the actual data for :class:`_expression.Values`
are given in two separate steps. The constructor receives the column
expressions typically as :func:`_expression.column` constructs, and the
data is then passed via the :meth:`_expression.Values.data` method as a
list, which can be called multiple times to add more data, e.g.::
from sqlalchemy import column
from sqlalchemy import values
from sqlalchemy import Integer
from sqlalchemy import String
value_expr = (
values(
column("id", Integer),
column("name", String),
)
.data([(1, "name1"), (2, "name2")])
.data([(3, "name3")])
)
Would represent a SQL fragment like::
VALUES(1, "name1"), (2, "name2"), (3, "name3")
The :class:`_sql.values` construct has an optional
:paramref:`_sql.values.name` field; when using this field, the
PostgreSQL-specific "named VALUES" clause may be generated::
value_expr = values(
column("id", Integer), column("name", String), name="somename"
).data([(1, "name1"), (2, "name2"), (3, "name3")])
When selecting from the above construct, the name and column names will
be listed out using a PostgreSQL-specific syntax::
>>> print(value_expr.select())
SELECT somename.id, somename.name
FROM (VALUES (:param_1, :param_2), (:param_3, :param_4),
(:param_5, :param_6)) AS somename (id, name)
For a more database-agnostic means of SELECTing named columns from a
VALUES expression, the :meth:`.Values.cte` method may be used, which
produces a named CTE with explicit column names against the VALUES
construct within; this syntax works on PostgreSQL, SQLite, and MariaDB::
value_expr = (
values(
column("id", Integer),
column("name", String),
)
.data([(1, "name1"), (2, "name2"), (3, "name3")])
.cte()
)
Rendering as::
>>> print(value_expr.select())
WITH anon_1(id, name) AS
(VALUES (:param_1, :param_2), (:param_3, :param_4), (:param_5, :param_6))
SELECT anon_1.id, anon_1.name
FROM anon_1
.. versionadded:: 2.0.42 Added the :meth:`.Values.cte` method to
:class:`.Values`
:param \*columns: column expressions, typically composed using
:func:`_expression.column` objects.
:param name: the name for this VALUES construct. If omitted, the
VALUES construct will be unnamed in a SQL expression. Different
backends may have different requirements here.
:param literal_binds: Defaults to False. Whether or not to render
the data values inline in the SQL output, rather than using bound
parameters.
sqlalchemy.within_group
Python Library Documentation: function within_group in module sqlalchemy.sql._elements_constructors
within_group(element: 'FunctionElement[_T]', *order_by: '_ColumnExpressionArgument[Any]') -> 'WithinGroup[_T]'
Produce a :class:`.WithinGroup` object against a function.
Used against so-called "ordered set aggregate" and "hypothetical
set aggregate" functions, including :class:`.percentile_cont`,
:class:`.rank`, :class:`.dense_rank`, etc.
:func:`_expression.within_group` is usually called using
the :meth:`.FunctionElement.within_group` method, e.g.::
from sqlalchemy import within_group
stmt = select(
department.c.id,
func.percentile_cont(0.5).within_group(department.c.salary.desc()),
)
The above statement would produce SQL similar to
``SELECT department.id, percentile_cont(0.5)
WITHIN GROUP (ORDER BY department.salary DESC)``.
:param element: a :class:`.FunctionElement` construct, typically
generated by :data:`~.expression.func`.
:param \*order_by: one or more column elements that will be used
as the ORDER BY clause of the WITHIN GROUP construct.
.. seealso::
:ref:`tutorial_functions_within_group` - in the
:ref:`unified_tutorial`
:data:`.expression.func`
:func:`_expression.over`