:versions: 0.8.3, 0.9.0b1
Fixed bug in :class:`.CheckConstraint` DDL where the "quote" flag from a
- :class:`.Column` object would not be propagated.
+ :class:`_schema.Column` object would not be propagated.
.. change::
:tags: bug, orm
:tickets: 2604
:versions: 0.8.0b2
- Fixed :meth:`.MetaData.reflect` to correctly use
- the given :class:`.Connection`, if given, without
+ Fixed :meth:`_schema.MetaData.reflect` to correctly use
+ the given :class:`_engine.Connection`, if given, without
opening a second connection from that connection's
- :class:`.Engine`.
+ :class:`_engine.Engine`.
.. change::
:tags: mssql, bug
:tags: sql, bug
:tickets: 2643
- Fixed bug where :meth:`.Table.tometadata` would fail if a
- :class:`.Column` had both a foreign key as well as an
+ Fixed bug where :meth:`_schema.Table.tometadata` would fail if a
+ :class:`_schema.Column` had both a foreign key as well as an
alternate ".key" name for the column.
.. change::
:tags: orm, bug
:tickets: 2640
- :meth:`.Query.merge_result` can now load rows from an outer join
+ :meth:`_query.Query.merge_result` can now load rows from an outer join
where an entity may be ``None`` without throwing an error.
.. change::
Fixed bug in :class:`.Enum` and other :class:`.SchemaType`
subclasses where direct association of the type with a
- :class:`.MetaData` would lead to a hang when events
- (like create events) were emitted on the :class:`.MetaData`.
+ :class:`_schema.MetaData` would lead to a hang when events
+ (like create events) were emitted on the :class:`_schema.MetaData`.
.. change::
:tags: bug, sql
:tickets: 3045
:versions: 0.9.5, 1.0.0b1
- Fixed bug where :meth:`.Table.update` and :meth:`.Table.delete`
+ Fixed bug where :meth:`_schema.Table.update` and :meth:`_schema.Table.delete`
would produce an empty WHERE clause when an empty :func:`.and_()`
or :func:`.or_()` or other blank expression were applied. This is
- now consistent with that of :func:`~.sql.expression.select`.
+ now consistent with that of :func:`_expression.select`.
.. change::
:tags: bug, postgresql
:versions: 0.9.4
Fixed regression from 0.8.3 as a result of :ticket:`2818`
- where :meth:`.Query.exists` wouldn't work on a query that only
- had a :meth:`.Query.select_from` entry but no other entities.
+ where :meth:`_query.Query.exists` wouldn't work on a query that only
+ had a :meth:`_query.Query.select_from` entry but no other entities.
.. change::
:tags: bug, general
:versions: 0.9.4
Improved an error message which would occur if a query() were made
- against a non-selectable, such as a :func:`.literal_column`, and then
- an attempt was made to use :meth:`.Query.join` such that the "left"
+ against a non-selectable, such as a :func:`_expression.literal_column`, and then
+ an attempt was made to use :meth:`_query.Query.join` such that the "left"
side would be determined as ``None`` and then fail. This condition
is now detected explicitly.
Added support for the ``PARTITION BY`` and ``PARTITIONS``
MySQL table keywords, specified as ``mysql_partition_by='value'`` and
- ``mysql_partitions='value'`` to :class:`.Table`. Pull request
+ ``mysql_partitions='value'`` to :class:`_schema.Table`. Pull request
courtesy Marcus McCurdy.
.. change::
:versions: 0.9.3
:tickets: 2944
- Fixed bug where calling :meth:`.Insert.values` with an empty list
+ Fixed bug where calling :meth:`_expression.Insert.values` with an empty list
or tuple would raise an IndexError. It now produces an empty
insert construct as would be the case with an empty dictionary.
Fixed bug where :meth:`.ColumnOperators.in_()` would go into an endless
loop if erroneously passed a column expression whose comparator
included the ``__getitem__()`` method, such as a column that uses the
- :class:`.postgresql.ARRAY` type.
+ :class:`_postgresql.ARRAY` type.
.. change::
:tags: bug, orm
:tickets: 2951
:versions: 0.9.3
- Fixed bug where :meth:`.Query.get` would fail to consistently
+ Fixed bug where :meth:`_query.Query.get` would fail to consistently
raise the :class:`.InvalidRequestError` that invokes when called
on a query with existing criterion, when the given identity is
already present in the identity map.
:versions: 0.9.0
:tickets: 2895
- Fixed bug with :meth:`.Insert.from_select` method where the order
+ Fixed bug with :meth:`_expression.Insert.from_select` method where the order
of the given names would not be taken into account when generating
the INSERT statement, thus producing a mismatch versus the column
names in the given SELECT statement. Also noted that
- :meth:`.Insert.from_select` implies that Python-side insert defaults
+ :meth:`_expression.Insert.from_select` implies that Python-side insert defaults
cannot be used, since the statement has no VALUES clause.
.. change::
:versions: 0.9.0
:tickets: 2888
- Error message when a string arg sent to :func:`.relationship` which
+ Error message when a string arg sent to :func:`_orm.relationship` which
doesn't resolve to a class or mapper has been corrected to work
the same way as when a non-string arg is received, which indicates
the name of the relationship which had the configurational error.
:versions: 0.9.0b1
Added support for "unique constraint" reflection, via the
- :meth:`.Inspector.get_unique_constraints` method.
+ :meth:`_reflection.Inspector.get_unique_constraints` method.
Thanks for Roman Podolyaka for the patch.
.. change::
Fixed bug where SQL statement would be improperly ASCII-encoded
when a pre-DBAPI :class:`.StatementError` were raised within
- :meth:`.Connection.execute`, causing encoding errors for
+ :meth:`_engine.Connection.execute`, causing encoding errors for
non-ASCII statements. The stringification now remains within
Python unicode thus avoiding encoding errors.
:versions: 0.9.0b1
The change in :ticket:`2721`, which is that the ``deferrable`` keyword
- of :class:`.ForeignKeyConstraint` is silently ignored on the MySQL
+ of :class:`_schema.ForeignKeyConstraint` is silently ignored on the MySQL
backend, will be reverted as of 0.9; this keyword will now render again, raising
errors on MySQL as it is not understood - the same behavior will also
apply to the ``initially`` keyword. In 0.8, the keywords will remain
this keyword is not only silently ignored by MySQL but also breaks
the ON UPDATE/ON DELETE options.
- To use a :class:`.ForeignKeyConstraint`
+ To use a :class:`_schema.ForeignKeyConstraint`
that does not render or renders differently on MySQL, use a custom
compilation option. An example of this usage has been added to the
documentation, see :ref:`mysql_foreign_keys`.
:versions: 0.9.0b1
The ``.unique`` flag on :class:`.Index` could be produced as ``None``
- if it was generated from a :class:`.Column` that didn't specify ``unique``
+ if it was generated from a :class:`_schema.Column` that didn't specify ``unique``
(where it defaults to ``None``). The flag will now always be ``True`` or
``False``.
:tickets: 2836
:versions: 0.9.0b1
- Added new option to :func:`.relationship` ``distinct_target_key``.
+ Added new option to :func:`_orm.relationship` ``distinct_target_key``.
This enables the subquery eager loader strategy to apply a DISTINCT
to the innermost SELECT subquery, to assist in the case where
duplicate rows are generated by the innermost query which corresponds
:tickets: 2815
:versions: 0.9.0b1
- A :func:`~.sql.expression.select` that is made to refer to itself in its FROM clause,
+ A :func:`_expression.select` that is made to refer to itself in its FROM clause,
typically via in-place mutation, will raise an informative error
message rather than causing a recursion overflow.
:versions: 0.9.0b1
Fixed bug where using an annotation such as :func:`.remote` or
- :func:`.foreign` on a :class:`.Column` before association with a parent
- :class:`.Table` could produce issues related to the parent table not
+ :func:`.foreign` on a :class:`_schema.Column` before association with a parent
+ :class:`_schema.Table` could produce issues related to the parent table not
rendering within joins, due to the inherent copy operation performed
by an annotation.
:tags: bug, sql
:tickets: 2831
- Non-working "schema" argument on :class:`.ForeignKey` is deprecated;
+ Non-working "schema" argument on :class:`_schema.ForeignKey` is deprecated;
raises a warning. Removed in 0.9.
.. change::
:tickets: 2821
:versions: 0.9.0b1
- ``repr()`` for the :class:`.URL` of an :class:`.Engine`
+ ``repr()`` for the :class:`.URL` of an :class:`_engine.Engine`
will now conceal the password using asterisks.
Courtesy Gunnlaugur Þór Briem.
:tickets: 2818
:versions: 0.9.0b1
- Fixed bug where :meth:`.Query.exists` failed to work correctly
+ Fixed bug where :meth:`_query.Query.exists` failed to work correctly
without any WHERE criterion. Courtesy Vladimir Magamedov.
.. change::
:versions: 0.9.0b1
Fixed bug where using the ``column_reflect`` event to change the ``.key``
- of the incoming :class:`.Column` would prevent primary key constraints,
+ of the incoming :class:`_schema.Column` would prevent primary key constraints,
indexes, and foreign key constraints from being correctly reflected.
.. change::
:tags: feature
:versions: 0.9.0b1
- Added a new flag ``system=True`` to :class:`.Column`, which marks
+ Added a new flag ``system=True`` to :class:`_schema.Column`, which marks
the column as a "system" column which is automatically made present
by the database (such as PostgreSQL ``oid`` or ``xmin``). The
column will be omitted from the ``CREATE TABLE`` statement but will
:tickets: 2776
:versions: 0.9.0b1
- Dialect.initialize() is not called a second time if an :class:`.Engine`
+ Dialect.initialize() is not called a second time if an :class:`_engine.Engine`
is recreated, due to a disconnect error. This fixes a particular
issue in the Oracle 8 dialect, but in general the dialect.initialize()
phase should only be once per dialect.
:tags: feature, sql
:tickets: 722
- Added new method to the :func:`~.sql.expression.insert` construct
- :meth:`.Insert.from_select`. Given a list of columns and
+ Added new method to the :func:`_expression.insert` construct
+ :meth:`_expression.Insert.from_select`. Given a list of columns and
a selectable, renders ``INSERT INTO (table) (columns) SELECT ..``.
.. change::
:tags: feature, sql
:versions: 0.9.0b1
- The :func:`.update`, :func:`~.sql.expression.insert`, and :func:`.delete` constructs
+ The :func:`_expression.update`, :func:`_expression.insert`, and :func:`_expression.delete` constructs
will now interpret ORM entities as target tables to be operated upon,
e.g.::
ORM descriptors such as hybrid properties can now be referenced
by name in a string argument used with ``order_by``,
- ``primaryjoin``, or similar in :func:`.relationship`,
+ ``primaryjoin``, or similar in :func:`_orm.relationship`,
in addition to column-bound attributes.
.. change::
:versions: 0.9.0b1
Multiple fixes to the correlation behavior of
- :class:`.Select` constructs, first introduced in 0.8.0:
+ :class:`_expression.Select` constructs, first introduced in 0.8.0:
* To satisfy the use case where FROM entries should be
correlated outwards to a SELECT that encloses another,
which then encloses this one, correlation now works
across multiple levels when explicit correlation is
- established via :meth:`.Select.correlate`, provided
+ established via :meth:`_expression.Select.correlate`, provided
that the target select is somewhere along the chain
contained by a WHERE/ORDER BY/columns clause, not
just nested FROM clauses. This makes
- :meth:`.Select.correlate` act more compatibly to
+ :meth:`_expression.Select.correlate` act more compatibly to
that of 0.7 again while still maintaining the new
"smart" correlation.
across nested FROMs in this case, maintaining compatibility
with 0.8.0/0.8.1.
- * The :meth:`.Select.correlate_except` method was not
+ * The :meth:`_expression.Select.correlate_except` method was not
preventing the given FROM clauses from correlation in
all cases, and also would cause FROM clauses to be incorrectly
omitted entirely (more like what 0.7 would do),
:tags: bug, engine
:versions: 0.9.0b1
- Fixed bug where the ``reset_on_return`` argument to various :class:`.Pool`
+ Fixed bug where the ``reset_on_return`` argument to various :class:`_pool.Pool`
implementations would not be propagated when the pool was regenerated.
Courtesy Eevee.
:tickets: 2754
:versions: 0.9.0b1
- Fixed bug where sending a composite attribute into :meth:`.Query.order_by`
+ Fixed bug where sending a composite attribute into :meth:`_query.Query.order_by`
would produce a parenthesized expression not accepted by some databases.
.. change::
:tickets: 2721
:versions: 0.9.0b1
- The ``deferrable`` keyword argument on :class:`.ForeignKey` and
- :class:`.ForeignKeyConstraint` will not render the ``DEFERRABLE`` keyword
+ The ``deferrable`` keyword argument on :class:`_schema.ForeignKey` and
+ :class:`_schema.ForeignKeyConstraint` will not render the ``DEFERRABLE`` keyword
on the MySQL dialect. For a long time we left this in place because
a non-deferrable foreign key would act very differently than a deferrable
one, but some environments just disable FKs on MySQL, so we'll be less
:tickets: 2728
:versions: 0.9.0b1
- Fixed bug whereby using :meth:`.MetaData.reflect` across a remote
+ Fixed bug whereby using :meth:`_schema.MetaData.reflect` across a remote
schema as well as a local schema could produce wrong results
in the case where both schemas had a table of the same name.
:tags: feature, orm
:tickets: 2736
- Added a new method :meth:`.Query.select_entity_from` which
+ Added a new method :meth:`_query.Query.select_entity_from` which
will in 0.9 replace part of the functionality of
- :meth:`.Query.select_from`. In 0.8, the two methods perform
+ :meth:`_query.Query.select_from`. In 0.8, the two methods perform
the same function, so that code can be migrated to use the
- :meth:`.Query.select_entity_from` method as appropriate.
+ :meth:`_query.Query.select_entity_from` method as appropriate.
See the 0.9 migration guide for details.
.. change::
:tickets: 2737
Fixed a regression caused by :ticket:`2682` whereby the
- evaluation invoked by :meth:`.Query.update` and :meth:`.Query.delete`
+ evaluation invoked by :meth:`_query.Query.update` and :meth:`_query.Query.delete`
would hit upon unsupported ``True`` and ``False`` symbols
which now appear due to the usage of ``IS``.
Fixed a small bug in the dogpile example where the generation
of SQL cache keys wasn't applying deduping labels to the
- statement the same way :class:`.Query` normally does.
+ statement the same way :class:`_query.Query` normally does.
.. change::
:tags: bug, engine, sybase
A meaningful :attr:`.QueryableAttribute.info` attribute is
added, which proxies down to the ``.info`` attribute on either
- the :class:`.schema.Column` object if directly present, or
+ the :class:`_schema.Column` object if directly present, or
the :class:`.MapperProperty` otherwise. The full behavior
is documented and ensured by tests to remain stable.
:tickets: 2668
The behavior of SELECT correlation has been improved such that
- the :meth:`.Select.correlate` and :meth:`.Select.correlate_except`
+ the :meth:`_expression.Select.correlate` and :meth:`_expression.Select.correlate_except`
methods, as well as their ORM analogues, will still retain
"auto-correlation" behavior in that the FROM clause is modified
only if the output would be legal SQL; that is, the FROM clause
.. change::
:tags: feature, orm
- Can set/change the "cascade" attribute on a :func:`.relationship`
+ Can set/change the "cascade" attribute on a :func:`_orm.relationship`
construct after it's been constructed already. This is not
a pattern for normal use but we like to change the setting
for demonstration purposes in tutorials.
:tags: bug, schema
:tickets: 2664
- :meth:`.MetaData.create_all` and :meth:`.MetaData.drop_all` will
+ :meth:`_schema.MetaData.create_all` and :meth:`_schema.MetaData.drop_all` will
now accommodate an empty list as an instruction to not create/drop
any items, rather than ignoring the collection.
:tags: bug, orm
:tickets: 2661
- Fixed bug whereby :meth:`.Query.yield_per` would set the execution
+ Fixed bug whereby :meth:`_query.Query.yield_per` would set the execution
options incorrectly, thereby breaking subsequent usage of the
- :meth:`.Query.execution_options` method. Courtesy Ryan Kelly.
+ :meth:`_query.Query.execution_options` method. Courtesy Ryan Kelly.
.. change::
:tags: bug, orm
:tickets: 2660, 1768
Fixed a bug regarding column annotations which in particular
- could impact some usages of the new :func:`.orm.remote` and
- :func:`.orm.local` annotation functions, where annotations
+ could impact some usages of the new :func:`_orm.remote` and
+ :func:`_orm.local` annotation functions, where annotations
could be lost when the column were used in a subsequent
expression.
Added a new argument to :class:`.Enum` and its base
:class:`.SchemaType` ``inherit_schema``. When set to ``True``,
the type will set its ``schema`` attribute of that of the
- :class:`.Table` to which it is associated. This also occurs
- during a :meth:`.Table.tometadata` operation; the :class:`.SchemaType`
- is now copied in all cases when :meth:`.Table.tometadata` happens,
+ :class:`_schema.Table` to which it is associated. This also occurs
+ during a :meth:`_schema.Table.tometadata` operation; the :class:`.SchemaType`
+ is now copied in all cases when :meth:`_schema.Table.tometadata` happens,
and if ``inherit_schema=True``, the type will take on the new
schema name passed to the method. The ``schema`` is important
when used with the PostgreSQL backend, as the type results in
:tags: sql, bug
:tickets: 2643
- Fixed bug where :meth:`.Table.tometadata` would fail if a
- :class:`.Column` had both a foreign key as well as an
+ Fixed bug where :meth:`_schema.Table.tometadata` would fail if a
+ :class:`_schema.Column` had both a foreign key as well as an
alternate ".key" name for the column. Also in 0.7.10.
.. change::
de-associated from any of its orphan-enabled parents. Previously,
the pending object would be expunged only if de-associated
from all of its orphan-enabled parents. The new flag ``legacy_is_orphan``
- is added to :func:`.orm.mapper` which re-establishes the
+ is added to :func:`_orm.mapper` which re-establishes the
legacy behavior.
See the change note and example case at :ref:`legacy_is_orphan_addition`
:tags: orm, bug
:tickets: 2640
- :meth:`.Query.merge_result` can now load rows from an outer join
+ :meth:`_query.Query.merge_result` can now load rows from an outer join
where an entity may be ``None`` without throwing an error.
Also in 0.7.10.
:tags: postgresql, bug
Fixed bug in :class:`~sqlalchemy.dialects.postgresql.array()` construct whereby using it
- inside of an :func:`.expression.insert` construct would produce an
+ inside of an :func:`_expression.insert` construct would produce an
error regarding a parameter issue in the ``self_group()`` method.
.. change::
This fulfills the common request of being able to inspect
all :class:`.QueryableAttribute` descriptors in addition to
extension types such as :class:`.hybrid_property` and
- :class:`.AssociationProxy`. See :attr:`.Mapper.all_orm_descriptors`.
+ :class:`.AssociationProxy`. See :attr:`_orm.Mapper.all_orm_descriptors`.
.. change::
:tags: mysql, feature
:tags: orm, bug
:tickets: 2637
- Fixes to the "dynamic" loader on :func:`.relationship`, includes
+ Fixes to the "dynamic" loader on :func:`_orm.relationship`, includes
that backrefs will work properly even when autoflush is disabled,
history events are more accurate in scenarios where multiple add/remove
of the same object occurs.
:tags: orm, bug
:tickets: 2635
- The :meth:`.Query.select_from` method can now be used with a
+ The :meth:`_query.Query.select_from` method can now be used with a
:func:`.aliased` construct without it interfering with the entities
being selected. Basically, a statement like this::
JOIN users ON users.name < users_1.name
Note that this behavior is in contrast
- to the original, older use case for :meth:`.Query.select_from`, which is that
+ to the original, older use case for :meth:`_query.Query.select_from`, which is that
of restating the mapped entity in terms of a different selectable::
session.query(User.name).\
It was the "aliasing" behavior of the latter use case that was
getting in the way of the former use case. The method now
specifically considers a SQL expression like
- :func:`.expression.select` or :func:`.expression.alias`
+ :func:`_expression.select` or :func:`_expression.alias`
separately from a mapped entity like a :func:`.aliased`
construct.
Fixed a regression caused by :ticket:`2410` whereby a
:class:`.CheckConstraint` would apply itself back to the
- original table during a :meth:`.Table.tometadata` operation, as
+ original table during a :meth:`_schema.Table.tometadata` operation, as
it would parse the SQL expression for a parent table. The
operation now copies the given expression to correspond to the
new table.
:tags: sql, feature
:tickets: 2623
- The :class:`~.sql.expression.Insert` construct now supports multi-valued inserts,
+ The :class:`_expression.Insert` construct now supports multi-valued inserts,
that is, an INSERT that renders like
"INSERT INTO table VALUES (...), (...), ...".
Supported by PostgreSQL, SQLite, and MySQL.
:tags: sql, bug
Fixed a gotcha where inadvertently calling list() on a
- :class:`.ColumnElement` would go into an endless loop, if
+ :class:`_expression.ColumnElement` would go into an endless loop, if
:meth:`.ColumnOperators.__getitem__` were implemented.
A new NotImplementedError is emitted via ``__iter__()``.
.. change::
:tags: engine, feature
- The :meth:`.Connection.connect` and :meth:`.Connection.contextual_connect`
- methods now return a "branched" version so that the :meth:`.Connection.close`
+ The :meth:`_engine.Connection.connect` and :meth:`_engine.Connection.contextual_connect`
+ methods now return a "branched" version so that the :meth:`_engine.Connection.close`
method can be called on the returned connection without affecting the
- original. Allows symmetry when using :class:`.Engine` and
- :class:`.Connection` objects as context managers::
+ original. Allows symmetry when using :class:`_engine.Engine` and
+ :class:`_engine.Connection` objects as context managers::
with conn.connect() as c: # leaves the Connection open
c.execute("...")
:tags: engine
The "reflect=True" argument to :class:`~sqlalchemy.schema.MetaData` is deprecated.
- Please use the :meth:`.MetaData.reflect` method.
+ Please use the :meth:`_schema.MetaData.reflect` method.
.. change::
:tags: sql, bug
.. change::
:tags: pool, feature
- The :class:`.Pool` will now log all connection.close()
+ The :class:`_pool.Pool` will now log all connection.close()
operations equally, including closes which occur for
invalidated connections, detached connections, and connections
beyond the pool capacity.
:tags: pool, feature
:tickets: 2611
- The :class:`.Pool` now consults the :class:`.Dialect` for
+ The :class:`_pool.Pool` now consults the :class:`.Dialect` for
functionality regarding how the connection should be
"auto rolled back", as well as closed. This grants more
control of transaction scope to the dialect, so that we
.. change::
:tags: pool, feature
- Added new :meth:`.PoolEvents.reset` hook to capture
+ Added new :meth:`_events.PoolEvents.reset` hook to capture
the event before a connection is auto-rolled back, upon
return to the pool. Together with
:meth:`.ConnectionEvents.rollback` this allows all rollback
.. change::
:tags: sql, feature
- Added a new method :meth:`.Engine.execution_options`
- to :class:`.Engine`. This method works similarly to
- :meth:`.Connection.execution_options` in that it creates
+ Added a new method :meth:`_engine.Engine.execution_options`
+ to :class:`_engine.Engine`. This method works similarly to
+ :meth:`_engine.Connection.execution_options` in that it creates
a copy of the parent object which will refer to the new
set of options. The method can be used to build
sharding schemes where each engine shares the same
.. seealso::
- :meth:`.Engine.execution_options`
+ :meth:`_engine.Engine.execution_options`
.. change::
:tags: sql, orm, bug
:tickets: 2595
- The auto-correlation feature of :func:`~.sql.expression.select`, and
- by proxy that of :class:`.Query`, will not
+ The auto-correlation feature of :func:`_expression.select`, and
+ by proxy that of :class:`_query.Query`, will not
take effect for a SELECT statement that is being
rendered directly in the FROM list of the enclosing
SELECT. Correlation in SQL only applies to column
:tags: sqlite
:changeset: c3addcc9ffad
- Added :class:`.types.NCHAR`, :class:`.types.NVARCHAR`
+ Added :class:`_types.NCHAR`, :class:`_types.NVARCHAR`
to the SQLite dialect's list of recognized type names
for reflection. SQLite returns the name given
to a type as the name returned.
:versions: 1.0.5
Added official support for a CTE used by the SELECT present
- inside of :meth:`.Insert.from_select`. This behavior worked
+ inside of :meth:`_expression.Insert.from_select`. This behavior worked
accidentally up until 0.9.9, when it no longer worked due to
unrelated changes as part of :ticket:`3248`. Note that this
is the rendering of the WITH clause after the INSERT, before the
:versions: 1.0.1
Added the string value ``"none"`` to those accepted by the
- :paramref:`.Pool.reset_on_return` parameter as a synonym for ``None``,
+ :paramref:`_pool.Pool.reset_on_return` parameter as a synonym for ``None``,
so that string values can be used for all settings, allowing
utilities like :func:`.engine_from_config` to be usable without
issue.
:tickets: 3362
:versions: 1.0.0
- Fixed issue where a :class:`.MetaData` object that used a naming
+ Fixed issue where a :class:`_schema.MetaData` object that used a naming
convention would not properly work with pickle. The attribute was
skipped leading to inconsistencies and failures if the unpickled
- :class:`.MetaData` object were used to base additional tables
+ :class:`_schema.MetaData` object were used to base additional tables
from.
.. change::
Fixed a long-standing bug where the :class:`.Enum` type as used
with the psycopg2 dialect in conjunction with non-ascii values
and ``native_enum=False`` would fail to decode return results properly.
- This stemmed from when the PG :class:`.postgresql.ENUM` type used
+ This stemmed from when the PG :class:`_postgresql.ENUM` type used
to be a standalone type without a "non native" option.
.. change::
:tags: bug, orm
:tickets: 3349
- :class:`.Query` doesn't support joins, subselects, or special
- FROM clauses when using the :meth:`.Query.update` or
- :meth:`.Query.delete` methods; instead of silently ignoring these
- fields if methods like :meth:`.Query.join` or
- :meth:`.Query.select_from` has been called, a warning is emitted.
+ :class:`_query.Query` doesn't support joins, subselects, or special
+ FROM clauses when using the :meth:`_query.Query.update` or
+ :meth:`_query.Query.delete` methods; instead of silently ignoring these
+ fields if methods like :meth:`_query.Query.join` or
+ :meth:`_query.Query.select_from` has been called, a warning is emitted.
As of 1.0.0b5 this will raise an error.
.. change::
:versions: 1.0.0b1
Added a new entry ``"entity"`` to the dictionaries returned by
- :attr:`.Query.column_descriptions`. This refers to the primary ORM
+ :attr:`_query.Query.column_descriptions`. This refers to the primary ORM
mapped class or aliased class that is referred to by the expression.
Compared to the existing entry for ``"type"``, it will always be
a mapped entity, even if extracted from a column expression, or
:tags: bug, orm
:versions: 1.0.0b1
- Fixed bug where TypeError raised when :meth:`.Query.join` called
+ Fixed bug where TypeError raised when :meth:`_query.Query.join` called
with unknown kw arguments would raise its own TypeError due
to broken formatting. Pull request courtesy Malthe Borch.
:tickets: 3302
:versions: 1.0.0b1
- Fixed bug in :class:`.Connection` and pool where the
- :meth:`.Connection.invalidate` method, or an invalidation due
+ Fixed bug in :class:`_engine.Connection` and pool where the
+ :meth:`_engine.Connection.invalidate` method, or an invalidation due
to a database disconnect, would fail if the
``isolation_level`` parameter had been used with
- :meth:`.Connection.execution_options`; the "finalizer" that resets
+ :meth:`_engine.Connection.execution_options`; the "finalizer" that resets
the isolation level would be called on the no longer opened connection.
.. change::
:versions: 1.0.0b1
Added new parameter :paramref:`.Session.connection.execution_options`
- which may be used to set up execution options on a :class:`.Connection`
+ which may be used to set up execution options on a :class:`_engine.Connection`
when it is first checked out, before the transaction has begun.
This is used to set up options such as isolation level on the
connection before the transaction starts.
:versions: 1.0.0b1
A warning is emitted if the ``isolation_level`` parameter is used
- with :meth:`.Connection.execution_options` when a :class:`.Transaction`
+ with :meth:`_engine.Connection.execution_options` when a :class:`.Transaction`
is in play; DBAPIs and/or SQLAlchemy dialects such as psycopg2,
MySQLdb may implicitly rollback or commit the transaction, or
not change the setting til next transaction, so this is never safe.
:tickets: 3298, 1765
Fixed bug in 0.9's foreign key setup system, such that
- the logic used to link a :class:`.ForeignKey` to its parent could fail
+ the logic used to link a :class:`_schema.ForeignKey` to its parent could fail
when the foreign key used "link_to_name=True" in conjunction with
- a target :class:`.Table` that would not receive its parent column until
+ a target :class:`_schema.Table` that would not receive its parent column until
later, such as within a reflection + "useexisting" scenario,
if the target column in fact had a key value different from its name,
as would occur in reflection if column reflect events were used to
- alter the .key of reflected :class:`.Column` objects so that the
+ alter the .key of reflected :class:`_schema.Column` objects so that the
link_to_name becomes significant. Also repaired support for column
type via FK transmission in a similar way when target columns had a
different key and were referenced using link_to_name.
:versions: 1.0.0b1
Added new user-space accessors for viewing transaction isolation
- levels; :meth:`.Connection.get_isolation_level`,
- :attr:`.Connection.default_isolation_level`.
+ levels; :meth:`_engine.Connection.get_isolation_level`,
+ :attr:`_engine.Connection.default_isolation_level`.
.. change::
:tags: bug, postgresql
Fixed bug where PostgreSQL dialect would fail to render an
expression in an :class:`.Index` that did not correspond directly
- to a table-bound column; typically when a :func:`.text` construct
+ to a table-bound column; typically when a :func:`_expression.text` construct
was one of the expressions within the index; or could misinterpret the
list of expressions if one or more of them were such an expression.
:tickets: 3287
The "wildcard" loader options, in particular the one set up by
- the :func:`.orm.load_only` option to cover all attributes not
+ the :func:`_orm.load_only` option to cover all attributes not
explicitly mentioned, now takes into account the superclasses
of a given entity, if that entity is mapped with inheritance mapping,
so that attribute names within the superclasses are also omitted
:tickets: 3285
Fixed bug where if an exception were thrown at the start of a
- :class:`.Query` before it fetched results, particularly when
+ :class:`_query.Query` before it fetched results, particularly when
row processors can't be formed, the cursor would stay open with
results pending and not actually be closed. This is typically only
an issue on an interpreter like PyPy where the cursor isn't
Added new method :meth:`.Session.invalidate`, functions similarly
to :meth:`.Session.close`, except also calls
- :meth:`.Connection.invalidate`
+ :meth:`_engine.Connection.invalidate`
on all connections, guaranteeing that they will not be returned to
the connection pool. This is useful in situations e.g. dealing
with gevent timeouts when it is not safe to use the connection further,
Fixed bug regarding expression mutations which could express
itself as a "Could not locate column" error when using
- :class:`.Query` to select from multiple, anonymous column
+ :class:`_query.Query` to select from multiple, anonymous column
entities when querying against SQLite, as a side effect of the
"join rewriting" feature used by the SQLite dialect.
:tickets: 3232
:versions: 1.0.0b1
- Fixed bug where the ON clause for :meth:`.Query.join`,
- and :meth:`.Query.outerjoin` to a single-inheritance subclass
+ Fixed bug where the ON clause for :meth:`_query.Query.join`,
+ and :meth:`_query.Query.outerjoin` to a single-inheritance subclass
using ``of_type()`` would not render the "single table criteria" in
the ON clause if the ``from_joinpoint=True`` flag were set.
:versions: 1.0.0b1
:tickets: 3200
- The execution options passed to an :class:`.Engine` either via
+ The execution options passed to an :class:`_engine.Engine` either via
:paramref:`.create_engine.execution_options` or
- :meth:`.Engine.update_execution_options` are not passed to the
- special :class:`.Connection` used to initialize the dialect
+ :meth:`_engine.Engine.update_execution_options` are not passed to the
+ special :class:`_engine.Connection` used to initialize the dialect
within the "first connect" event; dialects will usually
perform their own queries in this phase, and none of the
current available options should be applied here. In
particular, the "autocommit" option was causing an attempt to
autocommit within this initial connect which would fail with
an AttributeError due to the non-standard state of the
- :class:`.Connection`.
+ :class:`_engine.Connection`.
.. change::
:tags: bug, sqlite
* The value :func:`.null` can now be specified, which will always
result in a NULL value resulting in the statement.
- * A new parameter :paramref:`.JSON.none_as_null` is added, which
+ * A new parameter :paramref:`_types.JSON.none_as_null` is added, which
when True indicates that the Python ``None`` value should be
persisted as SQL NULL, rather than JSON-encoded ``'null'``.
:versions: 1.0.0b1
:tickets: 3141
- Fixed bug in :class:`.postgresql.array` object where comparison
+ Fixed bug in :class:`_postgresql.array` object where comparison
to a plain Python list would fail to use the correct array constructor.
Pull request courtesy Andrew.
:versions: 1.0.0b1
Fixed a regression from 0.9.0 due to :ticket:`2736` where the
- :meth:`.Query.select_from` method no longer set up the "from
- entity" of the :class:`.Query` object correctly, so that
- subsequent :meth:`.Query.filter_by` or :meth:`.Query.join`
+ :meth:`_query.Query.select_from` method no longer set up the "from
+ entity" of the :class:`_query.Query` object correctly, so that
+ subsequent :meth:`_query.Query.filter_by` or :meth:`_query.Query.join`
calls would fail to check the appropriate "from" entity when
searching for attributes by string name.
:tickets: 3069
:versions: 1.0.0b1
- Fixed bug where multi-valued :class:`~.sql.expression.Insert` construct would fail
+ Fixed bug where multi-valued :class:`_expression.Insert` construct would fail
to check subsequent values entries beyond the first one given
for literal SQL expressions.
The :meth:`.TypeEngine.with_variant` method will now accept a
type class as an argument which is internally converted to an
instance, using the same convention long established by other
- constructs such as :class:`.Column`.
+ constructs such as :class:`_schema.Column`.
.. change::
:tags: bug, orm
:tags: feature, postgresql
:versions: 1.0.0b1
- Added support for PostgreSQL JSONB via :class:`.JSONB`. Pull request
+ Added support for PostgreSQL JSONB via :class:`_postgresql.JSONB`. Pull request
courtesy Damian Dimmich.
.. change::
:tickets: 3023
:versions: 1.0.0b1
- The :paramref:`.Column.nullable` flag is implicitly set to ``False``
- when that :class:`.Column` is referred to in an explicit
+ The :paramref:`_schema.Column.nullable` flag is implicitly set to ``False``
+ when that :class:`_schema.Column` is referred to in an explicit
:class:`.PrimaryKeyConstraint` for that table. This behavior now
- matches that of when the :class:`.Column` itself has the
- :paramref:`.Column.primary_key` flag set to ``True``, which is
+ matches that of when the :class:`_schema.Column` itself has the
+ :paramref:`_schema.Column.primary_key` flag set to ``True``, which is
intended to be an exactly equivalent case.
.. change::
:tickets: 3002
:versions: 1.0.0b1
- Added a new type :class:`.postgresql.OID` to the PostgreSQL dialect.
+ Added a new type :class:`_postgresql.OID` to the PostgreSQL dialect.
While "oid" is generally a private type within PG that is not exposed
in modern versions, there are some PG use cases such as large object
support where these types might be exposed, as well as within some
:tickets: 3080
:versions: 1.0.0b1
- Modified the behavior of :func:`.orm.load_only` such that primary key
+ Modified the behavior of :func:`_orm.load_only` such that primary key
columns are always added to the list of columns to be "undeferred";
otherwise, the ORM can't load the row's identity. Apparently,
one can defer the mapped primary keys and the ORM will fail, that
:tickets: 2785
:versions: 1.0.0b1
- Added a new flag :paramref:`.ARRAY.zero_indexes` to the PostgreSQL
- :class:`.ARRAY` type. When set to ``True``, a value of one will be
+ Added a new flag :paramref:`_types.ARRAY.zero_indexes` to the PostgreSQL
+ :class:`_types.ARRAY` type. When set to ``True``, a value of one will be
added to all array index values before passing to the database, allowing
better interoperability between Python style zero-based indexes and
PostgreSQL one-based indexes. Pull request courtesy Alexey Terentev.
:versions: 1.0.0b1
Liberalized the contract for :class:`.Index` a bit in that you can
- specify a :func:`.text` expression as the target; the index no longer
+ specify a :func:`_expression.text` expression as the target; the index no longer
needs to have a table-bound column present if the index is to be
manually added to the table, either via inline declaration or via
- :meth:`.Table.append_constraint`.
+ :meth:`_schema.Table.append_constraint`.
.. change::
:tags: bug, firebird
Fixes to the newly enhanced boolean coercion in :ticket:`2804` where
the new rules for "where" and "having" woudn't take effect for the
- "whereclause" and "having" kw arguments of the :func:`~.sql.expression.select` construct,
- which is also what :class:`.Query` uses so wasn't working in the
+ "whereclause" and "having" kw arguments of the :func:`_expression.select` construct,
+ which is also what :class:`_query.Query` uses so wasn't working in the
ORM either.
.. change::
Improved the check for "how to join from A to B" such that when
a table has multiple, composite foreign keys targeting a parent table,
- the :paramref:`.relationship.foreign_keys` argument will be properly
+ the :paramref:`_orm.relationship.foreign_keys` argument will be properly
interpreted in order to resolve the ambiguity; previously this condition
would raise that there were multiple FK paths when in fact the
foreign_keys argument should be establishing which one is expected.
:tags: feature, engine
:tickets: 2978
- An event listener can now be associated with a :class:`.Engine`,
- after one or more :class:`.Connection` objects have been created
+ An event listener can now be associated with a :class:`_engine.Engine`,
+ after one or more :class:`_engine.Connection` objects have been created
(such as by an orm :class:`.Session` or via explicit connect)
and the listener will pick up events from those connections.
Previously, performance concerns pushed the event transfer from
- :class:`.Engine` to :class:`.Connection` at init-time only, but
+ :class:`_engine.Engine` to :class:`_engine.Connection` at init-time only, but
we've inlined a bunch of conditional checks to make this possible
without any additional function calls.
:tags: bug, engine
:tickets: 2985
- A major improvement made to the mechanics by which the :class:`.Engine`
+ A major improvement made to the mechanics by which the :class:`_engine.Engine`
recycles the connection pool when a "disconnect" condition is detected;
instead of discarding the pool and explicitly closing out connections,
the pool is retained and a "generational" timestamp is updated to
:tags: bug, oracle
:tickets: 2987
- Added new datatype :class:`.oracle.DATE`, which is a subclass of
+ Added new datatype :class:`_oracle.DATE`, which is a subclass of
:class:`.DateTime`. As Oracle has no "datetime" type per se,
it instead has only ``DATE``, it is appropriate here that the
``DATE`` type as present in the Oracle dialect be an instance of
:tags: bug, sql
:tickets: 2988
- Fixed an 0.9 regression where a :class:`.Table` that failed to
+ Fixed an 0.9 regression where a :class:`_schema.Table` that failed to
reflect correctly wouldn't be removed from the parent
- :class:`.MetaData`, even though in an invalid state. Pullreq
+ :class:`_schema.MetaData`, even though in an invalid state. Pullreq
courtesy Roman Podoliaka.
.. change::
:tags: bug, engine
The :meth:`.ConnectionEvents.after_cursor_execute` event is now
- emitted for the "_cursor_execute()" method of :class:`.Connection`;
+ emitted for the "_cursor_execute()" method of :class:`_engine.Connection`;
this is the "quick" executor that is used for things like
when a sequence is executed ahead of an INSERT statement, as well as
for dialect startup checks like unicode returns, charset, etc.
.. change::
:tags: feature, sql
- Added a new feature :func:`.schema.conv`, the purpose of which is to
+ Added a new feature :func:`_schema.conv`, the purpose of which is to
mark a constraint name as already having had a naming convention applied.
This token will be used by Alembic migrations as of Alembic 0.6.4
in order to render constraints in migration scripts with names marked
.. change::
:tags: bug, sql
- :paramref:`.MetaData.naming_convention` feature will now also
+ :paramref:`_schema.MetaData.naming_convention` feature will now also
apply to :class:`.CheckConstraint` objects that are associated
- directly with a :class:`.Column` instead of just on the
- :class:`.Table`.
+ directly with a :class:`_schema.Column` instead of just on the
+ :class:`_schema.Table`.
.. change::
:tags: bug, sql
:tickets: 2991
- Fixed bug in new :paramref:`.MetaData.naming_convention` feature
+ Fixed bug in new :paramref:`_schema.MetaData.naming_convention` feature
where the name of a check constraint making use of the
`"%(constraint_name)s"` token would get doubled up for the
constraint generated by a boolean or enum type, and overall
A warning is emitted if the :meth:`.MapperEvents.before_configured`
or :meth:`.MapperEvents.after_configured` events are applied to a
specific mapper or mapped class, as the events are only invoked
- for the :class:`.Mapper` target at the general level.
+ for the :class:`_orm.Mapper` target at the general level.
.. change::
:tags: feature, orm
:tags: feature, orm
:tickets: 2976
- Added a new option to :paramref:`.relationship.innerjoin` which is
+ Added a new option to :paramref:`_orm.relationship.innerjoin` which is
to specify the string ``"nested"``. When set to ``"nested"`` as opposed
to ``True``, the "chaining" of joins will parenthesize the inner join on the
right side of an existing outer join, instead of chaining as a string
:tickets: 2974
Adjusted the logic which applies names to the .c collection when
- a no-name :class:`.BindParameter` is received, e.g. via :func:`.sql.literal`
+ a no-name :class:`.BindParameter` is received, e.g. via :func:`_expression.literal`
or similar; the "key" of the bind param is used as the key within
.c. rather than the rendered name. Since these binds have "anonymous"
names in any case, this allows individual bound parameters to
:tags: bug, sql
:tickets: 2974
- Some changes to how the :attr:`.FromClause.c` collection behaves
+ Some changes to how the :attr:`_expression.FromClause.c` collection behaves
when presented with duplicate columns. The behavior of emitting a
warning and replacing the old column with the same name still
remains to some degree; the replacement in particular is to maintain
list of columns rather than the unique set of key names. This helps
with situations where SELECT statements with same-named columns
are used in unions and such, so that the union can match the columns
- up positionally and also there's some chance of :meth:`.FromClause.corresponding_column`
+ up positionally and also there's some chance of :meth:`_expression.FromClause.corresponding_column`
still being usable here (it can now return a column that is only
in selectable.c._all_columns and not otherwise named).
The new collection is underscored as we still need to decide where this
.. change::
:tags: bug, sql
- Fixed issue in new :meth:`.TextClause.columns` method where the ordering
+ Fixed issue in new :meth:`_expression.TextClause.columns` method where the ordering
of columns given positionally would not be preserved. This could
have potential impact in positional situations such as applying the
resulting :class:`.TextAsFrom` object to a union.
:tickets: 2973
Fixed bug where events set to listen at the class
- level (e.g. on the :class:`.Mapper` or :class:`.ClassManager`
+ level (e.g. on the :class:`_orm.Mapper` or :class:`.ClassManager`
level, as opposed to on an individual mapped class, and also on
- :class:`.Connection`) that also made use of internal argument conversion
+ :class:`_engine.Connection`) that also made use of internal argument conversion
(which is most within those categories) would fail to be removable.
.. change::
:tags: bug, orm
Fixed regression from 0.8 where using an option like
- :func:`.orm.lazyload` with the "wildcard" expression, e.g. ``"*"``,
+ :func:`_orm.lazyload` with the "wildcard" expression, e.g. ``"*"``,
would raise an assertion error in the case where the query didn't
contain any actual entities. This assertion is meant for other cases
and was catching this one inadvertently.
The SQLite dialect will now skip unsupported arguments when reflecting
types; such as if it encounters a string like ``INTEGER(5)``, the
- :class:`.INTEGER` type will be instantiated without the "5" being included,
+ :class:`_types.INTEGER` type will be instantiated without the "5" being included,
based on detecting a ``TypeError`` on the first attempt.
.. change::
:tags: postgresql, feature
Added the :attr:`.TypeEngine.python_type` convenience accessor onto the
- :class:`.postgresql.ARRAY` type. Pull request courtesy Alexey Terentev.
+ :class:`_postgresql.ARRAY` type. Pull request courtesy Alexey Terentev.
.. change::
:tags: examples, feature
Added optional "changed" column to the versioned rows example, as well
- as support for when the versioned :class:`.Table` has an explicit
- :paramref:`~.Table.schema` argument. Pull request
+ as support for when the versioned :class:`_schema.Table` has an explicit
+ :paramref:`_schema.Table.schema` argument. Pull request
courtesy jplaverdure.
.. change::
:tags: feature, sql
Added :paramref:`.MetaData.reflect.**dialect_kwargs`
- to support dialect-level reflection options for all :class:`.Table`
+ to support dialect-level reflection options for all :class:`_schema.Table`
objects reflected.
.. change::
:tickets: 2922
Added a new dialect-level argument ``postgresql_ignore_search_path``;
- this argument is accepted by both the :class:`.Table` constructor
- as well as by the :meth:`.MetaData.reflect` method. When in use
+ this argument is accepted by both the :class:`_schema.Table` constructor
+ as well as by the :meth:`_schema.MetaData.reflect` method. When in use
against PostgreSQL, a foreign-key referenced table which specifies
a remote schema name will retain that schema name even if the name
is present in the ``search_path``; the default behavior since 0.7.3
has been that schemas present in ``search_path`` would not be copied
- to reflected :class:`.ForeignKey` objects. The documentation has been
+ to reflected :class:`_schema.ForeignKey` objects. The documentation has been
updated to describe in detail the behavior of the ``pg_get_constraintdef()``
function and how the ``postgresql_ignore_search_path`` feature essentially
determines if we will honor the schema qualification reported by
:tags: bug, sql
:tickets: 2913
- The behavior of :meth:`.Table.tometadata` has been adjusted such that
- the schema target of a :class:`.ForeignKey` will not be changed unless
+ The behavior of :meth:`_schema.Table.tometadata` has been adjusted such that
+ the schema target of a :class:`_schema.ForeignKey` will not be changed unless
that schema matches that of the parent table. That is, if
a table "schema_a.user" has a foreign key to "schema_b.order.id",
the "schema_b" target will be maintained whether or not the
- "schema" argument is passed to :meth:`.Table.tometadata`. However
+ "schema" argument is passed to :meth:`_schema.Table.tometadata`. However
if a table "schema_a.user" refers to "schema_a.order.id", the presence
of "schema_a" will be updated on both the parent and referred tables.
This is a behavioral change hence isn't likely to be backported to
Additionally, a new parameter has been added
:paramref:`.Table.tometadata.referred_schema_fn`. This refers to a
callable function which will be used to determine the new referred
- schema for any :class:`.ForeignKeyConstraint` encountered in the
+ schema for any :class:`_schema.ForeignKeyConstraint` encountered in the
tometadata operation. This callable can be used to revert to the
previous behavior or to customize how referred schemas are treated
on a per-constraint basis.
:tags: bug, orm
:tickets: 2932
- Fixed bug in new :class:`.TextAsFrom` construct where :class:`.Column`-
+ Fixed bug in new :class:`.TextAsFrom` construct where :class:`_schema.Column`-
oriented row lookups were not matching up to the ad-hoc :class:`.ColumnClause`
objects that :class:`.TextAsFrom` generates, thereby making it not
- usable as a target in :meth:`.Query.from_statement`. Also fixed
- :meth:`.Query.from_statement` mechanics to not mistake a :class:`.TextAsFrom`
- for a :class:`.Select` construct. This bug is also an 0.9 regression
- as the :meth:`.Text.columns` method is called to accommodate the
- :paramref:`.text.typemap` argument.
+ usable as a target in :meth:`_query.Query.from_statement`. Also fixed
+ :meth:`_query.Query.from_statement` mechanics to not mistake a :class:`.TextAsFrom`
+ for a :class:`_expression.Select` construct. This bug is also an 0.9 regression
+ as the :meth:`_expression.TextClause.columns` method is called to accommodate the
+ :paramref:`_expression.text.typemap` argument.
.. change::
:tags: feature, sql
on a recipe in the wiki, the new feature uses schema-events to set up
names as various schema objects are associated with each other. The
events then expose a configuration system through a new argument
- :paramref:`.MetaData.naming_convention`. This system allows production
+ :paramref:`_schema.MetaData.naming_convention`. This system allows production
of both simple and custom naming schemes for constraints and indexes
- on a per-:class:`.MetaData` basis.
+ on a per-:class:`_schema.MetaData` basis.
.. seealso::
Added a new parameter :paramref:`.Operators.op.is_comparison`. This
flag allows a custom op from :meth:`.Operators.op` to be considered
as a "comparison" operator, thus usable for custom
- :paramref:`.relationship.primaryjoin` conditions.
+ :paramref:`_orm.relationship.primaryjoin` conditions.
.. seealso::
:tickets: 2918
Fixed an 0.9 regression where the automatic aliasing applied by
- :class:`.Query` and in other situations where selects or joins
+ :class:`_query.Query` and in other situations where selects or joins
were aliased (such as joined table inheritance) could fail if a
- user-defined :class:`.Column` subclass were used in the expression.
+ user-defined :class:`_schema.Column` subclass were used in the expression.
In this case, the subclass would fail to propagate ORM-specific
"annotations" along needed by the adaptation. The "expression
annotations" system has been corrected to account for this case.
.. change::
:tags: feature, orm
- Support is improved for supplying a :func:`.join` construct as the
- target of :paramref:`.relationship.secondary` for the purposes
- of creating very complex :func:`.relationship` join conditions.
+ Support is improved for supplying a :func:`_expression.join` construct as the
+ target of :paramref:`_orm.relationship.secondary` for the purposes
+ of creating very complex :func:`_orm.relationship` join conditions.
The change includes adjustments to query joining, joined eager loading
to not render a SELECT subquery, changes to lazy loading such that
the "secondary" target is properly included in the SELECT, and
where a more specific type is adapted to a more generic one - this
use case is needed by some third party tools such as ``sqlacodegen``.
The specific cases that needed repair within this test suite were that
- of :class:`.mysql.ENUM` being downcast into a :class:`.types.Enum`,
+ of :class:`.mysql.ENUM` being downcast into a :class:`_types.Enum`,
and that of SQLite date types being cast into generic date types.
The ``adapt()`` method needed to become more specific here to counteract
the removal of a "catch all" ``**kwargs`` collection on the base
the columns, or if both are present, that the column lists match
exactly. If an inconsistent set of columns in the
:class:`.PrimaryKeyConstraint`
- and within the :class:`.Table` marked as ``primary_key=True`` are
+ and within the :class:`_schema.Table` marked as ``primary_key=True`` are
present, a warning is emitted, and the list of columns is taken
only from the :class:`.PrimaryKeyConstraint` alone as was the case
in previous releases.
The system by which schema constructs and certain SQL constructs
accept dialect-specific keyword arguments has been enhanced. This
- system includes commonly the :class:`.Table` and :class:`.Index` constructs,
+ system includes commonly the :class:`_schema.Table` and :class:`.Index` constructs,
which accept a wide variety of dialect-specific arguments such as
``mysql_engine`` and ``postgresql_where``, as well as the constructs
:class:`.PrimaryKeyConstraint`, :class:`.UniqueConstraint`,
- :class:`.Update`, :class:`~.sql.expression.Insert` and :class:`.Delete`, and also
- newly added kwarg capability to :class:`.ForeignKeyConstraint`
- and :class:`.ForeignKey`. The change is that participating dialects
+ :class:`_expression.Update`, :class:`_expression.Insert` and :class:`_expression.Delete`, and also
+ newly added kwarg capability to :class:`_schema.ForeignKeyConstraint`
+ and :class:`_schema.ForeignKey`. The change is that participating dialects
can now specify acceptable argument lists for these constructs, allowing
an argument error to be raised if an invalid keyword is specified for
a particular dialect. If the dialect portion of the keyword is unrecognized,
.. change::
:tags: bug, sql
- A :class:`.UniqueConstraint` created inline with a :class:`.Table`
+ A :class:`.UniqueConstraint` created inline with a :class:`_schema.Table`
that has no columns within it will be skipped. Pullreq courtesy
Derek Harland.
with the same name across tables. This also changes the name used for
the bound parameter in the SET clause to "<tablename>_<colname>" for
the non-primary table only; as this parameter is typically specified
- using the :class:`.Column` object directly this should not have an
+ using the :class:`_schema.Column` object directly this should not have an
impact on applications. The fix takes effect for both
- :meth:`.Table.update` as well as :meth:`.Query.update` in the ORM.
+ :meth:`_schema.Table.update` as well as :meth:`_query.Query.update` in the ORM.
.. change::
:tags: bug, oracle
:tickets: 2908
Fixed a bug involving the new flattened JOIN structures which
- are used with :func:`.joinedload()` (thereby causing a regression
+ are used with :func:`_orm.joinedload()` (thereby causing a regression
in joined eager loading) as well as :func:`.aliased`
in conjunction with the ``flat=True`` flag and joined-table inheritance;
basically multiple joins across a "parent JOIN sub" entity using different
:tags: bug, mysql, pool, engine
:tickets: 2907
- :class:`.Connection` now associates a new
+ :class:`_engine.Connection` now associates a new
:class:`.RootTransaction` or :class:`.TwoPhaseTransaction`
with its immediate :class:`._ConnectionFairy` as a "reset handler"
for the span of that transaction, which takes over the task
of calling commit() or rollback() for the "reset on return" behavior
- of :class:`.Pool` if the transaction was not otherwise completed.
+ of :class:`_pool.Pool` if the transaction was not otherwise completed.
This resolves the issue that a picky transaction
like that of MySQL two-phase will be
properly closed out when the connection is closed without an
.. change::
:tags: feature, pool, engine
- Added a new pool event :meth:`.PoolEvents.invalidate`. Called when
+ Added a new pool event :meth:`_events.PoolEvents.invalidate`. Called when
a DBAPI connection is to be marked as "invalidated" and discarded
from the pool.
.. change::
:tags: bug, pool
- The argument names for the :meth:`.PoolEvents.reset` event have been
+ The argument names for the :meth:`_events.PoolEvents.reset` event have been
renamed to ``dbapi_connection`` and ``connection_record`` in order
to maintain consistency with all the other pool events. It is expected
that any existing listeners for this relatively new and
.. change::
:tags: feature, schema
- The :paramref:`.Table.extend_existing` and :paramref:`.Table.autoload_replace`
- parameters are now available on the :meth:`.MetaData.reflect`
+ The :paramref:`_schema.Table.extend_existing` and :paramref:`_schema.Table.autoload_replace`
+ parameters are now available on the :meth:`_schema.MetaData.reflect`
method.
.. change::
:tickets: 2828
Declarative does an extra check to detect if the same
- :class:`.Column` is mapped multiple times under different properties
+ :class:`_schema.Column` is mapped multiple times under different properties
(which typically should be a :func:`.synonym` instead) or if two
- or more :class:`.Column` objects are given the same name, raising
+ or more :class:`_schema.Column` objects are given the same name, raising
a warning if this condition is detected.
.. change::
:tickets: 2581
Support for PostgreSQL JSON has been added, using the new
- :class:`.JSON` type. Huge thanks to Nathan Rice for
+ :class:`_types.JSON` type. Huge thanks to Nathan Rice for
implementing and testing this.
.. change::
:tags: bug, sql
:tickets: 2883
- The :class:`.ForeignKey` class more aggressively checks the given
+ The :class:`_schema.ForeignKey` class more aggressively checks the given
column argument. If not a string, it checks that the object is
at least a :class:`.ColumnClause`, or an object that resolves to one,
and that the ``.table`` attribute, if present, refers to a
- :class:`.TableClause` or subclass, and not something like an
- :class:`.Alias`. Otherwise, a :class:`.ArgumentError` is raised.
+ :class:`_expression.TableClause` or subclass, and not something like an
+ :class:`_expression.Alias`. Otherwise, a :class:`.ArgumentError` is raised.
.. change::
:tags: feature, postgresql
Added support for PostgreSQL TSVECTOR via the
- :class:`.postgresql.TSVECTOR` type. Pull request courtesy
+ :class:`_postgresql.TSVECTOR` type. Pull request courtesy
Noufal Ibrahim.
.. change::
The :class:`.DeferredReflection` class has been enhanced to provide
automatic reflection support for the "secondary" table referred
- to by a :func:`.relationship`. "secondary", when specified
- either as a string table name, or as a :class:`.Table` object with
- only a name and :class:`.MetaData` object will also be included
+ to by a :func:`_orm.relationship`. "secondary", when specified
+ either as a string table name, or as a :class:`_schema.Table` object with
+ only a name and :class:`_schema.MetaData` object will also be included
in the reflection process when :meth:`.DeferredReflection.prepare`
is called.
Fixed bug where in Py2K a unicode literal would not be accepted
as the string name of a class or other argument within
- declarative using :func:`.relationship`.
+ declarative using :func:`_orm.relationship`.
.. change::
:tags: feature, sql
:tickets: 2877, 2882
- New improvements to the :func:`.text` construct, including
+ New improvements to the :func:`_expression.text` construct, including
more flexible ways to set up bound parameters and return types;
- in particular, a :func:`.text` can now be turned into a full
+ in particular, a :func:`_expression.text` can now be turned into a full
FROM-object, embeddable in other statements as an alias or CTE
- using the new method :meth:`.TextClause.columns`. The :func:`.text`
+ using the new method :meth:`_expression.TextClause.columns`. The :func:`_expression.text`
construct can also render "inline" bound parameters when the construct
is compiled in a "literal bound" context.
:tags: feature, sql
A new API for specifying the ``FOR UPDATE`` clause of a ``SELECT``
- is added with the new :meth:`.GenerativeSelect.with_for_update` method.
+ is added with the new :meth:`_expression.GenerativeSelect.with_for_update` method.
This method supports a more straightforward system of setting
dialect-specific options compared to the ``for_update`` keyword
- argument of :func:`~.sql.expression.select`, and also includes support for the
+ argument of :func:`_expression.select`, and also includes support for the
SQL standard ``FOR UPDATE OF`` clause. The ORM also includes
- a new corresponding method :meth:`.Query.with_for_update`.
+ a new corresponding method :meth:`_query.Query.with_for_update`.
Pull request courtesy Mario Lassnig.
.. seealso::
:tags: feature, orm
A new API for specifying the ``FOR UPDATE`` clause of a ``SELECT``
- is added with the new :meth:`.Query.with_for_update` method,
- to complement the new :meth:`.GenerativeSelect.with_for_update` method.
+ is added with the new :meth:`_query.Query.with_for_update` method,
+ to complement the new :meth:`_expression.GenerativeSelect.with_for_update` method.
Pull request courtesy Mario Lassnig.
.. seealso::
:tags: bug, orm
:tickets: 2833
- The ``viewonly`` flag on :func:`.relationship` will now prevent
+ The ``viewonly`` flag on :func:`_orm.relationship` will now prevent
attribute history from being written on behalf of the target attribute.
This has the effect of the object not being written to the
Session.dirty list if it is mutated. Previously, the object would
:tags: bug, orm
Fixed bug where usage of new :class:`.Bundle` object would cause
- the :attr:`.Query.column_descriptions` attribute to fail.
+ the :attr:`_query.Query.column_descriptions` attribute to fail.
.. change::
:tags: bug, examples
new copy is assigned the actual type of the compared column. Previously,
this logic would occur on the given :func:`.bindparam` in place.
Additionally, a similar process now occurs for :func:`.bindparam` constructs
- passed to :meth:`.ValuesBase.values` for an :class:`~.sql.expression.Insert` or
- :class:`.Update` construct, within the compilation phase of the
+ passed to :meth:`.ValuesBase.values` for an :class:`_expression.Insert` or
+ :class:`_expression.Update` construct, within the compilation phase of the
construct.
These are both subtle behavioral changes which may impact some
An overhaul of expression handling for special symbols particularly
with conjunctions, e.g.
- ``None`` :func:`.expression.null` :func:`.expression.true`
- :func:`.expression.false`, including consistency in rendering NULL
+ ``None`` :func:`_expression.null` :func:`_expression.true`
+ :func:`_expression.false`, including consistency in rendering NULL
in conjunctions, "short-circuiting" of :func:`.and_` and :func:`.or_`
expressions which contain boolean constants, and rendering of
boolean constants and expressions as compared to "1" or "0" for backends
:tags: feature, sql
:tickets: 2716
- The :meth:`.Table.tometadata` method now produces copies of
+ The :meth:`_schema.Table.tometadata` method now produces copies of
all :attr:`.SchemaItem.info` dictionaries from all :class:`.SchemaItem`
objects within the structure including columns, constraints,
foreign keys, etc. As these dictionaries
are copies, they are independent of the original dictionary.
- Previously, only the ``.info`` dictionary of :class:`.Column` was transferred
+ Previously, only the ``.info`` dictionary of :class:`_schema.Column` was transferred
within this operation, and it was only linked in place, not copied.
.. change::
.. change::
:tags: feature, sql
- The ``default`` argument of :class:`.Column` now accepts a class
+ The ``default`` argument of :class:`_schema.Column` now accepts a class
or object method as an argument, in addition to a standalone function;
will properly detect if the "context" argument is accepted or not.
:tags: bug, sql
:tickets: 2831
- The erroneous kw arg "schema" has been removed from the :class:`.ForeignKey`
+ The erroneous kw arg "schema" has been removed from the :class:`_schema.ForeignKey`
object. this was an accidental commit that did nothing; a warning is raised
in 0.8.3 when this kw arg is used.
:tags: feature, orm
:tickets: 1418
- Added a new load option :func:`.orm.load_only`. This allows a series
+ Added a new load option :func:`_orm.load_only`. This allows a series
of column names to be specified as loading "only" those attributes,
deferring the rest.
:tickets: 1418
The system of loader options has been entirely rearchitected to build
- upon a much more comprehensive base, the :class:`.Load` object. This
- base allows any common loader option like :func:`.joinedload`,
+ upon a much more comprehensive base, the :class:`_orm.Load` object. This
+ base allows any common loader option like :func:`_orm.joinedload`,
:func:`.defer`, etc. to be used in a "chained" style for the purpose
of specifying options down a path, such as ``joinedload("foo").subqueryload("bar")``.
The new system supersedes the usage of dot-separated path names,
:tickets: 2824
The :func:`.composite` construct now maintains the return object
- when used in a column-oriented :class:`.Query`, rather than expanding
+ when used in a column-oriented :class:`_query.Query`, rather than expanding
out into individual columns. This makes use of the new :class:`.Bundle`
feature internally. This behavior is backwards incompatible; to
select from a composite column which will expand out, use
:tickets: 2824
A new construct :class:`.Bundle` is added, which allows for specification
- of groups of column expressions to a :class:`.Query` construct.
+ of groups of column expressions to a :class:`_query.Query` construct.
The group of columns are returned as a single tuple by default. The
behavior of :class:`.Bundle` can be overridden however to provide
any sort of result processing to the returned row. The behavior
of :class:`.Bundle` is also embedded into composite attributes now
- when they are used in a column-oriented :class:`.Query`.
+ when they are used in a column-oriented :class:`_query.Query`.
.. seealso::
instead of relying upon various ``quote=True`` flags being passed around,
these flags are converted into rich string objects with quoting information
included at the point at which they are passed to common schema constructs
- like :class:`.Table`, :class:`.Column`, etc. This solves the issue
+ like :class:`_schema.Table`, :class:`_schema.Column`, etc. This solves the issue
of various methods that don't correctly honor the "quote" flag such
- as :meth:`.Engine.has_table` and related methods. The :class:`.quoted_name`
+ as :meth:`_engine.Engine.has_table` and related methods. The :class:`.quoted_name`
object is a string subclass that can also be used explicitly if needed;
the object will hold onto the quoting preferences passed and will
also bypass the "name normalization" performed by dialects that
:tags: feature, orm
:tickets: 2793
- The ``eager_defaults`` flag of :class:`.Mapper` will now allow the
+ The ``eager_defaults`` flag of :class:`_orm.Mapper` will now allow the
newly generated default values to be fetched using an inline
RETURNING clause, rather than a second SELECT statement, for backends
that support RETURNING.
:tags: feature, sql
:tickets: 722
- Added new method to the :func:`~.sql.expression.insert` construct
- :meth:`.Insert.from_select`. Given a list of columns and
+ Added new method to the :func:`_expression.insert` construct
+ :meth:`_expression.Insert.from_select`. Given a list of columns and
a selectable, renders ``INSERT INTO (table) (columns) SELECT ..``.
While this feature is highlighted as part of 0.9 it is also
backported to 0.8.3.
:tags: bug, sql
:tickets: 1765
- The resolution of :class:`.ForeignKey` objects to their
- target :class:`.Column` has been reworked to be as
+ The resolution of :class:`_schema.ForeignKey` objects to their
+ target :class:`_schema.Column` has been reworked to be as
immediate as possible, based on the moment that the
- target :class:`.Column` is associated with the same
- :class:`.MetaData` as this :class:`.ForeignKey`, rather
+ target :class:`_schema.Column` is associated with the same
+ :class:`_schema.MetaData` as this :class:`_schema.ForeignKey`, rather
than waiting for the first time a join is constructed,
or similar. This along with other improvements allows
earlier detection of some foreign key configuration
issues. Also included here is a rework of the
type-propagation system, so that
it should be reliable now to set the type as ``None``
- on any :class:`.Column` that refers to another via
- :class:`.ForeignKey` - the type will be copied from the
+ on any :class:`_schema.Column` that refers to another via
+ :class:`_schema.ForeignKey` - the type will be copied from the
target column as soon as that other column is associated,
and now works for composite foreign keys as well.
are no longer impacted by this workaround.
As part of this change, a new argument ``flat=True`` has been added
- to the :func:`.orm.aliased`, :meth:`.Join.alias`, and
- :func:`.orm.with_polymorphic` functions, which allows an "alias" of a
+ to the :func:`_orm.aliased`, :meth:`_expression.Join.alias`, and
+ :func:`_orm.with_polymorphic` functions, which allows an "alias" of a
JOIN to be produced which applies an anonymous alias to each component
table within the join, rather than producing a subquery.
:tags: bug, orm
:tickets: 2736
- The "auto-aliasing" behavior of the :meth:`.Query.select_from`
+ The "auto-aliasing" behavior of the :meth:`_query.Query.select_from`
method has been turned off. The specific behavior is now
- available via a new method :meth:`.Query.select_entity_from`.
+ available via a new method :meth:`_query.Query.select_entity_from`.
The auto-aliasing behavior here was never well documented and
- is generally not what's desired, as :meth:`.Query.select_from`
+ is generally not what's desired, as :meth:`_query.Query.select_from`
has become more oriented towards controlling how a JOIN is
- rendered. :meth:`.Query.select_entity_from` will also be made
+ rendered. :meth:`_query.Query.select_entity_from` will also be made
available in 0.8 so that applications which rely on the auto-aliasing
can shift their applications to use this method.
:tickets: 3778
:versions: 1.1.4
- Fixed bug where the :attr:`.Mapper.attrs`,
- :attr:`.Mapper.all_orm_descriptors` and other derived attributes would
+ Fixed bug where the :attr:`_orm.Mapper.attrs`,
+ :attr:`_orm.Mapper.all_orm_descriptors` and other derived attributes would
fail to refresh when mapper properties or other ORM constructs were
added to the mapper/class after these accessors were first called.
:tickets: 3755
:versions: 1.1.0
- Fixed bug in :class:`.Table` where the internal method
+ Fixed bug in :class:`_schema.Table` where the internal method
``_reset_exported()`` would corrupt the state of the object. This
method is intended for selectable objects and is called by the ORM
in some cases; an erroneous mapper configuration would could lead the
- ORM to call this on a :class:`.Table` object.
+ ORM to call this on a :class:`_schema.Table` object.
.. change::
:tags: bug, ext
:tags: bug, sql
:tickets: 3724
- :meth:`.FromClause.count` is pending deprecation for 1.1. This function
+ :meth:`_expression.FromClause.count` is pending deprecation for 1.1. This function
makes use of an arbitrary column in the table and is not reliable;
for Core use, ``func.count()`` should be preferred.
:tags: bug, sql
:tickets: 3722
- Fixed bug in :class:`.CTE` structure which would cause it to not
+ Fixed bug in :class:`_expression.CTE` structure which would cause it to not
clone properly when a union was used, as is common in a recursive
CTE. The improper cloning would cause errors when the CTE is used
in various ORM contexts such as that of a :func:`.column_property`.
:tags: bug, sql
:tickets: 3721
- Fixed bug whereby :meth:`.Table.tometadata` would make a duplicate
- :class:`.UniqueConstraint` for each :class:`.Column` object that
+ Fixed bug whereby :meth:`_schema.Table.tometadata` would make a duplicate
+ :class:`.UniqueConstraint` for each :class:`_schema.Column` object that
featured the ``unique=True`` parameter.
.. change::
:tickets: 3716
Fixed bug in cross-schema foreign key reflection in conjunction
- with the :paramref:`.MetaData.schema` argument, where a referenced
+ with the :paramref:`_schema.MetaData.schema` argument, where a referenced
table that is present in the "default" schema would fail since there
- would be no way to indicate a :class:`.Table` that has "blank" for
- a schema. The special symbol :attr:`.schema.BLANK_SCHEMA` has been
- added as an available value for :paramref:`.Table.schema` and
+ would be no way to indicate a :class:`_schema.Table` that has "blank" for
+ a schema. The special symbol :attr:`_schema.BLANK_SCHEMA` has been
+ added as an available value for :paramref:`_schema.Table.schema` and
:paramref:`.Sequence.schema`, indicating that the schema name
- should be forced to be ``None`` even if :paramref:`.MetaData.schema`
+ should be forced to be ``None`` even if :paramref:`_schema.MetaData.schema`
is specified.
.. change::
:tags: bug, orm
:tickets: 3700
- Fixed bug in "evaluate" strategy of :meth:`.Query.update` and
- :meth:`.Query.delete` which would fail to accommodate a bound
+ Fixed bug in "evaluate" strategy of :meth:`_query.Query.update` and
+ :meth:`_query.Query.delete` which would fail to accommodate a bound
parameter with a "callable" value, as which occurs when filtering
by a many-to-one equality expression along a relationship.
:tags: bug, orm
:tickets: 3706
- Fixed bug whereby passing a :func:`.text` construct to the
- :meth:`.Query.group_by` method would raise an error, instead
+ Fixed bug whereby passing a :func:`_expression.text` construct to the
+ :meth:`_query.Query.group_by` method would raise an error, instead
of interpreting the object as a SQL fragment.
.. change::
:tickets: 3690
Fixed bug where when using ``case_sensitive=False`` with an
- :class:`.Engine`, the result set would fail to correctly accommodate
+ :class:`_engine.Engine`, the result set would fail to correctly accommodate
for duplicate column names in the result set, causing an error
when the statement is executed in 1.0, and preventing the
"ambiguous column" exception from functioning in 1.1.
:tickets: 3666
Fixed bug where "unconsumed column names" exception would fail to
- be raised in the case where :meth:`.Insert.values` were called
+ be raised in the case where :meth:`_expression.Insert.values` were called
with a list of parameter mappings, instead of a single mapping
of parameters. Pull request courtesy Athena Yao.
Fixed bug in "to_list" conversion where a single bytes object
would be turned into a list of individual characters. This would
- impact among other things using the :meth:`.Query.get` method
+ impact among other things using the :meth:`_query.Query.get` method
on a primary key that's a bytes object.
.. change::
:tags: bug, postgresql
:tickets: 3644
- Fixed bug in :func:`.expression.text` construct where a double-colon
+ Fixed bug in :func:`_expression.text` construct where a double-colon
expression would not escape properly, e.g. ``some\:\:expr``, as is most
commonly required when rendering PostgreSQL-style CAST expressions.
:tickets: 3643
Fixed issue where the "literal_binds" flag was not propagated
- for :func:`.expression.insert`, :func:`.expression.update` or
- :func:`.expression.delete` constructs when compiled to string
+ for :func:`_expression.insert`, :func:`_expression.update` or
+ :func:`_expression.delete` constructs when compiled to string
SQL. Pull request courtesy Tim Tate.
.. change::
reraise" function which takes place across the ORM and Core in any
place that a transaction is being rolled back in response to an error
which occurred trying to commit, including the context managers
- provided by :class:`.Session` and :class:`.Connection`, and taking
+ provided by :class:`.Session` and :class:`_engine.Connection`, and taking
place for operations such as a failure on "RELEASE SAVEPOINT".
Previously, the fix was only in place for a specific path within
the ORM flush/commit process; it now takes place for all transactional
:tags: bug, sql
:tickets: 3632
- Fixed bug in :class:`.Table` metadata construct which appeared
- around the 0.9 series where adding columns to a :class:`.Table`
+ Fixed bug in :class:`_schema.Table` metadata construct which appeared
+ around the 0.9 series where adding columns to a :class:`_schema.Table`
that was unpickled would fail to correctly establish the
- :class:`.Column` within the 'c' collection, leading to issues in
+ :class:`_schema.Column` within the 'c' collection, leading to issues in
areas such as ORM configuration. This could impact use cases such
as ``extend_existing`` and others.
Fixed 1.0 regression where the eager fetch of cursor.rowcount was
no longer called for an UPDATE or DELETE statement emitted via plain
- text or via the :func:`.text` construct, affecting those drivers
+ text or via the :func:`_expression.text` construct, affecting those drivers
that erase cursor.rowcount once the cursor is closed such as SQL
Server ODBC and Firebird drivers.
:tags: bug, sql
:tickets: 3609
- Fixed bug in :meth:`.Update.return_defaults` which would cause all
+ Fixed bug in :meth:`_expression.Update.return_defaults` which would cause all
insert-default holding columns not otherwise included in the SET
clause (such as primary key cols) to get rendered into the RETURNING
even though this is an UPDATE.
:tags: bug, orm
:tickets: 3609
- Major fixes to the :paramref:`.Mapper.eager_defaults` flag, this
+ Major fixes to the :paramref:`_orm.Mapper.eager_defaults` flag, this
flag would not be honored correctly in the case that multiple
UPDATE statements were to be emitted, either as part of a flush
or a bulk update operation. Additionally, RETURNING
:tags: bug, orm
:tickets: 3606
- Fixed bug where use of the :meth:`.Query.select_from` method would
- cause a subsequent call to the :meth:`.Query.with_parent` method to
+ Fixed bug where use of the :meth:`_query.Query.select_from` method would
+ cause a subsequent call to the :meth:`_query.Query.with_parent` method to
fail.
.. changelog::
:tags: bug, sql
:tickets: 3603
- Fixed issue within the :meth:`.Insert.from_select` construct whereby
- the :class:`.Select` construct would have its ``._raw_columns``
- collection mutated in-place when compiling the :class:`~.sql.expression.Insert`
- construct, when the target :class:`.Table` has Python-side defaults.
- The :class:`.Select` construct would compile standalone with the
+ Fixed issue within the :meth:`_expression.Insert.from_select` construct whereby
+ the :class:`_expression.Select` construct would have its ``._raw_columns``
+ collection mutated in-place when compiling the :class:`_expression.Insert`
+ construct, when the target :class:`_schema.Table` has Python-side defaults.
+ The :class:`_expression.Select` construct would compile standalone with the
erroneous column present subsequent to compilation of the
- :class:`~.sql.expression.Insert`, and the :class:`~.sql.expression.Insert` statement itself would
+ :class:`_expression.Insert`, and the :class:`_expression.Insert` statement itself would
fail on a second compile attempt due to duplicate bound parameters.
.. change::
Fixed bug where some varieties of SQL expression passed to the
- "where" clause of :class:`.postgresql.ExcludeConstraint` would fail
+ "where" clause of :class:`_postgresql.ExcludeConstraint` would fail
to be accepted correctly. Pull request courtesy aisch.
.. change::
Fixed bug where in Py2K a unicode literal would not be accepted as the
string name of a class or other argument within declarative using
- :func:`.backref` on :func:`.relationship`. Pull request courtesy
+ :func:`.backref` on :func:`_orm.relationship`. Pull request courtesy
Nils Philippsen.
.. change::
Added support for parameter-ordered SET clauses in an UPDATE
statement. This feature is available by passing the
:paramref:`~.sqlalchemy.sql.expression.update.preserve_parameter_order`
- flag either to the core :class:`.Update` construct or alternatively
+ flag either to the core :class:`_expression.Update` construct or alternatively
adding it to the :paramref:`.Query.update.update_args` dictionary at
the ORM-level, also passing the parameters themselves as a list of 2-tuples.
Thanks to Gorka Eguileor for implementation and tests.
:tags: bug, postgresql
:tickets: 3571
- Fixed the ``.python_type`` attribute of :class:`.postgresql.INTERVAL`
+ Fixed the ``.python_type`` attribute of :class:`_postgresql.INTERVAL`
to return ``datetime.timedelta`` in the same way as that of
:obj:`.types.Interval.python_type`, rather than raising
``NotImplementedError``.
.. change::
:tags: feature, orm
- Added new method :meth:`.Query.one_or_none`; same as
- :meth:`.Query.one` but returns None if no row found. Pull request
+ Added new method :meth:`_query.Query.one_or_none`; same as
+ :meth:`_query.Query.one` but returns None if no row found. Pull request
courtesy esiegerman.
.. change::
:tags: feature, sql
:tickets: 3459
- Added a :meth:`.ColumnElement.cast` method which performs the same
- purpose as the standalone :func:`.expression.cast` function. Pull
+ Added a :meth:`_expression.ColumnElement.cast` method which performs the same
+ purpose as the standalone :func:`_expression.cast` function. Pull
request courtesy Sebastian Bank.
.. change::
:tickets: 3481
Fixed regression where new methods on :class:`.ResultProxy` used
- by the ORM :class:`.Query` object (part of the performance
+ by the ORM :class:`_query.Query` object (part of the performance
enhancements of :ticket:`3175`) would not raise the "this result
does not return rows" exception in the case where the driver
(typically MySQL) fails to generate cursor.description correctly;
Fixed 1.0 regression where the "parent entity" of a synonym-
mapped attribute on top of an :func:`.aliased` object would
resolve to the original mapper, not the :func:`.aliased`
- version of it, thereby causing problems for a :class:`.Query`
+ version of it, thereby causing problems for a :class:`_query.Query`
that relies on this attribute (e.g. it's the only representative
attribute given in the constructor) to figure out the correct FROM
clause for the query.
:tags: bug, mssql
:tickets: 3464
- Fixed issue when using :class:`.VARBINARY` type in conjunction with
+ Fixed issue when using :class:`_types.VARBINARY` type in conjunction with
an INSERT of NULL + pyodbc; pyodbc requires a special
- object be passed in order to persist NULL. As the :class:`.VARBINARY`
+ object be passed in order to persist NULL. As the :class:`_types.VARBINARY`
type is now usually the default for :class:`.LargeBinary` due to
:ticket:`3039`, this issue is partially a regression in 1.0.
The pymssql driver appears to be unaffected.
as the ``postgresql_using`` flag, which will now be set on
:class:`.Index` objects that are reflected, as well present
in a new "dialect_options" dictionary in the result of
- :meth:`.Inspector.get_indexes`. Pull request courtesy Pete Hollobon.
+ :meth:`_reflection.Inspector.get_indexes`. Pull request courtesy Pete Hollobon.
.. seealso::
Repaired the :class:`.ExcludeConstraint` construct to support common
features that other objects like :class:`.Index` now do, that
the column expression may be specified as an arbitrary SQL
- expression such as :obj:`.expression.cast` or :obj:`.expression.text`.
+ expression such as :obj:`_expression.cast` or :obj:`_expression.text`.
.. change::
:tags: feature, postgresql
by the psycopg2 dialect when the ``stream_results`` option is
used, which sets a limit on the size of the row buffer that may be
allocated. This value is also provided based on the integer
- value sent to :meth:`.Query.yield_per`. Pull request courtesy
+ value sent to :meth:`_query.Query.yield_per`. Pull request courtesy
mcclurem.
.. change::
:class:`.types.TypeEngine.Comparator` objects that made use of the
``__clause_element__()`` method and returned an object that was an
ORM-mapped :class:`.InstrumentedAttribute` and not explicitly a
- :class:`.ColumnElement` would fail to be correctly handled when passed
+ :class:`_expression.ColumnElement` would fail to be correctly handled when passed
as an expression to :meth:`.Session.query`. The logic in 0.9 happened
to succeed on this, so this use case is now supported.
:tags: feature, engine
Added new engine event :meth:`.ConnectionEvents.engine_disposed`.
- Called after the :meth:`.Engine.dispose` method is called.
+ Called after the :meth:`_engine.Engine.dispose` method is called.
.. change::
:tags: bug, postgresql, pypy
:tags: bug, orm
:tickets: 3420
- The "lightweight named tuple" used when a :class:`.Query` returns
+ The "lightweight named tuple" used when a :class:`_query.Query` returns
rows failed to implement ``__slots__`` correctly such that it still
had a ``__dict__``. This is resolved, but in the extremely
unlikely case someone was assigning values to the returned tuples,
Fixed bug in enhanced constraint-attachment logic introduced in
:ticket:`3341` where in the unusual case of a constraint that refers
- to a mixture of :class:`.Column` objects and string column names
+ to a mixture of :class:`_schema.Column` objects and string column names
at the same time, the auto-attach-on-column-attach logic will be
skipped; for the constraint to be auto-attached in this case,
all columns must be assembled on the target table up front.
Repaired / added to tests yet more expressions that were reported
as failing with the new 'entity' key value added to
- :attr:`.Query.column_descriptions`, the logic to discover the "from"
+ :attr:`_query.Query.column_descriptions`, the logic to discover the "from"
clause is again reworked to accommodate columns from aliased classes,
as well as to report the correct value for the "aliased" flag in these
cases.
:tickets: 3405
Fixed regression from 0.9.10 prior to release due to :ticket:`3349`
- where the check for query state on :meth:`.Query.update` or
- :meth:`.Query.delete` compared the empty tuple to itself using ``is``,
+ where the check for query state on :meth:`_query.Query.update` or
+ :meth:`_query.Query.delete` compared the empty tuple to itself using ``is``,
which fails on PyPy to produce ``True`` in this case; this would
erronously emit a warning in 0.9 and raise an exception in 1.0.
to a modern pool invalidation in that connections aren't actively
closed, but are recycled only on next checkout; this is essentially
a per-connection version of that feature. A new event
- :class:`.PoolEvents.soft_invalidate` is added to complement it.
+ :class:`_events.PoolEvents.soft_invalidate` is added to complement it.
Also added new flag
:attr:`.ExceptionContext.invalidate_pool_on_disconnect`.
:tickets: 3403, 3320
Fixed regression from 0.9.10 prior to release where the new addition
- of ``entity`` to the :attr:`.Query.column_descriptions` accessor
+ of ``entity`` to the :attr:`_query.Query.column_descriptions` accessor
would fail if the target entity was produced from a core selectable
- such as a :class:`.Table` or :class:`.CTE` object.
+ such as a :class:`_schema.Table` or :class:`_expression.CTE` object.
.. change::
:tags: feature, sql
Fixed unexpected use regression due to :ticket:`2992` where
textual elements placed
- into the :meth:`.Query.order_by` clause in conjunction with joined
+ into the :meth:`_query.Query.order_by` clause in conjunction with joined
eager loading would be added to the columns clause of the inner query
in such a way that they were assumed to be table-bound column names,
in the case where the joined eager load needs to wrap the query
Beyond that, the feature also fails for deprecated cases such as
``order_by("name desc")``, which, while it emits a
- warning that :func:`.text` should be used here (note that the issue
- does not impact cases where :func:`.text` is used explicitly),
+ warning that :func:`_expression.text` should be used here (note that the issue
+ does not impact cases where :func:`_expression.text` is used explicitly),
still produces a different query than previously where the "name desc"
expression is copied into the columns clause inappropriately. The
resolution is such that the "joined eager loading" aspect of the
feature will skip over these so-called "label reference" expressions
when augmenting the inner columns clause, as though they were
- :func:`.text` constructs already.
+ :func:`_expression.text` constructs already.
.. change::
:tags: bug, sql
:tickets: 3387
Fixed issue in new :meth:`.QueryEvents.before_compile` event where
- changes made to the :class:`.Query` object's collection of entities
+ changes made to the :class:`_query.Query` object's collection of entities
to load within the event would render in the SQL, but would not
be reflected during the loading process.
the tables; we instead emit a warning and go with the unsorted list.
If an environment needs both ordered DROPs *and* has foreign key
cycles, then the warning notes they will need to restore the
- ``use_alter`` flag to their :class:`.ForeignKey` and
- :class:`.ForeignKeyConstraint` objects so that just those objects will
+ ``use_alter`` flag to their :class:`_schema.ForeignKey` and
+ :class:`_schema.ForeignKeyConstraint` objects so that just those objects will
be omitted from the dependency sort.
.. seealso::
:tags: bug, orm
:tickets: 3367
- Identified an inconsistency when handling :meth:`.Query.join` to the
+ Identified an inconsistency when handling :meth:`_query.Query.join` to the
same target more than once; it implicitly dedupes only in the case of
a relationship join, and due to :ticket:`3233`, in 1.0 a join
to the same table twice behaves differently than 0.9 in that it no
longer erroneously aliases. To help document this change,
the verbiage regarding :ticket:`3233` in the migration notes has
- been generalized, and a warning has been added when :meth:`.Query.join`
+ been generalized, and a warning has been added when :meth:`_query.Query.join`
is called against the same target relationship more than once.
.. change::
:tags: feature, sql
:tickets: 3084
- The topological sorting used to sort :class:`.Table` objects
- and available via the :attr:`.MetaData.sorted_tables` collection
+ The topological sorting used to sort :class:`_schema.Table` objects
+ and available via the :attr:`_schema.MetaData.sorted_tables` collection
will now produce a **deterministic** ordering; that is, the same
ordering each time given a set of tables with particular names
and dependencies. This is to help with comparison of DDL scripts
Added new argument :paramref:`.Query.update.update_args` which allows
kw arguments such as ``mysql_limit`` to be passed to the underlying
- :class:`.Update` construct. Pull request courtesy Amir Sadoughi.
+ :class:`_expression.Update` construct. Pull request courtesy Amir Sadoughi.
.. changelog::
:version: 1.0.0b5
:tags: bug, orm
:tickets: 3349
- :class:`.Query` doesn't support joins, subselects, or special
- FROM clauses when using the :meth:`.Query.update` or
- :meth:`.Query.delete` methods; instead of silently ignoring these
- fields if methods like :meth:`.Query.join` or
- :meth:`.Query.select_from` has been called, an error is raised.
+ :class:`_query.Query` doesn't support joins, subselects, or special
+ FROM clauses when using the :meth:`_query.Query.update` or
+ :meth:`_query.Query.delete` methods; instead of silently ignoring these
+ fields if methods like :meth:`_query.Query.join` or
+ :meth:`_query.Query.select_from` has been called, an error is raised.
In 0.9.10 this only emits a warning.
.. change::
The "auto-attach" feature of constraints such as :class:`.UniqueConstraint`
and :class:`.CheckConstraint` has been further enhanced such that
- when the constraint is associated with non-table-bound :class:`.Column`
+ when the constraint is associated with non-table-bound :class:`_schema.Column`
objects, the constraint will set up event listeners with the
columns themselves such that the constraint auto attaches at the
same time the columns are associated with the table. This in particular
Fixed unexpected use regression from pullreq github:137 where
Py2K unicode literals (e.g. ``u""``) would not be accepted by the
- :paramref:`.relationship.cascade` option.
+ :paramref:`_orm.relationship.cascade` option.
Pull request courtesy Julien Castets.
Added a new extension suite :mod:`sqlalchemy.ext.baked`. This
simple but unusual system allows for a dramatic savings in Python
- overhead for the construction and processing of orm :class:`.Query`
+ overhead for the construction and processing of orm :class:`_query.Query`
objects, from query construction up through rendering of a string
SQL statement.
:tags: bug, postgresql
:tickets: 3319
- The PostgreSQL :class:`.postgresql.ENUM` type will emit a
+ The PostgreSQL :class:`_postgresql.ENUM` type will emit a
DROP TYPE instruction when a plain ``table.drop()`` is called,
assuming the object is not associated directly with a
- :class:`.MetaData` object. In order to accommodate the use case of
+ :class:`_schema.MetaData` object. In order to accommodate the use case of
an enumerated type shared between multiple tables, the type should
- be associated directly with the :class:`.MetaData` object; in this
+ be associated directly with the :class:`_schema.MetaData` object; in this
case the type will only be created at the metadata level, or if
created directly. The rules for create/drop of
PostgreSQL enumerated types have been highly reworked in general.
Added a new event suite :class:`.QueryEvents`. The
:meth:`.QueryEvents.before_compile` event allows the creation
of functions which may place additional modifications to
- :class:`.Query` objects before the construction of the SELECT
+ :class:`_query.Query` objects before the construction of the SELECT
statement. It is hoped that this event be made much more
useful via the advent of a new inspection system that will
allow for detailed modifications to be made against
- :class:`.Query` objects in an automated fashion.
+ :class:`_query.Query` objects in an automated fashion.
.. seealso::
is used with a one-to-many query that also features LIMIT,
OFFSET, or DISTINCT has been disabled in the case of a one-to-one
relationship, that is a one-to-many with
- :paramref:`.relationship.uselist` set to False. This will produce
+ :paramref:`_orm.relationship.uselist` set to False. This will produce
more efficient queries in these cases.
.. seealso::
:tickets: 3087
Literal values within a :class:`.DefaultClause`, which is invoked
- when using the :paramref:`.Column.server_default` parameter, will
+ when using the :paramref:`_schema.Column.server_default` parameter, will
now be rendered using the "inline" compiler, so that they are rendered
as-is, rather than as bound parameters.
:tags: bug, orm
:tickets: 3227, 3242, 1326
- The primary :class:`.Mapper` of a :class:`.Query` is now passed to the
+ The primary :class:`_orm.Mapper` of a :class:`_query.Query` is now passed to the
:meth:`.Session.get_bind` method when calling upon
- :meth:`.Query.count`, :meth:`.Query.update`, :meth:`.Query.delete`,
+ :meth:`_query.Query.count`, :meth:`_query.Query.update`, :meth:`_query.Query.delete`,
as well as queries against mapped columns,
:obj:`.column_property` objects, and SQL functions and expressions
derived from mapped columns. This allows sessions that rely upon
:tags: bug, sql
:tickets: 3288
- The multi-values version of :meth:`.Insert.values` has been
+ The multi-values version of :meth:`_expression.Insert.values` has been
repaired to work more usefully with tables that have Python-
side default values and/or functions, as well as server-side
defaults. The feature will now work with a dialect that uses
:tags: feature, schema
:tickets: 3282
- The DDL generation system of :meth:`.MetaData.create_all`
- and :meth:`.MetaData.drop_all` has been enhanced to in most
+ The DDL generation system of :meth:`_schema.MetaData.create_all`
+ and :meth:`_schema.MetaData.drop_all` has been enhanced to in most
cases automatically handle the case of mutually dependent
foreign key constraints; the need for the
- :paramref:`.ForeignKeyConstraint.use_alter` flag is greatly
+ :paramref:`_schema.ForeignKeyConstraint.use_alter` flag is greatly
reduced. The system also works for constraints which aren't given
a name up front; only in the case of DROP is a name required for
at least one of the constraints involved in the cycle.
.. change::
:tags: feature, schema
- Added a new accessor :attr:`.Table.foreign_key_constraints`
- to complement the :attr:`.Table.foreign_keys` collection,
- as well as :attr:`.ForeignKeyConstraint.referred_table`.
+ Added a new accessor :attr:`_schema.Table.foreign_key_constraints`
+ to complement the :attr:`_schema.Table.foreign_keys` collection,
+ as well as :attr:`_schema.ForeignKeyConstraint.referred_table`.
.. change::
:tags: bug, sqlite
:tags: bug, sqlite
:tickets: 3257
- The SQLite dialect, when using the :class:`.sqlite.DATE`,
- :class:`.sqlite.TIME`,
- or :class:`.sqlite.DATETIME` types, and given a ``storage_format`` that
+ The SQLite dialect, when using the :class:`_sqlite.DATE`,
+ :class:`_sqlite.TIME`,
+ or :class:`_sqlite.DATETIME` types, and given a ``storage_format`` that
only renders numbers, will render the types in DDL as
``DATE_CHAR``, ``TIME_CHAR``, and ``DATETIME_CHAR``, so that despite the
lack of alpha characters in the values, the column will still
take effect in all engine connection use cases, including
when user-custom connect routines are used via the
:paramref:`.create_engine.creator` parameter, as well as when
- the :class:`.Connection` encounters a connection error on
+ the :class:`_engine.Connection` encounters a connection error on
revalidation.
.. seealso::
:tags: bug, oracle
An alias name will be properly quoted when referred to using the
- ``%(name)s`` token inside the :meth:`.Select.with_hint` method.
+ ``%(name)s`` token inside the :meth:`_expression.Select.with_hint` method.
Previously, the Oracle backend hadn't implemented this quoting.
.. change::
Added support for CTEs under Oracle. This includes some tweaks
to the aliasing syntax, as well as a new CTE feature
- :meth:`.CTE.suffix_with`, which is useful for adding in special
+ :meth:`_expression.CTE.suffix_with`, which is useful for adding in special
Oracle-specific directives to the CTE.
.. seealso::
:tags: bug, sql
:tickets: 3260
- Fixed bug in :meth:`.Table.tometadata` method where the
+ Fixed bug in :meth:`_schema.Table.tometadata` method where the
:class:`.CheckConstraint` associated with a :class:`.Boolean`
or :class:`.Enum` type object would be doubled in the target table.
The copy process now tracks the production of this constraint object
:tickets: 3217
Added a parameter :paramref:`.Query.join.isouter` which is synonymous
- with calling :meth:`.Query.outerjoin`; this flag is to provide a more
- consistent interface compared to Core :meth:`.FromClause.join`.
+ with calling :meth:`_query.Query.outerjoin`; this flag is to provide a more
+ consistent interface compared to Core :meth:`_expression.FromClause.join`.
Pull request courtesy Jonathan Vanasco.
.. change::
:tags: bug, sql
:tickets: 3243
- The behavioral contract of the :attr:`.ForeignKeyConstraint.columns`
+ The behavioral contract of the :attr:`_schema.ForeignKeyConstraint.columns`
collection has been made consistent; this attribute is now a
- :class:`.ColumnCollection` like that of all other constraints and
+ :class:`_expression.ColumnCollection` like that of all other constraints and
is initialized at the point when the constraint is associated with
- a :class:`.Table`.
+ a :class:`_schema.Table`.
.. seealso::
The :meth:`.PropComparator.of_type` modifier has been
improved in conjunction with loader directives such as
- :func:`.joinedload` and :func:`.contains_eager` such that if
+ :func:`_orm.joinedload` and :func:`.contains_eager` such that if
two :meth:`.PropComparator.of_type` modifiers of the same
base type/path are encountered, they will be joined together
into a single "polymorphic" entity, rather than replacing
:tags: bug, sql
:tickets: 3245
- The :attr:`.Column.key` attribute is now used as the source of
+ The :attr:`_schema.Column.key` attribute is now used as the source of
anonymous bound parameter names within expressions, to match the
existing use of this value as the key when rendered in an INSERT
- or UPDATE statement. This allows :attr:`.Column.key` to be used
+ or UPDATE statement. This allows :attr:`_schema.Column.key` to be used
as a "substitute" string to work around a difficult column name
that doesn't translate well into a bound parameter name. Note that
the paramstyle is configurable on :func:`.create_engine` in any case,
:tags: feature, sql
Added a new parameter :paramref:`.Table.tometadata.name` to
- the :meth:`.Table.tometadata` method. Similar to
+ the :meth:`_schema.Table.tometadata` method. Similar to
:paramref:`.Table.tometadata.schema`, this argument causes the newly
- copied :class:`.Table` to take on the new name instead of
+ copied :class:`_schema.Table` to take on the new name instead of
the existing one. An interesting capability this adds is that of
- copying a :class:`.Table` object to the *same* :class:`.MetaData`
+ copying a :class:`_schema.Table` object to the *same* :class:`_schema.MetaData`
target with a new name. Pull request courtesy n.d. parker.
.. change::
Repaired support of the ``copy.deepcopy()`` call when used by the
:class:`.orm.util.CascadeOptions` argument, which occurs
- if ``copy.deepcopy()`` is being used with :func:`.relationship`
+ if ``copy.deepcopy()`` is being used with :func:`_orm.relationship`
(not an officially supported use case). Pull request courtesy
duesenfranz.
:tags: bug, orm
:tickets: 3228
- The :meth:`.Query.update` method will now convert string key
+ The :meth:`_query.Query.update` method will now convert string key
names in the given dictionary of values into mapped attribute names
against the mapped class being updated. Previously, string names
were taken in directly and passed to the core update statement without
any means to resolve against the mapped entity. Support for synonyms
and hybrid attributes as the subject attributes of
- :meth:`.Query.update` are also supported.
+ :meth:`_query.Query.update` are also supported.
.. seealso::
.. change::
:tags: feature, sql
- :meth:`.Insert.from_select` now includes Python and SQL-expression
+ :meth:`_expression.Insert.from_select` now includes Python and SQL-expression
defaults if otherwise unspecified; the limitation where non-
server column defaults aren't included in an INSERT FROM
SELECT is now lifted and these expressions are rendered as
:tags: bug, orm
:tickets: 3222
- The ON clause rendered when using :meth:`.Query.join`,
- :meth:`.Query.outerjoin`, or the standalone :func:`.orm.join` /
- :func:`.orm.outerjoin` functions to a single-inheritance subclass will
+ The ON clause rendered when using :meth:`_query.Query.join`,
+ :meth:`_query.Query.outerjoin`, or the standalone :func:`_orm.join` /
+ :func:`_orm.outerjoin` functions to a single-inheritance subclass will
now include the "single table criteria" in the ON clause even
if the ON clause is otherwise hand-rolled; it is now added to the
criteria using AND, the same way as if joining to a single-table
:tickets: 3184
The :class:`.UniqueConstraint` construct is now included when
- reflecting a :class:`.Table` object, for databases where this
+ reflecting a :class:`_schema.Table` object, for databases where this
is applicable. In order to achieve this
with sufficient accuracy, MySQL and PostgreSQL now contain features
that correct for the duplication of indexes and unique constraints
In the case of MySQL, there is not actually a "unique constraint"
concept independent of a "unique index", so for this backend
:class:`.UniqueConstraint` continues to remain non-present for a
- reflected :class:`.Table`. For PostgreSQL, the query used to
+ reflected :class:`_schema.Table`. For PostgreSQL, the query used to
detect indexes against ``pg_index`` has been improved to check for
the same construct in ``pg_constraint``, and the implicitly
constructed unique index is not included with a
- reflected :class:`.Table`.
+ reflected :class:`_schema.Table`.
- In both cases, the :meth:`.Inspector.get_indexes` and the
- :meth:`.Inspector.get_unique_constraints` methods return both
+ In both cases, the :meth:`_reflection.Inspector.get_indexes` and the
+ :meth:`_reflection.Inspector.get_unique_constraints` methods return both
constructs individually, but include a new token
``duplicates_constraint`` in the case of PostgreSQL or
``duplicates_index`` in the case
:tickets: 3215
Fixed bug where a "branched" connection, that is the kind you get
- when you call :meth:`.Connection.connect`, would not share invalidation
+ when you call :meth:`_engine.Connection.connect`, would not share invalidation
status with the parent. The architecture of branching has been tweaked
a bit so that the branched connection defers to the parent for
all invalidation status and operations.
:tickets: 3190
Fixed bug where a "branched" connection, that is the kind you get
- when you call :meth:`.Connection.connect`, would not share transaction
+ when you call :meth:`_engine.Connection.connect`, would not share transaction
status with the parent. The architecture of branching has been tweaked
a bit so that the branched connection defers to the parent for
all transactional status and operations.
one or more non-nullable columns. This argument is present in the
keywords passed to :func:`.automap.generate_relationship` in this
case and can still be overridden. Additionally, if the
- :class:`.ForeignKeyConstraint` specifies ``ondelete="CASCADE"``
+ :class:`_schema.ForeignKeyConstraint` specifies ``ondelete="CASCADE"``
for a non-nullable or ``ondelete="SET NULL"`` for a nullable set
of columns, the argument ``passive_deletes=True`` is also added to the
relationship. Note that not all backends support reflection of
:tags: feature, sql
:tickets: 3206
- Added new method :meth:`.Select.with_statement_hint` and ORM
- method :meth:`.Query.with_statement_hint` to support statement-level
+ Added new method :meth:`_expression.Select.with_statement_hint` and ORM
+ method :meth:`_query.Query.with_statement_hint` to support statement-level
hints that are not specific to a table.
.. change::
:tags: bug, sqlite
:tickets: 3204
- Added :meth:`.Inspector.get_temp_table_names` and
- :meth:`.Inspector.get_temp_view_names`; currently, only the
+ Added :meth:`_reflection.Inspector.get_temp_table_names` and
+ :meth:`_reflection.Inspector.get_temp_view_names`; currently, only the
SQLite and Oracle dialects support these methods. The return of
temporary table and view names has been **removed** from SQLite and
- Oracle's version of :meth:`.Inspector.get_table_names` and
- :meth:`.Inspector.get_view_names`; other database backends cannot
+ Oracle's version of :meth:`_reflection.Inspector.get_table_names` and
+ :meth:`_reflection.Inspector.get_view_names`; other database backends cannot
support this information (such as MySQL), and the scope of operation
is different in that the tables can be local to a session and
typically aren't supported in remote schemas.
Support has been added for reflection of materialized views
and foreign tables, as well as support for materialized views
- within :meth:`.Inspector.get_view_names`, and a new method
+ within :meth:`_reflection.Inspector.get_view_names`, and a new method
:meth:`.PGInspector.get_foreign_table_names` available on the
- PostgreSQL version of :class:`.Inspector`. Pull request courtesy
+ PostgreSQL version of :class:`_reflection.Inspector`. Pull request courtesy
Rodrigo Menezes.
.. seealso::
.. change::
:tags: changed, sql
- The :func:`~.expression.column` and :func:`~.expression.table`
+ The :func:`_expression.column` and :func:`_expression.table`
constructs are now importable from the "from sqlalchemy" namespace,
just like every other Core construct.
:tags: changed, sql
:tickets: 2992
- The implicit conversion of strings to :func:`.text` constructs
- when passed to most builder methods of :func:`~.sql.expression.select` as
- well as :class:`.Query` now emits a warning with just the
+ The implicit conversion of strings to :func:`_expression.text` constructs
+ when passed to most builder methods of :func:`_expression.select` as
+ well as :class:`_query.Query` now emits a warning with just the
plain string sent. The textual conversion still proceeds normally,
however. The only method that accepts a string without a warning
are the "label reference" methods like order_by(), group_by();
.. change::
:tags: feature, orm
- The :class:`.Query` will raise an exception when :meth:`.Query.yield_per`
+ The :class:`_query.Query` will raise an exception when :meth:`_query.Query.yield_per`
is used with mappings or options where either
subquery eager loading, or joined eager loading with collections,
would take place. These loading strategies are
not currently compatible with yield_per, so by raising this error,
the method is safer to use. Eager loads can be disabled with
- the ``lazyload('*')`` option or :meth:`.Query.enable_eagerloads`.
+ the ``lazyload('*')`` option or :meth:`_query.Query.enable_eagerloads`.
.. seealso::
:tickets: 3177
Changed the approach by which the "single inheritance criterion"
- is applied, when using :meth:`.Query.from_self`, or its common
- user :meth:`.Query.count`. The criteria to limit rows to those
+ is applied, when using :meth:`_query.Query.from_self`, or its common
+ user :meth:`_query.Query.count`. The criteria to limit rows to those
with a certain type is now indicated on the inside subquery,
not the outside one, so that even if the "type" column is not
available in the columns clause, we can filter on it on the "inner"
:tickets: 3176
A new implementation for :class:`.KeyedTuple` used by the
- :class:`.Query` object offers dramatic speed improvements when
+ :class:`_query.Query` object offers dramatic speed improvements when
fetching large numbers of column-oriented rows.
.. seealso::
:tags: feature, orm
:tickets: 3008
- The behavior of :paramref:`.joinedload.innerjoin` as well as
- :paramref:`.relationship.innerjoin` is now to use "nested"
+ The behavior of :paramref:`_orm.joinedload.innerjoin` as well as
+ :paramref:`_orm.relationship.innerjoin` is now to use "nested"
inner joins, that is, right-nested, as the default behavior when an
inner join joined eager load is chained to an outer join eager load.
:tags: bug, sql
:tickets: 3169
- Using :meth:`.Insert.from_select` now implies ``inline=True``
- on :func:`~.sql.expression.insert`. This helps to fix a bug where an
+ Using :meth:`_expression.Insert.from_select` now implies ``inline=True``
+ on :func:`_expression.insert`. This helps to fix a bug where an
INSERT...FROM SELECT construct would inadvertently be compiled
as "implicit returning" on supporting backends, which would
cause breakage in the case of an INSERT that inserts zero rows
may prefer ``inline=True`` with INSERT..FROM SELECT as some databases
don't support returning and therefore can't do "implicit" returning,
but there's no reason an INSERT...FROM SELECT needs implicit returning
- in any case. Regular explicit :meth:`.Insert.returning` should
+ in any case. Regular explicit :meth:`_expression.Insert.returning` should
be used to return variable numbers of result rows if inserted
data is needed.
Added support for PG table options TABLESPACE, ON COMMIT,
WITH(OUT) OIDS, and INHERITS, when rendering DDL via
- the :class:`.Table` construct. Pull request courtesy
+ the :class:`_schema.Table` construct. Pull request courtesy
malikdiarra.
.. seealso::
:tickets: 2963
The ``info`` parameter has been added as a constructor argument
- to all schema constructs including :class:`.MetaData`,
- :class:`.Index`, :class:`.ForeignKey`, :class:`.ForeignKeyConstraint`,
+ to all schema constructs including :class:`_schema.MetaData`,
+ :class:`.Index`, :class:`_schema.ForeignKey`, :class:`_schema.ForeignKeyConstraint`,
:class:`.UniqueConstraint`, :class:`.PrimaryKeyConstraint`,
:class:`.CheckConstraint`.
:class:`.InspectionAttr`, where in addition to being available
on all :class:`.MapperProperty` objects, it is also now available
on hybrid properties, association proxies, when accessed via
- :attr:`.Mapper.all_orm_descriptors`.
+ :attr:`_orm.Mapper.all_orm_descriptors`.
.. change::
:tags: sql, feature
:tickets: 3027
- The :paramref:`.Table.autoload_with` flag now implies that
- :paramref:`.Table.autoload` should be ``True``. Pull request
+ The :paramref:`_schema.Table.autoload_with` flag now implies that
+ :paramref:`_schema.Table.autoload` should be ``True``. Pull request
courtesy Malik Diarra.
.. change::
:tags: feature, sql
:tickets: 3034
- The :meth:`.Select.limit` and :meth:`.Select.offset` methods
+ The :meth:`_expression.Select.limit` and :meth:`_expression.Select.offset` methods
now accept any SQL expression, in addition to integer values, as
arguments. Typically this is used to allow a bound parameter to be
passed, which can be substituted with a value later thus allowing
:tickets: 4162
:versions: 1.2.1
- Fixed bug in :meth:`.Insert.values` where using the "multi-values"
- format in combination with :class:`.Column` objects as keys rather
+ Fixed bug in :meth:`_expression.Insert.values` where using the "multi-values"
+ format in combination with :class:`_schema.Column` objects as keys rather
than strings would fail. Pull request courtesy Aubrey Stark-Toller.
.. change::
Fixed a fairly serious connection pool bug where a connection that is
acquired after being refreshed as a result of a user-defined
- :class:`.DisconnectionError` or due to the 1.2-released "pre_ping" feature
+ :class:`_exc.DisconnectionError` or due to the 1.2-released "pre_ping" feature
would not be correctly reset if the connection were returned to the pool by
weakref cleanup (e.g. the front-facing object is garbage collected); the
weakref would still refer to the previously invalidated DBAPI connection
:tickets: 4006
:versions: 1.2.0b3
- Made further fixes to the :class:`.ARRAY` class in conjunction with
+ Made further fixes to the :class:`_types.ARRAY` class in conjunction with
COLLATE, as the fix made in :ticket:`4006` failed to accommodate
for a multidimensional array.
:tickets: 4107
:versions: 1.2.0b3
- Fixed bug in :obj:`.array_agg` function where passing an argument
- that is already of type :class:`.ARRAY`, such as a PostgreSQL
- :obj:`.postgresql.array` construct, would produce a ``ValueError``, due
+ Fixed bug in :obj:`_functions.array_agg` function where passing an argument
+ that is already of type :class:`_types.ARRAY`, such as a PostgreSQL
+ :obj:`_postgresql.array` construct, would produce a ``ValueError``, due
to the function attempting to nest the arrays.
.. change::
Fixed bug in PostgreSQL :meth:`.postgresql.dml.Insert.on_conflict_do_update`
which would prevent the insert statement from being used as a CTE,
- e.g. via :meth:`.Insert.cte`, within another statement.
+ e.g. via :meth:`_expression.Insert.cte`, within another statement.
.. change::
:tags: bug, orm
Fixed bug where the recently added :meth:`.ColumnOperators.any_`
and :meth:`.ColumnOperators.all_` methods didn't work when called
as methods, as opposed to using the standalone functions
- :func:`~.expression.any_` and :func:`~.expression.all_`. Also
+ :func:`_expression.any_` and :func:`_expression.all_`. Also
added documentation examples for these relatively unintuitive
SQL operators.
Fixed bug involving JSON NULL evaluation logic added in 1.1 as part
of :ticket:`3514` where the logic would not accommodate ORM
- mapped attributes named differently from the :class:`.Column`
+ mapped attributes named differently from the :class:`_schema.Column`
that was mapped.
.. change:: 4030
:tickets: 4006
:versions: 1.2.0b1
- Fixed bug where using :class:`.ARRAY` with a string type that
+ Fixed bug where using :class:`_types.ARRAY` with a string type that
features a collation would fail to produce the correct syntax
within CREATE TABLE.
:tickets: 3973
:versions: 1.2.0b1
- Added a placeholder type :class:`.mssql.XML` to the SQL Server
+ Added a placeholder type :class:`_mssql.XML` to the SQL Server
dialect, so that a reflected table which includes this type can
be re-rendered as a CREATE TABLE. The type has no special round-trip
behavior nor does it currently support additional qualifying
:tickets: 3949
An :class:`.ArgumentError` is now raised if a
- :class:`.ForeignKeyConstraint` object is created with a mismatched
+ :class:`_schema.ForeignKeyConstraint` object is created with a mismatched
number of "local" and "remote" columns, which otherwise causes the
internal state of the constraint to be incorrect. Note that this
also impacts the condition where a dialect's reflection process
:tickets: 3955
Changed the mechanics of :class:`.ResultProxy` to unconditionally
- delay the "autoclose" step until the :class:`.Connection` is done
+ delay the "autoclose" step until the :class:`_engine.Connection` is done
with the object; in the case where PostgreSQL ON CONFLICT with
RETURNING returns no rows, autoclose was occurring in this previously
non-existent use case, causing the usual autocommit behavior that
been copied using :meth:`.TypeEngine.copy`. This became more of
a regression in 1.1 compared to 1.0 because the :class:`.TypeDecorator`
class is now a subclass of :class:`.SchemaEventTarget`, which among
- other things indicates to the parent :class:`.Column` that the type
- should be copied when the :class:`.Column` is. These copies are
+ other things indicates to the parent :class:`_schema.Column` that the type
+ should be copied when the :class:`_schema.Column` is. These copies are
common when using declarative with mixins or abstract classes.
.. change::
:versions: 1.2.0b1
Added support for bound parameters, e.g. those normally set up
- via :meth:`.Query.params`, to the :meth:`.baked.Result.count`
+ via :meth:`_query.Query.params`, to the :meth:`.baked.Result.count`
method. Previously, support for parameters were omitted. Pull request
courtesy Pat Deegan.
:versions: 1.2.0b1
An :func:`.aliased()` construct can now be passed to the
- :meth:`.Query.select_entity_from` method. Entities will be pulled
+ :meth:`_query.Query.select_entity_from` method. Entities will be pulled
from the selectable represented by the :func:`.aliased` construct.
This allows special options for :func:`.aliased` such as
:paramref:`.aliased.adapt_on_names` to be used in conjunction with
- :meth:`.Query.select_entity_from`.
+ :meth:`_query.Query.select_entity_from`.
.. change::
:tags: bug, engine
:versions: 1.2.0b1
Added an exception handler that will warn for the "cause" exception on
- Py2K when the "autorollback" feature of :class:`.Connection` itself
+ Py2K when the "autorollback" feature of :class:`_engine.Connection` itself
raises an exception. In Py3K, the two exceptions are naturally reported
by the interpreter as one occurring during the handling of the other.
This is continuing with the series of changes for rollback failure
Fixed bug in compiler where the string identifier of a savepoint would
be cached in the identifier quoting dictionary; as these identifiers
are arbitrary, a small memory leak could occur if a single
- :class:`.Connection` had an unbounded number of savepoints used,
+ :class:`_engine.Connection` had an unbounded number of savepoints used,
as well as if the savepoint clause constructs were used directly
with an unbounded umber of savepoint names. The memory leak does
**not** impact the vast majority of cases as normally the
- :class:`.Connection`, which renders savepoint names with a simple
+ :class:`_engine.Connection`, which renders savepoint names with a simple
counter starting at "1", is used on a per-transaction or
per-fixed-number-of-transactions basis before being discarded.
allow a non-textual expression to be passed as the value of the
"default" for the new column, such as a :class:`.FetchedValue`
object to indicate a generic triggered default or a
- :func:`.sql.expression.text` construct. Clarified the documentation
+ :func:`_expression.text` construct. Clarified the documentation
in this regard as well.
.. change:: 3901
Fixed bug in PostgreSQL :class:`.ExcludeConstraint` where the
"whereclause" and "using" parameters would not be copied during an
- operation like :meth:`.Table.tometadata`.
+ operation like :meth:`_schema.Table.tometadata`.
.. change:: 3898
:tags: bug, mssql
:tickets: 3880
Fixed bug where literal_binds compiler flag was not honored by the
- :class:`~.sql.expression.Insert` construct for the "multiple values" feature; the
+ :class:`_expression.Insert` construct for the "multiple values" feature; the
subsequent values are now rendered as literals.
.. change:: 3877
:tags: bug, sql
The engine URL embedded in the exception for "could not reflect"
- in :meth:`.MetaData.reflect` now conceals the password; also
+ in :meth:`_schema.MetaData.reflect` now conceals the password; also
the ``__repr__`` for :class:`.TLEngine` now acts like that of
- :class:`.Engine`, concealing the URL password. Pull request courtesy
+ :class:`_engine.Engine`, concealing the URL password. Pull request courtesy
Valery Yundin.
.. change:: 3867
.. change:: pg_timestamp_zero_prec
:tags: bug, postgresql
- The :class:`.postgresql.TIME` and :class:`.postgresql.TIMESTAMP`
+ The :class:`_postgresql.TIME` and :class:`_postgresql.TIMESTAMP`
datatypes now support a setting of zero for "precision"; previously
a zero would be ignored. Pull request courtesy Ionuț Ciocîrlan.
:tags: bug, engine
:tickets: 3861
- The "extend_existing" option of :class:`.Table` reflection would
+ The "extend_existing" option of :class:`_schema.Table` reflection would
cause indexes and constraints to be doubled up in the case that the parameter
- were used with :meth:`.MetaData.reflect` (as the automap extension does)
+ were used with :meth:`_schema.MetaData.reflect` (as the automap extension does)
due to tables being reflected both within the foreign key path as well
as directly. A new de-duplicating set is passed through within the
- :meth:`.MetaData.reflect` sequence to prevent double reflection in this
+ :meth:`_schema.MetaData.reflect` sequence to prevent double reflection in this
way.
.. change:: 3859
:tickets: 3856
Fixed bug related to :ticket:`3177`, where a UNION or other set operation
- emitted by a :class:`.Query` would apply "single-inheritance" criteria
+ emitted by a :class:`_query.Query` would apply "single-inheritance" criteria
to the outside of the union (also referencing the wrong selectable),
even though this criteria is now expected to
be already present on the inside subqueries. The single-inheritance
criteria is now omitted once union() or another set operation is
- called against :class:`.Query` in the same way as :meth:`.Query.from_self`.
+ called against :class:`_query.Query` in the same way as :meth:`_query.Query.from_self`.
.. change:: 3548
:tags: bug, firebird
:tags: bug, engine
Removed long-broken "default_schema_name()" method from
- :class:`.Connection`. This method was left over from a very old
+ :class:`_engine.Connection`. This method was left over from a very old
version and was non-working (e.g. would raise). Pull request
courtesy Benjamin Dopplinger.
:tickets: 3835
PostgreSQL table reflection will ensure that the
- :paramref:`.Column.autoincrement` flag is set to False when reflecting
+ :paramref:`_schema.Column.autoincrement` flag is set to False when reflecting
a primary key column that is not of an :class:`.Integer` datatype,
even if the default is related to an integer-generating sequence.
This can happen if a column is created as SERIAL and the datatype
:tags: bug, orm
:tickets: 3836
- Fixed regression where some :class:`.Query` methods like
- :meth:`.Query.update` and others would fail if the :class:`.Query`
+ Fixed regression where some :class:`_query.Query` methods like
+ :meth:`_query.Query.update` and others would fail if the :class:`_query.Query`
were against a series of mapped columns, rather than the mapped
entity as a whole.
ORM attributes can now be assigned any object that is has a
``__clause_element__()`` attribute, which will result in inline
- SQL the way any :class:`.ClauseElement` class does. This covers other
+ SQL the way any :class:`_expression.ClauseElement` class does. This covers other
mapped attributes not otherwise transformed by further expression
constructs.
Enhanced the new "raise" lazy loader strategy to also include a
"raise_on_sql" variant, available both via :paramref:`.orm.relationship.lazy`
- as well as :func:`.orm.raiseload`. This variant only raises if the
+ as well as :func:`_orm.raiseload`. This variant only raises if the
lazy load would actually emit SQL, vs. raising if the lazy loader
mechanism is invoked at all.
:tickets: 3809
A string sent as a column default via the
- :paramref:`.Column.server_default` parameter is now escaped for quotes.
+ :paramref:`_schema.Column.server_default` parameter is now escaped for quotes.
.. seealso::
:tickets: 3803
The ``BaseException`` exception class is now intercepted by the
- exception-handling routines of :class:`.Connection`, and includes
+ exception-handling routines of :class:`_engine.Connection`, and includes
handling by the :meth:`~.ConnectionEvents.handle_error`
- event. The :class:`.Connection` is now **invalidated** by default in
+ event. The :class:`_engine.Connection` is now **invalidated** by default in
the case of a system level exception that is not a subclass of
``Exception``, including ``KeyboardInterrupt`` and the greenlet
``GreenletExit`` class, to prevent further operations from occurring
:tags: bug, orm
:tickets: 3767
- The primaryjoin of a :func:`.relationship` construct can now include
+ The primaryjoin of a :func:`_orm.relationship` construct can now include
a :func:`.bindparam` object that includes a callable function to
generate values. Previously, the lazy loader strategy would
be incompatible with this use, and additionally would fail to correctly
:tags: bug, sql
:tickets: 3789
- Stringify of expression with unnamed :class:`.Column` objects, as
+ Stringify of expression with unnamed :class:`_schema.Column` objects, as
occurs in lots of situations including ORM error reporting,
will now render the name in string context as "<name unknown>"
rather than raising a compile error.
.. change::
:tags: change, orm
- Passing False to :meth:`.Query.order_by` in order to cancel
+ Passing False to :meth:`_query.Query.order_by` in order to cancel
all order by's is deprecated; there is no longer any difference
between calling this method with False or with None.
.. change::
:tags: feature, orm
- The :meth:`.Query.group_by` method now resets the group by collection
+ The :meth:`_query.Query.group_by` method now resets the group by collection
if an argument of ``None`` is passed, in the same way that
- :meth:`.Query.order_by` has worked for a long time. Pull request
+ :meth:`_query.Query.order_by` has worked for a long time. Pull request
courtesy Iuri Diniz.
.. change::
:tickets: 3744
Fixed bug in new CTE feature for update/insert/delete whereby
- an anonymous (e.g. no name passed) :class:`.CTE` construct around
+ an anonymous (e.g. no name passed) :class:`_expression.CTE` construct around
the statement would fail.
.. change::
extension, whereby the existing compilation schemes for an established
construct would be removed if that construct itself didn't already
have its own dedicated ``__visit_name__``. This was a
- rare occurrence in 1.0, however in 1.1 :class:`.postgresql.ARRAY`
- subclasses :class:`.sqltypes.ARRAY` and has this behavior.
+ rare occurrence in 1.0, however in 1.1 :class:`_postgresql.ARRAY`
+ subclasses :class:`_types.ARRAY` and has this behavior.
As a result, setting up a compilation handler for another dialect
- such as SQLite would render the main :class:`.postgresql.ARRAY`
+ such as SQLite would render the main :class:`_postgresql.ARRAY`
object no longer compilable.
.. change::
:tags: feature, sql
:tickets: 3718
- Added TABLESAMPLE support via the new :meth:`.FromClause.tablesample`
+ Added TABLESAMPLE support via the new :meth:`_expression.FromClause.tablesample`
method and standalone function. Pull request courtesy Ilja Everilä.
.. seealso::
:tags: bug, sql
:tickets: 3724
- :meth:`.FromClause.count` is deprecated. This function makes use of
+ :meth:`_expression.FromClause.count` is deprecated. This function makes use of
an arbitrary column in the table and is not reliable; for Core use,
``func.count()`` should be preferred.
Added ``postgresql_tablespace`` as an argument to :class:`.Index`
to allow specification of TABLESPACE for an index in PostgreSQL.
- Complements the same-named parameter on :class:`.Table`. Pull
+ Complements the same-named parameter on :class:`_schema.Table`. Pull
request courtesy Benjamin Bertrand.
.. change::
Implemented reflection of CHECK constraints for SQLite and PostgreSQL.
This is available via the new inspector method
- :meth:`.Inspector.get_check_constraints` as well as when reflecting
- :class:`.Table` objects in the form of :class:`.CheckConstraint`
+ :meth:`_reflection.Inspector.get_check_constraints` as well as when reflecting
+ :class:`_schema.Table` objects in the form of :class:`.CheckConstraint`
objects present in the constraints collection. Pull request courtesy
Alex Grönholm.
:tags: change, orm
:tickets: 3394
- The :paramref:`.Mapper.order_by` parameter is deprecated.
+ The :paramref:`_orm.Mapper.order_by` parameter is deprecated.
This is an old parameter no longer relevant to how SQLAlchemy
works, once the Query object was introduced. By deprecating it
we establish that we aren't supporting non-working use cases
:tags: feature, sql
:tickets: 2857
- Added :meth:`.Select.lateral` and related constructs to allow
+ Added :meth:`_expression.Select.lateral` and related constructs to allow
for the SQL standard LATERAL keyword, currently only supported
by PostgreSQL.
:tags: bug, orm
:tickets: 3662
- An improvement to the workings of :meth:`.Query.correlate` such
+ An improvement to the workings of :meth:`_query.Query.correlate` such
that when a "polymorphic" entity is used which represents a straight
join of several tables, the statement will ensure that all the
tables within the join are part of what's correlating.
:tickets: 3641
A refinement to the logic which adds columns to the resulting SQL when
- :meth:`.Query.distinct` is combined with :meth:`.Query.order_by` such
+ :meth:`_query.Query.distinct` is combined with :meth:`_query.Query.order_by` such
that columns which are already present will not be added
a second time, even if they are labeled with a different name.
Regardless of this change, the extra columns added to the SQL have
Added support for PEP-435-style enumerated classes, namely
Python 3's ``enum.Enum`` class but also including compatible
- enumeration libraries, to the :class:`.types.Enum` datatype.
- The :class:`.types.Enum` datatype now also performs in-Python validation
+ enumeration libraries, to the :class:`_types.Enum` datatype.
+ The :class:`_types.Enum` datatype now also performs in-Python validation
of incoming values, and adds an option to forego creating the
CHECK constraint :paramref:`.Enum.create_constraint`.
Pull request courtesy Alex Grönholm.
:tags: feature, orm
:tickets: 3081
- The ``str()`` call for :class:`.Query` will now take into account
- the :class:`.Engine` to which the :class:`.Session` is bound, when
+ The ``str()`` call for :class:`_query.Query` will now take into account
+ the :class:`_engine.Engine` to which the :class:`.Session` is bound, when
generating the string form of the SQL, so that the actual SQL
that would be emitted to the database is shown, if possible. Previously,
- only the engine associated with the :class:`.MetaData` to which the
+ only the engine associated with the :class:`_schema.MetaData` to which the
mappings are associated would be used, if present. If
no bind can be located either on the :class:`.Session` or on
- the :class:`.MetaData` to which the mappings are associated, then
+ the :class:`_schema.MetaData` to which the mappings are associated, then
the "default" dialect is used to render the SQL, as was the case
previously.
:tags: feature, sql
:tickets: 3501
- A deep improvement to the recently added :meth:`.TextClause.columns`
+ A deep improvement to the recently added :meth:`_expression.TextClause.columns`
method, and its interaction with result-row processing, now allows
the columns passed to the method to be positionally matched with the
result columns in the statement, rather than matching on name alone.
:tags: feature, engine
:tickets: 2685
- Multi-tenancy schema translation for :class:`.Table` objects is added.
+ Multi-tenancy schema translation for :class:`_schema.Table` objects is added.
This supports the use case of an application that uses the same set of
- :class:`.Table` objects in many schemas, such as schema-per-user.
+ :class:`_schema.Table` objects in many schemas, such as schema-per-user.
A new execution option
:paramref:`.Connection.execution_options.schema_translate_map` is
added.
:tags: feature, sql
:tickets: 3619
- Added a new type to core :class:`.types.JSON`. This is the
- base of the PostgreSQL :class:`.postgresql.JSON` type as well as that
+ Added a new type to core :class:`_types.JSON`. This is the
+ base of the PostgreSQL :class:`_postgresql.JSON` type as well as that
of the new :class:`.mysql.JSON` type, so that a PG/MySQL-agnostic
JSON column may be used. The type features basic index and path
searching support.
:tickets: 3616
Fixed an assertion that would raise somewhat inappropriately
- if a :class:`.Index` were associated with a :class:`.Column` that
- is associated with a lower-case-t :class:`.TableClause`; the
+ if a :class:`.Index` were associated with a :class:`_schema.Column` that
+ is associated with a lower-case-t :class:`_expression.TableClause`; the
association should be ignored for the purposes of associating
- the index with a :class:`.Table`.
+ the index with a :class:`_schema.Table`.
.. change::
:tags: bug, orm
:tickets: 3587
Added support for reflecting the source of materialized views
- to the PostgreSQL version of the :meth:`.Inspector.get_view_definition`
+ to the PostgreSQL version of the :meth:`_reflection.Inspector.get_view_definition`
method.
.. change::
.. change::
:tags: enhancement, schema
- The default generation functions passed to :class:`.Column` objects
+ The default generation functions passed to :class:`_schema.Column` objects
are now run through "update_wrapper", or an equivalent function
if a callable non-function is passed, so that introspection tools
preserve the name and docstring of the wrapped function. Pull
:tags: change, sql, mysql
:tickets: 3216
- The system by which a :class:`.Column` considers itself to be an
+ The system by which a :class:`_schema.Column` considers itself to be an
"auto increment" column has been changed, such that autoincrement
- is no longer implicitly enabled for a :class:`.Table` that has a
+ is no longer implicitly enabled for a :class:`_schema.Table` that has a
composite primary key. In order to accommodate being able to enable
autoincrement for a composite PK member column while at the same time
maintaining SQLAlchemy's long standing behavior of enabling
implicit autoincrement for a single integer primary key, a third
- state has been added to the :paramref:`.Column.autoincrement` parameter
+ state has been added to the :paramref:`_schema.Column.autoincrement` parameter
``"auto"``, which is now the default.
.. seealso::
:tags: change, sqlite
Added support to the SQLite dialect for the
- :meth:`.Inspector.get_schema_names` method to work with SQLite;
+ :meth:`_reflection.Inspector.get_schema_names` method to work with SQLite;
pull request courtesy Brian Van Klaveren. Also repaired support
for creation of indexes with schemas as well as reflection of
foreign key constraints in schema-bound tables.
:tags: bug, postgresql
:tickets: 2729
- The use of a :class:`.postgresql.ARRAY` object that refers
- to a :class:`.types.Enum` or :class:`.postgresql.ENUM` subtype
+ The use of a :class:`_postgresql.ARRAY` object that refers
+ to a :class:`_types.Enum` or :class:`_postgresql.ENUM` subtype
will now emit the expected "CREATE TYPE" and "DROP TYPE" DDL when
the type is used within a "CREATE TABLE" or "DROP TABLE".
:tags: feature, sql, postgresql
:tickets: 3132
- Added support for the SQL-standard function :class:`.array_agg`,
- which automatically returns an :class:`.postgresql.ARRAY` of the correct type
+ Added support for the SQL-standard function :class:`_functions.array_agg`,
+ which automatically returns an :class:`_postgresql.ARRAY` of the correct type
and supports index / slice operations, as well as
- :func:`.postgresql.array_agg`, which returns a :class:`.postgresql.ARRAY`
+ :func:`_postgresql.array_agg`, which returns a :class:`_postgresql.ARRAY`
with additional comparison features. As arrays are only
supported on PostgreSQL at the moment, only actually works on
PostgreSQL. Also added a new construct
- :class:`.postgresql.aggregate_order_by` in support of PG's
+ :class:`_postgresql.aggregate_order_by` in support of PG's
"ORDER BY" extension.
.. seealso::
:tags: feature, sql
:tickets: 3516
- Added a new type to core :class:`.types.ARRAY`. This is the
- base of the PostgreSQL :class:`.postgresql.ARRAY` type, and is now part of Core
+ Added a new type to core :class:`_types.ARRAY`. This is the
+ base of the PostgreSQL :class:`_postgresql.ARRAY` type, and is now part of Core
to begin supporting various SQL-standard array-supporting features
including some functions and eventual support for native arrays
on other databases that have an "array" concept, such as DB2 or Oracle.
- Additionally, new operators :func:`.expression.any_` and
- :func:`.expression.all_` have been added. These support not just
+ Additionally, new operators :func:`_expression.any_` and
+ :func:`_expression.all_` have been added. These support not just
array constructs on PostgreSQL, but also subqueries that are usable
on MySQL (but sadly not on PostgreSQL).
:tags: bug, postgresql
:tickets: 3499
- The "hashable" flag on special datatypes such as :class:`.postgresql.ARRAY`,
- :class:`.postgresql.JSON` and :class:`.postgresql.HSTORE` is now
+ The "hashable" flag on special datatypes such as :class:`_postgresql.ARRAY`,
+ :class:`_postgresql.JSON` and :class:`_postgresql.HSTORE` is now
set to False, which allows these types to be fetchable in ORM
queries that include entities within the row.
:tags: bug, postgresql
:tickets: 3487
- The PostgreSQL :class:`.postgresql.ARRAY` type now supports multidimensional
+ The PostgreSQL :class:`_postgresql.ARRAY` type now supports multidimensional
indexed access, e.g. expressions such as ``somecol[5][6]`` without
any need for explicit casts or type coercions, provided
that the :paramref:`.postgresql.ARRAY.dimensions` parameter is set to the
:tags: bug, postgresql
:tickets: 3503
- The return type for the :class:`.postgresql.JSON` and :class:`.postgresql.JSONB`
+ The return type for the :class:`_postgresql.JSON` and :class:`_postgresql.JSONB`
when using indexed access has been fixed to work like PostgreSQL itself,
- and returns an expression that itself is of type :class:`.postgresql.JSON`
- or :class:`.postgresql.JSONB`. Previously, the accessor would return
+ and returns an expression that itself is of type :class:`_postgresql.JSON`
+ or :class:`_postgresql.JSONB`. Previously, the accessor would return
:class:`.NullType` which disallowed subsequent JSON-like operators to be
used.
:tags: bug, postgresql
:tickets: 3503
- The :class:`.postgresql.JSON`, :class:`.postgresql.JSONB` and
- :class:`.postgresql.HSTORE` datatypes now allow full control over the
+ The :class:`_postgresql.JSON`, :class:`_postgresql.JSONB` and
+ :class:`_postgresql.HSTORE` datatypes now allow full control over the
return type from an indexed textual access operation, either ``column[someindex].astext``
for a JSON type or ``column[someindex]`` for an HSTORE type,
via the :paramref:`.postgresql.JSON.astext_type` and
:tickets: 3503
The :attr:`.postgresql.JSON.Comparator.astext` modifier no longer
- calls upon :meth:`.ColumnElement.cast` implicitly, as PG's JSON/JSONB
+ calls upon :meth:`_expression.ColumnElement.cast` implicitly, as PG's JSON/JSONB
types allow cross-casting between each other as well. Code that
- makes use of :meth:`.ColumnElement.cast` on JSON indexed access,
+ makes use of :meth:`_expression.ColumnElement.cast` on JSON indexed access,
e.g. ``col[someindex].cast(Integer)``, will need to be changed
to call :attr:`.postgresql.JSON.Comparator.astext` explicitly.
:tickets: 3514
Additional fixes have been made regarding the value of ``None``
- in conjunction with the PostgreSQL :class:`.postgresql.JSON` type. When
- the :paramref:`.JSON.none_as_null` flag is left at its default
+ in conjunction with the PostgreSQL :class:`_postgresql.JSON` type. When
+ the :paramref:`_types.JSON.none_as_null` flag is left at its default
value of ``False``, the ORM will now correctly insert the JSON
"'null'" string into the column whenever the value on the ORM
object is set to the value ``None`` or when the value ``None``
:tags: bug, sql
:tickets: 2528
- The behavior of the :func:`.union` construct and related constructs
- such as :meth:`.Query.union` now handle the case where the embedded
+ The behavior of the :func:`_expression.union` construct and related constructs
+ such as :meth:`_query.Query.union` now handle the case where the embedded
SELECT statements need to be parenthesized due to the fact that they
include LIMIT, OFFSET and/or ORDER BY. These queries **do not work
on SQLite**, and will fail on that backend as they did before, but
:tags: feature, orm
:tickets: 3512
- Added new relationship loading strategy :func:`.orm.raiseload` (also
+ Added new relationship loading strategy :func:`_orm.raiseload` (also
accessible via ``lazy='raise'``). This strategy behaves almost like
- :func:`.orm.noload` but instead of returning ``None`` it raises an
+ :func:`_orm.noload` but instead of returning ``None`` it raises an
InvalidRequestError. Pull request courtesy Adrian Moennich.
.. seealso::
:tags: bug, oracle
:tickets: 4506
- Added support for reflection of the :class:`.NCHAR` datatype to the Oracle
- dialect, and added :class:`.NCHAR` to the list of types exported by the
+ Added support for reflection of the :class:`_types.NCHAR` datatype to the Oracle
+ dialect, and added :class:`_types.NCHAR` to the list of types exported by the
Oracle dialect.
:tags: bug, sql
:tickets: 4485
- Fixed issue where the :class:`.JSON` type had a read-only
- :attr:`.JSON.should_evaluate_none` attribute, which would cause failures
+ Fixed issue where the :class:`_types.JSON` type had a read-only
+ :attr:`_types.JSON.should_evaluate_none` attribute, which would cause failures
when making use of the :meth:`.TypeEngine.evaluates_none` method in
conjunction with this type. Pull request courtesy Sanjana S.
Fixed bug where the SQL Server "IDENTITY_INSERT" logic that allows an INSERT
to proceed with an explicit value on an IDENTITY column was not detecting
- the case where :meth:`.Insert.values` were used with a dictionary that
- contained a :class:`.Column` as key and a SQL expression as a value.
+ the case where :meth:`_expression.Insert.values` were used with a dictionary that
+ contained a :class:`_schema.Column` as key and a SQL expression as a value.
.. change::
:tags: bug, sqlite
Added new event hooks :meth:`.QueryEvents.before_compile_update` and
:meth:`.QueryEvents.before_compile_delete` which complement
- :meth:`.QueryEvents.before_compile` in the case of the :meth:`.Query.update`
- and :meth:`.Query.delete` methods.
+ :meth:`.QueryEvents.before_compile` in the case of the :meth:`_query.Query.update`
+ and :meth:`_query.Query.delete` methods.
.. change::
:tags: bug, postgresql
:tickets: 4416
- Fixed issue where a :class:`.postgresql.ENUM` or a custom domain present
+ Fixed issue where a :class:`_postgresql.ENUM` or a custom domain present
in a remote schema would not be recognized within column reflection if
the name of the enum/domain or the name of the schema required quoting.
A new parsing scheme now fully parses out quoted or non-quoted tokens
.. change::
:tags: bug, postgresql
- Fixed issue where multiple :class:`.postgresql.ENUM` objects referred to
- by the same :class:`.MetaData` object would fail to be created if
+ Fixed issue where multiple :class:`_postgresql.ENUM` objects referred to
+ by the same :class:`_schema.MetaData` object would fail to be created if
multiple objects had the same name under different schema names. The
internal memoization the PostgreSQL dialect uses to track if it has
- created a particular :class:`.postgresql.ENUM` in the database during
+ created a particular :class:`_postgresql.ENUM` in the database during
a DDL creation sequence now takes schema name into account.
.. change::
primaryjoin/secondaryjoin a relationship if one used the pattern
``ForeignKey(SomeClass.id)`` in the declarative mappings. This pattern
would leak undesired annotations into the join conditions which can break
- aliasing operations done within :class:`.Query` that are not supposed to
+ aliasing operations done within :class:`_query.Query` that are not supposed to
impact elements in that join condition. These annotations are now removed
up front if present.
:tags: bug, orm, declarative
:tickets: 4374
- A warning is emitted in the case that a :func:`.column` object is applied to
+ A warning is emitted in the case that a :func:`_expression.column` object is applied to
a declarative class, as it seems likely this intended to be a
- :class:`.Column` object.
+ :class:`_schema.Column` object.
.. change::
:tags: bug, orm
repaired issue with :meth:`.RelationshipProperty.Comparator.any` and
:meth:`.RelationshipProperty.Comparator.has` where the "secondary"
selectable needs to be explicitly part of the FROM clause in the
- EXISTS subquery to suit the case where this "secondary" is a :class:`.Join`
+ EXISTS subquery to suit the case where this "secondary" is a :class:`_expression.Join`
object.
.. change::
Fixed regression caused by :ticket:`4349` where adding the "secondary"
table to the FROM clause for a dynamic loader would affect the ability of
- the :class:`.Query` to make a subsequent join to another entity. The fix
+ the :class:`_query.Query` to make a subsequent join to another entity. The fix
adds the primary entity as the first element of the FROM list since
- :meth:`.Query.join` wants to jump from that. Version 1.3 will have
+ :meth:`_query.Query.join` wants to jump from that. Version 1.3 will have
a more comprehensive solution to this problem as well (:ticket:`4365`).
Fixed regression caused by :ticket:`4326` in version 1.2.12 where using
:class:`.declared_attr` with a mixin in conjunction with
- :func:`.orm.synonym` would fail to map the synonym properly to an inherited
+ :func:`_orm.synonym` would fail to map the synonym properly to an inherited
subclass.
.. change::
:tickets: 4352
The column conflict resolution technique discussed at
- :ref:`declarative_column_conflicts` is now functional for a :class:`.Column`
+ :ref:`declarative_column_conflicts` is now functional for a :class:`_schema.Column`
that is also a primary key column. Previously, a check for primary key
columns declared on a single-inheritance subclass would occur before the
column copy were allowed to pass.
:tags: bug, postgresql
:tickets: 4324
- Fixed the :func:`.postgresql.array_agg` function, which is a slightly
- altered version of the usual :func:`.functions.array_agg` function, to also
+ Fixed the :func:`_postgresql.array_agg` function, which is a slightly
+ altered version of the usual :func:`_functions.array_agg` function, to also
accept an incoming "type" argument without forcing an ARRAY around it,
essentially the same thing that was fixed for the generic function in 1.1
in :ticket:`4107`.
not the hybrid attribute itself, when receiving the descriptor via the
``@declared_attr`` callable on a subclass of an already-mapped class. This
would lead to an attribute that did not report itself as a hybrid when
- viewed within :attr:`.Mapper.all_orm_descriptors`.
+ viewed within :attr:`_orm.Mapper.all_orm_descriptors`.
.. change::
:tickets: 4334
:versions: 1.3.0b1
- Fixed bug where use of :class:`.Lateral` construct in conjunction with
- :meth:`.Query.join` as well as :meth:`.Query.select_entity_from` would not
+ Fixed bug where use of :class:`_expression.Lateral` construct in conjunction with
+ :meth:`_query.Query.join` as well as :meth:`_query.Query.select_entity_from` would not
apply clause adaption to the right side of the join. "lateral" introduces
the use case of the right side of a join being correlatable. Previously,
adaptation of this clause wasn't considered. Note that in 1.2 only,
- a selectable introduced by :meth:`.Query.subquery` is still not adapted
+ a selectable introduced by :meth:`_query.Query.subquery` is still not adapted
due to :ticket:`4304`; the selectable needs to be produced by the
- :func:`~.sql.expression.select` function to be the right side of the "lateral" join.
+ :func:`_expression.select` function to be the right side of the "lateral" join.
.. change::
:tags: bug, oracle
Fixed issue that is closely related to :ticket:`3639` where an expression
rendered in a boolean context on a non-native boolean backend would
be compared to 1/0 even though it is already an implicitly boolean
- expression, when :meth:`.ColumnElement.self_group` were used. While this
+ expression, when :meth:`_expression.ColumnElement.self_group` were used. While this
does not affect the user-friendly backends (MySQL, SQLite) it was not
handled by Oracle (and possibly SQL Server). Whether or not the
expression is implicitly boolean on any database is now determined
change now includes that a SELECT statement in the WHERE clause for such a
statement will try to auto-correlate back to these additional tables in the
parent UPDATE/DELETE or unconditionally correlate if
- :meth:`.Select.correlate` is used. Note that auto-correlation raises an
+ :meth:`_expression.Select.correlate` is used. Note that auto-correlation raises an
error if the SELECT statement would have no FROM clauses as a result, which
can now occur if the parent UPDATE/DELETE specifies the same tables in its
- additional set of tables; specify :meth:`.Select.correlate` explicitly to
+ additional set of tables; specify :meth:`_expression.Select.correlate` explicitly to
resolve.
.. changelog::
:tickets: 4300
Fixed bug where a :class:`.Sequence` would be dropped explicitly before any
- :class:`.Table` that refers to it, which breaks in the case when the
+ :class:`_schema.Table` that refers to it, which breaks in the case when the
sequence is also involved in a server-side default for that table, when
- using :meth:`.MetaData.drop_all`. The step which processes sequences
+ using :meth:`_schema.MetaData.drop_all`. The step which processes sequences
to be dropped via non server-side column default functions is now invoked
after the table itself is dropped.
:tickets: 4298
Fixed regression in 1.2.9 due to :ticket:`4287` where using a
- :class:`.Load` option in conjunction with a string wildcard would result
+ :class:`_orm.Load` option in conjunction with a string wildcard would result
in a TypeError.
.. changelog::
:tags: bug, sql
:tickets: 4279
- Fixed regression in 1.2 due to :ticket:`4147` where a :class:`.Table` that
+ Fixed regression in 1.2 due to :ticket:`4147` where a :class:`_schema.Table` that
has had some of its indexed columns redefined with new ones, as would occur
when overriding columns during reflection or when using
- :paramref:`.Table.extend_existing`, such that the :meth:`.Table.tometadata`
+ :paramref:`_schema.Table.extend_existing`, such that the :meth:`_schema.Table.tometadata`
method would fail when attempting to copy those indexes as they still
referred to the replaced column. The copy logic now accommodates for this
condition.
:tickets: 3505
Fixed issue where chaining multiple join elements inside of
- :meth:`.Query.join` might not correctly adapt to the previous left-hand
+ :meth:`_query.Query.join` might not correctly adapt to the previous left-hand
side, when chaining joined inheritance classes that share the same base
class.
:tickets: 4243
:versions: 1.3.0b1
- Added new attribute :attr:`.Query.lazy_loaded_from` which is populated
- with an :class:`.InstanceState` that is using this :class:`.Query` in
+ Added new attribute :attr:`_query.Query.lazy_loaded_from` which is populated
+ with an :class:`.InstanceState` that is using this :class:`_query.Query` in
order to lazy load a relationship. The rationale for this is that
it serves as a hint for the horizontal sharding feature to use, such that
the identity token of the state can be used as the default identity token
:tags: bug, mysql
:tickets: 3645
- The :class:`.Update` construct now accommodates a :class:`.Join` object
+ The :class:`_expression.Update` construct now accommodates a :class:`_expression.Join` object
as supported by MySQL for UPDATE..FROM. As the construct already
accepted an alias object for a similar purpose, the feature of UPDATE
against a non-table was already implied so this has been added.
Fixed regression caused by :ticket:`4256` (itself a regression fix for
:ticket:`4228`) which breaks an undocumented behavior which converted for a
- non-sequence of entities passed directly to the :class:`.Query` constructor
+ non-sequence of entities passed directly to the :class:`_query.Query` constructor
into a single-element sequence. While this behavior was never supported or
documented, it's already in use so has been added as a behavioral contract
- to :class:`.Query`.
+ to :class:`_query.Query`.
.. change::
:tags: bug, orm
Fixed an issue that was both a performance regression in 1.2 as well as an
incorrect result regarding the "baked" lazy loader, involving the
- generation of cache keys from the original :class:`.Query` object's loader
+ generation of cache keys from the original :class:`_query.Query` object's loader
options. If the loader options were built up in a "branched" style using
common base elements for multiple options, the same options would be
rendered into the cache key repeatedly, causing both a performance issue as
well as generating the wrong cache key. This is fixed, along with a
performance improvement when such "branched" options are applied via
- :meth:`.Query.options` to prevent the same option objects from being
+ :meth:`_query.Query.options` to prevent the same option objects from being
applied repeatedly.
.. change::
Fixed regression in 1.2.7 caused by :ticket:`4228`, which itself was fixing
a 1.2-level regression, where the ``query_cls`` callable passed to a
- :class:`.Session` was assumed to be a subclass of :class:`.Query` with
+ :class:`.Session` was assumed to be a subclass of :class:`_query.Query` with
class method availability, as opposed to an arbitrary callable. In
particular, the dogpile caching example illustrates ``query_cls`` as a
- function and not a :class:`.Query` subclass.
+ function and not a :class:`_query.Query` subclass.
.. change::
:tags: bug, engine
Fixed connection pool issue whereby if a disconnection error were raised
during the connection pool's "reset on return" sequence in conjunction with
- an explicit transaction opened against the enclosing :class:`.Connection`
+ an explicit transaction opened against the enclosing :class:`_engine.Connection`
object (such as from calling :meth:`.Session.close` without a rollback or
- commit, or calling :meth:`.Connection.close` without first closing a
- transaction declared with :meth:`.Connection.begin`), a double-checkin would
+ commit, or calling :meth:`_engine.Connection.close` without first closing a
+ transaction declared with :meth:`_engine.Connection.begin`), a double-checkin would
result, which could then lead towards concurrent checkouts of the same
connection. The double-checkin condition is now prevented overall by an
assertion, as well as the specific double-checkin scenario has been
The Oracle BINARY_FLOAT and BINARY_DOUBLE datatypes now participate within
cx_Oracle.setinputsizes(), passing along NATIVE_FLOAT, so as to support the
- NaN value. Additionally, :class:`.oracle.BINARY_FLOAT`,
- :class:`.oracle.BINARY_DOUBLE` and :class:`.oracle.DOUBLE_PRECISION` now
+ NaN value. Additionally, :class:`_oracle.BINARY_FLOAT`,
+ :class:`_oracle.BINARY_DOUBLE` and :class:`_oracle.DOUBLE_PRECISION` now
subclass :class:`.Float`, since these are floating point datatypes, not
decimal. These datatypes were already defaulting the
:paramref:`.Float.asdecimal` flag to False in line with what
.. change::
:tags: bug, oracle
- Added reflection capabilities for the :class:`.oracle.BINARY_FLOAT`,
- :class:`.oracle.BINARY_DOUBLE` datatypes.
+ Added reflection capabilities for the :class:`_oracle.BINARY_FLOAT`,
+ :class:`_oracle.BINARY_DOUBLE` datatypes.
.. change::
Fixed a long-standing regression that occurred in version
1.0, which prevented the use of a custom :class:`.MapperOption`
- that alters the _params of a :class:`.Query` object for a
+ that alters the _params of a :class:`_query.Query` object for a
lazy load, since the lazy loader itself would overwrite those
parameters. This applies to the "temporal range" example
on the wiki. Note however that the
- :meth:`.Query.populate_existing` method is now required in
+ :meth:`_query.Query.populate_existing` method is now required in
order to rewrite the mapper options associated with an object
already loaded in the identity map.
:tickets: 4160
:versions: 1.3.0b1
- Added new PG type :class:`.postgresql.REGCLASS` which assists in casting
+ Added new PG type :class:`_postgresql.REGCLASS` which assists in casting
table names to OID values. Pull request courtesy Sebastian Bank.
.. change::
Fixed issue in single-inheritance loading where the use of an aliased
entity against a single-inheritance subclass in conjunction with the
- :meth:`.Query.select_from` method would cause the SQL to be rendered with
+ :meth:`_query.Query.select_from` method would cause the SQL to be rendered with
the unaliased table mixed in to the query, causing a cartesian product. In
particular this was affecting the new "selectin" loader when used against a
single-inheritance subclass.
Fixed a regression that occurred from the previous fix to :ticket:`4204` in
version 1.2.5, where a CTE that refers to itself after the
- :meth:`.CTE.alias` method has been called would not refer to itself
+ :meth:`_expression.CTE.alias` method has been called would not refer to itself
correctly.
.. change::
:tickets: 4210
Fixed bug in :class:.`CTE` construct along the same lines as that of
- :ticket:`4204` where a :class:`.CTE` that was aliased would not copy itself
+ :ticket:`4204` where a :class:`_expression.CTE` that was aliased would not copy itself
correctly during a "clone" operation as is frequent within the ORM as well
- as when using the :meth:`.ClauseElement.params` method.
+ as when using the :meth:`_expression.ClauseElement.params` method.
.. change::
:tags: bug, orm
:tags: bug, sql
:tickets: 4204
- Fixed bug in CTE rendering where a :class:`.CTE` that was also turned into
- an :class:`.Alias` would not render its "ctename AS aliasname" clause
+ Fixed bug in CTE rendering where a :class:`_expression.CTE` that was also turned into
+ an :class:`_expression.Alias` would not render its "ctename AS aliasname" clause
appropriately if there were more than one reference to the CTE in a FROM
clause.
:tags: feature, orm
:versions: 1.3.0b1
- Added new feature :meth:`.Query.only_return_tuples`. Causes the
- :class:`.Query` object to return keyed tuple objects unconditionally even
+ Added new feature :meth:`_query.Query.only_return_tuples`. Causes the
+ :class:`_query.Query` object to return keyed tuple objects unconditionally even
if the query is against a single entity. Pull request courtesy Eric
Atkin.
:tickets: 4193
Fixed 1.2 regression in ORM versioning feature where a mapping against a
- :func:`~.sql.expression.select` or :func:`.alias` that also used a versioning column
+ :func:`_expression.select` or :func:`.alias` that also used a versioning column
against the underlying table would fail due to the check added as part of
:ticket:`3673`.
:tickets: 4190
Fixed regression caused in 1.2.3 due to fix from :ticket:`4181` where
- the changes to the event system involving :class:`.Engine` and
+ the changes to the event system involving :class:`_engine.Engine` and
:class:`.OptionEngine` did not accommodate for event removals, which
would raise an ``AttributeError`` when invoked at the class
level.
:tickets: 4175
Fixed bug where the :class:`.Bundle` object did not
- correctly report upon the primary :class:`.Mapper` object
+ correctly report upon the primary :class:`_orm.Mapper` object
represented by the bundle, if any. An immediate
side effect of this issue was that the new selectinload
loader strategy wouldn't work with the horizontal sharding
Fixed bug where events associated with an :class:`Engine`
at the class level would be doubled when the
- :meth:`.Engine.execution_options` method were used. To
+ :meth:`_engine.Engine.execution_options` method were used. To
achieve this, the semi-private class :class:`.OptionEngine`
no longer accepts events directly at the class level
and will raise an error; the class only propagates class-level
- events from its parent :class:`.Engine`. Instance-level
+ events from its parent :class:`_engine.Engine`. Instance-level
events continue to work as before.
.. change::
:tags: bug, orm
:tickets: 4178
- Fixed bug where the :func:`.orm.reconstructor` event
+ Fixed bug where the :func:`_orm.reconstructor` event
helper would not be recognized if it were applied to the
``__init__()`` method of the mapped class.
:tags: bug, sql
:tickets: 4147
- Fixed bug where the :meth:`.Table.tometadata` method would not properly
+ Fixed bug where the :meth:`_schema.Table.tometadata` method would not properly
accommodate :class:`.Index` objects that didn't consist of simple
- column expressions, such as indexes against a :func:`.text` construct,
+ column expressions, such as indexes against a :func:`_expression.text` construct,
indexes that used SQL expressions or :attr:`.func`, etc. The routine
now copies expressions fully to a new :class:`.Index` object while
- substituting all table-bound :class:`.Column` objects for those
+ substituting all table-bound :class:`_schema.Column` objects for those
of the target table.
.. change::
:tags: bug, sql
:tickets: 4142
- Changed the "visit name" of :class:`.ColumnElement` from "column" to
+ Changed the "visit name" of :class:`_expression.ColumnElement` from "column" to
"column_element", so that when this element is used as the basis for a
user-defined SQL element, it is not assumed to behave like a table-bound
:class:`.ColumnClause` when processed by various SQL traversal utilities,
:tags: bug, sql, ext
:tickets: 4141
- Fixed issue in :class:`.ARRAY` datatype which is essentially the same
+ Fixed issue in :class:`_types.ARRAY` datatype which is essentially the same
issue as that of :ticket:`3832`, except not a regression, where
- column attachment events on top of :class:`.ARRAY` would not fire
+ column attachment events on top of :class:`_types.ARRAY` would not fire
correctly, thus interfering with systems which rely upon this. A key
use case that was broken by this is the use of mixins to declare
columns that make use of :meth:`.MutableList.as_mutable`.
.. change::
:tags: feature, postgresql
- Added new :class:`.postgresql.MONEY` datatype. Pull request courtesy
+ Added new :class:`_postgresql.MONEY` datatype. Pull request courtesy
Cleber J Santos.
.. change::
:tags: bug, orm
:tickets: 4032
- The :meth:`.Query.exists` method will now disable eager loaders for when
+ The :meth:`_query.Query.exists` method will now disable eager loaders for when
the query is rendered. Previously, joined-eager load joins would be rendered
unnecessarily as well as subquery eager load queries would be needlessly
- generated. The new behavior matches that of the :meth:`.Query.subquery`
+ generated. The new behavior matches that of the :meth:`_query.Query.subquery`
method.
.. changelog::
Added a new flag ``use_batch_mode`` to the psycopg2 dialect. This flag
enables the use of psycopg2's ``psycopg2.extras.execute_batch``
- extension when the :class:`.Engine` calls upon
+ extension when the :class:`_engine.Engine` calls upon
``cursor.executemany()``. This extension provides a critical
performance increase by over an order of magnitude when running INSERT
statements in batch. The flag is False by default as it is considered
.. change::
:tags: bug, oracle
- The column keys present in a result set when using :meth:`.Insert.returning`
+ The column keys present in a result set when using :meth:`_expression.Insert.returning`
with the cx_Oracle backend now use the correct column / label names
like that of all other dialects. Previously, these came out as
``ret_nnn``.
:tickets: 4041
Fixed bug where the pg8000 driver would fail if using
- :meth:`.MetaData.reflect` with a schema name, since the schema name would
+ :meth:`_schema.MetaData.reflect` with a schema name, since the schema name would
be sent as a "quoted_name" object that's a string subclass, which pg8000
doesn't recognize. The quoted_name type is added to pg8000's
py_types collection on connect.
:tags: feature, mssql
:tickets: 4086
- Added a new :class:`.mssql.TIMESTAMP` datatype, that
+ Added a new :class:`_mssql.TIMESTAMP` datatype, that
correctly acts like a binary datatype for SQL Server
rather than a datetime type, as SQL Server breaks the
- SQL standard here. Also added :class:`.mssql.ROWVERSION`,
+ SQL standard here. Also added :class:`_mssql.ROWVERSION`,
as the "TIMESTAMP" type in SQL Server is deprecated in
favor of ROWVERSION.
:tickets: 4058
Added support for "AUTOCOMMIT" isolation level, as established
- via :meth:`.Connection.execution_options`, to the
+ via :meth:`_engine.Connection.execution_options`, to the
PyODBC and pymssql dialects. This isolation level sets the
appropriate DBAPI-specific flags on the underlying
connection object.
:tickets: 4087
Fixed bug in new SQL comments feature where table and column comment
- would not be copied when using :meth:`.Table.tometadata`.
+ would not be copied when using :meth:`_schema.Table.tometadata`.
.. change::
:tags: bug, sql
Changed the name of the ``.values`` attribute of the new MySQL
INSERT..ON DUPLICATE KEY UPDATE construct to ``.inserted``, as
- :class:`~.sql.expression.Insert` already has a method called :meth:`.Insert.values`.
+ :class:`_expression.Insert` already has a method called :meth:`_expression.Insert.values`.
The ``.inserted`` attribute ultimately renders the MySQL ``VALUES()``
function.
:class:`.Emulated` that indicates a type that provides Python-side
emulation of a DB native type, switching out to the DB native type when
a supporting backend is in use. The PostgreSQL
- :class:`.postgresql.INTERVAL` type when used directly will now include
+ :class:`_postgresql.INTERVAL` type when used directly will now include
the correct type coercion rules for SQL expressions that also take
- effect for :class:`.sqltypes.Interval` (such as adding a date to an
+ effect for :class:`_types.Interval` (such as adding a date to an
interval yields a datetime).
:tags: bug, engine
:tickets: 4028
- Made some adjustments to :class:`.Pool` and :class:`.Connection` such
+ Made some adjustments to :class:`_pool.Pool` and :class:`_engine.Connection` such
that recovery logic is not run underneath exception catches for
``pool.Empty``, ``AttributeError``, since when the recovery operation
itself fails, Python 3 creates a misleading stack trace referring to the
:tags: feature, orm
:tickets: 3058
- Added a new feature :func:`.orm.with_expression` that allows an ad-hoc
+ Added a new feature :func:`_orm.with_expression` that allows an ad-hoc
SQL expression to be added to a specific entity in a query at result
time. This is an alternative to the SQL expression being delivered as
a separate element in the result tuple.
:tickets: 3496
An UPDATE emitted as a result of the
- :paramref:`.relationship.post_update` feature will now integrate with
+ :paramref:`_orm.relationship.post_update` feature will now integrate with
the versioning feature to both bump the version id of the row as well
as assert that the existing version number was matched.
:tickets: 4003
The Oracle dialect now inspects unique and check constraints when using
- :meth:`.Inspector.get_unique_constraints`,
- :meth:`.Inspector.get_check_constraints`.
+ :meth:`_reflection.Inspector.get_unique_constraints`,
+ :meth:`_reflection.Inspector.get_check_constraints`.
As Oracle does not have unique constraints that are separate from a unique
- :class:`.Index`, a :class:`.Table` that's reflected will still continue
+ :class:`.Index`, a :class:`_schema.Table` that's reflected will still continue
to not have :class:`.UniqueConstraint` objects associated with it.
Pull requests courtesy Eloy Felix.
:tickets: 3471, 3472
Repaired several use cases involving the
- :paramref:`.relationship.post_update` feature when used in conjunction
+ :paramref:`_orm.relationship.post_update` feature when used in conjunction
with a column that has an "onupdate" value. When the UPDATE emits,
the corresponding object attribute is now expired or refreshed so that
the newly generated "onupdate" value can populate on the object;
:tickets: 3871
Added support for views that are unreflectable due to stale
- table definitions, when calling :meth:`.MetaData.reflect`; a warning
+ table definitions, when calling :meth:`_schema.MetaData.reflect`; a warning
is emitted for the table that cannot respond to ``DESCRIBE``,
but the operation succeeds.
:tickets: 3991
Added new argument :paramref:`.with_for_update` to the
- :meth:`.Session.refresh` method. When the :meth:`.Query.with_lockmode`
- method were deprecated in favor of :meth:`.Query.with_for_update`,
+ :meth:`.Session.refresh` method. When the :meth:`_query.Query.with_lockmode`
+ method were deprecated in favor of :meth:`_query.Query.with_for_update`,
the :meth:`.Session.refresh` method was never updated to reflect
the new option.
values from the loaded parent objects, rather than re-stating the
original query. This produces a more efficient query that is
"baked" (e.g. the SQL string is cached) and also works in the
- context of :meth:`.Query.yield_per`.
+ context of :meth:`_query.Query.yield_per`.
.. seealso::
.. change::
:tags: bug, orm
- Added warnings to the LRU "compiled cache" used by the :class:`.Mapper`
+ Added warnings to the LRU "compiled cache" used by the :class:`_orm.Mapper`
(and ultimately will be for other ORM-based LRU caches) such that
when the cache starts hitting its size limits, the application will
emit a warning that this is a performance-degrading situation that
may require attention. The LRU caches can reach their size limits
primarily if an application is making use of an unbounded number
- of :class:`.Engine` objects, which is an antipattern. Otherwise,
+ of :class:`_engine.Engine` objects, which is an antipattern. Otherwise,
this may suggest an issue that should be brought to the SQLAlchemy
developer's attention.
:tags: bug, postgresql
:tickets: 3964
- Fixed bug where the base :class:`.sqltypes.ARRAY` datatype would not
- invoke the bind/result processors of :class:`.postgresql.ARRAY`.
+ Fixed bug where the base :class:`_types.ARRAY` datatype would not
+ invoke the bind/result processors of :class:`_postgresql.ARRAY`.
.. change:: 3963
:tags: bug, orm
The ``lazy="select"`` loader strategy now makes used of the
:class:`.BakedQuery` query caching system in all cases. This
- removes most overhead of generating a :class:`.Query` object and
- running it into a :func:`~.sql.expression.select` and then string SQL statement from
+ removes most overhead of generating a :class:`_query.Query` object and
+ running it into a :func:`_expression.select` and then string SQL statement from
the process of lazy-loading related collections and objects. The
"baked" lazy loader has also been improved such that it can now
cache in most cases where query load options are used.
The system by which percent signs in SQL statements are "doubled"
for escaping purposes has been refined. The "doubling" of percent
- signs mostly associated with the :obj:`.literal_column` construct
+ signs mostly associated with the :obj:`_expression.literal_column` construct
as well as operators like :meth:`.ColumnOperators.contains` now
occurs based on the stated paramstyle of the DBAPI in use; for
percent-sensitive paramstyles as are common with the PostgreSQL
and MySQL drivers the doubling will occur, for others like that
of SQLite it will not. This allows more database-agnostic use
- of the :obj:`.literal_column` construct to be possible.
+ of the :obj:`_expression.literal_column` construct to be possible.
.. seealso::
Added support for all possible "fields" identifiers when reflecting the
PostgreSQL ``INTERVAL`` datatype, e.g. "YEAR", "MONTH", "DAY TO
- MINUTE", etc.. In addition, the :class:`.postgresql.INTERVAL`
+ MINUTE", etc.. In addition, the :class:`_postgresql.INTERVAL`
datatype itself now includes a new parameter
:paramref:`.postgresql.INTERVAL.fields` where these qualifiers can be
specified; the qualifier is also reflected back into the resulting
:tickets: 3785
The expression used for COLLATE as rendered by the column-level
- :func:`.expression.collate` and :meth:`.ColumnOperators.collate` is now
+ :func:`_expression.collate` and :meth:`.ColumnOperators.collate` is now
quoted as an identifier when the name is case sensitive, e.g. has
uppercase characters. Note that this does not impact type-level
collation, which is already quoted.
:tags: feature, orm, ext
:tickets: 3229
- The :meth:`.Query.update` method can now accommodate both
+ The :meth:`_query.Query.update` method can now accommodate both
hybrid attributes as well as composite attributes as a source
of the key to be placed in the SET clause. For hybrids, an
additional decorator :meth:`.hybrid_property.update_expression`
:tags: feature, sql, postgresql, mysql, oracle
:tickets: 1546
- Added support for SQL comments on :class:`.Table` and :class:`.Column`
- objects, via the new :paramref:`.Table.comment` and
- :paramref:`.Column.comment` arguments. The comments are included
+ Added support for SQL comments on :class:`_schema.Table` and :class:`_schema.Column`
+ objects, via the new :paramref:`_schema.Table.comment` and
+ :paramref:`_schema.Column.comment` arguments. The comments are included
as part of DDL on table creation, either inline or via an appropriate
ALTER statement, and are also reflected back within table reflection,
- as well as via the :class:`.Inspector`. Supported backends currently
+ as well as via the :class:`_reflection.Inspector`. Supported backends currently
include MySQL, PostgreSQL, and Oracle. Many thanks to Frazer McLean
for a large amount of effort on this.
:tags: feature, engine
:tickets: 3919
- Added native "pessimistic disconnection" handling to the :class:`.Pool`
- object. The new parameter :paramref:`.Pool.pre_ping`, available from
+ Added native "pessimistic disconnection" handling to the :class:`_pool.Pool`
+ object. The new parameter :paramref:`_pool.Pool.pre_ping`, available from
the engine as :paramref:`.create_engine.pool_pre_ping`, applies an
efficient form of the "pre-ping" recipe featured in the pooling
documentation, which upon each connection check out, emits a simple
:tags: bug, sql
:tickets: 3939
- Fixed bug where the use of an :class:`.Alias` object in a column
+ Fixed bug where the use of an :class:`_expression.Alias` object in a column
context would raise an argument error when it tried to group itself
- into a parenthesized expression. Using :class:`.Alias` in this way
+ into a parenthesized expression. Using :class:`_expression.Alias` in this way
is not yet a fully supported API, however it applies to some end-user
recipes and may have a more prominent role in support of some
future PostgreSQL features.
:tags: bug, orm
:tickets: 3366
- The "evaluate" strategy used by :meth:`.Query.update` and
- :meth:`.Query.delete` can now accommodate a simple
+ The "evaluate" strategy used by :meth:`_query.Query.update` and
+ :meth:`_query.Query.delete` can now accommodate a simple
object comparison from a many-to-one relationship to an instance,
when the attribute names of the primary key / foreign key columns
don't match the actual names of the columns. Previously this would
:tickets: 3938
Fixed bug where in the unusual case of passing a
- :class:`.Compiled` object directly to :meth:`.Connection.execute`,
+ :class:`.Compiled` object directly to :meth:`_engine.Connection.execute`,
the dialect with which the :class:`.Compiled` object were generated
was not consulted for the paramstyle of the string statement, instead
assuming it would match the dialect-level paramstyle, causing
:tags: bug, orm
:tickets: 3607
- Fixed bug where :meth:`.Query.with_parent` would not work if the
- :class:`.Query` were against an :func:`.aliased` construct rather than
+ Fixed bug where :meth:`_query.Query.with_parent` would not work if the
+ :class:`_query.Query` were against an :func:`.aliased` construct rather than
a regular mapped class. Also adds a new parameter
:paramref:`.util.with_parent.from_entity` to the standalone
:func:`.util.with_parent` function as well as
- :meth:`.Query.with_parent`.
+ :meth:`_query.Query.with_parent`.
:tags: bug, orm
:tickets: 5228
- Fixed bug in :func:`.orm.selectinload` loading option where two or more
+ Fixed bug in :func:`_orm.selectinload` loading option where two or more
loaders that represent different relationships with the same string key
- name as referenced from a single :func:`.orm.with_polymorphic` construct
+ name as referenced from a single :func:`_orm.with_polymorphic` construct
with multiple subclass mappers would fail to invoke each subqueryload
separately, instead making use of a single string-based slot that would
prevent the other loaders from being invoked.
:tickets: 5063
Added support for reflection of "computed" columns, which are now returned
- as part of the structure returned by :meth:`.Inspector.get_columns`.
- When reflecting full :class:`.Table` objects, computed columns will
+ as part of the structure returned by :meth:`_reflection.Inspector.get_columns`.
+ When reflecting full :class:`_schema.Table` objects, computed columns will
be represented using the :class:`.Computed` construct.
.. change::
:tickets: 5238
The string argument accepted as the first positional argument by the
- :func:`.relationship` function when using the Declarative API is no longer
+ :func:`_orm.relationship` function when using the Declarative API is no longer
interpreted using the Python ``eval()`` function; instead, the name is dot
separated and the names are looked up directly in the name resolution
dictionary without treating the value as a Python expression. However,
- passing a string argument to the other :func:`.relationship` parameters
+ passing a string argument to the other :func:`_orm.relationship` parameters
that necessarily must accept Python expressions will still use ``eval()``;
the documentation has been clarified to ensure that there is no ambiguity
that this is in use.
:tags: bug, orm
:tickets: 5194
- Adjusted the error message emitted by :meth:`.Query.join` when a left hand
- side can't be located that the :meth:`.Query.select_from` method is the
+ Adjusted the error message emitted by :meth:`_query.Query.join` when a left hand
+ side can't be located that the :meth:`_query.Query.select_from` method is the
best way to resolve the issue. Also, within the 1.3 series, used a
deterministic ordering when determining the FROM clause from a given column
- entity passed to :class:`.Query` so that the same expression is determined
+ entity passed to :class:`_query.Query` so that the same expression is determined
each time.
:tags: bug, mssql
:tickets: 5132
- Fixed issue where the :class:`.mssql.DATETIMEOFFSET` type would not
+ Fixed issue where the :class:`_mssql.DATETIMEOFFSET` type would not
accommodate for the ``None`` value, introduced as part of the series of
fixes for this type first introduced in :ticket:`4983`, :ticket:`5045`.
Additionally, added support for passing a backend-specific date formatted
Fixed issue where the "schema_translate_map" feature would not work with a
PostgreSQL native enumeration type (i.e. :class:`.Enum`,
- :class:`.postgresql.ENUM`) in that while the "CREATE TYPE" statement would
+ :class:`_postgresql.ENUM`) in that while the "CREATE TYPE" statement would
be emitted with the correct schema, the schema would not be rendered in
the CREATE TABLE statement at the point at which the enumeration was
referenced.
:tags: usecase, postgresql
:tickets: 5040
- Added support for prefixes to the :class:`.CTE` construct, to allow
+ Added support for prefixes to the :class:`_expression.CTE` construct, to allow
support for Postgresql 12 "MATERIALIZED" and "NOT MATERIALIZED" phrases.
Pull request courtesy Marat Sharafutdinov.
.. seealso::
- :meth:`.HasCTE.cte`
+ :meth:`_expression.HasCTE.cte`
.. change::
:tags: bug, mssql
:tickets: 5045
Fixed issue where a timezone-aware ``datetime`` value being converted to
- string for use as a parameter value of a :class:`.mssql.DATETIMEOFFSET`
+ string for use as a parameter value of a :class:`_mssql.DATETIMEOFFSET`
column was omitting the fractional seconds.
.. change::
:tickets: 5065
Fixed bug where usage of joined eager loading would not properly wrap the
- query inside of a subquery when :meth:`.Query.group_by` were used against
+ query inside of a subquery when :meth:`_query.Query.group_by` were used against
the query. When any kind of result-limiting approach is used, such as
DISTINCT, LIMIT, OFFSET, joined eager loading embeds the row-limited query
inside of a subquery so that the collection results are not impacted. For
:tags: bug, sql
:tickets: 5028
- Fixed bug where "distinct" keyword passed to :func:`~.sql.expression.select` would not
+ Fixed bug where "distinct" keyword passed to :func:`_expression.select` would not
treat a string value as a "label reference" in the same way that the
- :meth:`.select.distinct` does; it would instead raise unconditionally. This
- keyword argument and the others passed to :func:`~.sql.expression.select` will ultimately
+ :meth:`_expression.select.distinct` does; it would instead raise unconditionally. This
+ keyword argument and the others passed to :func:`_expression.select` will ultimately
be deprecated for SQLAlchemy 2.0.
:tags: bug, mssql
:tickets: 4983
- Repaired support for the :class:`.mssql.DATETIMEOFFSET` datatype on PyODBC,
+ Repaired support for the :class:`_mssql.DATETIMEOFFSET` datatype on PyODBC,
by adding PyODBC-level result handlers as it does not include native
support for this datatype. This includes usage of the Python 3 "timezone"
tzinfo subclass in order to set up a timezone, which on Python 2 makes
:tags: bug, orm
:tickets: 4993
- Setting persistence-related flags on :func:`.relationship` while also
+ Setting persistence-related flags on :func:`_orm.relationship` while also
setting viewonly=True will now emit a regular warning, as these flags do
not make sense for a viewonly=True relationship. In particular, the
"cascade" settings have their own warning that is generated based on the
:tags: orm, usecase
:tickets: 4934
- Added accessor :meth:`.Query.is_single_entity` to :class:`.Query`, which
- will indicate if the results returned by this :class:`.Query` will be a
+ Added accessor :meth:`_query.Query.is_single_entity` to :class:`_query.Query`, which
+ will indicate if the results returned by this :class:`_query.Query` will be a
list of ORM entities, or a tuple of entities or column expressions.
SQLAlchemy hopes to improve upon the behavior of single entity / tuples in
future releases such that the behavior would be explicit up front, however
:tags: bug, orm
:tickets: 4954
- The :paramref:`.relationship.omit_join` flag was not intended to be
+ The :paramref:`_orm.relationship.omit_join` flag was not intended to be
manually set to True, and will now emit a warning when this occurs. The
omit_join optimization is detected automatically, and the ``omit_join``
flag was only intended to disable the optimization in the hypothetical case
:tags: bug, orm
:tickets: 4915
- A warning is emitted if a primary key value is passed to :meth:`.Query.get`
+ A warning is emitted if a primary key value is passed to :meth:`_query.Query.get`
that consists of None for all primary key column positions. Previously,
passing a single None outside of a tuple would raise a ``TypeError`` and
passing a composite None (tuple of None values) would silently pass
were used later to generate a bound parameter name, in particular those
used by the ORM when generating the WHERE clause for an UPDATE statement.
The issue has been fixed by using an alternate ``._label`` accessor for DDL
- generation that does not affect the state of the :class:`.Column`. The
+ generation that does not affect the state of the :class:`_schema.Column`. The
accessor also bypasses the key-deduplication step as it is not necessary
for DDL, the naming is now consistently ``"<tablename>_<columnname>"``
without any subsequent numeric symbols when used in DDL.
:tags: bug, engine, postgresql
:tickets: 4955
- Fixed bug in :class:`.Inspector` where the cache key generation did not
+ Fixed bug in :class:`_reflection.Inspector` where the cache key generation did not
take into account arguments passed in the form of tuples, such as the tuple
of view name styles to return for the PostgreSQL dialect. This would lead
the inspector to cache too generally for a more specific set of criteria.
:tags: bug, mssql
:tickets: 4923
- Fixed an issue in the :meth:`.Engine.table_names` method where it would
+ Fixed an issue in the :meth:`_engine.Engine.table_names` method where it would
feed the dialect's default schema name back into the dialect level table
function, which in the case of SQL Server would interpret it as a
dot-tokenized schema name as viewed by the mssql dialect, which would
cause the method to fail in the case where the database username actually
had a dot inside of it. In 1.3, this method is still used by the
- :meth:`.MetaData.reflect` function so is a prominent codepath. In 1.4,
+ :meth:`_schema.MetaData.reflect` function so is a prominent codepath. In 1.4,
which is the current master development branch, this issue doesn't exist,
- both because :meth:`.MetaData.reflect` isn't using this method nor does the
+ both because :meth:`_schema.MetaData.reflect` isn't using this method nor does the
method pass the default schema name explicitly. The fix nonetheless
guards against the default server name value returned by the dialect from
being interpreted as dot-tokenized name under any circumstances by
Fixed ORM bug where a "secondary" table that referred to a selectable which
in some way would refer to the local primary table would apply aliasing to
both sides of the join condition when a relationship-related join, either
- via :meth:`.Query.join` or by :func:`.joinedload`, were generated. The
+ via :meth:`_query.Query.join` or by :func:`_orm.joinedload`, were generated. The
"local" side is now excluded.
.. change::
:tags: usecase, sql
:tickets: 4276
- Added new accessors to expressions of type :class:`.JSON` to allow for
+ Added new accessors to expressions of type :class:`_types.JSON` to allow for
specific datatype access and comparison, covering strings, integers,
numeric, boolean elements. This revises the documented approach of
CASTing to string when comparing values, instead adding specific
.. seealso::
- :class:`.JSON`
+ :class:`_types.JSON`
:meth:`.JSON.Comparator.as_string`
:tags: usecase, sql
:tickets: 4933
- The :func:`.text` construct now supports "unique" bound parameters, which
+ The :func:`_expression.text` construct now supports "unique" bound parameters, which
will dynamically uniquify themselves on compilation thus allowing multiple
- :func:`.text` constructs with the same bound parameter names to be combined
+ :func:`_expression.text` constructs with the same bound parameter names to be combined
together.
:tags: bug, oracle
:tickets: 4913
- The :class:`.sqltypes.NCHAR` datatype will now bind to the
+ The :class:`_types.NCHAR` datatype will now bind to the
``cx_Oracle.FIXED_NCHAR`` DBAPI data bindings when used in a bound
parameter, which supplies proper comparison behavior against a
- variable-length string. Previously, the :class:`.sqltypes.NCHAR` datatype
+ variable-length string. Previously, the :class:`_types.NCHAR` datatype
would bind to ``cx_oracle.NCHAR`` which is not fixed length; the
- :class:`.sqltypes.CHAR` datatype already binds to ``cx_Oracle.FIXED_CHAR``
- so it is now consistent that :class:`.sqltypes.NCHAR` binds to
+ :class:`_types.CHAR` datatype already binds to ``cx_Oracle.FIXED_CHAR``
+ so it is now consistent that :class:`_types.NCHAR` binds to
``cx_Oracle.FIXED_NCHAR``.
Added identifier quoting to the schema name applied to the "use" statement
which is invoked when a SQL Server multipart schema name is used within a
- :class:`.Table` that is being reflected, as well as for :class:`.Inspector`
- methods such as :meth:`.Inspector.get_table_names`; this accommodates for
+ :class:`_schema.Table` that is being reflected, as well as for :class:`_reflection.Inspector`
+ methods such as :meth:`_reflection.Inspector.get_table_names`; this accommodates for
special characters or spaces in the database name. Additionally, the "use"
statement is not emitted if the current database matches the target owner
database name being passed.
Passing a plain string expression to :meth:`.Session.query` is deprecated,
as all string coercions were removed in :ticket:`4481` and this one should
- have been included. The :func:`.literal_column` function may be used to
+ have been included. The :func:`_expression.literal_column` function may be used to
produce a textual column expression.
.. change::
:tickets: 4847
Added an explicit error message for the case when objects passed to
- :class:`.Table` are not :class:`.SchemaItem` objects, rather than resolving
+ :class:`_schema.Table` are not :class:`.SchemaItem` objects, rather than resolving
to an attribute error.
:tags: bug, orm
:tickets: 4823
- Fixed bug where :class:`.Load` objects were not pickleable due to
+ Fixed bug where :class:`_orm.Load` objects were not pickleable due to
mapper/relationship state in the internal context dictionary. These
objects are now converted to picklable using similar techniques as that of
other elements within the loader option system that have long been
:meth:`.postgresql.ARRAY.Comparator.contains` and
:meth:`.postgresql.ARRAY.Comparator.contained_by` would fail to function
correctly for non-integer values when used against a
- :class:`.postgresql.array` object, due to an erroneous assert statement.
+ :class:`_postgresql.array` object, due to an erroneous assert statement.
.. change::
:tags: feature, engine
constraints that were added to an exsiting table with the directive that
they not be applied to existing data in the table. The PostgreSQL
dictionary for CHECK constraints as returned by
- :meth:`.Inspector.get_check_constraints` may include an additional entry
+ :meth:`_reflection.Inspector.get_check_constraints` may include an additional entry
``dialect_options`` which within will contain an entry ``"not_valid":
True`` if this symbol is detected. Pull request courtesy Bill Finn.
supersedes the previous experimental ``use_batch_mode`` flag.
``executemany_mode`` supports both the "execute batch" and "execute values"
functions provided by psycopg2, the latter which is used for compiled
- :func:`~.sql.expression.insert` constructs. Pull request courtesy Yuval Dinari.
+ :func:`_expression.insert` constructs. Pull request courtesy Yuval Dinari.
.. seealso::
Fixed bug where :meth:`.TypeEngine.column_expression` method would not be
applied to subsequent SELECT statements inside of a UNION or other
- :class:`.CompoundSelect`, even though the SELECT statements are rendered at
+ :class:`_selectable.CompoundSelect`, even though the SELECT statements are rendered at
the topmost level of the statement. New logic now differentiates between
rendering the column expression, which is needed for all SELECTs in the
list, vs. gathering the returned data type for the result row, which is
:tags: usecase, mssql
:tickets: 4782
- Added new :func:`.mssql.try_cast` construct for SQL Server which emits
+ Added new :func:`_mssql.try_cast` construct for SQL Server which emits
"TRY_CAST" syntax. Pull request courtesy Leonel Atencio.
.. change::
:tags: bug, orm
:tickets: 4803
- Fixed bug where using :meth:`.Query.first` or a slice expression in
+ Fixed bug where using :meth:`_query.Query.first` or a slice expression in
conjunction with a query that has an expression based "offset" applied
would raise TypeError, due to an "or" conditional against "offset" that did
not expect it to be a SQL expression as opposed to an integer or None.
:tags: bug, engine
:tickets: 4754
- Fixed bug where using reflection function such as :meth:`.MetaData.reflect`
- with an :class:`.Engine` object that had execution options applied to it
+ Fixed bug where using reflection function such as :meth:`_schema.MetaData.reflect`
+ with an :class:`_engine.Engine` object that had execution options applied to it
would fail, as the resulting :class:`.OptionEngine` proxy object failed to
include a ``.engine`` attribute used within the reflection routines.
:tickets: 4743
Fixed bug where the special logic to render "NULL" for the
- :class:`.TIMESTAMP` datatype when ``nullable=True`` would not work if the
+ :class:`_types.TIMESTAMP` datatype when ``nullable=True`` would not work if the
column's datatype were a :class:`.TypeDecorator` or a :class:`.Variant`.
The logic now ensures that it unwraps down to the original
- :class:`.TIMESTAMP` so that this special case NULL keyword is correctly
+ :class:`_types.TIMESTAMP` so that this special case NULL keyword is correctly
rendered when requested.
.. change::
:tags: orm, feature
:tickets: 4736
- Added new loader option method :meth:`.Load.options` which allows loader
+ Added new loader option method :meth:`_orm.Load.options` which allows loader
options to be constructed hierarchically, so that many sub-options can be
applied to a particular path without needing to call :func:`.defaultload`
many times. Thanks to Alessio Bogon for the idea.
Fixed an issue where the :meth:`.orm._ORMJoin.join` method, which is a
not-internally-used ORM-level method that exposes what is normally an
- internal process of :meth:`.Query.join`, did not propagate the ``full`` and
+ internal process of :meth:`_query.Query.join`, did not propagate the ``full`` and
``outerjoin`` keyword arguments correctly. Pull request courtesy Denis
Kataev.
:tickets: 4756
Added support for multidimensional Postgresql array literals via nesting
- the :class:`.postgresql.array` object within another one. The
+ the :class:`_postgresql.array` object within another one. The
multidimensional array type is detected automatically.
.. seealso::
- :class:`.postgresql.array`
+ :class:`_postgresql.array`
.. change::
:tags: bug, sql, postgresql
:tickets: 4760
- Fixed issue where the :class:`.array_agg` construct in combination with
+ Fixed issue where the :class:`_functions.array_agg` construct in combination with
:meth:`.FunctionElement.filter` would not produce the correct operator
precedence in combination with the array index operator.
:tickets: 4747
Fixed an unlikely issue where the "corresponding column" routine for unions
- and other :class:`.CompoundSelect` objects could return the wrong column in
+ and other :class:`_selectable.CompoundSelect` objects could return the wrong column in
some overlapping column situtations, thus potentially impacting some ORM
operations when set operations are in use, if the underlying
- :func:`~.sql.expression.select` constructs were used previously in other similar kinds of
+ :func:`_expression.select` constructs were used previously in other similar kinds of
routines, due to a cached value not being cleared.
.. change::
:tags: bug, orm
:tickets: 4729
- Fixed bug where the :attr:`.Mapper.all_orm_descriptors` accessor would
- return an entry for the :class:`.Mapper` itself under the declarative
+ Fixed bug where the :attr:`_orm.Mapper.all_orm_descriptors` accessor would
+ return an entry for the :class:`_orm.Mapper` itself under the declarative
``__mapper___`` key, when this is not a descriptor. The ``.is_attribute``
flag that's present on all :class:`.InspectionAttr` objects is now
consulted, which has also been modified to be ``True`` for an association
:tags: bug, orm
:tickets: 4704
- Fixed regression in :meth:`.Query.join` where the ``aliased=True`` flag
+ Fixed regression in :meth:`_query.Query.join` where the ``aliased=True`` flag
would not properly apply clause adaptation to filter criteria, if a
previous join were made to the same entity. This is because the adapters
were placed in the wrong order. The order has been reversed so that the
:tickets: 4730
Fixed a series of quoting issues which all stemmed from the concept of the
- :func:`.literal_column` construct, which when being "proxied" through a
+ :func:`_expression.literal_column` construct, which when being "proxied" through a
subquery to be referred towards by a label that matches its text, the label
would not have quoting rules applied to it, even if the string in the
:class:`.Label` were set up as a :class:`.quoted_name` construct. Not
applying quoting to the text of the :class:`.Label` is a bug because this
text is strictly a SQL identifier name and not a SQL expression, and the
string should not have quotes embedded into it already unlike the
- :func:`.literal_column` which it may be applied towards. The existing
- behavior of a non-labeled :func:`.literal_column` being propagated as is on
+ :func:`_expression.literal_column` which it may be applied towards. The existing
+ behavior of a non-labeled :func:`_expression.literal_column` being propagated as is on
the outside of a subquery is maintained in order to help with manual
quoting schemes, although it's not clear if valid SQL can be generated for
such a construct in any case.
:tickets: 4585
Fixed behavioral regression as a result of deprecating the "use_threadlocal"
- flag for :class:`.Pool`, where the :class:`.SingletonThreadPool` no longer
+ flag for :class:`_pool.Pool`, where the :class:`.SingletonThreadPool` no longer
makes use of this option which causes the "rollback on return" logic to take
- place when the same :class:`.Engine` is used multiple times in the context
+ place when the same :class:`_engine.Engine` is used multiple times in the context
of a transaction to connect or implicitly execute, thereby cancelling the
transaction. While this is not the recommended way to work with engines
and connections, it is nonetheless a confusing behavioral change as when
:tickets: 4584
Fixed 1.3 regression in new "ambiguous FROMs" query logic introduced in
- :ref:`change_4365` where a :class:`.Query` that explicitly places an entity
- in the FROM clause with :meth:`.Query.select_from` and also joins to it
- using :meth:`.Query.join` would later cause an "ambiguous FROM" error if
+ :ref:`change_4365` where a :class:`_query.Query` that explicitly places an entity
+ in the FROM clause with :meth:`_query.Query.select_from` and also joins to it
+ using :meth:`_query.Query.join` would later cause an "ambiguous FROM" error if
that entity were used in additional joins, as the entity appears twice in
- the "from" list of the :class:`.Query`. The fix resolves this ambiguity by
+ the "from" list of the :class:`_query.Query`. The fix resolves this ambiguity by
folding the standalone entity into the join that it's already a part of in
the same way that ultimately happens when the SELECT statement is rendered.
:tags: bug, orm
:tickets: 4606
- Adjusted the :meth:`.Query.filter_by` method to not call :func:`.and()`
+ Adjusted the :meth:`_query.Query.filter_by` method to not call :func:`.and()`
internally against multiple criteria, instead passing it off to
- :meth:`.Query.filter` as a series of criteria, instead of a single criteria.
- This allows :meth:`.Query.filter_by` to defer to :meth:`.Query.filter`'s
+ :meth:`_query.Query.filter` as a series of criteria, instead of a single criteria.
+ This allows :meth:`_query.Query.filter_by` to defer to :meth:`_query.Query.filter`'s
treatment of variable numbers of clauses, including the case where the list
- is empty. In this case, the :class:`.Query` object will not have a
+ is empty. In this case, the :class:`_query.Query` object will not have a
``.whereclause``, which allows subsequent "no whereclause" methods like
- :meth:`.Query.select_from` to behave consistently.
+ :meth:`_query.Query.select_from` to behave consistently.
.. change::
:tags: bug, mssql
:tickets: 4550
Modified the :paramref:`.Select.with_for_update.of` parameter so that if a
- join or other composed selectable is passed, the individual :class:`.Table`
+ join or other composed selectable is passed, the individual :class:`_schema.Table`
objects will be filtered from it, allowing one to pass a join() object to
the parameter, as occurs normally when using joined table inheritance with
the ORM. Pull request courtesy Raymond Lu.
Fixed bug where use of :func:`.with_polymorphic` or other aliased construct
would not properly adapt when the aliased target were used as the
- :meth:`.Select.correlate_except` target of a subquery used inside of a
+ :meth:`_expression.Select.correlate_except` target of a subquery used inside of a
:func:`.column_property`. This required a fix to the clause adaption
mechanics to properly handle a selectable that shows up in the "correlate
except" list, in a similar manner as which occurs for selectables that show
:tags: feature, schema
:tickets: 4517
- Added new parameters :paramref:`.Table.resolve_fks` and
+ Added new parameters :paramref:`_schema.Table.resolve_fks` and
:paramref:`.MetaData.reflect.resolve_fks` which when set to False will
disable the automatic reflection of related tables encountered in
- :class:`.ForeignKey` objects, which can both reduce SQL overhead for omitted
+ :class:`_schema.ForeignKey` objects, which can both reduce SQL overhead for omitted
tables as well as avoid tables that can't be reflected for database-specific
- reasons. Two :class:`.Table` objects present in the same :class:`.MetaData`
+ reasons. Two :class:`_schema.Table` objects present in the same :class:`_schema.MetaData`
collection can still refer to each other even if the reflection of the two
tables occurred separately.
:tags: feature, orm
:tickets: 4316
- The :meth:`.Query.get` method can now accept a dictionary of attribute keys
+ The :meth:`_query.Query.get` method can now accept a dictionary of attribute keys
and values as a means of indicating the primary key value to load; is
particularly useful for composite primary keys. Pull request courtesy
Sanjana S.
:tags: bug, sql
:tickets: 4509
- The :class:`.Alias` class and related subclasses :class:`.CTE`,
- :class:`.Lateral` and :class:`.TableSample` have been reworked so that it is
+ The :class:`_expression.Alias` class and related subclasses :class:`_expression.CTE`,
+ :class:`_expression.Lateral` and :class:`_expression.TableSample` have been reworked so that it is
not possible for a user to construct the objects directly. These constructs
require that the standalone construction function or selectable-bound method
be used to instantiate new objects.
:tags: bug, orm
:tickets: 4469
- Improved the behavior of :func:`.orm.with_polymorphic` in conjunction with
+ Improved the behavior of :func:`_orm.with_polymorphic` in conjunction with
loader options, in particular wildcard operations as well as
- :func:`.orm.load_only`. The polymorphic object will be more accurately
+ :func:`_orm.load_only`. The polymorphic object will be more accurately
targeted so that column-level options on the entity will correctly take
effect.The issue is a continuation of the same kinds of things fixed in
:ticket:`4468`.
:tickets: 4481
Fully removed the behavior of strings passed directly as components of a
- :func:`~.sql.expression.select` or :class:`.Query` object being coerced to :func:`.text`
+ :func:`_expression.select` or :class:`_query.Query` object being coerced to :func:`_expression.text`
constructs automatically; the warning that has been emitted is now an
ArgumentError or in the case of order_by() / group_by() a CompileError.
This has emitted a warning since version 1.0 however its presence continues
:tickets: 4467
Quoting is applied to :class:`.Function` names, those which are usually but
- not necessarily generated from the :attr:`.sql.func` construct, at compile
+ not necessarily generated from the :attr:`_expression.func` construct, at compile
time if they contain illegal characters, such as spaces or punctuation. The
names are as before treated as case insensitive however, meaning if the
names contain uppercase or mixed case characters, that alone does not
:tickets: 4481
Added "SQL phrase validation" to key DDL phrases that are accepted as plain
- strings, including :paramref:`.ForeignKeyConstraint.on_delete`,
- :paramref:`.ForeignKeyConstraint.on_update`,
+ strings, including :paramref:`_schema.ForeignKeyConstraint.on_delete`,
+ :paramref:`_schema.ForeignKeyConstraint.on_update`,
:paramref:`.ExcludeConstraint.using`,
- :paramref:`.ForeignKeyConstraint.initially`, for areas where a series of SQL
+ :paramref:`_schema.ForeignKeyConstraint.initially`, for areas where a series of SQL
keywords only are expected.Any non-space characters that suggest the phrase
would need to be quoted will raise a :class:`.CompileError`. This change
is related to the series of changes committed as part of :ticket:`4481`.
:tickets: 4423
Implemented a new feature whereby the :class:`.AliasedClass` construct can
- now be used as the target of a :func:`.relationship`. This allows the
+ now be used as the target of a :func:`_orm.relationship`. This allows the
concept of "non primary mappers" to no longer be necessary, as the
:class:`.AliasedClass` is much easier to configure and automatically inherits
all the relationships of the mapped class, as well as preserves the
Added new :meth:`.MapperEvents.before_mapper_configured` event. This
event complements the other "configure" stage mapper events with a per
- mapper event that receives each :class:`.Mapper` right before its
+ mapper event that receives each :class:`_orm.Mapper` right before its
configure step, and additionally may be used to prevent or delay the
- configuration of specific :class:`.Mapper` objects using a new
+ configuration of specific :class:`_orm.Mapper` objects using a new
return value :attr:`.orm.interfaces.EXT_SKIP`. See the
documentation link for an example.
:tickets: 4464
Added accessors for execution options to Core and ORM, via
- :meth:`.Query.get_execution_options`,
- :meth:`.Connection.get_execution_options`,
- :meth:`.Engine.get_execution_options`, and
+ :meth:`_query.Query.get_execution_options`,
+ :meth:`_engine.Connection.get_execution_options`,
+ :meth:`_engine.Engine.get_execution_options`, and
:meth:`.Executable.get_execution_options`. PR courtesy Daniel Lister.
.. change::
The "threadlocal" engine strategy which has been a legacy feature of
SQLAlchemy since around version 0.2 is now deprecated, along with the
- :paramref:`.Pool.threadlocal` parameter of :class:`.Pool` which has no
+ :paramref:`_pool.Pool.threadlocal` parameter of :class:`_pool.Pool` which has no
effect in most modern use cases.
.. seealso::
:tickets: 3850
Added support for SQLite's json functionality via the new
- SQLite implementation for :class:`.types.JSON`, :class:`.sqlite.JSON`.
+ SQLite implementation for :class:`_types.JSON`, :class:`_sqlite.JSON`.
The name used for the type is ``JSON``, following an example found at
SQLite's own documentation. Pull request courtesy Ilja Everilä.
Implemented the SQLite ``ON CONFLICT`` clause as understood at the DDL
level, e.g. for primary key, unique, and CHECK constraints as well as
- specified on a :class:`.Column` to satisfy inline primary key and NOT NULL.
+ specified on a :class:`_schema.Column` to satisfy inline primary key and NOT NULL.
Pull request courtesy Denis Kataev.
.. seealso::
:tags: bug, orm
:tickets: 4365
- Refactored :meth:`.Query.join` to further clarify the individual components
+ Refactored :meth:`_query.Query.join` to further clarify the individual components
of structuring the join. This refactor adds the ability for
- :meth:`.Query.join` to determine the most appropriate "left" side of the
+ :meth:`_query.Query.join` to determine the most appropriate "left" side of the
join when there is more than one element in the FROM list or the query is
against multiple entities. If more than one FROM/entity matches, an error
is raised that asks for an ON clause to be specified to resolve the
ambiguity. In particular this targets the regression we saw in
:ticket:`4363` but is also of general use. The codepaths within
- :meth:`.Query.join` are now easier to follow and the error cases are
+ :meth:`_query.Query.join` are now easier to follow and the error cases are
decided more specifically at an earlier point in the operation.
.. seealso::
:tags: bug, orm
:tickets: 4304
- Fixed long-standing issue in :class:`.Query` where a scalar subquery such
- as produced by :meth:`.Query.exists`, :meth:`.Query.as_scalar` and other
- derivations from :attr:`.Query.statement` would not correctly be adapted
- when used in a new :class:`.Query` that required entity adaptation, such as
+ Fixed long-standing issue in :class:`_query.Query` where a scalar subquery such
+ as produced by :meth:`_query.Query.exists`, :meth:`_query.Query.as_scalar` and other
+ derivations from :attr:`_query.Query.statement` would not correctly be adapted
+ when used in a new :class:`_query.Query` that required entity adaptation, such as
when the query were turned into a union, or a from_self(), etc. The change
- removes the "no adaptation" annotation from the :func:`~.sql.expression.select` object
- produced by the :attr:`.Query.statement` accessor.
+ removes the "no adaptation" annotation from the :func:`_expression.select` object
+ produced by the :attr:`_query.Query.statement` accessor.
.. change::
:tags: bug, orm, declarative
:tickets: 4133
Fixed bug where declarative would not update the state of the
- :class:`.Mapper` as far as what attributes were present, when additional
+ :class:`_orm.Mapper` as far as what attributes were present, when additional
attributes were added or removed after the mapper attribute collections had
already been called and memoized. Additionally, a ``NotImplementedError``
is now raised if a fully mapped attribute (e.g. column, relationship, etc.)
:tags: feature, ext
:tickets: 4196
- Added support for bulk :meth:`.Query.update` and :meth:`.Query.delete`
+ Added support for bulk :meth:`_query.Query.update` and :meth:`_query.Query.delete`
to the :class:`.ShardedQuery` class within the horizontal sharding
extension. This also adds an additional expansion hook to the
- bulk update/delete methods :meth:`.Query._execute_crud`.
+ bulk update/delete methods :meth:`_query.Query._execute_crud`.
.. seealso::
one-to-many load, where it instead relies loads only from the related
table, relying upon the foreign key columns of the related table in order
to match up to primary keys in the parent table. This optimization can be
- disabled by setting the :paramref:`.relationship.omit_join` flag to False.
+ disabled by setting the :paramref:`_orm.relationship.omit_join` flag to False.
Many thanks to Jayson Reis for the efforts on this.
.. seealso::
:tickets: 4257
Added ``.info`` dictionary to the :class:`.InstanceState` class, the object
- that comes from calling :func:`.inspect` on a mapped object.
+ that comes from calling :func:`_sa.inspect` on a mapped object.
.. seealso::
.. _feature_relationship_08:
-Rewritten :func:`.relationship` mechanics
------------------------------------------
-
+Rewritten :func:`_orm.relationship` mechanics
+----------------------------------------------
0.8 features a much improved and capable system regarding
-how :func:`.relationship` determines how to join between two
+how :func:`_orm.relationship` determines how to join between two
entities. The new system includes these features:
* The ``primaryjoin`` argument is **no longer needed** when
- constructing a :func:`.relationship` against a class that
+ constructing a :func:`_orm.relationship` against a class that
has multiple foreign key paths to the target. Only the
``foreign_keys`` argument is needed to specify those
columns which should be included:
remote_side=ip_address
)
- The new :func:`.relationship` mechanics make use of a
+ The new :func:`_orm.relationship` mechanics make use of a
SQLAlchemy concept known as :term:`annotations`. These annotations
are also available to application code explicitly via
the :func:`.foreign` and :func:`.remote` functions, either
.. seealso::
- :ref:`relationship_configure_joins` - a newly revised section on :func:`.relationship`
+ :ref:`relationship_configure_joins` - a newly revised section on :func:`_orm.relationship`
detailing the latest techniques for customizing related attributes and collection
access.
systems, like JSON/XML conversion schemes and of course form
libraries galore.
-Originally, the :class:`.Table` and :class:`.Column` model were the
+Originally, the :class:`_schema.Table` and :class:`_schema.Column` model were the
original inspection points, which have a well-documented
system. While SQLAlchemy ORM models are also fully
introspectable, this has never been a fully stable and
documented API for this purpose, including an inspection
system which works on mapped classes, instances, attributes,
and other Core and ORM constructs. The entrypoint to this
-system is the core-level :func:`.inspect` function.
+system is the core-level :func:`_sa.inspect` function.
In most cases, the object being inspected
is one already part of SQLAlchemy's system,
-such as :class:`.Mapper`, :class:`.InstanceState`,
-:class:`.Inspector`. In some cases, new objects have been
+such as :class:`_orm.Mapper`, :class:`.InstanceState`,
+:class:`_reflection.Inspector`. In some cases, new objects have been
added with the job of providing the inspection API in
certain contexts, such as :class:`.AliasedInsp` and
:class:`.AttributeState`.
New with_polymorphic() feature, can be used anywhere
----------------------------------------------------
-The :meth:`.Query.with_polymorphic` method allows the user to
+The :meth:`_query.Query.with_polymorphic` method allows the user to
specify which tables should be present when querying against
a joined-table entity. Unfortunately the method is awkward
and only applies to the first entity in the list, and
The :meth:`.PropComparator.of_type` method is used to specify
a specific subtype to use when constructing SQL expressions along
-a :func:`.relationship` that has a :term:`polymorphic` mapping as its target.
+a :func:`_orm.relationship` that has a :term:`polymorphic` mapping as its target.
This method can now be used to target *any number* of target subtypes,
by combining it with the new :func:`.with_polymorphic` function::
The method now works equally well in most places a regular relationship
attribute is accepted, including with loader functions like
-:func:`.joinedload`, :func:`.subqueryload`, :func:`.contains_eager`,
+:func:`_orm.joinedload`, :func:`.subqueryload`, :func:`.contains_eager`,
and comparison methods like :meth:`.PropComparator.any`
and :meth:`.PropComparator.has`::
ORM Classes Now Accepted by Core Constructs
-------------------------------------------
-While the SQL expressions used with :meth:`.Query.filter`,
+While the SQL expressions used with :meth:`_query.Query.filter`,
such as ``User.id == 5``, have always been compatible for
-use with core constructs such as :func:`~.sql.expression.select`, the mapped
-class itself would not be recognized when passed to :func:`~.sql.expression.select`,
-:meth:`.Select.select_from`, or :meth:`.Select.correlate`.
+use with core constructs such as :func:`_expression.select`, the mapped
+class itself would not be recognized when passed to :func:`_expression.select`,
+:meth:`_expression.Select.select_from`, or :meth:`_expression.Select.correlate`.
A new SQL registration system allows a mapped class to be
accepted as a FROM clause within the core::
stmt = select([User]).where(User.id == 5)
Above, the mapped ``User`` class will expand into
-the :class:`.Table` to which ``User`` is mapped.
+the :class:`_schema.Table` to which ``User`` is mapped.
:ticket:`2245`
really drives what kinds of operations are present, it's the
*type* of the expression. The implementation details are
minimal - only a few extra methods are added to the core
-:class:`.ColumnElement` type so that it consults its
+:class:`_expression.ColumnElement` type so that it consults its
:class:`.TypeEngine` object for an optional set of operators.
New or revised operations can be associated with any type,
either via subclassing of an existing type, by using
Multiple-VALUES support for Insert
----------------------------------
-The :meth:`.Insert.values` method now supports a list of dictionaries,
+The :meth:`_expression.Insert.values` method now supports a list of dictionaries,
which will render a multi-VALUES statement such as
``VALUES (<row1>), (<row2>), ...``. This is only relevant to backends which
support this syntax, including PostgreSQL, SQLite, and MySQL. It is
.. seealso::
- :meth:`.Insert.values`
+ :meth:`_expression.Insert.values`
:ticket:`2623`
Core Inspection System
----------------------
-The :func:`.inspect` function introduced in :ref:`feature_orminspection_08`
-also applies to the core. Applied to an :class:`.Engine` it produces
-an :class:`.Inspector` object::
+The :func:`_sa.inspect` function introduced in :ref:`feature_orminspection_08`
+also applies to the core. Applied to an :class:`_engine.Engine` it produces
+an :class:`_reflection.Inspector` object::
from sqlalchemy import inspect
from sqlalchemy import create_engine
insp = inspect(engine)
print(insp.get_table_names())
-It can also be applied to any :class:`.ClauseElement`, which returns
-the :class:`.ClauseElement` itself, such as :class:`.Table`, :class:`.Column`,
-:class:`.Select`, etc. This allows it to work fluently between Core
+It can also be applied to any :class:`_expression.ClauseElement`, which returns
+the :class:`_expression.ClauseElement` itself, such as :class:`_schema.Table`, :class:`_schema.Column`,
+:class:`_expression.Select`, etc. This allows it to work fluently between Core
and ORM constructs.
-New Method :meth:`.Select.correlate_except`
--------------------------------------------
-
-:func:`~.sql.expression.select` now has a method :meth:`.Select.correlate_except`
+New Method :meth:`_expression.Select.correlate_except`
+-------------------------------------------------------
+:func:`_expression.select` now has a method :meth:`_expression.Select.correlate_except`
which specifies "correlate on all FROM clauses except those
specified". It can be used for mapping scenarios where
a related subquery should correlate normally, except
.. seealso::
- :meth:`.Select.correlate_except`
+ :meth:`_expression.Select.correlate_except`
PostgreSQL HSTORE type
----------------------
Support for PostgreSQL's ``HSTORE`` type is now available as
-:class:`.postgresql.HSTORE`. This type makes great usage
+:class:`_postgresql.HSTORE`. This type makes great usage
of the new operator system to provide a full range of operators
for HSTORE types, including index access, concatenation,
and containment methods such as
.. seealso::
- :class:`.postgresql.HSTORE`
+ :class:`_postgresql.HSTORE`
- :class:`.postgresql.hstore`
+ :class:`_postgresql.hstore`
:ticket:`2606`
Enhanced PostgreSQL ARRAY type
------------------------------
-The :class:`.postgresql.ARRAY` type will accept an optional
+The :class:`_postgresql.ARRAY` type will accept an optional
"dimension" argument, pinning it to a fixed number of
dimensions and greatly improving efficiency when retrieving
results:
.. seealso::
- :class:`.postgresql.ARRAY`
+ :class:`_postgresql.ARRAY`
- :class:`.postgresql.array`
+ :class:`_postgresql.array`
:ticket:`2441`
.. seealso::
- :class:`.sqlite.DATETIME`
+ :class:`_sqlite.DATETIME`
- :class:`.sqlite.DATE`
+ :class:`_sqlite.DATE`
- :class:`.sqlite.TIME`
+ :class:`_sqlite.TIME`
:ticket:`2363`
The "collate" keyword, long accepted by the MySQL dialect, is now established
on all :class:`.String` types and will render on any backend, including
-when features such as :meth:`.MetaData.create_all` and :func:`.cast` is used::
+when features such as :meth:`_schema.MetaData.create_all` and :func:`.cast` is used::
>>> stmt = select([cast(sometable.c.somechar, String(20, collation='utf8'))])
>>> print(stmt)
:ticket:`2276`
-"Prefixes" now supported for :func:`.update`, :func:`.delete`
-----------------------------------------------------------------------------
-
+"Prefixes" now supported for :func:`_expression.update`, :func:`_expression.delete`
+------------------------------------------------------------------------------------
Geared towards MySQL, a "prefix" can be rendered within any of
these constructs. E.g.::
stmt = table.update().prefix_with("LOW_PRIORITY", dialect="mysql")
The method is new in addition to those which already existed
-on :func:`~.sql.expression.insert`, :func:`~.sql.expression.select` and :class:`.Query`.
+on :func:`_expression.insert`, :func:`_expression.select` and :class:`_query.Query`.
.. seealso::
- :meth:`.Update.prefix_with`
+ :meth:`_expression.Update.prefix_with`
- :meth:`.Delete.prefix_with`
+ :meth:`_expression.Delete.prefix_with`
- :meth:`.Insert.prefix_with`
+ :meth:`_expression.Insert.prefix_with`
- :meth:`.Select.prefix_with`
+ :meth:`_expression.Select.prefix_with`
- :meth:`.Query.prefix_with`
+ :meth:`_query.Query.prefix_with`
:ticket:`2431`
associated with a :class:`.Session` but hasn't been inserted into the database
yet, is automatically expunged from the :class:`.Session` when it becomes an "orphan",
which means it has been de-associated with a parent object that refers to it
-with ``delete-orphan`` cascade on the configured :func:`.relationship`. This
+with ``delete-orphan`` cascade on the configured :func:`_orm.relationship`. This
behavior is intended to approximately mirror the behavior of a persistent
(that is, already inserted) object, where the ORM will emit a DELETE for such
objects that become orphans based on the interception of detachment events.
make user errors of this nature very hard to debug.
The old behavior, for applications that might have been relying upon it, can be re-enabled for
-any :class:`.Mapper` by specifying the flag ``legacy_is_orphan`` as a mapper
+any :class:`_orm.Mapper` by specifying the flag ``legacy_is_orphan`` as a mapper
option.
The new behavior allows the following test case to work::
Query now auto-correlates like a select() does
----------------------------------------------
-Previously it was necessary to call :meth:`.Query.correlate` in
+Previously it was necessary to call :meth:`_query.Query.correlate` in
order to have a column- or WHERE-subquery correlate to the
parent:
------------------------------------------
To allow a wider variety of correlation scenarios, the behavior of
-:meth:`.Select.correlate` and :meth:`.Query.correlate` has changed slightly
+:meth:`_expression.Select.correlate` and :meth:`_query.Query.correlate` has changed slightly
such that the SELECT statement will omit the "correlated" target from the
FROM clause only if the statement is actually used in that context. Additionally,
it's no longer possible for a SELECT statement that's placed as a FROM
create_all() and drop_all() will now honor an empty list as such
----------------------------------------------------------------
-The methods :meth:`.MetaData.create_all` and :meth:`.MetaData.drop_all`
-will now accept a list of :class:`.Table` objects that is empty,
+The methods :meth:`_schema.MetaData.create_all` and :meth:`_schema.MetaData.drop_all`
+will now accept a list of :class:`_schema.Table` objects that is empty,
and will not emit any CREATE or DROP statements. Previously,
an empty list was interpreted the same as passing ``None``
for a collection, and CREATE/DROP would be emitted for all
:ticket:`2320`
-:attr:`.Column.key` is honored in the :attr:`.Select.c` attribute of :func:`~.sql.expression.select` with :meth:`.Select.apply_labels`
+:attr:`_schema.Column.key` is honored in the :attr:`_expression.Select.c` attribute of :func:`_expression.select` with :meth:`_expression.Select.apply_labels`
---------------------------------------------------------------------------------------------------------------------------------------------------------------
-
-Users of the expression system know that :meth:`.Select.apply_labels`
+Users of the expression system know that :meth:`_expression.Select.apply_labels`
prepends the table name to each column name, affecting the
-names that are available from :attr:`.Select.c`:
+names that are available from :attr:`_expression.Select.c`:
::
s.c.table1_col1
s.c.table1_col2
-Before 0.8, if the :class:`.Column` had a different :attr:`.Column.key`, this
+Before 0.8, if the :class:`_schema.Column` had a different :attr:`_schema.Column.key`, this
key would be ignored, inconsistently versus when
-:meth:`.Select.apply_labels` were not used:
+:meth:`_expression.Select.apply_labels` were not used:
::
s.c.table1_column_one # would raise AttributeError
s.c.table1_col1 # would be accessible like this
-In 0.8, :attr:`.Column.key` is honored in both cases:
+In 0.8, :attr:`_schema.Column.key` is honored in both cases:
::
All other behavior regarding "name" and "key" are the same,
including that the rendered SQL will still use the form
``<tablename>_<colname>`` - the emphasis here was on
-preventing the :attr:`.Column.key` contents from being rendered into the
+preventing the :attr:`_schema.Column.key` contents from being rendered into the
``SELECT`` statement so that there are no issues with
-special/ non-ascii characters used in the :attr:`.Column.key`.
+special/ non-ascii characters used in the :attr:`_schema.Column.key`.
:ticket:`2397`
single_parent warning is now an error
-------------------------------------
-A :func:`.relationship` that is many-to-one or many-to-many and
+A :func:`_orm.relationship` that is many-to-one or many-to-many and
specifies "cascade='all, delete-orphan'", which is an
awkward but nonetheless supported use case (with
restrictions) will now raise an error if the relationship
Composite attributes are now returned as their object form when queried on a per-attribute basis
------------------------------------------------------------------------------------------------
-Using a :class:`.Query` in conjunction with a composite attribute now returns the object
+Using a :class:`_query.Query` in conjunction with a composite attribute now returns the object
type maintained by that composite, rather than being broken out into individual
columns. Using the mapping setup at :ref:`mapper_composite`::
.. _migration_2736:
-:meth:`.Query.select_from` no longer applies the clause to corresponding entities
------------------------------------------------------------------------------------------------
-
-The :meth:`.Query.select_from` method has been popularized in recent versions
-as a means of controlling the first thing that a :class:`.Query` object
+:meth:`_query.Query.select_from` no longer applies the clause to corresponding entities
+----------------------------------------------------------------------------------------
+The :meth:`_query.Query.select_from` method has been popularized in recent versions
+as a means of controlling the first thing that a :class:`_query.Query` object
"selects from", typically for the purposes of controlling how a JOIN will
render.
If we wanted to reverse the order of the left and right elements of the
JOIN, the documentation would lead us to believe we could use
-:meth:`.Query.select_from` to do so::
+:meth:`_query.Query.select_from` to do so::
q = session.query(User).\
select_from(select_stmt).\
join(User, User.id == select_stmt.c.id).\
filter(User.name == 'ed')
-However, in version 0.8 and earlier, the above use of :meth:`.Query.select_from`
+However, in version 0.8 and earlier, the above use of :meth:`_query.Query.select_from`
would apply the ``select_stmt`` to **replace** the ``User`` entity, as it
selects from the ``user`` table which is compatible with ``User``::
our WHERE clause has been replaced with ``anon_1`` as well.
This behavior is quite intentional, but has a different use case from that
-which has become popular for :meth:`.Query.select_from`. The above behavior
-is now available by a new method known as :meth:`.Query.select_entity_from`.
+which has become popular for :meth:`_query.Query.select_from`. The above behavior
+is now available by a new method known as :meth:`_query.Query.select_entity_from`.
This is a lesser used behavior that in modern SQLAlchemy is roughly equivalent
to selecting from a customized :func:`.aliased` construct::
WHERE "user".id = :id_1) AS anon_1 JOIN "user" ON "user".id = id
WHERE "user".name = :name_1
-The :meth:`.Query.select_entity_from` method will be available in SQLAlchemy
+The :meth:`_query.Query.select_entity_from` method will be available in SQLAlchemy
**0.8.2**, so applications which rely on the old behavior can transition
to this method first, ensure all tests continue to function, then upgrade
to 0.9 without issue.
``viewonly=True`` on ``relationship()`` prevents history from taking effect
---------------------------------------------------------------------------
-The ``viewonly`` flag on :func:`.relationship` is applied to prevent changes
+The ``viewonly`` flag on :func:`_orm.relationship` is applied to prevent changes
to the target attribute from having any effect within the flush process.
This is achieved by eliminating the attribute from being considered during
the flush. However, up until now, changes to the attribute would still
PostgreSQL CREATE TYPE <x> AS ENUM now applies quoting to values
----------------------------------------------------------------
-The :class:`.postgresql.ENUM` type will now apply escaping to single quote
+The :class:`_postgresql.ENUM` type will now apply escaping to single quote
signs within the enumerated values::
>>> from sqlalchemy.dialects import postgresql
New Query Options API; ``load_only()`` option
---------------------------------------------
-The system of loader options such as :func:`.orm.joinedload`,
-:func:`.orm.subqueryload`, :func:`.orm.lazyload`, :func:`.orm.defer`, etc.
-all build upon a new system known as :class:`.Load`. :class:`.Load` provides
+The system of loader options such as :func:`_orm.joinedload`,
+:func:`_orm.subqueryload`, :func:`_orm.lazyload`, :func:`_orm.defer`, etc.
+all build upon a new system known as :class:`_orm.Load`. :class:`_orm.Load` provides
a "method chained" (a.k.a. :term:`generative`) approach to loader options, so that
instead of joining together long paths using dots or multiple attribute names,
an explicit loader style is given for each path.
Loader options are now chainable, so the same ``joinedload(x)`` method is applied
equally to each link, without the need to keep straight between
-:func:`.joinedload` and :func:`.joinedload_all`::
+:func:`_orm.joinedload` and :func:`_orm.joinedload_all`::
query(User).options(joinedload("orders").joinedload("items").joinedload("keywords"))
**New Way**
-A single :class:`.Load` object that arrives at the target path can have
-:meth:`.Load.defer` called upon it repeatedly::
+A single :class:`_orm.Load` object that arrives at the target path can have
+:meth:`_orm.Load.defer` called upon it repeatedly::
query(User).options(defaultload("orders").defer("description").defer("isopen"))
The Load Class
^^^^^^^^^^^^^^^
-The :class:`.Load` class can be used directly to provide a "bound" target,
+The :class:`_orm.Load` class can be used directly to provide a "bound" target,
especially when multiple parent entities are present::
from sqlalchemy.orm import Load
Class-specific Wildcards
^^^^^^^^^^^^^^^^^^^^^^^^^
-Using :class:`.Load`, a wildcard may be used to set the loading for all
+Using :class:`_orm.Load`, a wildcard may be used to set the loading for all
relationships (or perhaps columns) on a given entity, without affecting any
others::
New ``text()`` Capabilities
---------------------------
-The :func:`.text` construct gains new methods:
+The :func:`_expression.text` construct gains new methods:
-* :meth:`.TextClause.bindparams` allows bound parameter types and values
+* :meth:`_expression.TextClause.bindparams` allows bound parameter types and values
to be set flexibly::
# setup values
bindparam("timestamp", type_=DateTime()
).bindparam(timestamp=datetime(2012, 11, 10, 15, 12, 35))
-* :meth:`.TextClause.columns` supersedes the ``typemap`` option
- of :func:`.text`, returning a new construct :class:`.TextAsFrom`::
+* :meth:`_expression.TextClause.columns` supersedes the ``typemap`` option
+ of :func:`_expression.text`, returning a new construct :class:`.TextAsFrom`::
# turn a text() into an alias(), with a .c. collection:
stmt = text("SELECT id, name FROM user").columns(id=Integer, name=String)
After literally years of pointless procrastination this relatively minor
syntactical feature has been added, and is also backported to 0.8.3,
-so technically isn't "new" in 0.9. A :func:`~.sql.expression.select` construct or other
-compatible construct can be passed to the new method :meth:`.Insert.from_select`
+so technically isn't "new" in 0.9. A :func:`_expression.select` construct or other
+compatible construct can be passed to the new method :meth:`_expression.Insert.from_select`
where it will be used to render an ``INSERT .. SELECT`` construct::
>>> from sqlalchemy.sql import table, column
WHERE t2.y = :y_1
The construct is smart enough to also accommodate ORM objects such as classes
-and :class:`.Query` objects::
+and :class:`_query.Query` objects::
s = Session()
q = s.query(User.id, User.name).filter_by(name='ed')
clause on ``SELECT`` statements made within Core and ORM, and support is added
for the ``FOR UPDATE OF`` SQL supported by PostgreSQL and Oracle.
-Using the core :meth:`.GenerativeSelect.with_for_update`, options like ``FOR SHARE`` and
+Using the core :meth:`_expression.GenerativeSelect.with_for_update`, options like ``FOR SHARE`` and
``NOWAIT`` can be specified individually, rather than linking to arbitrary
string codes::
SELECT table.a, table.b FROM table FOR SHARE OF table NOWAIT
-The :class:`.Query` object gains a similar method :meth:`.Query.with_for_update`
+The :class:`_query.Query` object gains a similar method :meth:`_query.Query.with_for_update`
which behaves in the same way. This method supersedes the existing
-:meth:`.Query.with_lockmode` method, which translated ``FOR UPDATE`` clauses
+:meth:`_query.Query.with_lockmode` method, which translated ``FOR UPDATE`` clauses
using a different system. At the moment, the "lockmode" string argument is still
accepted by the :meth:`.Session.refresh` method.
PostgreSQL JSON Type
--------------------
-The PostgreSQL dialect now features a :class:`.postgresql.JSON` type to
-complement the :class:`.postgresql.HSTORE` type.
+The PostgreSQL dialect now features a :class:`_postgresql.JSON` type to
+complement the :class:`_postgresql.HSTORE` type.
.. seealso::
- :class:`.postgresql.JSON`
+ :class:`_postgresql.JSON`
:ticket:`2581`
provides a base class :class:`.AutomapBase` which automatically generates
mapped classes and relationships between them based on given table metadata.
-The :class:`.MetaData` in use normally might be produced via reflection, but
+The :class:`_schema.MetaData` in use normally might be produced via reflection, but
there is no requirement that reflection is used. The most basic usage
illustrates how :mod:`sqlalchemy.ext.automap` is able to deliver mapped
classes, including relationships, based on a reflected schema::
) AS anon_1 ON a.id=anon_1.b_id
A JOIN like the above form is commonplace when working with joined-table inheritance structures;
-any time :meth:`.Query.join` is used to join from some parent to a joined-table subclass, or
-when :func:`.joinedload` is used similarly, SQLAlchemy's ORM would always make sure a nested
+any time :meth:`_query.Query.join` is used to join from some parent to a joined-table subclass, or
+when :func:`_orm.joinedload` is used similarly, SQLAlchemy's ORM would always make sure a nested
JOIN was never rendered, lest the query wouldn't be able to run on SQLite. Even though
the Core has always supported a JOIN of the more compact form, the ORM had to avoid it.
(order_item JOIN item ON order_item.item_id = item.id AND item.type = 'subitem')
ON order_item.order_id = order.id
-All of these joins, when rendered with a :class:`.Select` statement that specifically
+All of these joins, when rendered with a :class:`_expression.Select` statement that specifically
specifies ``use_labels=True``, which is true for all the queries the ORM emits,
are candidates for "join rewriting", which is the process of rewriting all those right-nested
joins into nested SELECT statements, while maintaining the identical labeling used by
-the :class:`.Select`. So SQLite, the one database that won't support this very
+the :class:`_expression.Select`. So SQLite, the one database that won't support this very
common SQL syntax even in 2013, shoulders the extra complexity itself,
with the above queries rewritten as::
will automatically disable themselves when SQLite version **3.7.16**
or greater is detected, as SQLite has repaired support for right-nested joins.
-The :meth:`.Join.alias`, :func:`.aliased` and :func:`.with_polymorphic` functions now
+The :meth:`_expression.Join.alias`, :func:`.aliased` and :func:`.with_polymorphic` functions now
support a new argument, ``flat=True``, which is used to construct aliases of joined-table
entities without embedding into a SELECT. This flag is not on by default, to help with
backwards compatibility - but now a "polymorphic" selectable can be joined as a target
FROM users LEFT OUTER JOIN (orders JOIN items ON <onclause>) ON <onclause>
Since we missed the boat on that, to avoid further regressions we've added the above
-functionality by specifying the string ``"nested"`` to :paramref:`.joinedload.innerjoin`::
+functionality by specifying the string ``"nested"`` to :paramref:`_orm.joinedload.innerjoin`::
query(User).options(joinedload("orders", innerjoin=False).joinedload("items", innerjoin="nested"))
ORM can efficiently fetch just-generated INSERT/UPDATE defaults using RETURNING
-------------------------------------------------------------------------------
-The :class:`.Mapper` has long supported an undocumented flag known as
+The :class:`_orm.Mapper` has long supported an undocumented flag known as
``eager_defaults=True``. The effect of this flag is that when an INSERT or UPDATE
proceeds, and the row is known to have server-generated default values,
a SELECT would immediately follow it in order to "eagerly" load those new values.
support in particular PostgreSQL, the ORM can fetch newly generated default
and SQL expression values inline with the INSERT or UPDATE. ``eager_defaults``,
when enabled, makes use of RETURNING automatically when the target backend
-and :class:`.Table` supports "implicit returning".
+and :class:`_schema.Table` supports "implicit returning".
.. _change_2836:
Since ``a.b_id`` is a non-distinct foreign key, DISTINCT is applied so that
redundant ``a.b_id`` are eliminated. The behavior can be turned on or off
-unconditionally for a particular :func:`.relationship` using the flag
+unconditionally for a particular :func:`_orm.relationship` using the flag
``distinct_target_key``, setting the value to ``True`` for unconditionally
on, ``False`` for unconditionally off, and ``None`` for the feature to take
effect when the target SELECT is against columns that do not comprise a full
---------------------------------------------------------------------
This change simplifies the Core's usage of so-called "quote" flags, such
-as the ``quote`` flag passed to :class:`.Table` and :class:`.Column`. The flag
+as the ``quote`` flag passed to :class:`_schema.Table` and :class:`_schema.Column`. The flag
is now internalized within the string name itself, which is now represented
as an instance of :class:`.quoted_name`, a string subclass. The
:class:`.IdentifierPreparer` now relies solely on the quoting preferences
reported by the :class:`.quoted_name` object rather than checking for any
explicit ``quote`` flags in most cases. The issue resolved here includes
-that various case-sensitive methods such as :meth:`.Engine.has_table` as well
+that various case-sensitive methods such as :meth:`_engine.Engine.has_table` as well
as similar methods within dialects now function with explicitly quoted names,
without the need to complicate or introduce backwards-incompatible changes
to those APIs (many of which are 3rd party) with the details of quoting flags -
type of the enclosing expression has been improved in two ways. First, the
:func:`.bindparam` object is **copied** before the new type is assigned, so that
the given :func:`.bindparam` is not mutated in place. Secondly, this same
-operation occurs when an :class:`~.sql.expression.Insert` or :class:`.Update` construct is compiled,
+operation occurs when an :class:`_expression.Insert` or :class:`_expression.Update` construct is compiled,
regarding the "values" that were set in the statement via the :meth:`.ValuesBase.values`
method.
binary expression, will take on the ``String`` type. Previously, ``bp`` itself
would have been changed in place to have ``String`` as its type.
-Similarly, this operation occurs in an :class:`~.sql.expression.Insert` or :class:`.Update`::
+Similarly, this operation occurs in an :class:`_expression.Insert` or :class:`_expression.Update`::
stmt = mytable.update().values(col=bp)
scenarios. Since the bound parameter is
**cloned**, users should not be relying upon making in-place changes to a
:func:`.bindparam` construct once created. Additionally, code which uses
-:func:`.bindparam` within an :class:`~.sql.expression.Insert` or :class:`.Update` statement
+:func:`.bindparam` within an :class:`_expression.Insert` or :class:`_expression.Update` statement
which is relying on the fact that the :func:`.bindparam` is not typed according
to the column being assigned towards will no longer function in that way.
Columns can reliably get their type from a column referred to via ForeignKey
----------------------------------------------------------------------------
-There's a long standing behavior which says that a :class:`.Column` can be
-declared without a type, as long as that :class:`.Column` is referred to
-by a :class:`.ForeignKeyConstraint`, and the type from the referenced column
+There's a long standing behavior which says that a :class:`_schema.Column` can be
+declared without a type, as long as that :class:`_schema.Column` is referred to
+by a :class:`_schema.ForeignKeyConstraint`, and the type from the referenced column
will be copied into this one. The problem has been that this feature never
worked very well and wasn't maintained. The core issue was that the
-:class:`.ForeignKey` object doesn't know what target :class:`.Column` it
+:class:`_schema.ForeignKey` object doesn't know what target :class:`_schema.Column` it
refers to until it is asked, typically the first time the foreign key is used
-to construct a :class:`.Join`. So until that time, the parent :class:`.Column`
+to construct a :class:`_expression.Join`. So until that time, the parent :class:`_schema.Column`
would not have a type, or more specifically, it would have a default type
of :class:`.NullType`.
While it's taken a long time, the work to reorganize the initialization of
-:class:`.ForeignKey` objects has been completed such that this feature can
-finally work acceptably. At the core of the change is that the :attr:`.ForeignKey.column`
-attribute no longer lazily initializes the location of the target :class:`.Column`;
-the issue with this system was that the owning :class:`.Column` would be stuck
-with :class:`.NullType` as its type until the :class:`.ForeignKey` happened to
+:class:`_schema.ForeignKey` objects has been completed such that this feature can
+finally work acceptably. At the core of the change is that the :attr:`_schema.ForeignKey.column`
+attribute no longer lazily initializes the location of the target :class:`_schema.Column`;
+the issue with this system was that the owning :class:`_schema.Column` would be stuck
+with :class:`.NullType` as its type until the :class:`_schema.ForeignKey` happened to
be used.
-In the new version, the :class:`.ForeignKey` coordinates with the eventual
-:class:`.Column` it will refer to using internal attachment events, so that the
-moment the referencing :class:`.Column` is associated with the
-:class:`.MetaData`, all :class:`.ForeignKey` objects that
+In the new version, the :class:`_schema.ForeignKey` coordinates with the eventual
+:class:`_schema.Column` it will refer to using internal attachment events, so that the
+moment the referencing :class:`_schema.Column` is associated with the
+:class:`_schema.MetaData`, all :class:`_schema.ForeignKey` objects that
refer to it will be sent a message that they need to initialize their parent
column. This system is more complicated but works more solidly; as a bonus,
-there are now tests in place for a wide variety of :class:`.Column` /
-:class:`.ForeignKey` configuration scenarios and error messages have been
+there are now tests in place for a wide variety of :class:`_schema.Column` /
+:class:`_schema.ForeignKey` configuration scenarios and error messages have been
improved to be very specific to no less than seven different error conditions.
Scenarios which now work correctly include:
-1. The type on a :class:`.Column` is immediately present as soon as the
- target :class:`.Column` becomes associated with the same :class:`.MetaData`;
+1. The type on a :class:`_schema.Column` is immediately present as soon as the
+ target :class:`_schema.Column` becomes associated with the same :class:`_schema.MetaData`;
this works no matter which side is configured first::
>>> from sqlalchemy import Table, MetaData, Column, Integer, ForeignKey
>>> t2.c.t1id.type
Integer()
-2. The system now works with :class:`.ForeignKeyConstraint` as well::
+2. The system now works with :class:`_schema.ForeignKeyConstraint` as well::
>>> from sqlalchemy import Table, MetaData, Column, Integer, ForeignKeyConstraint
>>> metadata = MetaData()
>>> t2.c.t1b.type
Integer()
-3. It even works for "multiple hops" - that is, a :class:`.ForeignKey` that refers to a
- :class:`.Column` that refers to another :class:`.Column`::
+3. It even works for "multiple hops" - that is, a :class:`_schema.ForeignKey` that refers to a
+ :class:`_schema.Column` that refers to another :class:`_schema.Column`::
>>> from sqlalchemy import Table, MetaData, Column, Integer, ForeignKey
>>> metadata = MetaData()
---------------
The "baked" query feature is an unusual new approach which allows for
-straightforward construction an invocation of :class:`.Query` objects
+straightforward construction an invocation of :class:`_query.Query` objects
using caching, which upon successive calls features vastly reduced
Python function call overhead (over 75%). By specifying a
-:class:`.Query` object as a series of lambdas which are only invoked
+:class:`_query.Query` object as a series of lambdas which are only invoked
once, a query as a pre-compiled unit begins to be feasible::
from sqlalchemy.ext import baked
A function decorated with :class:`.declared_attr` is now called only **after**
any mixin-based column copies are generated. This means the function can
call upon mixin-established columns and will receive a reference to the correct
-:class:`.Column` object::
+:class:`_schema.Column` object::
class HasFooBar(object):
foobar = Column(Integer)
id = Column(Integer, primary_key=True)
Above, ``SomeClass.foobar_prop`` will be invoked against ``SomeClass``,
-and ``SomeClass.foobar`` will be the final :class:`.Column` object that is
+and ``SomeClass.foobar`` will be the final :class:`_schema.Column` object that is
to be mapped to ``SomeClass``, as opposed to the non-copied object present
directly on ``HasFooBar``, even though the columns aren't mapped yet.
print("Total time: %d" % (time.time() - now))
Local MacBookPro results bench from 19 seconds for 0.9 down to 14 seconds for
-1.0. The :meth:`.Query.yield_per` call is always a good idea when batching
+1.0. The :meth:`_query.Query.yield_per` call is always a good idea when batching
huge numbers of rows, as it prevents the Python interpreter from having
to allocate a huge amount of memory for all objects and their instrumentation
-at once. Without the :meth:`.Query.yield_per`, the above script on the
+at once. Without the :meth:`_query.Query.yield_per`, the above script on the
MacBookPro is 31 seconds on 0.9 and 26 seconds on 1.0, the extra time spent
setting up very large memory buffers.
----------------------------------------------------------------------
A series of issues were repaired where the :meth:`.Session.get_bind`
-would not receive the primary :class:`.Mapper` of the :class:`.Query`,
+would not receive the primary :class:`_orm.Mapper` of the :class:`_query.Query`,
even though this mapper was readily available (the primary mapper is the
single mapper, or alternatively the first mapper, that is associated with
-a :class:`.Query` object).
+a :class:`_query.Query` object).
-The :class:`.Mapper` object, when passed to :meth:`.Session.get_bind`,
+The :class:`_orm.Mapper` object, when passed to :meth:`.Session.get_bind`,
is typically used by sessions that make use of the
:paramref:`.Session.binds` parameter to associate mappers with a
series of engines (although in this use case, things frequently
These scenarios include:
-* :meth:`.Query.count`::
+* :meth:`_query.Query.count`::
session.query(User).count()
-* :meth:`.Query.update` and :meth:`.Query.delete`, both for the UPDATE/DELETE
+* :meth:`_query.Query.update` and :meth:`_query.Query.delete`, both for the UPDATE/DELETE
statement as well as for the SELECT used by the "fetch" strategy::
session.query(User).filter(User.id == 15).update(
-----------------------------
The :attr:`.InspectionAttr.info` collection is now available on every kind
-of object that one would retrieve from the :attr:`.Mapper.all_orm_descriptors`
+of object that one would retrieve from the :attr:`_orm.Mapper.all_orm_descriptors`
collection. This includes :class:`.hybrid_property` and :func:`.association_proxy`.
However, as these objects are class-bound descriptors, they must be accessed
**separately** from the class to which they are attached in order to get
at the attribute. Below this is illustrated using the
-:attr:`.Mapper.all_orm_descriptors` namespace::
+:attr:`_orm.Mapper.all_orm_descriptors` namespace::
class SomeObject(Base):
# ...
inspect(SomeObject).all_orm_descriptors.some_prop.info['foo'] = 'bar'
It is also available as a constructor argument for all :class:`.SchemaItem`
-objects (e.g. :class:`.ForeignKey`, :class:`.UniqueConstraint` etc.) as well
-as remaining ORM constructs such as :func:`.orm.synonym`.
+objects (e.g. :class:`_schema.ForeignKey`, :class:`.UniqueConstraint` etc.) as well
+as remaining ORM constructs such as :func:`_orm.synonym`.
:ticket:`2971`
Select/Query LIMIT / OFFSET may be specified as an arbitrary SQL expression
---------------------------------------------------------------------------
-The :meth:`.Select.limit` and :meth:`.Select.offset` methods now accept
+The :meth:`_expression.Select.limit` and :meth:`_expression.Select.offset` methods now accept
any SQL expression, in addition to integer values, as arguments. The ORM
-:class:`.Query` object also passes through any expression to the underlying
-:class:`.Select` object. Typically
+:class:`_query.Query` object also passes through any expression to the underlying
+:class:`_expression.Select` object. Typically
this is used to allow a bound parameter to be passed, which can be substituted
with a value later::
The ``use_alter`` flag on ``ForeignKeyConstraint`` is (usually) no longer needed
--------------------------------------------------------------------------------
-The :meth:`.MetaData.create_all` and :meth:`.MetaData.drop_all` methods will
+The :meth:`_schema.MetaData.create_all` and :meth:`_schema.MetaData.drop_all` methods will
now make use of a system that automatically renders an ALTER statement
for foreign key constraints that are involved in mutually-dependent cycles
between tables, without the
-need to specify :paramref:`.ForeignKeyConstraint.use_alter`. Additionally,
+need to specify :paramref:`_schema.ForeignKeyConstraint.use_alter`. Additionally,
the foreign key constraints no longer need to have a name in order to be
created via ALTER; only the DROP operation requires a name. In the case
of a DROP, the feature will ensure that only constraints which have
case of an unresolvable cycle within a DROP, the system emits
a succinct and clear error message now if the DROP cannot proceed.
-The :paramref:`.ForeignKeyConstraint.use_alter` and
-:paramref:`.ForeignKey.use_alter` flags remain in place, and continue to have
+The :paramref:`_schema.ForeignKeyConstraint.use_alter` and
+:paramref:`_schema.ForeignKey.use_alter` flags remain in place, and continue to have
the same effect of establishing those constraints for which ALTER is
required during a CREATE/DROP scenario.
constraints are enabled. To resolve the warning and proceed with at least
a partial ordering on a SQLite database, particularly one where constraints
are enabled, re-apply "use_alter" flags to those
-:class:`.ForeignKey` and :class:`.ForeignKeyConstraint` objects which should
+:class:`_schema.ForeignKey` and :class:`_schema.ForeignKeyConstraint` objects which should
be explicitly omitted from the sort.
.. seealso::
-----------------------------------------------------------------------------------------------------------------
Since at least version 0.8, a :class:`.Constraint` has had the ability to
-"auto-attach" itself to a :class:`.Table` based on being passed table-attached columns::
+"auto-attach" itself to a :class:`_schema.Table` based on being passed table-attached columns::
from sqlalchemy import Table, Column, MetaData, Integer, UniqueConstraint
assert uq in t.constraints
In order to assist with some cases that tend to come up with declarative,
-this same auto-attachment logic can now function even if the :class:`.Column`
-objects are not yet associated with the :class:`.Table`; additional events
-are established such that when those :class:`.Column` objects are associated,
+this same auto-attachment logic can now function even if the :class:`_schema.Column`
+objects are not yet associated with the :class:`_schema.Table`; additional events
+are established such that when those :class:`_schema.Column` objects are associated,
the :class:`.Constraint` is also added::
from sqlalchemy import Table, Column, MetaData, Integer, UniqueConstraint
The above feature was a late add as of version 1.0.0b3. A fix as of
version 1.0.4 for :ticket:`3411` ensures that this logic
does not occur if the :class:`.Constraint` refers to a mixture of
-:class:`.Column` objects and string column names; as we do not yet have
-tracking for the addition of names to a :class:`.Table`::
+:class:`_schema.Column` objects and string column names; as we do not yet have
+tracking for the addition of names to a :class:`_schema.Table`::
from sqlalchemy import Table, Column, MetaData, Integer, UniqueConstraint
assert uq not in t.constraints
Above, the attachment event for column "a" to table "t" will fire off before
-column "b" is attached (as "a" is stated in the :class:`.Table` constructor
+column "b" is attached (as "a" is stated in the :class:`_schema.Table` constructor
before "b"), and the constraint will fail to locate "b" if it were to attempt
an attachment. For consistency, if the constraint refers to any string names,
the autoattach-on-column-attach logic is skipped.
-The original auto-attach logic of course remains in place, if the :class:`.Table`
-already contains all the target :class:`.Column` objects at the time
+The original auto-attach logic of course remains in place, if the :class:`_schema.Table`
+already contains all the target :class:`_schema.Column` objects at the time
the :class:`.Constraint` is constructed::
from sqlalchemy import Table, Column, MetaData, Integer, UniqueConstraint
INSERT FROM SELECT now includes Python and SQL-expression defaults
------------------------------------------------------------------
-:meth:`.Insert.from_select` now includes Python and SQL-expression defaults if
+:meth:`_expression.Insert.from_select` now includes Python and SQL-expression defaults if
otherwise unspecified; the limitation where non-server column defaults
aren't included in an INSERT FROM SELECT is now lifted and these
expressions are rendered as constants into the SELECT statement::
------------------------------------------------
The "literal binds" compiler flag is switched on when a
-:class:`.DefaultClause`, set up by :paramref:`.Column.server_default`
+:class:`.DefaultClause`, set up by :paramref:`_schema.Column.server_default`
is present as a SQL expression to be compiled. This allows literals
embedded in SQL to render correctly, such as::
UniqueConstraint is now part of the Table reflection process
------------------------------------------------------------
-A :class:`.Table` object populated using ``autoload=True`` will now
+A :class:`_schema.Table` object populated using ``autoload=True`` will now
include :class:`.UniqueConstraint` constructs as well as
:class:`.Index` constructs. This logic has a few caveats for
PostgreSQL and MySQL:
PostgreSQL has the behavior such that when a UNIQUE constraint is
created, it implicitly creates a UNIQUE INDEX corresponding to that
-constraint as well. The :meth:`.Inspector.get_indexes` and the
-:meth:`.Inspector.get_unique_constraints` methods will continue to
+constraint as well. The :meth:`_reflection.Inspector.get_indexes` and the
+:meth:`_reflection.Inspector.get_unique_constraints` methods will continue to
**both** return these entries distinctly, where
-:meth:`.Inspector.get_indexes` now features a token
+:meth:`_reflection.Inspector.get_indexes` now features a token
``duplicates_constraint`` within the index entry indicating the
corresponding constraint when detected. However, when performing
full table reflection using ``Table(..., autoload=True)``, the
:class:`.Index` construct is detected as being linked to the
:class:`.UniqueConstraint`, and is **not** present within the
-:attr:`.Table.indexes` collection; only the :class:`.UniqueConstraint`
-will be present in the :attr:`.Table.constraints` collection. This
+:attr:`_schema.Table.indexes` collection; only the :class:`.UniqueConstraint`
+will be present in the :attr:`_schema.Table.constraints` collection. This
deduplication logic works by joining to the ``pg_constraint`` table
when querying ``pg_index`` to see if the two constructs are linked.
MySQL does not have separate concepts for a UNIQUE INDEX and a UNIQUE
constraint. While it supports both syntaxes when creating tables and indexes,
it does not store them any differently. The
-:meth:`.Inspector.get_indexes`
-and the :meth:`.Inspector.get_unique_constraints` methods will continue to
+:meth:`_reflection.Inspector.get_indexes`
+and the :meth:`_reflection.Inspector.get_unique_constraints` methods will continue to
**both** return an entry for a UNIQUE index in MySQL,
-where :meth:`.Inspector.get_unique_constraints` features a new token
+where :meth:`_reflection.Inspector.get_unique_constraints` features a new token
``duplicates_index`` within the constraint entry indicating that this is a
dupe entry corresponding to that index. However, when performing
full table reflection using ``Table(..., autoload=True)``,
the :class:`.UniqueConstraint` construct is
-**not** part of the fully reflected :class:`.Table` construct under any
+**not** part of the fully reflected :class:`_schema.Table` construct under any
circumstances; this construct is always represented by a :class:`.Index`
-with the ``unique=True`` setting present in the :attr:`.Table.indexes`
+with the ``unique=True`` setting present in the :attr:`_schema.Table.indexes`
collection.
.. seealso::
query.update() now resolves string names into mapped attribute names
--------------------------------------------------------------------
-The documentation for :meth:`.Query.update` states that the given
+The documentation for :meth:`_query.Query.update` states that the given
``values`` dictionary is "a dictionary with attributes names as keys",
implying that these are mapped attribute names. Unfortunately, the function
was designed more in mind to receive attributes and SQL expressions and
name = Column('user_name', String(50))
Above, the column ``user_name`` is mapped as ``name``. Previously,
-a call to :meth:`.Query.update` that was passed strings would have to
+a call to :meth:`_query.Query.update` that was passed strings would have to
have been called as follows::
session.query(User).update({'user_name': 'moonbeam'})
would be "None" if it had been not set otherwise; it now will send the
value :data:`.orm.attributes.NEVER_SET`, which is a value that may be sent
to an attribute listener now. This symbol may also be received when
-calling on mapper utility functions such as :meth:`.Mapper.primary_key_from_instance`;
+calling on mapper utility functions such as :meth:`_orm.Mapper.primary_key_from_instance`;
if the primary key attributes have no setting at all, whereas the value
would be ``None`` before, it will now be the :data:`.orm.attributes.NEVER_SET`
symbol, and no change to the object's state occurs.
Joined/Subquery eager loading explicitly disallowed with yield_per
------------------------------------------------------------------
-In order to make the :meth:`.Query.yield_per` method easier to use,
+In order to make the :meth:`_query.Query.yield_per` method easier to use,
an exception is raised if any subquery eager loaders, or joined
eager loaders that would use collections, are
to take effect when yield_per is used, as these are currently not compatible
q = sess.query(Object).options(lazyload('*')).yield_per(100)
-or use :meth:`.Query.enable_eagerloads`::
+or use :meth:`_query.Query.enable_eagerloads`::
q = sess.query(Object).enable_eagerloads(False).yield_per(100)
Right inner join nesting now the default for joinedload with innerjoin=True
---------------------------------------------------------------------------
-The behavior of :paramref:`.joinedload.innerjoin` as well as
-:paramref:`.relationship.innerjoin` is now to use "nested"
+The behavior of :paramref:`_orm.joinedload.innerjoin` as well as
+:paramref:`_orm.relationship.innerjoin` is now to use "nested"
inner joins, that is, right-nested, as the default behavior when an
inner join joined eager load is chained to an outer join eager load. In
order to get the old behavior of chaining all joined eager loads as
That is, using a right-nested join for the INNER join so that the full
result of ``users`` can be returned. The use of an INNER join is more efficient
-than using an OUTER join, and allows the :paramref:`.joinedload.innerjoin`
+than using an OUTER join, and allows the :paramref:`_orm.joinedload.innerjoin`
optimization parameter to take effect in all cases.
To get the older behavior, use ``innerjoin="unnested"``::
--------------------------------------------------------------------------------------
A warning is emitted in SQLAlchemy 0.9.10 (not yet released as of
-June 9, 2015) when the :meth:`.Query.update` or :meth:`.Query.delete` methods
-are invoked against a query which has also called upon :meth:`.Query.join`,
-:meth:`.Query.outerjoin`,
-:meth:`.Query.select_from` or :meth:`.Query.from_self`. These are unsupported
+June 9, 2015) when the :meth:`_query.Query.update` or :meth:`_query.Query.delete` methods
+are invoked against a query which has also called upon :meth:`_query.Query.join`,
+:meth:`_query.Query.outerjoin`,
+:meth:`_query.Query.select_from` or :meth:`_query.Query.from_self`. These are unsupported
use cases which silently fail in the 0.9 series up until 0.9.10 where it emits
a warning. In 1.0, these cases raise an exception.
query.update() with ``synchronize_session='evaluate'`` raises on multi-table update
-----------------------------------------------------------------------------------
-The "evaluator" for :meth:`.Query.update` won't work with multi-table
+The "evaluator" for :meth:`_query.Query.update` won't work with multi-table
updates, and needs to be set to ``synchronize_session=False`` or
``synchronize_session='fetch'`` when multiple tables are present.
The new behavior is that an explicit exception is now raised, with a message
class FooWidget(Widget):
pass
-Using :meth:`.Query.from_self` or :meth:`.Query.count` against a subclass
+Using :meth:`_query.Query.from_self` or :meth:`_query.Query.count` against a subclass
would produce a subquery, but then add the "WHERE" criteria for subtypes
to the outside::
SELECT related.id AS related_id
FROM related JOIN widget ON related.id = widget.related_id AND widget.type IN (:type_1)
-Above, because we joined to a subclass ``FooWidget``, :meth:`.Query.join`
+Above, because we joined to a subclass ``FooWidget``, :meth:`_query.Query.join`
knew to add the ``AND widget.type IN ('foo')`` criteria to the ON clause.
The change here is that the ``AND widget.type IN()`` criteria is now appended
in the way of the usage of plain text. The Core and ORM expression systems
were intended to allow any number of points at which the user can just
use plain text SQL expressions, not just in the sense that you can send a
-full SQL string to :meth:`.Connection.execute`, but that you can send strings
-with SQL expressions into many functions, such as :meth:`.Select.where`,
-:meth:`.Query.filter`, and :meth:`.Select.order_by`.
+full SQL string to :meth:`_engine.Connection.execute`, but that you can send strings
+with SQL expressions into many functions, such as :meth:`_expression.Select.where`,
+:meth:`_query.Query.filter`, and :meth:`_expression.Select.order_by`.
Note that by "SQL expressions" we mean a **full fragment of a SQL string**,
such as::
stmt = select([sometable]).where(sometable.c.somecolumn == 'value')
The Core tutorial has long featured an example of the use of this technique,
-using a :func:`~.sql.expression.select` construct where virtually all components of it
+using a :func:`_expression.select` construct where virtually all components of it
are specified as straight strings. However, despite this long-standing
behavior and example, users are apparently surprised that this behavior
exists, and when asking around the community, I was unable to find any user
that was in fact *not* surprised that you can send a full string into a method
-like :meth:`.Query.filter`.
+like :meth:`_query.Query.filter`.
So the change here is to encourage the user to qualify textual strings when
composing SQL that is partially or fully composed from textual fragments.
]).where(text("a = b")).select_from(text("sometable"))
and as the warnings suggest, we can give our statement more specificity
-about the text if we use :func:`.column` and :func:`.table`::
+about the text if we use :func:`_expression.column` and :func:`.table`::
from sqlalchemy import select, text, column, table
stmt = select([column("a"), column("b")]).\
where(text("a = b")).select_from(table("sometable"))
-Where note also that :func:`.table` and :func:`.column` can now
+Where note also that :func:`.table` and :func:`_expression.column` can now
be imported from "sqlalchemy" without the "sql" part.
-The behavior here applies to :func:`~.sql.expression.select` as well as to key methods
-on :class:`.Query`, including :meth:`.Query.filter`,
-:meth:`.Query.from_statement` and :meth:`.Query.having`.
+The behavior here applies to :func:`_expression.select` as well as to key methods
+on :class:`_query.Query`, including :meth:`_query.Query.filter`,
+:meth:`_query.Query.from_statement` and :meth:`_query.Query.having`.
ORDER BY and GROUP BY are special cases
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
There is one case where usage of a string has special meaning, and as part
of this change we have enhanced its functionality. When we have a
-:func:`~.sql.expression.select` or :class:`.Query` that refers to some column name or named
+:func:`_expression.select` or :class:`_query.Query` that refers to some column name or named
label, we might want to GROUP BY and/or ORDER BY known columns or labels::
stmt = select([
PostgreSQL syntax).
We can still specify any arbitrary expression for ORDER BY or others using
-:func:`.text`::
+:func:`_expression.text`::
stmt = select([users]).order_by(text("some special expression"))
The upshot of the whole change is that SQLAlchemy now would like us
to tell it when a string is sent that this string is explicitly
-a :func:`.text` construct, or a column, table, etc., and if we use it as a
+a :func:`_expression.text` construct, or a column, table, etc., and if we use it as a
label name in an order by, group by, or other expression, SQLAlchemy expects
that the string resolves to something known, else it should again
-be qualified with :func:`.text` or similar.
+be qualified with :func:`_expression.text` or similar.
:ticket:`2992`
--------------------------------------------------------------------------------------
Support for Python-side column defaults when using the multi-valued
-version of :meth:`.Insert.values` were essentially not implemented, and
+version of :meth:`_expression.Insert.values` were essentially not implemented, and
would only work "by accident" in specific situations, when the dialect in
use was using a non-positional (e.g. named) style of bound parameter, and
when it was not necessary that a Python-side callable be invoked for each
The INSERT...FROM SELECT construct now implies ``inline=True``
--------------------------------------------------------------
-Using :meth:`.Insert.from_select` now implies ``inline=True``
-on :func:`~.sql.expression.insert`. This helps to fix a bug where an
+Using :meth:`_expression.Insert.from_select` now implies ``inline=True``
+on :func:`_expression.insert`. This helps to fix a bug where an
INSERT...FROM SELECT construct would inadvertently be compiled
as "implicit returning" on supporting backends, which would
cause breakage in the case of an INSERT that inserts zero rows
may prefer ``inline=True`` with INSERT..FROM SELECT as some databases
don't support returning and therefore can't do "implicit" returning,
but there's no reason an INSERT...FROM SELECT needs implicit returning
-in any case. Regular explicit :meth:`.Insert.returning` should
+in any case. Regular explicit :meth:`_expression.Insert.returning` should
be used to return variable numbers of result rows if inserted
data is needed.
``autoload_with`` now implies ``autoload=True``
-----------------------------------------------
-A :class:`.Table` can be set up for reflection by passing
-:paramref:`.Table.autoload_with` alone::
+A :class:`_schema.Table` can be set up for reflection by passing
+:paramref:`_schema.Table.autoload_with` alone::
my_table = Table('my_table', metadata, autoload_with=some_engine)
--------------------------------------------------------------
SQLAlchemy's wrapping of DBAPI exceptions was not taking place in the
-case where a :class:`.Connection` object was invalidated, and then tried
+case where a :class:`_engine.Connection` object was invalidated, and then tried
to reconnect and encountered an error; this has been resolved.
Additionally, the recently added :meth:`.ConnectionEvents.handle_error`
function via :paramref:`.create_engine.creator`.
The :class:`.ExceptionContext` object has a new datamember
-:attr:`.ExceptionContext.engine` that will always refer to the :class:`.Engine`
-in use, in those cases when the :class:`.Connection` object is not available
+:attr:`.ExceptionContext.engine` that will always refer to the :class:`_engine.Engine`
+in use, in those cases when the :class:`_engine.Connection` object is not available
(e.g. on initial connect).
ForeignKeyConstraint.columns is now a ColumnCollection
------------------------------------------------------
-:attr:`.ForeignKeyConstraint.columns` was previously a plain list
-containing either strings or :class:`.Column` objects, depending on
-how the :class:`.ForeignKeyConstraint` was constructed and whether it was
-associated with a table. The collection is now a :class:`.ColumnCollection`,
-and is only initialized after the :class:`.ForeignKeyConstraint` is
-associated with a :class:`.Table`. A new accessor
-:attr:`.ForeignKeyConstraint.column_keys`
+:attr:`_schema.ForeignKeyConstraint.columns` was previously a plain list
+containing either strings or :class:`_schema.Column` objects, depending on
+how the :class:`_schema.ForeignKeyConstraint` was constructed and whether it was
+associated with a table. The collection is now a :class:`_expression.ColumnCollection`,
+and is only initialized after the :class:`_schema.ForeignKeyConstraint` is
+associated with a :class:`_schema.Table`. A new accessor
+:attr:`_schema.ForeignKeyConstraint.column_keys`
is added to unconditionally return string keys for the local set of
columns regardless of how the object was constructed or its current
state.
MetaData.sorted_tables accessor is "deterministic"
--------------------------------------------------
-The sorting of tables resulting from the :attr:`.MetaData.sorted_tables`
+The sorting of tables resulting from the :attr:`_schema.MetaData.sorted_tables`
accessor is "deterministic"; the ordering should be the same in all cases
regardless of Python hashing. This is done by first sorting the tables
by name before passing them to the topological algorithm, which maintains
that ordering as it iterates.
Note that this change does **not** yet apply to the ordering applied
-when emitting :meth:`.MetaData.create_all` or :meth:`.MetaData.drop_all`.
+when emitting :meth:`_schema.MetaData.create_all` or :meth:`_schema.MetaData.drop_all`.
:ticket:`3084`
SQLite/Oracle have distinct methods for temporary table/view name reporting
---------------------------------------------------------------------------
-The :meth:`.Inspector.get_table_names` and :meth:`.Inspector.get_view_names`
+The :meth:`_reflection.Inspector.get_table_names` and :meth:`_reflection.Inspector.get_view_names`
methods in the case of SQLite/Oracle would also return the names of temporary
tables and views, which is not provided by any other dialect (in the case
of MySQL at least it is not even possible). This logic has been moved
-out to two new methods :meth:`.Inspector.get_temp_table_names` and
-:meth:`.Inspector.get_temp_view_names`.
+out to two new methods :meth:`_reflection.Inspector.get_temp_table_names` and
+:meth:`_reflection.Inspector.get_temp_view_names`.
Note that reflection of a specific named temporary table or temporary view,
either by ``Table('name', autoload=True)`` or via methods like
-:meth:`.Inspector.get_columns` continues to function for most if not all
+:meth:`_reflection.Inspector.get_columns` continues to function for most if not all
dialects. For SQLite specifically, there is a bug fix for UNIQUE constraint
reflection from temp tables as well, which is :ticket:`3203`.
Overhaul of ENUM type create/drop rules
---------------------------------------
-The rules for PostgreSQL :class:`.postgresql.ENUM` have been made more strict
+The rules for PostgreSQL :class:`_postgresql.ENUM` have been made more strict
with regards to creating and dropping of the TYPE.
-An :class:`.postgresql.ENUM` that is created **without** being explicitly
-associated with a :class:`.MetaData` object will be created *and* dropped
-corresponding to :meth:`.Table.create` and :meth:`.Table.drop`::
+An :class:`_postgresql.ENUM` that is created **without** being explicitly
+associated with a :class:`_schema.MetaData` object will be created *and* dropped
+corresponding to :meth:`_schema.Table.create` and :meth:`_schema.Table.drop`::
table = Table('sometable', metadata,
Column('some_enum', ENUM('a', 'b', 'c', name='myenum'))
of a common shared enumerated type, the behavior of a metadata-associated
enumeration has been enhanced.
-An :class:`.postgresql.ENUM` that is created **with** being explicitly
-associated with a :class:`.MetaData` object will *not* be created *or* dropped
-corresponding to :meth:`.Table.create` and :meth:`.Table.drop`, with
-the exception of :meth:`.Table.create` called with the ``checkfirst=True``
+An :class:`_postgresql.ENUM` that is created **with** being explicitly
+associated with a :class:`_schema.MetaData` object will *not* be created *or* dropped
+corresponding to :meth:`_schema.Table.create` and :meth:`_schema.Table.drop`, with
+the exception of :meth:`_schema.Table.create` called with the ``checkfirst=True``
flag::
my_enum = ENUM('a', 'b', 'c', name='myenum', metadata=metadata)
Added support for PG table options TABLESPACE, ON COMMIT,
WITH(OUT) OIDS, and INHERITS, when rendering DDL via
-the :class:`.Table` construct.
+the :class:`_schema.Table` construct.
.. seealso::
New get_enums() method with PostgreSQL Dialect
----------------------------------------------
-The :func:`.inspect` method returns a :class:`.PGInspector` object in the
+The :func:`_sa.inspect` method returns a :class:`.PGInspector` object in the
case of PostgreSQL, which includes a new :meth:`.PGInspector.get_enums`
method that returns information on all available ``ENUM`` types::
* the :class:`Table` construct with ``autoload=True`` will now match a name
that exists in the database as a materialized view or foreign table.
-* :meth:`.Inspector.get_view_names` will return plain and materialized view
+* :meth:`_reflection.Inspector.get_view_names` will return plain and materialized view
names.
-* :meth:`.Inspector.get_table_names` does **not** change for PostgreSQL, it
+* :meth:`_reflection.Inspector.get_table_names` does **not** change for PostgreSQL, it
continues to return only the names of plain tables.
* A new method :meth:`.PGInspector.get_foreign_table_names` is added which
SQL Server 2012 large text / binary types render as VARCHAR, NVARCHAR, VARBINARY
--------------------------------------------------------------------------------
-The rendering of the :class:`.Text`, :class:`.UnicodeText`, and :class:`.LargeBinary`
+The rendering of the :class:`_expression.TextClause`, :class:`.UnicodeText`, and :class:`.LargeBinary`
types has been changed for SQL Server 2012 and greater, with options
to control the behavior completely, based on deprecation guidelines from
Microsoft. See :ref:`mssql_large_type_deprecation` for details.
-----------------------------------
CTE support has been fixed up for Oracle, and there is also a new feature
-:meth:`.CTE.with_suffixes` that can assist with Oracle's special directives::
+:meth:`_expression.CTE.with_suffixes` that can assist with Oracle's special directives::
included_parts = select([
part.c.sub_part, part.c.part, part.c.quantity
Changes regarding "unhashable" types, impacts deduping of ORM rows
------------------------------------------------------------------
-The :class:`.Query` object has a well-known behavior of "deduping"
+The :class:`_query.Query` object has a well-known behavior of "deduping"
returned rows that contain at least one ORM-mapped entity (e.g., a
full mapped object, as opposed to individual column values). The
primary purpose of this is so that the handling of entities works
This deduplication relies upon the hashability of the elements within
the row. With the introduction of PostgreSQL's special types like
-:class:`.postgresql.ARRAY`, :class:`.postgresql.HSTORE` and
-:class:`.postgresql.JSON`, the experience of types within rows being
+:class:`_postgresql.ARRAY`, :class:`_postgresql.HSTORE` and
+:class:`_postgresql.JSON`, the experience of types within rows being
unhashable and encountering problems here is more prevalent than
it was previously.
The typing system now has specific checks for passing of SQLAlchemy
"inspectable" objects in contexts where they would otherwise be handled as
literal values. Any SQLAlchemy built-in object that is legal to pass as a
-SQL value (which is not already a :class:`.ClauseElement` instance)
+SQL value (which is not already a :class:`_expression.ClauseElement` instance)
includes a method ``__clause_element__()`` which provides a
valid SQL expression for that object. For SQLAlchemy objects that
don't provide this, such as mapped classes, mappers, and mapped
omitting the column from the INSERT statement, which has the effect of using
the column-level default. This allows a mapper-level
configuration of the existing object-level technique of assigning
-:func:`.sql.null` to the attribute.
+:func:`_expression.null` to the attribute.
.. seealso::
Further Fixes to single-table inheritance querying
--------------------------------------------------
-Continuing from 1.0's :ref:`migration_3177`, the :class:`.Query` should
+Continuing from 1.0's :ref:`migration_3177`, the :class:`_query.Query` should
no longer inappropriately add the "single inheritance" criteria when the
query is against a subquery expression such as an exists::
In recent SQLAlchemy versions, the SQL generated by many forms of
"polymorphic" queries has a more "flat" form than it used to, where
a JOIN of several tables is no longer bundled into a subquery unconditionally.
-To accommodate this, the :meth:`.Query.correlate` method now extracts the
+To accommodate this, the :meth:`_query.Query.correlate` method now extracts the
individual tables from such a polymorphic selectable and ensures that all
are part of the "correlate" for the subquery. Assuming the
``Person/Manager/Engineer->Company`` setup from the mapping documentation,
Stringify of Query will consult the Session for the correct dialect
-------------------------------------------------------------------
-Calling ``str()`` on a :class:`.Query` object will consult the :class:`.Session`
+Calling ``str()`` on a :class:`_query.Query` object will consult the :class:`.Session`
for the correct "bind" to use, in order to render the SQL that would be
-passed to the database. In particular this allows a :class:`.Query` that
+passed to the database. In particular this allows a :class:`_query.Query` that
refers to dialect-specific SQL constructs to be renderable, assuming the
-:class:`.Query` is associated with an appropriate :class:`.Session`.
-Previously, this behavior would only take effect if the :class:`.MetaData`
+:class:`_query.Query` is associated with an appropriate :class:`.Session`.
+Previously, this behavior would only take effect if the :class:`_schema.MetaData`
to which the mappings were associated were itself bound to the target
-:class:`.Engine`.
+:class:`_engine.Engine`.
-If neither the underlying :class:`.MetaData` nor the :class:`.Session` are
-associated with any bound :class:`.Engine`, then the fallback to the
+If neither the underlying :class:`_schema.MetaData` nor the :class:`.Session` are
+associated with any bound :class:`_engine.Engine`, then the fallback to the
"default" dialect is used to generate the SQL string.
.. seealso::
To assist with the use case of preventing unwanted lazy loads from occurring
after a series of objects are loaded, the new "lazy='raise'" and
"lazy='raise_on_sql'" strategies and
-corresponding loader option :func:`.orm.raiseload` may be applied to a
+corresponding loader option :func:`_orm.raiseload` may be applied to a
relationship attribute which will cause it to raise ``InvalidRequestError``
when a non-eagerly-loaded attribute is accessed for read. The two variants
test for either a lazy load of any variety, including those that would
-----------------------------
This old parameter from the very first versions of SQLAlchemy was part of
-the original design of the ORM which featured the :class:`.Mapper` object
+the original design of the ORM which featured the :class:`_orm.Mapper` object
as a public-facing query structure. This role has long since been replaced
-by the :class:`.Query` object, where we use :meth:`.Query.order_by` to
+by the :class:`_query.Query` object, where we use :meth:`_query.Query.order_by` to
indicate the ordering of results in a way that works consistently for any
combination of SELECT statements, entities and SQL expressions. There are
-many areas in which :paramref:`.Mapper.order_by` doesn't work as expected
+many areas in which :paramref:`_orm.Mapper.order_by` doesn't work as expected
(or what would be expected is not clear), such as when queries are combined
into unions; these cases are not supported.
identifiable base for system-level exceptions such as ``KeyboardInterrupt``,
``SystemExit``, and notably the ``GreenletExit`` exception that's used by
eventlet and gevent. This exception class is now intercepted by the exception-
-handling routines of :class:`.Connection`, and includes handling by the
-:meth:`~.ConnectionEvents.handle_error` event. The :class:`.Connection` is now
+handling routines of :class:`_engine.Connection`, and includes handling by the
+:meth:`~.ConnectionEvents.handle_error` event. The :class:`_engine.Connection` is now
**invalidated** by default in the case of a system level exception that is not
a subclass of ``Exception``, as it is assumed an operation was interrupted and
the connection may be in an unusable state. The MySQL drivers are most
targeted by this change however the change is across all DBAPIs.
Note that upon invalidation, the immediate DBAPI connection used by
-:class:`.Connection` is disposed, and the :class:`.Connection`, if still
+:class:`_engine.Connection` is disposed, and the :class:`_engine.Connection`, if still
being used subsequent to the exception raise, will use a new
DBAPI connection for subsequent operations upon next use; however, the state of
any transaction in progress is lost and the appropriate ``.rollback()`` method
The LATERAL keyword is currently known to only be supported by PostgreSQL 9.3
and greater, however as it is part of the SQL standard support for this keyword
-is added to Core. The implementation of :meth:`.Select.lateral` employs
+is added to Core. The implementation of :meth:`_expression.Select.lateral` employs
special logic beyond just rendering the LATERAL keyword to allow for
correlation of tables that are derived from the same FROM clause as the
selectable, e.g. lateral correlation::
:ref:`lateral_selects`
- :class:`.Lateral`
+ :class:`_expression.Lateral`
- :meth:`.Select.lateral`
+ :meth:`_expression.Select.lateral`
:ticket:`2857`
-----------------------
The SQL standard TABLESAMPLE can be rendered using the
-:meth:`.FromClause.tablesample` method, which returns a :class:`.TableSample`
+:meth:`_expression.FromClause.tablesample` method, which returns a :class:`_expression.TableSample`
construct similar to an alias::
from sqlalchemy import func
database provides in order to indicate an auto-incrementing integer identifier,
such as the SERIAL keyword on PostgreSQL or AUTO_INCREMENT on MySQL, and additionally
that the dialect will receive these generated values from the execution
-of a :meth:`.Table.insert` construct using techniques appropriate to that
+of a :meth:`_schema.Table.insert` construct using techniques appropriate to that
backend.
What's changed is that this feature no longer turns on automatically for a
)
In order to anticipate some potential backwards-incompatible scenarios,
-the :meth:`.Table.insert` construct will perform more thorough checks
+the :meth:`_schema.Table.insert` construct will perform more thorough checks
for missing primary key values on composite primary key columns that don't
have autoincrement set up; given a table such as::
on Python overhead as well as much greater accuracy in linking ORM and Core
SQL expressions to result rows. In 1.1, this reorganization has been taken
further internally, and also has been made available to pure-text SQL
-constructs via the use of the recently added :meth:`.TextClause.columns` method.
+constructs via the use of the recently added :meth:`_expression.TextClause.columns` method.
TextAsFrom.columns() now works positionally
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-The :meth:`.TextClause.columns` method, added in 0.9, accepts column-based arguments
+The :meth:`_expression.TextClause.columns` method, added in 0.9, accepts column-based arguments
positionally; in 1.1, when all columns are passed positionally, the correlation
of these columns to the ultimate result set is also performed positionally.
The key advantage here is that textual SQL can now be linked to an ORM-
level result set without the need to deal with ambiguous or duplicate column
names, or with having to match labeling schemes to ORM-level labeling schemes. All
that's needed now is the same ordering of columns within the textual SQL
-and the column arguments passed to :meth:`.TextClause.columns`::
+and the column arguments passed to :meth:`_expression.TextClause.columns`::
from sqlalchemy import text
normally be ambiguous. Using the new feature, we can apply the mapped
columns from the ``User`` and ``Address`` class directly, even linking
the ``Address.user_id`` column to the ``users.id`` column in textual SQL
-for fun, and the :class:`.Query` object will receive rows that are correctly
+for fun, and the :class:`_query.Query` object will receive rows that are correctly
targetable as needed, including for an eager load.
This change is **backwards incompatible** with code that passes the columns
:ref:`change_3547`
- :class:`.types.JSON`
+ :class:`_types.JSON`
- :class:`.postgresql.JSON`
+ :class:`_postgresql.JSON`
:class:`.mysql.JSON`
JSON "null" is inserted as expected with ORM operations, omitted when not present
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-The :class:`.types.JSON` type and its descendant types :class:`.postgresql.JSON`
+The :class:`_types.JSON` type and its descendant types :class:`_postgresql.JSON`
and :class:`.mysql.JSON` have a flag :paramref:`.types.JSON.none_as_null` which
when set to True indicates that the Python value ``None`` should translate
into a SQL NULL rather than a JSON NULL value. This flag defaults to False,
MyObject,
[{"json_value": None}])
-The :class:`.types.JSON` type now implements the
+The :class:`_types.JSON` type now implements the
:attr:`.TypeEngine.should_evaluate_none` flag,
indicating that ``None`` should not be ignored here; it is configured
automatically based on the value of :paramref:`.types.JSON.none_as_null`.
Thanks to :ticket:`3061`, we can differentiate when the value ``None`` is actively
set by the user versus when it was never set at all.
-The feature applies as well to the new base :class:`.types.JSON` type
+The feature applies as well to the new base :class:`_types.JSON` type
and its descendant types.
:ticket:`3514`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
To ensure that an application can always have full control at the value level
-of whether a :class:`.types.JSON`, :class:`.postgresql.JSON`, :class:`.mysql.JSON`,
-or :class:`.postgresql.JSONB` column
+of whether a :class:`_types.JSON`, :class:`_postgresql.JSON`, :class:`.mysql.JSON`,
+or :class:`_postgresql.JSONB` column
should receive a SQL NULL or JSON ``"null"`` value, the constant
:attr:`.types.JSON.NULL` has been added, which in conjunction with
:func:`.null` can be used to determine fully between SQL NULL and
session.add_all([obj1, obj2])
session.commit()
-The feature applies as well to the new base :class:`.types.JSON` type
+The feature applies as well to the new base :class:`_types.JSON` type
and its descendant types.
:ticket:`3514`
Array support added to Core; new ANY and ALL operators
------------------------------------------------------
-Along with the enhancements made to the PostgreSQL :class:`.postgresql.ARRAY`
-type described in :ref:`change_3503`, the base class of :class:`.postgresql.ARRAY`
-itself has been moved to Core in a new class :class:`.types.ARRAY`.
+Along with the enhancements made to the PostgreSQL :class:`_postgresql.ARRAY`
+type described in :ref:`change_3503`, the base class of :class:`_postgresql.ARRAY`
+itself has been moved to Core in a new class :class:`_types.ARRAY`.
Arrays are part of the SQL standard, as are several array-oriented functions
such as ``array_agg()`` and ``unnest()``. In support of these constructs
for not just PostgreSQL but also potentially for other array-capable backends
in the future such as DB2, the majority of array logic for SQL expressions
-is now in Core. The :class:`.types.ARRAY` type still **only works on
+is now in Core. The :class:`_types.ARRAY` type still **only works on
PostgreSQL**, however it can be used directly, supporting special array
use cases such as indexed access, as well as support for the ANY and ALL::
expr = mytable.c.data[5].any(12)
-In support of ANY and ALL, the :class:`.types.ARRAY` type retains the same
+In support of ANY and ALL, the :class:`_types.ARRAY` type retains the same
:meth:`.types.ARRAY.Comparator.any` and :meth:`.types.ARRAY.Comparator.all` methods
from the PostgreSQL type, but also exports these operations to new
-standalone operator functions :func:`.sql.expression.any_` and
-:func:`.sql.expression.all_`. These two functions work in more
+standalone operator functions :func:`_expression.any_` and
+:func:`_expression.all_`. These two functions work in more
of the traditional SQL way, allowing a right-side expression form such
as::
select([mytable]).where(12 == any_(mytable.c.data[5]))
For the PostgreSQL-specific operators "contains", "contained_by", and
-"overlaps", one should continue to use the :class:`.postgresql.ARRAY`
-type directly, which provides all functionality of the :class:`.types.ARRAY`
+"overlaps", one should continue to use the :class:`_postgresql.ARRAY`
+type directly, which provides all functionality of the :class:`_types.ARRAY`
type as well.
-The :func:`.sql.expression.any_` and :func:`.sql.expression.all_` operators
+The :func:`_expression.any_` and :func:`_expression.all_` operators
are open-ended at the Core level, however their interpretation by backend
databases is limited. On the PostgreSQL backend, the two operators
**only accept array values**. Whereas on the MySQL backend, they
New Function features, "WITHIN GROUP", array_agg and set aggregate functions
----------------------------------------------------------------------------
-With the new :class:`.types.ARRAY` type we can also implement a pre-typed
+With the new :class:`_types.ARRAY` type we can also implement a pre-typed
function for the ``array_agg()`` SQL function that returns an array,
-which is now available using :class:`.array_agg`::
+which is now available using :class:`_functions.array_agg`::
from sqlalchemy import func
stmt = select([func.array_agg(table.c.value)])
A PostgreSQL element for an aggregate ORDER BY is also added via
-:class:`.postgresql.aggregate_order_by`::
+:class:`_postgresql.aggregate_order_by`::
from sqlalchemy.dialects.postgresql import aggregate_order_by
expr = func.array_agg(aggregate_order_by(table.c.a, table.c.b.desc()))
SELECT array_agg(table1.a ORDER BY table1.b DESC) AS array_agg_1 FROM table1
-The PG dialect itself also provides an :func:`.postgresql.array_agg` wrapper to
-ensure the :class:`.postgresql.ARRAY` type::
+The PG dialect itself also provides an :func:`_postgresql.array_agg` wrapper to
+ensure the :class:`_postgresql.ARRAY` type::
from sqlalchemy.dialects.postgresql import array_agg
stmt = select([array_agg(table.c.value).contains('foo')])
type, also generate either a CHECK constraint or in the case of PostgreSQL
ENUM a new CREATE TYPE statement, will now work automatically with
:class:`.TypeDecorator` recipes. Previously, a :class:`.TypeDecorator` for
-an :class:`.postgresql.ENUM` had to look like this::
+an :class:`_postgresql.ENUM` had to look like this::
# old way
class MyEnum(TypeDecorator, SchemaType):
--------------------------------------------------
To support the use case of an application that uses the same set of
-:class:`.Table` objects in many schemas, such as schema-per-user, a new
+:class:`_schema.Table` objects in many schemas, such as schema-per-user, a new
execution option :paramref:`.Connection.execution_options.schema_translate_map`
-is added. Using this mapping, a set of :class:`.Table`
+is added. Using this mapping, a set of :class:`_schema.Table`
objects can be made on a per-connection basis to refer to any set of schemas
-instead of the :paramref:`.Table.schema` to which they were assigned. The
+instead of the :paramref:`_schema.Table.schema` to which they were assigned. The
translation works for DDL and SQL generation, as well as with the ORM.
For example, if the ``User`` class were assigned the schema "per_user"::
The type_coerce function is now a persistent SQL element
--------------------------------------------------------
-The :func:`.expression.type_coerce` function previously would return
+The :func:`_expression.type_coerce` function previously would return
an object either of type :class:`.BindParameter` or :class:`.Label`, depending
on the input. An effect this would have was that in the case where expression
transformations were used, such as the conversion of an element from a
-:class:`.Column` to a :class:`.BindParameter` that's critical to ORM-level
+:class:`_schema.Column` to a :class:`.BindParameter` that's critical to ORM-level
lazy loading, the type coercion information would not be used since it would
have been lost already.
id = Column('id', Integer, primary_key=True)
person_id = Column('person_id', Integer)
-Above, in the :paramref:`.relationship.primaryjoin` expression, we are
+Above, in the :paramref:`_orm.relationship.primaryjoin` expression, we are
using :func:`.type_coerce` to handle bound parameters passed via
lazyloading as integers, since we already know these will come from
our ``StringAsInt`` type which maintains the value as an integer in
Python. We are then using :func:`.cast` so that as a SQL expression,
the VARCHAR "id" column will be CAST to an integer for a regular non-
-converted join as with :meth:`.Query.join` or :func:`.orm.joinedload`.
+converted join as with :meth:`_query.Query.join` or :func:`_orm.joinedload`.
That is, a joinedload of ``.pets`` looks like::
SELECT person.id AS person_id, pets_1.id AS pets_1_id,
JSON Columns will not insert JSON NULL if no value is supplied and no default is established
--------------------------------------------------------------------------------------------
-As detailed in :ref:`change_3514`, :class:`.types.JSON` will not render
+As detailed in :ref:`change_3514`, :class:`_types.JSON` will not render
a JSON "null" value if the value is missing entirely. To prevent SQL NULL,
a default should be set up. Given the following mapping::
Note that setting ``None`` for the default is the same as omitting it entirely;
the :paramref:`.types.JSON.none_as_null` flag does not impact the value of ``None``
-passed to :paramref:`.Column.default` or :paramref:`.Column.server_default`::
+passed to :paramref:`_schema.Column.default` or :paramref:`_schema.Column.server_default`::
# default=None is the same as omitting it entirely, does not apply JSON NULL
json_value = Column(JSON(none_as_null=False), nullable=False, default=None)
result in any case, but the columns are unnecessary.
Additionally, when the PostgreSQL DISTINCT ON format is used by passing
-expressions to :meth:`.Query.distinct`, the above "column adding" logic
+expressions to :meth:`_query.Query.distinct`, the above "column adding" logic
is disabled entirely.
When the query is being bundled into a subquery for the purposes of
Same-named @validates decorators will now raise an exception
------------------------------------------------------------
-The :func:`.orm.validates` decorator is only intended to be created once
+The :func:`_orm.validates` decorator is only intended to be created once
per class for a particular attribute name. Creating more than one
now raises an error, whereas previously it would silently pick only the
last defined validator::
TextClause.columns() will match columns positionally, not by name, when passed positionally
-------------------------------------------------------------------------------------------
-The new behavior of the :meth:`.TextClause.columns` method, which itself
+The new behavior of the :meth:`_expression.TextClause.columns` method, which itself
was recently added as of the 0.9 series, is that when
columns are passed positionally without any additional keyword arguments,
they are linked to the ultimate result set
textual SQL statement, as would seem intuitive, even though the internals
weren't checking for this.
-An application that is using this method by passing :class:`.Column` objects
-to it positionally must ensure that the position of those :class:`.Column`
+An application that is using this method by passing :class:`_schema.Column` objects
+to it positionally must ensure that the position of those :class:`_schema.Column`
objects matches the position in which these columns are stated in the
textual SQL.
is now slightly risky, as the "*" specification will generally deliver columns
in the order in which they are present in the table itself. If the structure
of the table changes due to schema changes, this ordering may no longer be the same.
-Therefore when using :meth:`.TextClause.columns`, it's advised to list out
+Therefore when using :meth:`_expression.TextClause.columns`, it's advised to list out
the desired columns explicitly in the textual SQL, though it's no longer
necessary to worry about the names themselves in the textual SQL.
String server_default now literal quoted
----------------------------------------
-A server default passed to :paramref:`.Column.server_default` as a plain
+A server default passed to :paramref:`_schema.Column.server_default` as a plain
Python string that has quotes embedded is now
passed through the literal quoting system::
The ``ON CONFLICT`` clause of ``INSERT`` added to PostgreSQL as of
version 9.5 is now supported using a PostgreSQL-specific version of the
-:class:`~.sql.expression.Insert` object, via :func:`sqlalchemy.dialects.postgresql.dml.insert`.
-This :class:`~.sql.expression.Insert` subclass adds two new methods :meth:`.Insert.on_conflict_do_update`
-and :meth:`.Insert.on_conflict_do_nothing` which implement the full syntax
+:class:`_expression.Insert` object, via :func:`sqlalchemy.dialects.postgresql.dml.insert`.
+This :class:`_expression.Insert` subclass adds two new methods :meth:`_expression.Insert.on_conflict_do_update`
+and :meth:`_expression.Insert.on_conflict_do_nothing` which implement the full syntax
supported by PostgreSQL 9.5 in this area::
from sqlalchemy.dialects.postgresql import insert
produce a hash function for column values when a query's selected entities
mixes full ORM entities with column expressions. The ``hashable=False``
flag is now correctly set on all of PG's "data structure" types, including
-:class:`.postgresql.ARRAY` and :class:`.postgresql.JSON`.
-The :class:`.JSONB` and :class:`.HSTORE`
-types already included this flag. For :class:`.postgresql.ARRAY`,
+:class:`_postgresql.ARRAY` and :class:`_postgresql.JSON`.
+The :class:`_postgresql.JSONB` and :class:`.HSTORE`
+types already included this flag. For :class:`_postgresql.ARRAY`,
this is conditional based on the :paramref:`.postgresql.ARRAY.as_tuple`
flag, however it should no longer be necessary to set this flag
in order to have an array value present in a composed ORM row.
Correct SQL Types are Established from Indexed Access of ARRAY, JSON, HSTORE
----------------------------------------------------------------------------
-For all three of :class:`~.postgresql.ARRAY`, :class:`~.postgresql.JSON` and :class:`.HSTORE`,
+For all three of :class:`_postgresql.ARRAY`, :class:`_postgresql.JSON` and :class:`.HSTORE`,
the SQL type assigned to the expression returned by indexed access, e.g.
``col[someindex]``, should be correct in all cases.
This includes:
-* The SQL type assigned to indexed access of an :class:`~.postgresql.ARRAY` takes into
- account the number of dimensions configured. An :class:`~.postgresql.ARRAY` with three
- dimensions will return a SQL expression with a type of :class:`~.postgresql.ARRAY` of
+* The SQL type assigned to indexed access of an :class:`_postgresql.ARRAY` takes into
+ account the number of dimensions configured. An :class:`_postgresql.ARRAY` with three
+ dimensions will return a SQL expression with a type of :class:`_postgresql.ARRAY` of
one less dimension. Given a column with type ``ARRAY(Integer, dimensions=3)``,
we can now perform this expression::
type :class:`.Integer` where we could no longer perform indexed access
for the remaining dimensions, unless we used :func:`.cast` or :func:`.type_coerce`.
-* The :class:`~.postgresql.JSON` and :class:`~.postgresql.JSONB` types now mirror what PostgreSQL
+* The :class:`_postgresql.JSON` and :class:`_postgresql.JSONB` types now mirror what PostgreSQL
itself does for indexed access. This means that all indexed access for
- a :class:`~.postgresql.JSON` or :class:`~.postgresql.JSONB` type returns an expression that itself
- is *always* :class:`~.postgresql.JSON` or :class:`~.postgresql.JSONB` itself, unless the
+ a :class:`_postgresql.JSON` or :class:`_postgresql.JSONB` type returns an expression that itself
+ is *always* :class:`_postgresql.JSON` or :class:`_postgresql.JSONB` itself, unless the
:attr:`~.postgresql.JSON.Comparator.astext` modifier is used. This means that whether
the indexed access of the JSON structure ultimately refers to a string,
list, number, or other JSON structure, PostgreSQL always considers it
to be JSON itself unless it is explicitly cast differently. Like
- the :class:`~.postgresql.ARRAY` type, this means that it is now straightforward
+ the :class:`_postgresql.ARRAY` type, this means that it is now straightforward
to produce JSON expressions with multiple levels of indexed access::
json_expr = json_col['key1']['attr1'][5]
* The "textual" type that is returned by indexed access of :class:`.HSTORE`
as well as the "textual" type that is returned by indexed access of
- :class:`~.postgresql.JSON` and :class:`~.postgresql.JSONB` in conjunction with the
+ :class:`_postgresql.JSON` and :class:`_postgresql.JSONB` in conjunction with the
:attr:`~.postgresql.JSON.Comparator.astext` modifier is now configurable; it defaults
- to :class:`.Text` in both cases but can be set to a user-defined
+ to :class:`_expression.TextClause` in both cases but can be set to a user-defined
type using the :paramref:`.postgresql.JSON.astext_type` or
:paramref:`.postgresql.HSTORE.text_type` parameters.
-----------------------------------------------------------------------
As part of the changes in :ref:`change_3503`, the workings of the
-:meth:`.ColumnElement.cast` operator on :class:`.postgresql.JSON` and
-:class:`.postgresql.JSONB` no longer implicitly invoke the
+:meth:`_expression.ColumnElement.cast` operator on :class:`_postgresql.JSON` and
+:class:`_postgresql.JSONB` no longer implicitly invoke the
:attr:`.postgresql.JSON.Comparator.astext` modifier; PostgreSQL's JSON/JSONB types
support CAST operations to each other without the "astext" aspect.
-----------------------------
The PostgreSQL dialect now supports reflection of CHECK constraints
-both within the method :meth:`.Inspector.get_check_constraints` as well
-as within :class:`.Table` reflection within the :attr:`.Table.constraints`
+both within the method :meth:`_reflection.Inspector.get_check_constraints` as well
+as within :class:`_schema.Table` reflection within the :attr:`_schema.Table.constraints`
collection.
"Plain" and "Materialized" views can be inspected separately
The :class:`.Index` object now accepts the argument ``postgresql_tablespace``
in order to specify TABLESPACE, the same way as accepted by the
-:class:`.Table` object.
+:class:`_schema.Table` object.
.. seealso::
the JSON type newly added to MySQL 5.7. This type provides both persistence
of JSON as well as rudimentary indexed-access using the ``JSON_EXTRACT``
function internally. An indexable JSON column that works across MySQL
-and PostgreSQL can be achieved by using the :class:`.types.JSON` datatype
+and PostgreSQL can be achieved by using the :class:`_types.JSON` datatype
common to both MySQL and PostgreSQL.
.. seealso::
Along with the change :ref:`change_3216`, composite primary keys with
or without auto increment are now easier to specify;
-:paramref:`.Column.autoincrement`
+:paramref:`_schema.Column.autoincrement`
now defaults to the value ``"auto"`` and the ``autoincrement=False``
directives are no longer needed::
Improved Support for Remote Schemas
-----------------------------------
-The SQLite dialect now implements :meth:`.Inspector.get_schema_names`
+The SQLite dialect now implements :meth:`_reflection.Inspector.get_schema_names`
and additionally has improved support for tables and indexes that are
created and reflected from a remote schema, which in SQLite is a
database that is assigned a name via the ``ATTACH`` statement; previously,
the``CREATE INDEX`` DDL didn't work correctly for a schema-bound table
-and the :meth:`.Inspector.get_foreign_keys` method will now indicate the
+and the :meth:`_reflection.Inspector.get_foreign_keys` method will now indicate the
given schema in the results. Cross-schema foreign keys aren't supported.
.. _change_3629:
-----------------------------
The SQLite dialect now supports reflection of CHECK constraints
-both within the method :meth:`.Inspector.get_check_constraints` as well
-as within :class:`.Table` reflection within the :attr:`.Table.constraints`
+both within the method :meth:`_reflection.Inspector.get_check_constraints` as well
+as within :class:`_schema.Table` reflection within the :attr:`_schema.Table.constraints`
collection.
ON DELETE and ON UPDATE foreign key phrases now reflect
-------------------------------------------------------
-The :class:`.Inspector` will now include ON DELETE and ON UPDATE
+The :class:`_reflection.Inspector` will now include ON DELETE and ON UPDATE
phrases from foreign key constraints on the SQLite dialect, and the
-:class:`.ForeignKeyConstraint` object as reflected as part of a
-:class:`.Table` will also indicate these phrases.
+:class:`_schema.ForeignKeyConstraint` object as reflected as part of a
+:class:`_schema.Table` will also indicate these phrases.
Dialect Improvements and Changes - SQL Server
=============================================
String / varlength types no longer represent "max" explicitly on reflection
---------------------------------------------------------------------------
-When reflecting a type such as :class:`.String`, :class:`.Text`, etc.
+When reflecting a type such as :class:`.String`, :class:`_expression.TextClause`, etc.
which includes a length, an "un-lengthed" type under SQL Server would
copy the "length" parameter as the value ``"max"``::
The :mod:`sqlalchemy.ext.baked` extension, first introduced in the 1.0 series,
allows for the construction of a so-called :class:`.BakedQuery` object,
-which is an object that generates a :class:`.Query` object in conjunction
+which is an object that generates a :class:`_query.Query` object in conjunction
with a cache key representing the structure of the query; this cache key
is then linked to the resulting string SQL statement so that subsequent use
of another :class:`.BakedQuery` with the same structure will bypass all the
-overhead of building the :class:`.Query` object, building the core
-:func:`~.sql.expression.select` object within, as well as the compilation of the :func:`~.sql.expression.select`
+overhead of building the :class:`_query.Query` object, building the core
+:func:`_expression.select` object within, as well as the compilation of the :func:`_expression.select`
into a string, cutting out well the majority of function call overhead normally
-associated with constructing and emitting an ORM :class:`.Query` object.
+associated with constructing and emitting an ORM :class:`_query.Query` object.
The :class:`.BakedQuery` is now used by default by the ORM when it generates
-a "lazy" query for the lazy load of a :func:`.relationship` construct, e.g.
+a "lazy" query for the lazy load of a :func:`_orm.relationship` construct, e.g.
that of the default ``lazy="select"`` relationship loader strategy. This
will allow for a significant reduction in function calls within the scope
of an application's use of lazy load queries to load collections and related
to the lazy load.
The caching behavior can be disabled on a per-relationship basis using the
-:paramref:`.relationship.bake_queries` flag, which is available for
+:paramref:`_orm.relationship.bake_queries` flag, which is available for
very unusual cases, such as a relationship that uses a custom
-:class:`.Query` implementation that's not compatible with caching.
+:class:`_query.Query` implementation that's not compatible with caching.
:ticket:`3954`
significantly
* Because the query only fetches for a given list of primary key identifiers,
- "selectin" loading is potentially compatible with :meth:`.Query.yield_per` to
+ "selectin" loading is potentially compatible with :meth:`_query.Query.yield_per` to
operate on chunks of a SELECT result at a time, provided that the
database driver allows for multiple, simultaneous cursors (SQLite, PostgreSQL;
**not** MySQL drivers or SQL Server ODBC drivers). Neither joined eager
- loading nor subquery eager loading are compatible with :meth:`.Query.yield_per`.
+ loading nor subquery eager loading are compatible with :meth:`_query.Query.yield_per`.
The disadvantages of selectin eager loading are potentially large SQL
queries, with large lists of IN parameters. The list of IN parameters themselves
ORM attributes that can receive ad-hoc SQL expressions
------------------------------------------------------
-A new ORM attribute type :func:`.orm.query_expression` is added which
-is similar to :func:`.orm.deferred`, except its SQL expression
-is determined at query time using a new option :func:`.orm.with_expression`;
+A new ORM attribute type :func:`_orm.query_expression` is added which
+is similar to :func:`_orm.deferred`, except its SQL expression
+is determined at query time using a new option :func:`_orm.with_expression`;
if not specified, the attribute defaults to ``None``::
from sqlalchemy.orm import query_expression
ORM Support of multiple-table deletes
-------------------------------------
-The ORM :meth:`.Query.delete` method supports multiple-table criteria
+The ORM :meth:`_query.Query.delete` method supports multiple-table criteria
for DELETE, as introduced in :ref:`change_959`. The feature works
in the same manner as multiple-table criteria for UPDATE, first
introduced in 0.8 and described at :ref:`change_orm_2365`.
Both hybrid attributes (e.g. :mod:`sqlalchemy.ext.hybrid`) as well as composite
attributes (:ref:`mapper_composite`) now support being used in the
-SET clause of an UPDATE statement when using :meth:`.Query.update`.
+SET clause of an UPDATE statement when using :meth:`_query.Query.update`.
For hybrids, simple expressions can be used directly, or the new decorator
:meth:`.hybrid_property.update_expression` can be used to break a value
------------------------------------------------
Added new argument :paramref:`.Session.refresh.with_for_update` to the
-:meth:`.Session.refresh` method. When the :meth:`.Query.with_lockmode`
-method were deprecated in favor of :meth:`.Query.with_for_update`,
+:meth:`.Session.refresh` method. When the :meth:`_query.Query.with_lockmode`
+method were deprecated in favor of :meth:`_query.Query.with_for_update`,
the :meth:`.Session.refresh` method was never updated to reflect
the new option::
The :paramref:`.Session.refresh.with_for_update` argument accepts a dictionary
of options that will be passed as the same arguments which are sent to
-:meth:`.Query.with_for_update`::
+:meth:`_query.Query.with_for_update`::
session.refresh(some_objects, with_for_update={"read": True})
-------------------------------------------------------------------
The Core receives support for string comments associated with tables
-and columns. These are specified via the :paramref:`.Table.comment` and
-:paramref:`.Column.comment` arguments::
+and columns. These are specified via the :paramref:`_schema.Table.comment` and
+:paramref:`_schema.Column.comment` arguments::
Table(
'my_table', metadata,
Above, DDL will be rendered appropriately upon table create to associate
the above comments with the table/ column within the schema. When
-the above table is autoloaded or inspected with :meth:`.Inspector.get_columns`,
+the above table is autoloaded or inspected with :meth:`_reflection.Inspector.get_columns`,
the comments are included. The table comment is also available independently
-using the :meth:`.Inspector.get_table_comment` method.
+using the :meth:`_reflection.Inspector.get_table_comment` method.
Current backend support includes MySQL, PostgreSQL, and Oracle.
Multiple-table criteria support for DELETE
------------------------------------------
-The :class:`.Delete` construct now supports multiple-table criteria,
+The :class:`_expression.Delete` construct now supports multiple-table criteria,
implemented for those backends which support it, currently these are
PostgreSQL, MySQL and Microsoft SQL Server (support is also added to the
currently non-working Sybase dialect). The feature works in the same
A default generation function, e.g. that described at
:ref:`context_default_functions`, can look at the current parameters relevant
to the statement via the :attr:`.DefaultExecutionContext.current_parameters`
-attribute. However, in the case of a :class:`~.sql.expression.Insert` construct that specifies
-multiple VALUES clauses via the :meth:`.Insert.values` method, the user-defined
+attribute. However, in the case of a :class:`_expression.Insert` construct that specifies
+multiple VALUES clauses via the :meth:`_expression.Insert.values` method, the user-defined
function is called multiple times, once for each parameter set, however there
was no way to know which subset of keys in
:attr:`.DefaultExecutionContext.current_parameters` apply to that column. A
Fixed issue involving single-table inheritance with ``select_from()``
---------------------------------------------------------------------
-The :meth:`.Query.select_from` method now honors the single-table inheritance
+The :meth:`_query.Query.select_from` method now honors the single-table inheritance
column discriminator when generating SQL; previously, only the expressions
in the query column list would be taken into account.
SELECT employee.id FROM employee WHERE employee.type IN ('manager')
-However, if ``Manager`` were only specified by :meth:`.Query.select_from`
+However, if ``Manager`` were only specified by :meth:`_query.Query.select_from`
and not in the columns list, the discriminator would not be added::
sess.query(func.count(1)).select_from(Manager)
SELECT count(1) FROM employee
-With the fix, :meth:`.Query.select_from` now works correctly and we get::
+With the fix, :meth:`_query.Query.select_from` now works correctly and we get::
SELECT count(1) FROM employee WHERE employee.type IN ('manager')
Refinements to post_update in conjunction with onupdate
-------------------------------------------------------
-A relationship that uses the :paramref:`.relationship.post_update` feature
-will now interact better with a column that has an :paramref:`.Column.onupdate`
+A relationship that uses the :paramref:`_orm.relationship.post_update` feature
+will now interact better with a column that has an :paramref:`_schema.Column.onupdate`
value set. If an object is inserted with an explicit value for the column,
it is re-stated during the UPDATE so that the "onupdate" rule does not
overwrite it::
one of the many special operators defined by PostgreSQL, the
:paramref:`.Operators.op.is_comparison` flag has been repaired to follow
its documented behavior of allowing the return type to be :class:`.Boolean`
-in all cases, including for :class:`.ARRAY` and :class:`.JSON`::
+in all cases, including for :class:`_types.ARRAY` and :class:`_types.JSON`::
>>> column('x', types.String(50)).op('-%>', is_comparison=True)(None).type
Boolean()
Percent signs in literal_column() now conditionally escaped
-----------------------------------------------------------
-The :obj:`.literal_column` construct now escapes percent sign characters
+The :obj:`_expression.literal_column` construct now escapes percent sign characters
conditionally, based on whether or not the DBAPI in use makes use of a
percent-sign-sensitive paramstyle or not (e.g. 'format' or 'pyformat').
-Previously, it was not possible to produce a :obj:`.literal_column`
+Previously, it was not possible to produce a :obj:`_expression.literal_column`
construct that stated a single percent sign::
>>> from sqlalchemy import literal_column
The column-level COLLATE keyword now quotes the collation name
--------------------------------------------------------------
-A bug in the :func:`.expression.collate` and :meth:`.ColumnOperators.collate`
+A bug in the :func:`_expression.collate` and :meth:`.ColumnOperators.collate`
functions, used to supply ad-hoc column collations at the statement level,
is fixed, where a case sensitive name would not be quoted::
has added `Fast Execution Helpers <http://initd.org/psycopg/docs/extras.html#fast-execution-helpers>`_
which rework statements into fewer server round trips by sending multiple
DML statements in batch. SQLAlchemy 1.2 now includes support for these
-helpers to be used transparently whenever the :class:`.Engine` makes use
+helpers to be used transparently whenever the :class:`_engine.Engine` makes use
of ``cursor.executemany()`` to invoke a statement against multiple parameter
sets. The feature is off by default and can be enabled using the
``use_batch_mode`` argument on :func:`.create_engine`::
The "fields" specifier in PostgreSQL's INTERVAL datatype allows specification
of which fields of the interval to store, including such values as "YEAR",
-"MONTH", "YEAR TO MONTH", etc. The :class:`.postgresql.INTERVAL` datatype
+"MONTH", "YEAR TO MONTH", etc. The :class:`_postgresql.INTERVAL` datatype
now allows these values to be specified::
from sqlalchemy.dialects.postgresql import INTERVAL
The ``ON DUPLICATE KEY UPDATE`` clause of ``INSERT`` supported by MySQL
is now supported using a MySQL-specific version of the
-:class:`~.expression.Insert` object, via :func:`sqlalchemy.dialects.mysql.dml.insert`.
-This :class:`~.expression.Insert` subclass adds a new method
+:class:`_expression.Insert` object, via :func:`sqlalchemy.dialects.mysql.dml.insert`.
+This :class:`_expression.Insert` subclass adds a new method
:meth:`~.mysql.dml.Insert.on_duplicate_key_update` that implements MySQL's syntax::
from sqlalchemy.dialects.mysql import insert
----------------------------------------------
UNIQUE and CHECK constraints now reflect via
-:meth:`.Inspector.get_unique_constraints` and
-:meth:`.Inspector.get_check_constraints`. A :class:`.Table` object that's
+:meth:`_reflection.Inspector.get_unique_constraints` and
+:meth:`_reflection.Inspector.get_check_constraints`. A :class:`_schema.Table` object that's
reflected will now include :class:`.CheckConstraint` objects as well.
See the notes at :ref:`oracle_constraint_reflection` for information
-on behavioral quirks here, including that most :class:`.Table` objects
+on behavioral quirks here, including that most :class:`_schema.Table` objects
will still not include any :class:`.UniqueConstraint` objects as these
usually represent via :class:`.Index`.
-------------------------------------------------------------
The names of foreign key constraints as delivered to a
-:class:`.ForeignKeyConstraint` object during table reflection as well as
-within the :meth:`.Inspector.get_foreign_keys` method will now be
+:class:`_schema.ForeignKeyConstraint` object during table reflection as well as
+within the :meth:`_reflection.Inspector.get_foreign_keys` method will now be
"name normalized", that is, expressed as lower case for a case insensitive
name, rather than the raw UPPERCASE format that Oracle uses::
----------------------------------
Both the PyODBC and pymssql dialects now support the "AUTOCOMMIT" isolation
-level as set by :meth:`.Connection.execution_options` which will establish
+level as set by :meth:`_engine.Connection.execution_options` which will establish
the correct flags on the DBAPI connection object.
already mapped class against a different kind of selectable. The non primary
mapper has its roots in the 0.1, 0.2 series of SQLAlchemy where it was
anticipated that the :func:`.mapper` object was to be the primary query
-construction interface, before the :class:`.Query` object existed.
+construction interface, before the :class:`_query.Query` object existed.
-With the advent of :class:`.Query` and later the :class:`.AliasedClass`
+With the advent of :class:`_query.Query` and later the :class:`.AliasedClass`
construct, most use cases for the non primary mapper went away. This was a
good thing since SQLAlchemy also moved away from "classical" mappings altogether
around the 0.5 series in favor of the declarative system.
One use case remained around for non primary mappers when it was realized that
-some very hard-to-define :func:`.relationship` configurations could be made
+some very hard-to-define :func:`_orm.relationship` configurations could be made
possible when a non-primary mapper with an alternative selectable was made as
the mapping target, rather than trying to construct a
-:paramref:`.relationship.primaryjoin` that encompassed all the complexity of a
+:paramref:`_orm.relationship.primaryjoin` that encompassed all the complexity of a
particular inter-object relationship.
As this use case became more popular, its limitations became apparent,
explicitly on the non primary mapper do not function well with loader options,
and that the non primary mapper also doesn't provide a fully functional
namespace of column-based attributes which can be used in queries (which again,
-in the old 0.1 - 0.4 days, one would use :class:`.Table` objects directly with
+in the old 0.1 - 0.4 days, one would use :class:`_schema.Table` objects directly with
the ORM).
-The missing piece was to allow the :func:`.relationship` to refer directly
+The missing piece was to allow the :func:`_orm.relationship` to refer directly
to the :class:`.AliasedClass`. The :class:`.AliasedClass` already does
everything we want the non primary mapper to do; it allows an existing mapped
class to be loaded from an alternative selectable, it inherits all the
the feature's implementation became more complex as a result of advanced
scenarios regarding polymorphic loading. If problems are encountered,
users should report a bug, however the change also includes a flag
-:paramref:`.relationship.omit_join` which can be set to ``False`` on the
-:func:`.relationship` to disable the optimization.
+:paramref:`_orm.relationship.omit_join` which can be set to ``False`` on the
+:func:`_orm.relationship` to disable the optimization.
:ticket:`4340`
Given the case where a lazy load would proceed on a many-to-one relationship
in order to load the "old" value, if the relationship does not specify
-the :paramref:`.relationship.active_history` flag, an assertion will not
+the :paramref:`_orm.relationship.active_history` flag, an assertion will not
be raised for a detached object::
a1 = session.query(Address).filter_by(id=5).one()
--------------------------------------
Added the ``.info`` dictionary to the :class:`.InstanceState` class, the object
-that comes from calling :func:`.inspect` on a mapped object. This allows custom
+that comes from calling :func:`_sa.inspect` on a mapped object. This allows custom
recipes to add additional information about an object that will be carried
along with that object's full lifecycle in memory::
Horizontal Sharding extension supports bulk update and delete methods
---------------------------------------------------------------------
-The :class:`.ShardedQuery` extension object supports the :meth:`.Query.update`
-and :meth:`.Query.delete` bulk update/delete methods. The ``query_chooser``
+The :class:`.ShardedQuery` extension object supports the :meth:`_query.Query.update`
+and :meth:`_query.Query.delete` bulk update/delete methods. The ``query_chooser``
callable is consulted when they are called in order to run the update/delete
across multiple shards based on given criteria.
----------------------------------------------------------------------------
When an ORM-mapped collection that existed as a Python sequence, typically a
-Python ``list`` as is the default for :func:`.relationship`, contained
+Python ``list`` as is the default for :func:`_orm.relationship`, contained
duplicates, and the object were removed from one of its positions but not the
other(s), a many-to-one backref would set its attribute to ``None`` even
though the one-to-many side still represented the object as present. Even
though one-to-many collections cannot have duplicates in the relational model,
-an ORM-mapped :func:`.relationship` that uses a sequence collection can have
+an ORM-mapped :func:`_orm.relationship` that uses a sequence collection can have
duplicates inside of it in memory, with the restriction that this duplicate
state can neither be persisted nor retrieved from the database. In particular,
having a duplicate temporarily present in the list is intrinsic to a Python
FOR UPDATE clause is rendered within the joined eager load subquery as well as outside
--------------------------------------------------------------------------------------
-This change applies specifically to the use of the :func:`.joinedload` loading
-strategy in conjunction with a row limited query, e.g. using :meth:`.Query.first`
-or :meth:`.Query.limit`, as well as with use of the :class:`.Query.with_for_update` method.
+This change applies specifically to the use of the :func:`_orm.joinedload` loading
+strategy in conjunction with a row limited query, e.g. using :meth:`_query.Query.first`
+or :meth:`_query.Query.limit`, as well as with use of the :class:`_query.Query.with_for_update` method.
Given a query as::
session.query(A).options(joinedload(A.b)).limit(5)
-The :class:`.Query` object renders a SELECT of the following form when joined
+The :class:`_query.Query` object renders a SELECT of the following form when joined
eager loading is combined with LIMIT::
SELECT subq.a_id, subq.a_data, b_alias.id, b_alias.data FROM (
passive_deletes='all' will leave FK unchanged for object removed from collection
--------------------------------------------------------------------------------
-The :paramref:`.relationship.passive_deletes` option accepts the value
+The :paramref:`_orm.relationship.passive_deletes` option accepts the value
``"all"`` to indicate that no foreign key attributes should be modified when
the object is flushed, even if the relationship's collection / reference has
been removed. Previously, this did not take place for one-to-many, or
New multi-column naming convention tokens, long name truncation
----------------------------------------------------------------
-To suit the case where a :class:`.MetaData` naming convention needs to
+To suit the case where a :class:`_schema.MetaData` naming convention needs to
disambiguate between multiple-column constraints and wishes to use all the
columns within the generated constraint name, a new series of
naming convention tokens are added, including
:ref:`constraint_naming_conventions`
- :paramref:`.MetaData.naming_convention`
+ :paramref:`_schema.MetaData.naming_convention`
:ticket:`3989`
primarily to the ORM.
A SQL function that compares two elements can now be used as a "comparison"
-object, suitable for usage in an ORM :func:`.relationship`, by first
+object, suitable for usage in an ORM :func:`_orm.relationship`, by first
creating the function as usual using the :data:`.func` factory, then
when the function is complete calling upon the :meth:`.FunctionElement.as_comparison`
modifier to produce a :class:`.BinaryExpression` that has a "left" and a "right"
order_by=name
)
-Above, the :paramref:`.relationship.primaryjoin` of the "descendants" relationship
+Above, the :paramref:`_orm.relationship.primaryjoin` of the "descendants" relationship
will produce a "left" and a "right" expression based on the first and second
arguments passed to ``instr()``. This allows features like the ORM
lazyload to produce SQL like::
The warnings that were first added in version 1.0, described at
:ref:`migration_2992`, have now been converted into exceptions. Continued
concerns have been raised regarding the automatic coercion of string fragments
-passed to methods like :meth:`.Query.filter` and :meth:`.Select.order_by` being
-converted to :func:`.text` constructs, even though this has emitted a warning.
-In the case of :meth:`.Select.order_by`, :meth:`.Query.order_by`,
-:meth:`.Select.group_by`, and :meth:`.Query.group_by`, a string label or column
+passed to methods like :meth:`_query.Query.filter` and :meth:`_expression.Select.order_by` being
+converted to :func:`_expression.text` constructs, even though this has emitted a warning.
+In the case of :meth:`_expression.Select.order_by`, :meth:`_query.Query.order_by`,
+:meth:`_expression.Select.group_by`, and :meth:`_query.Query.group_by`, a string label or column
name is still resolved into the corresponding expression construct, however if
the resolution fails, a :class:`.CompileError` is raised, thus preventing raw
SQL text from being rendered directly.
At this point, any remaining code that is still relying upon the "threadlocal"
style will be encouraged via this deprecation to modernize - the feature should
be removed totally by the next major series of SQLAlchemy, e.g. 1.4. The
-connection pool parameter :paramref:`.Pool.use_threadlocal` is also deprecated
+connection pool parameter :paramref:`_pool.Pool.use_threadlocal` is also deprecated
as it does not actually have any effect in most cases, as is the
-:meth:`.Engine.contextual_connect` method, which is normally synonymous with
-the :meth:`.Engine.connect` method except in the case where the threadlocal
+:meth:`_engine.Engine.contextual_connect` method, which is normally synonymous with
+the :meth:`_engine.Engine.connect` method except in the case where the threadlocal
engine is in use.
-.. seealso::
-
- :ref:`threadlocal_strategy`
-
:ticket:`4393`
)
The two table names ``'data_values'`` and ``'data_values_4_10'`` will come
-back from :meth:`.Inspector.get_table_names` and additionally the columns
+back from :meth:`_reflection.Inspector.get_table_names` and additionally the columns
will come back from ``Inspector.get_columns('data_values')`` as well
as ``Inspector.get_columns('data_values_4_10')``. This also extends to the
use of ``Table(..., autoload=True)`` with these tables.
Support for SQLite JSON Added
-----------------------------
-A new datatype :class:`.sqlite.JSON` is added which implements SQLite's json
-member access functions on behalf of the :class:`.types.JSON`
+A new datatype :class:`_sqlite.JSON` is added which implements SQLite's json
+member access functions on behalf of the :class:`_types.JSON`
base datatype. The SQLite ``JSON_EXTRACT`` and ``JSON_QUOTE`` functions
are used by the implementation to provide basic JSON support.
for standalone constraints as well as some column-inline constraints such as
NOT NULL. Support has been added for these clauses via the ``sqlite_on_conflict``
keyword added to objects like :class:`.UniqueConstraint` as well
-as several :class:`.Column` -specific variants::
+as several :class:`_schema.Column` -specific variants::
some_table = Table(
'some_table', metadata,
the flag ``use_nchar_for_unicode`` can be passed to :func:`.create_engine` to
re-enable the old behavior.
-As always, using the :class:`.oracle.NVARCHAR2` and :class:`.oracle.NCLOB`
+As always, using the :class:`_oracle.NVARCHAR2` and :class:`_oracle.NCLOB`
datatypes explicitly will continue to make use of ``NVARCHAR2`` and ``NCLOB``,
including within DDL as well as when handling bound parameters with cx_Oracle's
``setinputsizes()``.
* The value of the ``threaded`` parameter, which has always been defaulted
to True for the SQLAlchemy dialect, is no longer generated by default.
- The SQLAlchemy :class:`.Connection` object is not considered to be thread-safe
+ The SQLAlchemy :class:`_engine.Connection` object is not considered to be thread-safe
itself so there's no need for this flag to be passed.
* It's deprecated to pass ``threaded`` to :func:`.create_engine` itself.
using :class:.`.Sequence` will emit a deprecation warning throughout the
1.3 series. In order to affect "start" and "increment", use the
new ``mssql_identity_start`` and ``mssql_identity_increment`` parameters
-on :class:`.Column`::
+on :class:`_schema.Column`::
test = Table(
'test', metadata,
)
In order to emit ``IDENTITY`` on a non-primary key column, which is a little-used
-but valid SQL Server use case, use the :paramref:`.Column.autoincrement` flag,
+but valid SQL Server use case, use the :paramref:`_schema.Column.autoincrement` flag,
setting it to ``True`` on the target column, ``False`` on any integer
primary key column::
cached, based on a cache key generated by the created statement object, which
itself is newly created for each use. Towards this goal, much of the Python
computation which occurs within the construction of statements, particularly
-the ORM :class:`.Query`, is being moved to occur only when the statement is
+the ORM :class:`_query.Query`, is being moved to occur only when the statement is
invoked. This means that some of the error messages which can arise based on
arguments passed to the object will no longer be raised immediately, and
instead will occur only when the statement is invoked.
Error conditions which fall under this category include:
-* when a :class:`.CompoundSelect` is constructed (e.g. a UNION, EXCEPT, etc.)
+* when a :class:`_selectable.CompoundSelect` is constructed (e.g. a UNION, EXCEPT, etc.)
and the SELECT statements passed do not have the same number of columns, a
:class:`.CompileError` is now raised to this effect; previously, a
:class:`.ArgumentError` would be raised immediately upon statement
however it is hoped that the end user impact is relatively small, as the change
more closely matches what databases like MySQL and PostgreSQL require in any case.
-The most immediate noticeable impact is that a :func:`~.sql.expression.select` can no longer
-be embedded inside of another :func:`~.sql.expression.select` directly, without explicitly
-turning the inner :func:`~.sql.expression.select` into a subquery first. This is historically
-performed by using the :meth:`.SelectBase.alias` method, which remains, however
-is more explicitly suited by using a new method :meth:`.SelectBase.subquery`;
+The most immediate noticeable impact is that a :func:`_expression.select` can no longer
+be embedded inside of another :func:`_expression.select` directly, without explicitly
+turning the inner :func:`_expression.select` into a subquery first. This is historically
+performed by using the :meth:`_expression.SelectBase.alias` method, which remains, however
+is more explicitly suited by using a new method :meth:`_expression.SelectBase.subquery`;
both methods do the same thing. The object returned is now :class:`.Subquery`,
-which is very similar to the :class:`.Alias` object and shares a common
+which is very similar to the :class:`_expression.Alias` object and shares a common
base :class:`.AliasedReturnsRows`.
That is, this will now raise::
sq1 = select([user.c.id, user.c.name]).subquery()
stmt2 = select([addresses, sq1]).select_from(addresses.join(sq1))
-Noting above that the :meth:`.SelectBase.subquery` method is essentially
-equivalent to using the :meth:`.SelectBase.alias` method.
+Noting above that the :meth:`_expression.SelectBase.subquery` method is essentially
+equivalent to using the :meth:`_expression.SelectBase.alias` method.
The above calling form is typically required in any case as the call to
-:meth:`.SelectBase.subquery` or :meth:`.SelectBase.alias` is needed to
+:meth:`_expression.SelectBase.subquery` or :meth:`_expression.SelectBase.alias` is needed to
ensure the subquery has a name. The MySQL and PostgreSQL databases do not
accept unnamed subqueries in the FROM clause and they are of limited use
on other platforms; this is described further below.
-Along with the above change, the general capability of :func:`~.sql.expression.select` and
+Along with the above change, the general capability of :func:`_expression.select` and
related constructs to create unnamed subqueries, which means a FROM subquery
that renders without any name i.e. "AS somename", has been removed, and the
-ability of the :func:`~.sql.expression.select` construct to implicitly create subqueries
+ability of the :func:`_expression.select` construct to implicitly create subqueries
without explicit calling code to do so is mostly deprecated. In the above
-example, as has always been the case, using the :meth:`.SelectBase.alias`
-method as well as the new :meth:`.SelectBase.subquery` method without passing a
+example, as has always been the case, using the :meth:`_expression.SelectBase.alias`
+method as well as the new :meth:`_expression.SelectBase.subquery` method without passing a
name will generate a so-called "anonymous" name, which is the familiar
``anon_1`` name we see in SQLAlchemy queries::
by moving to an all-explicit subquery much of the complexity incurred by
these areas can be removed.
-As :class:`.SelectBase` objects are no longer :class:`.FromClause` objects,
+As :class:`_expression.SelectBase` objects are no longer :class:`_expression.FromClause` objects,
attributes like the ``.c`` attribute as well as methods like ``.select()``,
-``.join()``, and ``.outerjoin()`` upon :class:`.SelectBase` are now
+``.join()``, and ``.outerjoin()`` upon :class:`_expression.SelectBase` are now
deprecated, as these methods all imply implicit production of a subquery.
Instead, as is already what the vast majority of applications have to do
-in any case, invoking :meth:`.SelectBase.alias` or :meth:`.SelectBase.subquery`
+in any case, invoking :meth:`_expression.SelectBase.alias` or :meth:`_expression.SelectBase.subquery`
will provide for a :class:`.Subquery` object that provides all these attributes,
-as it is part of the :class:`.FromClause` hierarchy. In the interim, these
+as it is part of the :class:`_expression.FromClause` hierarchy. In the interim, these
methods are still available, however they now produce an anonymously named
subquery rather than an unnamed one, and this subquery is distinct from the
-:class:`.SelectBase` construct itself.
+:class:`_expression.SelectBase` construct itself.
-In place of the ``.c`` attribute, a new attribute :attr:`.SelectBase.selected_columns`
+In place of the ``.c`` attribute, a new attribute :attr:`_expression.SelectBase.selected_columns`
is added. This attribute resolves to a column collection that is what most
people hope that ``.c`` does (but does not), which is to reference the columns
that are in the columns clause of the SELECT statement. A common beginner mistake
recognize that it in fact generates a useless subquery resembling
"SELECT * FROM (SELECT * FROM users) WHERE name='foo'".
-The new :attr:`.SelectBase.selected_columns` attribute however **does** suit
+The new :attr:`_expression.SelectBase.selected_columns` attribute however **does** suit
the use case above, as in a case like the above it links directly to the columns
present in the ``users.c`` collection::
stmt = select([users])
stmt = stmt.where(stmt.selected_columns.name == 'foo')
-There is of course the notion that perhaps ``.c`` on :class:`.SelectBase` could
-simply act the way :attr:`.SelectBase.selected_columns` does above, however in
-light of the fact that ``.c`` is strongly associated with the :class:`.FromClause`
+There is of course the notion that perhaps ``.c`` on :class:`_expression.SelectBase` could
+simply act the way :attr:`_expression.SelectBase.selected_columns` does above, however in
+light of the fact that ``.c`` is strongly associated with the :class:`_expression.FromClause`
hierarchy, meaning that it is a set of columns that can be directly in the
FROM clause of another SELECT, it's better that a column collection that
serves an entirely different purpose have a new name.
In the bigger picture, the reason this change is being made now is towards the
-goal of unifying the ORM :class:`.Query` object into the :class:`.SelectBase`
+goal of unifying the ORM :class:`_query.Query` object into the :class:`_expression.SelectBase`
hierarchy in SQLAlchemy 2.0, so that the ORM will have a "``select()``"
-construct that extends directly from the existing :func:`~.sql.expression.select` object,
+construct that extends directly from the existing :func:`_expression.select` object,
having the same methods and behaviors except that it will have additional ORM
functionality. All statement objects in Core will also be fully cacheable
using a new system that resembles "baked queries" except that it will work
whereby the parameter list is expanded at statement construction time into
individual :class:`.BindParameter` objects, the feature instead uses a single
:class:`.BindParameter` that stores the list of values at once; when the
-statement is executed by the :class:`.Engine`, it is "expanded" on the fly into
+statement is executed by the :class:`_engine.Engine`, it is "expanded" on the fly into
individual bound parameter positions based on the parameters passed to the call
-to :meth:`.Connection.execute`, and the existing SQL string which may have been
+to :meth:`_engine.Connection.execute`, and the existing SQL string which may have been
retrieved from a previous execution is modified using a regular expression to
suit the current parameter set. This allows for the same :class:`.Compiled`
object, which stores the rendered string statement, to be invoked multiple
For release 1.4, the :class:`.Row` class provides an additional subclass
:class:`.LegacyRow`, which is used by Core and provides a backwards-compatible
version of :class:`.RowProxy` while emitting deprecation warnings for those API
-features and behaviors that will be moved. ORM :class:`.Query` now makes use
+features and behaviors that will be moved. ORM :class:`_query.Query` now makes use
of :class:`.Row` directly as a replacement for :class:`.KeyedTuple`.
The :class:`.LegacyRow` class is a transitional class where the
book_w_excerpt = session.query(Book).options(undefer(Book.excerpt)).first()
It was originally considered that the existing :func:`.raiseload` option that
-works for :func:`.relationship` attributes be expanded to also support column-oriented
+works for :func:`_orm.relationship` attributes be expanded to also support column-oriented
attributes. However, this would break the "wildcard" behavior of :func:`.raiseload`,
which is documented as allowing one to prevent all relationships from loading::
As discussed at :ref:`change_4710_core`, the Core :class:`.RowProxy` object
is now replaced by a class called :class:`.Row`. The base :class:`.Row`
object now behaves more fully like a named tuple, and as such it is now
-used as the basis for tuple-like results returned by the :class:`.Query`
+used as the basis for tuple-like results returned by the :class:`_query.Query`
object, rather than the previous "KeyedTuple" class.
The rationale is so that by SQLAlchemy 2.0, both Core and ORM SELECT statements
will make use of a :class:`.Row` subclass :class:`.LegacyRow` which maintains
the previous dict/tuple hybrid behavior for backwards compatibility while the
:class:`.Row` class will be used directly for ORM tuple results returned
-by the :class:`.Query` object.
+by the :class:`_query.Query` object.
Effort has been made to get most of the featureset of :class:`.Row` to be
available within the ORM, meaning that access by string name as well
:class:`.Session` object's behavior; the :class:`.Session` will continue to have
the behavior that it remains usable for new operations after :meth:`.Session.close`
is called, and the sequencing of how the :class:`.Session` interacts with the
-:class:`.Engine` and the database itself should also remain unaffected, since
+:class:`_engine.Engine` and the database itself should also remain unaffected, since
these operations were already operating in an on-demand fashion.
:ticket:`5074`
WHERE a.id = ?
The behavior applies both to loader strategies applied to the
-:func:`.relationship` directly, as well as with options used with
-:meth:`.Query.options`, provided that the object was originally loaded by that
+:func:`_orm.relationship` directly, as well as with options used with
+:meth:`_query.Query.options`, provided that the object was originally loaded by that
query.
For the "secondary" eager loaders "selectinload" and "subqueryload", the SQL
Persistence-related cascade operations disallowed with viewonly=True
---------------------------------------------------------------------
-When a :func:`.relationship` is set as ``viewonly=True`` using the
-:paramref:`.relationship.viewonly` flag, it indicates this relationship should
+When a :func:`_orm.relationship` is set as ``viewonly=True`` using the
+:paramref:`_orm.relationship.viewonly` flag, it indicates this relationship should
only be used to load data from the database, and should not be mutated
or involved in a persistence operation. In order to ensure this contract
works successfully, the relationship can no longer specify
-:paramref:`.relationship.cascade` settings that make no sense in terms of
+:paramref:`_orm.relationship.cascade` settings that make no sense in terms of
"viewonly".
The primary targets here are the "delete, delete-orphan" cascades, which
the requested polymorphic identity or identities, an error is raised.
Previously, this condition would pass silently under joined table inheritance,
returning an invalid subclass, and under single table inheritance, the
-:class:`.Query` would be adding additional criteria against the subquery to
+:class:`_query.Query` would be adding additional criteria against the subquery to
limit the results which could inappropriately interfere with the intent of the
query.
2020-01-29 18:08:32,975 INFO sqlalchemy.engine.base.Engine ('manager',)
[<__main__.Manager object at 0x7ff1b0200d50>]
-The :class:`.Query` added the "single table inheritance" criteria to the
+The :class:`_query.Query` added the "single table inheritance" criteria to the
subquery, editorializing on the intent that was originally set up by it.
This behavior was added in version 1.0 in :ticket:`3891`, and creates a
behavioral inconsistency between "joined" and "single" table inheritance,
another one via the WHERE clause.
For some years there has been a recipe on the Wiki that applies a graph
-algorithm to a :func:`~.sql.expression.select` construct at query execution time and inspects
+algorithm to a :func:`_expression.select` construct at query execution time and inspects
the structure of the query for these un-linked FROM clauses, parsing through
the WHERE clause and all JOIN clauses to determine how FROM elements are linked
together and ensuring that all the FROM elements are connected in a single
q = session.query(User).join(Address, true()) # intentional cartesian product
The warning is only generated by default when the statement is compiled by the
-:class:`.Connection` for execution; calling the :meth:`.ClauseElement.compile`
+:class:`_engine.Connection` for execution; calling the :meth:`_expression.ClauseElement.compile`
method will not emit a warning unless the linting flag is supplied::
>>> from sqlalchemy.sql import FROM_LINTING
SELECT objects and derived FROM clauses allow for duplicate columns and column labels
-------------------------------------------------------------------------------------
-This change allows that the :func:`~.sql.expression.select` construct now allows for duplicate
+This change allows that the :func:`_expression.select` construct now allows for duplicate
column labels as well as duplicate column objects themselves, so that result
tuples are organized and ordered in the identical way in that the columns were
-selected. The ORM :class:`.Query` already works this way, so this change
+selected. The ORM :class:`_query.Query` already works this way, so this change
allows for greater cross-compatibility between the two, which is a key goal of
the 2.0 transition::
>>> print(stmt)
SELECT c1, c2, c3 AS c2, c2, c4
-To support this change, the :class:`.ColumnCollection` used by
-:class:`.SelectBase` as well as for derived FROM clauses such as subqueries
+To support this change, the :class:`_expression.ColumnCollection` used by
+:class:`_expression.SelectBase` as well as for derived FROM clauses such as subqueries
also support duplicate columns; this includes the new
-:attr:`.SelectBase.selected_columns` attribute, the deprecated ``SelectBase.c``
-attribute, as well as the :attr:`.FromClause.c` attribute seen on constructs
-such as :class:`.Subquery` and :class:`.Alias`::
+:attr:`_expression.SelectBase.selected_columns` attribute, the deprecated ``SelectBase.c``
+attribute, as well as the :attr:`_expression.FromClause.c` attribute seen on constructs
+such as :class:`.Subquery` and :class:`_expression.Alias`::
>>> list(stmt.selected_columns)
[
SELECT anon_1.c1, anon_1.c2, anon_1.c2, anon_1.c2, anon_1.c4
FROM (SELECT c1, c2, c3 AS c2, c2, c4) AS anon_1
-:class:`.ColumnCollection` also allows access by integer index to support
+:class:`_expression.ColumnCollection` also allows access by integer index to support
when the string "key" is ambiguous::
>>> stmt.selected_columns[2]
<sqlalchemy.sql.elements.Label object at 0x7fa540b3e2e8>
-To suit the use of :class:`.ColumnCollection` in objects such as
-:class:`.Table` and :class:`.PrimaryKeyConstraint`, the old "deduplicating"
+To suit the use of :class:`_expression.ColumnCollection` in objects such as
+:class:`_schema.Table` and :class:`.PrimaryKeyConstraint`, the old "deduplicating"
behavior which is more critical for these objects is preserved in a new class
:class:`.DedupeColumnCollection`.
The change includes that the familiar warning ``"Column %r on table %r being
replaced by %r, which has the same key. Consider use_labels for select()
-statements."`` is **removed**; the :meth:`.Select.apply_labels` is still
+statements."`` is **removed**; the :meth:`_expression.Select.apply_labels` is still
available and is still used by the ORM for all SELECT operations, however it
does not imply deduplication of column objects, although it does imply
deduplication of implicitly generated labels::
FROM "user"
Finally, the change makes it easier to create UNION and other
-:class:`.CompoundSelect` objects, by ensuring that the number and position
+:class:`_selectable.CompoundSelect` objects, by ensuring that the number and position
of columns in a SELECT statement mirrors what was given, in a use case such
as::
Connection-level transactions can now be inactive based on subtransaction
-------------------------------------------------------------------------
-A :class:`.Connection` now includes the behavior where a :class:`.Transaction`
+A :class:`_engine.Connection` now includes the behavior where a :class:`.Transaction`
can be made inactive due to a rollback on an inner transaction, however the
:class:`.Transaction` will not clear until it is itself rolled back.
This is essentially a new error condition which will disallow statement
-executions to proceed on a :class:`.Connection` if an inner "sub" transaction
+executions to proceed on a :class:`_engine.Connection` if an inner "sub" transaction
has been rolled back. The behavior works very similarly to that of the
ORM :class:`.Session`, where if an outer transaction has been begun, it needs
to be rolled back to clear the invalid transaction; this behavior is described
in :ref:`faq_session_rollback`
-While the :class:`.Connection` has had a less strict behavioral pattern than
+While the :class:`_engine.Connection` has had a less strict behavioral pattern than
the :class:`.Session`, this change was made as it helps to identify when
a subtransaction has rolled back the DBAPI transaction, however the external
code isn't aware of this and attempts to continue proceeding, which in fact
The MariaDB database as of 10.3 supports sequences. SQLAlchemy's MySQL
dialect now implements support for the :class:`.Sequence` object against this
database, meaning "CREATE SEQUENCE" DDL will be emitted for a
-:class:`.Sequence` that is present in a :class:`.Table` or :class:`.MetaData`
+:class:`.Sequence` that is present in a :class:`_schema.Table` or :class:`_schema.MetaData`
collection in the same way as it works for backends such as PostgreSQL, Oracle,
when the dialect's server version check has confirmed the database is MariaDB
10.3 or greater. Additionally, the :class:`.Sequence` will act as a
shortcomings that would be unknown today. The vast majority of Python
packages that are today taken for granted did not exist. SQLAlchemy itself
struggled with major API adjustments through versions 0.1 to 0.5, with such
- major concepts as :class:`.Connection`, :class:`.orm.query.Query`, and the
+ major concepts as :class:`_engine.Connection`, :class:`.orm.query.Query`, and the
Declarative mapping approach only being conceived and added to releases
gradually over a period of a several years.
conn.execute(some_table.insert().values(foo='bar'))
For "commit as you go, or rollback instead" usage, which resembles how the
-:class:`.orm.Session` is normally used today, new ``.commit()`` and
-``.rollback()`` methods will also be added to :class:`.Connection` itself.
-These will typically be used in conjunction with the :meth:`.Engine.connect`
+:class:`_orm.Session` is normally used today, new ``.commit()`` and
+``.rollback()`` methods will also be added to :class:`_engine.Connection` itself.
+These will typically be used in conjunction with the :meth:`_engine.Engine.connect`
method::
# 1.4 / 2.0 code
conn.execute(text("some other SQL"))
conn.rollback()
-Above, the ``engine.connect()`` method will return a :class:`.Connection` that
+Above, the ``engine.connect()`` method will return a :class:`_engine.Connection` that
features **autobegin**, meaning the ``begin()`` event is emitted when the
execute method is first used (note however that there is no actual "BEGIN" in
the Python DBAPI). This is the same as how the ORM :class:`.Session` will
above transaction block. The 1.4 change :ref:`change_5074` is part of this
architecture.
-In the case of both core :class:`.Connection` as well as orm :class:`.Session`,
+In the case of both core :class:`_engine.Connection` as well as orm :class:`.Session`,
if neither ``.commit()`` nor ``.rollback()`` are called, the connection is
returned to the pool normally where an implicit (yes, still need this one)
rollback will occur. This is the case already for Core and ORM::
a lot of ``engine.execute()`` calls that will need to be adjusted.
"Connectionless" execution refers to the still fairly popular pattern of
-invoking ``.execute()`` from the :class:`.Engine`::
+invoking ``.execute()`` from the :class:`_engine.Engine`::
result = engine.execute(some_statement)
-The above operation implicitly procures a :class:`.Connection` object,
+The above operation implicitly procures a :class:`_engine.Connection` object,
and runs the ``.execute()`` method on it. This seems like a pretty simple
and intuitive method to have so that people who just need to invoke a few
SQL statements don't need all the verbosity with connecting and all that.
Because implicit execution is removed, there's really no reason for "bound"
metadata to exist. There are many internal structures that are involved with
-locating the "bind" for a particular statement, to see if an :class:`.Engine`
+locating the "bind" for a particular statement, to see if an :class:`_engine.Engine`
is associated with some SQL statement exists which necessarily involves an
additional traversal of the statement, just to find the correct dialect with
which to compile it. This complex and error-prone logic can be removed from
Core by removing "bound" metadata.
Overall, the above executional patterns were introduced in SQLAlchemy's
-very first 0.1 release before the :class:`.Connection` object even existed.
+very first 0.1 release before the :class:`_engine.Connection` object even existed.
After many years of de-emphasizing these patterns, "implicit, connectionless"
execution and "bound metadata" are no longer as widely used so in 2.0 we seek
to finally reduce the number of choices for how to execute a statement in
To suit the use case of ORM "dynamic" relationships as well as Flask-oriented
ORM patterns, there still may be some semblance of "implicit" execution of
a statement, however, it won't really be "connectionless". Likely, a statement
-can be directly bound to a :class:`.Connection` or :class:`.Session` once
+can be directly bound to a :class:`_engine.Connection` or :class:`.Session` once
constructed::
# 1.4 / 2.0 code (tentative)
The use of execution options is expected to be more prominent as the Core and
ORM are largely unified at the statement handling level. To suit this,
-the :class:`.orm.Session` will be able to receive execution options local
+the :class:`_orm.Session` will be able to receive execution options local
to a series of statement executions in the same way as that of
-:class:`.Connection`::
+:class:`_engine.Connection`::
# 1.4 / 2.0 code
==================================================================
Already part of 1.4, the previous ``KeyedTuple`` class that was used when
-selecting rows from the :class:`.Query` object has been replaced by the
+selecting rows from the :class:`_query.Query` object has been replaced by the
:class:`.Row` class, which is the base of the same :class:`.Row` that comes
back with Core statement results (in 1.4 it is the :class:`.LegacyRow` class).
# "classical" mapping:
base.mapper(MyClass, my_table)
-In 2.0, an application that still wishes to use a separate :class:`.Table` and
+In 2.0, an application that still wishes to use a separate :class:`_schema.Table` and
does not want to use Declarative with ``__table__``, can instead use the above
pattern which basically does the same thing.
.. admonition:: Certainty: tentative
Tenative overall, however there will almost definitely be
- architectural changes in :class:`.Query` that move it closer to
- :func:`.select`.
+ architectural changes in :class:`_query.Query` that move it closer to
+ :func:`_expression.select`.
The ``session.query(<cls>)`` pattern itself will likely **not** be fully
removed. As this pattern is extremely prevalent and numerous within any
that a transition to 2.0 won't require a rewrite of every ``session.query()``
call, however it will be a legacy pattern that may warn as such.
-Ever wonder why SQLAlchemy :func:`~.sql.expression.select` uses :meth:`.Select.where` to add
-a WHERE clause and :class:`.Query` uses :meth:`.Query.filter` ? Same here!
-The :class:`.Query` object was not part of SQLAlchemy's original concept.
-Originally, the idea was that the :class:`.Mapper` construct itself would
-be able to select rows, and that :class:`.Table` objects, not classes,
+Ever wonder why SQLAlchemy :func:`_expression.select` uses :meth:`_expression.Select.where` to add
+a WHERE clause and :class:`_query.Query` uses :meth:`_query.Query.filter` ? Same here!
+The :class:`_query.Query` object was not part of SQLAlchemy's original concept.
+Originally, the idea was that the :class:`_orm.Mapper` construct itself would
+be able to select rows, and that :class:`_schema.Table` objects, not classes,
would be used to create the various criteria in a Core-style approach. The
-:class:`.Query` was basically an extension that was proposed by a user who
+:class:`_query.Query` was basically an extension that was proposed by a user who
quite plainly had a better idea of how to build up SQL queries. The
-"buildable" approach of :class:`.Query`, originally called ``SelectResults``,
-was also adapted to the Core SQL objects, so that :func:`~.sql.expression.select` gained
-methods like :meth:`.Select.where`, rather than being an all-at-once composed
+"buildable" approach of :class:`_query.Query`, originally called ``SelectResults``,
+was also adapted to the Core SQL objects, so that :func:`_expression.select` gained
+methods like :meth:`_expression.Select.where`, rather than being an all-at-once composed
object. Later on, ORM classes gained the ability to be used directly in
-constructing SQL criteria. :class:`.Query` evolved over many years to
-eventually support production of all the SQL that :func:`~.sql.expression.select` does, to
+constructing SQL criteria. :class:`_query.Query` evolved over many years to
+eventually support production of all the SQL that :func:`_expression.select` does, to
the point where having both forms has now become redundant.
SQLAlchemy 2.0 will resolve the inconsistency here by promoting the concept
-of :func:`~.sql.expression.select` to be the single way that one constructs a SELECT construct.
+of :func:`_expression.select` to be the single way that one constructs a SELECT construct.
For Core usage, the ``select()`` works mostly as it does now, except that it
gains a real working ``.join()`` method that will append JOIN conditions to the
-statement in the same way as works for :meth:`.Query.join` right now.
+statement in the same way as works for :meth:`_query.Query.join` right now.
-For ORM use however, one can construct a :func:`~.sql.expression.select` using ORM objects, and
+For ORM use however, one can construct a :func:`_expression.select` using ORM objects, and
then when delivered to the ``.invoke()`` or ``.execute()`` method of
:class:`.Session`, it will be interpreted appropriately::
rows = session.execute(stmt).all()
-Similarly, methods like :meth:`.Query.update` and :meth:`.Query.delete` are now
-replaced by usage of the :func:`.update` and :func:`.delete` constructs directly::
+Similarly, methods like :meth:`_query.Query.update` and :meth:`_query.Query.delete` are now
+replaced by usage of the :func:`_expression.update` and :func:`_expression.delete` constructs directly::
from sqlalchemy.future import update
Joining / loading on relationships uses attributes, not strings
----------------------------------------------------------------
-This refers to patterns such as that of :meth:`.Query.join` as well as
-query options like :func:`.joinedload` which currently accept a mixture of
+This refers to patterns such as that of :meth:`_query.Query.join` as well as
+query options like :func:`_orm.joinedload` which currently accept a mixture of
string attribute names or actual class attributes. The string calling form
leaves a lot more ambiguity and is also more complicated internally, so will
be deprecated in 1.4 and removed by 2.0. This means the following won't work::
join(..., aliased=True), from_joinpoint removed
-----------------------------------------------
-The ``aliased=True`` option on :meth:`.Query.join` is another feature that
+The ``aliased=True`` option on :meth:`_query.Query.join` is another feature that
seems to be almost never used, based on extensive code searches to find
actual use of this feature. The internal complexity that the ``aliased=True``
flag requires is **enormous**, and will be going away in 2.0.
filter(Node.name == 'some sub child')
The ``aliased=True`` and ``from_joinpoint`` parameters were developed at a time
-when the :class:`.Query` object didn't yet have good capabilities regarding
+when the :class:`_query.Query` object didn't yet have good capabilities regarding
joining along relationship attributes, functions like
:meth:`.PropComparator.of_type` did not exist, and the :func:`.aliased`
construct itself didn't exist early on.
The above patterns are all suited by standard use of the :func:`.aliased`
construct, resulting in a much clearer query as well as removing hundreds of
-lines of complexity from the internals of :class:`.Query` (or whatever it is
+lines of complexity from the internals of :class:`_query.Query` (or whatever it is
to be called in 2.0 :) ) ::
n1 = aliased(Node)
-By using attributes instead of strings above, the :meth:`.Query.join` method
+By using attributes instead of strings above, the :meth:`_query.Query.join` method
no longer needs the almost never-used option of ``from_joinpoint``.
Other ORM Query patterns changed
=================================
-This section will collect various :class:`.Query` patterns and how they work
+This section will collect various :class:`_query.Query` patterns and how they work
in terms of :func:`.future.select`.
.. _migration_20_query_distinct:
Using DISTINCT with additional columns, but only select the entity
-------------------------------------------------------------------
-:class:`.Query` will automatically add columns in the ORDER BY when
+:class:`_query.Query` will automatically add columns in the ORDER BY when
distinct is used. The following query will select from all User columns
as well as "address.email_address" but only return User objects::
Selecting from the query itself as a subquery, e.g. "from_self()"
-------------------------------------------------------------------
-The :meth:`.Query.from_self` method is a very complicated method that is rarely
-used. The purpose of this method is to convert a :class:`.Query` into a
-subquery, then return a new :class:`.Query` which SELECTs from that subquery.
+The :meth:`_query.Query.from_self` method is a very complicated method that is rarely
+used. The purpose of this method is to convert a :class:`_query.Query` into a
+subquery, then return a new :class:`_query.Query` which SELECTs from that subquery.
The elaborate aspect of this method is that the returned query applies
automatic translation of ORM entities and columns to be stated in the SELECT in
terms of the subquery, as well as that it allows the entities and columns to be
SELECTed from to be modified.
-Because :meth:`.Query.from_self` packs an intense amount of implicit
+Because :meth:`_query.Query.from_self` packs an intense amount of implicit
translation into the SQL it produces, while it does allow a certain kind of
pattern to be executed very succinctly, real world use of this method is
infrequent as it is not simple to understand.
In SQLAlchemy 2.0, as the :func:`.future.select` construct will be expected
-to handle every pattern the ORM :class:`.Query` does now, the pattern of
-:meth:`.Query.from_self` can be invoked now by making use of the
-:func:`.orm.aliased` function in conjunction with a subquery, that is
-the :meth:`.Query.subquery` or :meth:`.Select.subquery` method. Version 1.4
-of SQLAlchemy has enhanced the ability of the :func:`.orm.aliased` construct
+to handle every pattern the ORM :class:`_query.Query` does now, the pattern of
+:meth:`_query.Query.from_self` can be invoked now by making use of the
+:func:`_orm.aliased` function in conjunction with a subquery, that is
+the :meth:`_query.Query.subquery` or :meth:`_expression.Select.subquery` method. Version 1.4
+of SQLAlchemy has enhanced the ability of the :func:`_orm.aliased` construct
to correctly extract columns from a given subquery.
-Starting with a :meth:`.Query.from_self` query that selects from two different
+Starting with a :meth:`_query.Query.from_self` query that selects from two different
entities, then converts itself to select just one of the entities from
a subquery::
The SQL query above illustrates the automatic translation of the "user" and
"address" tables in terms of the anonymously named subquery.
-In 2.0, we perform these steps explicitly using :func:`.orm.aliased`::
+In 2.0, we perform these steps explicitly using :func:`_orm.aliased`::
# 1.4/2.0 code
The above query renders the identical SQL structure, but uses a more
succinct labeling scheme that doesn't pull in table names (that labeling
-scheme is still available if the :meth:`.Select.apply_labels` method is used)::
+scheme is still available if the :meth:`_expression.Select.apply_labels` method is used)::
SELECT anon_1.id AS anon_1_id
FROM (
Pending further architectural prototyping and performance testing
A major restructuring of the Core internals as well as of that of the ORM
-:class:`.Query` will be reorganizing the major statement objects to have very
+:class:`_query.Query` will be reorganizing the major statement objects to have very
simplified "builder" internals, that is, when you construct an object like
``select(table).where(criteria).join(some_table)``, the arguments passed are
simply stored and as little processing as possible will occur. Then there is
to keep up with SQLAlchemy's own capabilities and they likely don't really
work for lots of existing use cases either.
-* Essentially, it is hoped that the re-architecting of :class:`.Connection`
+* Essentially, it is hoped that the re-architecting of :class:`_engine.Connection`
to no longer support things like "autocommit" and "connectionless"
execution, as well as the changes to how result fetching will work with the
``Result`` which is hoped to be simpler in how it interacts with
the cursor, will make it **much easier** to build async versions of
- SQLAlchemy's :class:`.Connection`. The simplified model of
+ SQLAlchemy's :class:`_engine.Connection`. The simplified model of
``Connection.execute()`` and ``Session.execute()`` as the single point of
invocation of queries should also make things easier.
:tags: schema
:tickets: 4138
- Add ``comment`` attribute to :class:`.Column` ``__repr__`` method.
+ Add ``comment`` attribute to :class:`_schema.Column` ``__repr__`` method.
:tickets: 4194
Fixed bug where a versioning column specified on a mapper against a
- :func:`~.sql.expression.select` construct where the version_id_col itself were against the
+ :func:`_expression.select` construct where the version_id_col itself were against the
underlying table would incur additional loads when accessed, even if the
value were locally persisted by the flush. The actual fix is a result of
- the changes in :ticket:`4617`, by fact that a :func:`~.sql.expression.select` object no
+ the changes in :ticket:`4617`, by fact that a :func:`_expression.select` object no
longer has a ``.c`` attribute and therefore does not confuse the mapper
into thinking there's an unknown column value present.
:tags: bug, sql
:tickets: 4336
- Reworked the :meth:`.ClauseElement.compare` methods in terms of a new
+ Reworked the :meth:`_expression.ClauseElement.compare` methods in terms of a new
visitor-based approach, and additionally added test coverage ensuring that
- all :class:`.ClauseElement` subclasses can be accurately compared
+ all :class:`_expression.ClauseElement` subclasses can be accurately compared
against each other in terms of structure. Structural comparison
capability is used to a small degree within the ORM currently, however
it also may form the basis for new caching features.
"anon_1" label, that is, ``CAST(table.colname AS INTEGER) AS colname``.
If the inner expression doesn't have a name, then the previous "anonymous
label" logic is used. When using SELECT statements that make use of
- :meth:`.Select.apply_labels`, such as those emitted by the ORM, the
+ :meth:`_expression.Select.apply_labels`, such as those emitted by the ORM, the
labeling logic will produce ``<tablename>_<inner column name>`` in the same
was as if the column were named alone. The logic applies right now to the
:func:`.cast` and :func:`.type_coerce` constructs as well as some
:tickets: 4617
The "clause coercion" system, which is SQLAlchemy Core's system of receiving
- arguments and resolving them into :class:`.ClauseElement` structures in order
+ arguments and resolving them into :class:`_expression.ClauseElement` structures in order
to build up SQL expression objects, has been rewritten from a series of
ad-hoc functions to a fully consistent class-based system. This change
is internal and should have no impact on end users other than more specific
error messages when the wrong kind of argument is passed to an expression
object, however the change is part of a larger set of changes involving
- the role and behavior of :func:`~.sql.expression.select` objects.
+ the role and behavior of :func:`_expression.select` objects.
:tickets: 4617
As part of the SQLAlchemy 2.0 migration project, a conceptual change has
- been made to the role of the :class:`.SelectBase` class hierarchy,
+ been made to the role of the :class:`_expression.SelectBase` class hierarchy,
which is the root of all "SELECT" statement constructs, in that they no
longer serve directly as FROM clauses, that is, they no longer subclass
- :class:`.FromClause`. For end users, the change mostly means that any
- placement of a :func:`~.sql.expression.select` construct in the FROM clause of another
- :func:`~.sql.expression.select` requires first that it be wrapped in a subquery first,
- which historically is through the use of the :meth:`.SelectBase.alias`
+ :class:`_expression.FromClause`. For end users, the change mostly means that any
+ placement of a :func:`_expression.select` construct in the FROM clause of another
+ :func:`_expression.select` requires first that it be wrapped in a subquery first,
+ which historically is through the use of the :meth:`_expression.SelectBase.alias`
method, and is now also available through the use of
- :meth:`.SelectBase.subquery`. This was usually a requirement in any
+ :meth:`_expression.SelectBase.subquery`. This was usually a requirement in any
case since several databases don't accept unnamed SELECT subqueries
in their FROM clause in any case.
:tickets: 4617
Added a new Core class :class:`.Subquery`, which takes the place of
- :class:`.Alias` when creating named subqueries against a :class:`.SelectBase`
- object. :class:`.Subquery` acts in the same way as :class:`.Alias`
- and is produced from the :meth:`.SelectBase.subquery` method; for
- ease of use and backwards compatibility, the :meth:`.SelectBase.alias`
+ :class:`_expression.Alias` when creating named subqueries against a :class:`_expression.SelectBase`
+ object. :class:`.Subquery` acts in the same way as :class:`_expression.Alias`
+ and is produced from the :meth:`_expression.SelectBase.subquery` method; for
+ ease of use and backwards compatibility, the :meth:`_expression.SelectBase.alias`
method is synonymous with this new method.
.. seealso::
:tags: change, orm
:tickets: 4617
- The ORM will now warn when asked to coerce a :func:`~.sql.expression.select` construct into
+ The ORM will now warn when asked to coerce a :func:`_expression.select` construct into
a subquery implicitly. This occurs within places such as the
- :meth:`.Query.select_entity_from` and :meth:`.Query.select_from` methods
+ :meth:`_query.Query.select_entity_from` and :meth:`_query.Query.select_from` methods
as well as within the :func:`.with_polymorphic` function. When a
- :class:`.SelectBase` (which is what's produced by :func:`~.sql.expression.select`) or
- :class:`.Query` object is passed directly to these functions and others,
+ :class:`_expression.SelectBase` (which is what's produced by :func:`_expression.select`) or
+ :class:`_query.Query` object is passed directly to these functions and others,
the ORM is typically coercing them to be a subquery by calling the
- :meth:`.SelectBase.alias` method automatically (which is now superceded by
- the :meth:`.SelectBase.subquery` method). See the migration notes linked
+ :meth:`_expression.SelectBase.alias` method automatically (which is now superceded by
+ the :meth:`_expression.SelectBase.subquery` method). See the migration notes linked
below for further details.
.. seealso::
:tags: bug, sql
:tickets: 4617
- The ORDER BY clause of a :class:`.CompoundSelect`, e.g. UNION, EXCEPT, etc.
+ The ORDER BY clause of a :class:`_selectable.CompoundSelect`, e.g. UNION, EXCEPT, etc.
will not render the table name associated with a given column when applying
- :meth:`.CompoundSelect.order_by` in terms of a :class:`.Table` - bound
+ :meth:`_selectable.CompoundSelect.order_by` in terms of a :class:`_schema.Table` - bound
column. Most databases require that the names in the ORDER BY clause be
expressed as label names only which are matched to names in the first
SELECT statement. The change is related to :ticket:`4617` in that a
previous workaround was to refer to the ``.c`` attribute of the
- :class:`.CompoundSelect` in order to get at a column that has no table
+ :class:`_selectable.CompoundSelect` in order to get at a column that has no table
name. As the subquery is now named, this change allows both the workaround
to continue to work, as well as allows table-bound columns as well as the
- :attr:`.CompoundSelect.selected_columns` collections to be usable in the
- :meth:`.CompoundSelect.order_by` method.
\ No newline at end of file
+ :attr:`_selectable.CompoundSelect.selected_columns` collections to be usable in the
+ :meth:`_selectable.CompoundSelect.order_by` method.
\ No newline at end of file
:tags: change, sql
:tickets: 4617
- The :meth:`.SelectBase.as_scalar` and :meth:`.Query.as_scalar` methods have
- been renamed to :meth:`.SelectBase.scalar_subquery` and
- :meth:`.Query.scalar_subquery`, respectively. The old names continue to
+ The :meth:`_expression.SelectBase.as_scalar` and :meth:`_query.Query.as_scalar` methods have
+ been renamed to :meth:`_expression.SelectBase.scalar_subquery` and
+ :meth:`_query.Query.scalar_subquery`, respectively. The old names continue to
exist within 1.4 series with a deprecation warning. In addition, the
- implicit coercion of :class:`.SelectBase`, :class:`.Alias`, and other
+ implicit coercion of :class:`_expression.SelectBase`, :class:`_expression.Alias`, and other
SELECT oriented objects into scalar subqueries when evaluated in a column
context is also deprecated, and emits a warning that the
- :meth:`.SelectBase.scalar_subquery` method should be called explicitly.
+ :meth:`_expression.SelectBase.scalar_subquery` method should be called explicitly.
This warning will in a later major release become an error, however the
- message will always be clear when :meth:`.SelectBase.scalar_subquery` needs
+ message will always be clear when :meth:`_expression.SelectBase.scalar_subquery` needs
to be invoked. The latter part of the change is for clarity and to reduce
the implicit decisionmaking by the query coercion system. The
:meth:`.Subquery.as_scalar` method, which was previously
``Alias.as_scalar``, is also deprecated; ``.scalar_subquery()`` should be
- invoked directly from ` :func:`~.sql.expression.select` object or :class:`.Query` object.
+ invoked directly from ` :func:`_expression.select` object or :class:`_query.Query` object.
- This change is part of the larger change to convert :func:`~.sql.expression.select` objects
+ This change is part of the larger change to convert :func:`_expression.select` objects
to no longer be directly part of the "from clause" class hierarchy, which
also includes an overhaul of the clause coercion system.
:tags: bug, sql
:tickets: 4621
- The :class:`.Join` construct no longer considers the "onclause" as a source
+ The :class:`_expression.Join` construct no longer considers the "onclause" as a source
of additional FROM objects to be omitted from the FROM list of an enclosing
- :class:`.Select` object as standalone FROM objects. This applies to an ON
+ :class:`_expression.Select` object as standalone FROM objects. This applies to an ON
clause that includes a reference to another FROM object outside the JOIN;
while this is usually not correct from a SQL perspective, it's also
incorrect for it to be omitted, and the behavioral change makes the
- :class:`.Select` / :class:`.Join` behave a bit more intuitively.
+ :class:`_expression.Select` / :class:`_expression.Join` behave a bit more intuitively.
:tickets: 4643
Remove deprecated method ``get_primary_keys` in the :class:`.Dialect` and
- :class:`.Inspector` classes. Please refer to the
- :meth:`.Dialect.get_pk_constraint` and :meth:`.Inspector.get_primary_keys`
+ :class:`_reflection.Inspector` classes. Please refer to the
+ :meth:`.Dialect.get_pk_constraint` and :meth:`_reflection.Inspector.get_primary_keys`
methods.
Remove deprecated event ``dbapi_error`` and the method
maintaining strong identity references.
This change also removes the class ``StrongInstanceDict``.
- Remove deprecated parameter ``mapper.order_by``. Use :meth:`.Query.order_by`
+ Remove deprecated parameter ``mapper.order_by``. Use :meth:`_query.Query.order_by`
to determine the ordering of a result set.
Remove deprecated parameter ``Session._enable_transaction_accounting`.
``ClauseElement.__or__`` and attribute ``Over.func``.
Remove deprecated ``FromClause.count`` method. Please use the
- :class:`.functions.count` function available from the
+ :class:`_functions.count` function available from the
:attr:`.func` namespace.
.. change::
:tickets: 4643
Remove deprecated parameters ``text.bindparams`` and ``text.typemap``.
- Please refer to the :meth:`.TextClause.bindparams` and
- :meth:`.TextClause.columns` methods.
+ Please refer to the :meth:`_expression.TextClause.bindparams` and
+ :meth:`_expression.TextClause.columns` methods.
Remove deprecated parameter ``Table.useexisting``. Please use
- :paramref:`.Table.extend_existing`.
+ :paramref:`_schema.Table.extend_existing`.
:tags: change, orm
:tickets: 4710
- The "KeyedTuple" class returned by :class:`.Query` is now replaced with the
+ The "KeyedTuple" class returned by :class:`_query.Query` is now replaced with the
Core :class:`.Row` class, which behaves in the same way as KeyedTuple.
In SQLAlchemy 2.0, both Core and ORM will return result rows using the same
:class:`.Row` object. In the interim, Core uses a backwards-compatibility
:tags: bug, engine
:tickets: 4712
- The :class:`.Connection` object will now not clear a rolled-back
+ The :class:`_engine.Connection` object will now not clear a rolled-back
transaction until the outermost transaction is explicitly rolled back.
This is essentially the same behavior that the ORM :class:`.Session` has
had for a long time, where an explicit call to ``.rollback()`` on all
:tags: bug, orm
:tickets: 4719
- Calling the :meth:`.Query.instances` method without passing a
+ Calling the :meth:`_query.Query.instances` method without passing a
:class:`.QueryContext` is deprecated. The original use case for this was
- that a :class:`.Query` could yield ORM objects when given only the entities
+ that a :class:`_query.Query` could yield ORM objects when given only the entities
to be selected as well as a DBAPI cursor object. However, for this to work
correctly there is essential metadata that is passed from a SQLAlchemy
:class:`.ResultProxy` that is derived from the mapped column expressions,
which comes originally from the :class:`.QueryContext`. To retrieve ORM
- results from arbitrary SELECT statements, the :meth:`.Query.from_statement`
+ results from arbitrary SELECT statements, the :meth:`_query.Query.from_statement`
method should be used.
:tags: change,engine
:tickets: 4753
- The :func:`~.sql.expression.select` construct and related constructs now allow for
+ The :func:`_expression.select` construct and related constructs now allow for
duplication of column labels and columns themselves in the columns clause,
mirroring exactly how column expressions were passed in. This allows
the tuples returned by an executed result to match what was SELECTed
- for in the first place, which is how the ORM :class:`.Query` works, so
+ for in the first place, which is how the ORM :class:`_query.Query` works, so
this establishes better cross-compatibility between the two constructs.
Additionally, it allows column-positioning-sensitive structures such as
- UNIONs (i.e. :class:`.CompoundSelect`) to be more intuitively constructed
+ UNIONs (i.e. :class:`_selectable.CompoundSelect`) to be more intuitively constructed
in those cases where a particular column might appear in more than one
- place. To support this change, the :class:`.ColumnCollection` has been
+ place. To support this change, the :class:`_expression.ColumnCollection` has been
revised to support duplicate columns as well as to allow integer index
access.
:tickets: 4755
Deprecated remaining engine-level introspection and utility methods
- including :meth:`.Engine.run_callable`, :meth:`.Engine.transaction`,
- :meth:`.Engine.table_names`, :meth:`.Engine.has_table`. The utility
+ including :meth:`_engine.Engine.run_callable`, :meth:`_engine.Engine.transaction`,
+ :meth:`_engine.Engine.table_names`, :meth:`_engine.Engine.has_table`. The utility
methods are superseded by modern context-manager patterns, and the table
- introspection tasks are suited by the :class:`.Inspector` object.
+ introspection tasks are suited by the :class:`_reflection.Inspector` object.
.. change::
:tags: changed, engine
:tags: feature, engine
:tickets: 4755
- The :paramref:`.Table.autoload_with` parameter now accepts an :class:`.Inspector` object
- directly, as well as any :class:`.Engine` or :class:`.Connection` as was the case before.
+ The :paramref:`_schema.Table.autoload_with` parameter now accepts an :class:`_reflection.Inspector` object
+ directly, as well as any :class:`_engine.Engine` or :class:`_engine.Connection` as was the case before.
:tags: bug, orm
:tickets: 4829
- Added new entity-targeting capabilities to the :class:`.Query` object to
+ Added new entity-targeting capabilities to the :class:`_query.Query` object to
help with the case where the :class:`.Session` is using a bind dictionary
- against mapped classes, rather than a single bind, and the :class:`.Query`
+ against mapped classes, rather than a single bind, and the :class:`_query.Query`
is against a Core statement that was ultimately generated from a method
- such as :meth:`.Query.subquery`; a deep search is performed to locate
+ such as :meth:`_query.Query.subquery`; a deep search is performed to locate
any ORM entity related to the query in order to locate a mapper if
one is not otherwise present.
:tags: bug, engine
:tickets: 4877
- Deprecated the behavior by which a :class:`.Column` can be used as the key
- in a result set row lookup, when that :class:`.Column` is not part of the
+ Deprecated the behavior by which a :class:`_schema.Column` can be used as the key
+ in a result set row lookup, when that :class:`_schema.Column` is not part of the
SQL selectable that is being selected; that is, it is only matched on name.
A deprecation warning is now emitted for this case. Various ORM use
- cases, such as those involving :func:`.text` constructs, have been improved
+ cases, such as those involving :func:`_expression.text` constructs, have been improved
so that this fallback logic is avoided in most cases.
:tags: bug, oracle
:tickets: 4971
- The :class:`.oracle.INTERVAL` class of the Oracle dialect is now correctly
+ The :class:`_oracle.INTERVAL` class of the Oracle dialect is now correctly
a subclass of the abstract version of :class:`.Interval` as well as the
correct "emulated" base class, which allows for correct behavior under both
native and non-native modes; previously it was only based on
Added support for use of the :class:`.Sequence` construct with MariaDB 10.3
and greater, as this is now supported by this database. The construct
- integrates with the :class:`.Table` object in the same way that it does for
+ integrates with the :class:`_schema.Table` object in the same way that it does for
other databases like PostrgreSQL and Oracle; if is present on the integer
primary key "autoincrement" column, it is used to generate defaults. For
- backwards compatibility, to support a :class:`.Table` that has a
+ backwards compatibility, to support a :class:`_schema.Table` that has a
:class:`.Sequence` on it to support sequence only databases like Oracle,
while still not having the sequence fire off for MariaDB, the optional=True
flag should be set, which indicates the sequence should only be used to
:tags: bug, mssql
:tickets: 4980
- Fixed the base class of the :class:`.mssql.DATETIMEOFFSET` datatype to
+ Fixed the base class of the :class:`_mssql.DATETIMEOFFSET` datatype to
be based on the :class:`.DateTime` class hierarchy, as this is a
datetime-holding datatype.
:tickets: 4994
An error is raised if any persistence-related "cascade" settings are made
- on a :func:`.relationship` that also sets up viewonly=True. The "cascade"
+ on a :func:`_orm.relationship` that also sets up viewonly=True. The "cascade"
settings now default to non-persistence related settings only when viewonly
is also set. This is the continuation from :ticket:`4993` where this
setting was changed to emit a warning in 1.3.
:tickets: 5001
Fixed issue where when constructing constraints from ORM-bound columns,
- primarily :class:`.ForeignKey` objects but also :class:`.UniqueConstraint`,
+ primarily :class:`_schema.ForeignKey` objects but also :class:`.UniqueConstraint`,
:class:`.CheckConstraint` and others, the ORM-level
:class:`.InstrumentedAttribute` is discarded entirely, and all ORM-level
annotations from the columns are removed; this is so that the constraints
will be emitted when the :class:`.Session` first requires a
:class:`.SessionTransaction` be present, rather than whenever the
:class:`.Session` were created or the previous :class:`.SessionTransaction`
- were closed. Interactions with the :class:`.Engine` and the database
+ were closed. Interactions with the :class:`_engine.Engine` and the database
itself remain unaffected.
.. seealso::
:tickets: 5122
A query that is against a mapped inheritance subclass which also uses
- :meth:`.Query.select_entity_from` or a similar technique in order to
+ :meth:`_query.Query.select_entity_from` or a similar technique in order to
provide an existing subquery to SELECT from, will now raise an error if the
given subquery returns entities that do not correspond to the given
subclass, that is, they are sibling or superclasses in the same hierarchy.
Previously, these would be returned without error. Additionally, if the
inheritance mapping is a single-inheritance mapping, the given subquery
must apply the appropriate filtering against the polymorphic discriminator
- column in order to avoid this error; previously, the :class:`.Query` would
+ column in order to avoid this error; previously, the :class:`_query.Query` would
add this criteria to the outside query however this interferes with some
kinds of query that return other kinds of entities as well.
:tags: usecase, engine
:tickets: 5131
- The :meth:`.Connection.connect` method is deprecated as is the concept of
- "connection branching", which copies a :class:`.Connection` into a new one
+ The :meth:`_engine.Connection.connect` method is deprecated as is the concept of
+ "connection branching", which copies a :class:`_engine.Connection` into a new one
that has a no-op ".close()" method. This pattern is oriented around the
"connectionless execution" concept which is also being removed in 2.0.
:tags: orm, bug
:tickets: 5134
- Deprecated logic in :meth:`.Query.distinct` that automatically adds
+ Deprecated logic in :meth:`_query.Query.distinct` that automatically adds
columns in the ORDER BY clause to the columns clause; this will be removed
in 2.0.
and are not otherwise in an inheriting sibling/overriding arrangement, and
will populate the same foreign key column, a warning is emitted at mapper
configuration time warning that a conflict may arise. A new parameter
- :paramref:`.relationship.overlaps` is added to suit those very rare cases
+ :paramref:`_orm.relationship.overlaps` is added to suit those very rare cases
where such an overlapping persistence arrangement may be unavoidable.
:tickets: 5192
The :func:`.eagerload` and :func:`.relation` were old aliases and are
- now deprecated. Use :func:`.joinedload` and :func:`.relationship`
+ now deprecated. Use :func:`_orm.joinedload` and :func:`_orm.relationship`
respectively.
:tickets: 5221
Enhanced the disambiguating labels feature of the
- :func:`~.sql.expression.select` construct such that when a select statement
+ :func:`_expression.select` construct such that when a select statement
is used in a subquery, repeated column names from different tables are now
automatically labeled with a unique label name, without the need to use the
full "apply_labels()" feature that conbines tablename plus column name.
The disambigated labels are available as plain string keys in the .c
collection of the subquery, and most importantly the feature allows an ORM
- :func:`.orm.aliased` construct against the combination of an entity and an
+ :func:`_orm.aliased` construct against the combination of an entity and an
arbitrary subquery to work correctly, targeting the correct columns despite
same-named columns in the source tables, without the need for an "apply
labels" warning.
:ref:`migration_20_query_from_self` - Illustrates the new
disambiguation feature as part of a strategy to migrate away from the
- :meth:`.Query.from_self` method.
\ No newline at end of file
+ :meth:`_query.Query.from_self` method.
\ No newline at end of file
:tags: change, reflection
:tickets: 5244
- The :meth:`.Inspector.reflecttable` was renamed to
- :meth:`.Inspector.reflect_table`.
\ No newline at end of file
+ The :meth:`_reflection.Inspector.reflecttable` was renamed to
+ :meth:`_reflection.Inspector.reflect_table`.
\ No newline at end of file
The :meth:`.Index.create` and :meth:`.Index.drop` methods now have a
parameter :paramref:`.Index.create.checkfirst`, in the same way as that of
- :class:`.Table` and :class:`.Sequence`, which when enabled will cause the
+ :class:`_schema.Table` and :class:`.Sequence`, which when enabled will cause the
operation to detect if the index exists (or not) before performing a create
or drop operation.
:tags: usecase, sql
The :func:`.true` and :func:`.false` operators may now be applied as the
- "onclause" of a :func:`.sql.join` on a backend that does not support
+ "onclause" of a :func:`_expression.join` on a backend that does not support
"native boolean" expressions, e.g. Oracle or SQL Server, and the expression
will render as "1=1" for true and "1=0" false. This is the behavior that
was introduced many years ago in :ticket:`2804` for and/or expressions.
.. module:: sqlalchemy.engine
-This section details direct usage of the :class:`.Engine`,
-:class:`.Connection`, and related objects. Its important to note that when
+This section details direct usage of the :class:`_engine.Engine`,
+:class:`_engine.Connection`, and related objects. Its important to note that when
using the SQLAlchemy ORM, these objects are not generally accessed; instead,
the :class:`.Session` object is used as the interface to the database.
However, for applications that are built around direct usage of textual SQL
statements and/or SQL expression constructs without involvement by the ORM's
-higher level management services, the :class:`.Engine` and
-:class:`.Connection` are king (and queen?) - read on.
+higher level management services, the :class:`_engine.Engine` and
+:class:`_engine.Connection` are king (and queen?) - read on.
Basic Usage
===========
-Recall from :doc:`/core/engines` that an :class:`.Engine` is created via
+Recall from :doc:`/core/engines` that an :class:`_engine.Engine` is created via
the :func:`.create_engine` call::
engine = create_engine('mysql://scott:tiger@localhost/test')
The typical usage of :func:`.create_engine()` is once per particular database
URL, held globally for the lifetime of a single application process. A single
-:class:`.Engine` manages many individual :term:`DBAPI` connections on behalf of
+:class:`_engine.Engine` manages many individual :term:`DBAPI` connections on behalf of
the process and is intended to be called upon in a concurrent fashion. The
-:class:`.Engine` is **not** synonymous to the DBAPI ``connect`` function, which
-represents just one connection resource - the :class:`.Engine` is most
+:class:`_engine.Engine` is **not** synonymous to the DBAPI ``connect`` function, which
+represents just one connection resource - the :class:`_engine.Engine` is most
efficient when created just once at the module level of an application, not
per-object or per-function call.
.. sidebar:: tip
- When using an :class:`.Engine` with multiple Python processes, such as when
+ When using an :class:`_engine.Engine` with multiple Python processes, such as when
using ``os.fork`` or Python ``multiprocessing``, it's important that the
engine is initialized per process. See :ref:`pooling_multiprocessing` for
details.
-The most basic function of the :class:`.Engine` is to provide access to a
-:class:`.Connection`, which can then invoke SQL statements. To emit
+The most basic function of the :class:`_engine.Engine` is to provide access to a
+:class:`_engine.Connection`, which can then invoke SQL statements. To emit
a textual statement to the database looks like::
from sqlalchemy import text
for row in result:
print("username:", row['username'])
-Above, the :meth:`.Engine.connect` method returns a :class:`.Connection`
+Above, the :meth:`_engine.Engine.connect` method returns a :class:`_engine.Connection`
object, and by using it in a Python context manager (e.g. the ``with:``
-statement) the :meth:`.Connection.close` method is automatically invoked at the
-end of the block. The :class:`.Connection`, is a **proxy** object for an
+statement) the :meth:`_engine.Connection.close` method is automatically invoked at the
+end of the block. The :class:`_engine.Connection`, is a **proxy** object for an
actual DBAPI connection. The DBAPI connection is retrieved from the connection
-pool at the point at which :class:`.Connection` is created.
+pool at the point at which :class:`_engine.Connection` is created.
The object returned is known as :class:`.ResultProxy`, which
references a DBAPI cursor and provides methods for fetching rows
an UPDATE statement (without any returned rows),
releases cursor resources immediately upon construction.
-When the :class:`.Connection` is closed at the end of the ``with:`` block, the
+When the :class:`_engine.Connection` is closed at the end of the ``with:`` block, the
referenced DBAPI connection is :term:`released` to the connection pool. From
the perspective of the database itself, the connection pool will not actually
"close" the connection assuming the pool has room to store this connection for
2.0 with a newly refined object known as :class:`.future.Result`.
Our example above illustrated the execution of a textual SQL string, which
-should be invoked by using the :func:`.text` construct to indicate that
-we'd like to use textual SQL. The :meth:`~.Connection.execute` method can of
+should be invoked by using the :func:`_expression.text` construct to indicate that
+we'd like to use textual SQL. The :meth:`_engine.Connection.execute` method can of
course accommodate more than that, including the variety of SQL expression
constructs described in :ref:`sqlexpression_toplevel`.
.. note::
This section describes how to use transactions when working directly
- with :class:`.Engine` and :class:`.Connection` objects. When using the
+ with :class:`_engine.Engine` and :class:`_engine.Connection` objects. When using the
SQLAlchemy ORM, the public API for transaction control is via the
:class:`.Session` object, which makes usage of the :class:`.Transaction`
object internally. See :ref:`unitofwork_transaction` for further
information.
-The :class:`~sqlalchemy.engine.Connection` object provides a :meth:`~.Connection.begin`
-method which returns a :class:`.Transaction` object. Like the :class:`.Connection`
+The :class:`~sqlalchemy.engine.Connection` object provides a :meth:`_engine.Connection.begin`
+method which returns a :class:`.Transaction` object. Like the :class:`_engine.Connection`
itself, this object is usually used within a Python ``with:`` block so
that its scope is managed::
r1 = connection.execute(table1.select())
connection.execute(table1.insert(), {"col1": 7, "col2": "this is some data"})
-The above block can be stated more simply by using the :meth:`.Engine.begin`
-method of :class:`.Engine`::
+The above block can be stated more simply by using the :meth:`_engine.Engine.begin`
+method of :class:`_engine.Engine`::
# runs a transaction
with engine.begin() as connection:
The underlying object used to represent the transaction is the
:class:`.Transaction` object. This object is returned by the
-:meth:`.Connection.begin` method and includes the methods
+:meth:`_engine.Connection.begin` method and includes the methods
:meth:`.Transaction.commit` and :meth:`.Transaction.rollback`. The context
manager calling form, which invokes these methods automatically, is recommended
as a best practice.
The :class:`.Transaction` object also handles "nested" behavior by keeping
track of the outermost begin/commit pair. In this example, two functions both
-issue a transaction on a :class:`.Connection`, but only the outermost
+issue a transaction on a :class:`_engine.Connection`, but only the outermost
:class:`.Transaction` object actually takes effect when it is committed.
.. sourcecode:: python+sql
ongoing :class:`.Transaction`.
Full control of the "autocommit" behavior is available using the generative
-:meth:`.Connection.execution_options` method provided on :class:`.Connection`
-and :class:`.Engine`, using the "autocommit" flag which will
+:meth:`_engine.Connection.execution_options` method provided on :class:`_engine.Connection`
+and :class:`_engine.Engine`, using the "autocommit" flag which will
turn on or off the autocommit for the selected scope. For example, a
-:func:`.text` construct representing a stored procedure that commits might use
+:func:`_expression.text` construct representing a stored procedure that commits might use
it so that a SELECT statement will issue a COMMIT::
with engine.connect().execution_options(autocommit=True) as conn:
:ref:`migration_20_implicit_execution` for background.
Recall from the first section we mentioned executing with and without explicit
-usage of :class:`.Connection`. "Connectionless" execution
+usage of :class:`_engine.Connection`. "Connectionless" execution
refers to the usage of the ``execute()`` method on an object
-which is not a :class:`.Connection`. This was illustrated using the
-:meth:`~.Engine.execute` method of :class:`.Engine`::
+which is not a :class:`_engine.Connection`. This was illustrated using the
+:meth:`_engine.Engine.execute` method of :class:`_engine.Engine`::
result = engine.execute(text("select username from users"))
for row in result:
to use the :meth:`~.Executable.execute` method of
any :class:`.Executable` construct, which is a marker for SQL expression objects
that support execution. The SQL expression object itself references an
-:class:`.Engine` or :class:`.Connection` known as the **bind**, which it uses
+:class:`_engine.Engine` or :class:`_engine.Connection` known as the **bind**, which it uses
in order to provide so-called "implicit" execution services.
Given a table as below::
)
Explicit execution delivers the SQL text or constructed SQL expression to the
-:meth:`~.Connection.execute` method of :class:`~sqlalchemy.engine.Connection`:
+:meth:`_engine.Connection.execute` method of :class:`~sqlalchemy.engine.Connection`:
.. sourcecode:: python+sql
# ....
Explicit, connectionless execution delivers the expression to the
-:meth:`~.Engine.execute` method of :class:`~sqlalchemy.engine.Engine`:
+:meth:`_engine.Engine.execute` method of :class:`~sqlalchemy.engine.Engine`:
.. sourcecode:: python+sql
the assumption that either an
:class:`~sqlalchemy.engine.Engine` or
:class:`~sqlalchemy.engine.Connection` has been **bound** to the expression
-object. By "bound" we mean that the special attribute :attr:`.MetaData.bind`
+object. By "bound" we mean that the special attribute :attr:`_schema.MetaData.bind`
has been used to associate a series of
-:class:`.Table` objects and all SQL constructs derived from them with a specific
+:class:`_schema.Table` objects and all SQL constructs derived from them with a specific
engine::
engine = create_engine('sqlite:///file.db')
# ....
result.close()
-Above, we associate an :class:`.Engine` with a :class:`.MetaData` object using
-the special attribute :attr:`.MetaData.bind`. The :func:`~.sql.expression.select` construct produced
-from the :class:`.Table` object has a method :meth:`~.Executable.execute`, which will
-search for an :class:`.Engine` that's "bound" to the :class:`.Table`.
+Above, we associate an :class:`_engine.Engine` with a :class:`_schema.MetaData` object using
+the special attribute :attr:`_schema.MetaData.bind`. The :func:`_expression.select` construct produced
+from the :class:`_schema.Table` object has a method :meth:`~.Executable.execute`, which will
+search for an :class:`_engine.Engine` that's "bound" to the :class:`_schema.Table`.
Overall, the usage of "bound metadata" has three general effects:
* SQL statement objects gain an :meth:`.Executable.execute` method which automatically
locates a "bind" with which to execute themselves.
* The ORM :class:`.Session` object supports using "bound metadata" in order
- to establish which :class:`.Engine` should be used to invoke SQL statements
+ to establish which :class:`_engine.Engine` should be used to invoke SQL statements
on behalf of a particular mapped class, though the :class:`.Session`
- also features its own explicit system of establishing complex :class:`.Engine`/
+ also features its own explicit system of establishing complex :class:`_engine.Engine`/
mapped class configurations.
-* The :meth:`.MetaData.create_all`, :meth:`.MetaData.drop_all`, :meth:`.Table.create`,
- :meth:`.Table.drop`, and "autoload" features all make usage of the bound
- :class:`.Engine` automatically without the need to pass it explicitly.
+* The :meth:`_schema.MetaData.create_all`, :meth:`_schema.MetaData.drop_all`, :meth:`_schema.Table.create`,
+ :meth:`_schema.Table.drop`, and "autoload" features all make usage of the bound
+ :class:`_engine.Engine` automatically without the need to pass it explicitly.
.. note::
While they offer some convenience, they are no longer required by any API and
are never necessary.
- In applications where multiple :class:`.Engine` objects are present, each one logically associated
+ In applications where multiple :class:`_engine.Engine` objects are present, each one logically associated
with a certain set of tables (i.e. *vertical sharding*), the "bound metadata" technique can be used
- so that individual :class:`.Table` can refer to the appropriate :class:`.Engine` automatically;
+ so that individual :class:`_schema.Table` can refer to the appropriate :class:`_engine.Engine` automatically;
in particular this is supported within the ORM via the :class:`.Session` object
- as a means to associate :class:`.Table` objects with an appropriate :class:`.Engine`,
+ as a means to associate :class:`_schema.Table` objects with an appropriate :class:`_engine.Engine`,
as an alternative to using the bind arguments accepted directly by the :class:`.Session`.
However, the "implicit execution" technique is not at all appropriate for use with the
:class:`~sqlalchemy.engine.ResultProxy` returned by the ``execute()``
call references the :class:`~sqlalchemy.engine.Connection` used to issue
the SQL statement. When the :class:`.ResultProxy` is closed, the underlying
-:class:`.Connection` is closed for us, resulting in the
+:class:`_engine.Connection` is closed for us, resulting in the
DBAPI connection being returned to the pool with transactional resources removed.
.. _schema_translating:
To support multi-tenancy applications that distribute common sets of tables
into multiple schemas, the
:paramref:`.Connection.execution_options.schema_translate_map`
-execution option may be used to repurpose a set of :class:`.Table` objects
+execution option may be used to repurpose a set of :class:`_schema.Table` objects
to render under different schema names without any changes.
Given a table::
Column('name', String(50))
)
-The "schema" of this :class:`.Table` as defined by the
-:paramref:`.Table.schema` attribute is ``None``. The
+The "schema" of this :class:`_schema.Table` as defined by the
+:paramref:`_schema.Table.schema` attribute is ``None``. The
:paramref:`.Connection.execution_options.schema_translate_map` can specify
-that all :class:`.Table` objects with a schema of ``None`` would instead
+that all :class:`_schema.Table` objects with a schema of ``None`` would instead
render the schema as ``user_schema_one``::
connection = engine.connect().execution_options(
The :paramref:`.Connection.execution_options.schema_translate_map` parameter
affects all DDL and SQL constructs generated from the SQL expression language,
-as derived from the :class:`.Table` or :class:`.Sequence` objects.
-It does **not** impact literal string SQL used via the :func:`.expression.text`
-construct nor via plain strings passed to :meth:`.Connection.execute`.
+as derived from the :class:`_schema.Table` or :class:`.Sequence` objects.
+It does **not** impact literal string SQL used via the :func:`_expression.text`
+construct nor via plain strings passed to :meth:`_engine.Connection.execute`.
The feature takes effect **only** in those cases where the name of the
-schema is derived directly from that of a :class:`.Table` or :class:`.Sequence`;
+schema is derived directly from that of a :class:`_schema.Table` or :class:`.Sequence`;
it does not impact methods where a string schema name is passed directly.
By this pattern, it takes effect within the "can create" / "can drop" checks
-performed by methods such as :meth:`.MetaData.create_all` or
-:meth:`.MetaData.drop_all` are called, and it takes effect when
-using table reflection given a :class:`.Table` object. However it does
-**not** affect the operations present on the :class:`.Inspector` object,
+performed by methods such as :meth:`_schema.MetaData.create_all` or
+:meth:`_schema.MetaData.drop_all` are called, and it takes effect when
+using table reflection given a :class:`_schema.Table` object. However it does
+**not** affect the operations present on the :class:`_reflection.Inspector` object,
as the schema name is passed to these methods explicitly.
.. versionadded:: 1.1
Engine Disposal
===============
-The :class:`.Engine` refers to a connection pool, which means under normal
+The :class:`_engine.Engine` refers to a connection pool, which means under normal
circumstances, there are open database connections present while the
-:class:`.Engine` object is still resident in memory. When an :class:`.Engine`
+:class:`_engine.Engine` object is still resident in memory. When an :class:`_engine.Engine`
is garbage collected, its connection pool is no longer referred to by
-that :class:`.Engine`, and assuming none of its connections are still checked
+that :class:`_engine.Engine`, and assuming none of its connections are still checked
out, the pool and its connections will also be garbage collected, which has the
effect of closing out the actual database connections as well. But otherwise,
-the :class:`.Engine` will hold onto open database connections assuming
+the :class:`_engine.Engine` will hold onto open database connections assuming
it uses the normally default pool implementation of :class:`.QueuePool`.
-The :class:`.Engine` is intended to normally be a permanent
+The :class:`_engine.Engine` is intended to normally be a permanent
fixture established up-front and maintained throughout the lifespan of an
application. It is **not** intended to be created and disposed on a
per-connection basis; it is instead a registry that maintains both a pool
resources.
However, there are many cases where it is desirable that all connection resources
-referred to by the :class:`.Engine` be completely closed out. It's
+referred to by the :class:`_engine.Engine` be completely closed out. It's
generally not a good idea to rely on Python garbage collection for this
-to occur for these cases; instead, the :class:`.Engine` can be explicitly disposed using
-the :meth:`.Engine.dispose` method. This disposes of the engine's
+to occur for these cases; instead, the :class:`_engine.Engine` can be explicitly disposed using
+the :meth:`_engine.Engine.dispose` method. This disposes of the engine's
underlying connection pool and replaces it with a new one that's empty.
-Provided that the :class:`.Engine`
+Provided that the :class:`_engine.Engine`
is discarded at this point and no longer used, all **checked-in** connections
which it refers to will also be fully closed.
-Valid use cases for calling :meth:`.Engine.dispose` include:
+Valid use cases for calling :meth:`_engine.Engine.dispose` include:
* When a program wants to release any remaining checked-in connections
held by the connection pool and expects to no longer be connected
to that database at all for any future operations.
* When a program uses multiprocessing or ``fork()``, and an
- :class:`.Engine` object is copied to the child process,
- :meth:`.Engine.dispose` should be called so that the engine creates
+ :class:`_engine.Engine` object is copied to the child process,
+ :meth:`_engine.Engine.dispose` should be called so that the engine creates
brand new database connections local to that fork. Database connections
generally do **not** travel across process boundaries.
* Within test suites or multitenancy scenarios where many
- ad-hoc, short-lived :class:`.Engine` objects may be created and disposed.
+ ad-hoc, short-lived :class:`_engine.Engine` objects may be created and disposed.
Connections that are **checked out** are **not** discarded when the
engine is disposed or garbage collected, as these connections are still
strongly referenced elsewhere by the application.
-However, after :meth:`.Engine.dispose` is called, those
-connections are no longer associated with that :class:`.Engine`; when they
+However, after :meth:`_engine.Engine.dispose` is called, those
+connections are no longer associated with that :class:`_engine.Engine`; when they
are closed, they will be returned to their now-orphaned connection pool
which will ultimately be garbage collected, once all connections which refer
to it are also no longer referenced anywhere.
Since this process is not easy to control, it is strongly recommended that
-:meth:`.Engine.dispose` is called only after all checked out connections
+:meth:`_engine.Engine.dispose` is called only after all checked out connections
are checked in or otherwise de-associated from their pool.
An alternative for applications that are negatively impacted by the
-:class:`.Engine` object's use of connection pooling is to disable pooling
+:class:`_engine.Engine` object's use of connection pooling is to disable pooling
entirely. This typically incurs only a modest performance impact upon the
use of new connections, and means that when a connection is checked in,
it is entirely closed out and is not held in memory. See :ref:`pool_switching`
Working with Driver SQL and Raw DBAPI Connections
=================================================
-The introduction on using :meth:`.Connection.execute` made use of the
-:func:`.sql.text` construct in order to illustrate how textual SQL statements
+The introduction on using :meth:`_engine.Connection.execute` made use of the
+:func:`_expression.text` construct in order to illustrate how textual SQL statements
may be invoked. When working with SQLAlchemy, textual SQL is actually more
of the exception rather than the norm, as the Core expression language
and the ORM both abstract away the textual representation of SQL. Hpwever, the
-:func:`.sql.text` construct itself also provides some abstraction of textual
+:func:`_expression.text` construct itself also provides some abstraction of textual
SQL in that it normalizes how bound parameters are passed, as well as that
it supports datatyping behavior for parameters and result set rows.
For the use case where one wants to invoke textual SQL directly passed to the
underlying driver (known as the :term:`DBAPI`) without any intervention
-from the :func:`.sql.text` construct, the :meth:`.Connection.exec_driver_sql`
+from the :func:`_expression.text` construct, the :meth:`_engine.Connection.exec_driver_sql`
method may be used::
with engine.connect() as conn:
conn.exec_driver_sql("SET param='bar'")
-.. versionadded:: 1.4 Added the :meth:`.Connection.exec_driver_sql` method.
+.. versionadded:: 1.4 Added the :meth:`_engine.Connection.exec_driver_sql` method.
Working with the DBAPI cursor directly
--------------------------------------
to deal with the raw DBAPI connection directly.
The most common way to access the raw DBAPI connection is to get it
-from an already present :class:`.Connection` object directly. It is
-present using the :attr:`.Connection.connection` attribute::
+from an already present :class:`_engine.Connection` object directly. It is
+present using the :attr:`_engine.Connection.connection` attribute::
connection = engine.connect()
dbapi_conn = connection.connection
The DBAPI connection here is actually a "proxied" in terms of the
originating connection pool, however this is an implementation detail
that in most cases can be ignored. As this DBAPI connection is still
-contained within the scope of an owning :class:`.Connection` object, it is
-best to make use of the :class:`.Connection` object for most features such
-as transaction control as well as calling the :meth:`.Connection.close`
+contained within the scope of an owning :class:`_engine.Connection` object, it is
+best to make use of the :class:`_engine.Connection` object for most features such
+as transaction control as well as calling the :meth:`_engine.Connection.close`
method; if these operations are performed on the DBAPI connection directly,
-the owning :class:`.Connection` will not be aware of these changes in state.
+the owning :class:`_engine.Connection` will not be aware of these changes in state.
To overcome the limitations imposed by the DBAPI connection that is
-maintained by an owning :class:`.Connection`, a DBAPI connection is also
+maintained by an owning :class:`_engine.Connection`, a DBAPI connection is also
available without the need to procure a
-:class:`.Connection` first, using the :meth:`.Engine.raw_connection` method
-of :class:`.Engine`::
+:class:`_engine.Connection` first, using the :meth:`_engine.Engine.raw_connection` method
+of :class:`_engine.Engine`::
dbapi_conn = engine.raw_connection()
================================
This section will discuss SQL :term:`constraints` and indexes. In SQLAlchemy
-the key classes include :class:`.ForeignKeyConstraint` and :class:`.Index`.
+the key classes include :class:`_schema.ForeignKeyConstraint` and :class:`.Index`.
.. _metadata_foreignkeys:
The ``CONSTRAINT .. FOREIGN KEY`` directive is used to create the constraint
in an "inline" fashion within the CREATE TABLE definition. The
-:meth:`.MetaData.create_all` and :meth:`.MetaData.drop_all` methods do
-this by default, using a topological sort of all the :class:`.Table` objects
+:meth:`_schema.MetaData.create_all` and :meth:`_schema.MetaData.drop_all` methods do
+this by default, using a topological sort of all the :class:`_schema.Table` objects
involved such that tables are created and dropped in order of their foreign
key dependency (this sort is also available via the
-:attr:`.MetaData.sorted_tables` accessor).
+:attr:`_schema.MetaData.sorted_tables` accessor).
This approach can't work when two or more foreign key constraints are
involved in a "dependency cycle", where a set of tables
)
)
-When we call upon :meth:`.MetaData.create_all` on a backend such as the
+When we call upon :meth:`_schema.MetaData.create_all` on a backend such as the
PostgreSQL backend, the cycle between these two tables is resolved and the
constraints are created separately:
in the CREATE case without a name; the database typically assigns one
automatically.
-The :paramref:`.ForeignKeyConstraint.use_alter` and
-:paramref:`.ForeignKey.use_alter` keyword arguments can be used
+The :paramref:`_schema.ForeignKeyConstraint.use_alter` and
+:paramref:`_schema.ForeignKey.use_alter` keyword arguments can be used
to manually resolve dependency cycles. We can add this flag only to
the ``'element'`` table as follows::
FOREIGN KEY(parent_node_id) REFERENCES node (node_id)
{stop}
-:paramref:`.ForeignKeyConstraint.use_alter` and
-:paramref:`.ForeignKey.use_alter`, when used in conjunction with a drop
+:paramref:`_schema.ForeignKeyConstraint.use_alter` and
+:paramref:`_schema.ForeignKey.use_alter`, when used in conjunction with a drop
operation, will require that the constraint is named, else an error
like the following is generated::
ForeignKeyConstraint(...); it has no name
.. versionchanged:: 1.0.0 - The DDL system invoked by
- :meth:`.MetaData.create_all`
- and :meth:`.MetaData.drop_all` will now automatically resolve mutually
+ :meth:`_schema.MetaData.create_all`
+ and :meth:`_schema.MetaData.drop_all` will now automatically resolve mutually
depdendent foreign keys between tables declared by
- :class:`.ForeignKeyConstraint` and :class:`.ForeignKey` objects, without
- the need to explicitly set the :paramref:`.ForeignKeyConstraint.use_alter`
+ :class:`_schema.ForeignKeyConstraint` and :class:`_schema.ForeignKey` objects, without
+ the need to explicitly set the :paramref:`_schema.ForeignKeyConstraint.use_alter`
flag.
-.. versionchanged:: 1.0.0 - The :paramref:`.ForeignKeyConstraint.use_alter`
+.. versionchanged:: 1.0.0 - The :paramref:`_schema.ForeignKeyConstraint.use_alter`
flag can be used with an un-named constraint; only the DROP operation
will emit a specific error when actually called upon.
PRIMARY KEY Constraint
----------------------
-The primary key constraint of any :class:`.Table` object is implicitly
-present, based on the :class:`.Column` objects that are marked with the
-:paramref:`.Column.primary_key` flag. The :class:`.PrimaryKeyConstraint`
+The primary key constraint of any :class:`_schema.Table` object is implicitly
+present, based on the :class:`_schema.Column` objects that are marked with the
+:paramref:`_schema.Column.primary_key` flag. The :class:`.PrimaryKeyConstraint`
object provides explicit access to this constraint, which includes the
option of being configured directly::
Setting up Constraints when using the Declarative ORM Extension
---------------------------------------------------------------
-The :class:`.Table` is the SQLAlchemy Core construct that allows one to define
+The :class:`_schema.Table` is the SQLAlchemy Core construct that allows one to define
table metadata, which among other things can be used by the SQLAlchemy ORM
as a target to map a class. The :ref:`Declarative <declarative_toplevel>`
-extension allows the :class:`.Table` object to be created automatically, given
-the contents of the table primarily as a mapping of :class:`.Column` objects.
+extension allows the :class:`_schema.Table` object to be created automatically, given
+the contents of the table primarily as a mapping of :class:`_schema.Column` objects.
-To apply table-level constraint objects such as :class:`.ForeignKeyConstraint`
+To apply table-level constraint objects such as :class:`_schema.ForeignKeyConstraint`
to a table defined using Declarative, use the ``__table_args__`` attribute,
described at :ref:`declarative_table_args`.
Constraints can be named explicitly using the :paramref:`.Constraint.name` parameter,
and for indexes the :paramref:`.Index.name` parameter. However, in the
case of constraints this parameter is optional. There are also the use
-cases of using the :paramref:`.Column.unique` and :paramref:`.Column.index`
+cases of using the :paramref:`_schema.Column.unique` and :paramref:`_schema.Column.index`
parameters which create :class:`.UniqueConstraint` and :class:`.Index` objects
without an explicit name being specified.
using events. This approach has the advantage that constraints will get
a consistent naming scheme without the need for explicit name parameters
throughout the code, and also that the convention takes place just as well
-for those constraints and indexes produced by the :paramref:`.Column.unique`
-and :paramref:`.Column.index` parameters. As of SQLAlchemy 0.9.2 this
+for those constraints and indexes produced by the :paramref:`_schema.Column.unique`
+and :paramref:`_schema.Column.index` parameters. As of SQLAlchemy 0.9.2 this
event-based approach is included, and can be configured using the argument
-:paramref:`.MetaData.naming_convention`.
+:paramref:`_schema.MetaData.naming_convention`.
-:paramref:`.MetaData.naming_convention` refers to a dictionary which accepts
+:paramref:`_schema.MetaData.naming_convention` refers to a dictionary which accepts
the :class:`.Index` class or individual :class:`.Constraint` classes as keys,
and Python string templates as values. It also accepts a series of
string-codes as alternative keys, ``"fk"``, ``"pk"``,
``"ix"``, ``"ck"``, ``"uq"`` for foreign key, primary key, index,
check, and unique constraint, respectively. The string templates in this
dictionary are used whenever a constraint or index is associated with this
-:class:`.MetaData` object that does not have an existing name given (including
+:class:`_schema.MetaData` object that does not have an existing name given (including
one exception case where an existing name can be further embellished).
An example naming convention that suits basic cases is as follows::
metadata = MetaData(naming_convention=convention)
The above convention will establish names for all constraints within
-the target :class:`.MetaData` collection.
+the target :class:`_schema.MetaData` collection.
For example, we can observe the name produced when we create an unnamed
:class:`.UniqueConstraint`::
>>> list(user_table.constraints)[1].name
'uq_user_name'
-This same feature takes effect even if we just use the :paramref:`.Column.unique`
+This same feature takes effect even if we just use the :paramref:`_schema.Column.unique`
flag::
>>> user_table = Table('user', metadata,
The above ``"uq_user_name"`` string was copied from the :class:`.UniqueConstraint`
object that ``--autogenerate`` located in our metadata.
-The default value for :paramref:`.MetaData.naming_convention` handles
+The default value for :paramref:`_schema.MetaData.naming_convention` handles
the long-standing SQLAlchemy behavior of assigning a name to a :class:`.Index`
-object that is created using the :paramref:`.Column.index` parameter::
+object that is created using the :paramref:`_schema.Column.index` parameter::
>>> from sqlalchemy.sql.schema import DEFAULT_NAMING_CONVENTION
>>> DEFAULT_NAMING_CONVENTION
multiple-column versions of each including ``%(column_0N_name)s``,
``%(column_0_N_name)s``, ``%(referred_column_0_N_name)s`` which render all
column names separated with or without an underscore. The documentation for
-:paramref:`.MetaData.naming_convention` has further detail on each of these
+:paramref:`_schema.MetaData.naming_convention` has further detail on each of these
conventions.
When a generated name, particularly those that use the multiple-column tokens,
"fk": "fk_%(fk_guid)s",
}
-Above, when we create a new :class:`.ForeignKeyConstraint`, we will get a
+Above, when we create a new :class:`_schema.ForeignKeyConstraint`, we will get a
name as follows::
>>> metadata = MetaData(naming_convention=convention)
.. seealso::
- :paramref:`.MetaData.naming_convention` - for additional usage details
+ :paramref:`_schema.MetaData.naming_convention` - for additional usage details
as well as a listing of all available naming components.
`The Importance of Naming Constraints <https://alembic.sqlalchemy.org/en/latest/naming.html>`_ - in the Alembic documentation.
)
:class:`.CheckConstraint` also supports the ``%(columns_0_name)s``
-token; we can make use of this by ensuring we use a :class:`.Column` or
-:func:`.sql.expression.column` element within the constraint's expression,
+token; we can make use of this by ensuring we use a :class:`_schema.Column` or
+:func:`_expression.column` element within the constraint's expression,
either by declaring the constraint separate from the table::
metadata = MetaData(
CheckConstraint(foo.c.value > 5)
-or by using a :func:`.sql.expression.column` inline::
+or by using a :func:`_expression.column` inline::
from sqlalchemy import column
CREATE INDEX idx_col34 ON mytable (col3, col4){stop}
Note in the example above, the :class:`.Index` construct is created
-externally to the table which it corresponds, using :class:`.Column`
+externally to the table which it corresponds, using :class:`_schema.Column`
objects directly. :class:`.Index` also supports
-"inline" definition inside the :class:`.Table`, using string names to
+"inline" definition inside the :class:`_schema.Table`, using string names to
identify columns::
meta = MetaData()
:class:`.Index` supports SQL and function expressions, as supported by the
target backend. To create an index against a column using a descending
-value, the :meth:`.ColumnElement.desc` modifier may be used::
+value, the :meth:`_expression.ColumnElement.desc` modifier may be used::
from sqlalchemy import Index
def compile_binary_sqlite(type_, compiler, **kw):
return "BLOB"
-The above code allows the usage of :class:`.types.BINARY`, which
+The above code allows the usage of :class:`_types.BINARY`, which
will produce the string ``BINARY`` against all backends except SQLite,
in which case it will produce ``BLOB``.
Any :class:`.TypeEngine`, :class:`.UserDefinedType` or :class:`.TypeDecorator` subclass
can include implementations of
:meth:`.TypeEngine.bind_expression` and/or :meth:`.TypeEngine.column_expression`, which
-when defined to return a non-``None`` value should return a :class:`.ColumnElement`
+when defined to return a non-``None`` value should return a :class:`_expression.ColumnElement`
expression to be injected into the SQL statement, either surrounding
bound parameters or a column expression. For example, to build a ``Geometry``
type which will apply the PostGIS function ``ST_GeomFromText`` to all outgoing
def column_expression(self, col):
return func.ST_AsText(col, type_=self)
-We can apply the ``Geometry`` type into :class:`.Table` metadata
-and use it in a :func:`~.sql.expression.select` construct::
+We can apply the ``Geometry`` type into :class:`_schema.Table` metadata
+and use it in a :func:`_expression.select` construct::
geometry = Table('geometry', metadata,
Column('geom_id', Integer, primary_key=True),
The :meth:`.TypeEngine.column_expression` method interacts with the
mechanics of the compiler such that the SQL expression does not interfere
with the labeling of the wrapped expression. Such as, if we rendered
-a :func:`~.sql.expression.select` against a :func:`.label` of our expression, the string
+a :func:`_expression.select` against a :func:`.label` of our expression, the string
label is moved to the outside of the wrapped expression::
print(select([geometry.c.geom_data.label('my_data')]))
FROM geometry
Another example is we decorate
-:class:`.postgresql.BYTEA` to provide a ``PGPString``, which will make use of the
+:class:`_postgresql.BYTEA` to provide a ``PGPString``, which will make use of the
PostgreSQL ``pgcrypto`` extension to encrypt/decrypt values
transparently::
New methods added to a :class:`.TypeEngine.Comparator` are exposed on an
owning SQL expression
using a ``__getattr__`` scheme, which exposes methods added to
-:class:`.TypeEngine.Comparator` onto the owning :class:`.ColumnElement`.
+:class:`.TypeEngine.Comparator` onto the owning :class:`_expression.ColumnElement`.
For example, to add a ``log()`` function
to integers::
PostgreSQL dialect has a hardcoded mapping which links the string name
``"VARCHAR"`` to the SQLAlchemy :class:`.VARCHAR` class, and that's how when we
emit a statement like ``Table('my_table', m, autoload_with=engine)``, the
-:class:`.Column` object within it would have an instance of :class:`.VARCHAR`
+:class:`_schema.Column` object within it would have an instance of :class:`.VARCHAR`
present inside of it.
-The implication of this is that if a :class:`.Table` object makes use of type
+The implication of this is that if a :class:`_schema.Table` object makes use of type
objects that don't correspond directly to the database-native type name, if we
-create a new :class:`.Table` object against a new :class:`.MetaData` collection
+create a new :class:`_schema.Table` object against a new :class:`_schema.MetaData` collection
for this database table elsewhere using reflection, it will not have this
datatype. For example::
>>> my_table.c.data.type
PickleType()
-However, if we create another instance of :class:`.Table` using reflection,
+However, if we create another instance of :class:`_schema.Table` using reflection,
the use of :class:`.PickleType` is not represented in the SQLite database we've
created; we instead get back :class:`.BLOB`::
>>> my_reflected_table.c.data.type
BLOB()
-Typically, when an application defines explicit :class:`.Table` metadata with
+Typically, when an application defines explicit :class:`_schema.Table` metadata with
custom types, there is no need to use table reflection because the necessary
-:class:`.Table` metadata is already present. However, for the case where an
+:class:`_schema.Table` metadata is already present. However, for the case where an
application, or a combination of them, need to make use of both explicit
-:class:`.Table` metadata which includes custom, Python-level datatypes, as well
-as :class:`.Table` objects which set up their :class:`.Column` objects as
+:class:`_schema.Table` metadata which includes custom, Python-level datatypes, as well
+as :class:`_schema.Table` objects which set up their :class:`_schema.Column` objects as
reflected from the database, which nevertheless still need to exhibit the
additional Python behaviors of the custom datatypes, additional steps must be
taken to allow this.
The most straightforward is to override specific columns as described at
:ref:`reflection_overriding_columns`. In this technique, we simply
-use reflection in combination with explicit :class:`.Column` objects for those
+use reflection in combination with explicit :class:`_schema.Column` objects for those
columns for which we want to use a custom or decorated datatype::
>>> metadata_three = MetaData()
The ``my_reflected_table`` object above is reflected, and will load the
definition of the "id" column from the SQLite database. But for the "data"
-column, we've overridden the reflected object with an explicit :class:`.Column`
+column, we've overridden the reflected object with an explicit :class:`_schema.Column`
definition that includes our desired in-Python datatype, the
-:class:`.PickleType`. The reflection process will leave this :class:`.Column`
+:class:`.PickleType`. The reflection process will leave this :class:`_schema.Column`
object intact::
>>> my_reflected_table.c.data.type
When the above code is invoked *before* any table reflection occurs (note also
it should be invoked **only once** in the application, as it is a global rule),
-upon reflecting any :class:`.Table` that includes a column with a :class:`.BLOB`
-datatype, the resulting datatype will be stored in the :class:`.Column` object
+upon reflecting any :class:`_schema.Table` that includes a column with a :class:`.BLOB`
+datatype, the resulting datatype will be stored in the :class:`_schema.Column` object
as :class:`.PickleType`.
In practice, the above event-based approach would likely have additional rules
Controlling DDL Sequences
-------------------------
-The :class:`~.schema.DDL` construct introduced previously also has the
+The :class:`_schema.DDL` construct introduced previously also has the
ability to be invoked conditionally based on inspection of the
database. This feature is available using the :meth:`.DDLElement.execute_if`
method. For example, if we wanted to create a trigger but only on
:ref:`schema_ddl_sequences` is available with other :class:`.DDLElement`
objects as well. However, when dealing with the built-in constructs
such as :class:`.CreateIndex`, :class:`.CreateSequence`, etc, the event
-system is of **limited** use, as methods like :meth:`.Table.create` and
-:meth:`.MetaData.create_all` will invoke these constructs unconditionally.
+system is of **limited** use, as methods like :meth:`_schema.Table.create` and
+:meth:`_schema.MetaData.create_all` will invoke these constructs unconditionally.
In a future SQLAlchemy release, the DDL event system including conditional
execution will taken into account for built-in constructs that currently
invoke in all cases.
and :class:`.DropConstraint` objects, the main usefulness of DDL events
for now remains focused on the use of the :class:`.DDL` construct itself,
as well as with user-defined subclasses of :class:`.DDLElement` that aren't
-already part of the :meth:`.MetaData.create_all`, :meth:`.Table.create`,
+already part of the :meth:`_schema.MetaData.create_all`, :meth:`_schema.Table.create`,
and corresponding "drop" processes.
.. _schema_api_ddl:
Python-Executed Functions
-------------------------
-The :paramref:`.Column.default` and :paramref:`.Column.onupdate` keyword arguments also accept Python
+The :paramref:`_schema.Column.default` and :paramref:`_schema.Column.onupdate` keyword arguments also accept Python
functions. These functions are invoked at the time of insert or update if no
other value for that column is supplied, and the value returned is used for
the column's value. Below illustrates a crude "sequence" that assigns an
include sequence objects or other autoincrementing capabilities. For primary
key columns, SQLAlchemy will in most cases use these capabilities
automatically. See the API documentation for
-:class:`~sqlalchemy.schema.Column` including the :paramref:`.Column.autoincrement` flag, as
+:class:`~sqlalchemy.schema.Column` including the :paramref:`_schema.Column.autoincrement` flag, as
well as the section on :class:`~sqlalchemy.schema.Sequence` later in this
chapter for background on standard primary key generation techniques.
To illustrate onupdate, we assign the Python ``datetime`` function ``now`` to
-the :paramref:`.Column.onupdate` attribute::
+the :paramref:`_schema.Column.onupdate` attribute::
import datetime
Context-Sensitive Default Functions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The Python functions used by :paramref:`.Column.default` and
-:paramref:`.Column.onupdate` may also make use of the current statement's
+The Python functions used by :paramref:`_schema.Column.default` and
+:paramref:`_schema.Column.onupdate` may also make use of the current statement's
context in order to determine a value. The `context` of a statement is an
internal SQLAlchemy object which contains all information about the statement
being executed, including its source expression, the parameters associated with
in the execution for the ``counter`` column, plus the number 12.
For a single statement that is being executed using "executemany" style, e.g.
-with multiple parameter sets passed to :meth:`.Connection.execute`, the user-
+with multiple parameter sets passed to :meth:`_engine.Connection.execute`, the user-
defined function is called once for each set of parameters. For the use case of
-a multi-valued :class:`~.sql.expression.Insert` construct (e.g. with more than one VALUES
-clause set up via the :meth:`.Insert.values` method), the user-defined function
+a multi-valued :class:`_expression.Insert` construct (e.g. with more than one VALUES
+clause set up via the :meth:`_expression.Insert.values` method), the user-defined function
is also called once for each set of parameters.
When the function is invoked, the special method
Client-Invoked SQL Expressions
------------------------------
-The :paramref:`.Column.default` and :paramref:`.Column.onupdate` keywords may
+The :paramref:`_schema.Column.default` and :paramref:`_schema.Column.onupdate` keywords may
also be passed SQL expressions, which are in most cases rendered inline within the
INSERT or UPDATE statement::
``func.now()`` returns the SQL expression object that will render the
"NOW" function into the SQL being emitted.
-Default and update SQL expressions specified by :paramref:`.Column.default` and
-:paramref:`.Column.onupdate` are invoked explicitly by SQLAlchemy when an
+Default and update SQL expressions specified by :paramref:`_schema.Column.default` and
+:paramref:`_schema.Column.onupdate` are invoked explicitly by SQLAlchemy when an
INSERT or UPDATE statement occurs, typically rendered inline within the DML
statement except in certain cases listed below. This is different than a
"server side" default, which is part of the table's DDL definition, e.g. as
part of the "CREATE TABLE" statement, which are likely more common. For
server side defaults, see the next section :ref:`server_defaults`.
-When a SQL expression indicated by :paramref:`.Column.default` is used with
+When a SQL expression indicated by :paramref:`_schema.Column.default` is used with
primary key columns, there are some cases where SQLAlchemy must "pre-execute"
the default generation SQL function, meaning it is invoked in a separate SELECT
statement, and the resulting value is passed as a parameter to the INSERT.
This only occurs for primary key columns for an INSERT statement that is being
asked to return this primary key value, where RETURNING or ``cursor.lastrowid``
-may not be used. An :class:`~.sql.expression.Insert` construct that specifies the
+may not be used. An :class:`_expression.Insert` construct that specifies the
:paramref:`~.expression.insert.inline` flag will always render default expressions
inline.
Server-invoked DDL-Explicit Default Expressions
-----------------------------------------------
-A variant on the SQL expression default is the :paramref:`.Column.server_default`, which gets
-placed in the CREATE TABLE statement during a :meth:`.Table.create` operation:
+A variant on the SQL expression default is the :paramref:`_schema.Column.server_default`, which gets
+placed in the CREATE TABLE statement during a :meth:`_schema.Table.create` operation:
.. sourcecode:: python+sql
index_value integer default 0
)
-The above example illustrates the two typical use cases for :paramref:`.Column.server_default`,
+The above example illustrates the two typical use cases for :paramref:`_schema.Column.server_default`,
that of the SQL function (SYSDATE in the above example) as well as a server-side constant
value (the integer "0" in the above example). It is advisable to use the
-:func:`.text` construct for any literal SQL values as opposed to passing the
+:func:`_expression.text` construct for any literal SQL values as opposed to passing the
raw value, as SQLAlchemy does not typically perform any quoting or escaping on
these values.
-Like client-generated expressions, :paramref:`.Column.server_default` can accommodate
+Like client-generated expressions, :paramref:`_schema.Column.server_default` can accommodate
SQL expressions in general, however it is expected that these will usually be simple
functions and expressions, and not the more complex cases like an embedded SELECT.
part of a RETURNING or OUTPUT clause for the statement. Tools such as the
SQLAlchemy ORM then make use of this marker in order to know how to get at the
value of the column after such an operation. In particular, the
-:meth:`.ValuesBase.return_defaults` method can be used with an :class:`~.sql.expression.Insert`
-or :class:`.Update` construct to indicate that these values should be
+:meth:`.ValuesBase.return_defaults` method can be used with an :class:`_expression.Insert`
+or :class:`_expression.Update` construct to indicate that these values should be
returned.
For details on using :class:`.FetchedValue` with the ORM, see
RETURNING cart_id
When the :class:`~sqlalchemy.schema.Sequence` is associated with a
-:class:`.Column` as its **Python-side** default generator, the
+:class:`_schema.Column` as its **Python-side** default generator, the
:class:`.Sequence` will also be subject to "CREATE SEQUENCE" and "DROP
-SEQUENCE" DDL when similar DDL is emitted for the owning :class:`.Table`.
+SEQUENCE" DDL when similar DDL is emitted for the owning :class:`_schema.Table`.
This is a limited scope convenience feature that does not accommodate for
-inheritance of other aspects of the :class:`.MetaData`, such as the default
+inheritance of other aspects of the :class:`_schema.MetaData`, such as the default
schema. Therefore, it is best practice that for a :class:`.Sequence` which
-is local to a certain :class:`.Column` / :class:`.Table`, that it be
-explicitly associated with the :class:`.MetaData` using the
+is local to a certain :class:`_schema.Column` / :class:`_schema.Table`, that it be
+explicitly associated with the :class:`_schema.MetaData` using the
:paramref:`.Sequence.metadata` parameter. See the section
:ref:`sequence_metadata` for more background on this.
PostgreSQL's SERIAL datatype is an auto-incrementing type that implies
the implicit creation of a PostgreSQL sequence when CREATE TABLE is emitted.
-If a :class:`.Column` specifies an explicit :class:`.Sequence` object
+If a :class:`_schema.Column` specifies an explicit :class:`.Sequence` object
which also specifies a true value for the :paramref:`.Sequence.optional`
boolean flag, the :class:`.Sequence` will not take effect under PostgreSQL,
and the SERIAL datatype will proceed normally. Instead, the :class:`.Sequence`
While the above is a prominent idiomatic pattern, it is recommended that
the :class:`.Sequence` in most cases be explicitly associated with the
-:class:`.MetaData`, using the :paramref:`.Sequence.metadata` parameter::
+:class:`_schema.MetaData`, using the :paramref:`.Sequence.metadata` parameter::
table = Table("cartitems", meta,
Column(
The :class:`.Sequence` object is a first class
schema construct that can exist independently of any table in a database, and
can also be shared among tables. Therefore SQLAlchemy does not implicitly
-modify the :class:`.Sequence` when it is associated with a :class:`.Column`
+modify the :class:`.Sequence` when it is associated with a :class:`_schema.Column`
object as either the Python-side or server-side default generator. While the
CREATE SEQUENCE / DROP SEQUENCE DDL is emitted for a :class:`.Sequence`
defined as a Python side generator at the same time the table itself is subject
to CREATE or DROP, this is a convenience feature that does not imply that the
-:class:`.Sequence` is fully associated with the :class:`.MetaData` object.
+:class:`.Sequence` is fully associated with the :class:`_schema.MetaData` object.
-Explicitly associating the :class:`.Sequence` with :class:`.MetaData`
+Explicitly associating the :class:`.Sequence` with :class:`_schema.MetaData`
allows for the following behaviors:
-* The :class:`.Sequence` will inherit the :paramref:`.MetaData.schema`
- parameter specified to the target :class:`.MetaData`, which
+* 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:`.MetaData`
+ automatically use the engine bound to the :class:`_schema.MetaData`
object, if any.
-* The :meth:`.MetaData.create_all` and :meth:`.MetaData.drop_all`
+* 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:`.Table` / :class:`.Column` that's a member of this
- :class:`.MetaData`.
+ :class:`_schema.Table` / :class:`_schema.Column` that's a member of this
+ :class:`_schema.MetaData`.
Since the vast majority of cases that deal with :class:`.Sequence` expect
-that :class:`.Sequence` to be fully "owned" by the associated :class:`.Table`
+that :class:`.Sequence` to be fully "owned" by the associated :class:`_schema.Table`
and that options like default schema are propagated, setting the
:paramref:`.Sequence.metadata` parameter should be considered a best practice.
database. It does not work with Oracle.
The preceding sections illustrate how to associate a :class:`.Sequence` with a
-:class:`.Column` as the **Python side default generator**::
+:class:`_schema.Column` as the **Python side default generator**::
Column(
"cart_id", Integer, Sequence('cart_id_seq', metadata=meta),
primary_key=True)
In the above case, the :class:`.Sequence` will automatically be subject
-to CREATE SEQUENCE / DROP SEQUENCE DDL when the related :class:`.Table`
+to CREATE SEQUENCE / DROP SEQUENCE DDL when the related :class:`_schema.Table`
is subject to CREATE / DROP. However, the sequence will **not** be present
as the server-side default for the column when CREATE TABLE is emitted.
If we want the sequence to be used as a server-side default,
meaning it takes place even if we emit INSERT commands to the table from
-the SQL command line, we can use the :paramref:`.Column.server_default`
+the SQL command line, we can use the :paramref:`_schema.Column.server_default`
parameter in conjunction with the value-generation function of the
sequence, available from the :meth:`.Sequence.next_value` method. Below
we illustrate the same :class:`.Sequence` being associated with the
-:class:`.Column` both as the Python-side default generator as well as
+:class:`_schema.Column` both as the Python-side default generator as well as
the server-side default generator::
cart_id_seq = Sequence('cart_id_seq', metadata=meta)
included as the Python-side default generator function.
The example also associates the :class:`.Sequence` with the enclosing
-:class:`.MetaData` directly, which again ensures that the :class:`.Sequence`
-is fully associated with the parameters of the :class:`.MetaData` collection
+:class:`_schema.MetaData` directly, which again ensures that the :class:`.Sequence`
+is fully associated with the parameters of the :class:`_schema.MetaData` collection
including the default schema, if any.
.. seealso::
.. versionadded:: 1.3.11
-The :class:`.Computed` construct allows a :class:`.Column` to be declared in
+The :class:`.Computed` construct allows a :class:`_schema.Column` to be declared in
DDL as a "GENERATED ALWAYS AS" column, that is, one which has a value that is
computed by the database server. The construct accepts a SQL expression
-typically declared textually using a string or the :func:`.text` construct, in
+typically declared textually using a string or the :func:`_expression.text` construct, in
a similar manner as that of :class:`.CheckConstraint`. The SQL expression is
then interpreted by the database server in order to determine the value for the
column within a row.
The :class:`.Computed` construct is a subclass of the :class:`.FetchedValue`
object, and will set itself up as both the "server default" and "server
-onupdate" generator for the target :class:`.Column`, meaning it will be treated
+onupdate" generator for the target :class:`_schema.Column`, meaning it will be treated
as a default generating column when INSERT and UPDATE statements are generated,
as well as that it will be fetched as a generating column when using the ORM.
This includes that it will be part of the RETURNING clause of the database
for databases which support RETURNING and the generated values are to be
eagerly fetched.
-.. note:: A :class:`.Column` that is defined with the :class:`.Computed`
+.. note:: A :class:`_schema.Column` that is defined with the :class:`.Computed`
construct may not store any value outside of that which the server applies
to it; SQLAlchemy's behavior when a value is passed for such a column
to be written in INSERT or UPDATE is currently that the value will be
========================
INSERT, UPDATE and DELETE statements build on a hierarchy starting
-with :class:`.UpdateBase`. The :class:`~.sql.expression.Insert` and :class:`.Update`
+with :class:`.UpdateBase`. The :class:`_expression.Insert` and :class:`_expression.Update`
constructs build on the intermediary :class:`.ValuesBase`.
.. currentmodule:: sqlalchemy.sql.expression
Engine Configuration
====================
-The :class:`.Engine` is the starting point for any SQLAlchemy application. It's
+The :class:`_engine.Engine` is the starting point for any SQLAlchemy application. It's
"home base" for the actual database and its :term:`DBAPI`, delivered to the SQLAlchemy
application through a connection pool and a :class:`.Dialect`, which describes how
to talk to a specific kind of database/DBAPI combination.
.. image:: sqla_engine_arch.png
-Where above, an :class:`.Engine` references both a
-:class:`.Dialect` and a :class:`.Pool`,
+Where above, an :class:`_engine.Engine` references both a
+:class:`.Dialect` and a :class:`_pool.Pool`,
which together interpret the DBAPI's module functions as well as the behavior
of the database.
engine = create_engine('postgresql://scott:tiger@localhost:5432/mydatabase')
The above engine creates a :class:`.Dialect` object tailored towards
-PostgreSQL, as well as a :class:`.Pool` object which will establish a DBAPI
+PostgreSQL, as well as a :class:`_pool.Pool` object which will establish a DBAPI
connection at ``localhost:5432`` when a connection request is first received.
-Note that the :class:`.Engine` and its underlying :class:`.Pool` do **not**
-establish the first actual DBAPI connection until the :meth:`.Engine.connect`
+Note that the :class:`_engine.Engine` and its underlying :class:`_pool.Pool` do **not**
+establish the first actual DBAPI connection until the :meth:`_engine.Engine.connect`
method is called, or an operation which is dependent on this method such as
-:meth:`.Engine.execute` is invoked. In this way, :class:`.Engine` and
-:class:`.Pool` can be said to have a *lazy initialization* behavior.
+:meth:`_engine.Engine.execute` is invoked. In this way, :class:`_engine.Engine` and
+:class:`_pool.Pool` can be said to have a *lazy initialization* behavior.
-The :class:`.Engine`, once created, can either be used directly to interact with the database,
+The :class:`_engine.Engine`, once created, can either be used directly to interact with the database,
or can be passed to a :class:`.Session` object to work with the ORM. This section
-covers the details of configuring an :class:`.Engine`. The next section, :ref:`connections_toplevel`,
-will detail the usage API of the :class:`.Engine` and similar, typically for non-ORM
+covers the details of configuring an :class:`_engine.Engine`. The next section, :ref:`connections_toplevel`,
+will detail the usage API of the :class:`_engine.Engine` and similar, typically for non-ORM
applications.
.. _supported_dbapis:
Database Urls
=============
-The :func:`.create_engine` function produces an :class:`.Engine` object based
+The :func:`.create_engine` function produces an :class:`_engine.Engine` object based
on a URL. These URLs follow `RFC-1738
<http://rfc.net/rfc1738.html>`_, and usually can include username, password,
hostname, database name as well as optional keyword arguments for additional configuration.
Pooling
=======
-The :class:`.Engine` will ask the connection pool for a
+The :class:`_engine.Engine` will ask the connection pool for a
connection when the ``connect()`` or ``execute()`` methods are called. The
default connection pool, :class:`~.QueuePool`, will open connections to the
database on an as-needed basis. As concurrent statements are executed,
:class:`.QueuePool` will grow its pool of connections to a
default size of five, and will allow a default "overflow" of ten. Since the
-:class:`.Engine` is essentially "home base" for the
+:class:`_engine.Engine` is essentially "home base" for the
connection pool, it follows that you should keep a single
-:class:`.Engine` per database established within an
+:class:`_engine.Engine` per database established within an
application, rather than creating a new one for each connection.
.. note::
.. note::
- The SQLAlchemy :class:`.Engine` conserves Python function call overhead
+ The SQLAlchemy :class:`_engine.Engine` conserves Python function call overhead
by only emitting log statements when the current logging level is detected
as ``logging.INFO`` or ``logging.DEBUG``. It only checks this level when
a new connection is procured from the connection pool. Therefore when
changing the logging configuration for an already-running application, any
- :class:`.Connection` that's currently active, or more commonly a
+ :class:`_engine.Connection` that's currently active, or more commonly a
:class:`~.orm.session.Session` object that's active in a transaction, won't log any
- SQL according to the new configuration until a new :class:`.Connection`
+ SQL according to the new configuration until a new :class:`_engine.Connection`
is procured (in the case of :class:`~.orm.session.Session`, this is
after the current transaction ends and a new one begins).
The name of an event and the argument signature of a corresponding listener function is derived from
a class bound specification method, which exists bound to a marker class that's described in the documentation.
-For example, the documentation for :meth:`.PoolEvents.connect` indicates that the event name is ``"connect"``
+For example, the documentation for :meth:`_events.PoolEvents.connect` indicates that the event name is ``"connect"``
and that a user-defined listener function should receive two positional arguments::
from sqlalchemy.event import listen
---------------------
There are some varieties of argument styles which can be accepted by listener
-functions. Taking the example of :meth:`.PoolEvents.connect`, this function
+functions. Taking the example of :meth:`_events.PoolEvents.connect`, this function
is documented as receiving ``dbapi_connection`` and ``connection_record`` arguments.
We can opt to receive these arguments by name, by establishing a listener function
that accepts ``**keyword`` arguments, by passing ``named=True`` to either
generally accepts classes, instances of those classes, and related
classes or objects from which the appropriate target can be derived.
For example, the above mentioned ``"connect"`` event accepts
-:class:`.Engine` classes and objects as well as :class:`.Pool` classes
+:class:`_engine.Engine` classes and objects as well as :class:`_pool.Pool` classes
and objects::
from sqlalchemy.event import listen
Below is a listing of many of the most common inspection targets.
-* :class:`.Connectable` (i.e. :class:`.Engine`,
- :class:`.Connection`) - returns an :class:`.Inspector` object.
-* :class:`.ClauseElement` - all SQL expression components, including
- :class:`.Table`, :class:`.Column`, serve as their own inspection objects,
- meaning any of these objects passed to :func:`.inspect` return themselves.
+* :class:`.Connectable` (i.e. :class:`_engine.Engine`,
+ :class:`_engine.Connection`) - returns an :class:`_reflection.Inspector` object.
+* :class:`_expression.ClauseElement` - all SQL expression components, including
+ :class:`_schema.Table`, :class:`_schema.Column`, serve as their own inspection objects,
+ meaning any of these objects passed to :func:`_sa.inspect` return themselves.
* ``object`` - an object given will be checked by the ORM for a mapping -
if so, an :class:`.InstanceState` is returned representing the mapped
state of the object. The :class:`.InstanceState` also provides access
as the per-flush "history" of any attribute via the :class:`.History`
object.
* ``type`` (i.e. a class) - a class given will be checked by the ORM for a
- mapping - if so, a :class:`.Mapper` for that class is returned.
-* mapped attribute - passing a mapped attribute to :func:`.inspect`, such
+ mapping - if so, a :class:`_orm.Mapper` for that class is returned.
+* mapped attribute - passing a mapped attribute to :func:`_sa.inspect`, such
as ``inspect(MyClass.some_attribute)``, returns a :class:`.QueryableAttribute`
object, which is the :term:`descriptor` associated with a mapped class.
This descriptor refers to a :class:`.MapperProperty`, which is usually
.. module:: sqlalchemy.schema
-This section discusses the fundamental :class:`.Table`, :class:`.Column`
-and :class:`.MetaData` objects.
+This section discusses the fundamental :class:`_schema.Table`, :class:`_schema.Column`
+and :class:`_schema.MetaData` objects.
A collection of metadata entities is stored in an object aptly named
:class:`~sqlalchemy.schema.MetaData`::
schema constructs, the ability to alter those constructs, usually via the ALTER
statement as well as other database-specific constructs, is outside of the
scope of SQLAlchemy itself. While it's easy enough to emit ALTER statements
-and similar by hand, such as by passing a :func:`.text` construct to
-:meth:`.Connection.execute` or by using the :class:`.DDL` construct, it's a
+and similar by hand, such as by passing a :func:`_expression.text` construct to
+:meth:`_engine.Connection.execute` or by using the :class:`.DDL` construct, it's a
common practice to automate the maintenance of database schemas in relation to
application code using schema migration tools.
.. attribute:: sqlalchemy.schema.BLANK_SCHEMA
- Symbol indicating that a :class:`.Table` or :class:`.Sequence`
+ Symbol indicating that a :class:`_schema.Table` or :class:`.Sequence`
should have 'None' for its schema, even if the parent
- :class:`.MetaData` has specified a schema.
+ :class:`_schema.MetaData` has specified a schema.
.. seealso::
- :paramref:`.MetaData.schema`
+ :paramref:`_schema.MetaData.schema`
- :paramref:`.Table.schema`
+ :paramref:`_schema.Table.schema`
:paramref:`.Sequence.schema`
reused across requests.
SQLAlchemy includes several connection pool implementations
-which integrate with the :class:`.Engine`. They can also be used
+which integrate with the :class:`_engine.Engine`. They can also be used
directly for applications that want to add pooling to an otherwise
plain DBAPI approach.
Connection Pool Configuration
-----------------------------
-The :class:`~.engine.Engine` returned by the
+The :class:`_engine.Engine` returned by the
:func:`~sqlalchemy.create_engine` function in most cases has a :class:`.QueuePool`
integrated, pre-configured with reasonable pooling defaults. If
you're reading this section only to learn how to enable pooling - congratulations!
Using a Custom Connection Function
----------------------------------
-All :class:`.Pool` classes accept an argument ``creator`` which is
+All :class:`_pool.Pool` classes accept an argument ``creator`` which is
a callable that creates a new connection. :func:`.create_engine`
accepts this function to pass onto the pool via an argument of
the same name::
engine = create_engine('postgresql+psycopg2://', creator=getconn)
For most "initialize on connection" routines, it's more convenient
-to use the :class:`.PoolEvents` event hooks, so that the usual URL argument to
+to use the :class:`_events.PoolEvents` event hooks, so that the usual URL argument to
:func:`.create_engine` is still usable. ``creator`` is there as
a last resort for when a DBAPI has some form of ``connect``
that is not at all supported by SQLAlchemy.
Constructing a Pool
-------------------
-To use a :class:`.Pool` by itself, the ``creator`` function is
+To use a :class:`_pool.Pool` by itself, the ``creator`` function is
the only argument that's required and is passed first, followed
by any additional options::
mypool = pool.QueuePool(getconn, max_overflow=10, pool_size=5)
-DBAPI connections can then be procured from the pool using the :meth:`.Pool.connect`
+DBAPI connections can then be procured from the pool using the :meth:`_pool.Pool.connect`
function. The return value of this method is a DBAPI connection that's contained
within a transparent proxy::
that no existing state remains on next usage, but also so that table
and row locks are released as well as that any isolated data snapshots
are removed. This behavior can be disabled using the ``reset_on_return``
-option of :class:`.Pool`.
+option of :class:`_pool.Pool`.
-A particular pre-created :class:`.Pool` can be shared with one or more
+A particular pre-created :class:`_pool.Pool` can be shared with one or more
engines by passing it to the ``pool`` argument of :func:`.create_engine`::
e = create_engine('postgresql://', pool=mypool)
Connection pools support an event interface that allows hooks to execute
upon first connect, upon each new connection, and upon checkout and
-checkin of connections. See :class:`.PoolEvents` for details.
+checkin of connections. See :class:`_events.PoolEvents` for details.
.. _pool_disconnects:
connections dropped in the middle of transactions or other SQL operations**.
If the database becomes unavailable while a transaction is in progress, the
transaction will be lost and the database error will be raised. While
-the :class:`.Connection` object will detect a "disconnect" situation and
+the :class:`_engine.Connection` object will detect a "disconnect" situation and
recycle the connection as well as invalidate the rest of the connection pool
when this condition occurs,
the individual operation where the exception was raised will be lost, and it's
the operation, or retry the whole transaction again.
Pessimistic testing of connections upon checkout is achievable by
-using the :paramref:`.Pool.pre_ping` argument, available from :func:`.create_engine`
+using the :paramref:`_pool.Pool.pre_ping` argument, available from :func:`.create_engine`
via the :paramref:`.create_engine.pool_pre_ping` argument::
engine = create_engine("mysql+pymysql://user:pw@host/db", pool_pre_ping=True)
Python latency. As such, this statement is **not logged in the SQL
echo output**, and will not show up in SQLAlchemy's engine logging.
-.. versionadded:: 1.2 Added "pre-ping" capability to the :class:`.Pool`
+.. versionadded:: 1.2 Added "pre-ping" capability to the :class:`_pool.Pool`
class.
Custom / Legacy Pessimistic Ping
The above recipe has the advantage that we are making use of SQLAlchemy's
facilities for detecting those DBAPI exceptions that are known to indicate
-a "disconnect" situation, as well as the :class:`.Engine` object's ability
+a "disconnect" situation, as well as the :class:`_engine.Engine` object's ability
to correctly invalidate the current connection pool when this condition
-occurs and allowing the current :class:`.Connection` to re-validate onto
+occurs and allowing the current :class:`_engine.Connection` to re-validate onto
a new DBAPI connection.
to let SQLAlchemy handle disconnects as they occur, at which point all
connections in the pool are invalidated, meaning they are assumed to be
stale and will be refreshed upon next checkout. This behavior assumes the
-:class:`.Pool` is used in conjunction with a :class:`.Engine`.
-The :class:`.Engine` has logic which can detect
+:class:`_pool.Pool` is used in conjunction with a :class:`_engine.Engine`.
+The :class:`_engine.Engine` has logic which can detect
disconnection events and refresh the pool automatically.
-When the :class:`.Connection` attempts to use a DBAPI connection, and an
+When the :class:`_engine.Connection` attempts to use a DBAPI connection, and an
exception is raised that corresponds to a "disconnect" event, the connection
-is invalidated. The :class:`.Connection` then calls the :meth:`.Pool.recreate`
+is invalidated. The :class:`_engine.Connection` then calls the :meth:`_pool.Pool.recreate`
method, effectively invalidating all connections not currently checked out so
that they are replaced with new ones upon next checkout. This flow is
illustrated by the code example below::
Above, any DBAPI connection that has been open for more than one hour will be invalidated and replaced,
upon next checkout. Note that the invalidation **only** occurs during checkout - not on
any connections that are held in a checked out state. ``pool_recycle`` is a function
-of the :class:`.Pool` itself, independent of whether or not an :class:`.Engine` is in use.
+of the :class:`_pool.Pool` itself, independent of whether or not an :class:`_engine.Engine` is in use.
.. _pool_connection_invalidation:
More on Invalidation
^^^^^^^^^^^^^^^^^^^^
-The :class:`.Pool` provides "connection invalidation" services which allow
+The :class:`_pool.Pool` provides "connection invalidation" services which allow
both explicit invalidation of a connection as well as automatic invalidation
in response to conditions that are determined to render a connection unusable.
if it is not clear that the connection itself might not be closed, however
if this method fails, the exception is logged but the operation still proceeds.
-When using a :class:`.Engine`, the :meth:`.Connection.invalidate` method is
+When using a :class:`_engine.Engine`, the :meth:`_engine.Connection.invalidate` method is
the usual entrypoint to explicit invalidation. Other conditions by which
a DBAPI connection might be invalidated include:
A final attempt at calling ``.close()`` on the connection will be made,
and it is then discarded.
-* When a listener implementing :meth:`.PoolEvents.checkout` raises the
+* When a listener implementing :meth:`_events.PoolEvents.checkout` raises the
:class:`~sqlalchemy.exc.DisconnectionError` exception, indicating that the connection
won't be usable and a new connection attempt needs to be made.
-All invalidations which occur will invoke the :meth:`.PoolEvents.invalidate`
+All invalidations which occur will invoke the :meth:`_events.PoolEvents.invalidate`
event.
.. _pool_use_lifo:
-------------------------------------------
It's critical that when using a connection pool, and by extension when
-using an :class:`.Engine` created via :func:`.create_engine`, that
+using an :class:`_engine.Engine` created via :func:`.create_engine`, that
the pooled connections **are not shared to a forked process**. TCP connections
are represented as file descriptors, which usually work across process
boundaries, meaning this will cause concurrent access to the file descriptor
There are two approaches to dealing with this.
-The first is, either create a new :class:`.Engine` within the child
-process, or upon an existing :class:`.Engine`, call :meth:`.Engine.dispose`
+The first is, either create a new :class:`_engine.Engine` within the child
+process, or upon an existing :class:`_engine.Engine`, call :meth:`_engine.Engine.dispose`
before the child process uses any connections. This will remove all existing
connections from the pool so that it makes all new ones. Below is
a simple version using ``multiprocessing.Process``, but this idea
p = Process(target=run_in_process)
-The next approach is to instrument the :class:`.Pool` itself with events
+The next approach is to instrument the :class:`_pool.Pool` itself with events
so that connections are automatically invalidated in the subprocess.
This is a little more magical but probably more foolproof::
Limitations of Reflection
-------------------------
-It's important to note that the reflection process recreates :class:`.Table`
+It's important to note that the reflection process recreates :class:`_schema.Table`
metadata using only information which is represented in the relational database.
This process by definition cannot restore aspects of a schema that aren't
actually stored in the database. State which is not available from reflection
includes but is not limited to:
* Client side defaults, either Python functions or SQL expressions defined using
- the ``default`` keyword of :class:`.Column` (note this is separate from ``server_default``,
+ the ``default`` keyword of :class:`_schema.Column` (note this is separate from ``server_default``,
which specifically is what's available via reflection).
* Column information, e.g. data that might have been placed into the
- :attr:`.Column.info` dictionary
+ :attr:`_schema.Column.info` dictionary
-* The value of the ``.quote`` setting for :class:`.Column` or :class:`.Table`
+* The value of the ``.quote`` setting for :class:`_schema.Column` or :class:`_schema.Table`
-* The association of a particular :class:`.Sequence` with a given :class:`.Column`
+* The association of a particular :class:`.Sequence` with a given :class:`_schema.Column`
The relational database also in many cases reports on table metadata in a
-different format than what was specified in SQLAlchemy. The :class:`.Table`
+different format than what was specified in SQLAlchemy. The :class:`_schema.Table`
objects returned from reflection cannot be always relied upon to produce the identical
-DDL as the original Python-defined :class:`.Table` objects. Areas where
+DDL as the original Python-defined :class:`_schema.Table` objects. Areas where
this occurs includes server defaults, column-associated sequences and various
idiosyncrasies regarding constraints and datatypes. Server side defaults may
be returned with cast directives (typically PostgreSQL will include a ``::<type>``
=================================
The term "selectable" refers to any object that rows can be selected from;
-in SQLAlchemy, these objects descend from :class:`.FromClause` and their
-distinguishing feature is their :attr:`.FromClause.c` attribute, which is
+in SQLAlchemy, these objects descend from :class:`_expression.FromClause` and their
+distinguishing feature is their :attr:`_expression.FromClause.c` attribute, which is
a namespace of all the columns contained within the FROM clause (these
-elements are themselves :class:`.ColumnElement` subclasses).
+elements are themselves :class:`_expression.ColumnElement` subclasses).
.. currentmodule:: sqlalchemy.sql.expression
"SQL" links to see what's being generated.
The return value of :func:`.create_engine` is an instance of
-:class:`.Engine`, and it represents the core interface to the
+:class:`_engine.Engine`, and it represents the core interface to the
database, adapted through a :term:`dialect` that handles the details
of the database and :term:`DBAPI` in use. In this case the SQLite
dialect will interpret instructions to the Python built-in ``sqlite3``
.. sidebar:: Lazy Connecting
- The :class:`.Engine`, when first returned by :func:`.create_engine`,
+ The :class:`_engine.Engine`, when first returned by :func:`.create_engine`,
has not actually tried to connect to the database yet; that happens
only the first time it is asked to perform a task against the database.
-The first time a method like :meth:`.Engine.execute` or :meth:`.Engine.connect`
-is called, the :class:`.Engine` establishes a real :term:`DBAPI` connection to the
+The first time a method like :meth:`_engine.Engine.execute` or :meth:`_engine.Engine.connect`
+is called, the :class:`_engine.Engine` establishes a real :term:`DBAPI` connection to the
database, which is then used to emit the SQL.
.. seealso::
Column('nickname', String(50))
)
- We include this more verbose :class:`~.schema.Table` construct separately
+ We include this more verbose :class:`_schema.Table` construct separately
to highlight the difference between a minimal construct geared primarily
towards in-Python usage only, versus one that will be used to emit CREATE
TABLE statements on a particular set of backends with more stringent
{stop}<sqlalchemy.engine.result.ResultProxy object at 0x...>
Above, because we specified all three columns in the ``execute()`` method,
-the compiled :class:`~.expression.Insert` included all three
-columns. The :class:`~.expression.Insert` statement is compiled
+the compiled :class:`_expression.Insert` included all three
+columns. The :class:`_expression.Insert` statement is compiled
at execution time based on the parameters we specified; if we specified fewer
-parameters, the :class:`~.expression.Insert` would have fewer
+parameters, the :class:`_expression.Insert` would have fewer
entries in its VALUES clause.
To issue many inserts using DBAPI's ``executemany()`` method, we can send in a
statement.
The "executemany" style of invocation is available for each of the
-:func:`~.sql.expression.insert`, :func:`.update` and :func:`.delete` constructs.
+:func:`_expression.insert`, :func:`_expression.update` and :func:`_expression.delete` constructs.
.. _coretutorial_selecting:
We began with inserts just so that our test database had some data in it. The
more interesting part of the data is selecting it! We'll cover UPDATE and
DELETE statements later. The primary construct used to generate SELECT
-statements is the :func:`~.sql.expression.select` function:
+statements is the :func:`_expression.select` function:
.. sourcecode:: pycon+sql
FROM users
()
-Above, we issued a basic :func:`~.sql.expression.select` call, placing the ``users`` table
+Above, we issued a basic :func:`_expression.select` call, placing the ``users`` table
within the COLUMNS clause of the select, and then executing. SQLAlchemy
expanded the ``users`` table into the set of each of its columns, and also
generated a FROM clause for us. The result returned is again a
A more specialized method of column access is to use the SQL construct that
directly corresponds to a particular column as the mapping key; in this
-example, it means we would use the :class:`.Column` objects selected in our
+example, it means we would use the :class:`_schema.Column` objects selected in our
SELECT directly as keys in conjunction with the :attr:`.Row._mapping`
collection:
Lets observe something interesting about the FROM clause. Whereas the
generated statement contains two distinct sections, a "SELECT columns" part
-and a "FROM table" part, our :func:`~.sql.expression.select` construct only has a list
+and a "FROM table" part, our :func:`_expression.select` construct only has a list
containing columns. How does this work ? Let's try putting *two* tables into
-our :func:`~.sql.expression.select` statement:
+our :func:`_expression.select` statement:
.. sourcecode:: pycon+sql
Those who are familiar with SQL joins know that this is a **Cartesian
product**; each row from the ``users`` table is produced against each row from
the ``addresses`` table. So to put some sanity into this statement, we need a
-WHERE clause. We do that using :meth:`.Select.where`:
+WHERE clause. We do that using :meth:`_expression.Select.where`:
.. sourcecode:: pycon+sql
(2, u'wendy', u'Wendy Williams', 3, 2, u'www@www.org')
(2, u'wendy', u'Wendy Williams', 4, 2, u'wendy@aol.com')
-So that looks a lot better, we added an expression to our :func:`~.sql.expression.select`
+So that looks a lot better, we added an expression to our :func:`_expression.select`
which had the effect of adding ``WHERE users.id = addresses.user_id`` to our
statement, and our results were managed down so that the join of ``users`` and
``addresses`` rows made sense. But let's look at that expression? It's using
'users.id = addresses.user_id'
As you can see, the ``==`` operator is producing an object that is very much
-like the :class:`~.expression.Insert` and :func:`~.sql.expression.select`
+like the :class:`_expression.Insert` and :func:`_expression.select`
objects we've made so far, thanks to Python's ``__eq__()`` builtin; you call
``str()`` on it and it produces SQL. By now, one can see that everything we
are working with is ultimately the same type of object. SQLAlchemy terms the
-base class of all of these expressions as :class:`~.expression.ColumnElement`.
+base class of all of these expressions as :class:`_expression.ColumnElement`.
Operators
=========
users.id = :id_1
The ``7`` literal is embedded the resulting
-:class:`~.expression.ColumnElement`; we can use the same trick
+:class:`_expression.ColumnElement`; we can use the same trick
we did with the :class:`~sqlalchemy.sql.expression.Insert` object to see it:
.. sourcecode:: pycon+sql
============
-We'd like to show off some of our operators inside of :func:`~.sql.expression.select`
+We'd like to show off some of our operators inside of :func:`_expression.select`
constructs. But we need to lump them together a little more, so let's first
introduce some conjunctions. Conjunctions are those little words like AND and
OR that put things together. We'll also hit upon NOT. :func:`.and_`, :func:`.or_`,
address at AOL or MSN, whose name starts with a letter between "m" and "z",
and we'll also generate a column containing their full name combined with
their email address. We will add two new constructs to this statement,
-:meth:`~.ColumnOperators.between` and :meth:`~.ColumnElement.label`.
+:meth:`~.ColumnOperators.between` and :meth:`_expression.ColumnElement.label`.
:meth:`~.ColumnOperators.between` produces a BETWEEN clause, and
-:meth:`~.ColumnElement.label` is used in a column expression to produce labels using the ``AS``
+:meth:`_expression.ColumnElement.label` is used in a column expression to produce labels using the ``AS``
keyword; it's recommended when selecting from expressions that otherwise would
not have a name:
covered yet, which include ORDER BY, GROUP BY, and HAVING.
A shortcut to using :func:`.and_` is to chain together multiple
-:meth:`~.Select.where` clauses. The above can also be written as:
+:meth:`_expression.Select.where` clauses. The above can also be written as:
.. sourcecode:: pycon+sql
(', ', 'm', 'z', '%@aol.com', '%@msn.com')
[(u'Wendy Williams, wendy@aol.com',)]
-The way that we can build up a :func:`~.sql.expression.select` construct through successive
+The way that we can build up a :func:`_expression.select` construct through successive
method calls is called :term:`method chaining`.
.. _sqlexpression_text:
groups components together in a programmatic style can be hard. That's why
SQLAlchemy lets you just use strings, for those cases when the SQL
is already known and there isn't a strong need for the statement to support
-dynamic features. The :func:`~.expression.text` construct is used
+dynamic features. The :func:`_expression.text` construct is used
to compose a textual statement that is passed to the database mostly
-unchanged. Below, we create a :func:`~.expression.text` object and execute it:
+unchanged. Below, we create a :func:`_expression.text` object and execute it:
.. sourcecode:: pycon+sql
{stop}[(u'Wendy Williams, wendy@aol.com',)]
Above, we can see that bound parameters are specified in
-:func:`~.expression.text` using the named colon format; this format is
+:func:`_expression.text` using the named colon format; this format is
consistent regardless of database backend. To send values in for the
-parameters, we passed them into the :meth:`~.Connection.execute` method
+parameters, we passed them into the :meth:`_engine.Connection.execute` method
as additional arguments.
Specifying Bound Parameter Behaviors
------------------------------------
-The :func:`~.expression.text` construct supports pre-established bound values
-using the :meth:`.TextClause.bindparams` method::
+The :func:`_expression.text` construct supports pre-established bound values
+using the :meth:`_expression.TextClause.bindparams` method::
stmt = text("SELECT * FROM users WHERE users.name BETWEEN :x AND :y")
stmt = stmt.bindparams(x="m", y="z")
.. seealso::
- :meth:`.TextClause.bindparams` - full method description
+ :meth:`_expression.TextClause.bindparams` - full method description
.. _sqlexpression_text_columns:
----------------------------------
We may also specify information about the result columns using the
-:meth:`.TextClause.columns` method; this method can be used to specify
+:meth:`_expression.TextClause.columns` method; this method can be used to specify
the return types, based on name::
stmt = stmt.columns(id=Integer, name=String)
stmt = text("SELECT id, name FROM users")
stmt = stmt.columns(users.c.id, users.c.name)
-When we call the :meth:`.TextClause.columns` method, we get back a
+When we call the :meth:`_expression.TextClause.columns` method, we get back a
:class:`.TextAsFrom` object that supports the full suite of
:attr:`.TextAsFrom.c` and other "selectable" operations::
new_stmt = select([stmt.c.id, addresses.c.id]).\
select_from(j).where(stmt.c.name == 'x')
-The positional form of :meth:`.TextClause.columns` is particularly useful
+The positional form of :meth:`_expression.TextClause.columns` is particularly useful
when relating textual SQL to existing Core or ORM models, because we can use
column expressions directly without worrying about name conflicts or other issues with the
result column names in the textual SQL:
InvalidRequestError: Ambiguous column name 'id' in result set column descriptions
It's important to note that while accessing columns from a result set using
-:class:`.Column` objects may seem unusual, it is in fact the only system
+:class:`_schema.Column` objects may seem unusual, it is in fact the only system
used by the ORM, which occurs transparently beneath the facade of the
-:class:`~.orm.query.Query` object; in this way, the :meth:`.TextClause.columns` method
+:class:`~.orm.query.Query` object; in this way, the :meth:`_expression.TextClause.columns` method
is typically very applicable to textual statements to be used in an ORM
context. The example at :ref:`orm_tutorial_literal_sql` illustrates
a simple usage.
.. versionadded:: 1.1
- The :meth:`.TextClause.columns` method now accepts column expressions
+ The :meth:`_expression.TextClause.columns` method now accepts column expressions
which will be matched positionally to a plain text SQL result set,
eliminating the need for column names to match or even be unique in the
SQL statement when matching table metadata or ORM models to textual SQL.
.. seealso::
- :meth:`.TextClause.columns` - full method description
+ :meth:`_expression.TextClause.columns` - full method description
:ref:`orm_tutorial_literal_sql` - integrating ORM-level queries with
- :func:`.text`
+ :func:`_expression.text`
Using text() fragments inside bigger statements
-----------------------------------------------
-:func:`~.expression.text` can also be used to produce fragments of SQL
+:func:`_expression.text` can also be used to produce fragments of SQL
that can be freely within a
-:func:`~.expression.select` object, which accepts :func:`~.expression.text`
+:func:`_expression.select` object, which accepts :func:`_expression.text`
objects as an argument for most of its builder functions.
-Below, we combine the usage of :func:`~.expression.text` within a
-:func:`~.sql.expression.select` object. The :func:`~.expression.select` construct provides the "geometry"
-of the statement, and the :func:`~.expression.text` construct provides the
+Below, we combine the usage of :func:`_expression.text` within a
+:func:`_expression.select` object. The :func:`_expression.select` construct provides the "geometry"
+of the statement, and the :func:`_expression.text` construct provides the
textual content within this form. We can build a statement without the
-need to refer to any pre-established :class:`.Table` metadata:
+need to refer to any pre-established :class:`_schema.Table` metadata:
.. sourcecode:: pycon+sql
{stop}[(u'Wendy Williams, wendy@aol.com',)]
.. versionchanged:: 1.0.0
- The :func:`~.sql.expression.select` construct emits warnings when string SQL
- fragments are coerced to :func:`.text`, and :func:`.text` should
+ The :func:`_expression.select` construct emits warnings when string SQL
+ fragments are coerced to :func:`_expression.text`, and :func:`_expression.text` should
be used explicitly. See :ref:`migration_2992` for background.
.. _sqlexpression_literal_column:
-Using More Specific Text with :func:`.table`, :func:`.literal_column`, and :func:`.column`
--------------------------------------------------------------------------------------------
-
+Using More Specific Text with :func:`.table`, :func:`_expression.literal_column`, and :func:`_expression.column`
+-----------------------------------------------------------------------------------------------------------------
We can move our level of structure back in the other direction too,
-by using :func:`~.expression.column`, :func:`~.expression.literal_column`,
-and :func:`~.expression.table` for some of the
+by using :func:`_expression.column`, :func:`_expression.literal_column`,
+and :func:`_expression.table` for some of the
key elements of our statement. Using these constructs, we can get
-some more expression capabilities than if we used :func:`~.expression.text`
+some more expression capabilities than if we used :func:`_expression.text`
directly, as they provide to the Core more information about how the strings
they store are to be used, but still without the need to get into full
-:class:`.Table` based metadata. Below, we also specify the :class:`.String`
-datatype for two of the key :func:`~.expression.literal_column` objects,
+:class:`_schema.Table` based metadata. Below, we also specify the :class:`.String`
+datatype for two of the key :func:`_expression.literal_column` objects,
so that the string-specific concatenation operator becomes available.
-We also use :func:`~.expression.literal_column` in order to use table-qualified
+We also use :func:`_expression.literal_column` in order to use table-qualified
expressions, e.g. ``users.fullname``, that will be rendered as is;
-using :func:`~.expression.column` implies an individual column name that may
+using :func:`_expression.column` implies an individual column name that may
be quoted:
.. sourcecode:: pycon+sql
our statement has some labeled column element that we want to refer to in
a place such as the "ORDER BY" or "GROUP BY" clause; other candidates include
fields within an "OVER" or "DISTINCT" clause. If we have such a label
-in our :func:`~.sql.expression.select` construct, we can refer to it directly by passing the
-string straight into :meth:`.select.order_by` or :meth:`.select.group_by`,
+in our :func:`_expression.select` construct, we can refer to it directly by passing the
+string straight into :meth:`_expression.select.order_by` or :meth:`_expression.select.group_by`,
among others. This will refer to the named label and also prevent the
expression from being rendered twice. Label names that resolve to columns
are rendered fully:
{stop}[(1, 2), (2, 2)]
Note that the string feature here is very much tailored to when we have
-already used the :meth:`~.ColumnElement.label` method to create a
+already used the :meth:`_expression.ColumnElement.label` method to create a
specifically-named label. In other cases, we always want to refer to the
-:class:`.ColumnElement` object directly so that the expression system can
+:class:`_expression.ColumnElement` object directly so that the expression system can
make the most effective choices for rendering. Below, we illustrate how using
-the :class:`.ColumnElement` eliminates ambiguity when we want to order
+the :class:`_expression.ColumnElement` eliminates ambiguity when we want to order
by a column name that appears more than once:
.. sourcecode:: pycon+sql
parent name for the columns represented by the statement, allowing them to be
referenced relative to this name.
-In SQLAlchemy, any :class:`.Table` or other :class:`.FromClause` based
-selectable can be turned into an alias using :meth:`.FromClause.alias` method,
-which produces an :class:`.Alias` construct. :class:`.Alias` is a
-:class:`.FromClause` object that refers to a mapping of :class:`.Column`
-objects via its :attr:`.FromClause.c` collection, and can be used within the
+In SQLAlchemy, any :class:`_schema.Table` or other :class:`_expression.FromClause` based
+selectable can be turned into an alias using :meth:`_expression.FromClause.alias` method,
+which produces an :class:`_expression.Alias` construct. :class:`_expression.Alias` is a
+:class:`_expression.FromClause` object that refers to a mapping of :class:`_schema.Column`
+objects via its :attr:`_expression.FromClause.c` collection, and can be used within the
FROM clause of any subsequent SELECT statement, by referring to its column
elements in the columns or WHERE clause of the statement, or through explicit
placement in the FROM clause, either directly or within a join.
As an example, suppose we know that our user ``jack`` has two particular email
addresses. How can we locate jack based on the combination of those two
addresses? To accomplish this, we'd use a join to the ``addresses`` table,
-once for each address. We create two :class:`.Alias` constructs against
-``addresses``, and then use them both within a :func:`~.sql.expression.select` construct:
+once for each address. We create two :class:`_expression.Alias` constructs against
+``addresses``, and then use them both within a :func:`_expression.select` construct:
.. sourcecode:: pycon+sql
('jack@msn.com', 'jack@yahoo.com')
{stop}[(1, u'jack', u'Jack Jones')]
-Note that the :class:`.Alias` construct generated the names ``addresses_1`` and
+Note that the :class:`_expression.Alias` construct generated the names ``addresses_1`` and
``addresses_2`` in the final SQL result. The generation of these names is determined
by the position of the construct within the statement. If we created a query using
only the second ``a2`` alias, the name would come out as ``addresses_1``. The
statement construct will produce the identical SQL string each time it is
rendered for a particular dialect.
-Since on the outside, we refer to the alias using the :class:`.Alias` construct
+Since on the outside, we refer to the alias using the :class:`_expression.Alias` construct
itself, we don't need to be concerned about the generated name. However, for
the purposes of debugging, it can be specified by passing a string name
-to the :meth:`.FromClause.alias` method::
+to the :meth:`_expression.FromClause.alias` method::
>>> a1 = addresses.alias('a1')
-SELECT-oriented constructs which extend from :class:`.SelectBase` may be turned
-into aliased subqueries using the :meth:`.SelectBase.subquery` method, which
+SELECT-oriented constructs which extend from :class:`_expression.SelectBase` may be turned
+into aliased subqueries using the :meth:`_expression.SelectBase.subquery` method, which
produces a :class:`.Subquery` construct; for ease of use, there is also a
-:meth:`.SelectBase.alias` method that is synonymous with
-:class:`.SelectBase.subquery`. Like :class:`.Alias`, :class:`.Subquery` is
-also a :class:`.FromClause` object that may be part of any enclosing SELECT
-using the same techniques one would use for a :class:`.Alias`.
+:meth:`_expression.SelectBase.alias` method that is synonymous with
+:class:`_expression.SelectBase.subquery`. Like :class:`_expression.Alias`, :class:`.Subquery` is
+also a :class:`_expression.FromClause` object that may be part of any enclosing SELECT
+using the same techniques one would use for a :class:`_expression.Alias`.
-We can self-join the ``users`` table back to the :func:`~.sql.expression.select` we've created
+We can self-join the ``users`` table back to the :func:`_expression.select` we've created
by making :class:`.Subquery` of the entire statement:
.. sourcecode:: pycon+sql
We're halfway along to being able to construct any SELECT expression. The next
cornerstone of the SELECT is the JOIN expression. We've already been doing
joins in our examples, by just placing two tables in either the columns clause
-or the where clause of the :func:`~.sql.expression.select` construct. But if we want to make a
-real "JOIN" or "OUTERJOIN" construct, we use the :meth:`~.FromClause.join` and
-:meth:`~.FromClause.outerjoin` methods, most commonly accessed from the left table in the
+or the where clause of the :func:`_expression.select` construct. But if we want to make a
+real "JOIN" or "OUTERJOIN" construct, we use the :meth:`_expression.FromClause.join` and
+:meth:`_expression.FromClause.outerjoin` methods, most commonly accessed from the left table in the
join:
.. sourcecode:: pycon+sql
... )
users JOIN addresses ON addresses.email_address LIKE users.name || :name_1
-When we create a :func:`~.sql.expression.select` construct, SQLAlchemy looks around at the
+When we create a :func:`_expression.select` construct, SQLAlchemy looks around at the
tables we've mentioned and then places them in the FROM clause of the
statement. When we use JOINs however, we know what FROM clause we want, so
-here we make use of the :meth:`~.Select.select_from` method:
+here we make use of the :meth:`_expression.Select.select_from` method:
.. sourcecode:: pycon+sql
('%',)
{stop}[(u'Jack Jones',), (u'Jack Jones',), (u'Wendy Williams',)]
-The :meth:`~.FromClause.outerjoin` method creates ``LEFT OUTER JOIN`` constructs,
-and is used in the same way as :meth:`~.FromClause.join`:
+The :meth:`_expression.FromClause.outerjoin` method creates ``LEFT OUTER JOIN`` constructs,
+and is used in the same way as :meth:`_expression.FromClause.join`:
.. sourcecode:: pycon+sql
.. seealso::
- :func:`.expression.join`
+ :func:`_expression.join`
- :func:`.expression.outerjoin`
+ :func:`_expression.outerjoin`
- :class:`.Join`
+ :class:`_expression.Join`
Everything Else
===============
:func:`.cast`, in that it sets up a Python expression as having a specific SQL
database type, but does not render the ``CAST`` keyword or datatype on the
database side. :func:`.type_coerce` is particularly important when dealing
-with the :class:`.types.JSON` datatype, which typically has an intricate
+with the :class:`_types.JSON` datatype, which typically has an intricate
relationship with string-oriented datatypes on different platforms and
may not even be an explicit datatype, such as on SQLite and MariaDB.
Below, we use :func:`.type_coerce` to deliver a Python structure as a JSON
Above, MySQL's ``JSON_EXTRACT`` SQL function was invoked
because we used :func:`.type_coerce` to indicate that our Python dictionary
-should be treated as :class:`.types.JSON`. The Python ``__getitem__``
+should be treated as :class:`_types.JSON`. The Python ``__getitem__``
operator, ``['some_key']`` in this case, became available as a result and
allowed a ``JSON_EXTRACT`` path expression (not shown, however in this
case it would ultimately be ``'$."some_key"'``) to be rendered.
-------------------------------
Unions come in two flavors, UNION and UNION ALL, which are available via
-module level functions :func:`~.expression.union` and
-:func:`~.expression.union_all`:
+module level functions :func:`_expression.union` and
+:func:`_expression.union_all`:
.. sourcecode:: pycon+sql
{stop}[(1, 1, u'jack@yahoo.com')]
Also available, though not supported on all databases, are
-:func:`~.expression.intersect`,
-:func:`~.expression.intersect_all`,
-:func:`~.expression.except_`, and :func:`~.expression.except_all`:
+:func:`_expression.intersect`,
+:func:`_expression.intersect_all`,
+:func:`_expression.except_`, and :func:`_expression.except_all`:
.. sourcecode:: pycon+sql
.. seealso::
- :func:`.union`
+ :func:`_expression.union`
- :func:`.union_all`
+ :func:`_expression.union_all`
- :func:`.intersect`
+ :func:`_expression.intersect`
- :func:`.intersect_all`
+ :func:`_expression.intersect_all`
:func:`.except_`
- :func:`.except_all`
+ :func:`_expression.except_all`
Ordering Unions
^^^^^^^^^^^^^^^
not specific tables. As in the previous examples, we used
``.order_by(addresses.c.email_address)`` but SQLAlchemy rendered the ORDER BY
without using the table name. A generalized way to apply ORDER BY to a union
-is also to refer to the :attr:`.CompoundSelect.selected_columns` collection in
+is also to refer to the :attr:`_selectable.CompoundSelect.selected_columns` collection in
order to access the column expressions which are synonymous with the columns
selected from the first SELECT; the SQLAlchemy compiler will ensure these will
be rendered without table names::
is often a :term:`correlated subquery`, which relies upon the enclosing
SELECT statement in order to acquire at least one of its FROM clauses.
-The :func:`~.sql.expression.select` construct can be modified to act as a
-column expression by calling either the :meth:`~.SelectBase.scalar_subquery`
-or :meth:`~.SelectBase.label` method:
+The :func:`_expression.select` construct can be modified to act as a
+column expression by calling either the :meth:`_expression.SelectBase.scalar_subquery`
+or :meth:`_expression.SelectBase.label` method:
.. sourcecode:: pycon+sql
... where(users.c.id == addresses.c.user_id).\
... scalar_subquery()
-The above construct is now a :class:`~.expression.ScalarSelect` object,
+The above construct is now a :class:`_expression.ScalarSelect` object,
which is an adapter around the original :class:`.~expression.Select`
-object; it participates within the :class:`~.expression.ColumnElement`
+object; it participates within the :class:`_expression.ColumnElement`
family of expression constructs. We can place this construct the same as any
-other column within another :func:`~.sql.expression.select`:
+other column within another :func:`_expression.select`:
.. sourcecode:: pycon+sql
{stop}[(u'jack', 2), (u'wendy', 2)]
To apply a non-anonymous column name to our scalar select, we create
-it using :meth:`.SelectBase.label` instead:
+it using :meth:`_expression.SelectBase.label` instead:
.. sourcecode:: pycon+sql
.. seealso::
- :meth:`.Select.scalar_subquery`
+ :meth:`_expression.Select.scalar_subquery`
- :meth:`.Select.label`
+ :meth:`_expression.Select.label`
.. _correlated_subqueries:
Auto-correlation will usually do what's expected, however it can also be controlled.
For example, if we wanted a statement to correlate only to the ``addresses`` table
but not the ``users`` table, even if both were present in the enclosing SELECT,
-we use the :meth:`~.Select.correlate` method to specify those FROM clauses that
+we use the :meth:`_expression.Select.correlate` method to specify those FROM clauses that
may be correlated:
.. sourcecode:: pycon+sql
('wendy',)
{stop}[(u'wendy',)]
-We can also control correlation via exclusion, using the :meth:`.Select.correlate_except`
+We can also control correlation via exclusion, using the :meth:`_expression.Select.correlate_except`
method. Such as, we can write our SELECT for the ``users`` table
by telling it to correlate all FROM clauses except for ``users``:
Where above, the right side of the JOIN contains a subquery that refers not
just to the "books" table but also the "people" table, correlating
to the left side of the JOIN. SQLAlchemy Core supports a statement
-like the above using the :meth:`.Select.lateral` method as follows::
+like the above using the :meth:`_expression.Select.lateral` method as follows::
>>> from sqlalchemy import table, column, select, true
>>> people = table('people', column('people_id'), column('age'), column('name'))
FROM books WHERE books.owner_id = people.people_id)
AS book_subq ON true
-Above, we can see that the :meth:`.Select.lateral` method acts a lot like
-the :meth:`.Select.alias` method, including that we can specify an optional
-name. However the construct is the :class:`.Lateral` construct instead of
-an :class:`.Alias` which provides for the LATERAL keyword as well as special
+Above, we can see that the :meth:`_expression.Select.lateral` method acts a lot like
+the :meth:`_expression.Select.alias` method, including that we can specify an optional
+name. However the construct is the :class:`_expression.Lateral` construct instead of
+an :class:`_expression.Alias` which provides for the LATERAL keyword as well as special
instructions to allow correlation from inside the FROM clause of the
enclosing statement.
-The :meth:`.Select.lateral` method interacts normally with the
-:meth:`.Select.correlate` and :meth:`.Select.correlate_except` methods, except
+The :meth:`_expression.Select.lateral` method interacts normally with the
+:meth:`_expression.Select.correlate` and :meth:`_expression.Select.correlate_except` methods, except
that the correlation rules also apply to any other tables present in the
enclosing statement's FROM clause. Correlation is "automatic" to these
tables by default, is explicit if the table is specified to
-:meth:`.Select.correlate`, and is explicit to all tables except those
-specified to :meth:`.Select.correlate_except`.
+:meth:`_expression.Select.correlate`, and is explicit to all tables except those
+specified to :meth:`_expression.Select.correlate_except`.
.. versionadded:: 1.1
.. seealso::
- :class:`.Lateral`
+ :class:`_expression.Lateral`
- :meth:`.Select.lateral`
+ :meth:`_expression.Select.lateral`
.. _core_tutorial_ordering:
---------------------------------------------
Ordering is done by passing column expressions to the
-:meth:`~.SelectBase.order_by` method:
+:meth:`_expression.SelectBase.order_by` method:
.. sourcecode:: pycon+sql
()
{stop}[(u'jack',), (u'wendy',)]
-Ascending or descending can be controlled using the :meth:`~.ColumnElement.asc`
-and :meth:`~.ColumnElement.desc` modifiers:
+Ascending or descending can be controlled using the :meth:`_expression.ColumnElement.asc`
+and :meth:`_expression.ColumnElement.desc` modifiers:
.. sourcecode:: pycon+sql
Grouping refers to the GROUP BY clause, and is usually used in conjunction
with aggregate functions to establish groups of rows to be aggregated.
-This is provided via the :meth:`~.SelectBase.group_by` method:
+This is provided via the :meth:`_expression.SelectBase.group_by` method:
.. sourcecode:: pycon+sql
{stop}[(u'jack', 2), (u'wendy', 2)]
HAVING can be used to filter results on an aggregate value, after GROUP BY has
-been applied. It's available here via the :meth:`~.Select.having`
+been applied. It's available here via the :meth:`_expression.Select.having`
method:
.. sourcecode:: pycon+sql
A common system of dealing with duplicates in composed SELECT statements
is the DISTINCT modifier. A simple DISTINCT clause can be added using the
-:meth:`.Select.distinct` method:
+:meth:`_expression.Select.distinct` method:
.. sourcecode:: pycon+sql
rows after a given "offset". While common backends like PostgreSQL,
MySQL and SQLite support LIMIT and OFFSET keywords, other backends
need to refer to more esoteric features such as "window functions"
-and row ids to achieve the same effect. The :meth:`~.Select.limit`
-and :meth:`~.Select.offset` methods provide an easy abstraction
+and row ids to achieve the same effect. The :meth:`_expression.Select.limit`
+and :meth:`_expression.Select.offset` methods provide an easy abstraction
into the current backend's methodology:
.. sourcecode:: pycon+sql
Inserts, Updates and Deletes
============================
-We've seen :meth:`~.TableClause.insert` demonstrated
-earlier in this tutorial. Where :meth:`~.TableClause.insert`
-produces INSERT, the :meth:`~.TableClause.update`
+We've seen :meth:`_expression.TableClause.insert` demonstrated
+earlier in this tutorial. Where :meth:`_expression.TableClause.insert`
+produces INSERT, the :meth:`_expression.TableClause.update`
method produces UPDATE. Both of these constructs feature
a method called :meth:`~.ValuesBase.values` which specifies
the VALUES or SET clause of the statement.
COMMIT
{stop}<sqlalchemy.engine.result.ResultProxy object at 0x...>
-When using :meth:`~.TableClause.insert` or :meth:`~.TableClause.update`
+When using :meth:`_expression.TableClause.insert` or :meth:`_expression.TableClause.update`
in an "execute many" context, we may also want to specify named
bound parameters which we can refer to in the argument list.
The two constructs will automatically generate bound placeholders
for any column names passed in the dictionaries sent to
-:meth:`~.Connection.execute` at execution time. However, if we
+:meth:`_engine.Connection.execute` at execution time. However, if we
wish to use explicitly targeted named parameters with composed expressions,
-we need to use the :func:`~.expression.bindparam` construct.
-When using :func:`~.expression.bindparam` with
-:meth:`~.TableClause.insert` or :meth:`~.TableClause.update`,
+we need to use the :func:`_expression.bindparam` construct.
+When using :func:`_expression.bindparam` with
+:meth:`_expression.TableClause.insert` or :meth:`_expression.TableClause.update`,
the names of the table's columns themselves are reserved for the
"automatic" generation of bind names. We can combine the usage
of implicitly available bind names and explicitly named parameters
COMMIT
<sqlalchemy.engine.result.ResultProxy object at 0x...>
-An UPDATE statement is emitted using the :meth:`~.TableClause.update` construct. This
+An UPDATE statement is emitted using the :meth:`_expression.TableClause.update` construct. This
works much like an INSERT, except there is an additional WHERE clause
that can be specified:
COMMIT
{stop}<sqlalchemy.engine.result.ResultProxy object at 0x...>
-When using :meth:`~.TableClause.update` in an "executemany" context,
+When using :meth:`_expression.TableClause.update` in an "executemany" context,
we may wish to also use explicitly named bound parameters in the
-WHERE clause. Again, :func:`~.expression.bindparam` is the construct
+WHERE clause. Again, :func:`_expression.bindparam` is the construct
used to achieve this:
.. sourcecode:: pycon+sql
A correlated update lets you update a table using selection from another
table, or the same table; the SELECT statement is passed as a scalar
-subquery using :meth:`.Select.scalar_subquery`:
+subquery using :meth:`_expression.Select.scalar_subquery`:
.. sourcecode:: pycon+sql
which updates one table at a time, but can reference additional tables in an additional
"FROM" clause that can then be referenced in the WHERE clause directly. On MySQL,
multiple tables can be embedded into a single UPDATE statement separated by a comma.
-The SQLAlchemy :func:`.update` construct supports both of these modes
+The SQLAlchemy :func:`_expression.update` construct supports both of these modes
implicitly, by specifying multiple tables in the WHERE clause::
stmt = users.update().\
addresses.email_address LIKE :email_address_1 || '%'
When using MySQL, columns from each table can be assigned to in the
-SET clause directly, using the dictionary form passed to :meth:`.Update.values`::
+SET clause directly, using the dictionary form passed to :meth:`_expression.Update.values`::
stmt = users.update().\
values({
Parameter-Ordered Updates
-------------------------
-The default behavior of the :func:`.update` construct when rendering the SET
+The default behavior of the :func:`_expression.update` construct when rendering the SET
clauses is to render them using the column ordering given in the
-originating :class:`.Table` object.
+originating :class:`_schema.Table` object.
This is an important behavior, since it means that the rendering of a
particular UPDATE statement with particular columns
will be rendered the same each time, which has an impact on query caching systems
that rely on the form of the statement, either client side or server side.
-Since the parameters themselves are passed to the :meth:`.Update.values`
+Since the parameters themselves are passed to the :meth:`_expression.Update.values`
method as Python dictionary keys, there is no other fixed ordering
available.
is evaluated, the values embedded in the row are changing.
To suit this specific use case, the
-:meth:`.update.ordered_values` method may be used. When using this method,
+:meth:`_expression.update.ordered_values` method may be used. When using this method,
we supply a **series of 2-tuples**
as the argument to the method::
above form, we are assured that the "y" column's SET clause will render first,
then the "x" column's SET clause.
-.. versionchanged:: 1.4 Added the :meth:`.Update.ordered_values` method which
- supersedes the :paramref:`.update.preserve_parameter_order` flag that will
+.. versionchanged:: 1.4 Added the :meth:`_expression.Update.ordered_values` method which
+ supersedes the :paramref:`_expression.update.preserve_parameter_order` flag that will
be removed in SQLAlchemy 2.0.
.. seealso::
-------
Finally, a delete. This is accomplished easily enough using the
-:meth:`~.TableClause.delete` construct:
+:meth:`_expression.TableClause.delete` construct:
.. sourcecode:: pycon+sql
statements that refer to multiple tables within the WHERE criteria. For PG
and MySQL, this is the "DELETE USING" syntax, and for SQL Server, it's a
"DELETE FROM" that refers to more than one table. The SQLAlchemy
-:func:`.delete` construct supports both of these modes
+:func:`_expression.delete` construct supports both of these modes
implicitly, by specifying multiple tables in the WHERE clause::
stmt = users.delete().\
Matched Row Counts
------------------
-Both of :meth:`~.TableClause.update` and
-:meth:`~.TableClause.delete` are associated with *matched row counts*. This is a
+Both of :meth:`_expression.TableClause.update` and
+:meth:`_expression.TableClause.delete` are associated with *matched row counts*. This is a
number indicating the number of rows that were matched by the WHERE clause.
Note that by "matched", this includes rows where no UPDATE actually took place.
The value is available as :attr:`~.ResultProxy.rowcount`:
structure. This is not unlike the Python ``ast`` module in that is presents
a system by which a program can operate upon each component of a SQL
expression. Common purposes this serves are locating various kinds of
-elements such as :class:`.Table` or :class:`.BindParameter` objects,
+elements such as :class:`_schema.Table` or :class:`.BindParameter` objects,
as well as altering the state of the structure such as replacing certain FROM
clauses with others.
NUMBER, NVARCHAR, NVARCHAR2, RAW, TIMESTAMP, VARCHAR, \
VARCHAR2
-.. versionadded:: 1.2.19 Added :class:`.NCHAR` to the list of datatypes
+.. versionadded:: 1.2.19 Added :class:`_types.NCHAR` to the list of datatypes
exported by the Oracle dialect.
Types which are specific to Oracle, or have Oracle-specific
* **The SQLAlchemy Engine object uses a pool of connections by default** - What
this means is that when one makes use of a SQL database connection resource
- of an :class:`.Engine` object, and then :term:`releases` that resource,
+ of an :class:`_engine.Engine` object, and then :term:`releases` that resource,
the database connection itself remains connected to the database and
is returned to an internal queue where it can be used again. Even though
the code may appear to be ending its conversation with the database, in many
that persist until the application ends or the pool is explicitly disposed.
* Because of the pool, when an application makes use of a SQL database
- connection, most typically from either making use of :meth:`.Engine.connect`
+ connection, most typically from either making use of :meth:`_engine.Engine.connect`
or when making queries using an ORM :class:`.Session`, this activity
does not necessarily establish a new connection to the database at the
moment the connection object is acquired; it instead consults the
engine = create_engine("mysql://u:p@host/db", pool_size=10, max_overflow=20)
- The above :class:`.Engine` will allow **at most 30 connections** to be in
+ The above :class:`_engine.Engine` will allow **at most 30 connections** to be in
play at any time, not including connections that were detached from the
engine or invalidated. If a request for a new connection arrives and
30 connections are already in use by other parts of the application,
A common reason this can occur is that the application uses ORM sessions and
does not call :meth:`.Session.close` upon them one the work involving that
session is complete. Solution is to make sure ORM sessions if using the ORM,
- or engine-bound :class:`.Connection` objects if using Core, are explicitly
+ or engine-bound :class:`_engine.Connection` objects if using Core, are explicitly
closed at the end of the work being done, either via the appropriate
``.close()`` method, or by using one of the available context managers (e.g.
"with:" statement) to properly release the resource.
------------------------------------------------------------------------------------------
This error condition was added to SQLAlchemy as of version 1.4. The error
-refers to the state where a :class:`.Connection` is placed into a transaction
-using a method like :meth:`.Connection.begin`, and then a further "sub" transaction
+refers to the state where a :class:`_engine.Connection` is placed into a transaction
+using a method like :meth:`_engine.Connection.begin`, and then a further "sub" transaction
is created within that scope; the "sub" transaction is then rolled back using
:meth:`.Transaction.rollback`, however the outer transaction is not rolled back.
The "subtransaction" pattern in Core comes into play often when using the ORM
pattern described at :ref:`session_external_transaction`. As this pattern
-involves a behavior called "connection branching", where a :class:`.Connection`
-serves a "branched" :class:`.Connection` object to the :class:`.Session` via
-its :meth:`.Connection.connect` method, the same transaction behavior comes
+involves a behavior called "connection branching", where a :class:`_engine.Connection`
+serves a "branched" :class:`_engine.Connection` object to the :class:`.Session` via
+its :meth:`_engine.Connection.connect` method, the same transaction behavior comes
into play; if the :class:`.Session` rolls back the transaction, and savepoints
have not been used to prevent a rollback of the entire transaction, the
-outermost transaction started on the :class:`.Connection` is now in an inactive
+outermost transaction started on the :class:`_engine.Connection` is now in an inactive
state.
more specific to the "stringification" use case but describes the general
background as well.
-Normally, a Core SQL construct or ORM :class:`.Query` object can be stringified
+Normally, a Core SQL construct or ORM :class:`_query.Query` object can be stringified
directly, such as when we use ``print()``::
>>> from sqlalchemy import column
<class 'sqlalchemy.dialects.postgresql.dml.OnConflictDoNothing'>
In order to stringify constructs that are specific to particular backend,
-the :meth:`.ClauseElement.compile` method must be used, passing either an
-:class:`.Engine` or a :class:`.Dialect` object which will invoke the correct
+the :meth:`_expression.ClauseElement.compile` method must be used, passing either an
+:class:`_engine.Engine` or a :class:`.Dialect` object which will invoke the correct
compiler. Below we use a PostgreSQL dialect::
>>> from sqlalchemy.dialects import postgresql
>>> print(insert_stmt.compile(dialect=postgresql.dialect()))
INSERT INTO my_table (x) VALUES (%(x)s) ON CONFLICT (y) DO NOTHING
-For an ORM :class:`.Query` object, the statement can be accessed using the
+For an ORM :class:`_query.Query` object, the statement can be accessed using the
:attr:`~.orm.query.Query.statement` accessor::
statement = query.statement
)
Above, the ``cprop`` attribute is used inline before it has been mapped,
-however this ``cprop`` attribute is not a :class:`.Column`,
+however this ``cprop`` attribute is not a :class:`_schema.Column`,
it's a :class:`.ColumnProperty`, which is an interim object and therefore
-does not have the full functionality of either the :class:`.Column` object
+does not have the full functionality of either the :class:`_schema.Column` object
or the :class:`.InstrumentedAttribute` object that will be mapped onto the
``Bar`` class once the declarative process is complete.
``__eq__()`` method that would allow it to interpret the comparison to the
number "5" as a SQL expression and not a regular Python comparison.
-The solution is to access the :class:`.Column` directly using the
+The solution is to access the :class:`_schema.Column` directly using the
:attr:`.ColumnProperty.expression` attribute::
class Bar(Base):
This error refers to the concept of "bound metadata", described at
:ref:`dbengine_implicit`. The issue occurs when one invokes the
:meth:`.Executable.execute` method directly off of a Core expression object
-that is not associated with any :class:`.Engine`::
+that is not associated with any :class:`_engine.Engine`::
metadata = MetaData()
table = Table('t', metadata, Column('q', Integer))
stmt = select([table])
result = stmt.execute() # <--- raises
-What the logic is expecting is that the :class:`.MetaData` object has
-been **bound** to a :class:`.Engine`::
+What the logic is expecting is that the :class:`_schema.MetaData` object has
+been **bound** to a :class:`_engine.Engine`::
engine = create_engine("mysql+pymysql://user:pass@host/db")
metadata = MetaData(bind=engine)
-Where above, any statement that derives from a :class:`.Table` which
-in turn derives from that :class:`.MetaData` will implicitly make use of
-the given :class:`.Engine` in order to invoke the statement.
+Where above, any statement that derives from a :class:`_schema.Table` which
+in turn derives from that :class:`_schema.MetaData` will implicitly make use of
+the given :class:`_engine.Engine` in order to invoke the statement.
Note that the concept of bound metadata is a **legacy pattern** and in most
cases is **highly discouraged**. The best way to invoke the statement is
-to pass it to the :meth:`.Connection.execute` method of a :class:`.Connection`::
+to pass it to the :meth:`_engine.Connection.execute` method of a :class:`_engine.Connection`::
with engine.connect() as conn:
result = conn.execute(stmt)
--------------------------------------------------------------------------------------
This refers to a change made as of SQLAlchemy 1.4 where a SELECT statement as generated
-by a function such as :func:`~.sql.expression.select`, but also including things like unions and textual
-SELECT expressions are no longer considered to be :class:`.FromClause` objects and
+by a function such as :func:`_expression.select`, but also including things like unions and textual
+SELECT expressions are no longer considered to be :class:`_expression.FromClause` objects and
can't be placed directly in the FROM clause of another SELECT statement without them
being wrapped in a :class:`.Subquery` first. This is a major conceptual change in the
Core and the full rationale is discussed at :ref:`change_4617`.
would produce a parenthesized, unnamed subquery. In most cases, this form of
SQL is not very useful as databases like MySQL and PostgreSQL require that
subqueries in FROM clauses have named aliases, which means using the
-:meth:`.SelectBase.alias` method or as of 1.4 using the
-:meth:`.SelectBase.subquery` method to produce this. On other databases, it
+:meth:`_expression.SelectBase.alias` method or as of 1.4 using the
+:meth:`_expression.SelectBase.subquery` method to produce this. On other databases, it
is still much clearer for the subquery to have a name to resolve any ambiguity
on future references to column names inside the subquery.
Beyond the above practical reasons, there are a lot of other SQLAlchemy-oriented
reasons the change is being made. The correct form of the above two statements
-therefore requires that :meth:`.SelectBase.subquery` is used::
+therefore requires that :meth:`_expression.SelectBase.subquery` is used::
subq = stmt.subquery()
----------------------------------------------------------------
SQLAlchemy performs application-level connection pooling automatically
-in most cases. With the exception of SQLite, a :class:`.Engine` object
+in most cases. With the exception of SQLite, a :class:`_engine.Engine` object
refers to a :class:`.QueuePool` as a source of connectivity.
For more detail, see :ref:`engines_toplevel` and :ref:`pooling_toplevel`.
for this issue is that the connection is **invalidated** when such a failure
mode occurs so that the underlying database connection to MySQL is discarded.
This invalidation occurs automatically for many known failure modes and can
-also be called explicitly via the :meth:`.Connection.invalidate` method.
+also be called explicitly via the :meth:`_engine.Connection.invalidate` method.
There is also a second class of failure modes within this category where a context manager
such as ``with session.begin_nested():`` wants to "roll back" the transaction
the server receives interleaved messages and breaks the state of the connection.
This scenario can occur very easily if a program uses Python's "multiprocessing"
- module and makes use of an :class:`.Engine` that was created in the parent
+ module and makes use of an :class:`_engine.Engine` that was created in the parent
process. It's common that "multiprocessing" is in use when using tools like
- Celery. The correct approach should be either that a new :class:`.Engine`
- is produced when a child process first starts, discarding any :class:`.Engine`
- that came down from the parent process; or, the :class:`.Engine` that's inherited
+ Celery. The correct approach should be either that a new :class:`_engine.Engine`
+ is produced when a child process first starts, discarding any :class:`_engine.Engine`
+ that came down from the parent process; or, the :class:`_engine.Engine` that's inherited
from the parent process can have it's internal pool of connections disposed by
- calling :meth:`.Engine.dispose`.
+ calling :meth:`_engine.Engine.dispose`.
* **Greenlet Monkeypatching w/ Exits** - When using a library like gevent or eventlet
that monkeypatches the Python networking API, libraries like PyMySQL are now
--------------------------------------------------------------
With a regular SA engine-level Connection, you can get at a pool-proxied
-version of the DBAPI connection via the :attr:`.Connection.connection` attribute on
-:class:`.Connection`, and for the really-real DBAPI connection you can call the
+version of the DBAPI connection via the :attr:`_engine.Connection.connection` attribute on
+:class:`_engine.Connection`, and for the really-real DBAPI connection you can call the
:attr:`.ConnectionFairy.connection` attribute on that - but there should never be any need to access
the non-pool-proxied DBAPI connection, as all methods are proxied through::
operation-specific settings on the connection back to normal before returning
it to the pool.
-As an alternative to reverting settings, you can call the :meth:`.Connection.detach` method on
-either :class:`.Connection` or the proxied connection, which will de-associate
+As an alternative to reverting settings, you can call the :meth:`_engine.Connection.detach` method on
+either :class:`_engine.Connection` or the proxied connection, which will de-associate
the connection from the pool such that it will be closed and discarded
-when :meth:`.Connection.close` is called::
+when :meth:`_engine.Connection.close` is called::
conn = engine.connect()
conn.detach() # detaches the DBAPI connection from the connection pool
are used by multiple processes concurrently, leading to broken messaging (the latter
case is typically the most common).
-The SQLAlchemy :class:`.Engine` object refers to a connection pool of existing
+The SQLAlchemy :class:`_engine.Engine` object refers to a connection pool of existing
database connections. So when this object is replicated to a child process,
the goal is to ensure that no database connections are carried over. There
are three general approaches to this:
1. Disable pooling using :class:`.NullPool`. This is the most simplistic,
- one shot system that prevents the :class:`.Engine` from using any connection
+ one shot system that prevents the :class:`_engine.Engine` from using any connection
more than once.
-2. Call :meth:`.Engine.dispose` on any given :class:`.Engine` as soon one is
+2. Call :meth:`_engine.Engine.dispose` on any given :class:`_engine.Engine` as soon one is
within the new process. In Python multiprocessing, constructs such as
``multiprocessing.Pool`` include "initializer" hooks which are a place
that this can be performed; otherwise at the top of where ``os.fork()``
or where the ``Process`` object begins the child fork, a single call
- to :meth:`.Engine.dispose` will ensure any remaining connections are flushed.
+ to :meth:`_engine.Engine.dispose` will ensure any remaining connections are flushed.
3. An event handler can be applied to the connection pool that tests for connections
being shared across process boundaries, and invalidates them. This looks like
(connection_record.info['pid'], pid)
)
- These events are applied to an :class:`.Engine` as soon as its created::
+ These events are applied to an :class:`_engine.Engine` as soon as its created::
engine = create_engine("...")
add_engine_pidguard(engine)
-The above strategies will accommodate the case of an :class:`.Engine`
+The above strategies will accommodate the case of an :class:`_engine.Engine`
being shared among processes. However, for the case of a transaction-active
-:class:`.Session` or :class:`.Connection` being shared, there's no automatic
+:class:`.Session` or :class:`_engine.Connection` being shared, there's no automatic
fix for this; an application needs to ensure a new child process only
-initiate new :class:`.Connection` objects and transactions, as well as ORM
+initiate new :class:`_engine.Connection` objects and transactions, as well as ORM
:class:`.Session` objects. For a :class:`.Session` object, technically
this is only needed if the session is currently transaction-bound, however
the scope of a single :class:`.Session` is in any case intended to be
the result object is closed or all rows are exhausted.
The call to ``mytable.drop(engine)`` attempts to emit DROP TABLE on a second
-connection procured from the :class:`.Engine` which will lock.
+connection procured from the :class:`_engine.Engine` which will lock.
The solution is to close out all connections before emitting DROP TABLE::
How can I sort Table objects in order of their dependency?
==========================================================
-This is available via the :attr:`.MetaData.sorted_tables` function::
+This is available via the :attr:`_schema.MetaData.sorted_tables` function::
metadata = MetaData()
# ... add Table objects to metadata
print(CreateTable(mytable).compile(engine))
-There's also a special form of :class:`.Engine` available via
+There's also a special form of :class:`_engine.Engine` available via
:func:`.create_mock_engine` that allows one to dump an entire
metadata creation sequence as a string, using this recipe::
How can I subclass Table/Column to provide certain behaviors/configurations?
============================================================================
-:class:`.Table` and :class:`.Column` are not good targets for direct subclassing.
+:class:`_schema.Table` and :class:`_schema.Column` are not good targets for direct subclassing.
However, there are simple ways to get on-construction behaviors using creation
functions, and behaviors related to the linkages between schema objects such as
constraint conventions or naming conventions using attachment events.
.. note::
It's important to note that we're only talking about the SQLAlchemy ORM; an
- application which builds on Core and deals only with :class:`.Table` objects,
- :func:`~.sql.expression.select` constructs and the like, **does not** need any primary key
+ application which builds on Core and deals only with :class:`_schema.Table` objects,
+ :func:`_expression.select` constructs and the like, **does not** need any primary key
to be present on or associated with a table in any way (though again, in SQL, all tables
should really have some kind of primary key, lest you need to actually
update or delete specific rows).
How do I get a list of all columns, relationships, mapped attributes, etc. given a mapped class?
-------------------------------------------------------------------------------------------------
-This information is all available from the :class:`.Mapper` object.
+This information is all available from the :class:`_orm.Mapper` object.
-To get at the :class:`.Mapper` for a particular mapped class, call the
-:func:`.inspect` function on it::
+To get at the :class:`_orm.Mapper` for a particular mapped class, call the
+:func:`_sa.inspect` function on it::
from sqlalchemy import inspect
From there, all information about the class can be accessed through properties
such as:
-* :attr:`.Mapper.attrs` - a namespace of all mapped attributes. The attributes
+* :attr:`_orm.Mapper.attrs` - a namespace of all mapped attributes. The attributes
themselves are instances of :class:`.MapperProperty`, which contain additional
attributes that can lead to the mapped SQL expression or column, if applicable.
-* :attr:`.Mapper.column_attrs` - the mapped attribute namespace
+* :attr:`_orm.Mapper.column_attrs` - the mapped attribute namespace
limited to column and SQL expression attributes. You might want to use
- :attr:`.Mapper.columns` to get at the :class:`.Column` objects directly.
+ :attr:`_orm.Mapper.columns` to get at the :class:`_schema.Column` objects directly.
-* :attr:`.Mapper.relationships` - namespace of all :class:`.RelationshipProperty` attributes.
+* :attr:`_orm.Mapper.relationships` - namespace of all :class:`.RelationshipProperty` attributes.
-* :attr:`.Mapper.all_orm_descriptors` - namespace of all mapped attributes, plus user-defined
+* :attr:`_orm.Mapper.all_orm_descriptors` - namespace of all mapped attributes, plus user-defined
attributes defined using systems such as :class:`.hybrid_property`, :class:`.AssociationProxy` and others.
-* :attr:`.Mapper.columns` - A namespace of :class:`.Column` objects and other named
+* :attr:`_orm.Mapper.columns` - A namespace of :class:`_schema.Column` objects and other named
SQL expressions associated with the mapping.
-* :attr:`.Mapper.mapped_table` - The :class:`.Table` or other selectable to which
+* :attr:`_orm.Mapper.mapped_table` - The :class:`_schema.Table` or other selectable to which
this mapper is mapped.
-* :attr:`.Mapper.local_table` - The :class:`.Table` that is "local" to this mapper;
- this differs from :attr:`.Mapper.mapped_table` in the case of a mapper mapped
+* :attr:`_orm.Mapper.local_table` - The :class:`_schema.Table` that is "local" to this mapper;
+ this differs from :attr:`_orm.Mapper.mapped_table` in the case of a mapper mapped
using inheritance to a composed selectable.
.. _faq_combining_columns:
foo = relationship("Dest", primaryjoin=and_("MyClass.id==Dest.foo_id", "MyClass.foo==Dest.bar"))
-That's an ``and_()`` of two string expressions, which SQLAlchemy cannot apply any mapping towards. Declarative allows :func:`.relationship` arguments to be specified as strings, which are converted into expression objects using ``eval()``. But this doesn't occur inside of an ``and_()`` expression - it's a special operation declarative applies only to the *entirety* of what's passed to primaryjoin or other arguments as a string::
+That's an ``and_()`` of two string expressions, which SQLAlchemy cannot apply any mapping towards. Declarative allows :func:`_orm.relationship` arguments to be specified as strings, which are converted into expression objects using ``eval()``. But this doesn't occur inside of an ``and_()`` expression - it's a special operation declarative applies only to the *entirety* of what's passed to primaryjoin or other arguments as a string::
class MyClass(Base):
# ....
using ``LIMIT`` or ``OFFSET`` should **always** specify an ``ORDER BY``.
Otherwise, it is not deterministic which rows will actually be returned.
-When we use a SQLAlchemy method like :meth:`.Query.first`, we are in fact
+When we use a SQLAlchemy method like :meth:`_query.Query.first`, we are in fact
applying a ``LIMIT`` of one to the query, so without an explicit ordering
it is not deterministic what row we actually get back.
While we may not notice this for simple queries on databases that usually
returns rows in their natural
-order, it becomes much more of an issue if we also use :func:`.orm.subqueryload`
+order, it becomes much more of an issue if we also use :func:`_orm.subqueryload`
to load related collections, and we may not be loading the collections
as intended.
-SQLAlchemy implements :func:`.orm.subqueryload` by issuing a separate query,
+SQLAlchemy implements :func:`_orm.subqueryload` by issuing a separate query,
the results of which are matched up to the results from the first query.
We see two queries emitted like this:
The solution to this problem is to always specify a deterministic sort order,
so that the main query always returns the same set of rows. This generally
-means that you should :meth:`.Query.order_by` on a unique column on the table.
+means that you should :meth:`_query.Query.order_by` on a unique column on the table.
The primary key is a good choice for this::
session.query(User).options(subqueryload(User.addresses)).order_by(User.id).first()
-Note that the :func:`.joinedload` eager loader strategy does not suffer from
+Note that the :func:`_orm.joinedload` eager loader strategy does not suffer from
the same problem because only one query is ever issued, so the load query
cannot be different from the main query. Similarly, the :func:`.selectinload`
eager loader strategy also does not have this issue as it links its collection
being issued which could be better organized into much fewer queries.
When using the SQLAlchemy ORM, the "eager loading"
feature is provided to partially (:func:`.contains_eager()`) or fully
-(:func:`.joinedload()`, :func:`.subqueryload()`)
+(:func:`_orm.joinedload()`, :func:`.subqueryload()`)
automate this activity, but without
the ORM "eager loading" typically means to use joins so that results across multiple
tables can be loaded in one result set instead of multiplying numbers
or very long calls to ``fetchall()``, it may
mean your query is returning more rows than expected, or that the fetching
of rows itself is slow. The ORM itself typically uses ``fetchall()`` to fetch
-rows (or ``fetchmany()`` if the :meth:`.Query.yield_per` option is used).
+rows (or ``fetchmany()`` if the :meth:`_query.Query.yield_per` option is used).
An inordinately large number of rows would be indicated
by a very slow call to ``fetchall()`` at the DBAPI level::
to have many rows, can be the result of a cartesian product - when multiple
sets of rows are combined together without appropriately joining the tables
together. It's often easy to produce this behavior with SQLAlchemy Core or
-ORM query if the wrong :class:`.Column` objects are used in a complex query,
+ORM query if the wrong :class:`_schema.Column` objects are used in a complex query,
pulling in additional FROM clauses that are unexpected.
On the other hand, a fast call to ``fetchall()`` at the DBAPI level, but then
3. We can run whole queries while setting them to definitely overwrite
already-loaded objects as they read rows by using
- :meth:`.Query.populate_existing`.
+ :meth:`_query.Query.populate_existing`.
But remember, **the ORM cannot see changes in rows if our isolation
level is repeatable read or higher, unless we start a new transaction**.
My Query does not return the same number of objects as query.count() tells me - why?
-------------------------------------------------------------------------------------
-The :class:`.Query` object, when asked to return a list of ORM-mapped objects,
+The :class:`_query.Query` object, when asked to return a list of ORM-mapped objects,
will **deduplicate the objects based on primary key**. That is, if we
for example use the ``User`` mapping described at :ref:`ormtutorial_toplevel`,
and we had a SQL query like the following::
Above, the sample data used in the tutorial has two rows in the ``addresses``
table for the ``users`` row with the name ``'jack'``, primary key value 5.
-If we ask the above query for a :meth:`.Query.count`, we will get the answer
+If we ask the above query for a :meth:`_query.Query.count`, we will get the answer
**2**::
>>> q.count()
2
-However, if we run :meth:`.Query.all` or iterate over the query, we get back
+However, if we run :meth:`_query.Query.all` or iterate over the query, we get back
**one element**::
>>> q.all()
[User(id=5, name='jack', ...)]
-This is because when the :class:`.Query` object returns full entities, they
+This is because when the :class:`_query.Query` object returns full entities, they
are **deduplicated**. This does not occur if we instead request individual
columns back::
>>> session.query(User.id, User.name).outerjoin(User.addresses).filter(User.name == 'jack').all()
[(5, 'jack'), (5, 'jack')]
-There are two main reasons the :class:`.Query` will deduplicate:
+There are two main reasons the :class:`_query.Query` will deduplicate:
* **To allow joined eager loading to work correctly** - :ref:`joined_eager_loading`
works by querying rows using joins against related tables, where it then routes
were queried, e.g. all the ``User()`` objects whose name is ``'jack'`` which
for us is one object, with
the ``User.addresses`` collection eagerly loaded as was indicated either
- by ``lazy='joined'`` on the :func:`.relationship` or via the :func:`.joinedload`
+ by ``lazy='joined'`` on the :func:`_orm.relationship` or via the :func:`_orm.joinedload`
option. For consistency, the deduplication is still applied whether or not
the joinedload is established, as the key philosophy behind eager loading
is that these options never affect the result.
which must be maintained uniquely on its identity, that is, its primary key /
class combination. It doesn't actually make much sense, if one is querying for
``User()`` objects, to get the same object multiple times in the list. An
- ordered set would potentially be a better representation of what :class:`.Query`
+ ordered set would potentially be a better representation of what :class:`_query.Query`
seeks to return when it returns full objects.
-The issue of :class:`.Query` deduplication remains problematic, mostly for the
-single reason that the :meth:`.Query.count` method is inconsistent, and the
+The issue of :class:`_query.Query` deduplication remains problematic, mostly for the
+single reason that the :meth:`_query.Query.count` method is inconsistent, and the
current status is that joined eager loading has in recent releases been
superseded first by the "subquery eager loading" strategy and more recently the
"select IN eager loading" strategy, both of which are generally more
appropriate for collection eager loading. As this evolution continues,
-SQLAlchemy may alter this behavior on :class:`.Query`, which may also involve
+SQLAlchemy may alter this behavior on :class:`_query.Query`, which may also involve
new APIs in order to more directly control this behavior, and may also alter
the behavior of joined eager loading in order to create a more consistent usage
pattern.
------------------------------------------------------------------------------------------------------------------
Rows returned by an outer join may contain NULL for part of the primary key,
-as the primary key is the composite of both tables. The :class:`.Query` object ignores incoming rows
+as the primary key is the composite of both tables. The :class:`_query.Query` object ignores incoming rows
that don't have an acceptable primary key. Based on the setting of the ``allow_partial_pks``
flag on :func:`.mapper`, a primary key is accepted if the value has at least one non-NULL
value, or alternatively if the value has no NULL values. See ``allow_partial_pks``
The Python ``__len__()`` magic method applied to an object allows the ``len()``
builtin to be used to determine the length of the collection. It's intuitive
-that a SQL query object would link ``__len__()`` to the :meth:`.Query.count`
+that a SQL query object would link ``__len__()`` to the :meth:`_query.Query.count`
method, which emits a `SELECT COUNT`. The reason this is not possible is
because evaluating the query as a list would incur two SQL calls instead of
one::
See:
-* :ref:`orm_tutorial_literal_sql` - Ad-hoc textual blocks with :class:`.Query`
+* :ref:`orm_tutorial_literal_sql` - Ad-hoc textual blocks with :class:`_query.Query`
* :ref:`session_sql_expressions` - Using :class:`.Session` with textual SQL directly.
Manipulation of foreign key attributes is of course entirely legal. However,
setting a foreign-key attribute to a new value currently does not trigger
-an "expire" event of the :func:`.relationship` in which it's involved. This means
+an "expire" event of the :func:`_orm.relationship` in which it's involved. This means
that for the following sequence::
o = Session.query(SomeClass).first()
.. topic:: Attribute loading for non-persistent objects
One variant on the "pending" behavior above is if we use the flag
- ``load_on_pending`` on :func:`.relationship`. When this flag is set, the
+ ``load_on_pending`` on :func:`_orm.relationship`. When this flag is set, the
lazy loader will emit for ``new_obj.foo`` before the INSERT proceeds; another
variant of this is to use the :meth:`.Session.enable_relationship_loading`
method, which can "attach" an object to a :class:`.Session` in such a way that
-------------------------------------------------------------
An object that has other objects related to it will correspond to the
-:func:`.relationship` constructs set up between mappers. This code fragment will
+:func:`_orm.relationship` constructs set up between mappers. This code fragment will
iterate all the objects, correcting for cycles as well::
from sqlalchemy import inspect
------------------------------------------------------------------------------------
The "stringification" of a SQLAlchemy Core statement object or
-expression fragment, as well as that of an ORM :class:`.Query` object,
+expression fragment, as well as that of an ORM :class:`_query.Query` object,
in the majority of simple cases is as simple as using
the ``str()`` builtin function, as below when use it with the ``print``
function (note the Python ``print`` function also calls ``str()`` automatically
FROM my_table
The ``str()`` builtin, or an equivalent, can be invoked on ORM
-:class:`.Query` object as well as any statement such as that of
-:func:`~.sql.expression.select`, :func:`~.sql.expression.insert` etc. and also any expression fragment, such
+:class:`_query.Query` object as well as any statement such as that of
+:func:`_expression.select`, :func:`_expression.insert` etc. and also any expression fragment, such
as::
>>> from sqlalchemy import column
syntax for the database we are targeting, or the operation may raise a
:class:`.UnsupportedCompilationError` exception. In these cases, it is
necessary that we stringify the statement using the
-:meth:`.ClauseElement.compile` method, while passing along an :class:`.Engine`
+:meth:`_expression.ClauseElement.compile` method, while passing along an :class:`_engine.Engine`
or :class:`.Dialect` object that represents the target database. Such as
below, if we have a MySQL database engine, we can stringify a statement in
terms of the MySQL dialect::
engine = create_engine("mysql+pymysql://scott:tiger@localhost/test")
print(statement.compile(engine))
-More directly, without building up an :class:`.Engine` object we can
+More directly, without building up an :class:`_engine.Engine` object we can
instantiate a :class:`.Dialect` object directly, as below where we
use a PostgreSQL dialect::
print(statement.compile(dialect=postgresql.dialect()))
When given an ORM :class:`~.orm.query.Query` object, in order to get at the
-:meth:`.ClauseElement.compile`
+:meth:`_expression.ClauseElement.compile`
method we only need access the :attr:`~.orm.query.Query.statement`
accessor first::
We can also usually force parenthesization around a binary expression (e.g.
an expression that has left/right operands and an operator) using the
-:meth:`.ColumnElement.self_group` method::
+:meth:`_expression.ColumnElement.self_group` method::
>>> print((column('q1') + column('q2')).self_group().op('->')(column('p')))
(q1 + q2) -> p
A term used in SQLAlchemy to describe a SQL construct that represents
a collection of rows. It's largely similar to the concept of a
"relation" in :term:`relational algebra`. In SQLAlchemy, objects
- that subclass the :class:`.Selectable` class are considered to be
+ that subclass the :class:`expression.Selectable` class are considered to be
usable as "selectables" when using SQLAlchemy Core. The two most
- common constructs are that of the :class:`.Table` and that of the
- :class:`.Select` statement.
+ common constructs are that of the :class:`_schema.Table` and that of the
+ :class:`_expression.Select` statement.
annotations
Annotations are a concept used internally by SQLAlchemy in order to store
- additional information along with :class:`.ClauseElement` objects. A Python
+ additional information along with :class:`_expression.ClauseElement` objects. A Python
dictionary is associated with a copy of the object, which contains key/value
pairs significant to various internal systems, mostly within the ORM::
some_column = Column('some_column', Integer)
some_column_annotated = some_column._annotate({"entity": User})
- The annotation system differs from the public dictionary :attr:`.Column.info`
- in that the above annotation operation creates a *copy* of the new :class:`.Column`,
+ The annotation system differs from the public dictionary :attr:`_schema.Column.info`
+ in that the above annotation operation creates a *copy* of the new :class:`_schema.Column`,
rather than considering all annotation values to be part of a single
unit. The ORM creates copies of expression objects in order to
apply annotations that are specific to their context, such as to differentiate
The ``MyClass`` class will be :term:`mapped` when its definition
is complete, at which point the ``id`` and ``data`` attributes,
- starting out as :class:`.Column` objects, will be replaced
+ starting out as :class:`_schema.Column` objects, will be replaced
by the :term:`instrumentation` system with instances
of :class:`.InstrumentedAttribute`, which are descriptors that
provide the above mentioned ``__get__()``, ``__set__()`` and
The term "metadata" generally refers to "data that describes data";
data that itself represents the format and/or structure of some other
kind of data. In SQLAlchemy, the term "metadata" typically refers to
- the :class:`.MetaData` construct, which is a collection of information
+ the :class:`_schema.MetaData` construct, which is a collection of information
about the tables, columns, constraints, and other :term:`DDL` objects
that may exist in a particular database.
A term used in SQLAlchemy to describe how an ORM persistence action that
takes place on a particular object would extend into other objects
which are directly associated with that object. In SQLAlchemy, these
- object associations are configured using the :func:`.relationship`
- construct. :func:`.relationship` contains a parameter called
- :paramref:`.relationship.cascade` which provides options on how certain
+ object associations are configured using the :func:`_orm.relationship`
+ construct. :func:`_orm.relationship` contains a parameter called
+ :paramref:`_orm.relationship.cascade` which provides options on how certain
persistence operations may cascade.
The term "cascades" as well as the general architecture of this system
an attribute that is populated with its database-side value
at the same time as when the object itself is loaded from the database.
In SQLAlchemy, "eager loading" usually refers to related collections
- of objects that are mapped using the :func:`.relationship` construct.
+ of objects that are mapped using the :func:`_orm.relationship` construct.
Eager loading is the opposite of :term:`lazy loading`.
.. seealso::
mapping
mapped
We say a class is "mapped" when it has been passed through the
- :func:`.orm.mapper` function. This process associates the
+ :func:`_orm.mapper` function. This process associates the
class with a database table or other :term:`selectable`
construct, so that instances of it can be persisted
using a :class:`.Session` as well as loaded using a
additional state added to the object.
The two SQLAlchemy objects that make the most use of
- method chaining are the :class:`~.expression.Select`
+ method chaining are the :class:`_expression.Select`
object and the :class:`.orm.query.Query` object.
- For example, a :class:`~.expression.Select` object can
+ For example, a :class:`_expression.Select` object can
be assigned two expressions to its WHERE clause as well
- as an ORDER BY clause by calling upon the :meth:`~.Select.where`
- and :meth:`~.Select.order_by` methods::
+ as an ORDER BY clause by calling upon the :meth:`_expression.Select.where`
+ and :meth:`_expression.Select.order_by` methods::
stmt = select([user.c.name]).\
where(user.c.id > 5).\
order_by(user.c.name)
Each method call above returns a copy of the original
- :class:`~.expression.Select` object with additional qualifiers
+ :class:`_expression.Select` object with additional qualifiers
added.
.. seealso::
Linking Relationships with Backref
----------------------------------
-The :paramref:`~.relationship.backref` keyword argument was first introduced in :ref:`ormtutorial_toplevel`, and has been
+The :paramref:`_orm.relationship.backref` keyword argument was first introduced in :ref:`ormtutorial_toplevel`, and has been
mentioned throughout many of the examples here. What does it actually do ? Let's start
with the canonical ``User`` and ``Address`` scenario::
``User.addresses``. It also establishes a ``.user`` attribute on ``Address`` which will
refer to the parent ``User`` object.
-In fact, the :paramref:`~.relationship.backref` keyword is only a common shortcut for placing a second
-:func:`.relationship` onto the ``Address`` mapping, including the establishment
+In fact, the :paramref:`_orm.relationship.backref` keyword is only a common shortcut for placing a second
+:func:`_orm.relationship` onto the ``Address`` mapping, including the establishment
of an event listener on both sides which will mirror attribute operations
in both directions. The above configuration is equivalent to::
user = relationship("User", back_populates="addresses")
Above, we add a ``.user`` relationship to ``Address`` explicitly. On
-both relationships, the :paramref:`~.relationship.back_populates` directive tells each relationship
+both relationships, the :paramref:`_orm.relationship.back_populates` directive tells each relationship
about the other one, indicating that they should establish "bidirectional"
behavior between each other. The primary effect of this configuration
is that the relationship adds event handlers to both attributes
occurs entirely in Python without any interaction with the SQL database.
Without this behavior, the proper state would be apparent on both sides once the
data has been flushed to the database, and later reloaded after a commit or
-expiration operation occurs. The :paramref:`~.relationship.backref`/:paramref:`~.relationship.back_populates` behavior has the advantage
+expiration operation occurs. The :paramref:`_orm.relationship.backref`/:paramref:`_orm.relationship.back_populates` behavior has the advantage
that common bidirectional operations can reflect the correct state without requiring
a database round trip.
-Remember, when the :paramref:`~.relationship.backref` keyword is used on a single relationship, it's
+Remember, when the :paramref:`_orm.relationship.backref` keyword is used on a single relationship, it's
exactly the same as if the above two relationships were created individually
-using :paramref:`~.relationship.back_populates` on each.
+using :paramref:`_orm.relationship.back_populates` on each.
Backref Arguments
~~~~~~~~~~~~~~~~~
-We've established that the :paramref:`~.relationship.backref` keyword is merely a shortcut for building
-two individual :func:`.relationship` constructs that refer to each other. Part of
+We've established that the :paramref:`_orm.relationship.backref` keyword is merely a shortcut for building
+two individual :func:`_orm.relationship` constructs that refer to each other. Part of
the behavior of this shortcut is that certain configurational arguments applied to
-the :func:`.relationship`
+the :func:`_orm.relationship`
will also be applied to the other direction - namely those arguments that describe
the relationship at a schema level, and are unlikely to be different in the reverse
direction. The usual case
-here is a many-to-many :func:`.relationship` that has a :paramref:`~.relationship.secondary` argument,
-or a one-to-many or many-to-one which has a :paramref:`~.relationship.primaryjoin` argument (the
-:paramref:`~.relationship.primaryjoin` argument is discussed in :ref:`relationship_primaryjoin`). Such
+here is a many-to-many :func:`_orm.relationship` that has a :paramref:`_orm.relationship.secondary` argument,
+or a one-to-many or many-to-one which has a :paramref:`_orm.relationship.primaryjoin` argument (the
+:paramref:`_orm.relationship.primaryjoin` argument is discussed in :ref:`relationship_primaryjoin`). Such
as if we limited the list of ``Address`` objects to those which start with "tony"::
from sqlalchemy import Integer, ForeignKey, String, Column
This reuse of arguments should pretty much do the "right thing" - it
uses only arguments that are applicable, and in the case of a many-to-
many relationship, will reverse the usage of
-:paramref:`~.relationship.primaryjoin` and
-:paramref:`~.relationship.secondaryjoin` to correspond to the other
+:paramref:`_orm.relationship.primaryjoin` and
+:paramref:`_orm.relationship.secondaryjoin` to correspond to the other
direction (see the example in :ref:`self_referential_many_to_many` for
this).
It's very often the case however that we'd like to specify arguments
that are specific to just the side where we happened to place the
-"backref". This includes :func:`.relationship` arguments like
-:paramref:`~.relationship.lazy`,
-:paramref:`~.relationship.remote_side`,
-:paramref:`~.relationship.cascade` and
-:paramref:`~.relationship.cascade_backrefs`. For this case we use
+"backref". This includes :func:`_orm.relationship` arguments like
+:paramref:`_orm.relationship.lazy`,
+:paramref:`_orm.relationship.remote_side`,
+:paramref:`_orm.relationship.cascade` and
+:paramref:`_orm.relationship.cascade_backrefs`. For this case we use
the :func:`.backref` function in place of a string::
# <other imports>
side, indicating that when a query against ``Address`` is made, a join to the ``User``
entity should be made automatically which will populate the ``.user`` attribute of each
returned ``Address``. The :func:`.backref` function formatted the arguments we gave
-it into a form that is interpreted by the receiving :func:`.relationship` as additional
+it into a form that is interpreted by the receiving :func:`_orm.relationship` as additional
arguments to be applied to the new relationship it creates.
Setting cascade for backrefs
:class:`.Session` as a :term:`pending` object.
Since this behavior has been identified as counter-intuitive to most people,
-it can be disabled by setting :paramref:`~.relationship.cascade_backrefs`
+it can be disabled by setting :paramref:`_orm.relationship.cascade_backrefs`
to False, as in::
An unusual case is that of the "one way backref". This is where the
"back-populating" behavior of the backref is only desirable in one
direction. An example of this is a collection which contains a
-filtering :paramref:`~.relationship.primaryjoin` condition. We'd
+filtering :paramref:`_orm.relationship.primaryjoin` condition. We'd
like to append items to this collection as needed, and have them
populate the "parent" object on the incoming object. However, we'd
also like to have items that are not part of the collection, but still
the collection.
Taking our previous example, where we established a
-:paramref:`~.relationship.primaryjoin` that limited the collection
+:paramref:`_orm.relationship.primaryjoin` that limited the collection
only to ``Address`` objects whose email address started with the word
``tony``, the usual backref behavior is that all items populate in
both directions. We wouldn't want this behavior for a case like the
the transaction committed and their attributes expired for a re-load, the ``addresses``
collection will hit the database on next access and no longer have this ``Address`` object
present, due to the filtering condition. But we can do away with this unwanted side
-of the "backref" behavior on the Python side by using two separate :func:`.relationship` constructs,
-placing :paramref:`~.relationship.back_populates` only on one side::
+of the "backref" behavior on the Python side by using two separate :func:`_orm.relationship` constructs,
+placing :paramref:`_orm.relationship.back_populates` only on one side::
from sqlalchemy import Integer, ForeignKey, String, Column
from sqlalchemy.ext.declarative import declarative_base
False
Of course, we've disabled some of the usefulness of
-:paramref:`~.relationship.backref` here, in that when we do append an
+:paramref:`_orm.relationship.backref` here, in that when we do append an
``Address`` that corresponds to the criteria of
``email.startswith('tony')``, it won't show up in the
``User.addresses`` collection until the session is flushed, and the
~~~~~~~~~~~
A one to many relationship places a foreign key on the child table referencing
-the parent. :func:`.relationship` is then specified on the parent, as referencing
+the parent. :func:`_orm.relationship` is then specified on the parent, as referencing
a collection of items represented by the child::
class Parent(Base):
parent_id = Column(Integer, ForeignKey('parent.id'))
To establish a bidirectional relationship in one-to-many, where the "reverse"
-side is a many to one, specify an additional :func:`.relationship` and connect
-the two using the :paramref:`.relationship.back_populates` parameter::
+side is a many to one, specify an additional :func:`_orm.relationship` and connect
+the two using the :paramref:`_orm.relationship.back_populates` parameter::
class Parent(Base):
__tablename__ = 'parent'
``Child`` will get a ``parent`` attribute with many-to-one semantics.
-Alternatively, the :paramref:`~.relationship.backref` option may be used
-on a single :func:`.relationship` instead of using
-:paramref:`~.relationship.back_populates`::
+Alternatively, the :paramref:`_orm.relationship.backref` option may be used
+on a single :func:`_orm.relationship` instead of using
+:paramref:`_orm.relationship.back_populates`::
class Parent(Base):
__tablename__ = 'parent'
~~~~~~~~~~~
Many to one places a foreign key in the parent table referencing the child.
-:func:`.relationship` is declared on the parent, where a new scalar-holding
+:func:`_orm.relationship` is declared on the parent, where a new scalar-holding
attribute will be created::
class Parent(Base):
__tablename__ = 'child'
id = Column(Integer, primary_key=True)
-Bidirectional behavior is achieved by adding a second :func:`.relationship`
-and applying the :paramref:`.relationship.back_populates` parameter
+Bidirectional behavior is achieved by adding a second :func:`_orm.relationship`
+and applying the :paramref:`_orm.relationship.back_populates` parameter
in both directions::
class Parent(Base):
id = Column(Integer, primary_key=True)
parents = relationship("Parent", back_populates="child")
-Alternatively, the :paramref:`~.relationship.backref` parameter
-may be applied to a single :func:`.relationship`, such as ``Parent.child``::
+Alternatively, the :paramref:`_orm.relationship.backref` parameter
+may be applied to a single :func:`_orm.relationship`, such as ``Parent.child``::
class Parent(Base):
__tablename__ = 'parent'
~~~~~~~~~~
One To One is essentially a bidirectional relationship with a scalar
-attribute on both sides. To achieve this, the :paramref:`~.relationship.uselist` flag indicates
+attribute on both sides. To achieve this, the :paramref:`_orm.relationship.uselist` flag indicates
the placement of a scalar attribute instead of a collection on the "many" side
of the relationship. To convert one-to-many into one-to-one::
id = Column(Integer, primary_key=True)
parent = relationship("Parent", back_populates="child", uselist=False)
-As always, the :paramref:`.relationship.backref` and :func:`.backref` functions
-may be used in lieu of the :paramref:`.relationship.back_populates` approach;
+As always, the :paramref:`_orm.relationship.backref` and :func:`.backref` functions
+may be used in lieu of the :paramref:`_orm.relationship.back_populates` approach;
to specify ``uselist`` on a backref, use the :func:`.backref` function::
from sqlalchemy.orm import backref
~~~~~~~~~~~~
Many to Many adds an association table between two classes. The association
-table is indicated by the :paramref:`~.relationship.secondary` argument to
-:func:`.relationship`. Usually, the :class:`.Table` uses the :class:`.MetaData`
-object associated with the declarative base class, so that the :class:`.ForeignKey`
+table is indicated by the :paramref:`_orm.relationship.secondary` argument to
+:func:`_orm.relationship`. Usually, the :class:`_schema.Table` uses the :class:`_schema.MetaData`
+object associated with the declarative base class, so that the :class:`_schema.ForeignKey`
directives can locate the remote tables with which to link::
association_table = Table('association', Base.metadata,
id = Column(Integer, primary_key=True)
For a bidirectional relationship, both sides of the relationship contain a
-collection. Specify using :paramref:`.relationship.back_populates`, and
-for each :func:`.relationship` specify the common association table::
+collection. Specify using :paramref:`_orm.relationship.back_populates`, and
+for each :func:`_orm.relationship` specify the common association table::
association_table = Table('association', Base.metadata,
Column('left_id', Integer, ForeignKey('left.id')),
secondary=association_table,
back_populates="children")
-When using the :paramref:`~.relationship.backref` parameter instead of
-:paramref:`.relationship.back_populates`, the backref will automatically use
-the same :paramref:`~.relationship.secondary` argument for the reverse relationship::
+When using the :paramref:`_orm.relationship.backref` parameter instead of
+:paramref:`_orm.relationship.back_populates`, the backref will automatically use
+the same :paramref:`_orm.relationship.secondary` argument for the reverse relationship::
association_table = Table('association', Base.metadata,
Column('left_id', Integer, ForeignKey('left.id')),
__tablename__ = 'right'
id = Column(Integer, primary_key=True)
-The :paramref:`~.relationship.secondary` argument of :func:`.relationship` also accepts a callable
+The :paramref:`_orm.relationship.secondary` argument of :func:`_orm.relationship` also accepts a callable
that returns the ultimate argument, which is evaluated only when mappers are
first used. Using this, we can define the ``association_table`` at a later
point, as long as it's available to the callable after all module initialization
backref="parents")
.. warning:: When passed as a Python-evaluable string, the
- :paramref:`.relationship.secondary` argument is interpreted using Python's
+ :paramref:`_orm.relationship.secondary` argument is interpreted using Python's
``eval()`` function. **DO NOT PASS UNTRUSTED INPUT TO THIS STRING**. See
:ref:`declarative_relationship_eval` for details on declarative
- evaluation of :func:`.relationship` arguments.
+ evaluation of :func:`_orm.relationship` arguments.
.. _relationships_many_to_many_deletion:
Deleting Rows from the Many to Many Table
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-A behavior which is unique to the :paramref:`~.relationship.secondary` argument to :func:`.relationship`
-is that the :class:`.Table` which is specified here is automatically subject
+A behavior which is unique to the :paramref:`_orm.relationship.secondary` argument to :func:`_orm.relationship`
+is that the :class:`_schema.Table` which is specified here is automatically subject
to INSERT and DELETE statements, as objects are added or removed from the collection.
There is **no need to delete from this table manually**. The act of removing a
record from the collection will have the effect of the row being deleted on flush::
There are several possibilities here:
-* If there is a :func:`.relationship` from ``Parent`` to ``Child``, but there is
+* If there is a :func:`_orm.relationship` from ``Parent`` to ``Child``, but there is
**not** a reverse-relationship that links a particular ``Child`` to each ``Parent``,
SQLAlchemy will not have any awareness that when deleting this particular
``Child`` object, it needs to maintain the "secondary" table that links it to
the ``Child.parents`` collection to locate all ``Parent`` objects, and remove
each row from the "secondary" table which establishes this link. Note that
this relationship does not need to be bidirectional; SQLAlchemy is strictly
- looking at every :func:`.relationship` associated with the ``Child`` object
+ looking at every :func:`_orm.relationship` associated with the ``Child`` object
being deleted.
* A higher performing option here is to use ON DELETE CASCADE directives
with the foreign keys used by the database. Assuming the database supports
this feature, the database itself can be made to automatically delete rows in the
"secondary" table as referencing rows in "child" are deleted. SQLAlchemy
can be instructed to forego actively loading in the ``Child.parents``
- collection in this case using the :paramref:`~.relationship.passive_deletes`
- directive on :func:`.relationship`; see :ref:`passive_deletes` for more details
+ collection in this case using the :paramref:`_orm.relationship.passive_deletes`
+ directive on :func:`_orm.relationship`; see :ref:`passive_deletes` for more details
on this.
-Note again, these behaviors are *only* relevant to the :paramref:`~.relationship.secondary` option
-used with :func:`.relationship`. If dealing with association tables that
-are mapped explicitly and are *not* present in the :paramref:`~.relationship.secondary` option
-of a relevant :func:`.relationship`, cascade rules can be used instead
+Note again, these behaviors are *only* relevant to the :paramref:`_orm.relationship.secondary` option
+used with :func:`_orm.relationship`. If dealing with association tables that
+are mapped explicitly and are *not* present in the :paramref:`_orm.relationship.secondary` option
+of a relevant :func:`_orm.relationship`, cascade rules can be used instead
to automatically delete entities in reaction to a related entity being
deleted - see :ref:`unitofwork_cascades` for information on this feature.
The association object pattern is a variant on many-to-many: it's used
when your association table contains additional columns beyond those
which are foreign keys to the left and right tables. Instead of using
-the :paramref:`~.relationship.secondary` argument, you map a new class
+the :paramref:`_orm.relationship.secondary` argument, you map a new class
directly to the association table. The left side of the relationship
references the association object via one-to-many, and the association
class references the right side via many-to-one. Below we illustrate
__tablename__ = 'right'
id = Column(Integer, primary_key=True)
-As always, the bidirectional version makes use of :paramref:`.relationship.back_populates`
-or :paramref:`.relationship.backref`::
+As always, the bidirectional version makes use of :paramref:`_orm.relationship.back_populates`
+or :paramref:`_orm.relationship.backref`::
class Association(Base):
__tablename__ = 'association'
to how operations performed on a "parent" object relative to a
particular :class:`.Session` should be propagated to items
referred to by that relationship (e.g. "child" objects), and is
-affected by the :paramref:`.relationship.cascade` option.
+affected by the :paramref:`_orm.relationship.cascade` option.
The default behavior of cascade is limited to cascades of the
so-called :ref:`cascade_save_update` and :ref:`cascade_merge` settings.
long as they are attached to their parent, and are otherwise deleted.
Cascade behavior is configured using the
-:paramref:`~.relationship.cascade` option on
+:paramref:`_orm.relationship.cascade` option on
:func:`~sqlalchemy.orm.relationship`::
class Order(Base):
stating "The sections we have just covered can be a bit confusing.
However, in practice, it all works out nicely."
-The default value of :paramref:`~.relationship.cascade` is ``save-update, merge``.
+The default value of :paramref:`_orm.relationship.cascade` is ``save-update, merge``.
The typical alternative setting for this parameter is either
``all`` or more commonly ``all, delete-orphan``. The ``all`` symbol
is a synonym for ``save-update, merge, refresh-expire, expunge, delete``,
it is no longer associated with that parent.
The list of available values which can be specified for
-the :paramref:`~.relationship.cascade` parameter are described in the following subsections.
+the :paramref:`_orm.relationship.cascade` parameter are described in the following subsections.
.. _cascade_save_update:
``save-update`` cascade indicates that when an object is placed into a
:class:`.Session` via :meth:`.Session.add`, all the objects associated
-with it via this :func:`.relationship` should also be added to that
+with it via this :func:`_orm.relationship` should also be added to that
same :class:`.Session`. Suppose we have an object ``user1`` with two
related objects ``address1``, ``address2``::
backrefs, meaning that the association of a child object with a particular parent
can have the effect of the parent object being implicitly associated with that
child object's :class:`.Session`; this pattern, as well as how to modify its
-behavior using the :paramref:`~.relationship.cascade_backrefs` flag,
+behavior using the :paramref:`_orm.relationship.cascade_backrefs` flag,
is discussed in the section :ref:`backref_cascade`.
.. _cascade_delete:
cascade is not specified. Database level "ON DELETE" cascades are specific to the
"FOREIGN KEY" construct of the relational database; SQLAlchemy allows
configuration of these schema-level constructs at the :term:`DDL` level
- using options on :class:`.ForeignKeyConstraint` which are described
+ using options on :class:`_schema.ForeignKeyConstraint` which are described
at :ref:`on_update_on_delete`.
It is important to note the differences between the ORM and the relational
level. An attempt by SQLAlchemy to set the column to NULL will
fail with a simple NOT NULL constraint exception.
- * The other, more special case way is to set the :paramref:`~.relationship.passive_deletes`
+ * The other, more special case way is to set the :paramref:`_orm.relationship.passive_deletes`
flag to the string ``"all"``. This has the effect of entirely
disabling SQLAlchemy's behavior of setting the foreign key column
to NULL, and a DELETE will be emitted for the parent row without
* SQLAlchemy doesn't **need** to be this sophisticated, as we instead provide
smooth integration with the database's own ``ON DELETE`` functionality,
- by using the :paramref:`~.relationship.passive_deletes` option in conjunction
+ by using the :paramref:`_orm.relationship.passive_deletes` option in conjunction
with properly configured foreign key constraints. Under this behavior,
SQLAlchemy only emits DELETE for those rows that are already locally
present in the :class:`.Session`; for any collections that are unloaded,
this can easily result in constraint violations if there are other objects
referring to this "one" side from the "many", so it typically is only
useful when a relationship is in fact a "one to one". The
- :paramref:`~.relationship.single_parent` flag should be used to establish
+ :paramref:`_orm.relationship.single_parent` flag should be used to establish
an in-Python assertion for this case.
-When using a :func:`.relationship` that also includes a many-to-many
-table using the :paramref:`~.relationship.secondary` option, SQLAlchemy's
+When using a :func:`_orm.relationship` that also includes a many-to-many
+table using the :paramref:`_orm.relationship.secondary` option, SQLAlchemy's
delete cascade handles the rows in this many-to-many table automatically.
Just like, as described in :ref:`relationships_many_to_many_deletion`,
the addition or removal of an object from a many-to-many collection
on a one-to-many relationship. Setting it on a many-to-one or
many-to-many relationship is more awkward; for this use case,
SQLAlchemy requires that the :func:`~sqlalchemy.orm.relationship`
-be configured with the :paramref:`~.relationship.single_parent` argument,
+be configured with the :paramref:`_orm.relationship.single_parent` argument,
establishes Python-side validation that ensures the object
is associated with only one parent at a time.
>>> i1 in session
True
-This behavior can be disabled using the :paramref:`~.relationship.cascade_backrefs` flag::
+This behavior can be disabled using the :paramref:`_orm.relationship.cascade_backrefs` flag::
mapper(Order, order_table, properties={
'items' : relationship(Item, backref='order',
Collection Configuration and Techniques
=======================================
-The :func:`.relationship` function defines a linkage between two classes.
+The :func:`_orm.relationship` function defines a linkage between two classes.
When the linkage defines a one-to-many or many-to-many relationship, it's
represented as a Python collection when objects are loaded and manipulated.
This section presents additional information about collection configuration
Working with Large Collections
==============================
-The default behavior of :func:`.relationship` is to fully load
+The default behavior of :func:`_orm.relationship` is to fully load
the collection of items in, as according to the loading strategy of the
relationship. Additionally, the :class:`.Session` by default only knows how to delete
objects which are actually present within the session. When a parent instance
automatically each time the collection is about to emit a
query.
-To place a dynamic relationship on a backref, use the :func:`~.orm.backref`
+To place a dynamic relationship on a backref, use the :func:`_orm.backref`
function in conjunction with ``lazy='dynamic'``::
class Post(Base):
.. note::
- The :func:`~.orm.dynamic_loader` function is essentially the same
- as :func:`~.orm.relationship` with the ``lazy='dynamic'`` argument specified.
+ The :func:`_orm.dynamic_loader` function is essentially the same
+ as :func:`_orm.relationship` with the ``lazy='dynamic'`` argument specified.
.. warning::
time they are added. However when instances of ``MyClass`` are freshly loaded
from the database, the ``children`` collection stays empty. The noload
strategy is also available on a query option basis using the
-:func:`.orm.noload` loader option.
+:func:`_orm.noload` loader option.
Alternatively, a "raise"-loaded relationship will raise an
:exc:`~sqlalchemy.exc.InvalidRequestError` where the attribute would normally
Rather than having to read through SQL logs to determine that all necessary
attributes were eager loaded, the "raise" strategy will cause unloaded
attributes to raise immediately if accessed. The raise strategy is
-also available on a query option basis using the :func:`.orm.raiseload`
+also available on a query option basis using the :func:`_orm.raiseload`
loader option.
.. versionadded:: 1.1 added the "raise" loader strategy.
Using Passive Deletes
---------------------
-Use :paramref:`~.relationship.passive_deletes` to disable child object loading on a DELETE
+Use :paramref:`_orm.relationship.passive_deletes` to disable child object loading on a DELETE
operation, in conjunction with "ON DELETE (CASCADE|SET NULL)" on your database
to automatically cascade deletes to child objects::
* When using SQLite, foreign key support must be enabled explicitly.
See :ref:`sqlite_foreign_keys` for details.
-When :paramref:`~.relationship.passive_deletes` is applied, the ``children`` relationship will not be
+When :paramref:`_orm.relationship.passive_deletes` is applied, the ``children`` relationship will not be
loaded into memory when an instance of ``MyClass`` is marked for deletion. The
``cascade="all, delete-orphan"`` *will* take effect for instances of
``MyOtherClass`` which are currently present in the session; however for
Collections are not limited to lists. Sets, mutable sequences and almost any
other Python object that can act as a container can be used in place of the
-default list, by specifying the :paramref:`~.relationship.collection_class` option on
+default list, by specifying the :paramref:`_orm.relationship.collection_class` option on
:func:`~sqlalchemy.orm.relationship`::
class Parent(Base):
{('a', 'atext'): <__main__.Note object at 0x2eaaf0>}
Other built-in dictionary types include :func:`.column_mapped_collection`,
-which is almost like :func:`.attribute_mapped_collection` except given the :class:`.Column`
+which is almost like :func:`.attribute_mapped_collection` except given the :class:`_schema.Column`
object directly::
from sqlalchemy.orm.collections import column_mapped_collection
step beyond and represents the data internally in some fashion, presenting
a "view" of that data on the outside of a different form.
- For the first use case, the :func:`.orm.validates` decorator is by far
+ For the first use case, the :func:`_orm.validates` decorator is by far
the simplest way to intercept incoming values in all cases for the purposes
of validation and simple marshaling. See :ref:`simple_validators`
for an example of this.
the equality of two instances.
We will create a mapping to a table ``vertices``, which represents two points
-as ``x1/y1`` and ``x2/y2``. These are created normally as :class:`.Column`
+as ``x1/y1`` and ``x2/y2``. These are created normally as :class:`_schema.Column`
objects. Then, the :func:`.composite` function is used to assign new
attributes that will represent sets of columns via the ``Point`` class::
If you need to do some setup on database-loaded instances before they're ready
to use, there is an event hook known as :meth:`.InstanceEvents.load` which
can achieve this; it is also available via a class-specific decorator called
-:func:`.orm.reconstructor`. When using :func:`.orm.reconstructor`,
+:func:`_orm.reconstructor`. When using :func:`_orm.reconstructor`,
the mapper will invoke the decorated method with no
arguments every time it loads or reconstructs an instance of the
class. This is
loaded during a :class:`~sqlalchemy.orm.query.Query` operation as in
``query(MyMappedClass).one()``, ``init_on_load`` is called.
-Any method may be tagged as the :func:`.orm.reconstructor`, even
+Any method may be tagged as the :func:`_orm.reconstructor`, even
the ``__init__`` method itself. It is invoked after all immediate
column-level attributes are loaded as well as after eagerly-loaded scalar
relationships. Eagerly loaded collections may be only partially populated
next flush operation, so the activity within a reconstructor should be
conservative.
-:func:`.orm.reconstructor` is a shortcut into a larger system
+:func:`_orm.reconstructor` is a shortcut into a larger system
of "instance level" events, which can be subscribed to using the
event API - see :class:`.InstanceEvents` for the full API description
of these events.
---------------------------------
The :class:`.AssociationProxy` features simple SQL construction capabilities
-which relate down to the underlying :func:`.relationship` in use as well
+which relate down to the underlying :func:`_orm.relationship` in use as well
as the target attribute. For example, the :meth:`.RelationshipProperty.Comparator.any`
and :meth:`.RelationshipProperty.Comparator.has` operations are available, and will produce
a "nested" EXISTS clause, such as in our basic association object example::
AND keyword.id = userkeywords.keyword_id
AND keyword.keyword = :keyword_1)
-:class:`.AssociationProxy` can be used with :meth:`.Query.join` somewhat manually
+:class:`.AssociationProxy` can be used with :meth:`_query.Query.join` somewhat manually
using the :attr:`~.AssociationProxy.attr` attribute in a star-args context::
q = session.query(User).join(*User.keywords.attr)
By re-using a :class:`~.query.Query`, we save on the Python work within
the ``session.query(Model)`` constructor as well as calling upon
``filter(Model.id == bindparam('id'))``, which will skip for us the building
-up of the Core expression as well as sending it to :meth:`.Query.filter`.
-However, the approach still regenerates the full :class:`.Select`
-object every time when :meth:`.Query.all` is called and additionally this
-brand new :class:`.Select` is sent off to the string compilation step every
+up of the Core expression as well as sending it to :meth:`_query.Query.filter`.
+However, the approach still regenerates the full :class:`_expression.Select`
+object every time when :meth:`_query.Query.all` is called and additionally this
+brand new :class:`_expression.Select` is sent off to the string compilation step every
time, which for a simple case like the above is probably about 70% of the
overhead.
"my_key", and also includes the same feature as our custom "bake" function
that caches 100% of the Python invocation work from the
constructor of the query, to the filter call, to the production
-of the :class:`.Select` object, to the string compilation step.
+of the :class:`_expression.Select` object, to the string compilation step.
From the above, if we ask ourselves, "what if lookup needs to make conditional decisions
as to the structure of the query?", this is where hopefully it becomes apparent
Using Subqueries
^^^^^^^^^^^^^^^^
-When using :class:`.Query` objects, it is often needed that one :class:`.Query`
+When using :class:`_query.Query` objects, it is often needed that one :class:`_query.Query`
object is used to generate a subquery within another. In the case where the
-:class:`.Query` is currently in baked form, an interim method may be used to
-retrieve the :class:`.Query` object, using the :meth:`.BakedQuery.to_query`
-method. This method is passed the :class:`.Session` or :class:`.Query` that is
+:class:`_query.Query` is currently in baked form, an interim method may be used to
+retrieve the :class:`_query.Query` object, using the :meth:`.BakedQuery.to_query`
+method. This method is passed the :class:`.Session` or :class:`_query.Query` that is
the argument to the lambda callable used to generate a particular step
of the baked query::
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
As of SQLAlchemy 1.3.11, the use of the :meth:`.QueryEvents.before_compile`
-event against a particular :class:`.Query` will disallow the baked query
-system from caching the query, if the event hook returns a new :class:`.Query`
+event against a particular :class:`_query.Query` will disallow the baked query
+system from caching the query, if the event hook returns a new :class:`_query.Query`
object that is different from the one passed in. This is so that the
:meth:`.QueryEvents.before_compile` hook may be invoked against a particular
-:class:`.Query` every time it is used, to accommodate for hooks that
+:class:`_query.Query` every time it is used, to accommodate for hooks that
alter the query differently each time. To allow a
-:meth:`.QueryEvents.before_compile` to alter a :meth:`.Query` object, but
+:meth:`.QueryEvents.before_compile` to alter a :meth:`_query.Query` object, but
still to allow the result to be cached, the event can be registered
passing the ``bake_ok=True`` flag::
return query
The above strategy is appropriate for an event that will modify a
-given :class:`.Query` in exactly the same way every time, not dependent
+given :class:`_query.Query` in exactly the same way every time, not dependent
on specific parameters or external state that changes.
.. versionadded:: 1.3.11 - added the "bake_ok" flag to the
:meth:`.QueryEvents.before_compile` event and disallowed caching via
the "baked" extension from occurring for event handlers that
- return a new :class:`.Query` object if this flag is not set.
+ return a new :class:`_query.Query` object if this flag is not set.
Disabling Baked Queries Session-wide
------------------------
The baked query system is integrated into SQLAlchemy's lazy loader feature
-as used by :func:`.relationship`, and will cache queries for most lazy
+as used by :func:`_orm.relationship`, and will cache queries for most lazy
load conditions. A small subset of
"lazy loads" may not be cached; these involve query options in conjunction with ad-hoc
:obj:`.aliased` structures that cannot produce a repeatable cache
key.
.. versionchanged:: 1.2 "baked" queries are now the foundation of the
- lazy-loader feature of :func:`.relationship`.
+ lazy-loader feature of :func:`_orm.relationship`.
Opting out with the bake_queries flag
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-The :func:`.relationship` construct includes a flag
-:paramref:`.relationship.bake_queries` which when set to False will cause
+The :func:`_orm.relationship` construct includes a flag
+:paramref:`_orm.relationship.bake_queries` which when set to False will cause
that relationship to opt out of caching queries. Additionally, the
:paramref:`.Session.enable_baked_queries` setting can be used to disable
all "baked query" use. These flags can be useful to conserve memory,
""
One possible use of ``__abstract__`` is to use a distinct
-:class:`.MetaData` for different bases::
+:class:`_schema.MetaData` for different bases::
Base = declarative_base()
metadata = MetaData()
Above, classes which inherit from ``DefaultBase`` will use one
-:class:`.MetaData` as the registry of tables, and those which inherit from
+:class:`_schema.MetaData` as the registry of tables, and those which inherit from
``OtherBase`` will use a different one. The tables themselves can then be
created perhaps within distinct databases::
``__table_cls__``
~~~~~~~~~~~~~~~~~
-Allows the callable / class used to generate a :class:`.Table` to be customized.
+Allows the callable / class used to generate a :class:`_schema.Table` to be customized.
This is a very open-ended hook that can allow special customizations
-to a :class:`.Table` that one generates here::
+to a :class:`_schema.Table` that one generates here::
class MyMixin(object):
@classmethod
metadata, *arg, **kw
)
-The above mixin would cause all :class:`.Table` objects generated to include
+The above mixin would cause all :class:`_schema.Table` objects generated to include
the prefix ``"my_"``, followed by the name normally specified using the
``__tablename__`` attribute.
:ref:`mapper_config_toplevel`.
SQLAlchemy object-relational configuration involves the
-combination of :class:`.Table`, :func:`.mapper`, and class
+combination of :class:`_schema.Table`, :func:`.mapper`, and class
objects to define a mapped class.
:mod:`~sqlalchemy.ext.declarative` allows all three to be
expressed at once within the class declaration. As much as
Above, the :func:`declarative_base` callable returns a new base class from
which all mapped classes should inherit. When the class definition is
-completed, a new :class:`.Table` and :func:`.mapper` will have been generated.
+completed, a new :class:`_schema.Table` and :func:`.mapper` will have been generated.
The resulting table and mapper are accessible via
``__table__`` and ``__mapper__`` attributes on the
Defining Attributes
===================
-In the previous example, the :class:`.Column` objects are
+In the previous example, the :class:`_schema.Column` objects are
automatically named with the name of the attribute to which they are
assigned.
id = Column("some_table_id", Integer, primary_key=True)
Attributes may be added to the class after its construction, and they will be
-added to the underlying :class:`.Table` and
+added to the underlying :class:`_schema.Table` and
:func:`.mapper` definitions as appropriate::
SomeClass.data = Column('data', Unicode)
======================
The :func:`declarative_base` base class contains a
-:class:`.MetaData` object where newly defined
-:class:`.Table` objects are collected. This object is
+:class:`_schema.MetaData` object where newly defined
+:class:`_schema.Table` objects are collected. This object is
intended to be accessed directly for
-:class:`.MetaData`-specific operations. Such as, to issue
+:class:`_schema.MetaData`-specific operations. Such as, to issue
CREATE statements for all tables::
engine = create_engine('sqlite://')
Base.metadata.create_all(engine)
:func:`declarative_base` can also receive a pre-existing
-:class:`.MetaData` object, which allows a
+:class:`_schema.MetaData` object, which allows a
declarative setup to be associated with an already
existing traditional collection of :class:`~sqlalchemy.schema.Table`
objects::
Mapper Configuration
====================
-Declarative makes use of the :func:`~.orm.mapper` function internally
+Declarative makes use of the :func:`_orm.mapper` function internally
when it creates the mapping to the declared table. The options
-for :func:`~.orm.mapper` are passed directly through via the
+for :func:`_orm.mapper` are passed directly through via the
``__mapper_args__`` class attribute. As always, arguments which reference
locally mapped columns can reference them directly from within the
class declaration::
While the documentation typically refers to Declarative for most examples,
the following sections will provide detailed information on how the
-Declarative API interacts with the basic :func:`.mapper` and Core :class:`.Table`
+Declarative API interacts with the basic :func:`.mapper` and Core :class:`_schema.Table`
systems, as well as how sophisticated patterns can be built using systems
such as mixins.
In a situation like this, Declarative can't be sure
of the intent, especially if the ``start_date`` columns had, for example,
different types. A situation like this can be resolved by using
-:class:`.declared_attr` to define the :class:`.Column` conditionally, taking
+:class:`.declared_attr` to define the :class:`_schema.Column` conditionally, taking
care to return the **existing column** via the parent ``__table__`` if it
already exists::
Above, when ``Manager`` is mapped, the ``start_date`` column is
already present on the ``Person`` class. Declarative lets us return
-that :class:`.Column` as a result in this case, where it knows to skip
+that :class:`_schema.Column` as a result in this case, where it knows to skip
re-assigning the same column. If the mapping is mis-configured such
that the ``start_date`` column is accidentally re-assigned to a
different table (such as, if we changed ``Manager`` to be joined
inheritance without fixing ``start_date``), an error is raised which
-indicates an existing :class:`.Column` is trying to be re-assigned to
-a different owning :class:`.Table`.
+indicates an existing :class:`_schema.Column` is trying to be re-assigned to
+a different owning :class:`_schema.Table`.
The same concept can be used with mixin classes (see
:ref:`declarative_mixins`)::
Because we're using single table inheritance, we're sure that in this case,
``cls.__table__`` refers to ``Person.__table__``. If we were mixing joined-
and single-table inheritance, we might want our mixin to check more carefully
-if ``cls.__table__`` is really the :class:`.Table` we're looking for.
+if ``cls.__table__`` is really the :class:`_schema.Table` we're looking for.
.. _declarative_concrete_table:
Usage of an abstract base class is a little less straightforward as it
requires usage of :func:`~sqlalchemy.orm.util.polymorphic_union`,
-which needs to be created with the :class:`.Table` objects
+which needs to be created with the :class:`_schema.Table` objects
before the class is built::
engineers = Table('engineers', Base.metadata,
parent tables ``a`` and ``b`` respectively.
In the case of the mixin column, it seems that only one
-:class:`.Column` object is explicitly created, yet the ultimate
+:class:`_schema.Column` object is explicitly created, yet the ultimate
``created_at`` column above must exist as a distinct Python object
for each separate destination class. To accomplish this, the declarative
-extension creates a **copy** of each :class:`.Column` object encountered on
+extension creates a **copy** of each :class:`_schema.Column` object encountered on
a class that is detected as a mixin.
This copy mechanism is limited to simple columns that have no foreign
-keys, as a :class:`.ForeignKey` itself contains references to columns
+keys, as a :class:`_schema.ForeignKey` itself contains references to columns
which can't be properly recreated at this level. For columns that
have foreign keys, as well as for the variety of mapper-level constructs
that require destination-explicit context, the
Where above, the ``address_id`` class-level callable is executed at the
point at which the ``User`` class is constructed, and the declarative
-extension can use the resulting :class:`.Column` object as returned by
+extension can use the resulting :class:`_schema.Column` object as returned by
the method without the need to copy it.
Columns generated by :class:`~.declared_attr` can also be
primaryjoin, order_by etc. expressions should in all but the most
simplistic cases use **late bound** forms
for these arguments, meaning, using either the string form or a lambda.
-The reason for this is that the related :class:`.Column` objects which are to
+The reason for this is that the related :class:`_schema.Column` objects which are to
be configured using ``@declared_attr`` are not available to another
``@declared_attr`` attribute; while the methods will work and return new
-:class:`.Column` objects, those are not the :class:`.Column` objects that
+:class:`_schema.Column` objects, those are not the :class:`_schema.Column` objects that
Declarative will be using as it calls the methods on its own, thus using
-*different* :class:`.Column` objects.
+*different* :class:`_schema.Column` objects.
The canonical example is the primaryjoin condition that depends upon
another mixed-in column::
sqlalchemy.exc.InvalidRequestError: this ForeignKey's parent column is not
yet associated with a Table.
-This is because the ``target_id`` :class:`.Column` we've called upon in our
-``target()`` method is not the same :class:`.Column` that declarative is
+This is because the ``target_id`` :class:`_schema.Column` we've called upon in our
+``target()`` method is not the same :class:`_schema.Column` that declarative is
actually going to map to our table.
The condition above is resolved using a lambda::
string_table_name = 'type_b_strings'
id = Column(Integer(), primary_key=True)
-Above, the ``HasStringCollection`` mixin produces a :func:`.relationship`
+Above, the ``HasStringCollection`` mixin produces a :func:`_orm.relationship`
which refers to a newly generated class called ``StringAttribute``. The
-``StringAttribute`` class is generated with its own :class:`.Table`
+``StringAttribute`` class is generated with its own :class:`_schema.Table`
definition which is local to the parent class making usage of the
``HasStringCollection`` mixin. It also produces an :func:`.association_proxy`
object which proxies references to the ``strings`` attribute onto the ``value``
The strings accepted by the following parameters:
- :paramref:`.relationship.order_by`
+ :paramref:`_orm.relationship.order_by`
- :paramref:`.relationship.primaryjoin`
+ :paramref:`_orm.relationship.primaryjoin`
- :paramref:`.relationship.secondaryjoin`
+ :paramref:`_orm.relationship.secondaryjoin`
- :paramref:`.relationship.secondary`
+ :paramref:`_orm.relationship.secondary`
- :paramref:`.relationship.remote_side`
+ :paramref:`_orm.relationship.remote_side`
- :paramref:`.relationship.foreign_keys`
+ :paramref:`_orm.relationship.foreign_keys`
- :paramref:`.relationship._user_defined_foreign_keys`
+ :paramref:`_orm.relationship._user_defined_foreign_keys`
Are **evaluated as Python code expressions using eval(). DO NOT PASS
UNTRUSTED INPUT TO THESE ARGUMENTS.**
In addition, prior to version 1.3.16 of SQLAlchemy, the main
- "argument" to :func:`.relationship` is also evaluated as Python
+ "argument" to :func:`_orm.relationship` is also evaluated as Python
code. **DO NOT PASS UNTRUSTED INPUT TO THIS ARGUMENT.**
.. versionchanged:: 1.3.16
Many-to-many relationships are also declared in the same way
with declarative as with traditional mappings. The
``secondary`` argument to
-:func:`.relationship` is as usual passed a
-:class:`.Table` object, which is typically declared in the
-traditional way. The :class:`.Table` usually shares
-the :class:`.MetaData` object used by the declarative base::
+:func:`_orm.relationship` is as usual passed a
+:class:`_schema.Table` object, which is typically declared in the
+traditional way. The :class:`_schema.Table` usually shares
+the :class:`_schema.MetaData` object used by the declarative base::
keywords = Table(
'keywords', Base.metadata,
keywords = relationship("Keyword", secondary="keywords")
As with traditional mapping, its generally not a good idea to use
-a :class:`.Table` as the "secondary" argument which is also mapped to
-a class, unless the :func:`.relationship` is declared with ``viewonly=True``.
+a :class:`_schema.Table` as the "secondary" argument which is also mapped to
+a class, unless the :func:`_orm.relationship` is declared with ``viewonly=True``.
Otherwise, the unit-of-work system may attempt duplicate INSERT and
DELETE statements against the underlying table.
.. seealso::
This section describes specifics about how the Declarative system
- defines :class:`.Table` objects that are to be mapped with the
- SQLAlchemy ORM. For general information on :class:`.Table` objects
+ defines :class:`_schema.Table` objects that are to be mapped with the
+ SQLAlchemy ORM. For general information on :class:`_schema.Table` objects
see :ref:`metadata_describing_toplevel`.
Table arguments other than the name, metadata, and mapped Column
Some configuration schemes may find it more appropriate to use ``__table__``,
such as those which already take advantage of the data-driven nature of
-:class:`.Table` to customize and/or automate schema definition.
+:class:`_schema.Table` to customize and/or automate schema definition.
Note that when the ``__table__`` approach is used, the object is immediately
-usable as a plain :class:`.Table` within the class declaration body itself,
+usable as a plain :class:`_schema.Table` within the class declaration body itself,
as a Python class is only another syntactical block. Below this is illustrated
by using the ``id`` column in the ``primaryjoin`` condition of a
-:func:`.relationship`::
+:func:`_orm.relationship`::
class MyClass(Base):
__table__ = Table('my_table', Base.metadata,
Using Reflection with Declarative
=================================
-It's easy to set up a :class:`.Table` that uses ``autoload=True``
+It's easy to set up a :class:`_schema.Table` that uses ``autoload=True``
in conjunction with a mapped class::
class MyClass(Base):
autoload=True, autoload_with=some_engine)
However, one improvement that can be made here is to not
-require the :class:`.Engine` to be available when classes are
+require the :class:`_engine.Engine` to be available when classes are
being first declared. To achieve this, use the
:class:`.DeferredReflection` mixin, which sets up mappings
only after a special ``prepare(engine)`` step is called::
differentiated from each other.
Even though subclasses share the base table for all of their attributes,
-when using Declarative, :class:`.Column` objects may still be specified on
+when using Declarative, :class:`_schema.Column` objects may still be specified on
subclasses, indicating that the column is to be mapped only to that subclass;
-the :class:`.Column` will be applied to the same base :class:`.Table` object::
+the :class:`_schema.Column` will be applied to the same base :class:`_schema.Table` object::
class Employee(Base):
__tablename__ = 'employee'
As discussed in :ref:`inheritance_loading_toplevel`, mapper inheritance
configurations of any type can be configured to load from a special selectable
by default using the :paramref:`.mapper.with_polymorphic` argument. Current
-public API requires that this argument is set on a :class:`.Mapper` when
+public API requires that this argument is set on a :class:`_orm.Mapper` when
it is first constructed.
-However, in the case of Declarative, both the mapper and the :class:`.Table`
+However, in the case of Declarative, both the mapper and the :class:`_schema.Table`
that is mapped are created at once, the moment the mapped class is defined.
This means that the :paramref:`.mapper.with_polymorphic` argument cannot
-be provided yet, since the :class:`.Table` objects that correspond to the
+be provided yet, since the :class:`_schema.Table` objects that correspond to the
subclasses haven't yet been defined.
There are a few strategies available to resolve this cycle, however
.. topic:: Mappers can always SELECT
In SQLAlchemy, a mapper for a class always has to refer to some
- "selectable", which is normally a :class:`.Table` but may also refer to any
- :func:`~.sql.expression.select` object as well. While it may appear that a "single table
+ "selectable", which is normally a :class:`_schema.Table` but may also refer to any
+ :func:`_expression.select` object as well. While it may appear that a "single table
inheritance" mapper does not map to a table, these mappers in fact
implicitly refer to the table that is mapped by a superclass.
The Declarative configurations illustrated with :class:`.ConcreteBase`
and :class:`.AbstractConcreteBase` are equivalent to two other forms
of configuration that make use of :func:`.polymorphic_union` explicitly.
-These configurational forms make use of the :class:`.Table` object explicitly
+These configurational forms make use of the :class:`_schema.Table` object explicitly
so that the "polymorphic union" can be created first, then applied
to the mappings. These are illustrated here to clarify the role
of the :func:`.polymorphic_union` function in terms of mapping.
A **semi-classical mapping** for example makes use of Declarative, but
-establishes the :class:`.Table` objects separately::
+establishes the :class:`_schema.Table` objects separately::
metadata = Base.metadata
'engineer': engineers_table
}, 'type', 'pjoin')
-With the above :class:`.Table` objects, the mappings can be produced using "semi-classical" style,
+With the above :class:`_schema.Table` objects, the mappings can be produced using "semi-classical" style,
where we use Declarative in conjunction with the ``__table__`` argument;
our polymorphic union above is passed via ``__mapper_args__`` to
the :paramref:`.mapper.with_polymorphic` parameter::
'polymorphic_identity': 'manager',
'concrete': True}
-Alternatively, the same :class:`.Table` objects can be used in
+Alternatively, the same :class:`_schema.Table` objects can be used in
fully "classical" style, without using Declarative at all.
A constructor similar to that supplied by Declarative is illustrated::
The next complexity with concrete inheritance and relationships involves
when we'd like one or all of ``Employee``, ``Manager`` and ``Engineer`` to
themselves refer back to ``Company``. For this case, SQLAlchemy has
-special behavior in that a :func:`.relationship` placed on ``Employee``
+special behavior in that a :func:`_orm.relationship` placed on ``Employee``
which links to ``Company`` **does not work**
against the ``Manager`` and ``Engineer`` classes, when exercised at the
instance level. Instead, a distinct
-:func:`.relationship` must be applied to each class. In order to achieve
+:func:`_orm.relationship` must be applied to each class. In order to achieve
bi-directional behavior in terms of three separate relationships which
serve as the opposite of ``Company.employees``, the
-:paramref:`.relationship.back_populates` parameter is used between
+:paramref:`_orm.relationship.back_populates` parameter is used between
each of the relationships::
from sqlalchemy.ext.declarative import ConcreteBase
The options for loading with concrete inheritance are limited; generally,
if polymorphic loading is configured on the mapper using one of the
declarative concrete mixins, it can't be modified at query time
-in current SQLAlchemy versions. Normally, the :func:`.orm.with_polymorphic`
+in current SQLAlchemy versions. Normally, the :func:`_orm.with_polymorphic`
function would be able to override the style of loading used by concrete,
however due to current limitations this is not yet supported.
something to filter on, and it also will be loaded when we get our objects
back. If it's not queried up front, it gets loaded later when we first need
to access it. Basic control of this behavior is provided using the
-:func:`.orm.with_polymorphic` function, as well as two variants, the mapper
+:func:`_orm.with_polymorphic` function, as well as two variants, the mapper
configuration :paramref:`.mapper.with_polymorphic` in conjunction with
-the :paramref:`.mapper.polymorphic_load` option, and the :class:`.Query`
--level :meth:`.Query.with_polymorphic` method. The "with_polymorphic" family
+the :paramref:`.mapper.polymorphic_load` option, and the :class:`_query.Query`
+-level :meth:`_query.Query.with_polymorphic` method. The "with_polymorphic" family
each provide a means of specifying which specific subclasses of a particular
base class should be included within a query, which implies what columns and
tables will be available in the SELECT.
For the following sections, assume the ``Employee`` / ``Engineer`` / ``Manager``
examples introduced in :ref:`inheritance_toplevel`.
-Normally, when a :class:`.Query` specifies the base class of an
+Normally, when a :class:`_query.Query` specifies the base class of an
inheritance hierarchy, only the columns that are local to that base
class are queried::
(note that for single-table inheritance, this is common if Declarative is used,
but not for a classical mapping).
-To solve both of these issues, the :func:`.orm.with_polymorphic` function
+To solve both of these issues, the :func:`_orm.with_polymorphic` function
provides a special :class:`.AliasedClass` that represents a range of
-columns across subclasses. This object can be used in a :class:`.Query`
+columns across subclasses. This object can be used in a :class:`_query.Query`
like any other alias. When queried, it represents all the columns present in
the classes given::
Where above, the additional tables / columns for "engineer" and "manager" are
included. Similar behavior occurs in the case of single table inheritance.
-:func:`.orm.with_polymorphic` accepts a single class or
+:func:`_orm.with_polymorphic` accepts a single class or
mapper, a list of classes/mappers, or the string ``'*'`` to indicate all
subclasses:
Using aliasing with with_polymorphic
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The :func:`.orm.with_polymorphic` function also provides "aliasing" of the
-polymorphic selectable itself, meaning, two different :func:`.orm.with_polymorphic`
+The :func:`_orm.with_polymorphic` function also provides "aliasing" of the
+polymorphic selectable itself, meaning, two different :func:`_orm.with_polymorphic`
entities, referring to the same class hierarchy, can be used together. This
is available using the :paramref:`.orm.with_polymorphic.aliased` flag.
For a polymorphic selectable that is across multiple tables, the default behavior
The creation of subqueries above is very verbose. While it creates the best
encapsulation of the two distinct queries, it may be inefficient.
-:func:`.orm.with_polymorphic` includes an additional flag to help with this
+:func:`_orm.with_polymorphic` includes an additional flag to help with this
situation, :paramref:`.orm.with_polymorphic.flat`, which will "flatten" the
subquery / join combination into straight joins, applying aliasing to the
individual tables instead. Setting :paramref:`.orm.with_polymorphic.flat`
Referring to Specific Subclass Attributes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The entity returned by :func:`.orm.with_polymorphic` is an :class:`.AliasedClass`
-object, which can be used in a :class:`.Query` like any other alias, including
+The entity returned by :func:`_orm.with_polymorphic` is an :class:`.AliasedClass`
+object, which can be used in a :class:`_query.Query` like any other alias, including
named attributes for those attributes on the ``Employee`` class. In our
previous example, ``eng_plus_manager`` becomes the entity that we use to refer to the
three-way outer join above. It also includes namespaces for each class named
Setting with_polymorphic at mapper configuration time
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The :func:`.orm.with_polymorphic` function serves the purpose of allowing
+The :func:`_orm.with_polymorphic` function serves the purpose of allowing
"eager" loading of attributes from subclass tables, as well as the ability
to refer to the attributes from subclass tables at query time. Historically,
the "eager loading" of columns has been the more important part of the
asterisk is often a good idea as the load is still against a single table only,
but an additional lazy load of subclass-mapped columns will be prevented.
-Using :func:`.orm.with_polymorphic` or :meth:`.Query.with_polymorphic`
+Using :func:`_orm.with_polymorphic` or :meth:`_query.Query.with_polymorphic`
will override the mapper-level :paramref:`.mapper.with_polymorphic` setting.
The :paramref:`.mapper.with_polymorphic` option also accepts a list of
-classes just like :func:`.orm.with_polymorphic` to polymorphically load among
+classes just like :func:`_orm.with_polymorphic` to polymorphically load among
a subset of classes. However, when using Declarative, providing classes
to this list is not directly possible as the subclasses we'd like to add
are not available yet. Instead, we can specify on each subclass
Setting with_polymorphic against a query
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The :func:`.orm.with_polymorphic` function evolved from a query-level
-method :meth:`.Query.with_polymorphic`. This method has the same purpose
-as :func:`.orm.with_polymorphic`, except is not as
+The :func:`_orm.with_polymorphic` function evolved from a query-level
+method :meth:`_query.Query.with_polymorphic`. This method has the same purpose
+as :func:`_orm.with_polymorphic`, except is not as
flexible in its usage patterns in that it only applies to the first entity
-of the :class:`.Query`. It then takes effect for all occurrences of
+of the :class:`_query.Query`. It then takes effect for all occurrences of
that entity, so that the entity (and its subclasses) can be referred to
directly, rather than using an alias object. For simple cases it might be
considered to be more succinct::
)
)
-The :meth:`.Query.with_polymorphic` method has a more complicated job
-than the :func:`.orm.with_polymorphic` function, as it needs to correctly
+The :meth:`_query.Query.with_polymorphic` method has a more complicated job
+than the :func:`_orm.with_polymorphic` function, as it needs to correctly
transform entities like ``Engineer`` and ``Manager`` appropriately, but
not interfere with other entities. If its flexibility is lacking, switch
-to using :func:`.orm.with_polymorphic`.
+to using :func:`_orm.with_polymorphic`.
.. _polymorphic_selectin:
Polymorphic Selectin Loading
----------------------------
-An alternative to using the :func:`.orm.with_polymorphic` family of
+An alternative to using the :func:`_orm.with_polymorphic` family of
functions to "eagerly" load the additional subclasses on an inheritance
mapping, primarily when using joined table inheritance, is to use polymorphic
"selectin" loading. This is an eager loading
feature which works similarly to the :ref:`selectin_eager_loading` feature
of relationship loading. Given our example mapping, we can instruct
a load of ``Employee`` to emit an extra SELECT per subclass by using
-the :func:`.orm.selectin_polymorphic` loader option::
+the :func:`_orm.selectin_polymorphic` loader option::
from sqlalchemy.orm import selectin_polymorphic
}
-Unlike when using :func:`.orm.with_polymorphic`, when using the
-:func:`.orm.selectin_polymorphic` style of loading, we do **not** have the
+Unlike when using :func:`_orm.with_polymorphic`, when using the
+:func:`_orm.selectin_polymorphic` style of loading, we do **not** have the
ability to refer to the ``Engineer`` or ``Manager`` entities within our main
query as filter, order by, or other criteria, as these entities are not present
in the initial query that is used to locate results. However, we can apply
effect when the secondary SELECT is emitted. Below we assume ``Manager`` has
an additional relationship ``Manager.paperwork``, that we'd like to eagerly
load as well. We can use any type of eager loading, such as joined eager
-loading via the :func:`.joinedload` function::
+loading via the :func:`_orm.joinedload` function::
from sqlalchemy.orm import joinedload
from sqlalchemy.orm import selectin_polymorphic
(1,)
Combining "selectin" polymorhic loading with query-time
-:func:`.orm.with_polymorphic` usage is also possible (though this is very
+:func:`_orm.with_polymorphic` usage is also possible (though this is very
outer-space stuff!); assuming the above mappings had no ``polymorphic_load``
set up, we could get the same result as follows::
Referring to specific subtypes on relationships
-----------------------------------------------
-Mapped attributes which correspond to a :func:`.relationship` are used
+Mapped attributes which correspond to a :func:`_orm.relationship` are used
in querying in order to refer to the linkage between two mappings. Common
-uses for this are to refer to a :func:`.relationship` in :meth:`.Query.join`
-as well as in loader options like :func:`.joinedload`. When using
-:func:`.relationship` where the target class is an inheritance hierarchy,
+uses for this are to refer to a :func:`_orm.relationship` in :meth:`_query.Query.join`
+as well as in loader options like :func:`_orm.joinedload`. When using
+:func:`_orm.relationship` where the target class is an inheritance hierarchy,
the API allows that the join, eager load, or other linkage should target a specific
-subclass, alias, or :func:`.orm.with_polymorphic` alias, of that class hierarchy,
-rather than the class directly targeted by the :func:`.relationship`.
+subclass, alias, or :func:`_orm.with_polymorphic` alias, of that class hierarchy,
+rather than the class directly targeted by the :func:`_orm.relationship`.
The :func:`~sqlalchemy.orm.interfaces.PropComparator.of_type` method allows the
construction of joins along :func:`~sqlalchemy.orm.relationship` paths while
__mapper_args__ = {'polymorphic_identity':'manager'}
When querying from ``Company`` onto the ``Employee`` relationship, the
-:meth:`.Query.join` method as well as operators like :meth:`.PropComparator.any`
+:meth:`_query.Query.join` method as well as operators like :meth:`.PropComparator.any`
and :meth:`.PropComparator.has` will create
a join from ``company`` to ``employee``, without including ``engineer`` or
``manager`` in the mix. If we wish to have criterion which is specifically
Eager Loading of Specific or Polymorphic Subtypes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The :func:`.joinedload`, :func:`.subqueryload`, :func:`.contains_eager` and
+The :func:`_orm.joinedload`, :func:`.subqueryload`, :func:`.contains_eager` and
other eagerloader options support
paths which make use of :func:`~.PropComparator.of_type`.
Below, we load ``Company`` rows while eagerly loading related ``Engineer``
)
)
-As is the case with :meth:`.Query.join`, :meth:`~.PropComparator.of_type`
-can be used to combine eager loading and :func:`.orm.with_polymorphic`,
+As is the case with :meth:`_query.Query.join`, :meth:`~.PropComparator.of_type`
+can be used to combine eager loading and :func:`_orm.with_polymorphic`,
so that all sub-attributes of all referenced subtypes
can be loaded::
.. note::
When using :func:`.with_polymorphic` in conjunction with
- :func:`.joinedload`, the :func:`.with_polymorphic` object must be against
- an "aliased" object, that is an instance of :class:`.Alias`, so that the
+ :func:`_orm.joinedload`, the :func:`.with_polymorphic` object must be against
+ an "aliased" object, that is an instance of :class:`_expression.Alias`, so that the
polymorphic selectable is aliased (an informative error message is raised
otherwise).
:paramref:`.with_polymorphic.aliased` or :paramref:`.flat` flag, which will
apply this aliasing automatically. However, if the
:paramref:`.with_polymorphic.selectable` argument is being used to pass an
- object that is already an :class:`.Alias` object then this flag should
+ object that is already an :class:`_expression.Alias` object then this flag should
**not** be set. The "flat" option implies the "aliased" option and is an
alternate form of aliasing against join objects that produces fewer
subqueries.
that's the entity we would use for subsequent chaining, not the original class
or derived class. If we wanted to further eager load a collection on the
eager-loaded ``Engineer`` class, we access this class from the namespace of the
-:func:`.orm.with_polymorphic` object::
+:func:`_orm.with_polymorphic` object::
session.query(Company).\
options(
We will then get a collection of ``Engineer`` objects back, which will
contain all columns from ``employee`` and ``engineer`` loaded.
-However, when emitting a :class:`.Query` against a base class, the behavior
+However, when emitting a :class:`_query.Query` against a base class, the behavior
is to load only from the base table::
session.query(Employee).all()
WHERE ? = engineer.id
[2]
-The :func:`.orm.with_polymorphic`
+The :func:`_orm.with_polymorphic`
function and related configuration options allow us to instead emit a JOIN up
front which will conditionally load against ``employee``, ``engineer``, or
``manager``, very much like joined eager loading works for relationships,
ON employee.id = manager.id
[]
-The section :ref:`with_polymorphic` discusses the :func:`.orm.with_polymorphic`
+The section :ref:`with_polymorphic` discusses the :func:`_orm.with_polymorphic`
function and its configurational variants.
.. seealso::
Loading objects with single table inheritance
---------------------------------------------
-In modern Declarative, single inheritance mappings produce :class:`.Column`
+In modern Declarative, single inheritance mappings produce :class:`_schema.Column`
objects that are mapped only to a subclass, and not available from the
superclass, even though they are present on the same table.
In our example from :ref:`single_inheritance`, the ``Manager`` mapping for example had a
-:class:`.Column` specified::
+:class:`_schema.Column` specified::
class Manager(Employee):
manager_data = Column(String(50))
FROM employee
WHERE employee.id = ? AND employee.type IN (?)
-The :func:`.orm.with_polymorphic` function serves a similar role as joined
+The :func:`_orm.with_polymorphic` function serves a similar role as joined
inheritance in the case of single inheritance; it allows both for eager loading
of subclass attributes as well as specification of subclasses in a query,
just without the overhead of using OUTER JOIN::
The dictionary is generated when first accessed. Alternatively,
it can be specified as a constructor argument to the
- :func:`.column_property`, :func:`.relationship`, or :func:`.composite`
+ :func:`.column_property`, :func:`_orm.relationship`, or :func:`.composite`
functions.
.. versionchanged:: 1.0.0 :attr:`.InspectionAttr.info` moved
Configuring how Relationship Joins
----------------------------------
-:func:`.relationship` will normally create a join between two tables
+:func:`_orm.relationship` will normally create a join between two tables
by examining the foreign key relationship between the two tables
to determine which columns should be compared. There are a variety
of situations where this behavior needs to be customized.
counted as containing a foreign key reference to the parent table.
The above message is pretty long. There are many potential messages
-that :func:`.relationship` can return, which have been carefully tailored
+that :func:`_orm.relationship` can return, which have been carefully tailored
to detect a variety of common configurational issues; most will suggest
the additional configuration that's needed to resolve the ambiguity
or other missing information.
-In this case, the message wants us to qualify each :func:`.relationship`
+In this case, the message wants us to qualify each :func:`_orm.relationship`
by instructing for each one which foreign key column should be considered, and
the appropriate form is as follows::
billing_address = relationship("Address", foreign_keys=[billing_address_id])
shipping_address = relationship("Address", foreign_keys=[shipping_address_id])
-Above, we specify the ``foreign_keys`` argument, which is a :class:`.Column` or list
-of :class:`.Column` objects which indicate those columns to be considered "foreign",
+Above, we specify the ``foreign_keys`` argument, which is a :class:`_schema.Column` or list
+of :class:`_schema.Column` objects which indicate those columns to be considered "foreign",
or in other words, the columns that contain a value referring to a parent table.
Loading the ``Customer.billing_address`` relationship from a ``Customer``
object will use the value present in ``billing_address_id`` in order to
billing_address = relationship("Address", foreign_keys="[Customer.billing_address_id]")
In this specific example, the list is not necessary in any case as there's only
-one :class:`.Column` we need::
+one :class:`_schema.Column` we need::
billing_address = relationship("Address", foreign_keys="Customer.billing_address_id")
.. warning:: When passed as a Python-evaluable string, the
- :paramref:`.relationship.foreign_keys` argument is interpreted using Python's
+ :paramref:`_orm.relationship.foreign_keys` argument is interpreted using Python's
``eval()`` function. **DO NOT PASS UNTRUSTED INPUT TO THIS STRING**. See
:ref:`declarative_relationship_eval` for details on declarative
- evaluation of :func:`.relationship` arguments.
+ evaluation of :func:`_orm.relationship` arguments.
.. _relationship_primaryjoin:
Specifying Alternate Join Conditions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The default behavior of :func:`.relationship` when constructing a join
+The default behavior of :func:`_orm.relationship` when constructing a join
is that it equates the value of primary key columns
on one side to that of foreign-key-referring columns on the other.
We can change this criterion to be anything we'd like using the
-:paramref:`~.relationship.primaryjoin`
-argument, as well as the :paramref:`~.relationship.secondaryjoin`
+:paramref:`_orm.relationship.primaryjoin`
+argument, as well as the :paramref:`_orm.relationship.secondaryjoin`
argument in the case when a "secondary" table is used.
In the example below, using the ``User`` class
both the ``User.id`` and ``Address.user_id`` columns to each other, as well as
limiting rows in ``Address`` to just ``city='Boston'``. When using
Declarative, rudimentary SQL functions like :func:`.and_` are automatically
-available in the evaluated namespace of a string :func:`.relationship`
+available in the evaluated namespace of a string :func:`_orm.relationship`
argument.
.. warning:: When passed as a Python-evaluable string, the
- :paramref:`.relationship.primaryjoin` argument is interpreted using
+ :paramref:`_orm.relationship.primaryjoin` argument is interpreted using
Python's
``eval()`` function. **DO NOT PASS UNTRUSTED INPUT TO THIS STRING**. See
:ref:`declarative_relationship_eval` for details on declarative
- evaluation of :func:`.relationship` arguments.
+ evaluation of :func:`_orm.relationship` arguments.
-The custom criteria we use in a :paramref:`~.relationship.primaryjoin`
+The custom criteria we use in a :paramref:`_orm.relationship.primaryjoin`
is generally only significant when SQLAlchemy is rendering SQL in
order to load or represent this relationship. That is, it's used in
the SQL statement that's emitted in order to perform a per-attribute
lazy load, or when a join is constructed at query time, such as via
-:meth:`.Query.join`, or via the eager "joined" or "subquery" styles of
+:meth:`_query.Query.join`, or via the eager "joined" or "subquery" styles of
loading. When in-memory objects are being manipulated, we can place
any ``Address`` object we'd like into the ``boston_addresses``
collection, regardless of what the value of the ``.city`` attribute
Another element of the primary join condition is how those columns
considered "foreign" are determined. Usually, some subset
-of :class:`.Column` objects will specify :class:`.ForeignKey`, or otherwise
-be part of a :class:`.ForeignKeyConstraint` that's relevant to the join condition.
-:func:`.relationship` looks to this foreign key status as it decides
+of :class:`_schema.Column` objects will specify :class:`_schema.ForeignKey`, or otherwise
+be part of a :class:`_schema.ForeignKeyConstraint` that's relevant to the join condition.
+:func:`_orm.relationship` looks to this foreign key status as it decides
how it should load and persist data for this relationship. However, the
-:paramref:`~.relationship.primaryjoin` argument can be used to create a join condition that
-doesn't involve any "schema" level foreign keys. We can combine :paramref:`~.relationship.primaryjoin`
-along with :paramref:`~.relationship.foreign_keys` and :paramref:`~.relationship.remote_side` explicitly in order to
+:paramref:`_orm.relationship.primaryjoin` argument can be used to create a join condition that
+doesn't involve any "schema" level foreign keys. We can combine :paramref:`_orm.relationship.primaryjoin`
+along with :paramref:`_orm.relationship.foreign_keys` and :paramref:`_orm.relationship.remote_side` explicitly in order to
establish such a join.
Below, a class ``HostEntry`` joins to itself, equating the string ``content``
An alternative syntax to the above is to use the :func:`.foreign` and
:func:`.remote` :term:`annotations`,
-inline within the :paramref:`~.relationship.primaryjoin` expression.
-This syntax represents the annotations that :func:`.relationship` normally
-applies by itself to the join condition given the :paramref:`~.relationship.foreign_keys` and
-:paramref:`~.relationship.remote_side` arguments. These functions may
+inline within the :paramref:`_orm.relationship.primaryjoin` expression.
+This syntax represents the annotations that :func:`_orm.relationship` normally
+applies by itself to the join condition given the :paramref:`_orm.relationship.foreign_keys` and
+:paramref:`_orm.relationship.remote_side` arguments. These functions may
be more succinct when an explicit join condition is present, and additionally
serve to mark exactly the column that is "foreign" or "remote" independent
of whether that column is stated multiple times or within complex
Another use case for relationships is the use of custom operators, such
as PostgreSQL's "is contained within" ``<<`` operator when joining with
-types such as :class:`.postgresql.INET` and :class:`.postgresql.CIDR`.
+types such as :class:`_postgresql.INET` and :class:`_postgresql.CIDR`.
For custom operators we use the :meth:`.Operators.op` function::
inet_column.op("<<")(cidr_column)
-However, if we construct a :paramref:`~.relationship.primaryjoin` using this
-operator, :func:`.relationship` will still need more information. This is because
+However, if we construct a :paramref:`_orm.relationship.primaryjoin` using this
+operator, :func:`_orm.relationship` will still need more information. This is because
when it examines our primaryjoin condition, it specifically looks for operators
used for **comparisons**, and this is typically a fixed list containing known
comparison operators such as ``==``, ``<``, etc. So for our custom operator
FROM ip_address JOIN network ON ip_address.v4address << network.v4representation
.. versionadded:: 0.9.2 - Added the :paramref:`.Operators.op.is_comparison`
- flag to assist in the creation of :func:`.relationship` constructs using
+ flag to assist in the creation of :func:`_orm.relationship` constructs using
custom operators.
Custom operators based on SQL functions
Therefore, to get at all of #1, #2, and #3, we express the join condition
as well as which columns to be written by combining
-:paramref:`~.relationship.primaryjoin` fully, along with either the
-:paramref:`~.relationship.foreign_keys` argument, or more succinctly by
-annotating with :func:`~.orm.foreign`::
+:paramref:`_orm.relationship.primaryjoin` fully, along with either the
+:paramref:`_orm.relationship.foreign_keys` argument, or more succinctly by
+annotating with :func:`_orm.foreign`::
class Article(Base):
# ...
Self-Referential Many-to-Many Relationship
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Many to many relationships can be customized by one or both of :paramref:`~.relationship.primaryjoin`
-and :paramref:`~.relationship.secondaryjoin` - the latter is significant for a relationship that
-specifies a many-to-many reference using the :paramref:`~.relationship.secondary` argument.
-A common situation which involves the usage of :paramref:`~.relationship.primaryjoin` and :paramref:`~.relationship.secondaryjoin`
+Many to many relationships can be customized by one or both of :paramref:`_orm.relationship.primaryjoin`
+and :paramref:`_orm.relationship.secondaryjoin` - the latter is significant for a relationship that
+specifies a many-to-many reference using the :paramref:`_orm.relationship.secondary` argument.
+A common situation which involves the usage of :paramref:`_orm.relationship.primaryjoin` and :paramref:`_orm.relationship.secondaryjoin`
is when establishing a many-to-many relationship from a class to itself, as shown below::
from sqlalchemy import Integer, ForeignKey, String, Column, Table
)
Where above, SQLAlchemy can't know automatically which columns should connect
-to which for the ``right_nodes`` and ``left_nodes`` relationships. The :paramref:`~.relationship.primaryjoin`
-and :paramref:`~.relationship.secondaryjoin` arguments establish how we'd like to join to the association table.
+to which for the ``right_nodes`` and ``left_nodes`` relationships. The :paramref:`_orm.relationship.primaryjoin`
+and :paramref:`_orm.relationship.secondaryjoin` arguments establish how we'd like to join to the association table.
In the Declarative form above, as we are declaring these conditions within the Python
block that corresponds to the ``Node`` class, the ``id`` variable is available directly
-as the :class:`.Column` object we wish to join with.
+as the :class:`_schema.Column` object we wish to join with.
-Alternatively, we can define the :paramref:`~.relationship.primaryjoin`
-and :paramref:`~.relationship.secondaryjoin` arguments using strings, which is suitable
+Alternatively, we can define the :paramref:`_orm.relationship.primaryjoin`
+and :paramref:`_orm.relationship.secondaryjoin` arguments using strings, which is suitable
in the case that our configuration does not have either the ``Node.id`` column
object available yet or the ``node_to_node`` table perhaps isn't yet available.
-When referring to a plain :class:`.Table` object in a declarative string, we
-use the string name of the table as it is present in the :class:`.MetaData`::
+When referring to a plain :class:`_schema.Table` object in a declarative string, we
+use the string name of the table as it is present in the :class:`_schema.MetaData`::
class Node(Base):
__tablename__ = 'node'
)
.. warning:: When passed as a Python-evaluable string, the
- :paramref:`.relationship.primaryjoin` and
- :paramref:`.relationship.secondaryjoin` arguments are interpreted using
+ :paramref:`_orm.relationship.primaryjoin` and
+ :paramref:`_orm.relationship.secondaryjoin` arguments are interpreted using
Python's ``eval()`` function. **DO NOT PASS UNTRUSTED INPUT TO THESE
STRINGS**. See :ref:`declarative_relationship_eval` for details on
- declarative evaluation of :func:`.relationship` arguments.
+ declarative evaluation of :func:`_orm.relationship` arguments.
A classical mapping situation here is similar, where ``node_to_node`` can be joined
)})
-Note that in both examples, the :paramref:`~.relationship.backref`
+Note that in both examples, the :paramref:`_orm.relationship.backref`
keyword specifies a ``left_nodes`` backref - when
-:func:`.relationship` creates the second relationship in the reverse
+:func:`_orm.relationship` creates the second relationship in the reverse
direction, it's smart enough to reverse the
-:paramref:`~.relationship.primaryjoin` and
-:paramref:`~.relationship.secondaryjoin` arguments.
+:paramref:`_orm.relationship.primaryjoin` and
+:paramref:`_orm.relationship.secondaryjoin` arguments.
.. _composite_secondary_join:
in simpler ways whenever possible, by using reasonable relational
layouts and / or :ref:`in-Python attributes <mapper_hybrids>`.
-Sometimes, when one seeks to build a :func:`.relationship` between two tables
+Sometimes, when one seeks to build a :func:`_orm.relationship` between two tables
there is a need for more than just two or three tables to be involved in
-order to join them. This is an area of :func:`.relationship` where one seeks
+order to join them. This is an area of :func:`_orm.relationship` where one seeks
to push the boundaries of what's possible, and often the ultimate solution to
many of these exotic use cases needs to be hammered out on the SQLAlchemy mailing
list.
-In more recent versions of SQLAlchemy, the :paramref:`~.relationship.secondary`
+In more recent versions of SQLAlchemy, the :paramref:`_orm.relationship.secondary`
parameter can be used in some of these cases in order to provide a composite
target consisting of multiple tables. Below is an example of such a
join condition (requires version 0.9.2 at least to function as is)::
id = Column(Integer, primary_key=True)
-In the above example, we provide all three of :paramref:`~.relationship.secondary`,
-:paramref:`~.relationship.primaryjoin`, and :paramref:`~.relationship.secondaryjoin`,
+In the above example, we provide all three of :paramref:`_orm.relationship.secondary`,
+:paramref:`_orm.relationship.primaryjoin`, and :paramref:`_orm.relationship.secondaryjoin`,
in the declarative style referring to the named tables ``a``, ``b``, ``c``, ``d``
directly. A query from ``A`` to ``D`` looks like:
In the above example, we take advantage of being able to stuff multiple
tables into a "secondary" container, so that we can join across many
-tables while still keeping things "simple" for :func:`.relationship`, in that
+tables while still keeping things "simple" for :func:`_orm.relationship`, in that
there's just "one" table on both the "left" and the "right" side; the
complexity is kept within the middle.
.. versionadded:: 1.3
The :class:`.AliasedClass` construct can now be specified as the
- target of a :func:`.relationship`, replacing the previous approach
+ target of a :func:`_orm.relationship`, replacing the previous approach
of using non-primary mappers, which had limitations such that they did
not inherit sub-relationships of the mapped entity as well as that they
required complex configuration against an alternate selectable. The
recipes in this section are now updated to use :class:`.AliasedClass`.
In the previous section, we illustrated a technique where we used
-:paramref:`~.relationship.secondary` in order to place additional
+:paramref:`_orm.relationship.secondary` in order to place additional
tables within a join condition. There is one complex join case where
even this technique is not sufficient; when we seek to join from ``A``
to ``B``, making use of any number of ``C``, ``D``, etc. in between,
however there are also join conditions between ``A`` and ``B``
*directly*. In this case, the join from ``A`` to ``B`` may be
difficult to express with just a complex
-:paramref:`~.relationship.primaryjoin` condition, as the intermediary
+:paramref:`_orm.relationship.primaryjoin` condition, as the intermediary
tables may need special handling, and it is also not expressible with
-a :paramref:`~.relationship.secondary` object, since the
+a :paramref:`_orm.relationship.secondary` object, since the
``A->secondary->B`` pattern does not support any references between
``A`` and ``B`` directly. When this **extremely advanced** case
arises, we can resort to creating a second mapping as a target for the
mapping to a class that includes all the additional tables we need for
this join. In order to produce this mapper as an "alternative" mapping
for our class, we use the :func:`.aliased` function to produce the new
-construct, then use :func:`.relationship` against the object as though it
+construct, then use :func:`_orm.relationship` against the object as though it
were a plain mapped class.
-Below illustrates a :func:`.relationship` with a simple join from ``A`` to
+Below illustrates a :func:`_orm.relationship` with a simple join from ``A`` to
``B``, however the primaryjoin condition is augmented with two additional
entities ``C`` and ``D``, which also must have rows that line up with
the rows in both ``A`` and ``B`` simultaneously::
Very ambitious custom join conditions may fail to be directly persistable, and
in some cases may not even load correctly. To remove the persistence part of
-the equation, use the flag :paramref:`~.relationship.viewonly` on the
+the equation, use the flag :paramref:`_orm.relationship.viewonly` on the
:func:`~sqlalchemy.orm.relationship`, which establishes it as a read-only
attribute (data written to the collection will be ignored on flush()).
However, in extreme cases, consider using a regular Python property in
-conjunction with :class:`.Query` as follows:
+conjunction with :class:`_query.Query` as follows:
.. sourcecode:: python
Deferred column loading allows particular columns of a table be loaded only
upon direct access, instead of when the entity is queried using
-:class:`.Query`. This feature is useful when one wants to avoid
+:class:`_query.Query`. This feature is useful when one wants to avoid
loading a large text or binary field into memory when it's not needed.
Individual columns can be lazy loaded by themselves or placed into groups that
-lazy-load together, using the :func:`.orm.deferred` function to
+lazy-load together, using the :func:`_orm.deferred` function to
mark them as "deferred". In the example below, we define a mapping that will load each of
``.excerpt`` and ``.photo`` in separate, individual-row SELECT statements when each
attribute is first referenced on the individual object instance::
excerpt = deferred(Column(Text))
photo = deferred(Column(Binary))
-Classical mappings as always place the usage of :func:`.orm.deferred` in the
-``properties`` dictionary against the table-bound :class:`.Column`::
+Classical mappings as always place the usage of :func:`_orm.deferred` in the
+``properties`` dictionary against the table-bound :class:`_schema.Column`::
mapper(Book, book_table, properties={
'photo':deferred(book_table.c.photo)
------------------------------------
Columns can be marked as "deferred" or reset to "undeferred" at query time
-using options which are passed to the :meth:`.Query.options` method; the most
-basic query options are :func:`.orm.defer` and
-:func:`.orm.undefer`::
+using options which are passed to the :meth:`_query.Query.options` method; the most
+basic query options are :func:`_orm.defer` and
+:func:`_orm.undefer`::
from sqlalchemy.orm import defer
from sqlalchemy.orm import undefer
Above, the "summary" column will not load until accessed, and the "excerpt"
column will load immediately even if it was mapped as a "deferred" column.
-:func:`.orm.deferred` attributes which are marked with a "group" can be undeferred
-using :func:`.orm.undefer_group`, sending in the group name::
+:func:`_orm.deferred` attributes which are marked with a "group" can be undeferred
+using :func:`_orm.undefer_group`, sending in the group name::
from sqlalchemy.orm import undefer_group
Deferred Loading across Multiple Entities
-----------------------------------------
-To specify column deferral for a :class:`.Query` that loads multiple types of
+To specify column deferral for a :class:`_query.Query` that loads multiple types of
entities at once, the deferral options may be specified more explicitly using
class-bound attributes, rather than string names::
that path. Such as, to load ``Author`` instances, then joined-eager-load the
``Author.books`` collection for each author, then apply deferral options to
column-oriented attributes onto each ``Book`` entity from that relationship,
-the :func:`.joinedload` loader option can be combined with the :func:`.load_only`
+the :func:`_orm.joinedload` loader option can be combined with the :func:`.load_only`
option (described later in this section) to defer all ``Book`` columns except
those explicitly specified::
)
Option structures as above can also be organized in more complex ways, such
-as hierarchically using the :meth:`.Load.options`
+as hierarchically using the :meth:`_orm.Load.options`
method, which allows multiple sub-options to be chained to a common parent
option at once. Any mixture of string names and class-bound attribute objects
may be used::
)
)
-.. versionadded:: 1.3.6 Added :meth:`.Load.options` to allow easier
+.. versionadded:: 1.3.6 Added :meth:`_orm.Load.options` to allow easier
construction of hierarchies of loader options.
-Another way to apply options to a path is to use the :func:`.orm.defaultload`
+Another way to apply options to a path is to use the :func:`_orm.defaultload`
function. This function is used to indicate a particular path within a loader
option structure without actually setting any options at that level, so that further
-sub-options may be applied. The :func:`.orm.defaultload` function can be used
-to create the same structure as we did above using :meth:`.Load.options` as::
+sub-options may be applied. The :func:`_orm.defaultload` function can be used
+to create the same structure as we did above using :meth:`_orm.Load.options` as::
query = session.query(Author)
query = query.options(
are always used by the ORM.
A similar function is available with less verbosity by using the
-:func:`.orm.load_only` option. This is a so-called **exclusionary** option
+:func:`_orm.load_only` option. This is a so-called **exclusionary** option
which will apply deferred behavior to all column attributes except those
that are named::
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Wildcard options and exclusionary options such as :func:`.load_only` may
-only be applied to a single entity at a time within a :class:`.Query`. To
-suit the less common case where a :class:`.Query` is returning multiple
+only be applied to a single entity at a time within a :class:`_query.Query`. To
+suit the less common case where a :class:`_query.Query` is returning multiple
primary entities at once, a special calling style may be required in order
to apply a wildcard or exclusionary option, which is to use the
-:class:`.Load` object to indicate the starting entity for a deferral option.
-Such as, if we were loading ``Book`` and ``Author`` at once, the :class:`.Query`
+:class:`_orm.Load` object to indicate the starting entity for a deferral option.
+Such as, if we were loading ``Book`` and ``Author`` at once, the :class:`_query.Query`
will raise an informative error if we try to apply :func:`.load_only` to
-both at once. Using :class:`.Load` looks like::
+both at once. Using :class:`_orm.Load` looks like::
from sqlalchemy.orm import Load
Load(Book).load_only("summary", "excerpt")
)
-Above, :class:`.Load` is used in conjunction with the exclusionary option
+Above, :class:`_orm.Load` is used in conjunction with the exclusionary option
:func:`.load_only` so that the deferral of all other columns only takes
place for the ``Book`` class and not the ``Author`` class. Again,
-the :class:`.Query` object should raise an informative error message when
+the :class:`_query.Query` object should raise an informative error message when
the above calling style is actually required that describes those cases
-where explicit use of :class:`.Load` is needed.
+where explicit use of :class:`_orm.Load` is needed.
.. _deferred_raiseload:
The bundle can be subclassed to provide custom behaviors when results
are fetched. The method :meth:`.Bundle.create_row_processor` is given
-the :class:`.Query` and a set of "row processor" functions at query execution
+the :class:`_query.Query` and a set of "row processor" functions at query execution
time; these processor functions when given a result row will return the
individual attribute value, which can then be adapted into any kind of
return data structure. Below illustrates replacing the usual :class:`.Row`
A big part of SQLAlchemy is providing a wide range of control over how related
objects get loaded when querying. By "related objects" we refer to collections
-or scalar associations configured on a mapper using :func:`.relationship`.
+or scalar associations configured on a mapper using :func:`_orm.relationship`.
This behavior can be configured at mapper construction time using the
-:paramref:`.relationship.lazy` parameter to the :func:`.relationship`
-function, as well as by using options with the :class:`.Query` object.
+:paramref:`_orm.relationship.lazy` parameter to the :func:`_orm.relationship`
+function, as well as by using options with the :class:`_query.Query` object.
The loading of relationships falls into three categories; **lazy** loading,
**eager** loading, and **no** loading. Lazy loading refers to objects are returned
is emitted such that the requested collection is loaded.
Eager loading refers to objects returned from a query with the related
-collection or scalar reference already loaded up front. The :class:`.Query`
+collection or scalar reference already loaded up front. The :class:`_query.Query`
achieves this either by augmenting the SELECT statement it would normally
emit with a JOIN to load in related rows simultaneously, or by emitting
additional SELECT statements after the primary one to load collections
attribute access time to lazily load a related reference on a single
object at a time. Lazy loading is detailed at :ref:`lazy_loading`.
-* **joined loading** - available via ``lazy='joined'`` or the :func:`.joinedload`
+* **joined loading** - available via ``lazy='joined'`` or the :func:`_orm.joinedload`
option, this form of loading applies a JOIN to the given SELECT statement
so that related rows are loaded in the same result set. Joined eager loading
is detailed at :ref:`joined_eager_loading`.
The loader strategy for a particular relationship can be configured
at mapping time to take place in all cases where an object of the mapped
type is loaded, in the absence of any query-level options that modify it.
-This is configured using the :paramref:`.relationship.lazy` parameter to
-:func:`.relationship`; common values for this parameter
+This is configured using the :paramref:`_orm.relationship.lazy` parameter to
+:func:`_orm.relationship`; common values for this parameter
include ``select``, ``joined``, ``subquery`` and ``selectin``.
For example, to configure a relationship to use joined eager loading when
rows fetched by adding a JOIN to the query for ``Parent`` objects.
See :ref:`joined_eager_loading` for background on this style of loading.
-The default value of the :paramref:`.relationship.lazy` argument is
+The default value of the :paramref:`_orm.relationship.lazy` argument is
``"select"``, which indicates lazy loading. See :ref:`lazy_loading` for
further background.
The other, and possibly more common way to configure loading strategies
is to set them up on a per-query basis against specific attributes using the
-:meth:`.Query.options` method. Very detailed
+:meth:`_query.Query.options` method. Very detailed
control over relationship loading is available using loader options;
the most common are
:func:`~sqlalchemy.orm.joinedload`,
joinedload(B.btoc)).all()
A similar approach can be used to specify multiple sub-options at once, using
-the :meth:`.Load.options` method::
+the :meth:`_orm.Load.options` method::
session.query(A).options(
defaultload(A.atob).options(
joinedload(B.btod)
)).all()
-.. versionadded:: 1.3.6 added :meth:`.Load.options`
+.. versionadded:: 1.3.6 added :meth:`_orm.Load.options`
.. seealso::
object is accessed from a subsequent query that specifies a different set of
options.To change the options on an existing object without expunging it and
re-loading, they must be set explicitly in conjunction with the
- :meth:`.Query.populate_existing` method::
+ :meth:`_query.Query.populate_existing` method::
# change the options on Parent objects that were already loaded
session.query(Parent).populate_existing().options(
statements emitted. In SQLAlchemy, the usual mitigation for the N+1 problem
is to make use of its very capable eager load system. However, eager loading
requires that the attributes which are to be loaded be specified with the
-:class:`.Query` up front. The problem of code that may access other attributes
+:class:`_query.Query` up front. The problem of code that may access other attributes
that were not eagerly loaded, where lazy loading is not desired, may be
addressed using the :func:`.raiseload` strategy; this loader strategy
replaces the behavior of lazy loading with an informative error being
The above wildcard will apply to **all** relationships not just on ``Order``
besides ``items``, but all those on the ``Item`` objects as well. To set up
:func:`.raiseload` for only the ``Order`` objects, specify a full
-path with :class:`.orm.Load`::
+path with :class:`_orm.Load`::
from sqlalchemy.orm import Load
Joined eager loading is the most fundamental style of eager loading in the
ORM. It works by connecting a JOIN (by default
-a LEFT OUTER join) to the SELECT statement emitted by a :class:`.Query`
+a LEFT OUTER join) to the SELECT statement emitted by a :class:`_query.Query`
and populates the target scalar/collection from the
same result set as that of the parent.
Joined eager loading is usually applied as an option to a query, rather than
as a default loading option on the mapping, in particular when used for
collections rather than many-to-one-references. This is achieved
-using the :func:`.joinedload` loader option:
+using the :func:`_orm.joinedload` loader option:
.. sourcecode:: python+sql
to have an element, such as a many-to-one
reference to a related object where the referencing foreign key is NOT NULL,
the query can be made more efficient by using an inner join; this is available
-at the mapping level via the :paramref:`.relationship.innerjoin` flag::
+at the mapping level via the :paramref:`_orm.relationship.innerjoin` flag::
class Address(Base):
# ...
user_id = Column(ForeignKey('users.id'), nullable=False)
user = relationship(User, lazy="joined", innerjoin=True)
-At the query option level, via the :paramref:`.joinedload.innerjoin` flag::
+At the query option level, via the :paramref:`_orm.joinedload.innerjoin` flag::
session.query(Address).options(
joinedload(Address.user, innerjoin=True))
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
A central concept of joined eager loading when applied to collections is that
-the :class:`.Query` object must de-duplicate rows against the leading
+the :class:`_query.Query` object must de-duplicate rows against the leading
entity being queried. Such as above,
if the ``User`` object we loaded referred to three ``Address`` objects, the
-result of the SQL statement would have had three rows; yet the :class:`.Query`
+result of the SQL statement would have had three rows; yet the :class:`_query.Query`
returns only one ``User`` object. As additional rows are received for a
``User`` object just loaded in a previous row, the additional columns that
refer to new ``Address`` objects are directed into additional results within
This process is very transparent, however does imply that joined eager
loading is incompatible with "batched" query results, provided by the
-:meth:`.Query.yield_per` method, when used for collection loading. Joined
+:meth:`_query.Query.yield_per` method, when used for collection loading. Joined
eager loading used for scalar references is however compatible with
-:meth:`.Query.yield_per`. The :meth:`.Query.yield_per` method will result
+:meth:`_query.Query.yield_per`. The :meth:`_query.Query.yield_per` method will result
in an exception thrown if a collection based joined eager loader is
in play.
compatibility with collection-based joined eager loading, emit multiple
SELECT statements, each referring to a subset of rows using the WHERE
clause, e.g. windowing. Alternatively, consider using "select IN" eager loading
-which is **potentially** compatible with :meth:`.Query.yield_per`, provided
+which is **potentially** compatible with :meth:`_query.Query.yield_per`, provided
that the database driver in use supports multiple, simultaneous cursors
(SQLite, PostgreSQL drivers, not MySQL drivers or SQL Server ODBC drivers).
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Since joined eager loading seems to have many resemblances to the use of
-:meth:`.Query.join`, it often produces confusion as to when and how it should
+:meth:`_query.Query.join`, it often produces confusion as to when and how it should
be used. It is critical to understand the distinction that while
-:meth:`.Query.join` is used to alter the results of a query, :func:`.joinedload`
+:meth:`_query.Query.join` is used to alter the results of a query, :func:`_orm.joinedload`
goes through great lengths to **not** alter the results of the query, and
instead hide the effects of the rendered join to only allow for related objects
to be present.
strategy for these. The strategy can be changed with no other modifications
to the query, the results will remain identical, but fewer SQL statements would
be emitted. In theory (and pretty much in practice), nothing you can do to the
-:class:`.Query` would make it load a different set of primary or related
+:class:`_query.Query` would make it load a different set of primary or related
objects based on a change in loader strategy.
How :func:`joinedload` in particular achieves this result of not impacting
entity rows returned in any way is that it creates an anonymous alias of the
joins it adds to your query, so that they can't be referenced by other parts of
-the query. For example, the query below uses :func:`.joinedload` to create a
+the query. For example, the query below uses :func:`_orm.joinedload` to create a
LEFT OUTER JOIN from ``users`` to ``addresses``, however the ``ORDER BY`` added
against ``Address.email_address`` is not valid - the ``Address`` entity is not
named in the query:
Above, ``ORDER BY addresses.email_address`` is not valid since ``addresses`` is not in the
FROM list. The correct way to load the ``User`` records and order by email
-address is to use :meth:`.Query.join`:
+address is to use :meth:`_query.Query.join`:
.. sourcecode:: python+sql
The statement above is of course not the same as the previous one, in that the
columns from ``addresses`` are not included in the result at all. We can add
-:func:`.joinedload` back in, so that there are two joins - one is that which we
+:func:`_orm.joinedload` back in, so that there are two joins - one is that which we
are ordering on, the other is used anonymously to load the contents of the
``User.addresses`` collection:
ORDER BY addresses.email_address
['jack']
-What we see above is that our usage of :meth:`.Query.join` is to supply JOIN
+What we see above is that our usage of :meth:`_query.Query.join` is to supply JOIN
clauses we'd like to use in subsequent query criterion, whereas our usage of
-:func:`.joinedload` only concerns itself with the loading of the
+:func:`_orm.joinedload` only concerns itself with the loading of the
``User.addresses`` collection, for each ``User`` in the result. In this case,
the two joins most probably appear redundant - which they are. If we wanted to
use just one JOIN for collection loading as well as ordering, we use the
populate the ``User.addresses`` collection, for those ``User`` objects that are
returned.
-By changing the usage of :func:`.joinedload` to another style of loading, we
+By changing the usage of :func:`_orm.joinedload` to another style of loading, we
can change how the collection is loaded completely independently of SQL used to
-retrieve the actual ``User`` rows we want. Below we change :func:`.joinedload`
+retrieve the actual ``User`` rows we want. Below we change :func:`_orm.joinedload`
into :func:`.subqueryload`:
.. sourcecode:: python+sql
----------------------
Subqueryload eager loading is configured in the same manner as that of
-joined eager loading; for the :paramref:`.relationship.lazy` parameter,
+joined eager loading; for the :paramref:`_orm.relationship.lazy` parameter,
we would specify ``"subquery"`` rather than ``"joined"``, and for
the option we use the :func:`.subqueryload` option rather than the
-:func:`.joinedload` option.
+:func:`_orm.joinedload` option.
The operation of subquery eager loading is to emit a second SELECT statement
for each relationship to be loaded, across all result objects at once.
use of a subquery, can on some backends in some cases (notably MySQL) produce
significantly slow queries. Additionally, the subqueryload strategy can only
load the full contents of all collections at once, is therefore incompatible
-with "batched" loading supplied by :meth:`.Query.yield_per`, both for collection
+with "batched" loading supplied by :meth:`_query.Query.yield_per`, both for collection
and scalar relationships.
The newer style of loading provided by :func:`.selectinload` solves these
^^^^^^^^^^^^^^^^^^^^^^^^^^
A query which makes use of :func:`.subqueryload` in conjunction with a
-limiting modifier such as :meth:`.Query.first`, :meth:`.Query.limit`,
-or :meth:`.Query.offset` should **always** include :meth:`.Query.order_by`
+limiting modifier such as :meth:`_query.Query.first`, :meth:`_query.Query.limit`,
+or :meth:`_query.Query.offset` should **always** include :meth:`_query.Query.order_by`
against unique column(s) such as the primary key, so that the additional queries
emitted by :func:`.subqueryload` include
the same ordering as used by the parent query. Without it, there is a chance
that of subquery eager loading. Additionally, select IN loading applies
itself to subsets of the load result at a time, so unlike joined and subquery
eager loading, is compatible with batching of results using
-:meth:`.Query.yield_per`, provided the database driver supports simultaneous
+:meth:`_query.Query.yield_per`, provided the database driver supports simultaneous
cursors.
Overall, especially as of the 1.3 series of SQLAlchemy, selectin loading
.. versionadded:: 1.2
"Select IN" eager loading is provided using the ``"selectin"`` argument to
-:paramref:`.relationship.lazy` or by using the :func:`.selectinload` loader
+:paramref:`_orm.relationship.lazy` or by using the :func:`.selectinload` loader
option. This style of loading emits a SELECT that refers to the primary key
values of the parent object, or in the case of a simple many-to-one
relationship to the those of the child objects, inside of an IN clause, in
SQL overhead as they query against primary key directly.
* "selectin" loading is the only eager loading that can work in conjunction with
- the "batching" feature provided by :meth:`.Query.yield_per`, provided
+ the "batching" feature provided by :meth:`_query.Query.yield_per`, provided
the database driver supports simultaneous cursors. As it only
queries for related items against specific result objects, "selectin" loading
allows for eagerly loaded collections against arbitrarily large result sets
- with a top limit on memory use when used with :meth:`.Query.yield_per`.
+ with a top limit on memory use when used with :meth:`_query.Query.yield_per`.
Current database drivers that support simultaneous cursors include
SQLite, PostgreSQL. The MySQL drivers mysqlclient and pymysql currently
* selectin loading, unlike joined (when using collections) and subquery eager
loading (all kinds of relationships), is potentially compatible with result
- set batching provided by :meth:`.Query.yield_per` assuming an appropriate
+ set batching provided by :meth:`_query.Query.yield_per` assuming an appropriate
database driver, so may be able to allow batching for large result sets.
* Many to One Reference
* When using the default lazy loading, a load of 100 objects will like in the case of the collection
emit as many as 101 SQL statements. However - there is a significant exception to this, in that
if the many-to-one reference is a simple foreign key reference to the target's primary key, each
- reference will be checked first in the current identity map using :meth:`.Query.get`. So here,
+ reference will be checked first in the current identity map using :meth:`_query.Query.get`. So here,
if the collection of objects references a relatively small set of target objects, or the full set
of possible target objects have already been loaded into the session and are strongly referenced,
using the default of `lazy='select'` is by far the most efficient way to go.
will be a LEFT OUTER JOIN, and the total number of rows will be equal to 100 in all cases.
If you know that each parent definitely has a child (i.e. the foreign
key reference is NOT NULL), the joined load can be configured with
- :paramref:`~.relationship.innerjoin` set to ``True``, which is
+ :paramref:`_orm.relationship.innerjoin` set to ``True``, which is
usually specified within the :func:`~sqlalchemy.orm.relationship`. For a load of objects where
there are many possible target references which may have not been loaded already, joined loading
with an INNER JOIN is extremely efficient.
Specification of polymorphic options on a per-eager-load basis is supported.
See the section :ref:`eagerloading_polymorphic_subtypes` for examples
of the :meth:`.PropComparator.of_type` method in conjunction with the
-:func:`.orm.with_polymorphic` function.
+:func:`_orm.with_polymorphic` function.
.. _wildcard_loader_strategies:
Wildcard Loading Strategies
---------------------------
-Each of :func:`.joinedload`, :func:`.subqueryload`, :func:`.lazyload`,
+Each of :func:`_orm.joinedload`, :func:`.subqueryload`, :func:`.lazyload`,
:func:`.selectinload`,
:func:`.noload`, and :func:`.raiseload` can be used to set the default
-style of :func:`.relationship` loading
-for a particular query, affecting all :func:`.relationship` -mapped
+style of :func:`_orm.relationship` loading
+for a particular query, affecting all :func:`_orm.relationship` -mapped
attributes not otherwise
-specified in the :class:`.Query`. This feature is available by passing
+specified in the :class:`_query.Query`. This feature is available by passing
the string ``'*'`` as the argument to any of these options::
session.query(MyClass).options(lazyload('*'))
Above, the ``lazyload('*')`` option will supersede the ``lazy`` setting
-of all :func:`.relationship` constructs in use for that query,
+of all :func:`_orm.relationship` constructs in use for that query,
except for those which use the ``'dynamic'`` style of loading.
If some relationships specify
``lazy='joined'`` or ``lazy='subquery'``, for example,
A variant of the wildcard loader strategy is the ability to set the strategy
on a per-entity basis. For example, if querying for ``User`` and ``Address``,
we can instruct all relationships on ``Address`` only to use lazy loading
-by first applying the :class:`.Load` object, then specifying the ``*`` as a
+by first applying the :class:`_orm.Load` object, then specifying the ``*`` as a
chained option::
session.query(User, Address).options(
If the "eager" portion of the statement is "aliased", the ``alias`` keyword
argument to :func:`~sqlalchemy.orm.contains_eager` may be used to indicate it.
-This is sent as a reference to an :func:`.aliased` or :class:`.Alias`
+This is sent as a reference to an :func:`.aliased` or :class:`_expression.Alias`
construct:
.. sourcecode:: python+sql
The ``alias`` argument can be more creatively used, in that it can be made
to represent any set of arbitrary names to match up into a statement.
-Below it is linked to a :func:`~.sql.expression.select` which links a set of column objects
+Below it is linked to a :func:`_expression.select` which links a set of column objects
to a string SQL statement::
# label the columns of the addresses table
A non-ORM means of affecting the value of a column in a way that suits
converting data between how it is represented in Python, vs. how it is
represented in the database, can be achieved by using a custom datatype that is
-applied to the mapped :class:`.Table` metadata. This is more common in the
+applied to the mapped :class:`_schema.Table` metadata. This is more common in the
case of some style of encoding / decoding that occurs both as data goes to the
database and as it is returned; read more about this in the Core documentation
at :ref:`types_typedecorator`.
``EmailAddress`` object will shuttle the value through the ``email``
descriptor and into the ``_email`` mapped attribute, the class level
``EmailAddress.email`` attribute does not have the usual expression semantics
-usable with :class:`.Query`. To provide these, we instead use the
+usable with :class:`_query.Query`. To provide these, we instead use the
:mod:`~sqlalchemy.ext.hybrid` extension as follows::
from sqlalchemy.ext.hybrid import hybrid_property
type level - see the
section :ref:`types_operators` for a description.
-ORM level functions like :func:`.column_property`, :func:`.relationship`,
+ORM level functions like :func:`.column_property`, :func:`_orm.relationship`,
and :func:`.composite` also provide for operator redefinition at the ORM
level, by passing a :class:`.PropComparator` subclass to the ``comparator_factory``
argument of each function. Customization of operators at this level is a
must be distinguished from the Python expression, which can be achieved using
:meth:`.hybrid_property.expression`. Below we illustrate the case where a conditional
needs to be present inside the hybrid, using the ``if`` statement in Python and the
-:func:`.sql.expression.case` construct for SQL expressions::
+:func:`_expression.case` construct for SQL expressions::
from sqlalchemy.ext.hybrid import hybrid_property
from sqlalchemy.sql import case
Using column_property
---------------------
-The :func:`.orm.column_property` function can be used to map a SQL
-expression in a manner similar to a regularly mapped :class:`.Column`.
+The :func:`_orm.column_property` function can be used to map a SQL
+expression in a manner similar to a regularly mapped :class:`_schema.Column`.
With this technique, the attribute is loaded
along with all other column-mapped attributes at load time. This is in some
cases an advantage over the usage of hybrids, as the value can be loaded
subquery) to access data that wouldn't normally be
available on an already loaded object.
-Disadvantages to using :func:`.orm.column_property` for SQL expressions include that
+Disadvantages to using :func:`_orm.column_property` for SQL expressions include that
the expression must be compatible with the SELECT statement emitted for the class
as a whole, and there are also some configurational quirks which can occur
-when using :func:`.orm.column_property` from declarative mixins.
+when using :func:`_orm.column_property` from declarative mixins.
-Our "fullname" example can be expressed using :func:`.orm.column_property` as
+Our "fullname" example can be expressed using :func:`_orm.column_property` as
follows::
from sqlalchemy.orm import column_property
lastname = Column(String(50))
fullname = column_property(firstname + " " + lastname)
-Correlated subqueries may be used as well. Below we use the :func:`~.sql.expression.select`
+Correlated subqueries may be used as well. Below we use the :func:`_expression.select`
construct to create a SELECT that links together the count of ``Address``
objects available for a particular ``User``::
correlate_except(Address)
)
-In the above example, we define a :func:`~.sql.expression.select` construct like the following::
+In the above example, we define a :func:`_expression.select` construct like the following::
select([func.count(Address.id)]).\
where(Address.user_id==id).\
The meaning of the above statement is, select the count of ``Address.id`` rows
where the ``Address.user_id`` column is equated to ``id``, which in the context
-of the ``User`` class is the :class:`.Column` named ``id`` (note that ``id`` is
+of the ``User`` class is the :class:`_schema.Column` named ``id`` (note that ``id`` is
also the name of a Python built in function, which is not what we want to use
here - if we were outside of the ``User`` class definition, we'd use ``User.id``).
-The :meth:`.select.correlate_except` directive indicates that each element in the
-FROM clause of this :func:`~.sql.expression.select` may be omitted from the FROM list (that is, correlated
+The :meth:`_expression.select.correlate_except` directive indicates that each element in the
+FROM clause of this :func:`_expression.select` may be omitted from the FROM list (that is, correlated
to the enclosing SELECT statement against ``User``) except for the one corresponding
to ``Address``. This isn't strictly necessary, but prevents ``Address`` from
being inadvertently omitted from the FROM list in the case of a long string
If import issues prevent the :func:`.column_property` from being defined
inline with the class, it can be assigned to the class after both
-are configured. In Declarative this has the effect of calling :meth:`.Mapper.add_property`
+are configured. In Declarative this has the effect of calling :meth:`_orm.Mapper.add_property`
to add an additional property after the fact::
User.address_count = column_property(
Using a plain descriptor
------------------------
-In cases where a SQL query more elaborate than what :func:`.orm.column_property`
+In cases where a SQL query more elaborate than what :func:`_orm.column_property`
or :class:`.hybrid_property` can provide must be emitted, a regular Python
function accessed as an attribute can be used, assuming the expression
only needs to be available on an already-loaded instance. The function
expired**. Once the object is expired, either via :meth:`.Session.expire`
or via the expire_on_commit behavior of :meth:`.Session.commit`, the value is
removed from the attribute and will return ``None`` on subsequent access.
- Only by running a new :class:`.Query` that touches the object which includes
+ Only by running a new :class:`_query.Query` that touches the object which includes
a new :func:`.with_expression` directive will the attribute be set to a
non-None value.
Mapping Table Columns
=====================
-The default behavior of :func:`~.orm.mapper` is to assemble all the columns in
-the mapped :class:`.Table` into mapped object attributes, each of which are
+The default behavior of :func:`_orm.mapper` is to assemble all the columns in
+the mapped :class:`_schema.Table` into mapped object attributes, each of which are
named according to the name of the column itself (specifically, the ``key``
-attribute of :class:`.Column`). This behavior can be
+attribute of :class:`_schema.Column`). This behavior can be
modified in several ways.
.. _mapper_column_distinct_names:
----------------------------------------------
A mapping by default shares the same name for a
-:class:`.Column` as that of the mapped attribute - specifically
-it matches the :attr:`.Column.key` attribute on :class:`.Column`, which
-by default is the same as the :attr:`.Column.name`.
+:class:`_schema.Column` as that of the mapped attribute - specifically
+it matches the :attr:`_schema.Column.key` attribute on :class:`_schema.Column`, which
+by default is the same as the :attr:`_schema.Column.name`.
The name assigned to the Python attribute which maps to
-:class:`.Column` can be different from either :attr:`.Column.name` or :attr:`.Column.key`
+:class:`_schema.Column` can be different from either :attr:`_schema.Column.name` or :attr:`_schema.Column.key`
just by assigning it that way, as we illustrate here in a Declarative mapping::
class User(Base):
Where above ``User.id`` resolves to a column named ``user_id``
and ``User.name`` resolves to a column named ``user_name``.
-When mapping to an existing table, the :class:`.Column` object
+When mapping to an existing table, the :class:`_schema.Column` object
can be referenced directly::
class User(Base):
------------------------------------------------------
In the previous section :ref:`mapper_column_distinct_names`, we showed how
-a :class:`.Column` explicitly mapped to a class can have a different attribute
-name than the column. But what if we aren't listing out :class:`.Column`
-objects explicitly, and instead are automating the production of :class:`.Table`
+a :class:`_schema.Column` explicitly mapped to a class can have a different attribute
+name than the column. But what if we aren't listing out :class:`_schema.Column`
+objects explicitly, and instead are automating the production of :class:`_schema.Table`
objects using reflection (e.g. as described in :ref:`metadata_reflection_toplevel`)?
In this case we can make use of the :meth:`.DDLEvents.column_reflect` event
-to intercept the production of :class:`.Column` objects and provide them
-with the :attr:`.Column.key` of our choice::
+to intercept the production of :class:`_schema.Column` objects and provide them
+with the :attr:`_schema.Column.key` of our choice::
@event.listens_for(Table, "column_reflect")
def column_reflect(inspector, table, column_info):
# set column.key = "attr_<lower_case_name>"
column_info['key'] = "attr_%s" % column_info['name'].lower()
-With the above event, the reflection of :class:`.Column` objects will be intercepted
+With the above event, the reflection of :class:`_schema.Column` objects will be intercepted
with our event that adds a new ".key" element, such as in a mapping as below::
class MyClass(Base):
__table__ = Table("some_table", Base.metadata,
autoload=True, autoload_with=some_engine)
-If we want to qualify our event to only react for the specific :class:`.MetaData`
+If we want to qualify our event to only react for the specific :class:`_schema.MetaData`
object above, we can check for it in our event::
@event.listens_for(Table, "column_reflect")
--------------------------------
A quick approach to prefix column names, typically when mapping
-to an existing :class:`.Table` object, is to use ``column_prefix``::
+to an existing :class:`_schema.Table` object, is to use ``column_prefix``::
class User(Base):
__table__ = user_table
Using column_property for column level options
----------------------------------------------
-Options can be specified when mapping a :class:`.Column` using the
+Options can be specified when mapping a :class:`_schema.Column` using the
:func:`.column_property` function. This function
explicitly creates the :class:`.ColumnProperty` used by the
-:func:`.mapper` to keep track of the :class:`.Column`; normally, the
+:func:`.mapper` to keep track of the :class:`_schema.Column`; normally, the
:func:`.mapper` creates this automatically. Using :func:`.column_property`,
-we can pass additional arguments about how we'd like the :class:`.Column`
+we can pass additional arguments about how we'd like the :class:`_schema.Column`
to be mapped. Below, we pass an option ``active_history``,
which specifies that a change to this column's value should
result in the former value being loaded first::
name = column_property(Column(String(50)), active_history=True)
:func:`.column_property` is also used to map a single attribute to
-multiple columns. This use case arises when mapping to a :func:`~.expression.join`
+multiple columns. This use case arises when mapping to a :func:`_expression.join`
which has attributes which are equated to each other::
class User(Base):
Mapping a Subset of Table Columns
---------------------------------
-Sometimes, a :class:`.Table` object was made available using the
+Sometimes, a :class:`_schema.Table` object was made available using the
reflection process described at :ref:`metadata_reflection` to load
the table's structure from the database.
For such a table that has lots of columns that don't need to be referenced
all columns present except ``street``, ``city``, ``state``, and ``zip``.
When this mapping is used, the columns that are not included will not be
-referenced in any SELECT statements emitted by :class:`.Query`, nor will there
+referenced in any SELECT statements emitted by :class:`_query.Query`, nor will there
be any mapped attribute on the mapped class which represents the column;
assigning an attribute of that name will have no effect beyond that of
a normal Python attribute assignment.
In some cases, multiple columns may have the same name, such as when
mapping to a join of two or more tables that share some column name.
``include_properties`` and ``exclude_properties`` can also accommodate
-:class:`.Column` objects to more accurately describe which columns
+:class:`_schema.Column` objects to more accurately describe which columns
should be included or excluded::
class UserAddress(Base):
.. note::
- insert and update defaults configured on individual :class:`.Column`
+ insert and update defaults configured on individual :class:`_schema.Column`
objects, i.e. those described at :ref:`metadata_defaults` including those
- configured by the :paramref:`.Column.default`,
- :paramref:`.Column.onupdate`, :paramref:`.Column.server_default` and
- :paramref:`.Column.server_onupdate` parameters, will continue to function
- normally even if those :class:`.Column` objects are not mapped. This is
- because in the case of :paramref:`.Column.default` and
- :paramref:`.Column.onupdate`, the :class:`.Column` object is still present
- on the underlying :class:`.Table`, thus allowing the default functions to
+ configured by the :paramref:`_schema.Column.default`,
+ :paramref:`_schema.Column.onupdate`, :paramref:`_schema.Column.server_default` and
+ :paramref:`_schema.Column.server_onupdate` parameters, will continue to function
+ normally even if those :class:`_schema.Column` objects are not mapped. This is
+ because in the case of :paramref:`_schema.Column.default` and
+ :paramref:`_schema.Column.onupdate`, the :class:`_schema.Column` object is still present
+ on the underlying :class:`_schema.Table`, thus allowing the default functions to
take place when the ORM emits an INSERT or UPDATE, and in the case of
- :paramref:`.Column.server_default` and :paramref:`.Column.server_onupdate`,
+ :paramref:`_schema.Column.server_default` and :paramref:`_schema.Column.server_onupdate`,
the relational database itself emits these defaults as a server side
behavior.
"Declarative" is the richer and more succinct system that builds on top
of "Classical". Both styles may be used interchangeably, as the end
result of each is exactly the same - a user-defined class mapped by the
-:func:`.mapper` function onto a selectable unit, typically a :class:`.Table`.
+:func:`.mapper` function onto a selectable unit, typically a :class:`_schema.Table`.
Declarative Mapping
===================
mappings are constructed in modern SQLAlchemy.
Making use of the :ref:`declarative_toplevel`
system, the components of the user-defined class as well as the
-:class:`.Table` metadata to which the class is mapped are defined
+:class:`_schema.Table` metadata to which the class is mapped are defined
at once::
from sqlalchemy.ext.declarative import declarative_base
system provided by the ORM.
In "classical" form, the table metadata is created separately with the
-:class:`.Table` construct, then associated with the ``User`` class via
+:class:`_schema.Table` construct, then associated with the ``User`` class via
the :func:`.mapper` function::
from sqlalchemy import Table, MetaData, Column, Integer, String, ForeignKey
mapper(User, user)
Information about mapped attributes, such as relationships to other classes, are provided
-via the ``properties`` dictionary. The example below illustrates a second :class:`.Table`
-object, mapped to a class called ``Address``, then linked to ``User`` via :func:`.relationship`::
+via the ``properties`` dictionary. The example below illustrates a second :class:`_schema.Table`
+object, mapped to a class called ``Address``, then linked to ``User`` via :func:`_orm.relationship`::
address = Table('address', metadata,
Column('id', Integer, primary_key=True),
When using classical mappings, classes must be provided directly without the benefit
of the "string lookup" system provided by Declarative. SQL expressions are typically
-specified in terms of the :class:`.Table` objects, i.e. ``address.c.id`` above
+specified in terms of the :class:`_schema.Table` objects, i.e. ``address.c.id`` above
for the ``Address`` relationship, and not ``Address.id``, as ``Address`` may not
yet be linked to table metadata, nor can we specify a string here.
Some examples in the documentation still use the classical approach, but note that
the classical as well as Declarative approaches are **fully interchangeable**. Both
-systems ultimately create the same configuration, consisting of a :class:`.Table`,
+systems ultimately create the same configuration, consisting of a :class:`_schema.Table`,
user-defined class, linked together with a :func:`.mapper`. When we talk about
"the behavior of :func:`.mapper`", this includes when using the Declarative system
as well - it's still used, just behind the scenes.
Runtime Introspection of Mappings, Objects
==========================================
-The :class:`.Mapper` object is available from any mapped class, regardless
+The :class:`_orm.Mapper` object is available from any mapped class, regardless
of method, using the :ref:`core_inspection_toplevel` system. Using the
-:func:`.inspect` function, one can acquire the :class:`.Mapper` from a
+:func:`_sa.inspect` function, one can acquire the :class:`_orm.Mapper` from a
mapped class::
>>> from sqlalchemy import inspect
>>> insp = inspect(User)
-Detailed information is available including :attr:`.Mapper.columns`::
+Detailed information is available including :attr:`_orm.Mapper.columns`::
>>> insp.columns
<sqlalchemy.util._collections.OrderedProperties object at 0x102f407f8>
>>> insp.columns.name
Column('name', String(length=50), table=<user>)
-Other namespaces include :attr:`.Mapper.all_orm_descriptors`, which includes all mapped
+Other namespaces include :attr:`_orm.Mapper.all_orm_descriptors`, which includes all mapped
attributes as well as hybrids, association proxies::
>>> insp.all_orm_descriptors
>>> insp.all_orm_descriptors.keys()
['fullname', 'nickname', 'name', 'id']
-As well as :attr:`.Mapper.column_attrs`::
+As well as :attr:`_orm.Mapper.column_attrs`::
>>> list(insp.column_attrs)
[<ColumnProperty at 0x10403fde0; id>, <ColumnProperty at 0x10403fce8; name>, <ColumnProperty at 0x1040e9050; fullname>, <ColumnProperty at 0x1040e9148; nickname>]
:ref:`core_inspection_toplevel`
- :class:`.Mapper`
+ :class:`_orm.Mapper`
:class:`.InstanceState`
=======================================
Mappers can be constructed against arbitrary relational units (called
-*selectables*) in addition to plain tables. For example, the :func:`~.expression.join`
+*selectables*) in addition to plain tables. For example, the :func:`_expression.join`
function creates a selectable unit comprised of
multiple tables, complete with its own composite primary key, which can be
-mapped in the same way as a :class:`.Table`::
+mapped in the same way as a :class:`_schema.Table`::
from sqlalchemy import Table, Column, Integer, \
String, MetaData, join, ForeignKey
connection.execute(q_table.insert(), {"id": target.id})
where above, a row is INSERTed into the ``q_table`` table by creating an
- INSERT construct with :meth:`.Table.insert`, then executing it using the
- given :class:`.Connection` which is the same one being used to emit other
+ INSERT construct with :meth:`_schema.Table.insert`, then executing it using the
+ given :class:`_engine.Connection` which is the same one being used to emit other
SQL for the flush process. The user-supplied logic would have to detect
that the LEFT OUTER JOIN from "p" to "q" does not have an entry for the "q"
side.
Mapping a Class against Arbitrary Selects
=========================================
-Similar to mapping against a join, a plain :func:`~.expression.select` object can be used with a
+Similar to mapping against a join, a plain :func:`_expression.select` object can be used with a
mapper as well. The example fragment below illustrates mapping a class
-called ``Customer`` to a :func:`~.expression.select` which includes a join to a
+called ``Customer`` to a :func:`_expression.select` which includes a join to a
subquery::
from sqlalchemy import select, func
by direct query construction. The practice is to some degree
based on the very early history of SQLAlchemy where the :func:`.mapper`
construct was meant to represent the primary querying interface;
- in modern usage, the :class:`.Query` object can be used to construct
+ in modern usage, the :class:`_query.Query` object can be used to construct
virtually any SELECT statement, including complex composites, and should
be favored over the "map-to-selectable" approach.
functionality: querying, persistence, and instrumentation of the mapped class.
The rationale of the primary mapper relates to the fact that the
:func:`.mapper` modifies the class itself, not only persisting it towards a
-particular :class:`.Table`, but also :term:`instrumenting` attributes upon the
+particular :class:`_schema.Table`, but also :term:`instrumenting` attributes upon the
class which are structured specifically according to the table metadata. It's
not possible for more than one mapper to be associated with a class in equal
measure, since only one mapper can actually instrument the class.
So what if we want to actually put NULL into this column, even though the
column has a default value? There are two approaches. One is that
on a per-instance level, we assign the attribute using the
-:obj:`~.expression.null` SQL construct::
+:obj:`_expression.null` SQL construct::
from sqlalchemy import null
# and server-side defaults, and the database will
# persist this as the NULL value
-The :obj:`~.expression.null` SQL construct always translates into the SQL
+The :obj:`_expression.null` SQL construct always translates into the SQL
NULL value being directly present in the target INSERT statement.
If we'd like to be able to use the Python value ``None`` and have this
is often native to the Python DBAPI, and in general this process is automatic,
with the exception of a database like Oracle that requires us to specify a
:class:`.Sequence` explicitly. There is more documentation regarding this
-at :paramref:`.Column.autoincrement`.
+at :paramref:`_schema.Column.autoincrement`.
For server-generating columns that are not primary key columns or that are not
simple autoincrementing integer columns, the ORM requires that these columns
-------------------------------------------------------------
In this case, columns should be marked as :class:`.FetchedValue` or with an
-explicit :paramref:`.Column.server_default`. The
+explicit :paramref:`_schema.Column.server_default`. The
:paramref:`.orm.mapper.eager_defaults` flag may be used to indicate that these
columns should be fetched immediately upon INSERT and sometimes UPDATE::
MySQL with TIMESTAMP primary key
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-When using the :class:`.TIMESTAMP` datatype with MySQL, MySQL ordinarily
+When using the :class:`_types.TIMESTAMP` datatype with MySQL, MySQL ordinarily
associates a server-side default with this datatype automatically. However
when we use one as a primary key, the Core cannot retrieve the newly generated
-value unless we execute the function ourselves. As :class:`.TIMESTAMP` on
+value unless we execute the function ourselves. As :class:`_types.TIMESTAMP` on
MySQL actually stores a binary value, we need to add an additional "CAST" to our
usage of "NOW()" so that we retrieve a binary value that can be persisted
into the column::
:class:`.Session` with the :paramref:`.Session.binds` argument. This
argument receives a dictionary that contains any combination of
ORM-mapped classes, arbitrary classes within a mapped hierarchy (such
-as declarative base classes or mixins), :class:`.Table` objects,
-and :class:`.Mapper` objects as keys, which then refer typically to
-:class:`.Engine` or less typically :class:`.Connection` objects as targets.
+as declarative base classes or mixins), :class:`_schema.Table` objects,
+and :class:`_orm.Mapper` objects as keys, which then refer typically to
+:class:`_engine.Engine` or less typically :class:`_engine.Connection` objects as targets.
The dictionary is consulted whenever the :class:`.Session` needs to
emit SQL on behalf of a particular kind of mapped class in order to locate
the appropriate source of database connectivity::
session = Session()
-Above, SQL operations against either class will make usage of the :class:`.Engine`
+Above, SQL operations against either class will make usage of the :class:`_engine.Engine`
linked to that class. The functionality is comprehensive across both
-read and write operations; a :class:`.Query` that is against entities
+read and write operations; a :class:`_query.Query` that is against entities
mapped to ``engine1`` (determined by looking at the first entity in the
list of items requested) will make use of ``engine1`` to run the query. A
flush operation will make use of **both** engines on a per-class basis as it
Session = sessionmaker(class_=RoutingSession)
-This approach can be combined with multiple :class:`.MetaData` objects,
+This approach can be combined with multiple :class:`_schema.MetaData` objects,
using an approach such as that of using the declarative ``__abstract__``
keyword, described at :ref:`declarative_abstract`.
Horizontal partitioning partitions the rows of a single table (or a set of
tables) across multiple databases. The SQLAlchemy :class:`.Session`
contains support for this concept, however to use it fully requires that
-:class:`.Session` and :class:`.Query` subclasses are used. A basic version
+:class:`.Session` and :class:`_query.Query` subclasses are used. A basic version
of these subclasses are available in the :ref:`horizontal_sharding_toplevel`
ORM extension. An example of use is at: :ref:`examples_sharding`.
* The flush() process, including the survey of all objects, their state,
their cascade status, the status of all objects associated with them
- via :func:`.relationship`, and the topological sort of all operations to
+ via :func:`_orm.relationship`, and the topological sort of all operations to
be performed is completely bypassed. This reduces a great amount of
Python overhead.
---------------------------------------------
The bulk methods offer performance that under particular circumstances
-can be close to that of using the core :class:`~.sql.expression.Insert` and
-:class:`.Update` constructs in an "executemany" context (for a description
+can be close to that of using the core :class:`_expression.Insert` and
+:class:`_expression.Update` constructs in an "executemany" context (for a description
of "executemany", see :ref:`execute_multiple` in the Core tutorial).
In order to achieve this, the
:paramref:`.Session.bulk_insert_mappings.return_defaults`
versus traditional ORM use. The following is a listing of features that
are **not available** when using these methods:
-* persistence along :func:`.relationship` linkages
+* persistence along :func:`_orm.relationship` linkages
* sorting of rows within order of dependency; rows are inserted or updated
directly in the order in which they are passed to the methods
Query API
=========
-This section presents the API reference for the ORM :class:`.Query` object. For a walkthrough
+This section presents the API reference for the ORM :class:`_query.Query` object. For a walkthrough
of how to use this object, see :ref:`ormtutorial_toplevel`.
The Query Object
================
-:class:`~.Query` is produced in terms of a given :class:`~.Session`, using the :meth:`~.Session.query` method::
+:class:`_query.Query` is produced in terms of a given :class:`~.Session`, using the :meth:`~.Session.query` method::
q = session.query(SomeMappedClass)
-Following is the full interface for the :class:`.Query` object.
+Following is the full interface for the :class:`_query.Query` object.
.. autoclass:: sqlalchemy.orm.query.Query
:members:
:func:`~sqlalchemy.orm.relationship`).
To enable the usage of a supplementary UPDATE statement,
-we use the :paramref:`~.relationship.post_update` option
-of :func:`.relationship`. This specifies that the linkage between the
+we use the :paramref:`_orm.relationship.post_update` option
+of :func:`_orm.relationship`. This specifies that the linkage between the
two rows should be created using an UPDATE statement after both rows
have been INSERTED; it also causes the rows to be de-associated with
each other via UPDATE before a DELETE is emitted. The flag should
be placed on just *one* of the relationships, preferably the
many-to-one side. Below we illustrate
-a complete example, including two :class:`.ForeignKey` constructs::
+a complete example, including two :class:`_schema.ForeignKey` constructs::
from sqlalchemy import Integer, ForeignKey, Column
from sqlalchemy.ext.declarative import declarative_base
foreign_keys=favorite_entry_id,
post_update=True)
-The above mapping features a composite :class:`.ForeignKeyConstraint`
+The above mapping features a composite :class:`_schema.ForeignKeyConstraint`
bridging the ``widget_id`` and ``favorite_entry_id`` columns. To ensure
that ``Widget.widget_id`` remains an "autoincrementing" column we specify
-:paramref:`~.Column.autoincrement` to the value ``"ignore_fk"``
-on :class:`.Column`, and additionally on each
-:func:`.relationship` we must limit those columns considered as part of
+:paramref:`_schema.Column.autoincrement` to the value ``"ignore_fk"``
+on :class:`_schema.Column`, and additionally on each
+:func:`_orm.relationship` we must limit those columns considered as part of
the foreign key for the purposes of joining and cross-population.
.. _passive_updates:
ForeignKey('user.username', onupdate="cascade")
)
-Above, we illustrate ``onupdate="cascade"`` on the :class:`.ForeignKey`
+Above, we illustrate ``onupdate="cascade"`` on the :class:`_schema.ForeignKey`
object, and we also illustrate the ``mysql_engine='InnoDB'`` setting
which, on a MySQL backend, ensures that the ``InnoDB`` engine supporting
referential integrity is used. When using SQLite, referential integrity
so that SQLAlchemy can emit UPDATE statements.
The feature is enabled by setting the
-:paramref:`~.relationship.passive_updates` flag to ``False``,
+:paramref:`_orm.relationship.passive_updates` flag to ``False``,
most preferably on a one-to-many or
-many-to-many :func:`.relationship`. When "updates" are no longer
+many-to-many :func:`_orm.relationship`. When "updates" are no longer
"passive" this indicates that SQLAlchemy will
issue UPDATE statements individually for
objects referenced in the collection referred to by the parent object
5 3 subchild2
6 1 child3
-The :func:`.relationship` configuration here works in the
+The :func:`_orm.relationship` configuration here works in the
same way as a "normal" one-to-many relationship, with the
exception that the "direction", i.e. whether the relationship
is one-to-many or many-to-one, is assumed by default to
be one-to-many. To establish the relationship as many-to-one,
-an extra directive is added known as :paramref:`~.relationship.remote_side`, which
-is a :class:`.Column` or collection of :class:`.Column` objects
+an extra directive is added known as :paramref:`_orm.relationship.remote_side`, which
+is a :class:`_schema.Column` or collection of :class:`_schema.Column` objects
that indicate those which should be considered to be "remote"::
class Node(Base):
data = Column(String(50))
parent = relationship("Node", remote_side=[id])
-Where above, the ``id`` column is applied as the :paramref:`~.relationship.remote_side`
-of the ``parent`` :func:`.relationship`, thus establishing
+Where above, the ``id`` column is applied as the :paramref:`_orm.relationship.remote_side`
+of the ``parent`` :func:`_orm.relationship`, thus establishing
``parent_id`` as the "local" side, and the relationship
then behaves as a many-to-one.
remote_side=[account_id, folder_id]
)
-Above, we pass ``account_id`` into the :paramref:`~.relationship.remote_side` list.
-:func:`.relationship` recognizes that the ``account_id`` column here
+Above, we pass ``account_id`` into the :paramref:`_orm.relationship.remote_side` list.
+:func:`_orm.relationship` recognizes that the ``account_id`` column here
is on both sides, and aligns the "remote" column along with the
``folder_id`` column, which it recognizes as uniquely present on
the "remote" side.
expression be "aliased" so that it can be unambiguously referred to.
Recall from :ref:`ormtutorial_aliases` in the ORM tutorial that the
-:func:`.orm.aliased` construct is normally used to provide an "alias" of
+:func:`_orm.aliased` construct is normally used to provide an "alias" of
an ORM entity. Joining from ``Node`` to itself using this technique
looks like:
AND node_1.data = ?
['subchild1', 'child2']
-:meth:`.Query.join` also includes a feature known as
+:meth:`_query.Query.join` also includes a feature known as
:paramref:`.Query.join.aliased` that can shorten the verbosity self-
referential joins, at the expense of query flexibility. This feature
performs a similar "aliasing" step to that above, without the need for
-an explicit entity. Calls to :meth:`.Query.filter` and similar
+an explicit entity. Calls to :meth:`_query.Query.filter` and similar
subsequent to the aliased join will **adapt** the ``Node`` entity to
be that of the alias:
To add criterion to multiple points along a longer join, add
:paramref:`.Query.join.from_joinpoint` to the additional
-:meth:`~.Query.join` calls:
+:meth:`_query.Query.join` calls:
.. sourcecode:: python+sql
AND node_2.data = ?
['subchild1', 'child2', 'root']
-:meth:`.Query.reset_joinpoint` will also remove the "aliasing" from filtering
+:meth:`_query.Query.reset_joinpoint` will also remove the "aliasing" from filtering
calls::
session.query(Node).\
.. module:: sqlalchemy.orm.session
-The :func:`.orm.mapper` function and :mod:`~sqlalchemy.ext.declarative` extensions
+The :func:`_orm.mapper` function and :mod:`~sqlalchemy.ext.declarative` extensions
are the primary configurational interface for the ORM. Once mappings are
configured, the primary usage interface for persistence operations is the
:class:`.Session`.
This function is the internal version
of :func:`.object_state`. The
:func:`.object_state` and/or the
- :func:`.inspect` function is preferred here
+ :func:`_sa.inspect` function is preferred here
as they each emit an informative exception
if the given object is not mapped.
In the most general sense, the :class:`~.Session` establishes all
conversations with the database and represents a "holding zone" for all the
objects which you've loaded or associated with it during its lifespan. It
-provides the entrypoint to acquire a :class:`.Query` object, which sends
+provides the entrypoint to acquire a :class:`_query.Query` object, which sends
queries to the database using the :class:`~.Session` object's current database
connection, populating result rows into objects that are then stored in the
:class:`.Session`, inside a structure called the `Identity Map
The :class:`.Session` begins in an essentially stateless form. Once queries
are issued or other objects are persisted with it, it requests a connection
-resource from an :class:`.Engine` that is associated either with the
-:class:`.Session` itself or with the mapped :class:`.Table` objects being
+resource from an :class:`_engine.Engine` that is associated either with the
+:class:`.Session` itself or with the mapped :class:`_schema.Table` objects being
operated upon. This connection represents an ongoing transaction, which
remains in effect until the :class:`.Session` is instructed to commit or roll
back its pending state.
which we assign to the name ``Session``. This factory, when
called, will create a new :class:`.Session` object using the configurational
arguments we've given the factory. In this case, as is typical,
-we've configured the factory to specify a particular :class:`.Engine` for
+we've configured the factory to specify a particular :class:`_engine.Engine` for
connection resources.
-A typical setup will associate the :class:`.sessionmaker` with an :class:`.Engine`,
-so that each :class:`.Session` generated will use this :class:`.Engine`
+A typical setup will associate the :class:`.sessionmaker` with an :class:`_engine.Engine`,
+so that each :class:`.Session` generated will use this :class:`_engine.Engine`
to acquire connection resources. This association can
be set up as in the example above, using the ``bind`` argument.
-------------------------------------------------------------
A common scenario is where the :class:`.sessionmaker` is invoked
-at module import time, however the generation of one or more :class:`.Engine`
+at module import time, however the generation of one or more :class:`_engine.Engine`
instances to be associated with the :class:`.sessionmaker` has not yet proceeded.
For this use case, the :class:`.sessionmaker` construct offers the
:meth:`.sessionmaker.configure` method, which will place additional configuration
:class:`.sessionmaker` factory's :meth:`.sessionmaker.__call__` method.
These arguments will override whatever
configurations have already been placed, such as below, where a new :class:`.Session`
-is constructed against a specific :class:`.Connection`::
+is constructed against a specific :class:`_engine.Connection`::
# at the module level, the global sessionmaker,
# bound to a specific Engine
session = Session(bind=conn)
The typical rationale for the association of a :class:`.Session` with a specific
-:class:`.Connection` is that of a test fixture that maintains an external
+:class:`_engine.Connection` is that of a test fixture that maintains an external
transaction - see :ref:`session_external_transaction` for an example of this.
isolated transaction, there shouldn't be any issue of instances representing
data which is stale with regards to the current transaction.
-The :class:`.Query` object is introduced in great detail in
+The :class:`_query.Query` object is introduced in great detail in
:ref:`ormtutorial_toplevel`, and further documented in
:ref:`query_api_toplevel`.
The ORM in general never modifies the contents of a collection or scalar
relationship during the flush process. This means, if your class has a
-:func:`.relationship` that refers to a collection of objects, or a reference
+:func:`_orm.relationship` that refers to a collection of objects, or a reference
to a single object such as many-to-one, the contents of this attribute will
not be modified when the flush process occurs. Instead, if the :class:`.Session`
is expired afterwards, either through the expire-on-commit behavior of
:meth:`~.Session.delete` method. When :meth:`.Session.delete` is invoked upon
an object and the :class:`.Session` is flushed, the row is deleted from the
database. Rows that refer to the target row via foreign key, assuming they
-are tracked using a :func:`.relationship` between the two mapped object types,
+are tracked using a :func:`_orm.relationship` between the two mapped object types,
will also see their foreign key attributes UPDATED to null, or if delete
cascade is set up, the related rows will be deleted as well. However, even
though rows related to the deleted object might be themselves modified as well,
or one-to-one relationship, so that when an object is de-associated from its
parent, it is also automatically marked for deletion. Using ``delete-orphan``
cascade on a many-to-one or one-to-one requires an additional flag
-:paramref:`.relationship.single_parent` which invokes an assertion
+:paramref:`_orm.relationship.single_parent` which invokes an assertion
that this related object is not to shared with any other parent simultaneously::
class User(Base):
* :meth:`.MapperEvents.before_delete`
* :meth:`.MapperEvents.after_delete`
-Each event is passed the :class:`.Mapper`,
-the mapped object itself, and the :class:`.Connection` which is being
+Each event is passed the :class:`_orm.Mapper`,
+the mapped object itself, and the :class:`_engine.Connection` which is being
used to emit an INSERT, UPDATE or DELETE statement. The appeal of these
events is clear, in that if an application wants to tie some activity to
when a specific type of object is persisted with an INSERT, the hook is
* Mapped relationship attribute set/del events,
i.e. ``someobject.related = someotherobject``
-The reason the :class:`.Connection` is passed is that it is encouraged that
-**simple SQL operations take place here**, directly on the :class:`.Connection`,
+The reason the :class:`_engine.Connection` is passed is that it is encouraged that
+**simple SQL operations take place here**, directly on the :class:`_engine.Connection`,
such as incrementing counters or inserting extra rows within log tables.
-When dealing with the :class:`.Connection`, it is expected that Core-level
+When dealing with the :class:`_engine.Connection`, it is expected that Core-level
SQL operations will be used; e.g. those described in :ref:`sqlexpression_toplevel`.
There are also many per-object operations that don't need to be handled
Transaction events allow an application to be notified when transaction
boundaries occur at the :class:`.Session` level as well as when the
-:class:`.Session` changes the transactional state on :class:`.Connection`
+:class:`.Session` changes the transactional state on :class:`_engine.Connection`
objects.
* :meth:`.SessionEvents.after_transaction_create`,
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The actual state of any mapped object can be viewed at any time using
-the :func:`.inspect` system::
+the :func:`_sa.inspect` system::
>>> from sqlalchemy import inspect
>>> insp = inspect(my_object)
In the caching use case, it's common to use the ``load=False``
flag to remove the overhead of reconciling the object's state
with the database. There's also a "bulk" version of
- :meth:`~.Session.merge` called :meth:`~.Query.merge_result`
- that was designed to work with cache-extended :class:`.Query`
+ :meth:`~.Session.merge` called :meth:`_query.Query.merge_result`
+ that was designed to work with cache-extended :class:`_query.Query`
objects - see the section :ref:`examples_caching`.
* An application wants to transfer the state of a series of objects
Above, our ``a1`` is already pending in the session. The
subsequent :meth:`~.Session.merge` operation essentially
-does nothing. Cascade can be configured via the :paramref:`~.relationship.cascade`
-option on :func:`.relationship`, although in this case it
+does nothing. Cascade can be configured via the :paramref:`_orm.relationship.cascade`
+option on :func:`_orm.relationship`, although in this case it
would mean removing the ``save-update`` cascade from the
``User.addresses`` relationship - and usually, that behavior
is extremely convenient. The solution here would usually be to not assign
``a1.user`` to an object already persistent in the target
session.
-The ``cascade_backrefs=False`` option of :func:`.relationship`
+The ``cascade_backrefs=False`` option of :func:`_orm.relationship`
will also prevent the ``Address`` from
being added to the session via the ``a1.user = u1`` assignment.
``_sa_instance_state`` is a non-database-persisted value used by SQLAlchemy
internally (it refers to the :class:`.InstanceState` for the instance.
While not directly relevant to this section, if we want to get at it,
-we should use the :func:`.inspect` function to access it).
+we should use the :func:`_sa.inspect` function to access it).
At this point, the state in our ``User`` object matches that of the loaded
database row. But upon expiring the object using a method such as
* The load of expired attributes is triggered from **column-mapped attributes only**.
While any kind of attribute can be marked as expired, including a
- :func:`.relationship` - mapped attribute, accessing an expired :func:`.relationship`
+ :func:`_orm.relationship` - mapped attribute, accessing an expired :func:`_orm.relationship`
attribute will emit a load only for that attribute, using standard
relationship-oriented lazy loading. Column-oriented attributes, even if
expired, will not load as part of this operation, and instead will load when
any column-oriented attribute is accessed.
-* :func:`.relationship`- mapped attributes will not load in response to
+* :func:`_orm.relationship`- mapped attributes will not load in response to
expired column-based attributes being accessed.
* Regarding relationships, :meth:`~.Session.refresh` is more restrictive than
:meth:`.Session.expire` with regards to attributes that aren't column-mapped.
Calling :meth:`.Session.refresh` and passing a list of names that only includes
relationship-mapped attributes will actually raise an error.
- In any case, non-eager-loading :func:`.relationship` attributes will not be
+ In any case, non-eager-loading :func:`_orm.relationship` attributes will not be
included in any refresh operation.
-* :func:`.relationship` attributes configured as "eager loading" via the
- :paramref:`~.relationship.lazy` parameter will load in the case of
+* :func:`_orm.relationship` attributes configured as "eager loading" via the
+ :paramref:`_orm.relationship.lazy` parameter will load in the case of
:meth:`~.Session.refresh`, if either no attribute names are specified, or
if their names are included in the list of attributes to be
refreshed.
is possibly stale. Reasons for this might include:
* some SQL has been emitted within the transaction outside of the
- scope of the ORM's object handling, such as if a :meth:`.Table.update` construct
+ scope of the ORM's object handling, such as if a :meth:`_schema.Table.update` construct
were emitted using the :meth:`.Session.execute` method;
* if the application
A newly constructed :class:`.Session` may be said to be in the "begin" state.
In this state, the :class:`.Session` has not established any connection or
-transactional state with any of the :class:`.Engine` objects that may be associated
+transactional state with any of the :class:`_engine.Engine` objects that may be associated
with it.
The :class:`.Session` then receives requests to operate upon a database connection.
Typically, this means it is called upon to execute SQL statements using a particular
-:class:`.Engine`, which may be via :meth:`.Session.query`, :meth:`.Session.execute`,
+:class:`_engine.Engine`, which may be via :meth:`.Session.query`, :meth:`.Session.execute`,
or within a flush operation of pending data, which occurs when such state exists
and :meth:`.Session.commit` or :meth:`.Session.flush` is called.
-As these requests are received, each new :class:`.Engine` encountered is associated
+As these requests are received, each new :class:`_engine.Engine` encountered is associated
with an ongoing transactional state maintained by the :class:`.Session`.
-When the first :class:`.Engine` is operated upon, the :class:`.Session` can be said
+When the first :class:`_engine.Engine` is operated upon, the :class:`.Session` can be said
to have left the "begin" state and entered "transactional" state. For each
-:class:`.Engine` encountered, a :class:`.Connection` is associated with it,
-which is acquired via the :meth:`.Engine.connect` method. If a
-:class:`.Connection` was directly associated with the :class:`.Session` (see :ref:`session_external_transaction`
+:class:`_engine.Engine` encountered, a :class:`_engine.Connection` is associated with it,
+which is acquired via the :meth:`_engine.Engine.connect` method. If a
+:class:`_engine.Connection` was directly associated with the :class:`.Session` (see :ref:`session_external_transaction`
for an example of this), it is
added to the transactional state directly.
-For each :class:`.Connection`, the :class:`.Session` also maintains a :class:`.Transaction` object,
-which is acquired by calling :meth:`.Connection.begin` on each :class:`.Connection`,
+For each :class:`_engine.Connection`, the :class:`.Session` also maintains a :class:`.Transaction` object,
+which is acquired by calling :meth:`_engine.Connection.begin` on each :class:`_engine.Connection`,
or if the :class:`.Session`
object has been established using the flag ``twophase=True``, a :class:`.TwoPhaseTransaction`
-object acquired via :meth:`.Connection.begin_twophase`. These transactions are all committed or
+object acquired via :meth:`_engine.Connection.begin_twophase`. These transactions are all committed or
rolled back corresponding to the invocation of the
:meth:`.Session.commit` and :meth:`.Session.rollback` methods. A commit operation will
also call the :meth:`.TwoPhaseTransaction.prepare` method on all transactions if applicable.
When the transactional state is completed after a rollback or commit, the :class:`.Session`
-:term:`releases` all :class:`.Transaction` and :class:`.Connection` resources,
+:term:`releases` all :class:`.Transaction` and :class:`_engine.Connection` resources,
and goes back to the "begin" state, which
-will again invoke new :class:`.Connection` and :class:`.Transaction` objects as new
+will again invoke new :class:`_engine.Connection` and :class:`.Transaction` objects as new
requests to emit SQL statements are received.
The example below illustrates this lifecycle::
``subtransactions=True`` is generally only useful in conjunction with
autocommit, and is equivalent to the pattern described at :ref:`connections_nested_transactions`,
-where any number of functions can call :meth:`.Connection.begin` and :meth:`.Transaction.commit`
+where any number of functions can call :meth:`_engine.Connection.begin` and :meth:`.Transaction.commit`
as though they are the initiator of the transaction, but in fact may be participating
in an already ongoing transaction::
allows these to be set on a per-connection basis, either through explicit
APIs or via database-specific calls.
-SQLAlchemy's dialects support settable isolation modes on a per-:class:`.Engine`
-or per-:class:`.Connection` basis, using flags at both the
-:func:`.create_engine` level as well as at the :meth:`.Connection.execution_options`
+SQLAlchemy's dialects support settable isolation modes on a per-:class:`_engine.Engine`
+or per-:class:`_engine.Connection` basis, using flags at both the
+:func:`.create_engine` level as well as at the :meth:`_engine.Connection.execution_options`
level.
When using the ORM :class:`.Session`, it acts as a *facade* for engines and
connections, but does not expose transaction isolation directly. So in
order to affect transaction isolation level, we need to act upon the
-:class:`.Engine` or :class:`.Connection` as appropriate.
+:class:`_engine.Engine` or :class:`_engine.Connection` as appropriate.
.. seealso::
When we make a new :class:`.Session`, either using the constructor directly
or when we call upon the callable produced by a :class:`.sessionmaker`,
we can pass the ``bind`` argument directly, overriding the pre-existing bind.
-We can combine this with the :meth:`.Engine.execution_options` method
-in order to produce a copy of the original :class:`.Engine` that will
+We can combine this with the :meth:`_engine.Engine.execution_options` method
+in order to produce a copy of the original :class:`_engine.Engine` that will
add this option::
session = maker(
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
A key caveat regarding isolation level is that the setting cannot be
-safely modified on a :class:`.Connection` where a transaction has already
+safely modified on a :class:`_engine.Connection` where a transaction has already
started. Databases cannot change the isolation level of a transaction
in progress, and some DBAPIs and SQLAlchemy dialects
have inconsistent behaviors in this area. Some may implicitly emit a
ROLLBACK and some may implicitly emit a COMMIT, others may ignore the setting
until the next transaction. Therefore SQLAlchemy emits a warning if this
option is set when a transaction is already in play. The :class:`.Session`
-object does not provide for us a :class:`.Connection` for use in a transaction
+object does not provide for us a :class:`_engine.Connection` for use in a transaction
where the transaction is not already begun. So here, we need to pass
execution options to the :class:`.Session` at the start of a transaction
by passing :paramref:`.Session.connection.execution_options`
Joining a Session into an External Transaction (such as for test suites)
========================================================================
-If a :class:`.Connection` is being used which is already in a transactional
+If a :class:`_engine.Connection` is being used which is already in a transactional
state (i.e. has a :class:`.Transaction` established), a :class:`.Session` can
be made to participate within that transaction by just binding the
-:class:`.Session` to that :class:`.Connection`. The usual rationale for this
+:class:`.Session` to that :class:`_engine.Connection`. The usual rationale for this
is a test suite that allows ORM code to work freely with a :class:`.Session`,
including the ability to call :meth:`.Session.commit`, where afterwards the
entire database interaction is rolled back::
Above, we issue :meth:`.Session.commit` as well as
:meth:`.Transaction.rollback`. This is an example of where we take advantage
-of the :class:`.Connection` object's ability to maintain *subtransactions*, or
+of the :class:`_engine.Connection` object's ability to maintain *subtransactions*, or
nested begin/commit-or-rollback pairs where only the outermost begin/commit
pair actually commits the transaction, or if the outermost block rolls back,
everything is rolled back.
"SQL" links to see what's being generated.
The return value of :func:`.create_engine` is an instance of
-:class:`.Engine`, and it represents the core interface to the
+:class:`_engine.Engine`, and it represents the core interface to the
database, adapted through a :term:`dialect` that handles the details
of the database and :term:`DBAPI` in use. In this case the SQLite
dialect will interpret instructions to the Python built-in ``sqlite3``
.. sidebar:: Lazy Connecting
- The :class:`.Engine`, when first returned by :func:`.create_engine`,
+ The :class:`_engine.Engine`, when first returned by :func:`.create_engine`,
has not actually tried to connect to the database yet; that happens
only the first time it is asked to perform a task against the database.
-The first time a method like :meth:`.Engine.execute` or :meth:`.Engine.connect`
-is called, the :class:`.Engine` establishes a real :term:`DBAPI` connection to the
+The first time a method like :meth:`_engine.Engine.execute` or :meth:`_engine.Engine.connect`
+is called, the :class:`_engine.Engine` establishes a real :term:`DBAPI` connection to the
database, which is then used to emit the SQL. When using the ORM, we typically
-don't use the :class:`.Engine` directly once created; instead, it's used
+don't use the :class:`_engine.Engine` directly once created; instead, it's used
behind the scenes by the ORM as we'll see shortly.
.. seealso::
A class using Declarative at a minimum
needs a ``__tablename__`` attribute, and at least one
-:class:`.Column` which is part of a primary key [#]_. SQLAlchemy never makes any
+:class:`_schema.Column` which is part of a primary key [#]_. SQLAlchemy never makes any
assumptions by itself about the table to which
a class refers, including that it has no built-in conventions for names,
datatypes, or constraints. But this doesn't mean
own automated conventions using helper functions and mixin classes, which
is described in detail at :ref:`declarative_mixins`.
-When our class is constructed, Declarative replaces all the :class:`.Column`
+When our class is constructed, Declarative replaces all the :class:`_schema.Column`
objects with special Python accessors known as :term:`descriptors`; this is a
process known as :term:`instrumentation`. The "instrumented" mapped class
will provide us with the means to refer to our table in a SQL context as well
With our ``User`` class constructed via the Declarative system, we have defined information about
our table, known as :term:`table metadata`. The object used by SQLAlchemy to represent
-this information for a specific table is called the :class:`.Table` object, and here Declarative has made
+this information for a specific table is called the :class:`_schema.Table` object, and here Declarative has made
one for us. We can see this object by inspecting the ``__table__`` attribute::
>>> User.__table__ # doctest: +NORMALIZE_WHITESPACE
The Declarative system, though highly recommended,
is not required in order to use SQLAlchemy's ORM.
Outside of Declarative, any
- plain Python class can be mapped to any :class:`.Table`
+ plain Python class can be mapped to any :class:`_schema.Table`
using the :func:`.mapper` function directly; this
less common usage is described at :ref:`classical_mapping`.
When we declared our class, Declarative used a Python metaclass in order to
perform additional activities once the class declaration was complete; within
-this phase, it then created a :class:`.Table` object according to our
+this phase, it then created a :class:`_schema.Table` object according to our
specifications, and associated it with the class by constructing
-a :class:`.Mapper` object. This object is a behind-the-scenes object we normally
+a :class:`_orm.Mapper` object. This object is a behind-the-scenes object we normally
don't need to deal with directly (though it can provide plenty of information
about our mapping when we need it).
-The :class:`.Table` object is a member of a larger collection
-known as :class:`.MetaData`. When using Declarative,
+The :class:`_schema.Table` object is a member of a larger collection
+known as :class:`_schema.MetaData`. When using Declarative,
this object is available using the ``.metadata``
attribute of our declarative base class.
-The :class:`.MetaData`
+The :class:`_schema.MetaData`
is a :term:`registry` which includes the ability to emit a limited set
of schema generation commands to the database. As our SQLite database
-does not actually have a ``users`` table present, we can use :class:`.MetaData`
+does not actually have a ``users`` table present, we can use :class:`_schema.MetaData`
to issue CREATE TABLE statements to the database for all tables that don't yet exist.
-Below, we call the :meth:`.MetaData.create_all` method, passing in our :class:`.Engine`
+Below, we call the :meth:`_schema.MetaData.create_all` method, passing in our :class:`_engine.Engine`
as a source of database connectivity. We will see that special commands are
first emitted to check for the presence of the ``users`` table, and following that
the actual ``CREATE TABLE`` statement:
>>> session = Session()
The above :class:`~sqlalchemy.orm.session.Session` is associated with our
-SQLite-enabled :class:`.Engine`, but it hasn't opened any connections yet. When it's first
+SQLite-enabled :class:`_engine.Engine`, but it hasn't opened any connections yet. When it's first
used, it retrieves a connection from a pool of connections maintained by the
-:class:`.Engine`, and holds onto it until we commit all changes and/or close the
+:class:`_engine.Engine`, and holds onto it until we commit all changes and/or close the
session object.
<User(name='fred', fullname='Fred Flintstone', nickname='freddy')> fred
You can control the names of individual column expressions using the
-:meth:`~.ColumnElement.label` construct, which is available from
-any :class:`.ColumnElement`-derived object, as well as any class attribute which
+:meth:`_expression.ColumnElement.label` construct, which is available from
+any :class:`_expression.ColumnElement`-derived object, as well as any class attribute which
is mapped to one (such as ``User.name``):
.. sourcecode:: python+sql
Returning Lists and Scalars
---------------------------
-A number of methods on :class:`.Query`
+A number of methods on :class:`_query.Query`
immediately issue SQL and return a value containing loaded
database results. Here's a brief tour:
-* :meth:`~.Query.all()` returns a list:
+* :meth:`_query.Query.all()` returns a list:
.. sourcecode:: python+sql
.. warning::
- When the :class:`.Query` object returns lists of ORM-mapped objects
+ When the :class:`_query.Query` object returns lists of ORM-mapped objects
such as the ``User`` object above, the entries are **deduplicated**
based on primary key, as the results are interpreted from the SQL
result set. That is, if SQL query returns a row with ``id=7`` twice,
:ref:`faq_query_deduplicating`
-* :meth:`~.Query.first()` applies a limit of one and returns
+* :meth:`_query.Query.first()` applies a limit of one and returns
the first result as a scalar:
.. sourcecode:: python+sql
('%ed', 1, 0)
{stop}<User(name='ed', fullname='Ed Jones', nickname='eddie')>
-* :meth:`~.Query.one()` fully fetches all rows, and if not
+* :meth:`_query.Query.one()` fully fetches all rows, and if not
exactly one object identity or composite row is present in the result, raises
an error. With multiple rows found:
...
NoResultFound: No row was found for one()
- The :meth:`~.Query.one` method is great for systems that expect to handle
+ The :meth:`_query.Query.one` method is great for systems that expect to handle
"no items found" versus "multiple items found" differently; such as a RESTful
web service, which may want to raise a "404 not found" when no results are found,
but raise an application error when multiple results are found.
-* :meth:`~.Query.one_or_none` is like :meth:`~.Query.one`, except that if no
+* :meth:`_query.Query.one_or_none` is like :meth:`_query.Query.one`, except that if no
results are found, it doesn't raise an error; it just returns ``None``. Like
- :meth:`~.Query.one`, however, it does raise an error if multiple results are
+ :meth:`_query.Query.one`, however, it does raise an error if multiple results are
found.
-* :meth:`~.Query.scalar` invokes the :meth:`~.Query.one` method, and upon
+* :meth:`_query.Query.scalar` invokes the :meth:`_query.Query.one` method, and upon
success returns the first column of the row:
.. sourcecode:: python+sql
Literal strings can be used flexibly with
:class:`~sqlalchemy.orm.query.Query`, by specifying their use
-with the :func:`~.expression.text` construct, which is accepted
+with the :func:`_expression.text` construct, which is accepted
by most applicable methods. For example,
:meth:`~sqlalchemy.orm.query.Query.filter()` and
:meth:`~sqlalchemy.orm.query.Query.order_by()`:
(224, 'fred')
{stop}<User(name='fred', fullname='Fred Flintstone', nickname='freddy')>
-To use an entirely string-based statement, a :func:`.text` construct
+To use an entirely string-based statement, a :func:`_expression.text` construct
representing a complete statement can be passed to
:meth:`~sqlalchemy.orm.query.Query.from_statement()`. Without further
specification, the ORM will match columns in the ORM mapping to the result
For better targeting of mapped columns to a textual SELECT, as well as to
match on a specific subset of columns in arbitrary order, individual mapped
-columns are passed in the desired order to :meth:`.TextClause.columns`:
+columns are passed in the desired order to :meth:`_expression.TextClause.columns`:
.. sourcecode:: python+sql
('ed',)
{stop}[<User(name='ed', fullname='Ed Jones', nickname='eddie')>]
-When selecting from a :func:`~.expression.text` construct, the :class:`.Query`
+When selecting from a :func:`_expression.text` construct, the :class:`_query.Query`
may still specify what columns and entities are to be returned; instead of
``query(User)`` we can also ask for the columns individually, as in
any other case:
.. seealso::
- :ref:`sqlexpression_text` - The :func:`.text` construct explained
+ :ref:`sqlexpression_text` - The :func:`_expression.text` construct explained
from the perspective of Core-only queries.
Counting
.. sidebar:: Counting on ``count()``
- :meth:`.Query.count` used to be a very complicated method
+ :meth:`_query.Query.count` used to be a very complicated method
when it would try to guess whether or not a subquery was needed
around the
existing query, and in some exotic cases it wouldn't do the right thing.
and always returns the right answer. Use ``func.count()`` if a
particular statement absolutely cannot tolerate the subquery being present.
-The :meth:`~.Query.count()` method is used to determine
+The :meth:`_query.Query.count()` method is used to determine
how many rows the SQL statement would return. Looking
at the generated SQL above, SQLAlchemy always places whatever it is we are
querying into a subquery, then counts the rows from that. In some cases
('*',)
{stop}4
-The usage of :meth:`~.Query.select_from` can be removed if we express the count in terms
+The usage of :meth:`_query.Query.select_from` can be removed if we express the count in terms
of the ``User`` primary key directly:
.. sourcecode:: python+sql
>>> User.addresses = relationship(
... "Address", order_by=Address.id, back_populates="user")
-The above class introduces the :class:`.ForeignKey` construct, which is a
-directive applied to :class:`.Column` that indicates that values in this
+The above class introduces the :class:`_schema.ForeignKey` construct, which is a
+directive applied to :class:`_schema.Column` that indicates that values in this
column should be :term:`constrained` to be values present in the named remote
column. This is a core feature of relational databases, and is the "glue" that
transforms an otherwise unconnected collection of tables to have rich
-overlapping relationships. The :class:`.ForeignKey` above expresses that
+overlapping relationships. The :class:`_schema.ForeignKey` above expresses that
values in the ``addresses.user_id`` column should be constrained to
those values in the ``users.id`` column, i.e. its primary key.
-A second directive, known as :func:`.relationship`,
+A second directive, known as :func:`_orm.relationship`,
tells the ORM that the ``Address`` class itself should be linked
to the ``User`` class, using the attribute ``Address.user``.
-:func:`.relationship` uses the foreign key
+:func:`_orm.relationship` uses the foreign key
relationships between the two tables to determine the nature of
this linkage, determining that ``Address.user`` will be :term:`many to one`.
-An additional :func:`.relationship` directive is placed on the
+An additional :func:`_orm.relationship` directive is placed on the
``User`` mapped class under the attribute ``User.addresses``. In both
-:func:`.relationship` directives, the parameter
-:paramref:`.relationship.back_populates` is assigned to refer to the
-complementary attribute names; by doing so, each :func:`.relationship`
+:func:`_orm.relationship` directives, the parameter
+:paramref:`_orm.relationship.back_populates` is assigned to refer to the
+complementary attribute names; by doing so, each :func:`_orm.relationship`
can make intelligent decision about the same relationship as expressed
in reverse; on one side, ``Address.user`` refers to a ``User`` instance,
and on the other side, ``User.addresses`` refers to a list of
.. note::
- The :paramref:`.relationship.back_populates` parameter is a newer
+ The :paramref:`_orm.relationship.back_populates` parameter is a newer
version of a very common SQLAlchemy feature called
- :paramref:`.relationship.backref`. The :paramref:`.relationship.backref`
+ :paramref:`_orm.relationship.backref`. The :paramref:`_orm.relationship.backref`
parameter hasn't gone anywhere and will always remain available!
- The :paramref:`.relationship.back_populates` is the same thing, except
+ The :paramref:`_orm.relationship.back_populates` is the same thing, except
a little more verbose and easier to manipulate. For an overview
of the entire topic, see the section :ref:`relationships_backref`.
The reverse side of a many-to-one relationship is always :term:`one to many`.
-A full catalog of available :func:`.relationship` configurations
+A full catalog of available :func:`_orm.relationship` configurations
is at :ref:`relationship_patterns`.
The two complementing relationships ``Address.user`` and ``User.addresses``
feature of the SQLAlchemy ORM. The section :ref:`relationships_backref`
discusses the "backref" feature in detail.
-Arguments to :func:`.relationship` which concern the remote class
+Arguments to :func:`_orm.relationship` which concern the remote class
can be specified using strings, assuming the Declarative system is in
use. Once all mappings are complete, these strings are evaluated
as Python expressions in order to produce the actual argument, in the
this evaluation include, among other things, the names of all classes
which have been created in terms of the declared base.
-See the docstring for :func:`.relationship` for more detail on argument style.
+See the docstring for :func:`_orm.relationship` for more detail on argument style.
.. topic:: Did you know ?
Querying with Joins
===================
-Now that we have two tables, we can show some more features of :class:`.Query`,
+Now that we have two tables, we can show some more features of :class:`_query.Query`,
specifically how to create queries that deal with both tables at the same time.
The `Wikipedia page on SQL JOIN
<http://en.wikipedia.org/wiki/Join_%28SQL%29>`_ offers a good introduction to
join techniques, several of which we'll illustrate here.
To construct a simple implicit join between ``User`` and ``Address``,
-we can use :meth:`.Query.filter()` to equate their related columns together.
+we can use :meth:`_query.Query.filter()` to equate their related columns together.
Below we load the ``User`` and ``Address`` entities at once using this method:
.. sourcecode:: python+sql
<Address(email_address='jack@google.com')>
The actual SQL JOIN syntax, on the other hand, is most easily achieved
-using the :meth:`.Query.join` method:
+using the :meth:`_query.Query.join` method:
.. sourcecode:: python+sql
('jack@google.com',)
{stop}[<User(name='jack', fullname='Jack Bean', nickname='gjffdd')>]
-:meth:`.Query.join` knows how to join between ``User``
+:meth:`_query.Query.join` knows how to join between ``User``
and ``Address`` because there's only one foreign key between them. If there
-were no foreign keys, or several, :meth:`.Query.join`
+were no foreign keys, or several, :meth:`_query.Query.join`
works better when one of the following forms are used::
query.join(Address, User.id==Address.user_id) # explicit condition
query.join('addresses') # same, using a string
As you would expect, the same idea is used for "outer" joins, using the
-:meth:`~.Query.outerjoin` function::
+:meth:`_query.Query.outerjoin` function::
query.outerjoin(User.addresses) # LEFT OUTER JOIN
-The reference documentation for :meth:`~.Query.join` contains detailed information
-and examples of the calling styles accepted by this method; :meth:`~.Query.join`
+The reference documentation for :meth:`_query.Query.join` contains detailed information
+and examples of the calling styles accepted by this method; :meth:`_query.Query.join`
is an important method at the center of usage for any SQL-fluent application.
-.. topic:: What does :class:`.Query` select from if there's multiple entities?
+.. topic:: What does :class:`_query.Query` select from if there's multiple entities?
- The :meth:`.Query.join` method will **typically join from the leftmost
+ The :meth:`_query.Query.join` method will **typically join from the leftmost
item** in the list of entities, when the ON clause is omitted, or if the
ON clause is a plain SQL expression. To control the first entity in the list
- of JOINs, use the :meth:`.Query.select_from` method::
+ of JOINs, use the :meth:`_query.Query.select_from` method::
query = session.query(User, Address).select_from(Address).join(User)
Using the :class:`~sqlalchemy.orm.query.Query`, we build a statement like this
from the inside out. The ``statement`` accessor returns a SQL expression
representing the statement generated by a particular
-:class:`~sqlalchemy.orm.query.Query` - this is an instance of a :func:`~.expression.select`
+:class:`~sqlalchemy.orm.query.Query` - this is an instance of a :func:`_expression.select`
construct, which are described in :ref:`sqlexpression_toplevel`::
>>> from sqlalchemy.sql import func
query.filter(Address.user.has(name='ed'))
-* :meth:`.Query.with_parent` (used for any relationship)::
+* :meth:`_query.Query.with_parent` (used for any relationship)::
session.query(Address).with_parent(someuser, 'addresses')
we can apply an :term:`eager load` to the query operation. SQLAlchemy
offers three types of eager loading, two of which are automatic, and a third
which involves custom criterion. All three are usually invoked via functions known
-as query options which give additional instructions to the :class:`.Query` on how
-we would like various attributes to be loaded, via the :meth:`.Query.options` method.
+as query options which give additional instructions to the :class:`_query.Query` on how
+we would like various attributes to be loaded, via the :meth:`_query.Query.options` method.
Selectin Load
-------------
In this case we'd like to indicate that ``User.addresses`` should load eagerly.
A good choice for loading a set of objects as well as their related collections
-is the :func:`.orm.selectinload` option, which emits a second SELECT statement
+is the :func:`_orm.selectinload` option, which emits a second SELECT statement
that fully loads the collections associated with the results just loaded.
The name "selectin" originates from the fact that the SELECT statement
uses an IN clause in order to locate related rows for multiple objects
-----------
The other automatic eager loading function is more well known and is called
-:func:`.orm.joinedload`. This style of loading emits a JOIN, by default
+:func:`_orm.joinedload`. This style of loading emits a JOIN, by default
a LEFT OUTER JOIN, so that the lead object as well as the related object
or collection is loaded in one step. We illustrate loading the same
``addresses`` collection in this way - note that even though the ``User.addresses``
[<Address(email_address='jack@google.com')>, <Address(email_address='j25@yahoo.com')>]
Note that even though the OUTER JOIN resulted in two rows, we still only got
-one instance of ``User`` back. This is because :class:`.Query` applies a "uniquing"
+one instance of ``User`` back. This is because :class:`_query.Query` applies a "uniquing"
strategy, based on object identity, to the returned entities. This is specifically
so that joined eager loading can be applied without affecting the query results.
-While :func:`.joinedload` has been around for a long time, :func:`.selectinload`
+While :func:`_orm.joinedload` has been around for a long time, :func:`.selectinload`
is a newer form of eager loading. :func:`.selectinload` tends to be more appropriate
-for loading related collections while :func:`.joinedload` tends to be better suited
+for loading related collections while :func:`_orm.joinedload` tends to be better suited
for many-to-one relationships, due to the fact that only one row is loaded
for both the lead and the related object. Another form of loading,
:func:`.subqueryload`, also exists, which can be used in place of
.. topic:: ``joinedload()`` is not a replacement for ``join()``
- The join created by :func:`.joinedload` is anonymously aliased such that
- it **does not affect the query results**. An :meth:`.Query.order_by`
- or :meth:`.Query.filter` call **cannot** reference these aliased
+ The join created by :func:`_orm.joinedload` is anonymously aliased such that
+ it **does not affect the query results**. An :meth:`_query.Query.order_by`
+ or :meth:`_query.Query.filter` call **cannot** reference these aliased
tables - so-called "user space" joins are constructed using
- :meth:`.Query.join`. The rationale for this is that :func:`.joinedload` is only
+ :meth:`_query.Query.join`. The rationale for this is that :func:`_orm.joinedload` is only
applied in order to affect how related objects or collections are loaded
as an optimizing detail - it can be added or removed with no impact
on actual results. See the section :ref:`zen_of_eager_loading` for
A third style of eager loading is when we are constructing a JOIN explicitly in
order to locate the primary rows, and would like to additionally apply the extra
table to a related object or collection on the primary object. This feature
-is supplied via the :func:`.orm.contains_eager` function, and is most
+is supplied via the :func:`_orm.contains_eager` function, and is most
typically useful for pre-loading the many-to-one object on a query that needs
to filter on that same object. Below we illustrate loading an ``Address``
row as well as the related ``User`` object, filtering on the ``User`` named
-"jack" and using :func:`.orm.contains_eager` to apply the "user" columns to the ``Address.user``
+"jack" and using :func:`_orm.contains_eager` to apply the "user" columns to the ``Address.user``
attribute:
.. sourcecode:: python+sql
... def __repr__(self):
... return "<Address(email_address='%s')>" % self.email_address
-Now when we load the user ``jack`` (below using :meth:`~.Query.get`,
+Now when we load the user ``jack`` (below using :meth:`_query.Query.get`,
which loads by primary key), removing an address from the
corresponding ``addresses`` collection will result in that ``Address``
being deleted:
We'll make our application a blog application, where users can write
``BlogPost`` items, which have ``Keyword`` items associated with them.
-For a plain many-to-many, we need to create an un-mapped :class:`.Table` construct
+For a plain many-to-many, we need to create an un-mapped :class:`_schema.Table` construct
to serve as the association table. This looks like the following::
>>> from sqlalchemy import Table, Text
... Column('keyword_id', ForeignKey('keywords.id'), primary_key=True)
... )
-Above, we can see declaring a :class:`.Table` directly is a little different
-than declaring a mapped class. :class:`.Table` is a constructor function, so
-each individual :class:`.Column` argument is separated by a comma. The
-:class:`.Column` object is also given its name explicitly, rather than it being
+Above, we can see declaring a :class:`_schema.Table` directly is a little different
+than declaring a mapped class. :class:`_schema.Table` is a constructor function, so
+each individual :class:`_schema.Column` argument is separated by a comma. The
+:class:`_schema.Column` object is also given its name explicitly, rather than it being
taken from an assigned attribute name.
Next we define ``BlogPost`` and ``Keyword``, using complementary
-:func:`.relationship` constructs, each referring to the ``post_keywords``
+:func:`_orm.relationship` constructs, each referring to the ``post_keywords``
table as an association table::
>>> class BlogPost(Base):
Configuring a Version Counter
=============================
-The :class:`.Mapper` supports management of a :term:`version id column`, which
+The :class:`_orm.Mapper` supports management of a :term:`version id column`, which
is a single table column that increments or otherwise updates its value
each time an ``UPDATE`` to the mapped table occurs. This value is checked each
time the ORM emits an ``UPDATE`` or ``DELETE`` against the row to ensure that
record of an object, the feature only applies to the :meth:`.Session.flush`
process, where the ORM flushes individual in-memory rows to the database.
It does **not** take effect when performing
- a multirow UPDATE or DELETE using :meth:`.Query.update` or :meth:`.Query.delete`
+ a multirow UPDATE or DELETE using :meth:`_query.Query.update` or :meth:`_query.Query.delete`
methods, as these methods only emit an UPDATE or DELETE statement but otherwise
do not have direct access to the contents of those rows being affected.
+++ /dev/null
-.MetaData _schema.MetaData
-.ForeignKey _schema.ForeignKey
-.ForeignKeyConstraint _schema.ForeignKeyConstraint
-.PoolEvents _events.PoolEvents
-.DisconnectionError _exc.DisconnectionError
-.SADeprecationWarning _exc.SADeprecationWarning
-.Engine _engine.Engine
-.Pool _pool.Pool
-.future _future
-.inspect _sa.inspect
-.Inspector _reflection.Inspector
-.orm _orm
-.Mapper _orm.Mapper
-.engine _engine
-.JSON _types.JSON
-.postgresql _postgresql
-.types _types
-._mysql _mysql
-.sqlite _sqlite
-.array_agg _functions.array_agg
-.TIMESTAMP _types.TIMESTAMP
-.JSONB _postgresql.JSONB
-.ARRAY _types.ARRAY
-.mssql _mssql
-.sqltypes _types
-.functions _functions
-.INTERVAL _postgresql.INTERVAL
-.INTERVAL _oracle.INTERVAL
-.oracle _oracle
-.NCHAR _types.NCHAR
-.Query _query.Query
-.relationship _orm.relationship
-.FromClause _expression.FromClause
-.join _expression.join
-.SelectBase _expression.SelectBase
-.Load _orm.Load
-.joinedload _orm.joinedload
-.sql _expression
-.sql.expression _expression
-.INTEGER _types.INTEGER
-.VARBINARY _types.VARBINARY
-.joinedload_all _orm.joinedload_all
-.Insert _expression.Insert
-.Update _expression.Update
-.Delete _expression.Delete
-.insert _expression.insert
-.update _expression.update
-.delete _expression.delete
-.select _expression.select
-.expression _expression
-.future _future.Subquery _expression.Subquery
-.Select _expression.Select
-.ReturnsRows _expression.ReturnsRows
-.ColumnCollection _expression.ColumnCollection
-.ColumnElement _expression.ColumnElement
-.Selectable expression.Selectable
-.Lateral _expression.Lateral
-.HasPrefixes _expression.HasPrefixes
-.prefix_with _expression.HasPrefixes.prefix_with
-.ClauseElement _expression.ClauseElement
-.HasSuffixes _expression.HasSuffixes
-.suffix_with _expression.HasSuffixes.suffix_with
-.Table _schema.Table
-.Join _expression.Join
-.Alias _expression.Alias
-.TableSample _expression.TableSample
-.CTE _expression.CTE
-.HasCte _expression.HasCTE
-.HasCTE _expression.HasCTE
-.CompoundSelect _selectable.CompoundSelect
-.TextualSelect _expression.TextualSelect
-.TableClause _expression.TableClause
-.schema _schema
-.Values _expression.Values
-.column _expression.column
-.GenerativeSelect _expression.GenerativeSelect
-.Column _schema.Column
-.union _expression.union
-.union_all _expression.union_all
-.intersect _expression.intersect
-.intersect_all _expression.intersect_all
-.except _expression.except
-.except_all _expression.except_all
-.Text _expression.TextClause
-.text _expression.text
-.literal_column _expression.literal_column
-.Connection _engine.Connection
-.Engine _engine.Engine
-.apply_labels _expression.Select.apply_labels
-.BooleanClauseList _expression.BooleanClauseList
-.ScalarSelect _expression.ScalarSelect
-.Exists _expression.Exists
-.TextClause _expression.TextClause
of Firebird, and setting this flag to False will also cause the
SQLAlchemy ORM to ignore its usage. The behavior can also be controlled on a
per-execution basis using the ``enable_rowcount`` option with
- :meth:`.Connection.execution_options`::
+ :meth:`_engine.Connection.execution_options`::
conn = engine.connect().execution_options(enable_rowcount=True)
r = conn.execute(stmt)
``IDENTITY`` construct, which can be placed on any single integer column in a
table. SQLAlchemy considers ``IDENTITY`` within its default "autoincrement"
behavior for an integer primary key column, described at
-:paramref:`.Column.autoincrement`. This means that by default, the first
-integer primary key column in a :class:`.Table` will be considered to be the
+:paramref:`_schema.Column.autoincrement`. This means that by default,
+the first
+integer primary key column in a :class:`_schema.Table`
+will be considered to be the
identity column and will generate DDL as such::
from sqlalchemy import Table, MetaData, Column, Integer
)
For the case where this default generation of ``IDENTITY`` is not desired,
-specify ``False`` for the :paramref:`.Column.autoincrement` flag,
+specify ``False`` for the :paramref:`_schema.Column.autoincrement` flag,
on the first integer primary key column::
m = MetaData()
m.create_all(engine)
To add the ``IDENTITY`` keyword to a non-primary key column, specify
-``True`` for the :paramref:`.Column.autoincrement` flag on the desired
-:class:`.Column` object, and ensure that :paramref:`.Column.autoincrement`
+``True`` for the :paramref:`_schema.Column.autoincrement` flag on the desired
+:class:`_schema.Column` object, and ensure that
+:paramref:`_schema.Column.autoincrement`
is set to ``False`` on any integer primary key column::
m = MetaData()
m.create_all(engine)
.. versionchanged:: 1.3 Added ``mssql_identity_start`` and
- ``mssql_identity_increment`` parameters to :class:`.Column`. These replace
+ ``mssql_identity_increment`` parameters to :class:`_schema.Column`.
+ These replace
the use of the :class:`.Sequence` object in order to specify these values.
.. deprecated:: 1.3
marked with IDENTITY will be rejected by SQL Server. In order for the
value to be accepted, a session-level option "SET IDENTITY_INSERT" must be
enabled. The SQLAlchemy SQL Server dialect will perform this operation
- automatically when using a core :class:`~.sql.expression.Insert` construct; if the
+ automatically when using a core :class:`_expression.Insert`
+ construct; if the
execution specifies a value for the IDENTITY column, the "IDENTITY_INSERT"
option will be enabled for the span of that statement's invocation.However,
this scenario is not high performing and should not be relied upon for
Specific control over the "start" and "increment" values for
the ``IDENTITY`` generator are provided using the
``mssql_identity_start`` and ``mssql_identity_increment`` parameters
-passed to the :class:`.Column` object::
+passed to the :class:`_schema.Column` object::
from sqlalchemy import Table, Integer, Column
Column('name', String(20))
)
-The CREATE TABLE for the above :class:`.Table` object would be:
+The CREATE TABLE for the above :class:`_schema.Table` object would be:
.. sourcecode:: sql
.. versionchanged:: 1.3 The ``mssql_identity_start`` and
``mssql_identity_increment`` parameters are now used to affect the
- ``IDENTITY`` generator for a :class:`.Column` under SQL Server.
+ ``IDENTITY`` generator for a :class:`_schema.Column` under SQL Server.
Previously, the :class:`.Sequence` object was used. As SQL Server now
supports real sequences as a separate construct, :class:`.Sequence` will be
functional in the normal way in a future SQLAlchemy version.
A table that contains an ``IDENTITY`` column will prohibit an INSERT statement
that refers to the identity column explicitly. The SQLAlchemy dialect will
-detect when an INSERT construct, created using a core :func:`~.sql.expression.insert`
+detect when an INSERT construct, created using a core
+:func:`_expression.insert`
construct (not a plain string SQL), refers to the identity column, and
in this case will emit ``SET IDENTITY_INSERT ON`` prior to the insert
statement proceeding, and ``SET IDENTITY_INSERT OFF`` subsequent to the
-------------------------
SQL Server supports the special string "MAX" within the
-:class:`.sqltypes.VARCHAR` and :class:`.sqltypes.NVARCHAR` datatypes,
+:class:`_types.VARCHAR` and :class:`_types.NVARCHAR` datatypes,
to indicate "maximum length possible". The dialect currently handles this as
a length of "None" in the base type, rather than supplying a
dialect-specific version of these types, so that a base type
from sqlalchemy import VARCHAR
Column('login', VARCHAR(32, collation='Latin1_General_CI_AS'))
-When such a column is associated with a :class:`.Table`, the
+When such a column is associated with a :class:`_schema.Table`, the
CREATE TABLE statement for this column will yield::
login VARCHAR(32) COLLATE Latin1_General_CI_AS NULL
accepted by :func:`.create_engine`,
as well as the :paramref:`.Connection.execution_options.isolation_level`
argument as passed to
-:meth:`.Connection.execution_options`. This feature works by issuing the
+:meth:`_engine.Connection.execution_options`.
+This feature works by issuing the
command ``SET TRANSACTION ISOLATION LEVEL <level>`` for
each new connection.
`SQL Server 2012/2014 Documentation <http://technet.microsoft.com/en-us/library/ms187993.aspx>`_,
the ``NTEXT``, ``TEXT`` and ``IMAGE`` datatypes are to be removed from SQL
Server in a future release. SQLAlchemy normally relates these types to the
-:class:`.UnicodeText`, :class:`.Text` and :class:`.LargeBinary` datatypes.
+:class:`.UnicodeText`, :class:`_expression.TextClause` and
+:class:`.LargeBinary` datatypes.
In order to accommodate this change, a new flag ``deprecate_large_types``
is added to the dialect, which will be automatically set based on detection
of the server version in use, if not otherwise set by the user. The
behavior of this flag is as follows:
-* When this flag is ``True``, the :class:`.UnicodeText`, :class:`.Text` and
+* When this flag is ``True``, the :class:`.UnicodeText`,
+ :class:`_expression.TextClause` and
:class:`.LargeBinary` datatypes, when used to render DDL, will render the
types ``NVARCHAR(max)``, ``VARCHAR(max)``, and ``VARBINARY(max)``,
respectively. This is a new behavior as of the addition of this flag.
-* When this flag is ``False``, the :class:`.UnicodeText`, :class:`.Text` and
+* When this flag is ``False``, the :class:`.UnicodeText`,
+ :class:`_expression.TextClause` and
:class:`.LargeBinary` datatypes, when used to render DDL, will render the
types ``NTEXT``, ``TEXT``, and ``IMAGE``,
respectively. This is the long-standing behavior of these types.
* Complete control over whether the "old" or "new" types are rendered is
available in all SQLAlchemy versions by using the UPPERCASE type objects
- instead: :class:`.types.NVARCHAR`, :class:`.types.VARCHAR`,
- :class:`.types.VARBINARY`, :class:`.types.TEXT`, :class:`.mssql.NTEXT`,
- :class:`.mssql.IMAGE` will always remain fixed and always output exactly that
+ instead: :class:`_types.NVARCHAR`, :class:`_types.VARCHAR`,
+ :class:`_types.VARBINARY`, :class:`_types.TEXT`, :class:`_mssql.NTEXT`,
+ :class:`_mssql.IMAGE`
+ will always remain fixed and always output exactly that
type.
.. versionadded:: 1.0.0
SQL Server schemas sometimes require multiple parts to their "schema"
qualifier, that is, including the database name and owner name as separate
tokens, such as ``mydatabase.dbo.some_table``. These multipart names can be set
-at once using the :paramref:`.Table.schema` argument of :class:`.Table`::
+at once using the :paramref:`_schema.Table.schema` argument of
+:class:`_schema.Table`::
Table(
"some_table", metadata,
server side defaults. MS-SQL does not
allow the usage of OUTPUT INSERTED on tables that have triggers.
To disable the usage of OUTPUT INSERTED on a per-table basis,
-specify ``implicit_returning=False`` for each :class:`.Table`
+specify ``implicit_returning=False`` for each :class:`_schema.Table`
which has triggers::
Table('mytable', metadata,
warning will be emitted but the operation will proceed.
The use of OUTPUT INSERTED can be disabled by setting the
-:paramref:`.Table.implicit_returning` flag to ``False`` on a particular
-:class:`.Table`, which in declarative looks like::
+:paramref:`_schema.Table.implicit_returning` flag to ``False`` on a particular
+:class:`_schema.Table`, which in declarative looks like::
class MyTable(Base):
__tablename__ = 'mytable'
.. seealso::
- :class:`.mssql.ROWVERSION`
+ :class:`_mssql.ROWVERSION`
"""
The ROWVERSION datatype does **not** reflect (e.g. introspect) from the
database as itself; the returned datatype will be
- :class:`.mssql.TIMESTAMP`.
+ :class:`_mssql.TIMESTAMP`.
This is a read-only datatype that does not support INSERT of values.
.. seealso::
- :class:`.mssql.TIMESTAMP`
+ :class:`_mssql.TIMESTAMP`
"""
This type is present to support "deprecate_large_types" mode where
either ``VARBINARY(max)`` or IMAGE is rendered. Otherwise, this type
- object is redundant vs. :class:`.types.VARBINARY`.
+ object is redundant vs. :class:`_types.VARBINARY`.
.. versionadded:: 1.0.0
to ``InnoDB``. The ``InnoDB`` engine is typically preferred for its support
of transactions and foreign keys.
-A :class:`.Table` that is created in a MySQL database with a storage engine
+A :class:`_schema.Table`
+that is created in a MySQL database with a storage engine
of ``MyISAM`` will be essentially non-transactional, meaning any
INSERT/UPDATE/DELETE statement referring to this table will be invoked as
autocommit. It also will have no support for foreign key constraints; while
dialect-specific parameter :paramref:`.create_engine.isolation_level` accepted
by :func:`.create_engine`, as well as the
:paramref:`.Connection.execution_options.isolation_level` argument as passed to
-:meth:`.Connection.execution_options`. This feature works by issuing the
+:meth:`_engine.Connection.execution_options`.
+This feature works by issuing the
command ``SET SESSION TRANSACTION ISOLATION LEVEL <level>`` for each new
connection. For the special AUTOCOMMIT isolation level, DBAPI-specific
techniques are used.
)
You can disable this behavior by passing ``False`` to the
-:paramref:`~.Column.autoincrement` argument of :class:`.Column`. This flag
+:paramref:`_schema.Column.autoincrement` argument of :class:`_schema.Column`.
+This flag
can also be used to enable auto-increment on a secondary column in a
multi-column key for some storage engines::
backticks and the other using quotes, e.g. ```some_identifier``` vs.
``"some_identifier"``. All MySQL dialects detect which version
is in use by checking the value of ``sql_mode`` when a connection is first
-established with a particular :class:`.Engine`. This quoting style comes
+established with a particular :class:`_engine.Engine`.
+This quoting style comes
into play when rendering table and column names as well as when reflecting
existing database structures. The detection is entirely automatic and
no special configuration is needed to use either quoting style.
* INSERT..ON DUPLICATE KEY UPDATE: See
:ref:`mysql_insert_on_duplicate_key_update`
-* SELECT pragma, use :meth:`.Select.prefix_with` and :meth:`.Query.prefix_with`::
+* SELECT pragma, use :meth:`_expression.Select.prefix_with` and
+ :meth:`_query.Query.prefix_with`::
select(...).prefix_with(['HIGH_PRIORITY', 'SQL_SMALL_RESULT'])
update(..., mysql_limit=10)
-* optimizer hints, use :meth:`.Select.prefix_with` and :meth:`.Query.prefix_with`::
+* optimizer hints, use :meth:`_expression.Select.prefix_with` and
+ :meth:`_query.Query.prefix_with`::
select(...).prefix_with("/*+ NO_RANGE_OPTIMIZATION(t4 PRIMARY) */")
-* index hints, use :meth:`.Select.with_hint` and :meth:`.Query.with_hint`::
+* index hints, use :meth:`_expression.Select.with_hint` and
+ :meth:`_query.Query.with_hint`::
select(...).with_hint(some_table, "USE INDEX xyz")
keyword arguments passed to the
:meth:`~.mysql.Insert.on_duplicate_key_update`
given column key values (usually the name of the column, unless it
-specifies :paramref:`.Column.key`) as keys and literal or SQL expressions
+specifies :paramref:`_schema.Column.key`
+) as keys and literal or SQL expressions
as values::
on_duplicate_key_stmt = insert_stmt.on_duplicate_key_update(
as well as a list of 2-tuples, which will automatically provide
a parameter-ordered UPDATE statement in a manner similar to that described
-at :ref:`updates_order_parameters`. Unlike the :class:`.Update` object,
+at :ref:`updates_order_parameters`. Unlike the :class:`_expression.Update`
+object,
no special flag is needed to specify the intent since the argument form is
this context is unambiguous::
.. warning::
- The :meth:`.Insert.on_duplicate_key_update` method does **not** take into
+ The :meth:`_expression.Insert.on_duplicate_key_update`
+ method does **not** take into
account Python-side default UPDATE values or generation functions, e.g.
- e.g. those specified using :paramref:`.Column.onupdate`.
+ e.g. those specified using :paramref:`_schema.Column.onupdate`.
These values will not be exercised for an ON DUPLICATE KEY style of UPDATE,
unless they are manually specified explicitly in the parameters.
In order to refer to the proposed insertion row, the special alias
:attr:`~.mysql.Insert.inserted` is available as an attribute on
the :class:`.mysql.Insert` object; this object is a
-:class:`.ColumnCollection` which contains all columns of the target
+:class:`_expression.ColumnCollection` which contains all columns of the target
table::
from sqlalchemy.dialects.mysql import insert
MySQL does not support the foreign key arguments "DEFERRABLE", "INITIALLY",
or "MATCH". Using the ``deferrable`` or ``initially`` keyword argument with
-:class:`.ForeignKeyConstraint` or :class:`.ForeignKey` will have the effect of
+:class:`_schema.ForeignKeyConstraint` or :class:`_schema.ForeignKey`
+will have the effect of
these keywords being rendered in a DDL expression, which will then raise an
error on MySQL. In order to use these keywords on a foreign key while having
them ignored on a MySQL backend, use a custom compile rule::
.. versionchanged:: 0.9.0 - the MySQL backend no longer silently ignores
the ``deferrable`` or ``initially`` keyword arguments of
- :class:`.ForeignKeyConstraint` and :class:`.ForeignKey`.
+ :class:`_schema.ForeignKeyConstraint` and :class:`_schema.ForeignKey`.
The "MATCH" keyword is in fact more insidious, and is explicitly disallowed
by SQLAlchemy in conjunction with the MySQL backend. This argument is
.. versionadded:: 0.9.0 - the MySQL backend will raise a
:class:`.CompileError` when the ``match`` keyword is used with
- :class:`.ForeignKeyConstraint` or :class:`.ForeignKey`.
+ :class:`_schema.ForeignKeyConstraint` or :class:`_schema.ForeignKey`.
Reflection of Foreign Key Constraints
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
construct that is separate from a unique index; that is, the "UNIQUE"
constraint on MySQL is equivalent to creating a "UNIQUE INDEX".
-When reflecting these constructs, the :meth:`.Inspector.get_indexes`
-and the :meth:`.Inspector.get_unique_constraints` methods will **both**
+When reflecting these constructs, the
+:meth:`_reflection.Inspector.get_indexes`
+and the :meth:`_reflection.Inspector.get_unique_constraints`
+methods will **both**
return an entry for a UNIQUE index in MySQL. However, when performing
full table reflection using ``Table(..., autoload=True)``,
the :class:`.UniqueConstraint` construct is
-**not** part of the fully reflected :class:`.Table` construct under any
+**not** part of the fully reflected :class:`_schema.Table` construct under any
circumstances; this construct is always represented by a :class:`.Index`
-with the ``unique=True`` setting present in the :attr:`.Table.indexes`
+with the ``unique=True`` setting present in the :attr:`_schema.Table.indexes`
collection.
.. note::
- this usage is deprecated. :meth:`.Select.prefix_with`
+ this usage is deprecated. :meth:`_expression.Select.prefix_with`
should be used for special keywords at the start
of a SELECT.
This attribute provides all columns in this row to be referenceable
such that they will render within a ``VALUES()`` function inside the
ON DUPLICATE KEY UPDATE clause. The attribute is named ``.inserted``
- so as not to conflict with the existing :meth:`.Insert.values` method.
+ so as not to conflict with the existing
+ :meth:`_expression.Insert.values` method.
.. seealso::
:ref:`mysql_insert_on_duplicate_key_update` - example of how
- to use :attr:`.Insert.inserted`
+ to use :attr:`_expression.Insert.inserted`
"""
return self.inserted_alias.columns
.. warning:: This dictionary does **not** take into account
Python-specified default UPDATE values or generation functions,
- e.g. those specified using :paramref:`.Column.onupdate`.
+ e.g. those specified using :paramref:`_schema.Column.onupdate`.
These values will not be exercised for an ON DUPLICATE KEY UPDATE
style of UPDATE, unless values are manually specified here.
Passing a list of 2-tuples indicates that the parameter assignments
in the UPDATE clause should be ordered as sent, in a manner similar
- to that described for the :class:`.Update` construct overall
+ to that described for the :class:`_expression.Update`
+ construct overall
in :ref:`updates_order_parameters`::
insert().on_duplicate_key_update(
support JSON at the time of this writing.
The :class:`.mysql.JSON` type supports persistence of JSON values
- as well as the core index operations provided by :class:`.types.JSON`
+ as well as the core index operations provided by :class:`_types.JSON`
datatype, by adapting the operations to render the ``JSON_EXTRACT``
function at the database level.
explicit support for "READ COMMITTED". It is possible to emit a
"SET TRANSACTION" statement on a connection in order to use SERIALIZABLE
isolation, however the SQLAlchemy dialect will remain unaware of this setting,
-such as if the :meth:`.Connection.get_isolation_level` method is used;
+such as if the :meth:`_engine.Connection.get_isolation_level` method is used;
this method is hardcoded to return "READ COMMITTED" right now.
The AUTOCOMMIT isolation level is also supported by the cx_Oracle dialect.
When using reflection with Table objects, the dialect can optionally search
for tables indicated by synonyms, either in local or remote schemas or
accessed over DBLINK, by passing the flag ``oracle_resolve_synonyms=True`` as
-a keyword argument to the :class:`.Table` construct::
+a keyword argument to the :class:`_schema.Table` construct::
some_table = Table('some_table', autoload=True,
autoload_with=some_engine,
``@dblink``).
``oracle_resolve_synonyms`` is accepted wherever reflection arguments are
-accepted, including methods such as :meth:`.MetaData.reflect` and
-:meth:`.Inspector.get_columns`.
+accepted, including methods such as :meth:`_schema.MetaData.reflect` and
+:meth:`_reflection.Inspector.get_columns`.
If synonyms are not in use, this flag should be left disabled.
CHECK constraints, as well as indexes on tables.
Raw information regarding these constraints can be acquired using
-:meth:`.Inspector.get_foreign_keys`, :meth:`.Inspector.get_unique_constraints`,
-:meth:`.Inspector.get_check_constraints`, and :meth:`.Inspector.get_indexes`.
+:meth:`_reflection.Inspector.get_foreign_keys`,
+:meth:`_reflection.Inspector.get_unique_constraints`,
+:meth:`_reflection.Inspector.get_check_constraints`, and
+:meth:`_reflection.Inspector.get_indexes`.
.. versionchanged:: 1.2 The Oracle dialect can now reflect UNIQUE and
CHECK constraints.
-When using reflection at the :class:`.Table` level, the :class:`.Table`
+When using reflection at the :class:`_schema.Table` level, the
+:class:`_schema.Table`
will also include these constraints.
Note the following caveats:
-* When using the :meth:`.Inspector.get_check_constraints` method, Oracle
+* When using the :meth:`_reflection.Inspector.get_check_constraints` method,
+ Oracle
builds a special "IS NOT NULL" constraint for columns that specify
"NOT NULL". This constraint is **not** returned by default; to include
the "IS NOT NULL" constraints, pass the flag ``include_all=True``::
all_check_constraints = inspector.get_check_constraints(
"some_table", include_all=True)
-* in most cases, when reflecting a :class:`.Table`, a UNIQUE constraint will
+* in most cases, when reflecting a :class:`_schema.Table`,
+ a UNIQUE constraint will
**not** be available as a :class:`.UniqueConstraint` object, as Oracle
mirrors unique constraints with a UNIQUE index in most cases (the exception
seems to be when two or more unique constraints represent the same columns);
- the :class:`.Table` will instead represent these using :class:`.Index`
+ the :class:`_schema.Table` will instead represent these using
+ :class:`.Index`
with the ``unique=True`` flag set.
* Oracle creates an implicit index for the primary key of a table; this index
Table names with SYSTEM/SYSAUX tablespaces
-------------------------------------------
-The :meth:`.Inspector.get_table_names` and
-:meth:`.Inspector.get_temp_table_names`
+The :meth:`_reflection.Inspector.get_table_names` and
+:meth:`_reflection.Inspector.get_temp_table_names`
methods each return a list of table names for the current engine. These methods
are also part of the reflection which occurs within an operation such as
-:meth:`.MetaData.reflect`. By default, these operations exclude the ``SYSTEM``
+:meth:`_schema.MetaData.reflect`. By default,
+these operations exclude the ``SYSTEM``
and ``SYSAUX`` tablespaces from the operation. In order to change this, the
default list of tablespaces excluded can be changed at the engine level using
the ``exclude_tablespaces`` parameter::
Oracle has no datatype known as ``DATETIME``, it instead has only ``DATE``,
which can actually store a date and time value. For this reason, the Oracle
-dialect provides a type :class:`.oracle.DATE` which is a subclass of
+dialect provides a type :class:`_oracle.DATE` which is a subclass of
:class:`.DateTime`. This type has no special behavior, and is only
present as a "marker" for this type; additionally, when a database column
is reflected and the type is reported as ``DATE``, the time-supporting
-:class:`.oracle.DATE` type is used.
+:class:`_oracle.DATE` type is used.
-.. versionchanged:: 0.9.4 Added :class:`.oracle.DATE` to subclass
+.. versionchanged:: 0.9.4 Added :class:`_oracle.DATE` to subclass
:class:`.DateTime`. This is a change as previous versions
- would reflect a ``DATE`` column as :class:`.types.DATE`, which subclasses
+ would reflect a ``DATE`` column as :class:`_types.DATE`, which subclasses
:class:`.Date`. The only significance here is for schemes that are
examining the type of column for use in special Python translations or
for migrating schemas to other database backends.
-------------------------
The CREATE TABLE phrase supports the following options with Oracle
-in conjunction with the :class:`.Table` construct:
+in conjunction with the :class:`_schema.Table` construct:
* ``ON COMMIT``::
"""Provide the oracle DATE type.
This type has no special Python behavior, except that it subclasses
- :class:`.types.DateTime`; this is to suit the fact that the Oracle
+ :class:`_types.DateTime`; this is to suit the fact that the Oracle
``DATE`` type supports a time value.
.. versionadded:: 0.9.4
the VARCHAR2 and CLOB datatypes can accommodate the data.
In the case that the Oracle database is not configured with a Unicode character
-set, the two options are to use the :class:`.oracle.NCHAR` and
-:class:`.oracle.NCLOB` datatypes explicitly, or to pass the flag
+set, the two options are to use the :class:`_oracle.NCHAR` and
+:class:`_oracle.NCLOB` datatypes explicitly, or to pass the flag
``use_nchar_for_unicode=True`` to :func:`.create_engine`, which will cause the
SQLAlchemy dialect to use NCHAR/NCLOB for the :class:`.Unicode` /
:class:`.UnicodeText` datatypes instead of VARCHAR/CLOB.
SQLAlchemy's numeric types can handle receiving and returning values as Python
``Decimal`` objects or float objects. When a :class:`.Numeric` object, or a
-subclass such as :class:`.Float`, :class:`.oracle.DOUBLE_PRECISION` etc. is in
+subclass such as :class:`.Float`, :class:`_oracle.DOUBLE_PRECISION` etc. is in
use, the :paramref:`.Numeric.asdecimal` flag determines if values should be
coerced to ``Decimal`` upon return, or returned as float objects. To make
matters more complicated under Oracle, Oracle's ``NUMBER`` type can also
represent integer values if the "scale" is zero, so the Oracle-specific
-:class:`.oracle.NUMBER` type takes this into account as well.
+:class:`_oracle.NUMBER` type takes this into account as well.
The cx_Oracle dialect makes extensive use of connection- and cursor-level
"outputtypehandler" callables in order to coerce numeric values as requested.
.. seealso::
- :func:`.expression.any_`
+ :func:`_expression.any_`
"""
.. seealso::
- :func:`.expression.all_`
+ :func:`_expression.all_`
"""
ARRAY[%(param_3)s, %(param_4)s, %(param_5)s]) AS anon_1
An instance of :class:`.array` will always have the datatype
- :class:`.ARRAY`. The "inner" type of the array is inferred from
+ :class:`_types.ARRAY`. The "inner" type of the array is inferred from
the values present, unless the ``type_`` keyword argument is passed::
array(['foo', 'bar'], type_=CHAR)
Multidimensional arrays are produced by nesting :class:`.array` constructs.
- The dimensionality of the final :class:`.ARRAY` type is calculated by
- recursively adding the dimensions of the inner :class:`.ARRAY` type::
+ The dimensionality of the final :class:`_types.ARRAY`
+ type is calculated by
+ recursively adding the dimensions of the inner :class:`_types.ARRAY`
+ type::
stmt = select([
array([
.. seealso::
- :class:`.postgresql.ARRAY`
+ :class:`_postgresql.ARRAY`
"""
"""PostgreSQL ARRAY type.
- .. versionchanged:: 1.1 The :class:`.postgresql.ARRAY` type is now
- a subclass of the core :class:`.types.ARRAY` type.
+ .. versionchanged:: 1.1 The :class:`_postgresql.ARRAY` type is now
+ a subclass of the core :class:`_types.ARRAY` type.
- The :class:`.postgresql.ARRAY` type is constructed in the same way
- as the core :class:`.types.ARRAY` type; a member type is required, and a
+ The :class:`_postgresql.ARRAY` type is constructed in the same way
+ as the core :class:`_types.ARRAY` type; a member type is required, and a
number of dimensions is recommended if the type is to be used for more
than one dimension::
Column("data", postgresql.ARRAY(Integer, dimensions=2))
)
- The :class:`.postgresql.ARRAY` type provides all operations defined on the
- core :class:`.types.ARRAY` type, including support for "dimensions",
+ The :class:`_postgresql.ARRAY` type provides all operations defined on the
+ core :class:`_types.ARRAY` type, including support for "dimensions",
indexed access, and simple matching such as
:meth:`.types.ARRAY.Comparator.any` and
- :meth:`.types.ARRAY.Comparator.all`. :class:`.postgresql.ARRAY` class also
+ :meth:`.types.ARRAY.Comparator.all`. :class:`_postgresql.ARRAY`
+ class also
provides PostgreSQL-specific methods for containment operations, including
:meth:`.postgresql.ARRAY.Comparator.contains`
:meth:`.postgresql.ARRAY.Comparator.contained_by`, and
mytable.c.data.contains([1, 2])
- The :class:`.postgresql.ARRAY` type may not be supported on all
+ The :class:`_postgresql.ARRAY` type may not be supported on all
PostgreSQL DBAPIs; it is currently known to work on psycopg2 only.
- Additionally, the :class:`.postgresql.ARRAY` type does not work directly in
+ Additionally, the :class:`_postgresql.ARRAY`
+ type does not work directly in
conjunction with the :class:`.ENUM` type. For a workaround, see the
special type at :ref:`postgresql_array_of_enum`.
.. seealso::
- :class:`.types.ARRAY` - base array type
+ :class:`_types.ARRAY` - base array type
- :class:`.postgresql.array` - produces a literal array value.
+ :class:`_postgresql.array` - produces a literal array value.
"""
class Comparator(sqltypes.ARRAY.Comparator):
- """Define comparison operations for :class:`.ARRAY`.
+ """Define comparison operations for :class:`_types.ARRAY`.
Note that these operations are in addition to those provided
by the base :class:`.types.ARRAY.Comparator` class, including
both via a dialect-specific parameter
:paramref:`.create_engine.isolation_level` accepted by :func:`.create_engine`,
as well as the :paramref:`.Connection.execution_options.isolation_level`
-argument as passed to :meth:`.Connection.execution_options`.
+argument as passed to :meth:`_engine.Connection.execution_options`.
When using a non-psycopg2 dialect, this feature works by issuing the command
``SET SESSION CHARACTERISTICS AS TRANSACTION ISOLATION LEVEL <level>`` for
each new connection. For the special AUTOCOMMIT isolation level,
name schemas **other** than ``public`` explicitly within ``Table`` definitions.
The PostgreSQL dialect can reflect tables from any schema. The
-:paramref:`.Table.schema` argument, or alternatively the
+:paramref:`_schema.Table.schema` argument, or alternatively the
:paramref:`.MetaData.reflect.schema` argument determines which schema will
-be searched for the table or tables. The reflected :class:`.Table` objects
+be searched for the table or tables. The reflected :class:`_schema.Table`
+objects
will in all cases retain this ``.schema`` attribute as was specified.
-However, with regards to tables which these :class:`.Table` objects refer to
+However, with regards to tables which these :class:`_schema.Table`
+objects refer to
via foreign key constraint, a decision must be made as to how the ``.schema``
is represented in those remote tables, in the case where that remote
schema name is also a member of the current
...
<sqlalchemy.engine.result.ResultProxy object at 0x101612ed0>
-The above process would deliver to the :attr:`.MetaData.tables` collection
+The above process would deliver to the :attr:`_schema.MetaData.tables`
+collection
``referred`` table named **without** the schema::
>>> meta.tables['referred'].schema is None
To alter the behavior of reflection such that the referred schema is
maintained regardless of the ``search_path`` setting, use the
``postgresql_ignore_search_path`` option, which can be specified as a
-dialect-specific argument to both :class:`.Table` as well as
-:meth:`.MetaData.reflect`::
+dialect-specific argument to both :class:`_schema.Table` as well as
+:meth:`_schema.MetaData.reflect`::
>>> with engine.connect() as conn:
... conn.execute(text("SET search_path TO test_schema, public"))
you just stick to the simplest use pattern: leave the ``search_path`` set
to its default of ``public`` only, never refer to the name ``public`` as
an explicit schema name otherwise, and refer to all other schema names
- explicitly when building up a :class:`.Table` object. The options
+ explicitly when building up a :class:`_schema.Table` object. The options
described here are only for those users who can't, or prefer not to, stay
within these guidelines.
``.schema`` attribute set to ``None``.
.. versionadded:: 0.9.2 Added the ``postgresql_ignore_search_path``
- dialect-level option accepted by :class:`.Table` and
- :meth:`.MetaData.reflect`.
+ dialect-level option accepted by :class:`_schema.Table` and
+ :meth:`_schema.MetaData.reflect`.
.. seealso::
the indexes.
SQLAlchemy provides ``ON CONFLICT`` support via the PostgreSQL-specific
-:func:`.postgresql.insert()` function, which provides
+:func:`_postgresql.insert()` function, which provides
the generative methods :meth:`~.postgresql.Insert.on_conflict_do_update`
and :meth:`~.postgresql.Insert.on_conflict_do_nothing`::
named constraint or by column inference:
* The :paramref:`.Insert.on_conflict_do_update.index_elements` argument
- specifies a sequence containing string column names, :class:`.Column`
+ specifies a sequence containing string column names, :class:`_schema.Column`
objects, and/or SQL expression elements, which would identify a unique
index::
constraint is unnamed, then inference will be used, where the expressions
and optional WHERE clause of the constraint will be spelled out in the
construct. This use is especially convenient
- to refer to the named or unnamed primary key of a :class:`.Table` using the
- :attr:`.Table.primary_key` attribute::
+ to refer to the named or unnamed primary key of a :class:`_schema.Table`
+ using the
+ :attr:`_schema.Table.primary_key` attribute::
do_update_stmt = insert_stmt.on_conflict_do_update(
constraint=my_table.primary_key,
.. warning::
- The :meth:`.Insert.on_conflict_do_update` method does **not** take into
+ The :meth:`_expression.Insert.on_conflict_do_update`
+ method does **not** take into
account Python-side default UPDATE values or generation functions, e.g.
- those specified using :paramref:`.Column.onupdate`.
+ those specified using :paramref:`_schema.Column.onupdate`.
These values will not be exercised for an ON CONFLICT style of UPDATE,
unless they are manually specified in the
:paramref:`.Insert.on_conflict_do_update.set_` dictionary.
In order to refer to the proposed insertion row, the special alias
:attr:`~.postgresql.Insert.excluded` is available as an attribute on
-the :class:`.postgresql.Insert` object; this object is a
-:class:`.ColumnCollection` which alias contains all columns of the target
+the :class:`_postgresql.Insert` object; this object is a
+:class:`_expression.ColumnCollection`
+which alias contains all columns of the target
table::
from sqlalchemy.dialects.postgresql import insert
)
conn.execute(do_update_stmt)
-The :meth:`.Insert.on_conflict_do_update` method also accepts
+The :meth:`_expression.Insert.on_conflict_do_update` method also accepts
a WHERE clause using the :paramref:`.Insert.on_conflict_do_update.where`
parameter, which will limit those rows which receive an UPDATE::
----------------
SQLAlchemy makes available the PostgreSQL ``@@`` operator via the
-:meth:`.ColumnElement.match` method on any textual column expression.
+:meth:`_expression.ColumnElement.match`
+method on any textual column expression.
On a PostgreSQL dialect, an expression like the following::
select([sometable.c.text.match("search string")])
SELECT to_tsvector('fat cats ate rats') @@ to_tsquery('cat & rat')
-The :class:`.postgresql.TSVECTOR` type can provide for explicit CAST::
+The :class:`_postgresql.TSVECTOR` type can provide for explicit CAST::
from sqlalchemy.dialects.postgresql import TSVECTOR
from sqlalchemy import select, cast
})
Note that the keys in the ``postgresql_ops`` dictionary are the "key" name of
-the :class:`.Column`, i.e. the name used to access it from the ``.c``
-collection of :class:`.Table`, which can be configured to be different than
+the :class:`_schema.Column`, i.e. the name used to access it from the ``.c``
+collection of :class:`_schema.Table`,
+which can be configured to be different than
the actual name of the column as expressed in the database.
If ``postgresql_ops`` is to be used against a complex SQL expression such
.. versionadded:: 1.1
-Note that the same option is available on :class:`.Table` as well.
+Note that the same option is available on :class:`_schema.Table` as well.
.. _postgresql_index_concurrently:
The PostgreSQL database creates a UNIQUE INDEX implicitly whenever the
UNIQUE CONSTRAINT construct is used. When inspecting a table using
-:class:`.Inspector`, the :meth:`.Inspector.get_indexes`
-and the :meth:`.Inspector.get_unique_constraints` will report on these
+:class:`_reflection.Inspector`, the :meth:`_reflection.Inspector.get_indexes`
+and the :meth:`_reflection.Inspector.get_unique_constraints`
+will report on these
two constructs distinctly; in the case of the index, the key
``duplicates_constraint`` will be present in the index entry if it is
detected as mirroring a constraint. When performing reflection using
``Table(..., autoload=True)``, the UNIQUE INDEX is **not** returned
-in :attr:`.Table.indexes` when it is detected as mirroring a
-:class:`.UniqueConstraint` in the :attr:`.Table.constraints` collection.
+in :attr:`_schema.Table.indexes` when it is detected as mirroring a
+:class:`.UniqueConstraint` in the :attr:`_schema.Table.constraints` collection
+.
-.. versionchanged:: 1.0.0 - :class:`.Table` reflection now includes
- :class:`.UniqueConstraint` objects present in the :attr:`.Table.constraints`
+.. versionchanged:: 1.0.0 - :class:`_schema.Table` reflection now includes
+ :class:`.UniqueConstraint` objects present in the
+ :attr:`_schema.Table.constraints`
collection; the PostgreSQL backend will no longer include a "mirrored"
- :class:`.Index` construct in :attr:`.Table.indexes` if it is detected
+ :class:`.Index` construct in :attr:`_schema.Table.indexes`
+ if it is detected
as corresponding to a unique constraint.
Special Reflection Options
--------------------------
-The :class:`.Inspector` used for the PostgreSQL backend is an instance
+The :class:`_reflection.Inspector`
+used for the PostgreSQL backend is an instance
of :class:`.PGInspector`, which offers additional methods::
from sqlalchemy import create_engine, inspect
------------------------
Several options for CREATE TABLE are supported directly by the PostgreSQL
-dialect in conjunction with the :class:`.Table` construct:
+dialect in conjunction with the :class:`_schema.Table` construct:
* ``TABLESPACE``::
The PostgreSQL dialect supports arrays, both as multidimensional column types
as well as array literals:
-* :class:`.postgresql.ARRAY` - ARRAY datatype
+* :class:`_postgresql.ARRAY` - ARRAY datatype
-* :class:`.postgresql.array` - array literal
+* :class:`_postgresql.array` - array literal
-* :func:`.postgresql.array_agg` - ARRAY_AGG SQL function
+* :func:`_postgresql.array_agg` - ARRAY_AGG SQL function
-* :class:`.postgresql.aggregate_order_by` - helper for PG's ORDER BY aggregate
+* :class:`_postgresql.aggregate_order_by` - helper for PG's ORDER BY aggregate
function syntax.
JSON Types
psycopg2's native support and support for all of PostgreSQL's special
operators:
-* :class:`.postgresql.JSON`
+* :class:`_postgresql.JSON`
-* :class:`.postgresql.JSONB`
+* :class:`_postgresql.JSONB`
HSTORE Type
-----------
The PostgreSQL HSTORE type as well as hstore literals are supported:
-* :class:`.postgresql.HSTORE` - HSTORE datatype
+* :class:`_postgresql.HSTORE` - HSTORE datatype
-* :class:`.postgresql.hstore` - hstore literal
+* :class:`_postgresql.hstore` - hstore literal
ENUM Types
----------
CREATED and DROPPED. The type object is also an independently reflectable
entity. The following sections should be consulted:
-* :class:`.postgresql.ENUM` - DDL and typing support for ENUM.
+* :class:`_postgresql.ENUM` - DDL and typing support for ENUM.
* :meth:`.PGInspector.get_enums` - retrieve a listing of current ENUM types
The combination of ENUM and ARRAY is not directly supported by backend
DBAPIs at this time. In order to send and receive an ARRAY of ENUM,
use the following workaround type, which decorates the
-:class:`.postgresql.ARRAY` datatype.
+:class:`_postgresql.ARRAY` datatype.
.. sourcecode:: python
class TSVECTOR(sqltypes.TypeEngine):
- """The :class:`.postgresql.TSVECTOR` type implements the PostgreSQL
+ """The :class:`_postgresql.TSVECTOR` type implements the PostgreSQL
text search type TSVECTOR.
It can be used to do full text queries on natural language
"""PostgreSQL ENUM type.
- This is a subclass of :class:`.types.Enum` which includes
+ This is a subclass of :class:`_types.Enum` which includes
support for PG's ``CREATE TYPE`` and ``DROP TYPE``.
- When the builtin type :class:`.types.Enum` is used and the
+ When the builtin type :class:`_types.Enum` is used and the
:paramref:`.Enum.native_enum` flag is left at its default of
- True, the PostgreSQL backend will use a :class:`.postgresql.ENUM`
+ True, the PostgreSQL backend will use a :class:`_postgresql.ENUM`
type as the implementation, so the special create/drop rules
will be used.
parent table, in that it may be "owned" by just a single table, or
may be shared among many tables.
- When using :class:`.types.Enum` or :class:`.postgresql.ENUM`
+ When using :class:`_types.Enum` or :class:`_postgresql.ENUM`
in an "inline" fashion, the ``CREATE TYPE`` and ``DROP TYPE`` is emitted
- corresponding to when the :meth:`.Table.create` and :meth:`.Table.drop`
+ corresponding to when the :meth:`_schema.Table.create` and
+ :meth:`_schema.Table.drop`
methods are called::
table = Table('sometable', metadata,
table.drop(engine) # will emit DROP TABLE and DROP ENUM
To use a common enumerated type between multiple tables, the best
- practice is to declare the :class:`.types.Enum` or
- :class:`.postgresql.ENUM` independently, and associate it with the
- :class:`.MetaData` object itself::
+ practice is to declare the :class:`_types.Enum` or
+ :class:`_postgresql.ENUM` independently, and associate it with the
+ :class:`_schema.MetaData` object itself::
my_enum = ENUM('a', 'b', 'c', name='myenum', metadata=metadata)
my_enum.create(engine)
my_enum.drop(engine)
- .. versionchanged:: 1.0.0 The PostgreSQL :class:`.postgresql.ENUM` type
+ .. versionchanged:: 1.0.0 The PostgreSQL :class:`_postgresql.ENUM` type
now behaves more strictly with regards to CREATE/DROP. A metadata-level
ENUM type will only be created and dropped at the metadata level,
not the table level, with the exception of
native_enum = True
def __init__(self, *enums, **kw):
- """Construct an :class:`~.postgresql.ENUM`.
+ """Construct an :class:`_postgresql.ENUM`.
Arguments are the same as that of
- :class:`.types.Enum`, but also including
+ :class:`_types.Enum`, but also including
the following parameters.
:param create_type: Defaults to True.
@classmethod
def adapt_emulated_to_native(cls, impl, **kw):
- """Produce a PostgreSQL native :class:`.postgresql.ENUM` from plain
+ """Produce a PostgreSQL native :class:`_postgresql.ENUM` from plain
:class:`.Enum`.
"""
def create(self, bind=None, checkfirst=True):
"""Emit ``CREATE TYPE`` for this
- :class:`~.postgresql.ENUM`.
+ :class:`_postgresql.ENUM`.
If the underlying dialect does not support
PostgreSQL CREATE TYPE, no action is taken.
- :param bind: a connectable :class:`.Engine`,
- :class:`.Connection`, or similar object to emit
+ :param bind: a connectable :class:`_engine.Engine`,
+ :class:`_engine.Connection`, or similar object to emit
SQL.
:param checkfirst: if ``True``, a query against
the PG catalog will be first performed to see
def drop(self, bind=None, checkfirst=True):
"""Emit ``DROP TYPE`` for this
- :class:`~.postgresql.ENUM`.
+ :class:`_postgresql.ENUM`.
If the underlying dialect does not support
PostgreSQL DROP TYPE, no action is taken.
- :param bind: a connectable :class:`.Engine`,
- :class:`.Connection`, or similar object to emit
+ :param bind: a connectable :class:`_engine.Engine`,
+ :class:`_engine.Connection`, or similar object to emit
SQL.
:param checkfirst: if ``True``, a query against
the PG catalog will be first performed to see
def get_foreign_table_names(self, schema=None):
"""Return a list of FOREIGN TABLE names.
- Behavior is similar to that of :meth:`.Inspector.get_table_names`,
+ Behavior is similar to that of
+ :meth:`_reflection.Inspector.get_table_names`,
except that the list is limited to those tables that report a
``relkind`` value of ``f``.
Adds methods for PG-specific syntaxes such as ON CONFLICT.
- The :class:`.postgresql.Insert` object is created using the
+ The :class:`_postgresql.Insert` object is created using the
:func:`sqlalchemy.dialects.postgresql.insert` function.
.. versionadded:: 1.1
.. seealso::
:ref:`postgresql_insert_on_conflict` - example of how
- to use :attr:`.Insert.excluded`
+ to use :attr:`_expression.Insert.excluded`
"""
return alias(self.table, name="excluded").columns
or the constraint object itself if it has a .name attribute.
:param index_elements:
- A sequence consisting of string column names, :class:`.Column`
+ A sequence consisting of string column names, :class:`_schema.Column`
objects, or other column expression objects that will be used
to infer a target index.
Required argument. A dictionary or other mapping object
with column names as keys and expressions or literals as values,
specifying the ``SET`` actions to take.
- If the target :class:`.Column` specifies a ".key" attribute distinct
+ If the target :class:`_schema.Column` specifies a ".
+ key" attribute distinct
from the column name, that key should be used.
.. warning:: This dictionary does **not** take into account
Python-specified default UPDATE values or generation functions,
- e.g. those specified using :paramref:`.Column.onupdate`.
+ e.g. those specified using :paramref:`_schema.Column.onupdate`.
These values will not be exercised for an ON CONFLICT style of
UPDATE, unless they are manually specified in the
:paramref:`.Insert.on_conflict_do_update.set_` dictionary.
or the constraint object itself if it has a .name attribute.
:param index_elements:
- A sequence consisting of string column names, :class:`.Column`
+ A sequence consisting of string column names, :class:`_schema.Column`
objects, or other column expression objects that will be used
to infer a target index.
.. seealso::
- :class:`.array_agg`
+ :class:`_functions.array_agg`
"""
where=(Column('group') != 'some group')
)
- The constraint is normally embedded into the :class:`.Table` construct
+ The constraint is normally embedded into the :class:`_schema.Table`
+ construct
directly, or added later using :meth:`.append_constraint`::
some_table = Table(
A sequence of two tuples of the form ``(column, operator)`` where
"column" is a SQL expression element or a raw SQL string, most
- typically a :class:`.Column` object, and "operator" is a string
+ typically a :class:`_schema.Column` object,
+ and "operator" is a string
containing the operator to use. In order to specify a column name
- when a :class:`.Column` object is not available, while ensuring
+ when a :class:`_schema.Column` object is not available,
+ while ensuring
that any necessary quoting rules take effect, an ad-hoc
- :class:`.Column` or :func:`.sql.expression.column` object should be
+ :class:`_schema.Column` or :func:`_expression.column`
+ object should be
used.
:param name:
def array_agg(*arg, **kw):
- """PostgreSQL-specific form of :class:`.array_agg`, ensures
- return type is :class:`.postgresql.ARRAY` and not
- the plain :class:`.types.ARRAY`, unless an explicit ``type_``
+ """PostgreSQL-specific form of :class:`_functions.array_agg`, ensures
+ return type is :class:`_postgresql.ARRAY` and not
+ the plain :class:`_types.ARRAY`, unless an explicit ``type_``
is passed.
.. versionadded:: 1.1
"""Construct a new :class:`.HSTORE`.
:param text_type: the type that should be used for indexed values.
- Defaults to :class:`.types.Text`.
+ Defaults to :class:`_types.Text`.
.. versionadded:: 1.1.0
class JSON(sqltypes.JSON):
"""Represent the PostgreSQL JSON type.
- This type is a specialization of the Core-level :class:`.types.JSON`
- type. Be sure to read the documentation for :class:`.types.JSON` for
+ This type is a specialization of the Core-level :class:`_types.JSON`
+ type. Be sure to read the documentation for :class:`_types.JSON` for
important tips regarding treatment of NULL values and ORM use.
- .. versionchanged:: 1.1 :class:`.postgresql.JSON` is now a PostgreSQL-
- specific specialization of the new :class:`.types.JSON` type.
+ .. versionchanged:: 1.1 :class:`_postgresql.JSON` is now a PostgreSQL-
+ specific specialization of the new :class:`_types.JSON` type.
- The operators provided by the PostgreSQL version of :class:`.JSON`
+ The operators provided by the PostgreSQL version of :class:`_types.JSON`
include:
* Index operations (the ``->`` operator)::
data_table.c.data[('key_1', 'key_2', 5, ..., 'key_n')].astext == 'some value'
- .. versionchanged:: 1.1 The :meth:`.ColumnElement.cast` operator on
+ .. versionchanged:: 1.1 The :meth:`_expression.ColumnElement.cast`
+ operator on
JSON objects now requires that the :attr:`.JSON.Comparator.astext`
modifier be called explicitly, if the cast works only from a textual
string.
Index operations return an expression object whose type defaults to
- :class:`.JSON` by default, so that further JSON-oriented instructions
+ :class:`_types.JSON` by default,
+ so that further JSON-oriented instructions
may be called upon the result type.
Custom serializers and deserializers are specified at the dialect level,
.. seealso::
- :class:`.types.JSON` - Core level JSON type
+ :class:`_types.JSON` - Core level JSON type
- :class:`.JSONB`
+ :class:`_postgresql.JSONB`
""" # noqa
astext_type = sqltypes.Text()
def __init__(self, none_as_null=False, astext_type=None):
- """Construct a :class:`.JSON` type.
+ """Construct a :class:`_types.JSON` type.
:param none_as_null: if True, persist the value ``None`` as a
SQL NULL value, not the JSON encoding of ``null``. Note that
.. seealso::
- :attr:`.JSON.NULL`
+ :attr:`_types.JSON.NULL`
:param astext_type: the type to use for the
:attr:`.JSON.Comparator.astext`
- accessor on indexed attributes. Defaults to :class:`.types.Text`.
+ accessor on indexed attributes. Defaults to :class:`_types.Text`.
.. versionadded:: 1.1
self.astext_type = astext_type
class Comparator(sqltypes.JSON.Comparator):
- """Define comparison operations for :class:`.JSON`."""
+ """Define comparison operations for :class:`_types.JSON`."""
@property
def astext(self):
.. seealso::
- :meth:`.ColumnElement.cast`
+ :meth:`_expression.ColumnElement.cast`
"""
if isinstance(self.expr.right.type, sqltypes.JSON.JSONPathType):
class JSONB(JSON):
"""Represent the PostgreSQL JSONB type.
- The :class:`.JSONB` type stores arbitrary JSONB format data, e.g.::
+ The :class:`_postgresql.JSONB` type stores arbitrary JSONB format data, e.
+ g.::
data_table = Table('data_table', metadata,
Column('id', Integer, primary_key=True),
data = {"key1": "value1", "key2": "value2"}
)
- The :class:`.JSONB` type includes all operations provided by
- :class:`.JSON`, including the same behaviors for indexing operations.
+ The :class:`_postgresql.JSONB` type includes all operations provided by
+ :class:`_types.JSON`, including the same behaviors for indexing operations
+ .
It also adds additional operators specific to JSONB, including
:meth:`.JSONB.Comparator.has_key`, :meth:`.JSONB.Comparator.has_all`,
:meth:`.JSONB.Comparator.has_any`, :meth:`.JSONB.Comparator.contains`,
and :meth:`.JSONB.Comparator.contained_by`.
- Like the :class:`.JSON` type, the :class:`.JSONB` type does not detect
+ Like the :class:`_types.JSON` type, the :class:`_postgresql.JSONB`
+ type does not detect
in-place changes when used with the ORM, unless the
:mod:`sqlalchemy.ext.mutable` extension is used.
Custom serializers and deserializers
- are shared with the :class:`.JSON` class, using the ``json_serializer``
+ are shared with the :class:`_types.JSON` class,
+ using the ``json_serializer``
and ``json_deserializer`` keyword arguments. These must be specified
at the dialect level using :func:`.create_engine`. When using
psycopg2, the serializers are associated with the jsonb type using
.. seealso::
- :class:`.JSON`
+ :class:`_types.JSON`
"""
__visit_name__ = "JSONB"
class Comparator(JSON.Comparator):
- """Define comparison operations for :class:`.JSON`."""
+ """Define comparison operations for :class:`_types.JSON`."""
def has_key(self, other):
"""Boolean expression. Test for presence of a key. Note that the
-------------------------------------------
The following DBAPI-specific options are respected when used with
-:meth:`.Connection.execution_options`, :meth:`.Executable.execution_options`,
-:meth:`.Query.execution_options`, in addition to those not specific to DBAPIs:
+:meth:`_engine.Connection.execution_options`,
+:meth:`.Executable.execution_options`,
+:meth:`_query.Query.execution_options`,
+in addition to those not specific to DBAPIs:
* ``isolation_level`` - Set the transaction isolation level for the lifespan
- of a :class:`.Connection` (can only be set on a connection, not a statement
+ of a :class:`_engine.Connection` (can only be set on a connection,
+ not a statement
or query). See :ref:`psycopg2_isolation_level`.
* ``stream_results`` - Enable or disable usage of psycopg2 server side
cursors - this feature makes use of "named" cursors in combination with
special result handling methods so that result rows are not fully buffered.
If ``None`` or not set, the ``server_side_cursors`` option of the
- :class:`.Engine` is used.
+ :class:`_engine.Engine` is used.
* ``max_row_buffer`` - when using ``stream_results``, an integer value that
specifies the maximum number of rows to buffer at a time. This is
have been shown in benchmarking to improve psycopg2's executemany()
performance, primarily with INSERT statements, by multiple orders of magnitude.
SQLAlchemy allows this extension to be used for all ``executemany()`` style
-calls invoked by an :class:`.Engine` when used with :ref:`multiple parameter
+calls invoked by an :class:`_engine.Engine`
+when used with :ref:`multiple parameter
sets <execute_multiple>`, which includes the use of this feature both by the
Core as well as by the ORM for inserts of objects with non-autogenerated
primary key values, by adding the ``executemany_mode`` flag to
semicolon. This is the same behavior as was provided by the
``use_batch_mode=True`` flag.
-* ``'values'``- For Core :func:`~.sql.expression.insert` constructs only (including those
+* ``'values'``- For Core :func:`_expression.insert`
+ constructs only (including those
emitted by the ORM automatically), the ``psycopg2.extras.execute_values``
extension is used so that multiple parameter sets are grouped into a single
INSERT statement and joined together with multiple VALUES expressions. This
method requires that the string text of the VALUES clause inside the
INSERT statement is manipulated, so is only supported with a compiled
- :func:`~.sql.expression.insert` construct where the format is predictable. For all other
+ :func:`_expression.insert` construct where the format is predictable.
+ For all other
constructs, including plain textual INSERT statements not rendered by the
SQLAlchemy expression language compiler, the
``psycopg2.extras.execute_batch`` method is used. It is therefore important
.. seealso::
:ref:`execute_multiple` - General information on using the
- :class:`.Connection` object to execute statements in such a way as to make
+ :class:`_engine.Connection`
+ object to execute statements in such a way as to make
use of the DBAPI ``.executemany()`` method.
.. versionchanged:: 1.3.7 - Added support for
generates bound parameter names based on the name of a column, the presence
of these characters in a column name can lead to problems.
-There are two solutions to the issue of a :class:`.schema.Column` that contains
+There are two solutions to the issue of a :class:`_schema.Column`
+that contains
one of these characters in its name. One is to specify the
:paramref:`.schema.Column.key` for columns that have such names::
``measurement.c.size_meters > 10`` will derive the bound parameter name
from the ``size_meters`` key as well.
-.. versionchanged:: 1.0.0 - SQL expressions will use :attr:`.Column.key`
+.. versionchanged:: 1.0.0 - SQL expressions will use
+ :attr:`_schema.Column.key`
as the source of naming when anonymous bound parameters are created
in SQL expressions; previously, this behavior only applied to
- :meth:`.Table.insert` and :meth:`.Table.update` parameter names.
+ :meth:`_schema.Table.insert` and :meth:`_schema.Table.update`
+ parameter names.
The other solution is to use a positional format; psycopg2 allows use of the
"format" paramstyle, which can be passed to
all PostgreSQL dialects support setting of transaction isolation level
both via the ``isolation_level`` parameter passed to :func:`.create_engine`,
as well as the ``isolation_level`` argument used by
-:meth:`.Connection.execution_options`. When using the psycopg2 dialect, these
+:meth:`_engine.Connection.execution_options`. When using the psycopg2 dialect
+, these
options make use of psycopg2's ``set_isolation_level()`` connection method,
rather than emitting a PostgreSQL directive; this is because psycopg2's
API-level setting is always emitted at the start of each transaction in any
`datetime` objects and a SQLite-supported format. SQLAlchemy's own
:class:`~sqlalchemy.types.DateTime` and related types provide date formatting
and parsing functionality when SQLite is used. The implementation classes are
-:class:`~.sqlite.DATETIME`, :class:`~.sqlite.DATE` and :class:`~.sqlite.TIME`.
+:class:`_sqlite.DATETIME`, :class:`_sqlite.DATE` and :class:`_sqlite.TIME`.
These types represent dates and times as ISO formatted strings, which also
nicely support ordering. There's no reliance on typical "libc" internals for
these functions so historical dates are fully supported.
SQLite supports SAVEPOINTs, which only function once a transaction is
begun. SQLAlchemy's SAVEPOINT support is available using the
-:meth:`.Connection.begin_nested` method at the Core level, and
+:meth:`_engine.Connection.begin_nested` method at the Core level, and
:meth:`.Session.begin_nested` at the ORM level. However, SAVEPOINTs
won't work at all with pysqlite unless workarounds are taken.
clause within DDL, the extension parameter ``sqlite_on_conflict`` can be
specified with a string conflict resolution algorithm within the
:class:`.PrimaryKeyConstraint`, :class:`.UniqueConstraint`,
-:class:`.CheckConstraint` objects. Within the :class:`.Column` object, there
+:class:`.CheckConstraint` objects. Within the :class:`_schema.Column` object,
+there
are individual parameters ``sqlite_on_conflict_not_null``,
``sqlite_on_conflict_primary_key``, ``sqlite_on_conflict_unique`` which each
correspond to the three types of relevant constraint types that can be
-indicated from a :class:`.Column` object.
+indicated from a :class:`_schema.Column` object.
.. seealso::
)
-When using the :paramref:`.Column.unique` flag to add a UNIQUE constraint
+When using the :paramref:`_schema.Column.unique`
+flag to add a UNIQUE constraint
to a single column, the ``sqlite_on_conflict_unique`` parameter can
-be added to the :class:`.Column` as well, which will be added to the
+be added to the :class:`_schema.Column` as well, which will be added to the
UNIQUE constraint in the DDL::
some_table = Table(
The provided typemap will make direct associations from an exact string
name match for the following types:
-:class:`~.types.BIGINT`, :class:`~.types.BLOB`,
-:class:`~.types.BOOLEAN`, :class:`~.types.BOOLEAN`,
-:class:`~.types.CHAR`, :class:`~.types.DATE`,
-:class:`~.types.DATETIME`, :class:`~.types.FLOAT`,
-:class:`~.types.DECIMAL`, :class:`~.types.FLOAT`,
-:class:`~.types.INTEGER`, :class:`~.types.INTEGER`,
-:class:`~.types.NUMERIC`, :class:`~.types.REAL`,
-:class:`~.types.SMALLINT`, :class:`~.types.TEXT`,
-:class:`~.types.TIME`, :class:`~.types.TIMESTAMP`,
-:class:`~.types.VARCHAR`, :class:`~.types.NVARCHAR`,
-:class:`~.types.NCHAR`
+:class:`_types.BIGINT`, :class:`_types.BLOB`,
+:class:`_types.BOOLEAN`, :class:`_types.BOOLEAN`,
+:class:`_types.CHAR`, :class:`_types.DATE`,
+:class:`_types.DATETIME`, :class:`_types.FLOAT`,
+:class:`_types.DECIMAL`, :class:`_types.FLOAT`,
+:class:`_types.INTEGER`, :class:`_types.INTEGER`,
+:class:`_types.NUMERIC`, :class:`_types.REAL`,
+:class:`_types.SMALLINT`, :class:`_types.TEXT`,
+:class:`_types.TIME`, :class:`_types.TIMESTAMP`,
+:class:`_types.VARCHAR`, :class:`_types.NVARCHAR`,
+:class:`_types.NCHAR`
When a type name does not match one of the above types, the "type affinity"
lookup is used instead:
-* :class:`~.types.INTEGER` is returned if the type name includes the
+* :class:`_types.INTEGER` is returned if the type name includes the
string ``INT``
-* :class:`~.types.TEXT` is returned if the type name includes the
+* :class:`_types.TEXT` is returned if the type name includes the
string ``CHAR``, ``CLOB`` or ``TEXT``
-* :class:`~.types.NullType` is returned if the type name includes the
+* :class:`_types.NullType` is returned if the type name includes the
string ``BLOB``
-* :class:`~.types.REAL` is returned if the type name includes the string
+* :class:`_types.REAL` is returned if the type name includes the string
``REAL``, ``FLOA`` or ``DOUB``.
-* Otherwise, the :class:`~.types.NUMERIC` type is used.
+* Otherwise, the :class:`_types.NUMERIC` type is used.
.. versionadded:: 0.9.3 Support for SQLite type affinity rules when reflecting
columns.
contain dots, and the functionality of :meth:`.ResultProxy.keys` and
:meth:`.Row.keys()` is required to return these dotted names unmodified,
the ``sqlite_raw_colnames`` execution option may be provided, either on a
-per-:class:`.Connection` basis::
+per-:class:`_engine.Connection` basis::
result = conn.execution_options(sqlite_raw_colnames=True).exec_driver_sql('''
select x.a, x.b from x where a=1
''')
assert result.keys() == ["x.a", "x.b"]
-or on a per-:class:`.Engine` basis::
+or on a per-:class:`_engine.Engine` basis::
engine = create_engine("sqlite://", execution_options={"sqlite_raw_colnames": True})
-When using the per-:class:`.Engine` execution option, note that
+When using the per-:class:`_engine.Engine` execution option, note that
**Core and ORM queries that use UNION may not function properly**.
""" # noqa
`loadable extension <https://www.sqlite.org/loadext.html>`_ and as such
may not be available, or may require run-time loading.
- The :class:`.sqlite.JSON` type supports persistence of JSON values
- as well as the core index operations provided by :class:`.types.JSON`
+ The :class:`_sqlite.JSON` type supports persistence of JSON values
+ as well as the core index operations provided by :class:`_types.JSON`
datatype, by adapting the operations to render the ``JSON_EXTRACT``
function wrapped in the ``JSON_QUOTE`` function at the database level.
Extracted values are quoted in order to ensure that the results are
.. warning:: When using the above recipe, it is advised to not use the
:paramref:`.Connection.execution_options.isolation_level` setting on
- :class:`.Connection` and :func:`.create_engine` with the SQLite driver,
+ :class:`_engine.Connection` and :func:`.create_engine`
+ with the SQLite driver,
as this function necessarily will also alter the ".isolation_level" setting.
from ..sql import util as sql_util
-"""Defines :class:`.Connection` and :class:`.Engine`.
+"""Defines :class:`_engine.Connection` and :class:`_engine.Engine`.
"""
"""Provides high-level functionality for a wrapped DB-API connection.
Provides execution support for string-based SQL statements as well as
- :class:`.ClauseElement`, :class:`.Compiled` and :class:`.DefaultGenerator`
+ :class:`_expression.ClauseElement`, :class:`.Compiled` and
+ :class:`.DefaultGenerator`
objects. Provides a :meth:`begin` method to return :class:`.Transaction`
objects.
r""" Set non-SQL options for the connection which take effect
during execution.
- The method returns a copy of this :class:`.Connection` which references
+ The method returns a copy of this :class:`_engine.Connection`
+ which references
the same underlying DBAPI connection, but also defines the given
execution options which will take effect for a call to
- :meth:`execute`. As the new :class:`.Connection` references the same
+ :meth:`execute`. As the new :class:`_engine.Connection`
+ references the same
underlying resource, it's usually a good idea to ensure that the copies
will be discarded immediately, which is implicit if used as in::
execute(stmt)
Note that any key/value can be passed to
- :meth:`.Connection.execution_options`, and it will be stored in the
- ``_execution_options`` dictionary of the :class:`.Connection`. It
+ :meth:`_engine.Connection.execution_options`,
+ and it will be stored in the
+ ``_execution_options`` dictionary of the :class:`_engine.Connection`.
+ It
is suitable for usage by end-user schemes to communicate with
event listeners, for example.
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:`.Connection`.
+ as well as others that are specific to :class:`_engine.Connection`.
:param autocommit: Available on: Connection, statement.
When True, a COMMIT will be invoked after execution
:param compiled_cache: Available on: Connection.
A dictionary where :class:`.Compiled` objects
- will be cached when the :class:`.Connection` compiles a clause
+ will be cached when the :class:`_engine.Connection`
+ compiles a clause
expression into a :class:`.Compiled` object.
It is the user's responsibility to
manage the size of this dictionary, which will have keys
used by the ORM internally supersedes a cache dictionary
specified here.
- :param isolation_level: Available on: :class:`.Connection`.
+ :param isolation_level: Available on: :class:`_engine.Connection`.
Set the transaction isolation level for the lifespan of this
- :class:`.Connection` object. Valid values include those string
+ :class:`_engine.Connection` object.
+ Valid values include those string
values accepted by the :paramref:`.create_engine.isolation_level`
parameter passed to :func:`.create_engine`. These levels are
semi-database specific; see individual dialect documentation for
The isolation level option applies the isolation level by emitting
statements on the DBAPI connection, and **necessarily affects the
original Connection object overall**, not just the copy that is
- returned by the call to :meth:`.Connection.execution_options`
+ returned by the call to :meth:`_engine.Connection.execution_options`
method. The isolation level will remain at the given setting until
the DBAPI connection itself is returned to the connection pool, i.e.
- the :meth:`.Connection.close` method on the original
- :class:`.Connection` is called, where an event handler will emit
+ the :meth:`_engine.Connection.close` method on the original
+ :class:`_engine.Connection` is called,
+ where an event handler will emit
additional statements on the DBAPI connection in order to revert the
isolation level change.
.. warning:: The ``isolation_level`` execution option should
**not** be used when a transaction is already established, that
- is, the :meth:`.Connection.begin` method or similar has been
+ is, the :meth:`_engine.Connection.begin`
+ method or similar has been
called. A database cannot change the isolation level on a
transaction in progress, and different DBAPIs and/or
SQLAlchemy dialects may implicitly roll back or commit
the transaction, or not affect the connection at all.
.. note:: The ``isolation_level`` execution option is implicitly
- reset if the :class:`.Connection` is invalidated, e.g. via
- the :meth:`.Connection.invalidate` method, or if a
+ 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 isolation level re-applied
to it automatically.
.. seealso::
:paramref:`.create_engine.isolation_level`
- - set per :class:`.Engine` isolation level
+ - set per :class:`_engine.Engine` isolation level
- :meth:`.Connection.get_isolation_level` - view current level
+ :meth:`_engine.Connection.get_isolation_level`
+ - view current level
:ref:`SQLite Transaction Isolation <sqlite_isolation_level>`
:param schema_translate_map: Available on: Connection, Engine.
A dictionary mapping schema names to schema names, that will be
- applied to the :paramref:`.Table.schema` element of each
- :class:`.Table` encountered when SQL or DDL expression elements
+ 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::
- :meth:`.Engine.execution_options`
+ :meth:`_engine.Engine.execution_options`
:meth:`.Executable.execution_options`
- :meth:`.Connection.get_execution_options`
+ :meth:`_engine.Connection.get_execution_options`
""" # noqa
.. seealso::
- :meth:`.Connection.execution_options`
+ :meth:`_engine.Connection.execution_options`
"""
return self._execution_options
def get_isolation_level(self):
"""Return the current isolation level assigned to this
- :class:`.Connection`.
+ :class:`_engine.Connection`.
This will typically be the default isolation level as determined
by the dialect, unless if the
:paramref:`.Connection.execution_options.isolation_level`
feature has been used to alter the isolation level on a
- per-:class:`.Connection` basis.
+ per-:class:`_engine.Connection` basis.
This attribute will typically perform a live SQL operation 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. Compare to the
- :attr:`.Connection.default_isolation_level` accessor
+ :attr:`_engine.Connection.default_isolation_level` accessor
which returns the dialect-level setting without performing a SQL
query.
.. seealso::
- :attr:`.Connection.default_isolation_level` - view default level
+ :attr:`_engine.Connection.default_isolation_level`
+ - view default level
:paramref:`.create_engine.isolation_level`
- - set per :class:`.Engine` isolation level
+ - set per :class:`_engine.Engine` isolation level
:paramref:`.Connection.execution_options.isolation_level`
- - set per :class:`.Connection` isolation level
+ - set per :class:`_engine.Connection` isolation level
"""
try:
@property
def default_isolation_level(self):
- """The default isolation level assigned to this :class:`.Connection`.
+ """The default isolation level assigned to this
+ :class:`_engine.Connection`.
- This is the isolation level setting that the :class:`.Connection`
- has when first procured via the :meth:`.Engine.connect` method.
+ This is the isolation level setting that the
+ :class:`_engine.Connection`
+ has when first procured via the :meth:`_engine.Engine.connect` method.
This level stays in place until the
:paramref:`.Connection.execution_options.isolation_level` is used
- to change the setting on a per-:class:`.Connection` basis.
+ to change the setting on a per-:class:`_engine.Connection` basis.
- Unlike :meth:`.Connection.get_isolation_level`, this attribute is set
+ Unlike :meth:`_engine.Connection.get_isolation_level`,
+ this attribute is set
ahead of time from the first connection procured by the dialect,
so SQL query is not invoked when this accessor is called.
.. seealso::
- :meth:`.Connection.get_isolation_level` - view current level
+ :meth:`_engine.Connection.get_isolation_level`
+ - view current level
:paramref:`.create_engine.isolation_level`
- - set per :class:`.Engine` isolation level
+ - set per :class:`_engine.Engine` isolation level
:paramref:`.Connection.execution_options.isolation_level`
- - set per :class:`.Connection` isolation level
+ - set per :class:`_engine.Connection` isolation level
"""
return self.dialect.default_isolation_level
@property
def info(self):
"""Info dictionary associated with the underlying DBAPI connection
- referred to by this :class:`.Connection`, allowing user-defined
+ 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:`.Connection`.
+ in subsequent instances of :class:`_engine.Connection`.
"""
@util.deprecated_20(":meth:`.Connection.connect`")
def connect(self, close_with_result=False):
- """Returns a branched version of this :class:`.Connection`.
+ """Returns a branched version of this :class:`_engine.Connection`.
- The :meth:`.Connection.close` method on the returned
- :class:`.Connection` can be called and this
- :class:`.Connection` will remain open.
+ The :meth:`_engine.Connection.close` method on the returned
+ :class:`_engine.Connection` can be called and this
+ :class:`_engine.Connection` will remain open.
This method provides usage symmetry with
- :meth:`.Engine.connect`, including for usage
+ :meth:`_engine.Engine.connect`, including for usage
with context managers.
"""
def invalidate(self, exception=None):
"""Invalidate the underlying DBAPI connection associated with
- this :class:`.Connection`.
+ this :class:`_engine.Connection`.
The underlying DBAPI connection is literally closed (if
possible), and is discarded. Its source connection pool will
typically lazily create a new connection to replace it.
Upon the next use (where "use" typically means using the
- :meth:`.Connection.execute` method or similar),
- this :class:`.Connection` will attempt to
+ :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` as a source of connectivity (e.g. a "reconnection").
+ :class:`_pool.Pool` as a source of connectivity (e.g.
+ a "reconnection").
If a transaction was in progress (e.g. the
- :meth:`.Connection.begin` method has been called) when
- :meth:`.Connection.invalidate` method is called, at the DBAPI
+ :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:`.Connection`
+ 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:`.Connection` will raise an
+ 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:`.Connection.invalidate` method, just like auto-invalidation,
+ The :meth:`_engine.Connection.invalidate` method,
+ just like auto-invalidation,
will at the connection pool level invoke the
- :meth:`.PoolEvents.invalidate` event.
+ :meth:`_events.PoolEvents.invalidate` event.
.. seealso::
# connection is fully closed (since we used "with:", can
# also call .close())
- This :class:`.Connection` instance will remain usable. When closed
+ 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.
which completes when either the :meth:`.Transaction.rollback`
or :meth:`.Transaction.commit` method is called.
- Nested calls to :meth:`.begin` on the same :class:`.Connection`
+ Nested calls to :meth:`.begin` on the same :class:`_engine.Connection`
will return new :class:`.Transaction` objects that represent
an emulated transaction within the scope of the enclosing
transaction, that is::
.. seealso::
- :meth:`.Connection.begin_nested` - use a SAVEPOINT
+ :meth:`_engine.Connection.begin_nested` - use a SAVEPOINT
- :meth:`.Connection.begin_twophase` -
+ :meth:`_engine.Connection.begin_twophase` -
use a two phase /XID transaction
- :meth:`.Engine.begin` - context manager available from
- :class:`.Engine`
+ :meth:`_engine.Engine.begin` - context manager available from
+ :class:`_engine.Engine`
"""
if self.__branch_from:
.. seealso::
- :meth:`.Connection.begin`
+ :meth:`_engine.Connection.begin`
- :meth:`.Connection.begin_twophase`
+ :meth:`_engine.Connection.begin_twophase`
"""
if self.__branch_from:
.. seealso::
- :meth:`.Connection.begin`
+ :meth:`_engine.Connection.begin`
- :meth:`.Connection.begin_twophase`
+ :meth:`_engine.Connection.begin_twophase`
"""
self._root._rollback_impl()
def close(self):
- """Close this :class:`.Connection`.
+ """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` referenced
- by the :class:`.Engine` that produced this
- :class:`.Connection`. Any transactional state present on
+ 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:`.Connection`.
+ outstanding with regards to this :class:`_engine.Connection`.
- After :meth:`~.Connection.close` is called, the
- :class:`.Connection` is permanently in a closed state,
+ After :meth:`_engine.Connection.close` is called, the
+ :class:`_engine.Connection` is permanently in a closed state,
and will allow no further operations.
"""
one of:
* a plain string (deprecated)
- * any :class:`.ClauseElement` construct that is also
+ * any :class:`_expression.ClauseElement` construct that is also
a subclass of :class:`.Executable`, such as a
- :func:`~.expression.select` construct
+ :func:`_expression.select` construct
* a :class:`.FunctionElement`, such as that generated
by :data:`.func`, will be automatically wrapped in
a SELECT statement, which is then executed.
* a :class:`.DefaultGenerator` object
* a :class:`.Compiled` object
- .. deprecated:: 2.0 passing a string to :meth:`.Connection.execute` is
+ .. deprecated:: 2.0 passing a string to
+ :meth:`_engine.Connection.execute` is
deprecated and will be removed in version 2.0. Use the
- :func:`~.expression.text` construct with
- :meth:`.Connection.execute`, or the
- :meth:`.Connection.exec_driver_sql` method to invoke a driver-level
+ :func:`_expression.text` construct with
+ :meth:`_engine.Connection.execute`, or the
+ :meth:`_engine.Connection.exec_driver_sql`
+ method to invoke a driver-level
SQL string.
:param \*multiparams/\**params: represent bound parameter
for details on paramstyle.
To execute a textual SQL statement which uses bound parameters in a
- DBAPI-agnostic way, use the :func:`~.expression.text` construct.
+ DBAPI-agnostic way, use the :func:`_expression.text` construct.
.. deprecated:: 2.0 use of tuple or scalar positional parameters
is deprecated. All params should be dicts or sequences of dicts.
@util.deprecated(
"1.4",
- "The :meth:`.Connection.transaction` method is deprecated and will be "
- "removed in a future release. Use the :meth:`.Engine.begin` "
+ "The :meth:`_engine.Connection.transaction` "
+ "method is deprecated and will be "
+ "removed in a future release. Use the :meth:`_engine.Engine.begin` "
"context manager instead.",
)
def transaction(self, callable_, *args, **kwargs):
r"""Execute the given function within a transaction boundary.
- The function is passed this :class:`.Connection`
+ The function is passed this :class:`_engine.Connection`
as the first argument, followed by the given \*args and \**kwargs,
e.g.::
The :meth:`.transaction` method is superseded by
the usage of the Python ``with:`` statement, which can
- be used with :meth:`.Connection.begin`::
+ be used with :meth:`_engine.Connection.begin`::
with conn.begin():
conn.execute(text("some statement"), {'x':5, 'y':10})
- As well as with :meth:`.Engine.begin`::
+ As well as with :meth:`_engine.Engine.begin`::
with engine.begin() as conn:
conn.execute(text("some statement"), {'x':5, 'y':10})
.. seealso::
- :meth:`.Engine.begin` - engine-level transactional
+ :meth:`_engine.Engine.begin` - engine-level transactional
context
- :meth:`.Engine.transaction` - engine-level version of
- :meth:`.Connection.transaction`
+ :meth:`_engine.Engine.transaction` - engine-level version of
+ :meth:`_engine.Connection.transaction`
"""
@util.deprecated(
"1.4",
- "The :meth:`.Connection.run_callable` method is deprecated and will "
+ "The :meth:`_engine.Connection.run_callable` "
+ "method is deprecated and will "
"be removed in a future release. Use a context manager instead.",
)
def run_callable(self, callable_, *args, **kwargs):
r"""Given a callable object or function, execute it, passing
- a :class:`.Connection` as the first argument.
+ a :class:`_engine.Connection` as the first argument.
The given \*args and \**kwargs are passed subsequent
- to the :class:`.Connection` argument.
+ to the :class:`_engine.Connection` argument.
- This function, along with :meth:`.Engine.run_callable`,
- allows a function to be run with a :class:`.Connection`
- or :class:`.Engine` object without the need to know
+ This function, along with :meth:`_engine.Engine.run_callable`,
+ allows a function to be run with a :class:`_engine.Connection`
+ or :class:`_engine.Engine` object without the need to know
which one is being dealt with.
"""
"""Represent a database transaction in progress.
The :class:`.Transaction` object is procured by
- calling the :meth:`~.Connection.begin` method of
- :class:`.Connection`::
+ calling the :meth:`_engine.Connection.begin` method of
+ :class:`_engine.Connection`::
from sqlalchemy import create_engine
engine = create_engine("postgresql://scott:tiger@localhost/test")
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:`.Connection.begin` method::
+ :meth:`_engine.Connection.begin` method::
with connection.begin():
connection.execute(text("insert into x (a, b) values (1, 2)"))
.. seealso::
- :meth:`.Connection.begin`
+ :meth:`_engine.Connection.begin`
- :meth:`.Connection.begin_twophase`
+ :meth:`_engine.Connection.begin_twophase`
- :meth:`.Connection.begin_nested`
+ :meth:`_engine.Connection.begin_nested`
.. index::
single: thread safety; Transaction
"""Represent a 'nested', or SAVEPOINT transaction.
A new :class:`.NestedTransaction` object may be procured
- using the :meth:`.Connection.begin_nested` method.
+ using the :meth:`_engine.Connection.begin_nested` method.
The interface is the same as that of :class:`.Transaction`.
"""Represent a two-phase transaction.
A new :class:`.TwoPhaseTransaction` object may be procured
- using the :meth:`.Connection.begin_twophase` method.
+ 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.
:class:`~sqlalchemy.engine.interfaces.Dialect` together to provide a
source of database connectivity and behavior.
- An :class:`.Engine` object is instantiated publicly using the
+ An :class:`_engine.Engine` object is instantiated publicly using the
:func:`~sqlalchemy.create_engine` function.
.. seealso::
def update_execution_options(self, **opt):
r"""Update the default execution_options dictionary
- of this :class:`.Engine`.
+ of this :class:`_engine.Engine`.
The given keys/values in \**opt are added to the
default execution options that will be used for
.. seealso::
- :meth:`.Connection.execution_options`
+ :meth:`_engine.Connection.execution_options`
- :meth:`.Engine.execution_options`
+ :meth:`_engine.Engine.execution_options`
"""
self._execution_options = self._execution_options.union(opt)
self.dialect.set_engine_execution_options(self, opt)
def execution_options(self, **opt):
- """Return a new :class:`.Engine` that will provide
- :class:`.Connection` objects with the given execution options.
+ """Return a new :class:`_engine.Engine` that will provide
+ :class:`_engine.Connection` objects with the given execution options.
- The returned :class:`.Engine` remains related to the original
- :class:`.Engine` in that it shares the same connection pool and
+ 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` used by the new :class:`.Engine` is the
- same instance. The :meth:`.Engine.dispose` method will replace
+ * 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`
+ * 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` individually.
+ with the new :class:`_engine.Engine` individually.
* The logging configuration and logging_name is copied from the parent
- :class:`.Engine`.
+ :class:`_engine.Engine`.
- The intent of the :meth:`.Engine.execution_options` method is
- to implement "sharding" schemes where multiple :class:`.Engine`
+ The intent of the :meth:`_engine.Engine.execution_options` method is
+ to implement "sharding" schemes where multiple :class:`_engine.Engine`
objects refer to the same connection pool, but are differentiated
by options that would be consumed by a custom event::
shard2 = primary_engine.execution_options(shard_id="shard2")
Above, the ``shard1`` engine serves as a factory for
- :class:`.Connection` objects that will contain the execution option
- ``shard_id=shard1``, and ``shard2`` will produce :class:`.Connection`
+ :class:`_engine.Connection`
+ objects that will contain the execution option
+ ``shard_id=shard1``, and ``shard2`` will produce
+ :class:`_engine.Connection`
objects that contain the execution option ``shard_id=shard2``.
An event handler can consume the above execution option to perform
a schema switch or other operation, given a connection. Below
we emit a MySQL ``use`` statement to switch databases, at the same
time keeping track of which database we've established using the
- :attr:`.Connection.info` dictionary, which gives us a persistent
+ :attr:`_engine.Connection.info` dictionary,
+ which gives us a persistent
storage space that follows the DBAPI connection::
from sqlalchemy import event
.. seealso::
- :meth:`.Connection.execution_options` - update execution options
- on a :class:`.Connection` object.
+ :meth:`_engine.Connection.execution_options`
+ - update execution options
+ on a :class:`_engine.Connection` object.
- :meth:`.Engine.update_execution_options` - update the execution
- options for a given :class:`.Engine` in place.
+ :meth:`_engine.Engine.update_execution_options`
+ - update the execution
+ options for a given :class:`_engine.Engine` in place.
- :meth:`.Engine.get_execution_options`
+ :meth:`_engine.Engine.get_execution_options`
"""
.. seealso::
- :meth:`.Engine.execution_options`
+ :meth:`_engine.Engine.execution_options`
"""
return self._execution_options
return "Engine(%r)" % self.url
def dispose(self):
- """Dispose of the connection pool used by this :class:`.Engine`.
+ """Dispose of the connection pool used by this :class:`_engine.Engine`
+ .
This 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`, so when they are closed individually,
- eventually the :class:`.Pool` which they are associated with will
+ 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.
A new connection pool is created immediately after the old one has
been disposed. This new pool, like all SQLAlchemy connection pools,
does not make any actual connections to the database until one is
- first requested, so as long as the :class:`.Engine` isn't used again,
+ first requested, so as long as the :class:`_engine.Engine`
+ isn't used again,
no new connections will be made.
.. seealso::
self.conn.close()
def begin(self, close_with_result=False):
- """Return a context manager delivering a :class:`.Connection`
+ """Return a context manager delivering a :class:`_engine.Connection`
with a :class:`.Transaction` established.
E.g.::
is rolled back.
The ``close_with_result`` flag is normally ``False``, and indicates
- that the :class:`.Connection` will be closed when the operation
+ that the :class:`_engine.Connection` will be closed when the operation
is complete. When set to ``True``, it indicates the
- :class:`.Connection` is in "single use" mode, where the
+ :class:`_engine.Connection` is in "single use" mode, where the
:class:`.ResultProxy` returned by the first call to
- :meth:`.Connection.execute` will close the :class:`.Connection` when
+ :meth:`_engine.Connection.execute` will close the
+ :class:`_engine.Connection` when
that :class:`.ResultProxy` has exhausted all result rows.
.. seealso::
- :meth:`.Engine.connect` - procure a :class:`.Connection` from
- an :class:`.Engine`.
+ :meth:`_engine.Engine.connect` - procure a
+ :class:`_engine.Connection` from
+ an :class:`_engine.Engine`.
- :meth:`.Connection.begin` - start a :class:`.Transaction`
- for a particular :class:`.Connection`.
+ :meth:`_engine.Connection.begin` - start a :class:`.Transaction`
+ for a particular :class:`_engine.Connection`.
"""
conn = self.connect(close_with_result=close_with_result)
@util.deprecated(
"1.4",
- "The :meth:`.Engine.transaction` method is deprecated and will be "
- "removed in a future release. Use the :meth:`.Engine.begin` context "
+ "The :meth:`_engine.Engine.transaction` "
+ "method is deprecated and will be "
+ "removed in a future release. Use the :meth:`_engine.Engine.begin` "
+ "context "
"manager instead.",
)
def transaction(self, callable_, *args, **kwargs):
r"""Execute the given function within a transaction boundary.
- The function is passed a :class:`.Connection` newly procured
- from :meth:`.Engine.connect` as the first argument,
+ The function is passed a :class:`_engine.Connection` newly procured
+ from :meth:`_engine.Engine.connect` as the first argument,
followed by the given \*args and \**kwargs.
e.g.::
The :meth:`.transaction` method is superseded by
the usage of the Python ``with:`` statement, which can
- be used with :meth:`.Engine.begin`::
+ be used with :meth:`_engine.Engine.begin`::
with engine.begin() as conn:
conn.execute(text("some statement"), {'x':5, 'y':10})
.. seealso::
- :meth:`.Engine.begin` - engine-level transactional
+ :meth:`_engine.Engine.begin` - engine-level transactional
context
- :meth:`.Connection.transaction` - connection-level version of
- :meth:`.Engine.transaction`
+ :meth:`_engine.Connection.transaction`
+ - connection-level version of
+ :meth:`_engine.Engine.transaction`
"""
kwargs["_sa_skip_warning"] = True
@util.deprecated(
"1.4",
- "The :meth:`.Engine.run_callable` method is deprecated and will be "
- "removed in a future release. Use the :meth:`.Engine.connect` "
+ "The :meth:`_engine.Engine.run_callable` "
+ "method is deprecated and will be "
+ "removed in a future release. Use the :meth:`_engine.Engine.connect` "
"context manager instead.",
)
def run_callable(self, callable_, *args, **kwargs):
r"""Given a callable object or function, execute it, passing
- a :class:`.Connection` as the first argument.
+ a :class:`_engine.Connection` as the first argument.
The given \*args and \**kwargs are passed subsequent
- to the :class:`.Connection` argument.
+ to the :class:`_engine.Connection` argument.
- This function, along with :meth:`.Connection.run_callable`,
- allows a function to be run with a :class:`.Connection`
- or :class:`.Engine` object without the need to know
+ This function, along with :meth:`_engine.Connection.run_callable`,
+ allows a function to be run with a :class:`_engine.Connection`
+ or :class:`_engine.Engine` object without the need to know
which one is being dealt with.
"""
conn._run_ddl_visitor(visitorcallable, element, **kwargs)
@util.deprecated_20(
- ":meth:`.Engine.execute`",
+ ":meth:`_engine.Engine.execute`",
alternative="All statement execution in SQLAlchemy 2.0 is performed "
- "by the :meth:`.Connection.execute` method of :class:`.Connection`, "
+ "by the :meth:`_engine.Connection.execute` method of "
+ ":class:`_engine.Connection`, "
"or in the ORM by the :meth:`.Session.execute` method of "
":class:`.Session`.",
)
"""Executes the given construct and returns a :class:`.ResultProxy`.
The arguments are the same as those used by
- :meth:`.Connection.execute`.
+ :meth:`_engine.Connection.execute`.
- Here, a :class:`.Connection` is acquired using the
- :meth:`~.Engine.connect` method, and the statement executed
+ Here, a :class:`_engine.Connection` is acquired using the
+ :meth:`_engine.Engine.connect` method, and the statement executed
with that connection. The returned :class:`.ResultProxy` is flagged
such that when the :class:`.ResultProxy` is exhausted and its
- underlying cursor is closed, the :class:`.Connection` created here
+ underlying cursor is closed, the :class:`_engine.Connection`
+ created here
will also be closed, which allows its associated DBAPI connection
resource to be returned to the connection pool.
return connection.execute(statement, *multiparams, **params)
@util.deprecated_20(
- ":meth:`.Engine.scalar`",
+ ":meth:`_engine.Engine.scalar`",
alternative="All statement execution in SQLAlchemy 2.0 is performed "
- "by the :meth:`.Connection.execute` method of :class:`.Connection`, "
+ "by the :meth:`_engine.Connection.execute` method of "
+ ":class:`_engine.Connection`, "
"or in the ORM by the :meth:`.Session.execute` method of "
":class:`.Session`; the :meth:`.Result.scalar` method can then be "
"used to return a scalar result.",
return connection._execute_compiled(compiled, multiparams, params)
def connect(self, close_with_result=False):
- """Return a new :class:`.Connection` object.
+ """Return a new :class:`_engine.Connection` object.
- The :class:`.Connection` object is a facade that uses a DBAPI
+ The :class:`_engine.Connection` object is a facade that uses a DBAPI
connection internally in order to communicate with the database. This
- connection is procured from the connection-holding :class:`.Pool`
- referenced by this :class:`.Engine`. When the
- :meth:`~.Connection.close` method of the :class:`.Connection` object
+ connection is procured from the connection-holding :class:`_pool.Pool`
+ referenced by this :class:`_engine.Engine`. When the
+ :meth:`_engine.Connection.close` method of the
+ :class:`_engine.Connection` object
is called, the underlying DBAPI connection is then returned to the
connection pool, where it may be used again in a subsequent call to
- :meth:`~.Engine.connect`.
+ :meth:`_engine.Engine.connect`.
"""
@util.deprecated(
"1.4",
- "The :meth:`.Engine.table_names` method is deprecated and will be "
+ "The :meth:`_engine.Engine.table_names` "
+ "method is deprecated and will be "
"removed in a future release. Please refer to "
- ":meth:`.Inspector.get_table_names`.",
+ ":meth:`_reflection.Inspector.get_table_names`.",
)
def table_names(self, schema=None, connection=None):
"""Return a list of all table names available in the database.
@util.deprecated(
"1.4",
- "The :meth:`.Engine.has_table` method is deprecated and will be "
+ "The :meth:`_engine.Engine.has_table` "
+ "method is deprecated and will be "
"removed in a future release. Please refer to "
- ":meth:`.Inspector.has_table`.",
+ ":meth:`_reflection.Inspector.has_table`.",
)
def has_table(self, table_name, schema=None):
"""Return True if the given backend has a table of the given name.
.. seealso::
:ref:`metadata_reflection_inspector` - detailed schema inspection
- using the :class:`.Inspector` interface.
+ using the :class:`_reflection.Inspector` interface.
:class:`.quoted_name` - used to pass quoting information along
with a schema identifier.
for real.
This method provides direct DBAPI connection access for
- special situations when the API provided by :class:`.Connection`
- is not needed. When a :class:`.Connection` object is already
+ 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:`.Connection.connection` accessor.
+ the :attr:`_engine.Connection.connection` accessor.
.. seealso::
),
)
def create_engine(url, **kwargs):
- """Create a new :class:`.Engine` instance.
+ """Create a new :class:`_engine.Engine` instance.
The standard calling form is to send the URL as the
first positional argument, usually a string
engine = create_engine("postgresql://scott:tiger@localhost/test")
Additional keyword arguments may then follow it which
- establish various options on the resulting :class:`.Engine`
- and its underlying :class:`.Dialect` and :class:`.Pool`
+ establish various options on the resulting :class:`_engine.Engine`
+ and its underlying :class:`.Dialect` and :class:`_pool.Pool`
constructs::
engine = create_engine("mysql://scott:tiger@hostname/dbname",
``**kwargs`` takes a wide variety of options which are routed
towards their appropriate components. Arguments may be specific to
- the :class:`.Engine`, the underlying :class:`.Dialect`, as well as the
- :class:`.Pool`. Specific dialects also accept keyword arguments that
+ 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:`.create_engine()` usage.
- Once established, the newly resulting :class:`.Engine` will
- request a connection from the underlying :class:`.Pool` once
- :meth:`.Engine.connect` is called, or a method which depends on it
- such as :meth:`.Engine.execute` is invoked. The :class:`.Pool` in turn
+ 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:`.create_engine` call itself does **not**
establish any actual DBAPI connections directly.
individual dialects should be consulted directly.
Note that the isolation level can also be set on a
- per-:class:`.Connection` basis as well, using the
+ per-:class:`_engine.Connection` basis as well, using the
:paramref:`.Connection.execution_options.isolation_level`
feature.
.. seealso::
- :attr:`.Connection.default_isolation_level` - view default level
+ :attr:`_engine.Connection.default_isolation_level`
+ - view default level
:paramref:`.Connection.execution_options.isolation_level`
- - set per :class:`.Connection` isolation level
+ - set per :class:`_engine.Connection` isolation level
:ref:`SQLite Transaction Isolation <sqlite_isolation_level>`
:ref:`session_transaction_isolation` - for the ORM
- :param json_deserializer: for dialects that support the :class:`.JSON`
+ :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:`.JSON`
+ :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.
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`.
+ inject "mock" DBAPI implementations into the :class:`_engine.Engine`.
:param paramstyle=None: The `paramstyle <http://legacy.python.org/dev/peps/pep-0249/#paramstyle>`_
to use when rendering bound parameters. This style defaults to the
:ref:`pool_setting_recycle`
:param pool_reset_on_return='rollback': set the
- :paramref:`.Pool.reset_on_return` parameter of the underlying
- :class:`.Pool` object, which can be set to the values
+ :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::
- :paramref:`.Pool.reset_on_return`
+ :paramref:`_pool.Pool.reset_on_return`
:param pool_timeout=30: number of seconds to wait before giving
up on getting a connection from the pool. This is only used
This method looks for a dictionary called
``colspecs`` as a class or instance-level variable,
- and passes on to :func:`.types.adapt_type`.
+ and passes on to :func:`_types.adapt_type`.
"""
return sqltypes.adapt_type(typeobj, self.colspecs)
generation function, e.g. as described at :ref:`context_default_functions`.
It consists of a dictionary which includes entries for each column/value
pair that is to be part of the INSERT or UPDATE statement. The keys of the
- dictionary will be the key value of each :class:`.Column`, which is usually
+ dictionary will be the key value of each :class:`_schema.Column`,
+ which is usually
synonymous with the name.
Note that the :attr:`.DefaultExecutionContext.current_parameters` attribute
does not accommodate for the "multi-values" feature of the
- :meth:`.Insert.values` method. The
+ :meth:`_expression.Insert.values` method. The
:meth:`.DefaultExecutionContext.get_current_parameters` method should be
preferred.
:ref:`context_default_functions`. When invoked, a dictionary is
returned which includes entries for each column/value pair that is part
of the INSERT or UPDATE statement. The keys of the dictionary will be
- the key value of each :class:`.Column`, which is usually synonymous
+ the key value of each :class:`_schema.Column`,
+ which is usually synonymous
with the name.
:param isolate_multiinsert_groups=True: indicates that multi-valued
- INSERT constructs created using :meth:`.Insert.values` should be
+ INSERT constructs created using :meth:`_expression.Insert.values`
+ should be
handled by returning only the subset of parameters that are local
to the current column default invocation. When ``False``, the
raw parameters of the statement are returned including the
class ConnectionEvents(event.Events):
"""Available events for :class:`.Connectable`, which includes
- :class:`.Connection` and :class:`.Engine`.
+ :class:`_engine.Connection` and :class:`_engine.Engine`.
The methods here define the name of an event as well as the names of
members that are passed to listener functions.
An event listener can be associated with any :class:`.Connectable`
- class or instance, such as an :class:`.Engine`, e.g.::
+ class or instance, such as an :class:`_engine.Engine`, e.g.::
from sqlalchemy import event, create_engine
engine = create_engine('postgresql://scott:tiger@localhost/test')
event.listen(engine, "before_cursor_execute", before_cursor_execute)
- or with a specific :class:`.Connection`::
+ or with a specific :class:`_engine.Connection`::
with engine.begin() as conn:
@event.listens_for(conn, 'before_cursor_execute')
return statement, parameters
.. note:: :class:`.ConnectionEvents` can be established on any
- combination of :class:`.Engine`, :class:`.Connection`, as well
+ combination of :class:`_engine.Engine`, :class:`_engine.Connection`,
+ as well
as instances of each of those classes. Events across all
four scopes will fire off for a given instance of
- :class:`.Connection`. However, for performance reasons, the
- :class:`.Connection` object determines at instantiation time
- whether or not its parent :class:`.Engine` has event listeners
- established. Event listeners added to the :class:`.Engine`
- class or to an instance of :class:`.Engine` *after* the instantiation
- of a dependent :class:`.Connection` instance will usually
- *not* be available on that :class:`.Connection` instance. The newly
- added listeners will instead take effect for :class:`.Connection`
+ :class:`_engine.Connection`. However, for performance reasons, the
+ :class:`_engine.Connection` object determines at instantiation time
+ whether or not its parent :class:`_engine.Engine` has event listeners
+ established. Event listeners added to the :class:`_engine.Engine`
+ class or to an instance of :class:`_engine.Engine`
+ *after* the instantiation
+ of a dependent :class:`_engine.Connection` instance will usually
+ *not* be available on that :class:`_engine.Connection` instance.
+ The newly
+ added listeners will instead take effect for
+ :class:`_engine.Connection`
instances created subsequent to those event listeners being
- established on the parent :class:`.Engine` class or instance.
+ established on the parent :class:`_engine.Engine` class or instance.
:param retval=False: Applies to the :meth:`.before_execute` and
:meth:`.before_cursor_execute` events only. When True, the
# do something with clauseelement, multiparams, params
return clauseelement, multiparams, params
- :param conn: :class:`.Connection` object
+ :param conn: :class:`_engine.Connection` object
:param clauseelement: SQL expression construct, :class:`.Compiled`
- instance, or string statement passed to :meth:`.Connection.execute`.
+ instance, or string statement passed to
+ :meth:`_engine.Connection.execute`.
:param multiparams: Multiple parameter sets, a list of dictionaries.
:param params: Single parameter set, a single dictionary.
"""Intercept high level execute() events after execute.
- :param conn: :class:`.Connection` object
+ :param conn: :class:`_engine.Connection` object
:param clauseelement: SQL expression construct, :class:`.Compiled`
- instance, or string statement passed to :meth:`.Connection.execute`.
+ instance, or string statement passed to
+ :meth:`_engine.Connection.execute`.
:param multiparams: Multiple parameter sets, a list of dictionaries.
:param params: Single parameter set, a single dictionary.
:param result: :class:`.ResultProxy` generated by the execution.
See the example at :class:`.ConnectionEvents`.
- :param conn: :class:`.Connection` object
+ :param conn: :class:`_engine.Connection` object
:param cursor: DBAPI cursor object
:param statement: string SQL statement, as to be passed to the DBAPI
:param parameters: Dictionary, tuple, or list of parameters being
):
"""Intercept low-level cursor execute() events after execution.
- :param conn: :class:`.Connection` object
+ :param conn: :class:`_engine.Connection` object
:param cursor: DBAPI cursor object. Will have results pending
if the statement was a SELECT, but these should not be consumed
as they will be needed by the :class:`.ResultProxy`.
"""
def handle_error(self, exception_context):
- r"""Intercept all exceptions processed by the :class:`.Connection`.
+ r"""Intercept all exceptions processed by the
+ :class:`_engine.Connection`.
This includes all exceptions emitted by the DBAPI as well as
within SQLAlchemy's statement invocation process, including
``False``.
.. versionchanged:: 1.0.0 The :meth:`.handle_error` event is now
- invoked when an :class:`.Engine` fails during the initial
- call to :meth:`.Engine.connect`, as well as when a
- :class:`.Connection` object encounters an error during a
+ invoked when an :class:`_engine.Engine` fails during the initial
+ call to :meth:`_engine.Engine.connect`, as well as when a
+ :class:`_engine.Connection` object encounters an error during a
reconnect operation.
.. versionchanged:: 1.0.0 The :meth:`.handle_error` event is
"""
def engine_connect(self, conn, branch):
- """Intercept the creation of a new :class:`.Connection`.
+ """Intercept the creation of a new :class:`_engine.Connection`.
This event is called typically as the direct result of calling
- the :meth:`.Engine.connect` method.
+ the :meth:`_engine.Engine.connect` method.
- It differs from the :meth:`.PoolEvents.connect` method, which
+ It differs from the :meth:`_events.PoolEvents.connect` method, which
refers to the actual connection to a database at the DBAPI level;
a DBAPI connection may be pooled and reused for many operations.
In contrast, this event refers only to the production of a higher level
- :class:`.Connection` wrapper around such a DBAPI connection.
+ :class:`_engine.Connection` wrapper around such a DBAPI connection.
- It also differs from the :meth:`.PoolEvents.checkout` event
- in that it is specific to the :class:`.Connection` object, not the
- DBAPI connection that :meth:`.PoolEvents.checkout` deals with, although
+ It also differs from the :meth:`_events.PoolEvents.checkout` event
+ in that it is specific to the :class:`_engine.Connection` object,
+ not the
+ DBAPI connection that :meth:`_events.PoolEvents.checkout` deals with,
+ although
this DBAPI connection is available here via the
- :attr:`.Connection.connection` attribute. But note there can in fact
- be multiple :meth:`.PoolEvents.checkout` events within the lifespan
- of a single :class:`.Connection` object, if that :class:`.Connection`
+ :attr:`_engine.Connection.connection` attribute.
+ But note there can in fact
+ be multiple :meth:`_events.PoolEvents.checkout`
+ events within the lifespan
+ of a single :class:`_engine.Connection` object, if that
+ :class:`_engine.Connection`
is invalidated and re-established. There can also be multiple
- :class:`.Connection` objects generated for the same already-checked-out
- DBAPI connection, in the case that a "branch" of a :class:`.Connection`
+ :class:`_engine.Connection`
+ objects generated for the same already-checked-out
+ DBAPI connection, in the case that a "branch" of a
+ :class:`_engine.Connection`
is produced.
- :param conn: :class:`.Connection` object.
+ :param conn: :class:`_engine.Connection` object.
:param branch: if True, this is a "branch" of an existing
- :class:`.Connection`. A branch is generated within the course
+ :class:`_engine.Connection`. A branch is generated within the course
of a statement execution to invoke supplemental statements, most
typically to pre-execute a SELECT of a default value for the purposes
of an INSERT statement.
to transparently ensure pooled connections are connected to the
database.
- :meth:`.PoolEvents.checkout` the lower-level pool checkout event
+ :meth:`_events.PoolEvents.checkout`
+ the lower-level pool checkout event
for an individual DBAPI connection
:meth:`.ConnectionEvents.set_connection_execution_options` - a copy
- of a :class:`.Connection` is also made when the
- :meth:`.Connection.execution_options` method is called.
+ of a :class:`_engine.Connection` is also made when the
+ :meth:`_engine.Connection.execution_options` method is called.
"""
def set_connection_execution_options(self, conn, opts):
- """Intercept when the :meth:`.Connection.execution_options`
+ """Intercept when the :meth:`_engine.Connection.execution_options`
method is called.
- This method is called after the new :class:`.Connection` has been
+ This method is called after the new :class:`_engine.Connection`
+ has been
produced, with the newly updated execution options collection, but
before the :class:`.Dialect` has acted upon any of those new options.
- Note that this method is not called when a new :class:`.Connection`
+ Note that this method is not called when a new
+ :class:`_engine.Connection`
is produced which is inheriting execution options from its parent
- :class:`.Engine`; to intercept this condition, use the
+ :class:`_engine.Engine`; to intercept this condition, use the
:meth:`.ConnectionEvents.engine_connect` event.
- :param conn: The newly copied :class:`.Connection` object
+ :param conn: The newly copied :class:`_engine.Connection` object
:param opts: dictionary of options that were passed to the
- :meth:`.Connection.execution_options` method.
+ :meth:`_engine.Connection.execution_options` method.
.. versionadded:: 0.9.0
.. seealso::
:meth:`.ConnectionEvents.set_engine_execution_options` - event
- which is called when :meth:`.Engine.execution_options` is called.
+ which is called when :meth:`_engine.Engine.execution_options`
+ is called.
"""
def set_engine_execution_options(self, engine, opts):
- """Intercept when the :meth:`.Engine.execution_options`
+ """Intercept when the :meth:`_engine.Engine.execution_options`
method is called.
- The :meth:`.Engine.execution_options` method produces a shallow
- copy of the :class:`.Engine` which stores the new options. That new
- :class:`.Engine` is passed here. A particular application of this
+ The :meth:`_engine.Engine.execution_options` method produces a shallow
+ copy of the :class:`_engine.Engine` which stores the new options.
+ That new
+ :class:`_engine.Engine` is passed here.
+ A particular application of this
method is to add a :meth:`.ConnectionEvents.engine_connect` event
- handler to the given :class:`.Engine` which will perform some per-
- :class:`.Connection` task specific to these execution options.
+ handler to the given :class:`_engine.Engine`
+ which will perform some per-
+ :class:`_engine.Connection` task specific to these execution options.
- :param conn: The newly copied :class:`.Engine` object
+ :param conn: The newly copied :class:`_engine.Engine` object
:param opts: dictionary of options that were passed to the
- :meth:`.Connection.execution_options` method.
+ :meth:`_engine.Connection.execution_options` method.
.. versionadded:: 0.9.0
.. seealso::
:meth:`.ConnectionEvents.set_connection_execution_options` - event
- which is called when :meth:`.Connection.execution_options` is
+ which is called when :meth:`_engine.Connection.execution_options`
+ is
called.
"""
def engine_disposed(self, engine):
- """Intercept when the :meth:`.Engine.dispose` method is called.
+ """Intercept when the :meth:`_engine.Engine.dispose` method is called.
- The :meth:`.Engine.dispose` method instructs the engine to
- "dispose" of it's connection pool (e.g. :class:`.Pool`), and
+ The :meth:`_engine.Engine.dispose` method instructs the engine to
+ "dispose" of it's connection pool (e.g. :class:`_pool.Pool`), and
replaces it with a new one. Disposing of the old pool has the
effect that existing checked-in connections are closed. The new
pool does not establish any new connections until it is first used.
This event can be used to indicate that resources related to the
- :class:`.Engine` should also be cleaned up, keeping in mind that the
- :class:`.Engine` can still be used for new requests in which case
+ :class:`_engine.Engine` should also be cleaned up,
+ keeping in mind that the
+ :class:`_engine.Engine`
+ can still be used for new requests in which case
it re-acquires connection resources.
.. versionadded:: 1.0.5
def begin(self, conn):
"""Intercept begin() events.
- :param conn: :class:`.Connection` object
+ :param conn: :class:`_engine.Connection` object
"""
"""Intercept rollback() events, as initiated by a
:class:`.Transaction`.
- Note that the :class:`.Pool` also "auto-rolls back"
+ Note that the :class:`_pool.Pool` also "auto-rolls back"
a DBAPI connection upon checkin, if the ``reset_on_return``
flag is set to its default value of ``'rollback'``.
To intercept this
- rollback, use the :meth:`.PoolEvents.reset` hook.
+ rollback, use the :meth:`_events.PoolEvents.reset` hook.
- :param conn: :class:`.Connection` object
+ :param conn: :class:`_engine.Connection` object
.. seealso::
- :meth:`.PoolEvents.reset`
+ :meth:`_events.PoolEvents.reset`
"""
"""Intercept commit() events, as initiated by a
:class:`.Transaction`.
- Note that the :class:`.Pool` may also "auto-commit"
+ Note that the :class:`_pool.Pool` may also "auto-commit"
a DBAPI connection upon checkin, if the ``reset_on_return``
flag is set to the value ``'commit'``. To intercept this
- commit, use the :meth:`.PoolEvents.reset` hook.
+ commit, use the :meth:`_events.PoolEvents.reset` hook.
- :param conn: :class:`.Connection` object
+ :param conn: :class:`_engine.Connection` object
"""
def savepoint(self, conn, name):
"""Intercept savepoint() events.
- :param conn: :class:`.Connection` object
+ :param conn: :class:`_engine.Connection` object
:param name: specified name used for the savepoint.
"""
def rollback_savepoint(self, conn, name, context):
"""Intercept rollback_savepoint() events.
- :param conn: :class:`.Connection` object
+ :param conn: :class:`_engine.Connection` object
:param name: specified name used for the savepoint.
:param context: :class:`.ExecutionContext` in use. May be ``None``.
def release_savepoint(self, conn, name, context):
"""Intercept release_savepoint() events.
- :param conn: :class:`.Connection` object
+ :param conn: :class:`_engine.Connection` object
:param name: specified name used for the savepoint.
:param context: :class:`.ExecutionContext` in use. May be ``None``.
def begin_twophase(self, conn, xid):
"""Intercept begin_twophase() events.
- :param conn: :class:`.Connection` object
+ :param conn: :class:`_engine.Connection` object
:param xid: two-phase XID identifier
"""
def prepare_twophase(self, conn, xid):
"""Intercept prepare_twophase() events.
- :param conn: :class:`.Connection` object
+ :param conn: :class:`_engine.Connection` object
:param xid: two-phase XID identifier
"""
def rollback_twophase(self, conn, xid, is_prepared):
"""Intercept rollback_twophase() events.
- :param conn: :class:`.Connection` object
+ :param conn: :class:`_engine.Connection` object
:param xid: two-phase XID identifier
:param is_prepared: boolean, indicates if
:meth:`.TwoPhaseTransaction.prepare` was called.
def commit_twophase(self, conn, xid, is_prepared):
"""Intercept commit_twophase() events.
- :param conn: :class:`.Connection` object
+ :param conn: :class:`_engine.Connection` object
:param xid: two-phase XID identifier
:param is_prepared: boolean, indicates if
:meth:`.TwoPhaseTransaction.prepare` was called.
"""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
+ :func:`_types.adapt_type` function in the types module to
accomplish this.
The returned result is cached *per dialect class* so can
def get_columns(self, connection, table_name, schema=None, **kw):
"""Return information about columns in `table_name`.
- Given a :class:`.Connection`, a string
+ Given a :class:`_engine.Connection`, a string
`table_name`, and an optional string `schema`, return column
information as a list of dictionaries with these keys:
"""Return information about the primary key constraint on
table_name`.
- Given a :class:`.Connection`, a string
+ Given a :class:`_engine.Connection`, a string
`table_name`, and an optional string `schema`, return primary
key information as a dictionary with these keys:
def get_foreign_keys(self, connection, table_name, schema=None, **kw):
"""Return information about foreign_keys in `table_name`.
- Given a :class:`.Connection`, a string
+ Given a :class:`_engine.Connection`, a string
`table_name`, and an optional string `schema`, return foreign
key information as a list of dicts with these keys:
def get_view_definition(self, connection, view_name, schema=None, **kw):
"""Return view definition.
- Given a :class:`.Connection`, a string
+ Given a :class:`_engine.Connection`, a string
`view_name`, and an optional string `schema`, return the view
definition.
"""
def get_indexes(self, connection, table_name, schema=None, **kw):
"""Return information about indexes in `table_name`.
- Given a :class:`.Connection`, a string
+ Given a :class:`_engine.Connection`, a string
`table_name` and an optional string `schema`, return index
information as a list of dictionaries with these keys:
def has_table(self, connection, table_name, schema=None, **kw):
"""Check the existence of a particular table in the database.
- Given a :class:`.Connection` object and a string
+ Given a :class:`_engine.Connection` object and a string
`table_name`, return True if the given table (possibly within
the specified `schema`) exists in the database, False
otherwise.
def has_index(self, connection, table_name, index_name, schema=None):
"""Check the existence of a particular index name in the database.
- Given a :class:`.Connection` object, a string
+ Given a :class:`_engine.Connection` object, a string
`table_name` and stiring index name, return True if an index of the
given name on the given table exists, false otherwise.
def has_sequence(self, connection, sequence_name, schema=None, **kw):
"""Check the existence of a particular sequence in the database.
- Given a :class:`.Connection` object and a string
+ Given a :class:`_engine.Connection` object and a string
`sequence_name`, return True if the given sequence exists in
the database, False otherwise.
"""
:meth:`.Dialect.do_autocommit`
hook is provided for DBAPIs that need some extra commands emitted
after a commit in order to enter the next transaction, when the
- SQLAlchemy :class:`.Connection` is used in its default "autocommit"
+ SQLAlchemy :class:`_engine.Connection`
+ is used in its default "autocommit"
mode.
:param dbapi_connection: a DBAPI connection, typically
"""Provide an implementation of ``connection.close()``, given a DBAPI
connection.
- This hook is called by the :class:`.Pool` when a connection has been
+ 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.
def do_savepoint(self, connection, name):
"""Create a savepoint with the given name.
- :param connection: a :class:`.Connection`.
+ :param connection: a :class:`_engine.Connection`.
:param name: savepoint name.
"""
def do_rollback_to_savepoint(self, connection, name):
"""Rollback a connection to the named savepoint.
- :param connection: a :class:`.Connection`.
+ :param connection: a :class:`_engine.Connection`.
:param name: savepoint name.
"""
def do_release_savepoint(self, connection, name):
"""Release the named savepoint on a connection.
- :param connection: a :class:`.Connection`.
+ :param connection: a :class:`_engine.Connection`.
:param name: savepoint name.
"""
def do_begin_twophase(self, connection, xid):
"""Begin a two phase transaction on the given connection.
- :param connection: a :class:`.Connection`.
+ :param connection: a :class:`_engine.Connection`.
:param xid: xid
"""
def do_prepare_twophase(self, connection, xid):
"""Prepare a two phase transaction on the given connection.
- :param connection: a :class:`.Connection`.
+ :param connection: a :class:`_engine.Connection`.
:param xid: xid
"""
):
"""Rollback a two phase transaction on the given connection.
- :param connection: a :class:`.Connection`.
+ :param connection: a :class:`_engine.Connection`.
:param xid: xid
:param is_prepared: whether or not
:meth:`.TwoPhaseTransaction.prepare` was called.
"""Commit a two phase transaction on the given connection.
- :param connection: a :class:`.Connection`.
+ :param connection: a :class:`_engine.Connection`.
:param xid: xid
:param is_prepared: whether or not
:meth:`.TwoPhaseTransaction.prepare` was called.
"""Recover list of uncommitted prepared two phase transaction
identifiers on the given connection.
- :param connection: a :class:`.Connection`.
+ :param connection: a :class:`_engine.Connection`.
"""
isolation modes, Unicode modes, etc.
The "do_on_connect" callable is invoked by using the
- :meth:`.PoolEvents.first_connect` and :meth:`.PoolEvents.connect` event
+ :meth:`_events.PoolEvents.first_connect` and
+ :meth:`_events.PoolEvents.connect` event
hooks, then unwrapping the DBAPI connection and passing it into the
callable. The reason it is invoked for both events is so that any
dialect-level initialization that occurs upon first connection, which
- also makes use of the :meth:`.PoolEvents.first_connect` method, will
+ also makes use of the :meth:`_events.PoolEvents.first_connect` method,
+ will
proceed after this hook has been called. This currently means the
hook is in fact called twice for the very first connection in which a
dialect creates; and once per connection afterwards.
"""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:`.Connection` and
- :class:`.Engine`
+ 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:`.Connection.get_isolation_level` - view current level
+ :meth:`_engine.Connection.get_isolation_level`
+ - view current level
- :attr:`.Connection.default_isolation_level` - view default level
+ :attr:`_engine.Connection.default_isolation_level`
+ - view default level
:paramref:`.Connection.execution_options.isolation_level` -
- set per :class:`.Connection` isolation level
+ set per :class:`_engine.Connection` isolation level
:paramref:`.create_engine.isolation_level` -
- set per :class:`.Engine` isolation level
+ set per :class:`_engine.Engine` isolation level
"""
"""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:`.Connection` and
- :class:`.Engine`
+ 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:`.Connection.get_isolation_level` - view current level
+ :meth:`_engine.Connection.get_isolation_level`
+ - view current level
- :attr:`.Connection.default_isolation_level` - view default level
+ :attr:`_engine.Connection.default_isolation_level`
+ - view default level
:paramref:`.Connection.execution_options.isolation_level` -
- set per :class:`.Connection` isolation level
+ set per :class:`_engine.Connection` isolation level
:paramref:`.create_engine.isolation_level` -
- set per :class:`.Engine` isolation level
+ set per :class:`_engine.Engine` isolation level
"""
def get_isolation_level(self, dbapi_conn):
"""Given a DBAPI connection, return its isolation level.
- When working with a :class:`.Connection` object, the corresponding
+ When working with a :class:`_engine.Connection` object,
+ the corresponding
DBAPI connection may be procured using the
- :attr:`.Connection.connection` accessor.
+ :attr:`_engine.Connection.connection` accessor.
Note that this is a dialect-level method which is used as part
- of the implementation of the :class:`.Connection` and
- :class:`.Engine` isolation level facilities;
+ 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:`.Connection.get_isolation_level` - view current level
+ :meth:`_engine.Connection.get_isolation_level`
+ - view current level
- :attr:`.Connection.default_isolation_level` - view default level
+ :attr:`_engine.Connection.default_isolation_level`
+ - view default level
:paramref:`.Connection.execution_options.isolation_level` -
- set per :class:`.Connection` isolation level
+ set per :class:`_engine.Connection` isolation level
:paramref:`.create_engine.isolation_level` -
- set per :class:`.Engine` isolation level
+ set per :class:`_engine.Engine` isolation level
"""
@classmethod
def engine_created(cls, engine):
- """A convenience hook called before returning the final :class:`.Engine`.
+ """A convenience hook called before returning the final
+ :class:`_engine.Engine`.
If the dialect returned a different class from the
:meth:`.get_dialect_cls`
class CreateEnginePlugin(object):
"""A set of hooks intended to augment the construction of an
- :class:`.Engine` object based on entrypoint names in a URL.
+ :class:`_engine.Engine` object based on entrypoint names in a URL.
The purpose of :class:`.CreateEnginePlugin` is to allow third-party
systems to apply engine, pool and dialect level event listeners without
arguments afterwards.
When the engine creation process completes and produces the
- :class:`.Engine` object, it is again passed to the plugin via the
+ :class:`_engine.Engine` object, it is again passed to the plugin via the
:meth:`.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`).
"""Construct a new :class:`.CreateEnginePlugin`.
The plugin object is instantiated individually for each call
- to :func:`.create_engine`. A single :class:`.Engine` will be
+ to :func:`.create_engine`. A single :class:`_engine.Engine` will be
passed to the :meth:`.CreateEnginePlugin.engine_created` method
corresponding to this URL.
"""parse and modify pool kwargs"""
def engine_created(self, engine):
- """Receive the :class:`.Engine` object when it is fully constructed.
+ """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.
@util.deprecated_20_cls(
":class:`.Connectable`",
alternative=(
- "The :class:`.Engine` will be the only Core "
+ "The :class:`_engine.Engine` will be the only Core "
"object that features a .connect() method, and the "
- ":class:`.Connection` will be the only object that features "
+ ":class:`_engine.Connection` will be the only object that features "
"an .execute() method."
),
constructor=None,
"""Interface for an object which supports execution of SQL constructs.
The two implementations of :class:`.Connectable` are
- :class:`.Connection` and :class:`.Engine`.
+ :class:`_engine.Connection` and :class:`_engine.Engine`.
Connectable must also implement the 'dialect' member which references a
:class:`.Dialect` instance.
"""
def connect(self, **kwargs):
- """Return a :class:`.Connection` object.
+ """Return a :class:`_engine.Connection` object.
Depending on context, this may be ``self`` if this object
- is already an instance of :class:`.Connection`, or a newly
- procured :class:`.Connection` if this object is an instance
- of :class:`.Engine`.
+ is already an instance of :class:`_engine.Connection`, or a newly
+ procured :class:`_engine.Connection` if this object is an instance
+ of :class:`_engine.Engine`.
"""
engine = None
- """The :class:`.Engine` instance referred to by this :class:`.Connectable`.
+ """The :class:`_engine.Engine` instance referred to by this
+ :class:`.Connectable`.
- May be ``self`` if this is already an :class:`.Engine`.
+ May be ``self`` if this is already an :class:`_engine.Engine`.
"""
"""
connection = None
- """The :class:`.Connection` in use during the exception.
+ """The :class:`_engine.Connection` in use during the exception.
This member is present, except in the case of a failure when
first connecting.
"""
engine = None
- """The :class:`.Engine` in use during the exception.
+ """The :class:`_engine.Engine` in use during the exception.
This member should always be present, even in the case of a failure
when first connecting.
"""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:`.MetaData.create_all` and related methods.
+ 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
consistent interface as well as caching support for previously
fetched metadata.
- A :class:`.Inspector` object is usually created via the
- :func:`.inspect` function, which may be passed an :class:`.Engine`
- or a :class:`.Connection`::
+ 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:`.Inspector` subclass that
+ with the engine may opt to return an :class:`_reflection.Inspector`
+ subclass that
provides additional methods specific to the dialect's target database.
"""
@util.deprecated(
"1.4",
- "The __init__() method on :class:`.Inspector` is deprecated and "
+ "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` or :class:`.Connection` in order to "
- "acquire an :class:`.Inspector`.",
+ "function on an :class:`_engine.Engine` or "
+ ":class:`_engine.Connection` "
+ "in order to "
+ "acquire an :class:`_reflection.Inspector`.",
)
def __init__(self, bind):
- """Initialize a new :class:`.Inspector`.
+ """Initialize a new :class:`_reflection.Inspector`.
:param bind: a :class:`~sqlalchemy.engine.Connectable`,
which is typically an instance of
:class:`~sqlalchemy.engine.Engine` or
:class:`~sqlalchemy.engine.Connection`.
- For a dialect-specific instance of :class:`.Inspector`, see
- :meth:`.Inspector.from_engine`
+ For a dialect-specific instance of :class:`_reflection.Inspector`, see
+ :meth:`_reflection.Inspector.from_engine`
"""
return self._init_legacy(bind)
@classmethod
@util.deprecated(
"1.4",
- "The from_engine() method on :class:`.Inspector` is deprecated and "
+ "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` or :class:`.Connection` in order to "
- "acquire an :class:`.Inspector`.",
+ "function on an :class:`_engine.Engine` or "
+ ":class:`_engine.Connection` "
+ "in order to "
+ "acquire an :class:`_reflection.Inspector`.",
)
def from_engine(cls, bind):
"""Construct a new dialect-specific Inspector object from the given
:class:`~sqlalchemy.engine.Connection`.
This method differs from direct a direct constructor call of
- :class:`.Inspector` in that the
+ :class:`_reflection.Inspector` in that the
:class:`~sqlalchemy.engine.interfaces.Dialect` is given a chance to
- provide a dialect-specific :class:`.Inspector` instance, which may
+ provide a dialect-specific :class:`_reflection.Inspector` instance,
+ which may
provide additional methods.
- See the example at :class:`.Inspector`.
+ See the example at :class:`_reflection.Inspector`.
"""
return cls._construct(cls._init_legacy, bind)
transaction.
This essentially allows connect()/close() to be called if we detected
- that we're against an :class:`.Engine` and not a :class:`.Connection`.
+ that we're against an :class:`_engine.Engine` and not a
+ :class:`_engine.Connection`.
"""
if self._op_context_requires_connect:
@contextlib.contextmanager
def _inspection_context(self):
- """Return an :class:`.Inspector` from this one that will run all
+ """Return an :class:`_reflection.Inspector`
+ from this one that will run all
operations on a single connection.
"""
"""Return all table names in referred to within a particular schema.
The names are expected to be real tables only, not views.
- Views are instead returned using the :meth:`.Inspector.get_view_names`
+ Views are instead returned using the
+ :meth:`_reflection.Inspector.get_view_names`
method.
.. seealso::
- :meth:`.Inspector.get_sorted_table_and_fkc_names`
+ :meth:`_reflection.Inspector.get_sorted_table_and_fkc_names`
- :attr:`.MetaData.sorted_tables`
+ :attr:`_schema.MetaData.sorted_tables`
"""
.. seealso::
- :meth:`.Inspector.get_table_names`
+ :meth:`_reflection.Inspector.get_table_names`
:func:`.sort_tables_and_constraints` - similar method which works
- with an already-given :class:`.MetaData`.
+ with an already-given :class:`_schema.MetaData`.
"""
)
@util.deprecated_20(
- ":meth:`.Inspector.reflecttable`",
- "The :meth:`.Inspector.reflecttable` method was renamed to "
- ":meth:`.Inspector.reflect_table`. This deprecated alias "
+ ":meth:`_reflection.Inspector.reflecttable`",
+ "The :meth:`_reflection.Inspector.reflecttable` "
+ "method was renamed to "
+ ":meth:`_reflection.Inspector.reflect_table`. This deprecated alias "
"will be removed in a future release.",
)
def reflecttable(self, *args, **kwargs):
The remaining fairly common case is that of the textual SQL
that includes at least partial column information; this is when
- we use a :class:`.TextualSelect` construct. This construct may have
+ we use a :class:`_expression.TextualSelect` construct.
+ This construct may have
unordered or ordered column information. In the ordered case, we
merge the cursor.description and the compiled construct's information
positionally, and warn if there are additional description names
SQLAlchemy for all cases up through te 0.9 series. Positional
matching for compiled SQL expressions was introduced in 1.0 as a
major performance feature, and positional matching for textual
- :class:`.TextualSelect` objects in 1.1. As name matching is no longer
+ :class:`_expression.TextualSelect` objects in 1.1.
+ As name matching is no longer
a common case, it was acceptable to factor it into smaller generator-
oriented methods that are easier to understand, but incur slightly
more performance overhead.
corresponding to the list of primary key columns
in the target table.
- This only applies to single row :func:`~.sql.expression.insert`
+ This only applies to single row :func:`_expression.insert`
constructs which did not explicitly specify
- :meth:`.Insert.returning`.
+ :meth:`_expression.Insert.returning`.
Note that primary key columns which specify a
server_default clause,
or otherwise do not qualify as "autoincrement"
- columns (see the notes at :class:`.Column`), and were
+ 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
def is_insert(self):
"""True if this :class:`.ResultProxy` is the result
of a executing an expression language compiled
- :func:`.expression.insert` construct.
+ :func:`_expression.insert` construct.
When True, this implies that the
:attr:`inserted_primary_key` attribute is accessible,
In the case of a result that is the product of
:ref:`connectionless execution <dbengine_implicit>`,
- the underlying :class:`.Connection` object is also closed, which
+ the underlying :class:`_engine.Connection` object is also closed,
+ which
:term:`releases` DBAPI connection resources.
.. deprecated:: 2.0 "connectionless" execution is deprecated and will
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:`.MetaData.sorted_tables` operation, two :class:`.ForeignKey`
- or :class:`.ForeignKeyConstraint` objects mutually refer to each
+ * 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`.
"""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:`.PoolEvents.checkout` event so that the host pool
+ 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.
class InvalidatePoolError(DisconnectionError):
"""Raised when the connection pool should invalidate all stale connections.
- A subclass of :class:`.DisconnectionError` that indicates that the
+ 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:`.DisconnectionError`, allowing three attempts to reconnect
+ :class:`_exc.DisconnectionError`, allowing three attempts to reconnect
before giving up.
.. versionadded:: 1.2
class SAPendingDeprecationWarning(PendingDeprecationWarning):
- """A similar warning as :class:`.SADeprecationWarning`, this warning
+ """A similar warning as :class:`_exc.SADeprecationWarning`, this warning
is not used in modern versions of SQLAlchemy.
"""
and/or subclassed directly.
:param target_collection: Name of the collection we'll proxy to,
- usually created with :func:`.relationship`.
+ usually created with :func:`_orm.relationship`.
:param attr: Attribute on the collected instances we'll proxy
for. For example, given a target collection of [obj1, obj2], a
keywords = association_proxy('kws', 'keyword')
If we access this :class:`.AssociationProxy` from
- :attr:`.Mapper.all_orm_descriptors`, and we want to view the
+ :attr:`_orm.Mapper.all_orm_descriptors`, and we want to view the
target class for this proxy as mapped by ``User``::
inspect(User).all_orm_descriptors["keywords"].for_class(User).target_class
"""Return a tuple of ``(local_attr, remote_attr)``.
This attribute is convenient when specifying a join
- using :meth:`.Query.join` across two relationships::
+ using :meth:`_query.Query.join` across two relationships::
sess.query(Parent).join(*Parent.proxied.attr)
Above, calling :meth:`.AutomapBase.prepare` while passing along the
:paramref:`.AutomapBase.prepare.reflect` parameter indicates that the
-:meth:`.MetaData.reflect` method will be called on this declarative base
-classes' :class:`.MetaData` collection; then, each **viable**
-:class:`.Table` within the :class:`.MetaData` will get a new mapped class
-generated automatically. The :class:`.ForeignKeyConstraint` objects which
+:meth:`_schema.MetaData.reflect`
+method will be called on this declarative base
+classes' :class:`_schema.MetaData` collection; then, each **viable**
+:class:`_schema.Table` within the :class:`_schema.MetaData`
+will get a new mapped class
+generated automatically. The :class:`_schema.ForeignKeyConstraint`
+objects which
link the various tables together will be used to produce new, bidirectional
-:func:`.relationship` objects between classes. The classes and relationships
+:func:`_orm.relationship` objects between classes.
+The classes and relationships
follow along a default naming scheme that we can customize. At this point,
our basic mapping consisting of related ``User`` and ``Address`` classes is
ready to use in the traditional way.
Generating Mappings from an Existing MetaData
=============================================
-We can pass a pre-declared :class:`.MetaData` object to :func:`.automap_base`.
+We can pass a pre-declared :class:`_schema.MetaData` object to
+:func:`.automap_base`.
This object can be constructed in any way, including programmatically, from
a serialized file, or from itself being reflected using
-:meth:`.MetaData.reflect`. Below we illustrate a combination of reflection and
+:meth:`_schema.MetaData.reflect`.
+Below we illustrate a combination of reflection and
explicit table declaration::
from sqlalchemy import create_engine, MetaData, Table, Column, ForeignKey
print (a1.user)
Above, one of the more intricate details is that we illustrated overriding
-one of the :func:`.relationship` objects that automap would have created.
+one of the :func:`_orm.relationship` objects that automap would have created.
To do this, we needed to make sure the names match up with what automap
would normally generate, in that the relationship name would be
``User.address_collection`` and the name of the class referred to, from
======================
The vast majority of what automap accomplishes is the generation of
-:func:`.relationship` structures based on foreign keys. The mechanism
+:func:`_orm.relationship` structures based on foreign keys. The mechanism
by which this works for many-to-one and one-to-many relationships is as
follows:
-1. A given :class:`.Table`, known to be mapped to a particular class,
- is examined for :class:`.ForeignKeyConstraint` objects.
+1. A given :class:`_schema.Table`, known to be mapped to a particular class,
+ is examined for :class:`_schema.ForeignKeyConstraint` objects.
-2. From each :class:`.ForeignKeyConstraint`, the remote :class:`.Table`
+2. From each :class:`_schema.ForeignKeyConstraint`, the remote
+ :class:`_schema.Table`
object present is matched up to the class to which it is to be mapped,
if any, else it is skipped.
-3. As the :class:`.ForeignKeyConstraint` we are examining corresponds to a
+3. As the :class:`_schema.ForeignKeyConstraint`
+ we are examining corresponds to a
reference from the immediate mapped class, the relationship will be set up
as a many-to-one referring to the referred class; a corresponding
one-to-many backref will be created on the referred class referring
to this class.
-4. If any of the columns that are part of the :class:`.ForeignKeyConstraint`
+4. If any of the columns that are part of the
+ :class:`_schema.ForeignKeyConstraint`
are not nullable (e.g. ``nullable=False``), a
- :paramref:`~.relationship.cascade` keyword argument
+ :paramref:`_orm.relationship.cascade` keyword argument
of ``all, delete-orphan`` will be added to the keyword arguments to
be passed to the relationship or backref. If the
- :class:`.ForeignKeyConstraint` reports that
- :paramref:`.ForeignKeyConstraint.ondelete`
+ :class:`_schema.ForeignKeyConstraint` reports that
+ :paramref:`_schema.ForeignKeyConstraint.ondelete`
is set to ``CASCADE`` for a not null or ``SET NULL`` for a nullable
- set of columns, the option :paramref:`~.relationship.passive_deletes`
+ set of columns, the option :paramref:`_orm.relationship.passive_deletes`
flag is set to ``True`` in the set of relationship keyword arguments.
Note that not all backends support reflection of ON DELETE.
.. versionadded:: 1.0.0 - automap will detect non-nullable foreign key
constraints when producing a one-to-many relationship and establish
a default cascade of ``all, delete-orphan`` if so; additionally,
- if the constraint specifies :paramref:`.ForeignKeyConstraint.ondelete`
+ if the constraint specifies
+ :paramref:`_schema.ForeignKeyConstraint.ondelete`
of ``CASCADE`` for non-nullable or ``SET NULL`` for nullable columns,
the ``passive_deletes=True`` option is also added.
6. The classes are inspected for an existing mapped property matching these
names. If one is detected on one side, but none on the other side,
:class:`.AutomapBase` attempts to create a relationship on the missing side,
- then uses the :paramref:`.relationship.back_populates` parameter in order to
+ then uses the :paramref:`_orm.relationship.back_populates`
+ parameter in order to
point the new relationship to the other side.
7. In the usual case where no relationship is on either side,
- :meth:`.AutomapBase.prepare` produces a :func:`.relationship` on the
+ :meth:`.AutomapBase.prepare` produces a :func:`_orm.relationship` on the
"many-to-one" side and matches it to the other using the
- :paramref:`.relationship.backref` parameter.
+ :paramref:`_orm.relationship.backref` parameter.
-8. Production of the :func:`.relationship` and optionally the :func:`.backref`
+8. Production of the :func:`_orm.relationship` and optionally the
+ :func:`.backref`
is handed off to the :paramref:`.AutomapBase.prepare.generate_relationship`
function, which can be supplied by the end-user in order to augment
- the arguments passed to :func:`.relationship` or :func:`.backref` or to
+ the arguments passed to :func:`_orm.relationship` or :func:`.backref` or to
make use of custom implementations of these functions.
Custom Relationship Arguments
arguments.
Below is an illustration of how to send
-:paramref:`.relationship.cascade` and
-:paramref:`.relationship.passive_deletes`
+:paramref:`_orm.relationship.cascade` and
+:paramref:`_orm.relationship.passive_deletes`
options along to all one-to-many relationships::
from sqlalchemy.ext.automap import generate_relationship
those which contain a ``secondary`` argument. The process for producing these
is as follows:
-1. A given :class:`.Table` is examined for :class:`.ForeignKeyConstraint`
+1. A given :class:`_schema.Table` is examined for
+ :class:`_schema.ForeignKeyConstraint`
objects, before any mapped class has been assigned to it.
-2. If the table contains two and exactly two :class:`.ForeignKeyConstraint`
+2. If the table contains two and exactly two
+ :class:`_schema.ForeignKeyConstraint`
objects, and all columns within this table are members of these two
- :class:`.ForeignKeyConstraint` objects, the table is assumed to be a
+ :class:`_schema.ForeignKeyConstraint` objects, the table is assumed to be a
"secondary" table, and will **not be mapped directly**.
3. The two (or one, for self-referential) external tables to which the
- :class:`.Table` refers to are matched to the classes to which they will be
+ :class:`_schema.Table`
+ refers to are matched to the classes to which they will be
mapped, if any.
4. If mapped classes for both sides are located, a many-to-many bi-directional
- :func:`.relationship` / :func:`.backref` pair is created between the two
+ :func:`_orm.relationship` / :func:`.backref`
+ pair is created between the two
classes.
5. The override logic for many-to-many works the same as that of one-to-many/
========================================
As noted previously, automap has no dependency on reflection, and can make
-use of any collection of :class:`.Table` objects within a :class:`.MetaData`
+use of any collection of :class:`_schema.Table` objects within a
+:class:`_schema.MetaData`
collection. From this, it follows that automap can also be used
generate missing relationships given an otherwise complete model that fully
defines table metadata::
assert a1.user is u1
Above, given mostly complete ``User`` and ``Address`` mappings, the
-:class:`.ForeignKey` which we defined on ``Address.user_id`` allowed a
+:class:`_schema.ForeignKey` which we defined on ``Address.user_id`` allowed a
bidirectional relationship pair ``Address.user`` and
``User.address_collection`` to be generated on the mapped classes.
:param base: the :class:`.AutomapBase` class doing the prepare.
- :param tablename: string name of the :class:`.Table`.
+ :param tablename: string name of the :class:`_schema.Table`.
- :param table: the :class:`.Table` object itself.
+ :param table: the :class:`_schema.Table` object itself.
:return: a string class name.
In Python 2, the string used for the class name **must** be a
non-Unicode object, e.g. a ``str()`` object. The ``.name`` attribute
- of :class:`.Table` is typically a Python unicode subclass, so the
+ of :class:`_schema.Table` is typically a Python unicode subclass,
+ so the
``str()`` function should be applied to this name, after accounting for
any non-ASCII characters.
:param referred_cls: the class to be mapped on the referring side.
- :param constraint: the :class:`.ForeignKeyConstraint` that is being
+ :param constraint: the :class:`_schema.ForeignKeyConstraint` that is being
inspected to produce this relationship.
"""
:param referred_cls: the class to be mapped on the referring side.
- :param constraint: the :class:`.ForeignKeyConstraint` that is being
+ :param constraint: the :class:`_schema.ForeignKeyConstraint` that is being
inspected to produce this relationship.
"""
def generate_relationship(
base, direction, return_fn, attrname, local_cls, referred_cls, **kw
):
- r"""Generate a :func:`.relationship` or :func:`.backref` on behalf of two
+ r"""Generate a :func:`_orm.relationship` or :func:`.backref`
+ on behalf of two
mapped classes.
An alternate implementation of this function can be specified using the
be one of :data:`.ONETOMANY`, :data:`.MANYTOONE`, :data:`.MANYTOMANY`.
:param return_fn: the function that is used by default to create the
- relationship. This will be either :func:`.relationship` or
+ relationship. This will be either :func:`_orm.relationship` or
:func:`.backref`. The :func:`.backref` function's result will be used to
- produce a new :func:`.relationship` in a second step, so it is critical
+ produce a new :func:`_orm.relationship` in a second step,
+ so it is critical
that user-defined implementations correctly differentiate between the two
functions, if a custom relationship function is being used.
:param \**kw: all additional keyword arguments are passed along to the
function.
- :return: a :func:`.relationship` or :func:`.backref` construct, as dictated
+ :return: a :func:`_orm.relationship` or :func:`.backref` construct,
+ as dictated
by the :paramref:`.generate_relationship.return_fn` parameter.
"""
name_for_collection_relationship=name_for_collection_relationship,
generate_relationship=generate_relationship,
):
- """Extract mapped classes and relationships from the :class:`.MetaData` and
+ """Extract mapped classes and relationships from the
+ :class:`_schema.MetaData` and
perform mappings.
- :param engine: an :class:`.Engine` or :class:`.Connection` with which
+ :param engine: an :class:`_engine.Engine` or
+ :class:`_engine.Connection` with which
to perform schema reflection, if specified.
If the :paramref:`.AutomapBase.prepare.reflect` argument is False,
this object is not used.
- :param reflect: if True, the :meth:`.MetaData.reflect` method is called
- on the :class:`.MetaData` associated with this :class:`.AutomapBase`.
- The :class:`.Engine` passed via
+ :param reflect: if True, the :meth:`_schema.MetaData.reflect`
+ method is called
+ on the :class:`_schema.MetaData` associated with this
+ :class:`.AutomapBase`.
+ The :class:`_engine.Engine` passed via
:paramref:`.AutomapBase.prepare.engine` will be used to perform the
- reflection if present; else, the :class:`.MetaData` should already be
+ reflection if present; else, the :class:`_schema.MetaData`
+ should already be
bound to some engine else the operation will fail.
:param classname_for_table: callable function which will be used to
relationships. Defaults to :func:`.name_for_collection_relationship`.
:param generate_relationship: callable function which will be used to
- actually generate :func:`.relationship` and :func:`.backref`
+ actually generate :func:`_orm.relationship` and :func:`.backref`
constructs. Defaults to :func:`.generate_relationship`.
:param collection_class: the Python collection class that will be used
- when a new :func:`.relationship` object is created that represents a
+ when a new :func:`_orm.relationship`
+ object is created that represents a
collection. Defaults to ``list``.
:param schema: When present in conjunction with the
:paramref:`.AutomapBase.prepare.reflect` flag, is passed to
- :meth:`.MetaData.reflect` to indicate the primary schema where tables
+ :meth:`_schema.MetaData.reflect`
+ to indicate the primary schema where tables
should be reflected from. When omitted, the default schema in use
by the database connection is used.
:class:`.BakedQuery` object subsequent to the spoil step will be
non-cached; the state of the :class:`.BakedQuery` up until
this point will be pulled from the cache. If True, then the
- entire :class:`.Query` object is built from scratch each
+ entire :class:`_query.Query` object is built from scratch each
time, with all creational functions being called on each
invocation.
:class:`.Session`.
This basically means we also will include the session's query_class,
- as the actual :class:`.Query` object is part of what's cached
- and needs to match the type of :class:`.Query` that a later
+ as the actual :class:`_query.Query` object is part of what's cached
+ and needs to match the type of :class:`_query.Query` that a later
session will want to use.
"""
return context
def to_query(self, query_or_session):
- """Return the :class:`.Query` object for use as a subquery.
+ """Return the :class:`_query.Query` object for use as a subquery.
This method should be used within the lambda callable being used
to generate a step of an enclosing :class:`.BakedQuery`. The
- parameter should normally be the :class:`.Query` object that
+ parameter should normally be the :class:`_query.Query` object that
is passed to the lambda::
sub_bq = self.bakery(lambda s: s.query(User.name))
Address.id, sub_bq.to_query(q).scalar_subquery())
)
- :param query_or_session: a :class:`.Query` object or a class
+ :param query_or_session: a :class:`_query.Query` object or a class
:class:`.Session` object, that is assumed to be within the context
of an enclosing :class:`.BakedQuery` callable.
"""Add a criteria function that will be applied post-cache.
This adds a function that will be run against the
- :class:`.Query` object after it is retrieved from the
+ :class:`_query.Query` object after it is retrieved from the
cache. Functions here can be used to alter the query in ways
that **do not affect the SQL output**, such as execution options
and shard identifiers (when using a shard-enabled query object)
.. warning:: :meth:`.Result.with_post_criteria` functions are applied
- to the :class:`.Query` object **after** the query's SQL statement
+ to the :class:`_query.Query`
+ object **after** the query's SQL statement
object has been retrieved from the cache. Any operations here
which intend to modify the SQL should ensure that
:meth:`.BakedQuery.spoil` was called first.
def count(self):
"""return the 'count'.
- Equivalent to :meth:`.Query.count`.
+ Equivalent to :meth:`_query.Query.count`.
Note this uses a subquery to ensure an accurate count regardless
of the structure of the original statement.
if no rows present. If multiple rows are returned,
raises MultipleResultsFound.
- Equivalent to :meth:`.Query.scalar`.
+ Equivalent to :meth:`_query.Query.scalar`.
.. versionadded:: 1.1.6
def first(self):
"""Return the first row.
- Equivalent to :meth:`.Query.first`.
+ Equivalent to :meth:`_query.Query.first`.
"""
bq = self.bq.with_criteria(lambda q: q.slice(0, 1))
def one(self):
"""Return exactly one result or raise an exception.
- Equivalent to :meth:`.Query.one`.
+ Equivalent to :meth:`_query.Query.one`.
"""
try:
"""Return one or zero results, or raise an exception for multiple
rows.
- Equivalent to :meth:`.Query.one_or_none`.
+ Equivalent to :meth:`_query.Query.one_or_none`.
.. versionadded:: 1.0.9
def all(self):
"""Return all rows.
- Equivalent to :meth:`.Query.all`.
+ Equivalent to :meth:`_query.Query.all`.
"""
return list(self)
def get(self, ident):
"""Retrieve an object based on identity.
- Equivalent to :meth:`.Query.get`.
+ Equivalent to :meth:`_query.Query.get`.
"""
This method now raises NotImplementedError() as the "baked" implementation
is the only lazy load implementation. The
- :paramref:`.relationship.bake_queries` flag may be used to disable
+ :paramref:`_orm.relationship.bake_queries` flag may be used to disable
the caching of queries on a per-relationship basis.
"""
The above ``InsertFromSelect`` construct is only an example, this actual
functionality is already available using the
- :meth:`.Insert.from_select` method.
+ :meth:`_expression.Insert.from_select` method.
.. note::
Enabling Autocommit on a Construct
==================================
-Recall from the section :ref:`autocommit` that the :class:`.Engine`, when
+Recall from the section :ref:`autocommit` that the :class:`_engine.Engine`,
+when
asked to execute a construct in the absence of a user-defined transaction,
detects if the given construct represents DML or DDL, that is, a data
modification or data definition statement, which requires (or may require,
More succinctly, if the construct is truly similar to an INSERT, UPDATE, or
DELETE, :class:`.UpdateBase` can be used, which already is a subclass
-of :class:`.Executable`, :class:`.ClauseElement` and includes the
+of :class:`.Executable`, :class:`_expression.ClauseElement` and includes the
``autocommit`` flag::
from sqlalchemy.sql.expression import UpdateBase
def compiles(class_, *specs):
"""Register a function as a compiler for a
- given :class:`.ClauseElement` type."""
+ given :class:`_expression.ClauseElement` type."""
def decorate(fn):
# get an existing @compiles handler
def deregister(class_):
"""Remove all custom compilers associated with a given
- :class:`.ClauseElement` type."""
+ :class:`_expression.ClauseElement` type."""
if hasattr(class_, "_compiler_dispatcher"):
# regenerate default _compiler_dispatch
def synonym_for(name, map_column=False):
- """Decorator that produces an :func:`.orm.synonym` attribute in conjunction
+ """Decorator that produces an :func:`_orm.synonym`
+ attribute in conjunction
with a Python descriptor.
- The function being decorated is passed to :func:`.orm.synonym` as the
+ The function being decorated is passed to :func:`_orm.synonym` as the
:paramref:`.orm.synonym.descriptor` parameter::
class MyClass(Base):
:ref:`synonyms` - Overview of synonyms
- :func:`.orm.synonym` - the mapper-level function
+ :func:`_orm.synonym` - the mapper-level function
:ref:`mapper_hybrids` - The Hybrid Attribute extension provides an
updated approach to augmenting attribute behavior more flexibly than
:param class_registry: optional dictionary that will serve as the
registry of class names-> mapped classes when string names
- are used to identify classes inside of :func:`.relationship`
+ are used to identify classes inside of :func:`_orm.relationship`
and others. Allows two or more declarative base classes
to share the same registry of class names for simplified
inter-base relationships.
.. seealso::
- :func:`.orm.configure_mappers`
+ :func:`_orm.configure_mappers`
Example::
a deferred reflection step.
Normally, declarative can be used with reflection by
- setting a :class:`.Table` object using autoload=True
+ setting a :class:`_schema.Table` object using autoload=True
as the ``__table__`` attribute on a declarative class.
- The caveat is that the :class:`.Table` must be fully
+ The caveat is that the :class:`_schema.Table` must be fully
reflected, or at the very least have a primary key column,
at the point at which a normal declarative mapping is
- constructed, meaning the :class:`.Engine` must be available
+ constructed, meaning the :class:`_engine.Engine` must be available
at class declaration time.
The :class:`.DeferredReflection` mixin moves the construction
of mappers to be at a later point, after a specific
- method is called which first reflects all :class:`.Table`
+ method is called which first reflects all :class:`_schema.Table`
objects created so far. Classes can define it as such::
from sqlalchemy.ext.declarative import declarative_base
@classmethod
def prepare(cls, engine):
- """Reflect all :class:`.Table` objects for all current
+ """Reflect all :class:`_schema.Table` objects for all current
:class:`.DeferredReflection` subclasses"""
to_map = _DeferredMapperConfig.classes_for_base(cls)
"""Routines to handle the string class registry used by declarative.
This system allows specification of classes and expressions used in
-:func:`.relationship` using strings.
+:func:`_orm.relationship` using strings.
"""
import weakref
possible identity tokens (e.g. shard ids).
.. versionchanged:: 1.4 Moved :meth:`.Session._identity_lookup` from
- the :class:`.Query` object to the :class:`.Session`.
+ the :class:`_query.Query` object to the :class:`.Session`.
"""
FROM interval
WHERE interval."end" - interval.start > :param_1
-ORM methods such as :meth:`~.Query.filter_by` generally use ``getattr()`` to
+ORM methods such as :meth:`_query.Query.filter_by`
+generally use ``getattr()`` to
locate attributes, so can also be used with hybrid attributes::
>>> print(Session().query(Interval).filter_by(length=5))
------------------------
A hybrid can define a custom "UPDATE" handler for when using the
-:meth:`.Query.update` method, allowing the hybrid to be used in the
+:meth:`_query.Query.update` method, allowing the hybrid to be used in the
SET clause of the update.
-Normally, when using a hybrid with :meth:`.Query.update`, the SQL
+Normally, when using a hybrid with :meth:`_query.Query.update`, the SQL
expression is used as the column that's the target of the SET. If our
``Interval`` class had a hybrid ``start_point`` that linked to
``Interval.start``, this could be substituted directly::
However, when using a composite hybrid like ``Interval.length``, this
hybrid represents more than one column. We can set up a handler that will
-accommodate a value passed to :meth:`.Query.update` which can affect
+accommodate a value passed to :meth:`_query.Query.update` which can affect
this, using the :meth:`.hybrid_property.update_expression` decorator.
A handler that works similarly to our setter would be::
Building Transformers
----------------------
-A *transformer* is an object which can receive a :class:`.Query` object and
-return a new one. The :class:`.Query` object includes a method
-:meth:`.with_transformation` that returns a new :class:`.Query` transformed by
+A *transformer* is an object which can receive a :class:`_query.Query`
+object and
+return a new one. The :class:`_query.Query` object includes a method
+:meth:`.with_transformation` that returns a new :class:`_query.Query`
+transformed by
the given function.
We can combine this with the :class:`.Comparator` class to produce one type
return self.parent.parent
For the expression, things are not so clear. We'd need to construct a
-:class:`.Query` where we :meth:`~.Query.join` twice along ``Node.parent`` to
+:class:`_query.Query` where we :meth:`_query.Query.join` twice along ``Node.
+parent`` to
get to the ``grandparent``. We can instead return a transforming callable
that we'll combine with the :class:`.Comparator` class to receive any
-:class:`.Query` object, and return a new one that's joined to the
+:class:`_query.Query` object, and return a new one that's joined to the
``Node.parent`` attribute and filtered based on the given criterion::
from sqlalchemy.ext.hybrid import Comparator
particular context. Such as, in the example above, the ``operate`` method is
called, given the :attr:`.Operators.eq` callable as well as the right side of
the comparison ``Node(id=5)``. A function ``transform`` is then returned which
-will transform a :class:`.Query` first to join to ``Node.parent``, then to
+will transform a :class:`_query.Query` first to join to ``Node.parent``,
+then to
compare ``parent_alias`` using :attr:`.Operators.eq` against the left and right
-sides, passing into :class:`.Query.filter`:
+sides, passing into :class:`_query.Query.filter`:
.. sourcecode:: pycon+sql
.. seealso::
- :attr:`.Mapper.all_orm_attributes`
+ :attr:`_orm.Mapper.all_orm_attributes`
"""
.. seealso::
- :attr:`.Mapper.all_orm_attributes`
+ :attr:`_orm.Mapper.all_orm_attributes`
"""
# the MIT License: http://www.opensource.org/licenses/mit-license.php
"""Define attributes on ORM-mapped classes that have "index" attributes for
-columns with :class:`~.types.Indexable` types.
+columns with :class:`_types.Indexable` types.
"index" means the attribute is associated with an element of an
-:class:`~.types.Indexable` column with the predefined index to access it.
-The :class:`~.types.Indexable` types include types such as
-:class:`~.types.ARRAY`, :class:`~.types.JSON` and
-:class:`~.postgresql.HSTORE`.
+:class:`_types.Indexable` column with the predefined index to access it.
+The :class:`_types.Indexable` types include types such as
+:class:`_types.ARRAY`, :class:`_types.JSON` and
+:class:`_postgresql.HSTORE`.
The :mod:`~sqlalchemy.ext.indexable` extension provides
-:class:`~.schema.Column`-like interface for any element of an
-:class:`~.types.Indexable` typed column. In simple cases, it can be
-treated as a :class:`~.schema.Column` - mapped attribute.
+:class:`_schema.Column`-like interface for any element of an
+:class:`_types.Indexable` typed column. In simple cases, it can be
+treated as a :class:`_schema.Column` - mapped attribute.
.. versionadded:: 1.1
return expr.astext.cast(self.cast_type)
The above subclass can be used with the PostgreSQL-specific
-version of :class:`.postgresql.JSON`::
+version of :class:`_postgresql.JSON`::
from sqlalchemy import Column, Integer
from sqlalchemy.ext.declarative import declarative_base
class index_property(hybrid_property): # noqa
"""A property generator. The generated property describes an object
- attribute that corresponds to an :class:`~.types.Indexable`
+ attribute that corresponds to an :class:`_types.Indexable`
column.
.. versionadded:: 1.1
The usage of ``json`` is only for the purposes of example. The
:mod:`sqlalchemy.ext.mutable` extension can be used
with any type whose target Python type may be mutable, including
-:class:`.PickleType`, :class:`.postgresql.ARRAY`, etc.
+:class:`.PickleType`, :class:`_postgresql.ARRAY`, etc.
When using the :mod:`sqlalchemy.ext.mutable` extension, the value itself
tracks all parents which reference it. Below, we illustrate a simple
return not self.__eq__(other)
The :class:`.MutableComposite` class uses a Python metaclass to automatically
-establish listeners for any usage of :func:`.orm.composite` that specifies our
+establish listeners for any usage of :func:`_orm.composite` that specifies our
``Point`` type. Below, when ``Point`` is mapped to the ``Vertex`` class,
listeners are established which will route change events from ``Point``
objects to each of the ``Vertex.start`` and ``Vertex.end`` attributes::
:author: Jason Kirtland
``orderinglist`` is a helper for mutable ordered relationships. It will
-intercept list operations performed on a :func:`.relationship`-managed
+intercept list operations performed on a :func:`_orm.relationship`-managed
collection and
automatically synchronize changes in list position onto a target scalar
attribute.
The :class:`.OrderingList` construct only works with **changes** to a
collection, and not the initial load from the database, and requires that the
list be sorted when loaded. Therefore, be sure to specify ``order_by`` on the
-:func:`.relationship` against the target ordering attribute, so that the
+:func:`_orm.relationship` against the target ordering attribute, so that the
ordering is correct when first loaded.
.. warning::
The :class:`.OrderingList` object is normally set up using the
:func:`.ordering_list` factory function, used in conjunction with
- the :func:`.relationship` function.
+ the :func:`_orm.relationship` function.
"""
# This module is part of SQLAlchemy and is released under
# the MIT License: http://www.opensource.org/licenses/mit-license.php
-"""The inspection module provides the :func:`.inspect` function,
+"""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:`.inspect` function is the entry point to SQLAlchemy's
+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:`.inspect`, the return value will either be
+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:`.inspect` is twofold. One is that
+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:`.Inspector.from_engine`,
-:func:`.orm.attributes.instance_state`, :func:`.orm.class_mapper`,
-and others. The other is that the return value of :func:`.inspect`
+getting" functions in SQLAlchemy, such as
+:meth:`_reflection.Inspector.from_engine`,
+: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.
The returned value in some cases may be the
same object as the one given, such as if a
- :class:`.Mapper` object is passed. In other
+ :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:`.Inspector` object is returned.
+ 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
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`
-and :class:`.Pool` objects, corresponds to a logger specific to that
+The "echo" keyword parameter, available on SQLA :class:`_engine.Engine`
+and :class:`_pool.Pool` objects, corresponds to a logger specific to that
instance only.
"""
not load unless accessed.
:param \*columns: columns to be mapped. This is typically a single
- :class:`.Column` object, however a collection is supported in order
+ :class:`_schema.Column` object,
+ however a collection is supported in order
to support multiple columns mapped under the same attribute.
:param raiseload: boolean, if True, indicates an exception should be raised
:class:`.MapperProperty`
- :attr:`.Mapper.all_orm_descriptors`
+ :attr:`_orm.Mapper.all_orm_descriptors`
- :attr:`.Mapper.attrs`
+ :attr:`_orm.Mapper.attrs`
"""
is_attribute = True
* If the attribute is a column-mapped property, i.e.
:class:`.ColumnProperty`, which is mapped directly
- to a schema-level :class:`.Column` object, this attribute
+ to a schema-level :class:`_schema.Column` object, this attribute
will return the :attr:`.SchemaItem.info` dictionary associated
- with the core-level :class:`.Column` object.
+ with the core-level :class:`_schema.Column` object.
* If the attribute is a :class:`.ColumnProperty` but is mapped to
- any other kind of SQL expression other than a :class:`.Column`,
+ any other kind of SQL expression other than a
+ :class:`_schema.Column`,
the attribute will refer to the :attr:`.MapperProperty.info`
dictionary associated directly with the :class:`.ColumnProperty`,
assuming the SQL expression itself does not have its own ``.info``
* To access the :attr:`.MapperProperty.info` dictionary of the
:class:`.MapperProperty` unconditionally, including for a
:class:`.ColumnProperty` that's associated directly with a
- :class:`.schema.Column`, the attribute can be referred to using
+ :class:`_schema.Column`, the attribute can be referred to using
:attr:`.QueryableAttribute.property` attribute, as
``MyClass.someattribute.property.info``.
def parent(self):
"""Return an inspection instance representing the parent.
- This will be either an instance of :class:`.Mapper`
+ This will be either an instance of :class:`_orm.Mapper`
or :class:`.AliasedInsp`, depending upon the nature
of the parent entity which this attribute is associated
with.
attribute.
The easiest way to get a :class:`.History` object for a particular
- attribute on an object is to use the :func:`.inspect` function::
+ attribute on an object is to use the :func:`_sa.inspect` function::
from sqlalchemy import inspect
ONETOMANY = util.symbol(
"ONETOMANY",
- """Indicates the one-to-many direction for a :func:`.relationship`.
+ """Indicates the one-to-many direction for a :func:`_orm.relationship`.
This symbol is typically used by the internals but may be exposed within
certain API features.
MANYTOONE = util.symbol(
"MANYTOONE",
- """Indicates the many-to-one direction for a :func:`.relationship`.
+ """Indicates the many-to-one direction for a :func:`_orm.relationship`.
This symbol is typically used by the internals but may be exposed within
certain API features.
MANYTOMANY = util.symbol(
"MANYTOMANY",
- """Indicates the many-to-many direction for a :func:`.relationship`.
+ """Indicates the many-to-many direction for a :func:`_orm.relationship`.
This symbol is typically used by the internals but may be exposed within
certain API features.
Raises :class:`sqlalchemy.orm.exc.UnmappedInstanceError`
if no mapping is configured.
- Equivalent functionality is available via the :func:`.inspect`
+ Equivalent functionality is available via the :func:`_sa.inspect`
function as::
inspect(instance)
def _mapper_or_none(entity):
- """Return the :class:`.Mapper` for the given class or None if the
+ """Return the :class:`_orm.Mapper` for the given class or None if the
class is not mapped.
"""
def _is_mapped_class(entity):
"""Return True if the given object is a mapped class,
- :class:`.Mapper`, or :class:`.AliasedClass`.
+ :class:`_orm.Mapper`, or :class:`.AliasedClass`.
"""
insp = inspection.inspect(entity, False)
def class_mapper(class_, configure=True):
- """Given a class, return the primary :class:`.Mapper` associated
+ """Given a class, return the primary :class:`_orm.Mapper` associated
with the key.
Raises :exc:`.UnmappedClassError` if no mapping is configured
on the given class, or :exc:`.ArgumentError` if a non-class
object is passed.
- Equivalent functionality is available via the :func:`.inspect`
+ Equivalent functionality is available via the :func:`_sa.inspect`
function as::
inspect(some_mapped_class)
class InspectionAttr(object):
"""A base class applied to all ORM objects that can be returned
- by the :func:`.inspect` function.
+ by the :func:`_sa.inspect` function.
The attributes defined here allow the usage of simple boolean
checks to test basic facts about the object returned.
__slots__ = ()
is_selectable = False
- """Return True if this object is an instance of :class:`.Selectable`."""
+ """Return True if this object is an instance of """
+ """:class:`expression.Selectable`."""
is_aliased_class = False
"""True if this object is an instance of :class:`.AliasedClass`."""
"""True if this object is an instance of :class:`.InstanceState`."""
is_mapper = False
- """True if this object is an instance of :class:`.Mapper`."""
+ """True if this object is an instance of :class:`_orm.Mapper`."""
is_property = False
"""True if this object is an instance of :class:`.MapperProperty`."""
.. seealso::
- :attr:`.Mapper.all_orm_descriptors`
+ :attr:`_orm.Mapper.all_orm_descriptors`
"""
"""
is_clause_element = False
- """True if this object is an instance of :class:`.ClauseElement`."""
+ """True if this object is an instance of """
+ """:class:`_expression.ClauseElement`."""
extension_type = NOT_EXTENSION
"""The extension type, if any.
The dictionary is generated when first accessed. Alternatively,
it can be specified as a constructor argument to the
- :func:`.column_property`, :func:`.relationship`, or :func:`.composite`
+ :func:`.column_property`, :func:`_orm.relationship`, or
+ :func:`.composite`
functions.
.. versionchanged:: 1.0.0 :attr:`.MapperProperty.info` is also
:param map_column: **For classical mappings and mappings against
an existing Table object only**. if ``True``, the :func:`.synonym`
- construct will locate the :class:`.Column` object upon the mapped
+ construct will locate the :class:`_schema.Column`
+ object upon the mapped
table that would normally be associated with the attribute name of
this synonym, and produce a new :class:`.ColumnProperty` that instead
- maps this :class:`.Column` to the alternate name given as the "name"
+ maps this :class:`_schema.Column`
+ to the alternate name given as the "name"
argument of the synonym; in this way, the usual step of redefining
- the mapping of the :class:`.Column` to be under a different name is
+ the mapping of the :class:`_schema.Column`
+ to be under a different name is
unnecessary. This is usually intended to be used when a
- :class:`.Column` is to be replaced with an attribute that also uses a
+ :class:`_schema.Column`
+ is to be replaced with an attribute that also uses a
descriptor, that is, in conjunction with the
:paramref:`.synonym.descriptor` parameter::
* mapped classes
* unmapped superclasses of mapped or to-be-mapped classes
(using the ``propagate=True`` flag)
- * :class:`.Mapper` objects
- * the :class:`.Mapper` class itself and the :func:`.mapper`
+ * :class:`_orm.Mapper` objects
+ * the :class:`_orm.Mapper` class itself and the :func:`.mapper`
function indicate listening for all mappers.
Instance events are closely related to mapper events, but
The :meth:`.InstanceEvents.load` event is also available in a
- class-method decorator format called :func:`.orm.reconstructor`.
+ class-method decorator format called :func:`_orm.reconstructor`.
:param target: the mapped instance. If
the event is configured with ``raw=True``, this will
instead be the :class:`.InstanceState` state-management
object associated with the instance.
:param context: the :class:`.QueryContext` corresponding to the
- current :class:`.Query` in progress. This argument may be
- ``None`` if the load does not correspond to a :class:`.Query`,
+ current :class:`_query.Query` in progress. This argument may be
+ ``None`` if the load does not correspond to a :class:`_query.Query`,
such as during :meth:`.Session.merge`.
.. seealso::
instead be the :class:`.InstanceState` state-management
object associated with the instance.
:param context: the :class:`.QueryContext` corresponding to the
- current :class:`.Query` in progress.
+ current :class:`_query.Query` in progress.
:param attrs: sequence of attribute names which
were populated, or None if all column-mapped, non-deferred
attributes were populated.
* mapped classes
* unmapped superclasses of mapped or to-be-mapped classes
(using the ``propagate=True`` flag)
- * :class:`.Mapper` objects
- * the :class:`.Mapper` class itself and the :func:`.mapper`
+ * :class:`_orm.Mapper` objects
+ * the :class:`_orm.Mapper` class itself and the :func:`.mapper`
function indicate listening for all mappers.
Mapper events provide hooks into critical sections of the
This event is the earliest phase of mapper construction.
Most attributes of the mapper are not yet initialized.
- This listener can either be applied to the :class:`.Mapper`
+ This listener can either be applied to the :class:`_orm.Mapper`
class overall, or to any un-mapped class which serves as a base
for classes that will be mapped (using the ``propagate=True`` flag)::
def on_new_class(mapper, cls_):
" ... "
- :param mapper: the :class:`.Mapper` which is the target
+ :param mapper: the :class:`_orm.Mapper` which is the target
of this event.
:param class\_: the mapped class.
The :meth:`.MapperEvents.mapper_configured` event is invoked
for each mapper that is encountered when the
- :func:`.orm.configure_mappers` function proceeds through the current
+ :func:`_orm.configure_mappers` function proceeds through the current
list of not-yet-configured mappers.
- :func:`.orm.configure_mappers` is typically invoked
+ :func:`_orm.configure_mappers` is typically invoked
automatically as mappings are first used, as well as each time
new mappers have been made available and new mapper use is
detected.
on a specific mapper basis, which don't require that "backref"
configurations are necessarily ready yet.
- :param mapper: the :class:`.Mapper` which is the target
+ :param mapper: the :class:`_orm.Mapper` which is the target
of this event.
:param class\_: the mapped class.
"""Called before a series of mappers have been configured.
The :meth:`.MapperEvents.before_configured` event is invoked
- each time the :func:`.orm.configure_mappers` function is
+ each time the :func:`_orm.configure_mappers` function is
invoked, before the function has done any of its work.
- :func:`.orm.configure_mappers` is typically invoked
+ :func:`_orm.configure_mappers` is typically invoked
automatically as mappings are first used, as well as each time
new mappers have been made available and new mapper use is
detected.
- This event can **only** be applied to the :class:`.Mapper` class
+ This event can **only** be applied to the :class:`_orm.Mapper` class
or :func:`.mapper` function, and not to individual mappings or
mapped classes. It is only invoked for all mappings as a whole::
Theoretically this event is called once per
application, but is actually called any time new mappers
- are to be affected by a :func:`.orm.configure_mappers`
+ are to be affected by a :func:`_orm.configure_mappers`
call. If new mappings are constructed after existing ones have
already been used, this event will likely be called again. To ensure
that a particular event is only called once and no further, the
"""Called after a series of mappers have been configured.
The :meth:`.MapperEvents.after_configured` event is invoked
- each time the :func:`.orm.configure_mappers` function is
+ each time the :func:`_orm.configure_mappers` function is
invoked, after the function has completed its work.
- :func:`.orm.configure_mappers` is typically invoked
+ :func:`_orm.configure_mappers` is typically invoked
automatically as mappings are first used, as well as each time
new mappers have been made available and new mapper use is
detected.
Also contrast to :meth:`.MapperEvents.before_configured`,
which is invoked before the series of mappers has been configured.
- This event can **only** be applied to the :class:`.Mapper` class
+ This event can **only** be applied to the :class:`_orm.Mapper` class
or :func:`.mapper` function, and not to individual mappings or
mapped classes. It is only invoked for all mappings as a whole::
Theoretically this event is called once per
application, but is actually called any time new mappers
- have been affected by a :func:`.orm.configure_mappers`
+ have been affected by a :func:`_orm.configure_mappers`
call. If new mappings are constructed after existing ones have
already been used, this event will likely be called again. To ensure
that a particular event is only called once and no further, the
Mapper-level flush events only allow **very limited operations**,
on attributes local to the row being operated upon only,
as well as allowing any SQL to be emitted on the given
- :class:`.Connection`. **Please read fully** the notes
+ :class:`_engine.Connection`. **Please read fully** the notes
at :ref:`session_persistence_mapper` for guidelines on using
these methods; generally, the :meth:`.SessionEvents.before_flush`
method should be preferred for general on-flush changes.
- :param mapper: the :class:`.Mapper` which is the target
+ :param mapper: the :class:`_orm.Mapper` which is the target
of this event.
- :param connection: the :class:`.Connection` being used to
+ :param connection: the :class:`_engine.Connection` being used to
emit INSERT statements for this instance. This
provides a handle into the current transaction on the
target database specific to this instance.
Mapper-level flush events only allow **very limited operations**,
on attributes local to the row being operated upon only,
as well as allowing any SQL to be emitted on the given
- :class:`.Connection`. **Please read fully** the notes
+ :class:`_engine.Connection`. **Please read fully** the notes
at :ref:`session_persistence_mapper` for guidelines on using
these methods; generally, the :meth:`.SessionEvents.before_flush`
method should be preferred for general on-flush changes.
- :param mapper: the :class:`.Mapper` which is the target
+ :param mapper: the :class:`_orm.Mapper` which is the target
of this event.
- :param connection: the :class:`.Connection` being used to
+ :param connection: the :class:`_engine.Connection` being used to
emit INSERT statements for this instance. This
provides a handle into the current transaction on the
target database specific to this instance.
Mapper-level flush events only allow **very limited operations**,
on attributes local to the row being operated upon only,
as well as allowing any SQL to be emitted on the given
- :class:`.Connection`. **Please read fully** the notes
+ :class:`_engine.Connection`. **Please read fully** the notes
at :ref:`session_persistence_mapper` for guidelines on using
these methods; generally, the :meth:`.SessionEvents.before_flush`
method should be preferred for general on-flush changes.
- :param mapper: the :class:`.Mapper` which is the target
+ :param mapper: the :class:`_orm.Mapper` which is the target
of this event.
- :param connection: the :class:`.Connection` being used to
+ :param connection: the :class:`_engine.Connection` being used to
emit UPDATE statements for this instance. This
provides a handle into the current transaction on the
target database specific to this instance.
Mapper-level flush events only allow **very limited operations**,
on attributes local to the row being operated upon only,
as well as allowing any SQL to be emitted on the given
- :class:`.Connection`. **Please read fully** the notes
+ :class:`_engine.Connection`. **Please read fully** the notes
at :ref:`session_persistence_mapper` for guidelines on using
these methods; generally, the :meth:`.SessionEvents.before_flush`
method should be preferred for general on-flush changes.
- :param mapper: the :class:`.Mapper` which is the target
+ :param mapper: the :class:`_orm.Mapper` which is the target
of this event.
- :param connection: the :class:`.Connection` being used to
+ :param connection: the :class:`_engine.Connection` being used to
emit UPDATE statements for this instance. This
provides a handle into the current transaction on the
target database specific to this instance.
Mapper-level flush events only allow **very limited operations**,
on attributes local to the row being operated upon only,
as well as allowing any SQL to be emitted on the given
- :class:`.Connection`. **Please read fully** the notes
+ :class:`_engine.Connection`. **Please read fully** the notes
at :ref:`session_persistence_mapper` for guidelines on using
these methods; generally, the :meth:`.SessionEvents.before_flush`
method should be preferred for general on-flush changes.
- :param mapper: the :class:`.Mapper` which is the target
+ :param mapper: the :class:`_orm.Mapper` which is the target
of this event.
- :param connection: the :class:`.Connection` being used to
+ :param connection: the :class:`_engine.Connection` being used to
emit DELETE statements for this instance. This
provides a handle into the current transaction on the
target database specific to this instance.
Mapper-level flush events only allow **very limited operations**,
on attributes local to the row being operated upon only,
as well as allowing any SQL to be emitted on the given
- :class:`.Connection`. **Please read fully** the notes
+ :class:`_engine.Connection`. **Please read fully** the notes
at :ref:`session_persistence_mapper` for guidelines on using
these methods; generally, the :meth:`.SessionEvents.before_flush`
method should be preferred for general on-flush changes.
- :param mapper: the :class:`.Mapper` which is the target
+ :param mapper: the :class:`_orm.Mapper` which is the target
of this event.
- :param connection: the :class:`.Connection` being used to
+ :param connection: the :class:`_engine.Connection` being used to
emit DELETE statements for this instance. This
provides a handle into the current transaction on the
target database specific to this instance.
:param session: The target :class:`.Session`.
:param transaction: The :class:`.SessionTransaction`.
- :param connection: The :class:`~.engine.Connection` object
+ :param connection: The :class:`_engine.Connection` object
which will be used for SQL statements.
.. seealso::
def after_bulk_update(self, update_context):
"""Execute after a bulk update operation to the session.
- This is called as a result of the :meth:`.Query.update` method.
+ This is called as a result of the :meth:`_query.Query.update` method.
:param update_context: an "update context" object which contains
details about the update, including these attributes:
* ``session`` - the :class:`.Session` involved
- * ``query`` -the :class:`.Query` object that this update operation
+ * ``query`` -the :class:`_query.Query`
+ object that this update operation
was called upon.
* ``values`` The "values" dictionary that was passed to
- :meth:`.Query.update`.
+ :meth:`_query.Query.update`.
* ``context`` The :class:`.QueryContext` object, corresponding
to the invocation of an ORM query.
* ``result`` the :class:`.ResultProxy` returned as a result of the
def after_bulk_delete(self, delete_context):
"""Execute after a bulk delete operation to the session.
- This is called as a result of the :meth:`.Query.delete` method.
+ This is called as a result of the :meth:`_query.Query.delete` method.
:param delete_context: a "delete context" object which contains
details about the update, including these attributes:
* ``session`` - the :class:`.Session` involved
- * ``query`` -the :class:`.Query` object that this update operation
+ * ``query`` -the :class:`_query.Query`
+ object that this update operation
was called upon.
* ``context`` The :class:`.QueryContext` object, corresponding
to the invocation of an ORM query.
replaced unconditionally, even if this requires firing off
database loads. Note that ``active_history`` can also be
set directly via :func:`.column_property` and
- :func:`.relationship`.
+ :func:`_orm.relationship`.
:param propagate=False: When True, the listener function will
be established not just for the class attribute given, but
Python's usual behavior of raising ``AttributeError``. The
event here can be used to customize what value is actually returned,
with the assumption that the event listener would be mirroring
- a default generator that is configured on the Core :class:`.Column`
+ a default generator that is configured on the Core
+ :class:`_schema.Column`
object as well.
- Since a default generator on a :class:`.Column` might also produce
+ Since a default generator on a :class:`_schema.Column`
+ might also produce
a changing value such as a timestamp, the
:meth:`.AttributeEvents.init_scalar`
event handler can also be used to **set** the newly returned value, so
* By setting the value ``SOME_CONSTANT`` in the given ``dict_``,
we indicate that this value is to be persisted to the database.
This supersedes the use of ``SOME_CONSTANT`` in the default generator
- for the :class:`.Column`. The ``active_column_defaults.py``
+ for the :class:`_schema.Column`. The ``active_column_defaults.py``
example given at :ref:`examples_instrumentation` illustrates using
the same approach for a changing default, e.g. a timestamp
generator. In this particular example, it is not strictly
In the above example, the attribute set event
:meth:`.AttributeEvents.set` as well as the related validation feature
- provided by :obj:`.orm.validates` is **not** invoked when we apply our
+ provided by :obj:`_orm.validates` is **not** invoked when we apply our
value to the given ``dict_``. To have these events to invoke in
response to our newly generated value, apply the value to the given
object as a normal attribute set operation::
be the :class:`.InstanceState` object.
:param collection: the new collection. This will always be generated
from what was specified as
- :paramref:`.relationship.collection_class`, and will always
+ :paramref:`_orm.relationship.collection_class`, and will always
be empty.
:param collection_adapter: the :class:`.CollectionAdapter` that will
mediate internal access to the collection.
class QueryEvents(event.Events):
- """Represent events within the construction of a :class:`.Query` object.
+ """Represent events within the construction of a :class:`_query.Query`
+ object.
The events here are intended to be used with an as-yet-unreleased
- inspection system for :class:`.Query`. Some very basic operations
+ inspection system for :class:`_query.Query`. Some very basic operations
are possible now, however the inspection system is intended to allow
complex query manipulations to be automated.
_dispatch_target = Query
def before_compile(self, query):
- """Receive the :class:`.Query` object before it is composed into a
- core :class:`.Select` object.
+ """Receive the :class:`_query.Query`
+ object before it is composed into a
+ core :class:`_expression.Select` object.
This event is intended to allow changes to the query given::
The :meth:`.QueryEvents.before_compile` event by default
will disallow "baked" queries from caching a query, if the event
- hook returns a new :class:`.Query` object. This affects both direct
+ hook returns a new :class:`_query.Query` object.
+ This affects both direct
use of the baked query extension as well as its operation within
lazy loaders and eager loaders for relationships. In order to
re-establish the query being cached, apply the event adding the
.. versionadded:: 1.3.11 - added the "bake_ok" flag to the
:meth:`.QueryEvents.before_compile` event and disallowed caching via
the "baked" extension from occurring for event handlers that
- return a new :class:`.Query` object if this flag is not set.
+ return a new :class:`_query.Query` object if this flag is not set.
.. seealso::
"""
def before_compile_update(self, query, update_context):
- """Allow modifications to the :class:`.Query` object within
- :meth:`.Query.update`.
+ """Allow modifications to the :class:`_query.Query` object within
+ :meth:`_query.Query.update`.
Like the :meth:`.QueryEvents.before_compile` event, if the event
- is to be used to alter the :class:`.Query` object, it should
+ is to be used to alter the :class:`_query.Query` object, it should
be configured with ``retval=True``, and the modified
- :class:`.Query` object returned, as in ::
+ :class:`_query.Query` object returned, as in ::
@event.listens_for(Query, "before_compile_update", retval=True)
def no_deleted(query, update_context):
The ``.values`` dictionary of the "update context" object can also
be modified in place as illustrated above.
- :param query: a :class:`.Query` instance; this is also
+ :param query: a :class:`_query.Query` instance; this is also
the ``.query`` attribute of the given "update context"
object.
the same kind of object as described in
:paramref:`.QueryEvents.after_bulk_update.update_context`.
The object has a ``.values`` attribute in an UPDATE context which is
- the dictionary of parameters passed to :meth:`.Query.update`. This
+ the dictionary of parameters passed to :meth:`_query.Query.update`.
+ This
dictionary can be modified to alter the VALUES clause of the
resulting UPDATE statement.
"""
def before_compile_delete(self, query, delete_context):
- """Allow modifications to the :class:`.Query` object within
- :meth:`.Query.delete`.
+ """Allow modifications to the :class:`_query.Query` object within
+ :meth:`_query.Query.delete`.
Like the :meth:`.QueryEvents.before_compile` event, this event
should be configured with ``retval=True``, and the modified
- :class:`.Query` object returned, as in ::
+ :class:`_query.Query` object returned, as in ::
@event.listens_for(Query, "before_compile_delete", retval=True)
def no_deleted(query, delete_context):
query = query.filter(entity.deleted == False)
return query
- :param query: a :class:`.Query` instance; this is also
+ :param query: a :class:`_query.Query` instance; this is also
the ``.query`` attribute of the given "delete context"
object.
row corresponding to an object's known primary key identity.
A refresh operation proceeds when an expired attribute is
- accessed on an object, or when :meth:`.Query.get` is
+ accessed on an object, or when :meth:`_query.Query.get` is
used to retrieve an object which is, upon retrieval, detected
as expired. A SELECT is emitted for the target row
based on primary key; if no row is returned, this
class MapperProperty(
HasCacheKey, _MappedAttribute, InspectionAttr, util.MemoizedSlots
):
- """Represent a particular class attribute mapped by :class:`.Mapper`.
+ """Represent a particular class attribute mapped by :class:`_orm.Mapper`.
The most common occurrences of :class:`.MapperProperty` are the
- mapped :class:`.Column`, which is represented in a mapping as
+ mapped :class:`_schema.Column`, which is represented in a mapping as
an instance of :class:`.ColumnProperty`,
- and a reference to another class produced by :func:`.relationship`,
+ and a reference to another class produced by :func:`_orm.relationship`,
represented in the mapping as an instance of
:class:`.RelationshipProperty`.
The dictionary is generated when first accessed. Alternatively,
it can be specified as a constructor argument to the
- :func:`.column_property`, :func:`.relationship`, or :func:`.composite`
+ :func:`.column_property`, :func:`_orm.relationship`, or
+ :func:`.composite`
functions.
.. versionchanged:: 1.0.0 :attr:`.MapperProperty.info` is also
"""Receive a SQL expression that represents a value in the SET
clause of an UPDATE statement.
- Return a tuple that can be passed to a :class:`.Update` construct.
+ Return a tuple that can be passed to a :class:`_expression.Update`
+ construct.
"""
"""
def process_query(self, query):
- """Apply a modification to the given :class:`.Query`."""
+ """Apply a modification to the given :class:`_query.Query`."""
def process_query_conditionally(self, query):
"""same as process_query(), except that this option may not
def _generate_path_cache_key(self, path):
"""Used by the "baked lazy loader" to see if this option can be cached.
- The "baked lazy loader" refers to the :class:`.Query` that is
+ The "baked lazy loader" refers to the :class:`_query.Query` that is
produced during a lazy load operation for a mapped relationship.
It does not yet apply to the "lazy" load operation for deferred
or expired column attributes, however this may change in the future.
This loader generates SQL for a query only once and attempts to cache
it; from that point on, if the SQL has been cached it will no longer
- run the :meth:`.Query.options` method of the :class:`.Query`. The
+ run the :meth:`_query.Query.options` method of the
+ :class:`_query.Query`. The
:class:`.MapperOption` object that wishes to participate within a lazy
load operation therefore needs to tell the baked loader that it either
needs to forego this caching, or that it needs to include the state of
not cache the SQL when this :class:`.MapperOption` is present.
This is the safest option and ensures both that the option is
invoked every time, and also that the cache isn't filled up with
- an unlimited number of :class:`.Query` objects for an unlimited
+ an unlimited number of :class:`_query.Query` objects for an unlimited
number of :class:`.MapperOption` objects.
.. versionchanged:: 1.2.8 the default return value of
was ``None`` indicating "safe to cache, don't include as part of
the cache key"
- To enable caching of :class:`.Query` objects within lazy loaders, a
+ To enable caching of :class:`_query.Query` objects within lazy loaders
+ , a
given :class:`.MapperOption` that returns a cache key must return a key
that uniquely identifies the complete state of this option, which will
match any other :class:`.MapperOption` that itself retains the
If the :class:`.MapperOption` does not apply to the given path and
would not affect query results on such a path, it should return None,
- indicating the :class:`.Query` is safe to cache for this given
+ indicating the :class:`_query.Query` is safe to cache for this given
loader path and that this :class:`.MapperOption` need not be
part of the cache key.
@util.preload_module("sqlalchemy.orm.query")
def merge_result(query, iterator, load=True):
- """Merge a result into this :class:`.Query` object's Session."""
+ """Merge a result into this :class:`_query.Query` object's Session."""
querylib = util.preloaded.orm_query
session = query.session
"""Define the correlation of class attributes to database table
columns.
- The :class:`.Mapper` object is instantiated using the
+ The :class:`_orm.Mapper` object is instantiated using the
:func:`~sqlalchemy.orm.mapper` function. For information
- about instantiating new :class:`.Mapper` objects, see
+ about instantiating new :class:`_orm.Mapper` objects, see
that function's documentation.
makes usage of :func:`.mapper` behind the scenes.
Given a particular class known to be mapped by the ORM,
- the :class:`.Mapper` which maintains it can be acquired
- using the :func:`.inspect` function::
+ the :class:`_orm.Mapper` which maintains it can be acquired
+ using the :func:`_sa.inspect` function::
from sqlalchemy import inspect
"and will be removed in a future release. The functionality "
"of non primary mappers is now better suited using the "
":class:`.AliasedClass` construct, which can also be used "
- "as the target of a :func:`.relationship` in 1.3.",
+ "as the target of a :func:`_orm.relationship` in 1.3.",
),
)
def __init__(
legacy_is_orphan=False,
_compiled_cache_size=100,
):
- r"""Return a new :class:`~.Mapper` object.
+ r"""Return a new :class:`_orm.Mapper` object.
This function is typically used behind the scenes
via the Declarative extension. When using Declarative,
this argument is automatically passed as the declared class
itself.
- :param local_table: The :class:`.Table` or other selectable
+ :param local_table: The :class:`_schema.Table` or other selectable
to which the class is mapped. May be ``None`` if
this mapper inherits from another mapper using single-table
inheritance. When using Declarative, this argument is
automatically passed by the extension, based on what
is configured via the ``__table__`` argument or via the
- :class:`.Table` produced as a result of the ``__tablename__``
- and :class:`.Column` arguments present.
+ :class:`_schema.Table`
+ produced as a result of the ``__tablename__``
+ and :class:`_schema.Column` arguments present.
:param always_refresh: If True, all query operations for this mapped
class will overwrite all data within object instances that already
exist within the session, erasing any in-memory changes with
whatever information was loaded from the database. Usage of this
flag is highly discouraged; as an alternative, see the method
- :meth:`.Query.populate_existing`.
+ :meth:`_query.Query.populate_existing`.
:param allow_partial_pks: Defaults to True. Indicates that a
composite primary key with some NULL values should be considered as
in between individual row persistence operations.
:param column_prefix: A string which will be prepended
- to the mapped attribute name when :class:`.Column`
+ to the mapped attribute name when :class:`_schema.Column`
objects are automatically assigned as attributes to the
mapped class. Does not affect explicitly specified
column-based properties.
See :ref:`include_exclude_cols` for an example.
- :param inherits: A mapped class or the corresponding :class:`.Mapper`
- of one indicating a superclass to which this :class:`.Mapper`
+ :param inherits: A mapped class or the corresponding
+ :class:`_orm.Mapper`
+ of one indicating a superclass to which this :class:`_orm.Mapper`
should *inherit* from. The mapped class here must be a subclass
of the other mapper's class. When using Declarative, this argument
is passed automatically as a result of the natural class
between the two tables.
:param inherit_foreign_keys: When ``inherit_condition`` is used and
- the columns present are missing a :class:`.ForeignKey`
+ the columns present are missing a :class:`_schema.ForeignKey`
configuration, this parameter can be used to specify which columns
are "foreign". In most cases can be left as ``None``.
See the change note and example at :ref:`legacy_is_orphan_addition`
for more detail on this change.
- :param non_primary: Specify that this :class:`.Mapper` is in addition
+ :param non_primary: Specify that this :class:`_orm.Mapper`
+ is in addition
to the "primary" mapper, that is, the one used for persistence.
- The :class:`.Mapper` created here may be used for ad-hoc
+ The :class:`_orm.Mapper` created here may be used for ad-hoc
mapping of the class to an alternate selectable, for loading
only.
- :paramref:`.Mapper.non_primary` is not an often used option, but
- is useful in some specific :func:`.relationship` cases.
+ :paramref:`_orm.Mapper.non_primary` is not an often used option, but
+ is useful in some specific :func:`_orm.relationship` cases.
.. seealso::
.. seealso::
:ref:`passive_deletes` - description of similar feature as
- used with :func:`.relationship`
+ used with :func:`_orm.relationship`
:paramref:`.mapper.passive_updates` - supporting ON UPDATE
CASCADE for joined-table inheritance mappers
.. seealso::
:ref:`passive_updates` - description of a similar feature as
- used with :func:`.relationship`
+ used with :func:`_orm.relationship`
:paramref:`.mapper.passive_deletes` - supporting ON DELETE
CASCADE for joined-table inheritance mappers
SQL expression used to determine the target class for an
incoming row, when inheriting classes are present.
- This value is commonly a :class:`.Column` object that's
- present in the mapped :class:`.Table`::
+ This value is commonly a :class:`_schema.Column` object that's
+ present in the mapped :class:`_schema.Table`::
class Employee(Base):
__tablename__ = 'employee'
When setting ``polymorphic_on`` to reference an
attribute or expression that's not present in the
- locally mapped :class:`.Table`, yet the value
+ locally mapped :class:`_schema.Table`, yet the value
of the discriminator should be persisted to the database,
the value of the
discriminator is not automatically set on new
:param properties: A dictionary mapping the string names of object
attributes to :class:`.MapperProperty` instances, which define the
- persistence behavior of that attribute. Note that :class:`.Column`
+ persistence behavior of that attribute. Note that
+ :class:`_schema.Column`
objects present in
- the mapped :class:`.Table` are automatically placed into
+ the mapped :class:`_schema.Table` are automatically placed into
``ColumnProperty`` instances upon mapping, unless overridden.
When using Declarative, this argument is passed automatically,
based on all those :class:`.MapperProperty` instances declared
in the declared class body.
- :param primary_key: A list of :class:`.Column` objects which define
+ :param primary_key: A list of :class:`_schema.Column`
+ objects which define
the primary key to be used against this mapper's selectable unit.
This is normally simply the primary key of the ``local_table``, but
can be overridden here.
- :param version_id_col: A :class:`.Column`
+ :param version_id_col: A :class:`_schema.Column`
that will be used to keep a running version id of rows
in the table. This is used to detect concurrent updates or
the presence of stale data in a flush. The methodology is to
return self.class_
local_table = None
- """The :class:`.Selectable` which this :class:`.Mapper` manages.
+ """The :class:`expression.Selectable` which this :class:`_orm.Mapper`
+ manages.
- Typically is an instance of :class:`.Table` or :class:`.Alias`.
+ Typically is an instance of :class:`_schema.Table` or
+ :class:`_expression.Alias`.
May also be ``None``.
The "local" table is the
- selectable that the :class:`.Mapper` is directly responsible for
+ selectable that the :class:`_orm.Mapper` is directly responsible for
managing from an attribute access and flush perspective. For
non-inheriting mappers, the local table is the same as the
"mapped" table. For joined-table inheritance mappers, local_table
will be the particular sub-table of the overall "join" which
- this :class:`.Mapper` represents. If this mapper is a
+ this :class:`_orm.Mapper` represents. If this mapper is a
single-table inheriting mapper, local_table will be ``None``.
.. seealso::
- :attr:`~.Mapper.persist_selectable`.
+ :attr:`_orm.Mapper.persist_selectable`.
"""
persist_selectable = None
- """The :class:`.Selectable` to which this :class:`.Mapper` is mapped.
+ """The :class:`expression.Selectable` to which this :class:`_orm.Mapper`
+ is mapped.
- Typically an instance of :class:`.Table`, :class:`.Join`, or
- :class:`.Alias`.
+ Typically an instance of :class:`_schema.Table`, :class:`_expression.Join`
+ , or
+ :class:`_expression.Alias`.
- The :attr:`.Mapper.persist_selectable` is separate from
- :attr:`.Mapper.selectable` in that the former represents columns
+ The :attr:`_orm.Mapper.persist_selectable` is separate from
+ :attr:`_orm.Mapper.selectable` in that the former represents columns
that are mapped on this class or its superclasses, whereas the
latter may be a "polymorphic" selectable that contains additional columns
which are in fact mapped on subclasses only.
"persist selectable" is the "thing the mapper writes to" and
"selectable" is the "thing the mapper selects from".
- :attr:`.Mapper.persist_selectable` is also separate from
- :attr:`.Mapper.local_table`, which represents the set of columns that
+ :attr:`_orm.Mapper.persist_selectable` is also separate from
+ :attr:`_orm.Mapper.local_table`, which represents the set of columns that
are locally mapped on this class directly.
.. seealso::
- :attr:`~.Mapper.selectable`.
+ :attr:`_orm.Mapper.selectable`.
- :attr:`~.Mapper.local_table`.
+ :attr:`_orm.Mapper.local_table`.
"""
inherits = None
- """References the :class:`.Mapper` which this :class:`.Mapper`
+ """References the :class:`_orm.Mapper` which this :class:`_orm.Mapper`
inherits from, if any.
This is a *read only* attribute determined during mapper construction.
"""
configured = None
- """Represent ``True`` if this :class:`.Mapper` has been configured.
+ """Represent ``True`` if this :class:`_orm.Mapper` has been configured.
This is a *read only* attribute determined during mapper construction.
Behavior is undefined if directly modified.
"""
concrete = None
- """Represent ``True`` if this :class:`.Mapper` is a concrete
+ """Represent ``True`` if this :class:`_orm.Mapper` is a concrete
inheritance mapper.
This is a *read only* attribute determined during mapper construction.
"""
tables = None
- """An iterable containing the collection of :class:`.Table` objects
- which this :class:`.Mapper` is aware of.
+ """An iterable containing the collection of :class:`_schema.Table` objects
+ which this :class:`_orm.Mapper` is aware of.
- If the mapper is mapped to a :class:`.Join`, or an :class:`.Alias`
- representing a :class:`.Select`, the individual :class:`.Table`
+ If the mapper is mapped to a :class:`_expression.Join`, or an
+ :class:`_expression.Alias`
+ representing a :class:`_expression.Select`, the individual
+ :class:`_schema.Table`
objects that comprise the full construct will be represented here.
This is a *read only* attribute determined during mapper construction.
"""
primary_key = None
- """An iterable containing the collection of :class:`.Column` objects
+ """An iterable containing the collection of :class:`_schema.Column`
+ objects
which comprise the 'primary key' of the mapped table, from the
- perspective of this :class:`.Mapper`.
+ perspective of this :class:`_orm.Mapper`.
- This list is against the selectable in :attr:`~.Mapper.persist_selectable`.
+ This list is against the selectable in
+ :attr:`_orm.Mapper.persist_selectable`.
In the case of inheriting mappers, some columns may be managed by a
- superclass mapper. For example, in the case of a :class:`.Join`, the
+ superclass mapper. For example, in the case of a
+ :class:`_expression.Join`, the
primary key is determined by all of the primary key columns across all
- tables referenced by the :class:`.Join`.
+ tables referenced by the :class:`_expression.Join`.
The list is also not necessarily the same as the primary key column
- collection associated with the underlying tables; the :class:`.Mapper`
+ collection associated with the underlying tables; the :class:`_orm.Mapper`
features a ``primary_key`` argument that can override what the
- :class:`.Mapper` considers as primary key columns.
+ :class:`_orm.Mapper` considers as primary key columns.
This is a *read only* attribute determined during mapper construction.
Behavior is undefined if directly modified.
"""
class_ = None
- """The Python class which this :class:`.Mapper` maps.
+ """The Python class which this :class:`_orm.Mapper` maps.
This is a *read only* attribute determined during mapper construction.
Behavior is undefined if directly modified.
class_manager = None
"""The :class:`.ClassManager` which maintains event listeners
- and class-bound descriptors for this :class:`.Mapper`.
+ and class-bound descriptors for this :class:`_orm.Mapper`.
This is a *read only* attribute determined during mapper construction.
Behavior is undefined if directly modified.
"""
single = None
- """Represent ``True`` if this :class:`.Mapper` is a single table
+ """Represent ``True`` if this :class:`_orm.Mapper` is a single table
inheritance mapper.
- :attr:`~.Mapper.local_table` will be ``None`` if this flag is set.
+ :attr:`_orm.Mapper.local_table` will be ``None`` if this flag is set.
This is a *read only* attribute determined during mapper construction.
Behavior is undefined if directly modified.
"""
non_primary = None
- """Represent ``True`` if this :class:`.Mapper` is a "non-primary"
+ """Represent ``True`` if this :class:`_orm.Mapper` is a "non-primary"
mapper, e.g. a mapper that is used only to select rows but not for
persistence management.
"""
polymorphic_on = None
- """The :class:`.Column` or SQL expression specified as the
+ """The :class:`_schema.Column` or SQL expression specified as the
``polymorphic_on`` argument
- for this :class:`.Mapper`, within an inheritance scenario.
+ for this :class:`_orm.Mapper`, within an inheritance scenario.
- This attribute is normally a :class:`.Column` instance but
+ This attribute is normally a :class:`_schema.Column` instance but
may also be an expression, such as one derived from
:func:`.cast`.
polymorphic_map = None
"""A mapping of "polymorphic identity" identifiers mapped to
- :class:`.Mapper` instances, within an inheritance scenario.
+ :class:`_orm.Mapper` instances, within an inheritance scenario.
The identifiers can be of any type which is comparable to the
- type of column represented by :attr:`~.Mapper.polymorphic_on`.
+ type of column represented by :attr:`_orm.Mapper.polymorphic_on`.
An inheritance chain of mappers will all reference the same
polymorphic map object. The object is used to correlate incoming
polymorphic_identity = None
"""Represent an identifier which is matched against the
- :attr:`~.Mapper.polymorphic_on` column during result row loading.
+ :attr:`_orm.Mapper.polymorphic_on` column during result row loading.
Used only with inheritance, this object can be of any type which is
comparable to the type of column represented by
- :attr:`~.Mapper.polymorphic_on`.
+ :attr:`_orm.Mapper.polymorphic_on`.
This is a *read only* attribute determined during mapper construction.
Behavior is undefined if directly modified.
"""
base_mapper = None
- """The base-most :class:`.Mapper` in an inheritance chain.
+ """The base-most :class:`_orm.Mapper` in an inheritance chain.
In a non-inheriting scenario, this attribute will always be this
- :class:`.Mapper`. In an inheritance scenario, it references
- the :class:`.Mapper` which is parent to all other :class:`.Mapper`
+ :class:`_orm.Mapper`. In an inheritance scenario, it references
+ the :class:`_orm.Mapper` which is parent to all other :class:`_orm.Mapper`
objects in the inheritance chain.
This is a *read only* attribute determined during mapper construction.
"""
columns = None
- """A collection of :class:`.Column` or other scalar expression
- objects maintained by this :class:`.Mapper`.
+ """A collection of :class:`_schema.Column` or other scalar expression
+ objects maintained by this :class:`_orm.Mapper`.
The collection behaves the same as that of the ``c`` attribute on
- any :class:`.Table` object, except that only those columns included in
+ any :class:`_schema.Table` object,
+ except that only those columns included in
this mapping are present, and are keyed based on the attribute name
defined in the mapping, not necessarily the ``key`` attribute of the
- :class:`.Column` itself. Additionally, scalar expressions mapped
+ :class:`_schema.Column` itself. Additionally, scalar expressions mapped
by :func:`.column_property` are also present here.
This is a *read only* attribute determined during mapper construction.
validators = None
"""An immutable dictionary of attributes which have been decorated
- using the :func:`~.orm.validates` decorator.
+ using the :func:`_orm.validates` decorator.
The dictionary contains string attribute names as keys
mapped to the actual validation method.
"""
c = None
- """A synonym for :attr:`~.Mapper.columns`."""
+ """A synonym for :attr:`_orm.Mapper.columns`."""
@property
@util.deprecated("1.3", "Use .persist_selectable")
)
def _set_concrete_base(self, mapper):
- """Set the given :class:`.Mapper` as the 'inherits' for this
- :class:`.Mapper`, assuming this :class:`.Mapper` is concrete
+ """Set the given :class:`_orm.Mapper` as the 'inherits' for this
+ :class:`_orm.Mapper`, assuming this :class:`_orm.Mapper` is concrete
and does not already have an inherits."""
assert self.concrete
@util.preload_module("sqlalchemy.orm.descriptor_props")
def _property_from_column(self, key, prop):
"""generate/update a :class:`.ColumnProperty` given a
- :class:`.Column` object. """
+ :class:`_schema.Column` object. """
descriptor_props = util.preloaded.orm_descriptor_props
# we were passed a Column or a list of Columns;
# generate a properties.ColumnProperty
)
def get_property_by_column(self, column):
- """Given a :class:`.Column` object, return the
+ """Given a :class:`_schema.Column` object, return the
:class:`.MapperProperty` which maps this column."""
return self._columntoproperty[column]
)
with_polymorphic_mappers = _with_polymorphic_mappers
- """The list of :class:`.Mapper` objects included in the
+ """The list of :class:`_orm.Mapper` objects included in the
default "polymorphic" query.
"""
@property
def selectable(self):
- """The :func:`~.sql.expression.select` construct this
- :class:`.Mapper` selects from by default.
+ """The :func:`_expression.select` construct this
+ :class:`_orm.Mapper` selects from by default.
Normally, this is equivalent to :attr:`.persist_selectable`, unless
the ``with_polymorphic`` feature is in use, in which case the
column. The namespace object can also be iterated,
which would yield each :class:`.MapperProperty`.
- :class:`.Mapper` has several pre-filtered views
+ :class:`_orm.Mapper` has several pre-filtered views
of this attribute which limit the types of properties
returned, including :attr:`.synonyms`, :attr:`.column_attrs`,
:attr:`.relationships`, and :attr:`.composites`.
.. warning::
- The :attr:`.Mapper.attrs` accessor namespace is an
+ The :attr:`_orm.Mapper.attrs` accessor namespace is an
instance of :class:`.OrderedProperties`. This is
a dictionary-like object which includes a small number of
named methods such as :meth:`.OrderedProperties.items`
.. seealso::
- :attr:`.Mapper.all_orm_descriptors`
+ :attr:`_orm.Mapper.all_orm_descriptors`
"""
if Mapper._new_mappers:
:attr:`.QueryableAttribute.property` attribute refers to the
:class:`.MapperProperty` property, which is what you get when
referring to the collection of mapped properties via
- :attr:`.Mapper.attrs`.
+ :attr:`_orm.Mapper.attrs`.
.. warning::
- The :attr:`.Mapper.all_orm_descriptors` accessor namespace is an
+ The :attr:`_orm.Mapper.all_orm_descriptors`
+ accessor namespace is an
instance of :class:`.OrderedProperties`. This is
a dictionary-like object which includes a small number of
named methods such as :meth:`.OrderedProperties.items`
.. seealso::
- :attr:`.Mapper.attrs`
+ :attr:`_orm.Mapper.attrs`
"""
return util.ImmutableProperties(
@util.preload_module("sqlalchemy.orm.descriptor_props")
def synonyms(self):
"""Return a namespace of all :class:`.SynonymProperty`
- properties maintained by this :class:`.Mapper`.
+ properties maintained by this :class:`_orm.Mapper`.
.. seealso::
- :attr:`.Mapper.attrs` - namespace of all :class:`.MapperProperty`
+ :attr:`_orm.Mapper.attrs` - namespace of all
+ :class:`.MapperProperty`
objects.
"""
@HasMemoized.memoized_attribute
def column_attrs(self):
"""Return a namespace of all :class:`.ColumnProperty`
- properties maintained by this :class:`.Mapper`.
+ properties maintained by this :class:`_orm.Mapper`.
.. seealso::
- :attr:`.Mapper.attrs` - namespace of all :class:`.MapperProperty`
+ :attr:`_orm.Mapper.attrs` - namespace of all
+ :class:`.MapperProperty`
objects.
"""
@HasMemoized.memoized_attribute
def relationships(self):
"""A namespace of all :class:`.RelationshipProperty` properties
- maintained by this :class:`.Mapper`.
+ maintained by this :class:`_orm.Mapper`.
.. warning::
- the :attr:`.Mapper.relationships` accessor namespace is an
+ the :attr:`_orm.Mapper.relationships` accessor namespace is an
instance of :class:`.OrderedProperties`. This is
a dictionary-like object which includes a small number of
named methods such as :meth:`.OrderedProperties.items`
.. seealso::
- :attr:`.Mapper.attrs` - namespace of all :class:`.MapperProperty`
+ :attr:`_orm.Mapper.attrs` - namespace of all
+ :class:`.MapperProperty`
objects.
"""
@util.preload_module("sqlalchemy.orm.descriptor_props")
def composites(self):
"""Return a namespace of all :class:`.CompositeProperty`
- properties maintained by this :class:`.Mapper`.
+ properties maintained by this :class:`_orm.Mapper`.
.. seealso::
- :attr:`.Mapper.attrs` - namespace of all :class:`.MapperProperty`
+ :attr:`_orm.Mapper.attrs` - namespace of all
+ :class:`.MapperProperty`
objects.
"""
item from the identity map.
:param row: A :class:`.Row` instance. The columns which are
- mapped by this :class:`.Mapper` should be locatable in the row,
- preferably via the :class:`.Column` object directly (as is the case
- when a :func:`~.sql.expression.select` construct is executed), or
+ mapped by this :class:`_orm.Mapper` should be locatable in the row,
+ preferably via the :class:`_schema.Column`
+ object directly (as is the case
+ when a :func:`_expression.select` construct is executed), or
via string names of the form ``<tablename>_<colname>``.
"""
proceeds.
* :meth:`.MapperEvents.mapper_configured` - called as each individual
- :class:`.Mapper` is configured within the process; will include all
+ :class:`_orm.Mapper` is configured within the process; will include all
mapper state except for backrefs set up by other mappers that are still
to be configured.
* :meth:`.MapperEvents.after_configured` - called once after
:func:`.configure_mappers` is complete; at this stage, all
- :class:`.Mapper` objects that are known to SQLAlchemy will be fully
+ :class:`_orm.Mapper` objects that are known to SQLAlchemy will be fully
configured. Note that the calling application may still have other
mappings that haven't been produced yet, such as if they are in modules
as yet unimported.
# the MIT License: http://www.opensource.org/licenses/mit-license.php
"""private module containing functions used to emit INSERT, UPDATE
-and DELETE statements on behalf of a :class:`.Mapper` and its descending
+and DELETE statements on behalf of a :class:`_orm.Mapper` and its descending
mappers.
The functions here are called only by the unit of work functions
class BulkUD(object):
- """Handle bulk update and deletes via a :class:`.Query`."""
+ """Handle bulk update and deletes via a :class:`_query.Query`."""
def __init__(self, query):
self.query = query.enable_eagerloads(False)
class ColumnProperty(StrategizedProperty):
"""Describes an object attribute that corresponds to a table column.
- Public constructor is the :func:`.orm.column_property` function.
+ Public constructor is the :func:`_orm.column_property` function.
"""
r"""Provide a column-level property for use with a mapping.
Column-based properties can normally be applied to the mapper's
- ``properties`` dictionary using the :class:`.Column` element directly.
+ ``properties`` dictionary using the :class:`_schema.Column`
+ element directly.
Use this function when the given column is not directly present within
the mapper's selectable; examples include SQL expressions, functions,
and scalar SELECT queries.
- The :func:`.orm.column_property` function returns an instance of
+ The :func:`_orm.column_property` function returns an instance of
:class:`.ColumnProperty`.
Columns that aren't present in the mapper's selectable won't be
"""The Query class and support.
-Defines the :class:`.Query` class, the central
+Defines the :class:`_query.Query` class, the central
construct used by the ORM to construct database queries.
-The :class:`.Query` class should not be confused with the
-:class:`.Select` class, which defines database
+The :class:`_query.Query` class should not be confused with the
+:class:`_expression.Select` class, which defines database
SELECT operations at the SQL (non-ORM) level. ``Query`` differs from
``Select`` in that it returns ORM-mapped objects and interacts with an
ORM session, whereas the ``Select`` construct interacts directly with the
class Query(Generative):
"""ORM-level SQL construction object.
- :class:`.Query` is the source of all SELECT statements generated by the
+ :class:`_query.Query`
+ is the source of all SELECT statements generated by the
ORM, both those formulated by end-user query operations as well as by
high level internal operations such as related collection loading. It
features a generative interface whereby successive calls return a new
- :class:`.Query` object, a copy of the former with additional
+ :class:`_query.Query` object, a copy of the former with additional
criteria and options associated with it.
- :class:`.Query` objects are normally initially generated using the
+ :class:`_query.Query` objects are normally initially generated using the
:meth:`~.Session.query` method of :class:`.Session`, and in
- less common cases by instantiating the :class:`.Query` directly and
- associating with a :class:`.Session` using the :meth:`.Query.with_session`
+ less common cases by instantiating the :class:`_query.Query` directly and
+ associating with a :class:`.Session` using the
+ :meth:`_query.Query.with_session`
method.
- For a full walkthrough of :class:`.Query` usage, see the
+ For a full walkthrough of :class:`_query.Query` usage, see the
:ref:`ormtutorial_toplevel`.
"""
_bake_ok = True
lazy_loaded_from = None
- """An :class:`.InstanceState` that is using this :class:`.Query` for a
+ """An :class:`.InstanceState` that is using this :class:`_query.Query`
+ for a
lazy load operation.
The primary rationale for this attribute is to support the horizontal
.. note::
- Within the realm of regular :class:`.Query` usage, this attribute is
+ Within the realm of regular :class:`_query.Query` usage,
+ this attribute is
set by the lazy loader strategy before the query is invoked. However
there is no established hook that is available to reliably intercept
this value programmatically. It is set by the lazy loading strategy
cache SQL compilation, the :meth:`.QueryEvents.before_compile` hook is
also not reliable.
- Currently, setting the :paramref:`.relationship.bake_queries` to
- ``False`` on the target :func:`.relationship`, and then making use of
+ Currently, setting the :paramref:`_orm.relationship.bake_queries` to
+ ``False`` on the target :func:`_orm.relationship`,
+ and then making use of
the :meth:`.QueryEvents.before_compile` event hook, is the only
available programmatic path to intercepting this attribute. In future
releases, there will be new hooks available that allow interception of
- the :class:`.Query` before it is executed, rather than before it is
+ the :class:`_query.Query` before it is executed,
+ rather than before it is
compiled.
.. versionadded:: 1.2.9
"""
def __init__(self, entities, session=None):
- """Construct a :class:`.Query` directly.
+ """Construct a :class:`_query.Query` directly.
E.g.::
:param entities: a sequence of entities and/or SQL expressions.
- :param session: a :class:`.Session` with which the :class:`.Query`
- will be associated. Optional; a :class:`.Query` can be associated
+ :param session: a :class:`.Session` with which the
+ :class:`_query.Query`
+ will be associated. Optional; a :class:`_query.Query`
+ can be associated
with a :class:`.Session` generatively via the
- :meth:`.Query.with_session` method as well.
+ :meth:`_query.Query.with_session` method as well.
.. seealso::
:meth:`.Session.query`
- :meth:`.Query.with_session`
+ :meth:`_query.Query.with_session`
"""
self.session = session
def subquery(self, name=None, with_labels=False, reduce_columns=False):
"""return the full SELECT statement represented by
- this :class:`.Query`, embedded within an :class:`.Alias`.
+ this :class:`_query.Query`, embedded within an
+ :class:`_expression.Alias`.
Eager JOIN generation within the query is disabled.
:param name: string name to be assigned as the alias;
- this is passed through to :meth:`.FromClause.alias`.
+ this is passed through to :meth:`_expression.FromClause.alias`.
If ``None``, a name will be deterministically generated
at compile time.
:param with_labels: if True, :meth:`.with_labels` will be called
- on the :class:`.Query` first to apply table-qualified labels
+ on the :class:`_query.Query` first to apply table-qualified labels
to all columns.
- :param reduce_columns: if True, :meth:`.Select.reduce_columns` will
- be called on the resulting :func:`~.sql.expression.select` construct,
+ :param reduce_columns: if True,
+ :meth:`_expression.Select.reduce_columns` will
+ be called on the resulting :func:`_expression.select` construct,
to remove same-named columns where one also refers to the other
via foreign key or WHERE clause equivalence.
def cte(self, name=None, recursive=False):
r"""Return the full SELECT statement represented by this
- :class:`.Query` represented as a common table expression (CTE).
+ :class:`_query.Query` represented as a common table expression (CTE).
Parameters and usage are the same as those of the
- :meth:`.SelectBase.cte` method; see that method for
+ :meth:`_expression.SelectBase.cte` method; see that method for
further details.
Here is the `PostgreSQL WITH
Note that, in this example, the ``included_parts`` cte and the
``incl_alias`` alias of it are Core selectables, which
means the columns are accessed via the ``.c.`` attribute. The
- ``parts_alias`` object is an :func:`.orm.aliased` instance of the
+ ``parts_alias`` object is an :func:`_orm.aliased` instance of the
``Part`` entity, so column-mapped attributes are available
directly::
.. seealso::
- :meth:`.HasCTE.cte`
+ :meth:`_expression.HasCTE.cte`
"""
return self.enable_eagerloads(False).statement.cte(
def label(self, name):
"""Return the full SELECT statement represented by this
- :class:`.Query`, converted
+ :class:`_query.Query`, converted
to a scalar subquery with a label of the given name.
Analogous to :meth:`sqlalchemy.sql.expression.SelectBase.label`.
@util.deprecated(
"1.4",
- "The :meth:`.Query.as_scalar` method is deprecated and will be "
+ "The :meth:`_query.Query.as_scalar` method is deprecated and will be "
"removed in a future release. Please refer to "
- ":meth:`.Query.scalar_subquery`.",
+ ":meth:`_query.Query.scalar_subquery`.",
)
def as_scalar(self):
"""Return the full SELECT statement represented by this
- :class:`.Query`, converted to a scalar subquery.
+ :class:`_query.Query`, converted to a scalar subquery.
"""
return self.scalar_subquery()
def scalar_subquery(self):
"""Return the full SELECT statement represented by this
- :class:`.Query`, converted to a scalar subquery.
+ :class:`_query.Query`, converted to a scalar subquery.
Analogous to
:meth:`sqlalchemy.sql.expression.SelectBase.scalar_subquery`.
- .. versionchanged:: 1.4 the :meth:`.Query.scalar_subquery` method
- replaces the :meth:`.Query.as_scalar` method.
+ .. versionchanged:: 1.4 the :meth:`_query.Query.scalar_subquery`
+ method
+ replaces the :meth:`_query.Query.as_scalar` method.
"""
return self.enable_eagerloads(False).statement.scalar_subquery()
.. seealso::
- :meth:`.Query.is_single_entity`
+ :meth:`_query.Query.is_single_entity`
"""
self._only_return_tuples = value
@property
def is_single_entity(self):
- """Indicates if this :class:`.Query` returns tuples or single entities.
+ """Indicates if this :class:`_query.Query`
+ returns tuples or single entities.
Returns True if this query returns a single entity for each instance
in its result list, and False if this query returns a tuple of entities
.. seealso::
- :meth:`.Query.only_return_tuples`
+ :meth:`_query.Query.only_return_tuples`
"""
return (
This is used primarily when nesting the Query's
statement into a subquery or other
- selectable, or when using :meth:`.Query.yield_per`.
+ selectable, or when using :meth:`_query.Query.yield_per`.
"""
self._enable_eagerloads = value
When the `Query` actually issues SQL to load rows, it always
uses column labeling.
- .. note:: The :meth:`.Query.with_labels` method *only* applies
- the output of :attr:`.Query.statement`, and *not* to any of
- the result-row invoking systems of :class:`.Query` itself, e.g.
- :meth:`.Query.first`, :meth:`.Query.all`, etc. To execute
- a query using :meth:`.Query.with_labels`, invoke the
- :attr:`.Query.statement` using :meth:`.Session.execute`::
+ .. note:: The :meth:`_query.Query.with_labels` method *only* applies
+ the output of :attr:`_query.Query.statement`, and *not* to any of
+ the result-row invoking systems of :class:`_query.Query` itself, e.
+ g.
+ :meth:`_query.Query.first`, :meth:`_query.Query.all`, etc.
+ To execute
+ a query using :meth:`_query.Query.with_labels`, invoke the
+ :attr:`_query.Query.statement` using :meth:`.Session.execute`::
result = session.execute(query.with_labels().statement)
):
"""Load columns for inheriting classes.
- :meth:`.Query.with_polymorphic` applies transformations
- to the "main" mapped class represented by this :class:`.Query`.
- The "main" mapped class here means the :class:`.Query`
+ :meth:`_query.Query.with_polymorphic` applies transformations
+ to the "main" mapped class represented by this :class:`_query.Query`.
+ The "main" mapped class here means the :class:`_query.Query`
object's first argument is a full class, i.e.
``session.query(SomeClass)``. These transformations allow additional
tables to be present in the FROM clause so that columns for a
(e.g. approximately 1000) is used, even with DBAPIs that buffer
rows (which are most).
- The :meth:`.Query.yield_per` method **is not compatible
+ The :meth:`_query.Query.yield_per` method **is not compatible
subqueryload eager loading or joinedload eager loading when
using collections**. It is potentially compatible with "select in"
eager loading, **provided the database driver supports multiple,
Therefore in some cases, it may be helpful to disable
eager loads, either unconditionally with
- :meth:`.Query.enable_eagerloads`::
+ :meth:`_query.Query.enable_eagerloads`::
q = sess.query(Object).yield_per(100).enable_eagerloads(False)
.. seealso::
- :meth:`.Query.enable_eagerloads`
+ :meth:`_query.Query.enable_eagerloads`
"""
self._yield_per = count
some_object = session.query(VersionedFoo).get(
{"id": 5, "version_id": 10})
- :meth:`~.Query.get` is special in that it provides direct
+ :meth:`_query.Query.get` is special in that it provides direct
access to the identity map of the owning :class:`.Session`.
If the given primary key identifier is present
in the local identity map, the object is returned
If not present,
a SELECT is performed in order to locate the object.
- :meth:`~.Query.get` also will perform a check if
+ :meth:`_query.Query.get` also will perform a check if
the object is present in the identity map and
marked as expired - a SELECT
is emitted to refresh the object as well as to
ensure that the row is still present.
If not, :class:`~sqlalchemy.orm.exc.ObjectDeletedError` is raised.
- :meth:`~.Query.get` is only used to return a single
+ :meth:`_query.Query.get` is only used to return a single
mapped instance, not multiple instances or
individual column constructs, and strictly
on a single primary key value. The originating
- :class:`.Query` must be constructed in this way,
+ :class:`_query.Query` must be constructed in this way,
i.e. against a single mapped entity,
with no additional filtering criterion. Loading
- options via :meth:`~.Query.options` may be applied
+ options via :meth:`_query.Query.options` may be applied
however, and will be used if the object is not
yet locally present.
A lazy-loading, many-to-one attribute configured
- by :func:`.relationship`, using a simple
+ by :func:`_orm.relationship`, using a simple
foreign-key-to-primary-key criterion, will also use an
- operation equivalent to :meth:`~.Query.get` in order to retrieve
+ operation equivalent to :meth:`_query.Query.get` in order to retrieve
the target value from the local identity map
before querying the database. See :doc:`/orm/loading_relationships`
for further details on relationship loading.
my_object = query.get(5)
The tuple form contains primary key values typically in
- the order in which they correspond to the mapped :class:`.Table`
+ the order in which they correspond to the mapped
+ :class:`_schema.Table`
object's primary key columns, or if the
- :paramref:`.Mapper.primary_key` configuration parameter were used, in
+ :paramref:`_orm.Mapper.primary_key` configuration parameter were used
+ , in
the order used for that parameter. For example, if the primary key
of a row is represented by the integer
digits "5, 10" the call would look like::
my_object = query.get({"id": 5, "version_id": 10})
- .. versionadded:: 1.3 the :meth:`.Query.get` method now optionally
+ .. versionadded:: 1.3 the :meth:`_query.Query.get`
+ method now optionally
accepts a dictionary of attribute names to values in order to
indicate a primary key identifier.
@_generative
def correlate(self, *args):
- """Return a :class:`.Query` construct which will correlate the given
- FROM clauses to that of an enclosing :class:`.Query` or
- :func:`~.expression.select`.
+ """Return a :class:`_query.Query`
+ construct which will correlate the given
+ FROM clauses to that of an enclosing :class:`_query.Query` or
+ :func:`_expression.select`.
The method here accepts mapped classes, :func:`.aliased` constructs,
and :func:`.mapper` constructs as arguments, which are resolved into
constructs.
The correlation arguments are ultimately passed to
- :meth:`.Select.correlate` after coercion to expression constructs.
+ :meth:`_expression.Select.correlate`
+ after coercion to expression constructs.
The correlation arguments take effect in such cases
- as when :meth:`.Query.from_self` is used, or when
- a subquery as returned by :meth:`.Query.subquery` is
- embedded in another :func:`~.expression.select` construct.
+ as when :meth:`_query.Query.from_self` is used, or when
+ a subquery as returned by :meth:`_query.Query.subquery` is
+ embedded in another :func:`_expression.select` construct.
"""
@_generative
def populate_existing(self):
- """Return a :class:`.Query` that will expire and refresh all instances
+ """Return a :class:`_query.Query`
+ that will expire and refresh all instances
as they are loaded, or reused from the current :class:`.Session`.
:meth:`.populate_existing` does not improve behavior when
subquery loaders to traverse into already-loaded related objects
and collections.
- Default is that of :attr:`.Query._invoke_all_eagers`.
+ Default is that of :attr:`_query.Query._invoke_all_eagers`.
"""
self._invoke_all_eagers = value
def with_parent(self, instance, property=None, from_entity=None): # noqa
"""Add filtering criterion that relates the given instance
to a child object or collection, using its attribute state
- as well as an established :func:`.relationship()`
+ as well as an established :func:`_orm.relationship()`
configuration.
The method uses the :func:`.with_parent` function to generate
- the clause, the result of which is passed to :meth:`.Query.filter`.
+ the clause, the result of which is passed to
+ :meth:`_query.Query.filter`.
Parameters are the same as :func:`.with_parent`, with the exception
that the given property can be None, in which case a search is
- performed against this :class:`.Query` object's target mapper.
+ performed against this :class:`_query.Query` object's target mapper.
:param instance:
- An instance which has some :func:`.relationship`.
+ An instance which has some :func:`_orm.relationship`.
:param property:
String property name, or class-bound attribute, which indicates
:param from_entity:
Entity in which to consider as the left side. This defaults to the
- "zero" entity of the :class:`.Query` itself.
+ "zero" entity of the :class:`_query.Query` itself.
"""
relationships = util.preloaded.orm_relationships
@_generative
def with_session(self, session):
- """Return a :class:`.Query` that will use the given :class:`.Session`.
+ """Return a :class:`_query.Query` that will use the given
+ :class:`.Session`.
- While the :class:`.Query` object is normally instantiated using the
- :meth:`.Session.query` method, it is legal to build the :class:`.Query`
+ While the :class:`_query.Query`
+ object is normally instantiated using the
+ :meth:`.Session.query` method, it is legal to build the
+ :class:`_query.Query`
directly without necessarily using a :class:`.Session`. Such a
- :class:`.Query` object, or any :class:`.Query` already associated
- with a different :class:`.Session`, can produce a new :class:`.Query`
+ :class:`_query.Query` object, or any :class:`_query.Query`
+ already associated
+ with a different :class:`.Session`, can produce a new
+ :class:`_query.Query`
object associated with a target session using this method::
from sqlalchemy.orm import Query
self.session = session
@util.deprecated_20(
- ":meth:`.Query.from_self`",
+ ":meth:`_query.Query.from_self`",
alternative="The new approach is to use the :func:`.orm.aliased` "
"construct in conjunction with a subquery. See the section "
":ref:`Selecting from the query itself as a subquery "
r"""return a Query that selects from this Query's
SELECT statement.
- :meth:`.Query.from_self` essentially turns the SELECT statement
+ :meth:`_query.Query.from_self` essentially turns the SELECT statement
into a SELECT of itself. Given a query such as::
q = session.query(User).filter(User.name.like('e%'))
- Given the :meth:`.Query.from_self` version::
+ Given the :meth:`_query.Query.from_self` version::
q = session.query(User).filter(User.name.like('e%')).from_self()
FROM "user"
WHERE "user".name LIKE :name_1) AS anon_1
- There are lots of cases where :meth:`.Query.from_self` may be useful.
+ There are lots of cases where :meth:`_query.Query.from_self`
+ may be useful.
A simple one is where above, we may want to apply a row LIMIT to
the set of user objects we query against, and then apply additional
joins against that row-limited set::
**Automatic Aliasing**
- Another key behavior of :meth:`.Query.from_self` is that it applies
+ Another key behavior of :meth:`_query.Query.from_self`
+ is that it applies
**automatic aliasing** to the entities inside the subquery, when
they are referenced on the outside. Above, if we continue to
refer to the ``User`` entity without any additional aliasing applied
for simple filters and orderings. More ambitious constructions
such as referring to the entity in joins should prefer to use
explicit subquery objects, typically making use of the
- :meth:`.Query.subquery` method to produce an explicit subquery object.
+ :meth:`_query.Query.subquery`
+ method to produce an explicit subquery object.
Always test the structure of queries by viewing the SQL to ensure
a particular structure does what's expected!
**Changing the Entities**
- :meth:`.Query.from_self` also includes the ability to modify what
+ :meth:`_query.Query.from_self`
+ also includes the ability to modify what
columns are being queried. In our example, we want ``User.id``
to be queried by the inner query, so that we can join to the
``Address`` entity on the outside, but we only wanted the outer
q = q.add_entity(User).from_self().\
options(contains_eager(Address.user))
- We use :meth:`.Query.add_entity` above **before** we call
- :meth:`.Query.from_self` so that the ``User`` columns are present
+ We use :meth:`_query.Query.add_entity` above **before** we call
+ :meth:`_query.Query.from_self`
+ so that the ``User`` columns are present
in the inner subquery, so that they are available to the
:func:`.contains_eager` modifier we are using on the outside,
producing:
@_generative
def with_entities(self, *entities):
- r"""Return a new :class:`.Query` replacing the SELECT list with the
+ r"""Return a new :class:`_query.Query`
+ replacing the SELECT list with the
given entities.
e.g.::
@util.deprecated(
"1.4",
- ":meth:`.Query.add_column` is deprecated and will be removed in a "
- "future release. Please use :meth:`.Query.add_columns`",
+ ":meth:`_query.Query.add_column` "
+ "is deprecated and will be removed in a "
+ "future release. Please use :meth:`_query.Query.add_columns`",
)
def add_column(self, column):
"""Add a column expression to the list of result columns to be
return self.add_columns(column)
def options(self, *args):
- """Return a new :class:`.Query` object, applying the given list of
+ """Return a new :class:`_query.Query` object,
+ applying the given list of
mapper options.
Most supplied options regard changing how column- and
opt.process_query(self)
def with_transformation(self, fn):
- """Return a new :class:`.Query` object transformed by
+ """Return a new :class:`_query.Query` object transformed by
the given function.
E.g.::
q = q.with_transformation(filter_something(x==5))
- This allows ad-hoc recipes to be created for :class:`.Query`
+ This allows ad-hoc recipes to be created for :class:`_query.Query`
objects. See the example at :ref:`hybrid_transformers`.
"""
def with_hint(self, selectable, text, dialect_name="*"):
"""Add an indexing or other executional context
hint for the given entity or selectable to
- this :class:`.Query`.
+ this :class:`_query.Query`.
Functionality is passed straight through to
:meth:`~sqlalchemy.sql.expression.Select.with_hint`,
with the addition that ``selectable`` can be a
- :class:`.Table`, :class:`.Alias`, or ORM entity / mapped class
+ :class:`_schema.Table`, :class:`_expression.Alias`,
+ or ORM entity / mapped class
/etc.
.. seealso::
- :meth:`.Query.with_statement_hint`
+ :meth:`_query.Query.with_statement_hint`
:meth:.`.Query.prefix_with` - generic SELECT prefixing which also
can suit some database-specific HINT syntaxes such as MySQL
self._with_hints += ((selectable, text, dialect_name),)
def with_statement_hint(self, text, dialect_name="*"):
- """add a statement hint to this :class:`.Select`.
+ """add a statement hint to this :class:`_expression.Select`.
- This method is similar to :meth:`.Select.with_hint` except that
+ 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.
- This feature calls down into :meth:`.Select.with_statement_hint`.
+ This feature calls down into
+ :meth:`_expression.Select.with_statement_hint`.
.. versionadded:: 1.0.0
.. seealso::
- :meth:`.Query.with_hint`
+ :meth:`_query.Query.with_hint`
"""
return self.with_hint(None, text, dialect_name)
.. seealso::
- :meth:`.Query.execution_options`
+ :meth:`_query.Query.execution_options`
"""
return self._execution_options
""" Set non-SQL options which take effect during execution.
The options are the same as those accepted by
- :meth:`.Connection.execution_options`.
+ :meth:`_engine.Connection.execution_options`.
Note that the ``stream_results`` execution option is enabled
automatically if the :meth:`~sqlalchemy.orm.query.Query.yield_per()`
.. seealso::
- :meth:`.Query.get_execution_options`
+ :meth:`_query.Query.get_execution_options`
"""
self._execution_options = self._execution_options.union(kwargs)
skip_locked=False,
key_share=False,
):
- """return a new :class:`.Query` with the specified options for the
+ """return a new :class:`_query.Query`
+ with the specified options for the
``FOR UPDATE`` clause.
The behavior of this method is identical to that of
- :meth:`.SelectBase.with_for_update`. When called with no arguments,
+ :meth:`_expression.SelectBase.with_for_update`.
+ When called with no arguments,
the resulting ``SELECT`` statement will have a ``FOR UPDATE`` clause
appended. When additional arguments are specified, backend-specific
options such as ``FOR UPDATE NOWAIT`` or ``LOCK IN SHARE MODE``
.. seealso::
- :meth:`.GenerativeSelect.with_for_update` - Core level method with
+ :meth:`_expression.GenerativeSelect.with_for_update`
+ - Core level method with
full argument and behavioral description.
"""
@_assertions(_no_statement_condition, _no_limit_offset)
def filter(self, *criterion):
r"""apply the given filtering criterion to a copy
- of this :class:`.Query`, using SQL expressions.
+ of this :class:`_query.Query`, using SQL expressions.
e.g.::
The criterion is any SQL expression object applicable to the
WHERE clause of a select. String expressions are coerced
- into SQL expression constructs via the :func:`.text` construct.
+ into SQL expression constructs via the :func:`_expression.text`
+ construct.
.. seealso::
- :meth:`.Query.filter_by` - filter on keyword expressions.
+ :meth:`_query.Query.filter_by` - filter on keyword expressions.
"""
for criterion in list(criterion):
def filter_by(self, **kwargs):
r"""apply the given filtering criterion to a copy
- of this :class:`.Query`, using keyword expressions.
+ of this :class:`_query.Query`, using keyword expressions.
e.g.::
The keyword expressions are extracted from the primary
entity of the query, or the last entity that was the
- target of a call to :meth:`.Query.join`.
+ target of a call to :meth:`_query.Query.join`.
.. seealso::
- :meth:`.Query.filter` - filter on SQL expressions.
+ :meth:`_query.Query.filter` - filter on SQL expressions.
"""
@_assertions(_no_statement_condition, _no_limit_offset)
def group_by(self, *criterion):
"""apply one or more GROUP BY criterion to the query and return
- the newly resulting :class:`.Query`
+ the newly resulting :class:`_query.Query`
All existing GROUP BY settings can be suppressed by
passing ``None`` - this will suppress any GROUP BY configured
@_assertions(_no_statement_condition, _no_limit_offset)
def having(self, criterion):
r"""apply a HAVING criterion to the query and return the
- newly resulting :class:`.Query`.
+ newly resulting :class:`_query.Query`.
- :meth:`~.Query.having` is used in conjunction with
- :meth:`~.Query.group_by`.
+ :meth:`_query.Query.having` is used in conjunction with
+ :meth:`_query.Query.group_by`.
HAVING criterion makes it possible to use filters on aggregate
functions like COUNT, SUM, AVG, MAX, and MIN, eg.::
be rendered on a query called within UNION, EXCEPT, etc.
To disable all ORDER BY clauses including those configured
on mappers, issue ``query.order_by(None)`` - the resulting
- :class:`.Query` object will not render ORDER BY within
+ :class:`_query.Query` object will not render ORDER BY within
its SELECT statement.
"""
return self._set_op(expression.except_all, *q)
def join(self, *props, **kwargs):
- r"""Create a SQL JOIN against this :class:`.Query` object's criterion
- and apply generatively, returning the newly resulting :class:`.Query`.
+ r"""Create a SQL JOIN against this :class:`_query.Query`
+ object's criterion
+ and apply generatively, returning the newly resulting
+ :class:`_query.Query`.
**Simple Relationship Joins**
Consider a mapping between two classes ``User`` and ``Address``,
with a relationship ``User.addresses`` representing a collection
of ``Address`` objects associated with each ``User``. The most
- common usage of :meth:`~.Query.join` is to create a JOIN along this
+ common usage of :meth:`_query.Query.join`
+ is to create a JOIN along this
relationship, using the ``User.addresses`` attribute as an indicator
for how this should occur::
q = session.query(User).join(User.addresses)
- Where above, the call to :meth:`~.Query.join` along ``User.addresses``
+ Where above, the call to :meth:`_query.Query.join` along ``User.
+ addresses``
will result in SQL equivalent to::
SELECT user.* FROM user JOIN address ON user.id = address.user_id
In the above example we refer to ``User.addresses`` as passed to
- :meth:`~.Query.join` as the *on clause*, that is, it indicates
+ :meth:`_query.Query.join` as the *on clause*, that is, it indicates
how the "ON" portion of the JOIN should be constructed. For a
single-entity query such as the one above (i.e. we start by selecting
only from ``User`` and nothing else), the relationship can also be
q = session.query(User).join("addresses")
- :meth:`~.Query.join` can also accommodate multiple
+ :meth:`_query.Query.join` can also accommodate multiple
"on clause" arguments to produce a chain of joins, such as below
where a join across four related entities is constructed::
q = session.query(User).join("orders", "items", "keywords")
The above would be shorthand for three separate calls to
- :meth:`~.Query.join`, each using an explicit attribute to indicate
+ :meth:`_query.Query.join`,
+ each using an explicit attribute to indicate
the source entity::
q = session.query(User).\
**Joins to a Target Entity or Selectable**
- A second form of :meth:`~.Query.join` allows any mapped entity
+ A second form of :meth:`_query.Query.join` allows any mapped entity
or core selectable construct as a target. In this usage,
- :meth:`~.Query.join` will attempt
+ :meth:`_query.Query.join` will attempt
to create a JOIN along the natural foreign key relationship between
two entities::
q = session.query(User).join(Address)
- The above calling form of :meth:`~.Query.join` will raise an error if
+ The above calling form of :meth:`_query.Query.join`
+ will raise an error if
either there are no foreign keys between the two entities, or if
there are multiple foreign key linkages between them. In the
- above calling form, :meth:`~.Query.join` is called upon to
+ above calling form, :meth:`_query.Query.join` is called upon to
create the "on clause" automatically for us. The target can
- be any mapped entity or selectable, such as a :class:`.Table`::
+ be any mapped entity or selectable, such as a :class:`_schema.Table`::
q = session.query(User).join(addresses_table)
WHERE address.email_address = :email_address_1
AND address_1.email_address = :email_address_2
- The two-argument calling form of :meth:`~.Query.join`
+ The two-argument calling form of :meth:`_query.Query.join`
also allows us to construct arbitrary joins with SQL-oriented
"on clause" expressions, not relying upon configured relationships
at all. Any SQL expression can be passed as the ON clause
**Advanced Join Targeting and Adaption**
There is a lot of flexibility in what the "target" can be when using
- :meth:`~.Query.join`. As noted previously, it also accepts
- :class:`.Table` constructs and other selectables such as :func:`.alias`
- and :func:`~.sql.expression.select` constructs, with either the one or
+ :meth:`_query.Query.join`. As noted previously, it also accepts
+ :class:`_schema.Table` constructs and other selectables such as
+ :func:`.alias`
+ and :func:`_expression.select` constructs, with either the one or
two-argument forms::
addresses_q = select([Address.user_id]).\
q = session.query(User).\
join(addresses_q, addresses_q.c.user_id==User.id)
- :meth:`~.Query.join` also features the ability to *adapt* a
+ :meth:`_query.Query.join` also features the ability to *adapt* a
:meth:`~sqlalchemy.orm.relationship` -driven ON clause to the target
selectable. Below we construct a JOIN from ``User`` to a subquery
against ``Address``, allowing the relationship denoted by
**Controlling what to Join From**
- While :meth:`~.Query.join` exclusively deals with the "right"
+ While :meth:`_query.Query.join` exclusively deals with the "right"
side of the JOIN, we can also control the "left" side, in those
- cases where it's needed, using :meth:`~.Query.select_from`.
+ cases where it's needed, using :meth:`_query.Query.select_from`.
Below we construct a query against ``Address`` but can still
make usage of ``User.addresses`` as our ON clause by instructing
- the :class:`.Query` to select first from the ``User``
+ the :class:`_query.Query` to select first from the ``User``
entity::
q = session.query(Address).select_from(User).\
**Constructing Aliases Anonymously**
- :meth:`~.Query.join` can construct anonymous aliases
+ :meth:`_query.Query.join` can construct anonymous aliases
using the ``aliased=True`` flag. This feature is useful
when a query is being joined algorithmically, such as
when querying self-referentially to an arbitrary depth::
When ``aliased=True`` is used, the actual "alias" construct
is not explicitly available. To work with it, methods such as
- :meth:`.Query.filter` will adapt the incoming entity to
+ :meth:`_query.Query.filter` will adapt the incoming entity to
the last join point::
q = session.query(Node).\
When using automatic aliasing, the ``from_joinpoint=True``
argument can allow a multi-node join to be broken into
- multiple calls to :meth:`~.Query.join`, so that
+ multiple calls to :meth:`_query.Query.join`, so that
each path along the way can be further filtered::
q = session.query(Node).\
filter(Node.name == 'grandchild 1')
The filtering aliases above can then be reset back to the
- original ``Node`` entity using :meth:`~.Query.reset_joinpoint`::
+ original ``Node`` entity using :meth:`_query.Query.reset_joinpoint`::
q = session.query(Node).\
join("children", "children", aliased=True).\
A special two-argument calling form of the form ``target, onclause``
is also accepted.
:param aliased=False: If True, indicate that the JOIN target should be
- anonymously aliased. Subsequent calls to :meth:`~.Query.filter`
+ anonymously aliased. Subsequent calls to :meth:`_query.Query.filter`
and similar will adapt the incoming criterion to the target
- alias, until :meth:`~.Query.reset_joinpoint` is called.
+ alias, until :meth:`_query.Query.reset_joinpoint` is called.
:param isouter=False: If True, the join used will be a left outer join,
- just as if the :meth:`.Query.outerjoin` method were called. This
+ just as if the :meth:`_query.Query.outerjoin` method were called.
+ This
flag is here to maintain consistency with the same flag as accepted
- by :meth:`.FromClause.join` and other Core constructs.
+ by :meth:`_expression.FromClause.join` and other Core constructs.
.. versionadded:: 1.0.0
:ref:`ormtutorial_joins` in the ORM tutorial.
:ref:`inheritance_toplevel` for details on how
- :meth:`~.Query.join` is used for inheritance relationships.
+ :meth:`_query.Query.join` is used for inheritance relationships.
- :func:`.orm.join` - a standalone ORM-level join function,
- used internally by :meth:`.Query.join`, which in previous
+ :func:`_orm.join` - a standalone ORM-level join function,
+ used internally by :meth:`_query.Query.join`, which in previous
SQLAlchemy versions was the primary ORM-level joining interface.
"""
@_generative
@_assertions(_no_statement_condition)
def reset_joinpoint(self):
- """Return a new :class:`.Query`, where the "join point" has
+ """Return a new :class:`_query.Query`, where the "join point" has
been reset back to the base FROM entities of the query.
This method is usually used in conjunction with the
- ``aliased=True`` feature of the :meth:`~.Query.join`
- method. See the example in :meth:`~.Query.join` for how
+ ``aliased=True`` feature of the :meth:`_query.Query.join`
+ method. See the example in :meth:`_query.Query.join` for how
this is used.
"""
@_generative
@_assertions(_no_clauseelement_condition)
def select_from(self, *from_obj):
- r"""Set the FROM clause of this :class:`.Query` explicitly.
+ r"""Set the FROM clause of this :class:`_query.Query` explicitly.
- :meth:`.Query.select_from` is often used in conjunction with
- :meth:`.Query.join` in order to control which entity is selected
+ :meth:`_query.Query.select_from` is often used in conjunction with
+ :meth:`_query.Query.join` in order to control which entity is selected
from on the "left" side of the join.
The entity or selectable object here effectively replaces the
- "left edge" of any calls to :meth:`~.Query.join`, when no
+ "left edge" of any calls to :meth:`_query.Query.join`, when no
joinpoint is otherwise established - usually, the default "join
- point" is the leftmost entity in the :class:`~.Query` object's
+ point" is the leftmost entity in the :class:`_query.Query` object's
list of entities to be selected.
A typical example::
:param \*from_obj: collection of one or more entities to apply
to the FROM clause. Entities can be mapped classes,
- :class:`.AliasedClass` objects, :class:`.Mapper` objects
- as well as core :class:`.FromClause` elements like subqueries.
+ :class:`.AliasedClass` objects, :class:`_orm.Mapper` objects
+ as well as core :class:`_expression.FromClause`
+ elements like subqueries.
.. versionchanged:: 0.9
This method no longer applies the given FROM object
.. seealso::
- :meth:`~.Query.join`
+ :meth:`_query.Query.join`
- :meth:`.Query.select_entity_from`
+ :meth:`_query.Query.select_entity_from`
"""
@_generative
@_assertions(_no_clauseelement_condition)
def select_entity_from(self, from_obj):
- r"""Set the FROM clause of this :class:`.Query` to a
+ r"""Set the FROM clause of this :class:`_query.Query` to a
core selectable, applying it as a replacement FROM clause
for corresponding mapped entities.
- The :meth:`.Query.select_entity_from` method supplies an alternative
+ The :meth:`_query.Query.select_entity_from`
+ method supplies an alternative
approach to the use case of applying an :func:`.aliased` construct
explicitly throughout a query. Instead of referring to the
:func:`.aliased` construct explicitly,
- :meth:`.Query.select_entity_from` automatically *adapts* all
+ :meth:`_query.Query.select_entity_from` automatically *adapts* all
occurrences of the entity to the target selectable.
Given a case for :func:`.aliased` such as selecting ``User``
Above, we apply the ``user_alias`` object explicitly throughout the
query. When it's not feasible for ``user_alias`` to be referenced
- explicitly in many places, :meth:`.Query.select_entity_from` may be
+ explicitly in many places, :meth:`_query.Query.select_entity_from`
+ may be
used at the start of the query to adapt the existing ``User`` entity::
q = session.query(User).\
WHERE "user".id = :id_1) AS anon_1
WHERE anon_1.name = :name_1
- The :meth:`.Query.select_entity_from` method is similar to the
- :meth:`.Query.select_from` method, in that it sets the FROM clause
+ The :meth:`_query.Query.select_entity_from` method is similar to the
+ :meth:`_query.Query.select_from` method,
+ in that it sets the FROM clause
of the query. The difference is that it additionally applies
adaptation to the other parts of the query that refer to the
- primary entity. If above we had used :meth:`.Query.select_from`
+ primary entity. If above we had used :meth:`_query.Query.select_from`
instead, the SQL generated would have been:
.. sourcecode:: sql
WHERE "user".id = :id_1) AS anon_1
WHERE "user".name = :name_1
- To supply textual SQL to the :meth:`.Query.select_entity_from` method,
- we can make use of the :func:`.text` construct. However, the
- :func:`.text` construct needs to be aligned with the columns of our
+ To supply textual SQL to the :meth:`_query.Query.select_entity_from`
+ method,
+ we can make use of the :func:`_expression.text` construct. However,
+ the
+ :func:`_expression.text`
+ construct needs to be aligned with the columns of our
entity, which is achieved by making use of the
- :meth:`.TextClause.columns` method::
+ :meth:`_expression.TextClause.columns` method::
text_stmt = text("select id, name from user").columns(
User.id, User.name).subquery()
q = session.query(User).select_entity_from(text_stmt)
- :meth:`.Query.select_entity_from` itself accepts an :func:`.aliased`
+ :meth:`_query.Query.select_entity_from` itself accepts an
+ :func:`.aliased`
object, so that the special options of :func:`.aliased` such as
:paramref:`.aliased.adapt_on_names` may be used within the
- scope of the :meth:`.Query.select_entity_from` method's adaptation
+ scope of the :meth:`_query.Query.select_entity_from`
+ method's adaptation
services. Suppose
a view ``user_view`` also returns rows from ``user``. If
- we reflect this view into a :class:`.Table`, this view has no
- relationship to the :class:`.Table` to which we are mapped, however
+ we reflect this view into a :class:`_schema.Table`, this view has no
+ relationship to the :class:`_schema.Table` to which we are mapped,
+ however
we can use name matching to select from it::
user_view = Table('user_view', metadata,
select_entity_from(user_view_alias).\
order_by(User.name)
- .. versionchanged:: 1.1.7 The :meth:`.Query.select_entity_from`
+ .. versionchanged:: 1.1.7 The :meth:`_query.Query.select_entity_from`
method now accepts an :func:`.aliased` object as an alternative
- to a :class:`.FromClause` object.
+ to a :class:`_expression.FromClause` object.
- :param from_obj: a :class:`.FromClause` object that will replace
- the FROM clause of this :class:`.Query`. It also may be an instance
+ :param from_obj: a :class:`_expression.FromClause`
+ object that will replace
+ the FROM clause of this :class:`_query.Query`.
+ It also may be an instance
of :func:`.aliased`.
.. seealso::
- :meth:`.Query.select_from`
+ :meth:`_query.Query.select_from`
"""
@_generative
@_assertions(_no_statement_condition)
def slice(self, start, stop):
- """Computes the "slice" of the :class:`.Query` represented by
- the given indices and returns the resulting :class:`.Query`.
+ """Computes the "slice" of the :class:`_query.Query` represented by
+ the given indices and returns the resulting :class:`_query.Query`.
The start and stop indices behave like the argument to Python's
built-in :func:`range` function. This method provides an
.. seealso::
- :meth:`.Query.limit`
+ :meth:`_query.Query.limit`
- :meth:`.Query.offset`
+ :meth:`_query.Query.offset`
"""
if start is not None and stop is not None:
columns clause of the SELECT statement, to satisfy the common need
of the database backend that ORDER BY columns be part of the SELECT
list when DISTINCT is used. These columns *are not* added to the
- list of columns actually fetched by the :class:`.Query`, however,
+ list of columns actually fetched by the :class:`_query.Query`,
+ however,
so would not affect results. The columns are passed through when
- using the :attr:`.Query.statement` accessor, however.
+ using the :attr:`_query.Query.statement` accessor, however.
.. deprecated:: 2.0 This logic is deprecated and will be removed
in SQLAlchemy 2.0. See :ref:`migration_20_query_distinct`
.. seealso::
- :meth:`.HasPrefixes.prefix_with`
+ :meth:`_expression.HasPrefixes.prefix_with`
"""
if self._prefixes:
.. seealso::
- :meth:`.Query.prefix_with`
+ :meth:`_query.Query.prefix_with`
- :meth:`.HasSuffixes.suffix_with`
+ :meth:`_expression.HasSuffixes.suffix_with`
"""
if self._suffixes:
self._suffixes = suffixes
def all(self):
- """Return the results represented by this :class:`.Query` as a list.
+ """Return the results represented by this :class:`_query.Query`
+ as a list.
This results in an execution of the underlying SQL statement.
- .. warning:: The :class:`.Query` object, when asked to return either
+ .. warning:: The :class:`_query.Query` object,
+ when asked to return either
a sequence or iterator that consists of full ORM-mapped entities,
will **deduplicate entries based on primary key**. See the FAQ for
more details.
This method bypasses all internal statement compilation, and the
statement is executed without modification.
- The statement is typically either a :func:`~.expression.text`
- or :func:`~.expression.select` construct, and should return the set
+ The statement is typically either a :func:`_expression.text`
+ or :func:`_expression.select` construct, and should return the set
of columns
- appropriate to the entity class represented by this :class:`.Query`.
+ appropriate to the entity class represented by this
+ :class:`_query.Query`.
.. seealso::
(note this may consist of multiple result rows if join-loaded
collections are present).
- Calling :meth:`.Query.first` results in an execution of the underlying
+ Calling :meth:`_query.Query.first`
+ results in an execution of the underlying
query.
.. seealso::
- :meth:`.Query.one`
+ :meth:`_query.Query.one`
- :meth:`.Query.one_or_none`
+ :meth:`_query.Query.one_or_none`
"""
if self._statement is not None:
rows are returned for a query that returns only scalar values
as opposed to full identity-mapped entities.
- Calling :meth:`.Query.one_or_none` results in an execution of the
+ Calling :meth:`_query.Query.one_or_none`
+ results in an execution of the
underlying query.
.. versionadded:: 1.0.9
- Added :meth:`.Query.one_or_none`
+ Added :meth:`_query.Query.one_or_none`
.. seealso::
- :meth:`.Query.first`
+ :meth:`_query.Query.first`
- :meth:`.Query.one`
+ :meth:`_query.Query.one`
"""
ret = list(self)
.. seealso::
- :meth:`.Query.first`
+ :meth:`_query.Query.first`
- :meth:`.Query.one_or_none`
+ :meth:`_query.Query.one_or_none`
"""
try:
@property
def column_descriptions(self):
"""Return metadata about the columns which would be
- returned by this :class:`.Query`.
+ returned by this :class:`_query.Query`.
Format is a list of dictionaries::
util.warn_deprecated(
"Using the Query.instances() method without a context "
"is deprecated and will be disallowed in a future release. "
- "Please make use of :meth:`.Query.from_statement` "
+ "Please make use of :meth:`_query.Query.from_statement` "
"for linking ORM results to arbitrary select constructs.",
version="1.4",
)
return loading.instances(self, result_proxy, context)
def merge_result(self, iterator, load=True):
- """Merge a result into this :class:`.Query` object's Session.
+ """Merge a result into this :class:`_query.Query` object's Session.
- Given an iterator returned by a :class:`.Query` of the same structure
+ Given an iterator returned by a :class:`_query.Query`
+ of the same structure
as this one, return an identical iterator of results, with all mapped
instances merged into the session using :meth:`.Session.merge`. This
is an optimized method which will merge all mapped instances,
explicitly for each value.
The structure of the results is determined based on the column list of
- this :class:`.Query` - if these do not correspond, unchecked errors
+ this :class:`_query.Query` - if these do not correspond,
+ unchecked errors
will occur.
The 'load' argument is the same as that of :meth:`.Session.merge`.
- For an example of how :meth:`~.Query.merge_result` is used, see
+ For an example of how :meth:`_query.Query.merge_result` is used, see
the source code for the example :ref:`examples_caching`, where
- :meth:`~.Query.merge_result` is used to efficiently restore state
+ :meth:`_query.Query.merge_result` is used to efficiently restore state
from a cache back into a target :class:`.Session`.
"""
) AS anon_1
The above SQL returns a single row, which is the aggregate value
- of the count function; the :meth:`.Query.count` method then returns
+ of the count function; the :meth:`_query.Query.count`
+ method then returns
that single integer value.
.. warning::
It is important to note that the value returned by
count() is **not the same as the number of ORM objects that this
Query would return from a method such as the .all() method**.
- The :class:`.Query` object, when asked to return full entities,
+ The :class:`_query.Query` object,
+ when asked to return full entities,
will **deduplicate entries based on primary key**, meaning if the
same primary key value would appear in the results more than once,
only one object of that primary key would be present. This does
sess.query(User).filter(User.age == 25).\
delete(synchronize_session='evaluate')
- .. warning:: The :meth:`.Query.delete` method is a "bulk" operation,
+ .. warning:: The :meth:`_query.Query.delete`
+ method is a "bulk" operation,
which bypasses ORM unit-of-work automation in favor of greater
performance. **Please read all caveats and warnings below.**
.. seealso::
- :meth:`.Query.update`
+ :meth:`_query.Query.update`
:ref:`inserts_and_updates` - Core SQL tutorial
update({"age": User.age - 10}, synchronize_session='evaluate')
- .. warning:: The :meth:`.Query.update` method is a "bulk" operation,
+ .. warning:: The :meth:`_query.Query.update`
+ method is a "bulk" operation,
which bypasses ORM unit-of-work automation in favor of greater
performance. **Please read all caveats and warnings below.**
string collations between the database and Python.
:param update_args: Optional dictionary, if present will be passed
- to the underlying :func:`.update` construct as the ``**kw`` for
+ to the underlying :func:`_expression.update`
+ construct as the ``**kw`` for
the object. May be used to pass dialect-specific arguments such
as ``mysql_limit``, as well as other special arguments such as
:paramref:`~sqlalchemy.sql.expression.update.preserve_parameter_order`.
.. seealso::
- :meth:`.Query.delete`
+ :meth:`_query.Query.delete`
:ref:`inserts_and_updates` - Core SQL tutorial
@inspection._self_inspects
class Bundle(InspectionAttr):
- """A grouping of SQL expressions that are returned by a :class:`.Query`
+ """A grouping of SQL expressions that are returned by a
+ :class:`_query.Query`
under one namespace.
The :class:`.Bundle` essentially allows nesting of the tuple-based
- results returned by a column-oriented :class:`.Query` object. It also
+ results returned by a column-oriented :class:`_query.Query` object.
+ It also
is extensible via simple subclassing, where the primary capability
to override is that of how the set of expressions should be returned,
allowing post-processing as well as custom return types, without
class AliasOption(interfaces.MapperOption):
def __init__(self, alias):
- r"""Return a :class:`.MapperOption` that will indicate to the :class:`.Query`
+ r"""Return a :class:`.MapperOption` that will indicate to the
+ :class:`_query.Query`
that the main table has been aliased.
This is a seldom-used option to suit the
results = query.from_statement(statement).all()
:param alias: is the string name of an alias, or a
- :class:`~.sql.expression.Alias` object representing
+ :class:`_expression.Alias` object representing
the alias.
"""
# the MIT License: http://www.opensource.org/licenses/mit-license.php
"""Heuristics related to join conditions as used in
-:func:`.relationship`.
+:func:`_orm.relationship`.
Provides the :class:`.JoinCondition` object, which encapsulates
SQL annotation and aliasing behavior focused on the `primaryjoin`
-and `secondaryjoin` aspects of :func:`.relationship`.
+and `secondaryjoin` aspects of :func:`_orm.relationship`.
"""
from __future__ import absolute_import
"""Describes an object property that holds a single item or list
of items that correspond to a related database table.
- Public constructor is the :func:`.orm.relationship` function.
+ Public constructor is the :func:`_orm.relationship` function.
.. seealso::
The constructed class is an instance of
:class:`.RelationshipProperty`.
- A typical :func:`.relationship`, used in a classical mapping::
+ A typical :func:`_orm.relationship`, used in a classical mapping::
mapper(Parent, properties={
'children': relationship(Child)
})
- Some arguments accepted by :func:`.relationship` optionally accept a
+ Some arguments accepted by :func:`_orm.relationship`
+ optionally accept a
callable function, which when called produces the desired value.
- The callable is invoked by the parent :class:`.Mapper` at "mapper
+ The callable is invoked by the parent :class:`_orm.Mapper` at "mapper
initialization" time, which happens only when mappers are first used,
and is assumed to be after all mappings have been constructed. This
can be used to resolve order-of-declaration and other dependency
When using the :ref:`declarative_toplevel` extension, the Declarative
initializer allows string arguments to be passed to
- :func:`.relationship`. These string arguments are converted into
+ :func:`_orm.relationship`. These string arguments are converted into
callables that evaluate the string as Python code, using the
Declarative class-registry as a namespace. This allows the lookup of
related classes to be automatic via their string name, and removes the
that the modules in which these related classes appear are imported
anywhere in the application at some point before the related mappings
are actually used, else a lookup error will be raised when the
- :func:`.relationship` attempts to resolve the string reference to the
+ :func:`_orm.relationship`
+ attempts to resolve the string reference to the
related class. An example of a string- resolved class is as
follows::
.. seealso::
:ref:`relationship_config_toplevel` - Full introductory and
- reference documentation for :func:`.relationship`.
+ reference documentation for :func:`_orm.relationship`.
:ref:`orm_tutorial_relationship` - ORM tutorial introduction.
:param argument:
- a mapped class, or actual :class:`.Mapper` instance, representing
+ a mapped class, or actual :class:`_orm.Mapper` instance,
+ representing
the target of the relationship.
- :paramref:`~.relationship.argument` may also be passed as a callable
+ :paramref:`_orm.relationship.argument`
+ may also be passed as a callable
function which is evaluated at mapper initialization time, and may
be passed as a string name when using Declarative.
using Python's ``eval()`` function.
**DO NOT PASS UNTRUSTED INPUT TO THIS STRING**.
See :ref:`declarative_relationship_eval` for details on
- declarative evaluation of :func:`.relationship` arguments.
+ declarative evaluation of :func:`_orm.relationship` arguments.
.. versionchanged 1.3.16::
:param secondary:
for a many-to-many relationship, specifies the intermediary
- table, and is typically an instance of :class:`.Table`.
+ table, and is typically an instance of :class:`_schema.Table`.
In less common circumstances, the argument may also be specified
- as an :class:`.Alias` construct, or even a :class:`.Join` construct.
+ as an :class:`_expression.Alias` construct, or even a
+ :class:`_expression.Join` construct.
- :paramref:`~.relationship.secondary` may
+ :paramref:`_orm.relationship.secondary` may
also be passed as a callable function which is evaluated at
mapper initialization time. When using Declarative, it may also
- be a string argument noting the name of a :class:`.Table` that is
- present in the :class:`.MetaData` collection associated with the
- parent-mapped :class:`.Table`.
+ be a string argument noting the name of a :class:`_schema.Table`
+ that is
+ present in the :class:`_schema.MetaData`
+ collection associated with the
+ parent-mapped :class:`_schema.Table`.
.. warning:: When passed as a Python-evaluable string, the
argument is interpreted using Python's ``eval()`` function.
**DO NOT PASS UNTRUSTED INPUT TO THIS STRING**.
See :ref:`declarative_relationship_eval` for details on
- declarative evaluation of :func:`.relationship` arguments.
+ declarative evaluation of :func:`_orm.relationship` arguments.
- The :paramref:`~.relationship.secondary` keyword argument is
- typically applied in the case where the intermediary :class:`.Table`
+ The :paramref:`_orm.relationship.secondary` keyword argument is
+ typically applied in the case where the intermediary
+ :class:`_schema.Table`
is not otherwise expressed in any direct class mapping. If the
"secondary" table is also explicitly mapped elsewhere (e.g. as in
:ref:`association_pattern`), one should consider applying the
- :paramref:`~.relationship.viewonly` flag so that this
- :func:`.relationship` is not used for persistence operations which
+ :paramref:`_orm.relationship.viewonly` flag so that this
+ :func:`_orm.relationship`
+ is not used for persistence operations which
may conflict with those of the association object pattern.
.. seealso::
Declarative.
:ref:`association_pattern` - an alternative to
- :paramref:`~.relationship.secondary` when composing association
+ :paramref:`_orm.relationship.secondary`
+ when composing association
table relationships, allowing additional attributes to be
specified on the association table.
:ref:`composite_secondary_join` - a lesser-used pattern which
- in some cases can enable complex :func:`.relationship` SQL
+ in some cases can enable complex :func:`_orm.relationship` SQL
conditions to be used.
- .. versionadded:: 0.9.2 :paramref:`~.relationship.secondary` works
- more effectively when referring to a :class:`.Join` instance.
+ .. versionadded:: 0.9.2 :paramref:`_orm.relationship.secondary`
+ works
+ more effectively when referring to a :class:`_expression.Join`
+ instance.
:param active_history=False:
When ``True``, indicates that the "previous" value for a
:ref:`relationships_backref` - Introductory documentation and
examples.
- :paramref:`~.relationship.back_populates` - alternative form
+ :paramref:`_orm.relationship.back_populates` - alternative form
of backref specification.
- :func:`.backref` - allows control over :func:`.relationship`
- configuration when using :paramref:`~.relationship.backref`.
+ :func:`.backref` - allows control over :func:`_orm.relationship`
+ configuration when using :paramref:`_orm.relationship.backref`.
:param back_populates:
Takes a string name and has the same meaning as
- :paramref:`~.relationship.backref`, except the complementing
+ :paramref:`_orm.relationship.backref`, except the complementing
property is **not** created automatically, and instead must be
configured explicitly on the other mapper. The complementing
property should also indicate
- :paramref:`~.relationship.back_populates` to this relationship to
+ :paramref:`_orm.relationship.back_populates` to this relationship to
ensure proper functioning.
.. seealso::
:ref:`relationships_backref` - Introductory documentation and
examples.
- :paramref:`~.relationship.backref` - alternative form
+ :paramref:`_orm.relationship.backref` - alternative form
of backref specification.
:param overlaps:
.. seealso::
:ref:`backref_cascade` - Full discussion and examples on how
- the :paramref:`~.relationship.cascade_backrefs` option is used.
+ the :paramref:`_orm.relationship.cascade_backrefs` option is used.
:param collection_class:
a class or callable that returns a new list-holding object. will
duplicate innermost rows may be causing.
.. versionchanged:: 0.9.0 -
- :paramref:`~.relationship.distinct_target_key` now defaults to
+ :paramref:`_orm.relationship.distinct_target_key` now defaults to
``None``, so that the feature enables itself automatically for
those cases where the innermost query targets a non-unique
key.
a list of columns which are to be used as "foreign key"
columns, or columns which refer to the value in a remote
- column, within the context of this :func:`.relationship`
- object's :paramref:`~.relationship.primaryjoin` condition.
- That is, if the :paramref:`~.relationship.primaryjoin`
- condition of this :func:`.relationship` is ``a.id ==
+ column, within the context of this :func:`_orm.relationship`
+ object's :paramref:`_orm.relationship.primaryjoin` condition.
+ That is, if the :paramref:`_orm.relationship.primaryjoin`
+ condition of this :func:`_orm.relationship` is ``a.id ==
b.a_id``, and the values in ``b.a_id`` are required to be
present in ``a.id``, then the "foreign key" column of this
- :func:`.relationship` is ``b.a_id``.
+ :func:`_orm.relationship` is ``b.a_id``.
- In normal cases, the :paramref:`~.relationship.foreign_keys`
- parameter is **not required.** :func:`.relationship` will
+ In normal cases, the :paramref:`_orm.relationship.foreign_keys`
+ parameter is **not required.** :func:`_orm.relationship` will
automatically determine which columns in the
- :paramref:`~.relationship.primaryjoin` condition are to be
+ :paramref:`_orm.relationship.primaryjoin` condition are to be
considered "foreign key" columns based on those
- :class:`.Column` objects that specify :class:`.ForeignKey`,
+ :class:`_schema.Column` objects that specify
+ :class:`_schema.ForeignKey`,
or are otherwise listed as referencing columns in a
- :class:`.ForeignKeyConstraint` construct.
- :paramref:`~.relationship.foreign_keys` is only needed when:
+ :class:`_schema.ForeignKeyConstraint` construct.
+ :paramref:`_orm.relationship.foreign_keys` is only needed when:
1. There is more than one way to construct a join from the local
table to the remote table, as there are multiple foreign key
references present. Setting ``foreign_keys`` will limit the
- :func:`.relationship` to consider just those columns specified
+ :func:`_orm.relationship`
+ to consider just those columns specified
here as "foreign".
- 2. The :class:`.Table` being mapped does not actually have
- :class:`.ForeignKey` or :class:`.ForeignKeyConstraint`
+ 2. The :class:`_schema.Table` being mapped does not actually have
+ :class:`_schema.ForeignKey` or
+ :class:`_schema.ForeignKeyConstraint`
constructs present, often because the table
was reflected from a database that does not support foreign key
reflection (MySQL MyISAM).
- 3. The :paramref:`~.relationship.primaryjoin` argument is used to
+ 3. The :paramref:`_orm.relationship.primaryjoin`
+ argument is used to
construct a non-standard join condition, which makes use of
columns or expressions that do not normally refer to their
"parent" column, such as a join condition expressed by a
complex comparison using a SQL function.
- The :func:`.relationship` construct will raise informative
+ The :func:`_orm.relationship` construct will raise informative
error messages that suggest the use of the
- :paramref:`~.relationship.foreign_keys` parameter when
+ :paramref:`_orm.relationship.foreign_keys` parameter when
presented with an ambiguous condition. In typical cases,
- if :func:`.relationship` doesn't raise any exceptions, the
- :paramref:`~.relationship.foreign_keys` parameter is usually
+ if :func:`_orm.relationship` doesn't raise any exceptions, the
+ :paramref:`_orm.relationship.foreign_keys` parameter is usually
not needed.
- :paramref:`~.relationship.foreign_keys` may also be passed as a
+ :paramref:`_orm.relationship.foreign_keys` may also be passed as a
callable function which is evaluated at mapper initialization time,
and may be passed as a Python-evaluable string when using
Declarative.
argument is interpreted using Python's ``eval()`` function.
**DO NOT PASS UNTRUSTED INPUT TO THIS STRING**.
See :ref:`declarative_relationship_eval` for details on
- declarative evaluation of :func:`.relationship` arguments.
+ declarative evaluation of :func:`_orm.relationship` arguments.
.. seealso::
:ref:`relationship_custom_foreign`
:func:`.foreign` - allows direct annotation of the "foreign"
- columns within a :paramref:`~.relationship.primaryjoin` condition.
+ columns within a :paramref:`_orm.relationship.primaryjoin`
+ condition.
:param info: Optional data dictionary which will be populated into the
:attr:`.MapperProperty.info` attribute of this object.
is guaranteed to have one or at least one entry.
The option supports the same "nested" and "unnested" options as
- that of :paramref:`.joinedload.innerjoin`. See that flag
+ that of :paramref:`_orm.joinedload.innerjoin`. See that flag
for details on nested / unnested behaviors.
.. seealso::
- :paramref:`.joinedload.innerjoin` - the option as specified by
+ :paramref:`_orm.joinedload.innerjoin` - the option as specified by
loader option, including detail on nesting behavior.
:ref:`what_kind_of_loading` - Discussion of some details of
* ``joined`` - items should be loaded "eagerly" in the same query as
that of the parent, using a JOIN or LEFT OUTER JOIN. Whether
the join is "outer" or not is determined by the
- :paramref:`~.relationship.innerjoin` parameter.
+ :paramref:`_orm.relationship.innerjoin` parameter.
* ``subquery`` - items should be loaded "eagerly" as the parents are
loaded, using one additional SQL statement, which issues a JOIN to
.. versionadded:: 1.1
* ``dynamic`` - the attribute will return a pre-configured
- :class:`.Query` object for all read
+ :class:`_query.Query` object for all read
operations, onto which further filtering operations can be
applied before iterating the results. See
the section :ref:`dynamic_relationship` for more details.
"attached" to a :class:`.Session` but is not part of its pending
collection.
- The :paramref:`~.relationship.load_on_pending` flag does not improve
+ The :paramref:`_orm.relationship.load_on_pending`
+ flag does not improve
behavior when the ORM is used normally - object references should be
constructed at the object level, not at the foreign key level, so
that they are present in an ordinary way before a flush proceeds.
:param order_by:
indicates the ordering that should be applied when loading these
- items. :paramref:`~.relationship.order_by` is expected to refer to
- one of the :class:`.Column` objects to which the target class is
+ items. :paramref:`_orm.relationship.order_by`
+ is expected to refer to
+ one of the :class:`_schema.Column`
+ objects to which the target class is
mapped, or the attribute itself bound to the target class which
refers to the column.
- :paramref:`~.relationship.order_by` may also be passed as a callable
+ :paramref:`_orm.relationship.order_by`
+ may also be passed as a callable
function which is evaluated at mapper initialization time, and may
be passed as a Python-evaluable string when using Declarative.
argument is interpreted using Python's ``eval()`` function.
**DO NOT PASS UNTRUSTED INPUT TO THIS STRING**.
See :ref:`declarative_relationship_eval` for details on
- declarative evaluation of :func:`.relationship` arguments.
+ declarative evaluation of :func:`_orm.relationship` arguments.
:param passive_deletes=False:
Indicates loading behavior during delete operations.
When True, it is assumed that ``ON UPDATE CASCADE`` is configured on
the foreign key in the database, and that the database will
handle propagation of an UPDATE from a source column to
- dependent rows. When False, the SQLAlchemy :func:`.relationship`
+ dependent rows. When False, the SQLAlchemy
+ :func:`_orm.relationship`
construct will attempt to emit its own UPDATE statements to
modify related targets. However note that SQLAlchemy **cannot**
emit an UPDATE for more than one level of cascade. Also,
list (i.e. both tables contain a foreign key to each other). If
a flush operation returns an error that a "cyclical
dependency" was detected, this is a cue that you might want to
- use :paramref:`~.relationship.post_update` to "break" the cycle.
+ use :paramref:`_orm.relationship.post_update` to "break" the cycle.
.. seealso::
foreign key relationships of the parent and child tables (or
association table).
- :paramref:`~.relationship.primaryjoin` may also be passed as a
+ :paramref:`_orm.relationship.primaryjoin` may also be passed as a
callable function which is evaluated at mapper initialization time,
and may be passed as a Python-evaluable string when using
Declarative.
argument is interpreted using Python's ``eval()`` function.
**DO NOT PASS UNTRUSTED INPUT TO THIS STRING**.
See :ref:`declarative_relationship_eval` for details on
- declarative evaluation of :func:`.relationship` arguments.
+ declarative evaluation of :func:`_orm.relationship` arguments.
.. seealso::
used for self-referential relationships, indicates the column or
list of columns that form the "remote side" of the relationship.
- :paramref:`.relationship.remote_side` may also be passed as a
+ :paramref:`_orm.relationship.remote_side` may also be passed as a
callable function which is evaluated at mapper initialization time,
and may be passed as a Python-evaluable string when using
Declarative.
argument is interpreted using Python's ``eval()`` function.
**DO NOT PASS UNTRUSTED INPUT TO THIS STRING**.
See :ref:`declarative_relationship_eval` for details on
- declarative evaluation of :func:`.relationship` arguments.
+ declarative evaluation of :func:`_orm.relationship` arguments.
.. seealso::
:ref:`self_referential` - in-depth explanation of how
- :paramref:`~.relationship.remote_side`
+ :paramref:`_orm.relationship.remote_side`
is used to configure self-referential relationships.
:func:`.remote` - an annotation function that accomplishes the
- same purpose as :paramref:`~.relationship.remote_side`, typically
- when a custom :paramref:`~.relationship.primaryjoin` condition
+ same purpose as :paramref:`_orm.relationship.remote_side`,
+ typically
+ when a custom :paramref:`_orm.relationship.primaryjoin` condition
is used.
:param query_class:
- a :class:`.Query` subclass that will be used as the base of the
+ a :class:`_query.Query`
+ subclass that will be used as the base of the
"appender query" returned by a "dynamic" relationship, that
is, a relationship that specifies ``lazy="dynamic"`` or was
- otherwise constructed using the :func:`.orm.dynamic_loader`
+ otherwise constructed using the :func:`_orm.dynamic_loader`
function.
.. seealso::
computed based on the foreign key relationships of the association
and child tables.
- :paramref:`~.relationship.secondaryjoin` may also be passed as a
+ :paramref:`_orm.relationship.secondaryjoin` may also be passed as a
callable function which is evaluated at mapper initialization time,
and may be passed as a Python-evaluable string when using
Declarative.
argument is interpreted using Python's ``eval()`` function.
**DO NOT PASS UNTRUSTED INPUT TO THIS STRING**.
See :ref:`declarative_relationship_eval` for details on
- declarative evaluation of :func:`.relationship` arguments.
+ declarative evaluation of :func:`_orm.relationship` arguments.
.. seealso::
from being associated with more than one parent at a time.
This is used for many-to-one or many-to-many relationships that
should be treated either as one-to-one or one-to-many. Its usage
- is optional, except for :func:`.relationship` constructs which
+ is optional, except for :func:`_orm.relationship` constructs which
are many-to-one or many-to-many and also
specify the ``delete-orphan`` cascade option. The
- :func:`.relationship` construct itself will raise an error
+ :func:`_orm.relationship` construct itself will raise an error
instructing when this option is required.
.. seealso::
:ref:`unitofwork_cascades` - includes detail on when the
- :paramref:`~.relationship.single_parent` flag may be appropriate.
+ :paramref:`_orm.relationship.single_parent`
+ flag may be appropriate.
:param uselist:
a boolean that indicates if this property should be loaded as a
list or a scalar. In most cases, this value is determined
- automatically by :func:`.relationship` at mapper configuration
+ automatically by :func:`_orm.relationship` at mapper configuration
time, based on the type and direction
of the relationship - one to many forms a list, many to one
forms a scalar, many to many is a list. If a scalar is desired
where normally a list would be present, such as a bi-directional
- one-to-one relationship, set :paramref:`~.relationship.uselist` to
+ one-to-one relationship, set :paramref:`_orm.relationship.uselist`
+ to
False.
- The :paramref:`~.relationship.uselist` flag is also available on an
- existing :func:`.relationship` construct as a read-only attribute,
- which can be used to determine if this :func:`.relationship` deals
+ The :paramref:`_orm.relationship.uselist`
+ flag is also available on an
+ existing :func:`_orm.relationship`
+ construct as a read-only attribute,
+ which can be used to determine if this :func:`_orm.relationship`
+ deals
with collections or scalar attributes::
>>> User.addresses.property.uselist
:ref:`relationships_one_to_one` - Introduction to the "one to
one" relationship pattern, which is typically when the
- :paramref:`~.relationship.uselist` flag is needed.
+ :paramref:`_orm.relationship.uselist` flag is needed.
:param viewonly=False:
when set to True, the relationship is used only for loading objects,
- and not for any persistence operation. A :func:`.relationship`
- which specifies :paramref:`~.relationship.viewonly` can work
+ and not for any persistence operation. A :func:`_orm.relationship`
+ which specifies :paramref:`_orm.relationship.viewonly` can work
with a wider range of SQL operations within the
- :paramref:`~.relationship.primaryjoin` condition, including
+ :paramref:`_orm.relationship.primaryjoin` condition, including
operations that feature the use of a variety of comparison operators
- as well as SQL functions such as :func:`~.sql.expression.cast`. The
- :paramref:`~.relationship.viewonly` flag is also of general use when
- defining any kind of :func:`~.relationship` that doesn't represent
+ as well as SQL functions such as :func:`_expression.cast`. The
+ :paramref:`_orm.relationship.viewonly`
+ flag is also of general use when
+ defining any kind of :func:`_orm.relationship`
+ that doesn't represent
the full set of related objects, to prevent modifications of the
collection from resulting in persistence operations.
be accessed via read. Towards this behavior, it is also not
appropriate for the viewonly=True relationship to have any kind
of persistence cascade settings, nor should it be the target of
- either :paramref:`.relationship.backref` or
- :paramref:`.relationship.back_populates`, as backrefs imply
+ either :paramref:`_orm.relationship.backref` or
+ :paramref:`_orm.relationship.back_populates`, as backrefs imply
in-Python mutation of the attribute. SQLAlchemy may emit
warnings for some or all of these conditions as of the 1.3 and
1.4 series of SQLAlchemy and will eventually be disallowed.
"""The target entity referred to by this
:class:`.RelationshipProperty.Comparator`.
- This is either a :class:`.Mapper` or :class:`.AliasedInsp`
+ This is either a :class:`_orm.Mapper` or :class:`.AliasedInsp`
object.
This is the "target" or "remote" side of the
- :func:`.relationship`.
+ :func:`_orm.relationship`.
"""
return self.property.entity
@util.memoized_property
def mapper(self):
- """The target :class:`.Mapper` referred to by this
+ """The target :class:`_orm.Mapper` referred to by this
:class:`.RelationshipProperty.Comparator`.
This is the "target" or "remote" side of the
- :func:`.relationship`.
+ :func:`_orm.relationship`.
"""
return self.property.mapper
def in_(self, other):
"""Produce an IN clause - this is not implemented
- for :func:`~.orm.relationship`-based attributes at this time.
+ for :func:`_orm.relationship`-based attributes at this time.
"""
raise NotImplementedError(
related.my_id=my_table.id))
:meth:`~.RelationshipProperty.Comparator.any` is only
- valid for collections, i.e. a :func:`.relationship`
+ valid for collections, i.e. a :func:`_orm.relationship`
that has ``uselist=True``. For scalar references,
use :meth:`~.RelationshipProperty.Comparator.has`.
using a join.
:meth:`~.RelationshipProperty.Comparator.has` is only
- valid for scalar references, i.e. a :func:`.relationship`
+ valid for scalar references, i.e. a :func:`_orm.relationship`
that has ``uselist=False``. For collection references,
use :meth:`~.RelationshipProperty.Comparator.any`.
:meth:`~.RelationshipProperty.Comparator.contains` is
only valid for a collection, i.e. a
- :func:`~.orm.relationship` that implements
+ :func:`_orm.relationship` that implements
one-to-many or many-to-many with ``uselist=True``.
When used in a simple one-to-many context, an
explicit "outer joins" will need to be used instead.
See :meth:`~.RelationshipProperty.Comparator.any` for
a less-performant alternative using EXISTS, or refer
- to :meth:`.Query.outerjoin` as well as :ref:`ormtutorial_joins`
+ to :meth:`_query.Query.outerjoin`
+ as well as :ref:`ormtutorial_joins`
for more details on constructing outer joins.
"""
* Comparisons against collections are not supported.
Use
:meth:`~.RelationshipProperty.Comparator.contains`
- in conjunction with :func:`~.expression.not_`.
+ in conjunction with :func:`_expression.not_`.
* Compared to a scalar one-to-many, will produce a
clause that compares the target columns in the parent to
the given target.
comparisons, such as those which use OR. Use
explicit joins, outerjoins, or
:meth:`~.RelationshipProperty.Comparator.has` in
- conjunction with :func:`~.expression.not_` for
+ conjunction with :func:`_expression.not_` for
more comprehensive non-many-to-one scalar
membership tests.
* Comparisons against ``None`` given in a one-to-many
@util.memoized_property
def mapper(self):
- """Return the targeted :class:`.Mapper` for this
+ """Return the targeted :class:`_orm.Mapper` for this
:class:`.RelationshipProperty`.
This is a lazy-initializing static attribute.
def _generate_backref(self):
"""Interpret the 'backref' instruction to create a
- :func:`.relationship` complementary to this one."""
+ :func:`_orm.relationship` complementary to this one."""
if self.parent.non_primary:
return
session_factory = None
"""The `session_factory` provided to `__init__` is stored in this
attribute and may be accessed at a later time. This can be useful when
- a new non-scoped :class:`.Session` or :class:`.Connection` to the
+ a new non-scoped :class:`.Session` or :class:`_engine.Connection` to the
database is needed."""
def __init__(self, session_factory, scopefunc=None):
self.session_factory.configure(**kwargs)
def query_property(self, query_cls=None):
- """return a class property which produces a :class:`.Query` object
+ """return a class property which produces a :class:`_query.Query`
+ object
against the class and the current :class:`.Session` when called.
e.g.::
:class:`.SessionTransaction` is a mostly behind-the-scenes object
not normally referenced directly by application code. It coordinates
- among multiple :class:`.Connection` objects, maintaining a database
+ among multiple :class:`_engine.Connection` objects, maintaining a database
transaction for each one individually, committing or rolling them
back all at once. It also provides optional two-phase commit behavior
which can augment this coordination operation.
its default mode of ``autocommit=False`` whenever the "autobegin" process
takes place, associated with no database connections. As the
:class:`.Session` is called upon to emit SQL on behalf of various
- :class:`.Engine` or :class:`.Connection` objects, a corresponding
- :class:`.Connection` and associated :class:`.Transaction` is added to a
+ :class:`_engine.Engine` or :class:`_engine.Connection` objects,
+ a corresponding
+ :class:`_engine.Connection` and associated :class:`.Transaction`
+ is added to a
collection within the :class:`.SessionTransaction` object, becoming one of
the connection/transaction pairs maintained by the
:class:`.SessionTransaction`. The start of a :class:`.SessionTransaction`
:meth:`~.Session.flush` are rarely needed; you usually only need to
call :meth:`~.Session.commit` (which flushes) to finalize changes.
- :param bind: An optional :class:`.Engine` or :class:`.Connection` to
+ :param bind: An optional :class:`_engine.Engine` or
+ :class:`_engine.Connection` to
which this ``Session`` should be bound. When specified, all SQL
operations performed by this session will execute via this
connectable.
:param binds: A dictionary which may specify any number of
- :class:`.Engine` or :class:`.Connection` objects as the source of
+ :class:`_engine.Engine` or :class:`_engine.Connection`
+ objects as the source of
connectivity for SQL operations on a per-entity basis. The keys
of the dictionary consist of any series of mapped classes,
arbitrary Python classes that are bases for mapped classes,
- :class:`.Table` objects and :class:`.Mapper` objects. The
- values of the dictionary are then instances of :class:`.Engine`
- or less commonly :class:`.Connection` objects. Operations which
+ :class:`_schema.Table` objects and :class:`_orm.Mapper` objects.
+ The
+ values of the dictionary are then instances of
+ :class:`_engine.Engine`
+ or less commonly :class:`_engine.Connection` objects.
+ Operations which
proceed relative to a particular mapped class will consult this
dictionary for the closest matching entity in order to determine
- which :class:`.Engine` should be used for a particular SQL
+ which :class:`_engine.Engine` should be used for a particular SQL
operation. The complete heuristics for resolution are
described at :meth:`.Session.get_bind`. Usage looks like::
:param query_cls: Class which should be used to create new Query
objects, as returned by the :meth:`~.Session.query` method.
- Defaults to :class:`.Query`.
+ Defaults to :class:`_query.Query`.
:param twophase: When ``True``, all transactions will be started as
a "two phase" transaction, i.e. using the "two phase" semantics
execution_options=None,
**kw
):
- r"""Return a :class:`.Connection` object corresponding to this
+ r"""Return a :class:`_engine.Connection` object corresponding to this
:class:`.Session` object's transactional state.
If this :class:`.Session` is configured with ``autocommit=False``,
- either the :class:`.Connection` corresponding to the current
+ either the :class:`_engine.Connection` corresponding to the current
transaction is returned, or if no transaction is in progress, a new
- one is begun and the :class:`.Connection` returned (note that no
+ one is begun and the :class:`_engine.Connection`
+ returned (note that no
transactional state is established with the DBAPI until the first
SQL statement is emitted).
Alternatively, if this :class:`.Session` is configured with
- ``autocommit=True``, an ad-hoc :class:`.Connection` is returned
- using :meth:`.Engine.connect` on the underlying
- :class:`.Engine`.
+ ``autocommit=True``, an ad-hoc :class:`_engine.Connection` is returned
+ using :meth:`_engine.Engine.connect` on the underlying
+ :class:`_engine.Engine`.
Ambiguity in multi-bind or unbound :class:`.Session` objects can be
resolved through any of the optional keyword arguments. This
ultimately makes usage of the :meth:`.get_bind` method for resolution.
:param bind:
- Optional :class:`.Engine` to be used as the bind. If
+ Optional :class:`_engine.Engine` to be used as the bind. If
this engine is already involved in an ongoing transaction,
that connection will be used. This argument takes precedence
over ``mapper``, ``clause``.
``clause``.
:param clause:
- A :class:`.ClauseElement` (i.e. :func:`~.sql.expression.select`,
- :func:`~.sql.expression.text`,
+ A :class:`_expression.ClauseElement` (i.e.
+ :func:`_expression.select`,
+ :func:`_expression.text`,
etc.) which will be used to locate a bind, if a bind
cannot otherwise be identified.
- :param close_with_result: Passed to :meth:`.Engine.connect`,
- indicating the :class:`.Connection` should be considered
+ :param close_with_result: Passed to :meth:`_engine.Engine.connect`,
+ indicating the :class:`_engine.Connection` should be considered
"single use", automatically closing when the first result set is
closed. This flag only has an effect if this :class:`.Session` is
configured with ``autocommit=True`` and does not already have a
transaction in progress.
:param execution_options: a dictionary of execution options that will
- be passed to :meth:`.Connection.execution_options`, **when the
+ be passed to :meth:`_engine.Connection.execution_options`, **when the
connection is first procured only**. If the connection is already
present within the :class:`.Session`, a warning is emitted and
the arguments are ignored.
Returns a :class:`.ResultProxy` representing
results of the statement execution, in the same manner as that of an
- :class:`.Engine` or
- :class:`.Connection`.
+ :class:`_engine.Engine` or
+ :class:`_engine.Connection`.
E.g.::
)
:meth:`~.Session.execute` accepts any executable clause construct,
- such as :func:`~.sql.expression.select`,
- :func:`~.sql.expression.insert`,
- :func:`~.sql.expression.update`,
- :func:`~.sql.expression.delete`, and
- :func:`~.sql.expression.text`. Plain SQL strings can be passed
+ such as :func:`_expression.select`,
+ :func:`_expression.insert`,
+ :func:`_expression.update`,
+ :func:`_expression.delete`, and
+ :func:`_expression.text`. Plain SQL strings can be passed
as well, which in the case of :meth:`.Session.execute` only
will be interpreted the same as if it were passed via a
- :func:`~.expression.text` construct. That is, the following usage::
+ :func:`_expression.text` construct. That is, the following usage::
result = session.execute(
"SELECT * FROM user WHERE id=:param",
The second positional argument to :meth:`.Session.execute` is an
optional parameter set. Similar to that of
- :meth:`.Connection.execute`, whether this is passed as a single
+ :meth:`_engine.Connection.execute`, whether this is passed as a single
dictionary, or a sequence of dictionaries, determines whether the DBAPI
cursor's ``execute()`` or ``executemany()`` is used to execute the
statement. An INSERT construct may be invoked for a single row::
])
The statement is executed within the current transactional context of
- this :class:`.Session`. The :class:`.Connection` which is used
+ this :class:`.Session`. The :class:`_engine.Connection`
+ which is used
to execute the statement can also be acquired directly by
calling the :meth:`.Session.connection` method. Both methods use
a rule-based resolution scheme in order to determine the
- :class:`.Connection`, which in the average case is derived directly
+ :class:`_engine.Connection`,
+ which in the average case is derived directly
from the "bind" of the :class:`.Session` itself, and in other cases
can be based on the :func:`.mapper`
- and :class:`.Table` objects passed to the method; see the
+ and :class:`_schema.Table` objects passed to the method; see the
documentation for :meth:`.Session.get_bind` for a full description of
this scheme.
method is returned with the "close_with_result" flag set to true;
the significance of this flag is that if this :class:`.Session` is
autocommitting and does not have a transaction-dedicated
- :class:`.Connection` available, a temporary :class:`.Connection` is
+ :class:`_engine.Connection` available, a temporary
+ :class:`_engine.Connection` is
established for the statement execution, which is closed (meaning,
returned to the connection pool) when the :class:`.ResultProxy` has
consumed all available data. This applies *only* when the
:param clause:
An executable statement (i.e. an :class:`.Executable` expression
- such as :func:`.expression.select`) or string SQL statement
+ such as :func:`_expression.select`) or string SQL statement
to be executed.
:param params:
for more details.
:param bind:
- Optional :class:`.Engine` to be used as the bind. If
+ Optional :class:`_engine.Engine` to be used as the bind. If
this engine is already involved in an ongoing transaction,
that connection will be used. This argument takes
precedence over ``mapper`` and ``clause`` when locating
:ref:`connections_toplevel` - Further information on direct
statement execution.
- :meth:`.Connection.execute` - core level statement execution
+ :meth:`_engine.Connection.execute`
+ - core level statement execution
method, which is :meth:`.Session.execute` ultimately uses
in order to execute the statement.
"""Close this Session, using connection invalidation.
This is a variant of :meth:`.Session.close` that will additionally
- ensure that the :meth:`.Connection.invalidate` method will be called
- on all :class:`.Connection` objects. This can be called when
+ ensure that the :meth:`_engine.Connection.invalidate`
+ method will be called
+ on all :class:`_engine.Connection` objects. This can be called when
the database is known to be in a state where the connections are
no longer safe to be used.
)
def bind_mapper(self, mapper, bind):
- """Associate a :class:`.Mapper` or arbitrary Python class with a
- "bind", e.g. an :class:`.Engine` or :class:`.Connection`.
+ """Associate a :class:`_orm.Mapper` or arbitrary Python class with a
+ "bind", e.g. an :class:`_engine.Engine` or :class:`_engine.Connection`
+ .
The given entity is added to a lookup used by the
:meth:`.Session.get_bind` method.
- :param mapper: a :class:`.Mapper` object, or an instance of a mapped
+ :param mapper: a :class:`_orm.Mapper` object,
+ or an instance of a mapped
class, or any Python class that is the base of a set of mapped
classes.
- :param bind: an :class:`.Engine` or :class:`.Connection` object.
+ :param bind: an :class:`_engine.Engine` or :class:`_engine.Connection`
+ object.
.. seealso::
self._add_bind(mapper, bind)
def bind_table(self, table, bind):
- """Associate a :class:`.Table` with a "bind", e.g. an :class:`.Engine`
- or :class:`.Connection`.
+ """Associate a :class:`_schema.Table` with a "bind", e.g. an
+ :class:`_engine.Engine`
+ or :class:`_engine.Connection`.
- The given :class:`.Table` is added to a lookup used by the
+ The given :class:`_schema.Table` is added to a lookup used by the
:meth:`.Session.get_bind` method.
- :param table: a :class:`.Table` object, which is typically the target
+ :param table: a :class:`_schema.Table` object,
+ which is typically the target
of an ORM mapping, or is present within a selectable that is
mapped.
- :param bind: an :class:`.Engine` or :class:`.Connection` object.
+ :param bind: an :class:`_engine.Engine` or :class:`_engine.Connection`
+ object.
.. seealso::
def get_bind(self, mapper=None, clause=None):
"""Return a "bind" to which this :class:`.Session` is bound.
- The "bind" is usually an instance of :class:`.Engine`,
+ The "bind" is usually an instance of :class:`_engine.Engine`,
except in the case where the :class:`.Session` has been
- explicitly bound directly to a :class:`.Connection`.
+ explicitly bound directly to a :class:`_engine.Connection`.
For a multiply-bound or unbound :class:`.Session`, the
``mapper`` or ``clause`` arguments are used to determine the
present in the ``__mro__`` of the mapped class, from more specific
superclasses to more general.
2. if clause given and session.binds is present,
- locate a bind based on :class:`.Table` objects
+ locate a bind based on :class:`_schema.Table` objects
found in the given clause present in session.binds.
3. if session.bind is present, return that.
4. if clause given, attempt to return a bind
- linked to the :class:`.MetaData` ultimately
+ linked to the :class:`_schema.MetaData` ultimately
associated with the clause.
5. if mapper given, attempt to return a bind
- linked to the :class:`.MetaData` ultimately
- associated with the :class:`.Table` or other
+ linked to the :class:`_schema.MetaData` ultimately
+ associated with the :class:`_schema.Table` or other
selectable to which the mapper is mapped.
6. No bind can be found, :exc:`~sqlalchemy.exc.UnboundExecutionError`
is raised.
:param mapper:
Optional :func:`.mapper` mapped class or instance of
- :class:`.Mapper`. The bind can be derived from a :class:`.Mapper`
+ :class:`_orm.Mapper`. The bind can be derived from a
+ :class:`_orm.Mapper`
first by consulting the "binds" map associated with this
- :class:`.Session`, and secondly by consulting the :class:`.MetaData`
- associated with the :class:`.Table` to which the :class:`.Mapper`
+ :class:`.Session`, and secondly by consulting the
+ :class:`_schema.MetaData`
+ associated with the :class:`_schema.Table` to which the
+ :class:`_orm.Mapper`
is mapped for a bind.
:param clause:
- A :class:`.ClauseElement` (i.e. :func:`~.sql.expression.select`,
- :func:`~.sql.expression.text`,
+ A :class:`_expression.ClauseElement` (i.e.
+ :func:`_expression.select`,
+ :func:`_expression.text`,
etc.). If the ``mapper`` argument is not present or could not
produce a bind, the given expression construct will be searched
- for a bound element, typically a :class:`.Table` associated with
- bound :class:`.MetaData`.
+ for a bound element, typically a :class:`_schema.Table`
+ associated with
+ bound :class:`_schema.MetaData`.
.. seealso::
)
def query(self, *entities, **kwargs):
- """Return a new :class:`.Query` object corresponding to this
+ """Return a new :class:`_query.Query` object corresponding to this
:class:`.Session`."""
return self._query_cls(entities, self, **kwargs)
PASSIVE_NO_RESULT. In all other cases the instance is returned.
.. versionchanged:: 1.4.0 - the :meth:`.Session._identity_lookup`
- method was moved from :class:`.Query` to
+ method was moved from :class:`_query.Query` to
:class:`.Session`, to avoid having to instantiate the
- :class:`.Query` object.
+ :class:`_query.Query` object.
"""
:param with_for_update: optional boolean ``True`` indicating FOR UPDATE
should be used, or may be a dictionary containing flags to
indicate a more specific set of FOR UPDATE flags for the SELECT;
- flags should match the parameters of :meth:`.Query.with_for_update`.
+ flags should match the parameters of
+ :meth:`_query.Query.with_for_update`.
Supersedes the :paramref:`.Session.refresh.lockmode` parameter.
.. versionadded:: 1.2
:meth:`.enable_relationship_loading` exists to serve special
use cases and is not recommended for general use.
- Accesses of attributes mapped with :func:`.relationship`
+ Accesses of attributes mapped with :func:`_orm.relationship`
will attempt to load a value from the database using this
:class:`.Session` as the source of connectivity. The values
will be loaded based on foreign key and primary key values
is what was already loaded from a foreign-key-holding value.
The :meth:`.Session.enable_relationship_loading` method is
- similar to the ``load_on_pending`` flag on :func:`.relationship`.
+ similar to the ``load_on_pending`` flag on :func:`_orm.relationship`.
Unlike that flag, :meth:`.Session.enable_relationship_loading` allows
an object to remain transient while still being able to load
related items.
.. seealso::
- ``load_on_pending`` at :func:`.relationship` - this flag
+ ``load_on_pending`` at :func:`_orm.relationship` - this flag
allows per-relationship loading of many-to-ones on items that
are pending.
large numbers of simple rows.
The values within the dictionaries as given are typically passed
- without modification into Core :meth:`.Insert` constructs, after
+ without modification into Core :meth:`_expression.Insert` constructs,
+ after
organizing the values within them across the tables to which
the given mapper is mapped.
**before using this method, and fully test and confirm the
functionality of all code developed using these systems.**
- :param mapper: a mapped class, or the actual :class:`.Mapper` object,
+ :param mapper: a mapped class, or the actual :class:`_orm.Mapper`
+ object,
representing the single kind of object represented within the mapping
list.
**before using this method, and fully test and confirm the
functionality of all code developed using these systems.**
- :param mapper: a mapped class, or the actual :class:`.Mapper` object,
+ :param mapper: a mapped class, or the actual :class:`_orm.Mapper`
+ object,
representing the single kind of object represented within the mapping
list.
:class:`.Session` has actually begun to use DBAPI resources is to
implement a listener using the :meth:`.SessionEvents.after_begin`
method, which will deliver both the :class:`.Session` as well as the
- target :class:`.Connection` to a user-defined event listener.
+ target :class:`_engine.Connection` to a user-defined event listener.
The "partial rollback" state refers to when an "inner" transaction,
typically used during a flush, encounters an error and emits a
The class also includes a method :meth:`.configure`, which can
be used to specify additional keyword arguments to the factory, which
will take effect for subsequent :class:`.Session` objects generated.
- This is usually used to associate one or more :class:`.Engine` objects
+ This is usually used to associate one or more :class:`_engine.Engine`
+ objects
with an existing :class:`.sessionmaker` factory before it is first
used::
accepted by :class:`.Session` directly. See the
:meth:`.Session.__init__` docstring for more details on parameters.
- :param bind: a :class:`.Engine` or other :class:`.Connectable` with
+ :param bind: a :class:`_engine.Engine` or other :class:`.Connectable`
+ with
which newly created :class:`.Session` objects will be associated.
:param class\_: class to use in order to create new :class:`.Session`
objects. Defaults to :class:`.Session`.
status within a particular :class:`.Session` and details
about data on individual attributes. The public API
in order to acquire a :class:`.InstanceState` object
- is to use the :func:`.inspect` system::
+ is to use the :func:`_sa.inspect` system::
>>> from sqlalchemy import inspect
>>> insp = inspect(some_mapped_object)
"""Return the mapped identity of the mapped object.
This is the primary key identity as persisted by the ORM
which can always be passed directly to
- :meth:`.Query.get`.
+ :meth:`_query.Query.get`.
Returns ``None`` if the object has no primary key identity.
@util.memoized_property
def mapper(self):
- """Return the :class:`.Mapper` used for this mapped object."""
+ """Return the :class:`_orm.Mapper` used for this mapped object."""
return self.manager.mapper
@property
The attribute history system tracks changes on a **per flush
basis**. Each time the :class:`.Session` is flushed, the history
of each attribute is reset to empty. The :class:`.Session` by
- default autoflushes each time a :class:`.Query` is invoked. For
+ default autoflushes each time a :class:`_query.Query` is invoked.
+ For
options on how to control this, see :ref:`session_flushing`.
The attribute history system tracks changes on a **per flush
basis**. Each time the :class:`.Session` is flushed, the history
of each attribute is reset to empty. The :class:`.Session` by
- default autoflushes each time a :class:`.Query` is invoked. For
+ default autoflushes each time a :class:`_query.Query` is invoked.
+ For
options on how to control this, see :ref:`session_flushing`.
.. seealso::
return q
class _SubqCollections(object):
- """Given a :class:`.Query` used to emit the "subquery load",
+ """Given a :class:`_query.Query` used to emit the "subquery load",
provide a load interface that executes the query at the
first moment a value is needed.
class Load(HasCacheKey, Generative, MapperOption):
"""Represents loader options which modify the state of a
- :class:`.Query` in order to affect how various mapped attributes are
+ :class:`_query.Query` in order to affect how various mapped attributes are
loaded.
- The :class:`.Load` object is in most cases used implicitly behind the
- scenes when one makes use of a query option like :func:`.joinedload`,
- :func:`.defer`, or similar. However, the :class:`.Load` object
+ The :class:`_orm.Load` object is in most cases used implicitly behind the
+ scenes when one makes use of a query option like :func:`_orm.joinedload`,
+ :func:`.defer`, or similar. However, the :class:`_orm.Load` object
can also be used directly, and in some cases can be useful.
- To use :class:`.Load` directly, instantiate it with the target mapped
+ To use :class:`_orm.Load` directly, instantiate it with the target mapped
class as the argument. This style of usage is
- useful when dealing with a :class:`.Query` that has multiple entities::
+ useful when dealing with a :class:`_query.Query`
+ that has multiple entities::
myopt = Load(MyClass).joinedload("widgets")
- The above ``myopt`` can now be used with :meth:`.Query.options`, where it
+ The above ``myopt`` can now be used with :meth:`_query.Query.options`,
+ where it
will only take effect for the ``MyClass`` entity::
session.query(MyClass, MyOtherClass).options(myopt)
- One case where :class:`.Load` is useful as public API is when specifying
+ One case where :class:`_orm.Load`
+ is useful as public API is when specifying
"wildcard" options that only take effect for a certain class::
session.query(Order).options(Load(Order).lazyload('*'))
@_generative
def options(self, *opts):
- r"""Apply a series of options as sub-options to this :class:`.Load`
+ r"""Apply a series of options as sub-options to this
+ :class:`_orm.Load`
object.
E.g.::
)
:param \*opts: A series of loader option objects (ultimately
- :class:`.Load` objects) which should be applied to the path
- specified by this :class:`.Load` object.
+ :class:`_orm.Load` objects) which should be applied to the path
+ specified by this :class:`_orm.Load` object.
.. versionadded:: 1.3.6
class _UnboundLoad(Load):
"""Represent a loader option that isn't tied to a root entity.
- The loader option will produce an entity-linked :class:`.Load`
- object when it is passed :meth:`.Query.options`.
+ The loader option will produce an entity-linked :class:`_orm.Load`
+ object when it is passed :meth:`_query.Query.options`.
This provides compatibility with the traditional system
of freestanding options, e.g. ``joinedload('x.y.z')``.
def _add_unbound_fn(self, fn):
self._unbound_fn = fn
fn_doc = self.fn.__doc__
- self.fn.__doc__ = """Produce a new :class:`.Load` object with the
+ self.fn.__doc__ = """Produce a new :class:`_orm.Load` object with the
:func:`_orm.%(name)s` option applied.
See :func:`_orm.%(name)s` for usage examples.
r"""Indicate that the given attribute should be eagerly loaded from
columns stated manually in the query.
- This function is part of the :class:`.Load` interface and supports
+ This function is part of the :class:`_orm.Load` interface and supports
both method-chained and standalone operation.
The option is used in conjunction with an explicit join that loads
of column-based attribute names should be loaded; all others will be
deferred.
- This function is part of the :class:`.Load` interface and supports
+ This function is part of the :class:`_orm.Load` interface and supports
both method-chained and standalone operation.
Example - given a class ``User``, load only the ``name`` and ``fullname``
subqueryload("addresses").load_only("email_address")
)
- For a :class:`.Query` that has multiple entities, the lead entity can be
- specifically referred to using the :class:`.Load` constructor::
+ For a :class:`_query.Query` that has multiple entities,
+ the lead entity can be
+ specifically referred to using the :class:`_orm.Load` constructor::
session.query(User, Address).join(User.addresses).options(
Load(User).load_only("name", "fullname"),
"""Indicate that the given attribute should be loaded using joined
eager loading.
- This function is part of the :class:`.Load` interface and supports
+ This function is part of the :class:`_orm.Load` interface and supports
both method-chained and standalone operation.
examples::
.. note:: The "unnested" flag does **not** affect the JOIN rendered
from a many-to-many association table, e.g. a table configured
- as :paramref:`.relationship.secondary`, to the target table; for
+ as :paramref:`_orm.relationship.secondary`, to the target table; for
correctness of results, these joins are always INNER and are
therefore right-nested if linked to an OUTER join.
.. note::
- The joins produced by :func:`.orm.joinedload` are **anonymously
+ The joins produced by :func:`_orm.joinedload` are **anonymously
aliased**. The criteria by which the join proceeds cannot be
- modified, nor can the :class:`.Query` refer to these joins in any way,
+ modified, nor can the :class:`_query.Query`
+ refer to these joins in any way,
including ordering. See :ref:`zen_of_eager_loading` for further
detail.
To produce a specific SQL JOIN which is explicitly available, use
- :meth:`.Query.join`. To combine explicit JOINs with eager loading
- of collections, use :func:`.orm.contains_eager`; see
+ :meth:`_query.Query.join`.
+ To combine explicit JOINs with eager loading
+ of collections, use :func:`_orm.contains_eager`; see
:ref:`contains_eager`.
.. seealso::
"""Indicate that the given attribute should be loaded using
subquery eager loading.
- This function is part of the :class:`.Load` interface and supports
+ This function is part of the :class:`_orm.Load` interface and supports
both method-chained and standalone operation.
examples::
"""Indicate that the given attribute should be loaded using
SELECT IN eager loading.
- This function is part of the :class:`.Load` interface and supports
+ This function is part of the :class:`_orm.Load` interface and supports
both method-chained and standalone operation.
examples::
"""Indicate that the given attribute should be loaded using "lazy"
loading.
- This function is part of the :class:`.Load` interface and supports
+ This function is part of the :class:`_orm.Load` interface and supports
both method-chained and standalone operation.
.. seealso::
by the :func:`.selectinload` option, which performs the same task
more efficiently by emitting a SELECT for all loaded objects.
- This function is part of the :class:`.Load` interface and supports
+ This function is part of the :class:`_orm.Load` interface and supports
both method-chained and standalone operation.
.. seealso::
def noload(loadopt, attr):
"""Indicate that the given relationship attribute should remain unloaded.
- This function is part of the :class:`.Load` interface and supports
+ This function is part of the :class:`_orm.Load` interface and supports
both method-chained and standalone operation.
- :func:`.orm.noload` applies to :func:`.relationship` attributes; for
- column-based attributes, see :func:`.orm.defer`.
+ :func:`_orm.noload` applies to :func:`_orm.relationship` attributes; for
+ column-based attributes, see :func:`_orm.defer`.
.. seealso::
def raiseload(loadopt, attr, sql_only=False):
"""Indicate that the given attribute should raise an error if accessed.
- A relationship attribute configured with :func:`.orm.raiseload` will
+ A relationship attribute configured with :func:`_orm.raiseload` will
raise an :exc:`~sqlalchemy.exc.InvalidRequestError` upon access. The
typical way this is useful is when an application is attempting to ensure
that all relationship attributes that are accessed in a particular context
to read through SQL logs to ensure lazy loads aren't occurring, this
strategy will cause them to raise immediately.
- :func:`.orm.raiseload` applies to :func:`.relationship` attributes only.
+ :func:`_orm.raiseload` applies to :func:`_orm.relationship`
+ attributes only.
In order to apply raise-on-SQL behavior to a column-based attribute,
use the :paramref:`.orm.defer.raiseload` parameter on the :func:`.defer`
loader option.
related value should just be None due to missing keys. When False, the
strategy will raise for all varieties of relationship loading.
- This function is part of the :class:`.Load` interface and supports
+ This function is part of the :class:`_orm.Load` interface and supports
both method-chained and standalone operation.
.. seealso::
- :meth:`.Load.options` - allows for complex hierarchical
+ :meth:`_orm.Load.options` - allows for complex hierarchical
loader option structures with less verbosity than with individual
:func:`.defaultload` directives.
r"""Indicate that the given column-oriented attribute should be deferred,
e.g. not loaded until accessed.
- This function is part of the :class:`.Load` interface and supports
+ This function is part of the :class:`_orm.Load` interface and supports
both method-chained and standalone operation.
e.g.::
To specify a deferred load of an attribute on a related class,
the path can be specified one token at a time, specifying the loading
style for each link along the chain. To leave the loading style
- for a link unchanged, use :func:`.orm.defaultload`::
+ for a link unchanged, use :func:`_orm.defaultload`::
session.query(MyClass).options(defaultload("someattr").defer("some_column"))
- A :class:`.Load` object that is present on a certain path can have
- :meth:`.Load.defer` called multiple times, each will operate on the same
+ A :class:`_orm.Load` object that is present on a certain path can have
+ :meth:`_orm.Load.defer` called multiple times,
+ each will operate on the same
parent entity::
of specifying a path as a series of attributes, which is now superseded
by the method-chained style.
- .. deprecated:: 0.9 The \*addl_attrs on :func:`.orm.defer` is
+ .. deprecated:: 0.9 The \*addl_attrs on :func:`_orm.defer` is
deprecated and will be removed in a future release. Please
use method chaining in conjunction with defaultload() to
indicate a path.
:ref:`deferred`
- :func:`.orm.undefer`
+ :func:`_orm.undefer`
"""
strategy = {"deferred": True, "instrument": True}
The column being undeferred is typically set up on the mapping as a
:func:`.deferred` attribute.
- This function is part of the :class:`.Load` interface and supports
+ This function is part of the :class:`_orm.Load` interface and supports
both method-chained and standalone operation.
Examples::
of specifying a path as a series of attributes, which is now superseded
by the method-chained style.
- .. deprecated:: 0.9 The \*addl_attrs on :func:`.orm.undefer` is
+ .. deprecated:: 0.9 The \*addl_attrs on :func:`_orm.undefer` is
deprecated and will be removed in a future release. Please
use method chaining in conjunction with defaultload() to
indicate a path.
:ref:`deferred`
- :func:`.orm.defer`
+ :func:`_orm.defer`
- :func:`.orm.undefer_group`
+ :func:`_orm.undefer_group`
"""
return loadopt.set_column_strategy(
To undefer a group of attributes on a related entity, the path can be
spelled out using relationship loader options, such as
- :func:`.orm.defaultload`::
+ :func:`_orm.defaultload`::
session.query(MyClass).options(
defaultload("someattr").undefer_group("large_attrs"))
- .. versionchanged:: 0.9.0 :func:`.orm.undefer_group` is now specific to a
+ .. versionchanged:: 0.9.0 :func:`_orm.undefer_group` is now specific to a
particular entity load path.
.. seealso::
:ref:`deferred`
- :func:`.orm.defer`
+ :func:`_orm.defer`
- :func:`.orm.undefer`
+ :func:`_orm.undefer`
"""
return loadopt.set_column_strategy(
def with_expression(loadopt, key, expression):
r"""Apply an ad-hoc SQL expression to a "deferred expression" attribute.
- This option is used in conjunction with the :func:`.orm.query_expression`
+ This option is used in conjunction with the :func:`_orm.query_expression`
mapper-level construct that indicates an attribute which should be the
target of an ad-hoc SQL expression.
this is used.
:param table_map: mapping of polymorphic identities to
- :class:`.Table` objects.
+ :class:`_schema.Table` objects.
:param typecolname: string name of a "discriminator" column, which will be
derived from the query, producing the polymorphic identity for
each row. If ``None``, no polymorphic discriminator is generated.
(<class '__main__.MyClass'>, (1, 2), None)
In this form, the given instance is ultimately run though
- :meth:`.Mapper.identity_key_from_instance`, which will have the
+ :meth:`_orm.Mapper.identity_key_from_instance`, which will have the
effect of performing a database check for the corresponding row
if the object is expired.
:class:`.AliasedClass` is also capable of mapping an existing mapped
class to an entirely new selectable, provided this selectable is column-
compatible with the existing mapped selectable, and it can also be
- configured in a mapping as the target of a :func:`.relationship`.
+ configured in a mapping as the target of a :func:`_orm.relationship`.
See the links below for examples.
The :class:`.AliasedClass` object is constructed typically using the
- :func:`.orm.aliased` function. It also is produced with additional
- configuration when using the :func:`.orm.with_polymorphic` function.
+ :func:`_orm.aliased` function. It also is produced with additional
+ configuration when using the :func:`_orm.with_polymorphic` function.
The resulting object is an instance of :class:`.AliasedClass`.
This object implements an attribute scheme which produces the
including hybrid attributes (see :ref:`hybrids_toplevel`).
The :class:`.AliasedClass` can be inspected for its underlying
- :class:`.Mapper`, aliased selectable, and other information
- using :func:`.inspect`::
+ :class:`_orm.Mapper`, aliased selectable, and other information
+ using :func:`_sa.inspect`::
from sqlalchemy import inspect
my_alias = aliased(MyClass)
The :class:`.AliasedInsp` object is returned
given an :class:`.AliasedClass` using the
- :func:`.inspect` function::
+ :func:`_sa.inspect` function::
from sqlalchemy import inspect
from sqlalchemy.orm import aliased
include:
* ``entity`` - the :class:`.AliasedClass` represented.
- * ``mapper`` - the :class:`.Mapper` mapping the underlying class.
- * ``selectable`` - the :class:`.Alias` construct which ultimately
- represents an aliased :class:`.Table` or :class:`.Select`
+ * ``mapper`` - the :class:`_orm.Mapper` mapping the underlying class.
+ * ``selectable`` - the :class:`_expression.Alias`
+ construct which ultimately
+ represents an aliased :class:`_schema.Table` or
+ :class:`_expression.Select`
construct.
* ``name`` - the name of the alias. Also is used as the attribute
- name when returned in a result tuple from :class:`.Query`.
- * ``with_polymorphic_mappers`` - collection of :class:`.Mapper` objects
+ name when returned in a result tuple from :class:`_query.Query`.
+ * ``with_polymorphic_mappers`` - collection of :class:`_orm.Mapper`
+ objects
indicating all those mappers expressed in the select construct
for the :class:`.AliasedClass`.
* ``polymorphic_on`` - an alternate column or SQL expression which
The :func:`.aliased` function is used to create an ad-hoc mapping of a
mapped class to a new selectable. By default, a selectable is generated
- from the normally mapped selectable (typically a :class:`.Table`) using the
- :meth:`.FromClause.alias` method. However, :func:`.aliased` can also be
- used to link the class to a new :func:`~.sql.expression.select` statement.
+ from the normally mapped selectable (typically a :class:`_schema.Table`
+ ) using the
+ :meth:`_expression.FromClause.alias` method. However, :func:`.aliased`
+ can also be
+ used to link the class to a new :func:`_expression.select` statement.
Also, the :func:`.with_polymorphic` function is a variant of
:func:`.aliased` that is intended to specify a so-called "polymorphic
selectable", that corresponds to the union of several joined-inheritance
subclasses at once.
For convenience, the :func:`.aliased` function also accepts plain
- :class:`.FromClause` constructs, such as a :class:`.Table` or
- :func:`~.sql.expression.select` construct. In those cases, the
- :meth:`.FromClause.alias` method is called on the object and the new
- :class:`.Alias` object returned. The returned :class:`.Alias` is not
+ :class:`_expression.FromClause` constructs, such as a
+ :class:`_schema.Table` or
+ :func:`_expression.select` construct. In those cases, the
+ :meth:`_expression.FromClause.alias`
+ method is called on the object and the new
+ :class:`_expression.Alias` object returned. The returned
+ :class:`_expression.Alias` is not
ORM-mapped in this case.
:param element: element to be aliased. Is normally a mapped class,
- but for convenience can also be a :class:`.FromClause` element.
+ but for convenience can also be a :class:`_expression.FromClause` element
+ .
:param alias: Optional selectable unit to map the element to. This should
- normally be a :class:`.Alias` object corresponding to the :class:`.Table`
- to which the class is mapped, or to a :func:`~.sql.expression.select`
+ normally be a :class:`_expression.Alias` object corresponding to the
+ :class:`_schema.Table`
+ to which the class is mapped, or to a :func:`_expression.select`
construct that is compatible with the mapping. By default, a simple
anonymous alias of the mapped table is generated.
:param name: optional string name to use for the alias, if not specified
by the ``alias`` parameter. The name, among other things, forms the
attribute name that will be accessible via tuples returned by a
- :class:`.Query` object.
+ :class:`_query.Query` object.
:param flat: Boolean, will be passed through to the
- :meth:`.FromClause.alias` call so that aliases of :class:`.Join` objects
+ :meth:`_expression.FromClause.alias` call so that aliases of
+ :class:`_expression.Join` objects
don't include an enclosing SELECT. This can lead to more efficient
queries in many circumstances. A JOIN against a nested JOIN will be
rewritten as a JOIN against an aliased SELECT subquery on backends that
.. versionadded:: 0.9.0
- .. seealso:: :meth:`.Join.alias`
+ .. seealso:: :meth:`_expression.Join.alias`
:param adapt_on_names: if True, more liberal "matching" will be used when
mapping the mapped columns of the ORM entity to those of the
.. seealso::
:ref:`with_polymorphic` - full discussion of
- :func:`.orm.with_polymorphic`.
+ :func:`_orm.with_polymorphic`.
:param base: Base class to be aliased.
support parenthesized joins, such as SQLite and older
versions of MySQL. However if the
:paramref:`.with_polymorphic.selectable` parameter is in use
- with an existing :class:`.Alias` construct, then you should not
+ with an existing :class:`_expression.Alias` construct,
+ then you should not
set this flag.
:param flat: Boolean, will be passed through to the
- :meth:`.FromClause.alias` call so that aliases of :class:`.Join`
+ :meth:`_expression.FromClause.alias` call so that aliases of
+ :class:`_expression.Join`
objects don't include an enclosing SELECT. This can lead to more
efficient queries in many circumstances. A JOIN against a nested JOIN
will be rewritten as a JOIN against an aliased SELECT subquery on
.. versionadded:: 0.9.0
- .. seealso:: :meth:`.Join.alias`
+ .. seealso:: :meth:`_expression.Join.alias`
:param selectable: a table or subquery that will
be used in place of the generated FROM clause. This argument is
"""Remove annotations that link a column to a particular mapping.
Note this doesn't affect "remote" and "foreign" annotations
- passed by the :func:`.orm.foreign` and :func:`.orm.remote`
+ passed by the :func:`_orm.foreign` and :func:`_orm.remote`
annotators.
"""
):
r"""Produce an inner join between left and right clauses.
- :func:`.orm.join` is an extension to the core join interface
- provided by :func:`.sql.expression.join()`, where the
+ :func:`_orm.join` is an extension to the core join interface
+ provided by :func:`_expression.join()`, where the
left and right selectables may be not only core selectable
- objects such as :class:`.Table`, but also mapped classes or
+ objects such as :class:`_schema.Table`, but also mapped classes or
:class:`.AliasedClass` instances. The "on" clause can
be a SQL expression, or an attribute or string name
- referencing a configured :func:`.relationship`.
+ referencing a configured :func:`_orm.relationship`.
- :func:`.orm.join` is not commonly needed in modern usage,
+ :func:`_orm.join` is not commonly needed in modern usage,
as its functionality is encapsulated within that of the
- :meth:`.Query.join` method, which features a
- significant amount of automation beyond :func:`.orm.join`
- by itself. Explicit usage of :func:`.orm.join`
- with :class:`.Query` involves usage of the
- :meth:`.Query.select_from` method, as in::
+ :meth:`_query.Query.join` method, which features a
+ significant amount of automation beyond :func:`_orm.join`
+ by itself. Explicit usage of :func:`_orm.join`
+ with :class:`_query.Query` involves usage of the
+ :meth:`_query.Query.select_from` method, as in::
from sqlalchemy.orm import join
session.query(User).\
join(User.addresses).\
filter(Address.email_address=='foo@bar.com')
- See :meth:`.Query.join` for information on modern usage
+ See :meth:`_query.Query.join` for information on modern usage
of ORM level joins.
.. deprecated:: 0.8
def outerjoin(left, right, onclause=None, full=False, join_to_left=None):
"""Produce a left outer join between left and right clauses.
- This is the "outer join" version of the :func:`.orm.join` function,
+ This is the "outer join" version of the :func:`_orm.join` function,
featuring the same behavior except that an OUTER JOIN is generated.
See that function's documentation for other usage details.
def with_parent(instance, prop, from_entity=None):
"""Create filtering criterion that relates this query's primary entity
- to the given related instance, using established :func:`.relationship()`
+ to the given related instance, using established
+ :func:`_orm.relationship()`
configuration.
The SQL rendered is the same as that rendered when a lazy loader
in the rendered statement.
:param instance:
- An instance which has some :func:`.relationship`.
+ An instance which has some :func:`_orm.relationship`.
:param property:
String property name, or class-bound attribute, which indicates
:param from_entity:
Entity in which to consider as the left side. This defaults to the
- "zero" entity of the :class:`.Query` itself.
+ "zero" entity of the :class:`_query.Query` itself.
.. versionadded:: 1.2
"""partial implementation of :class:`.Dialect`
which provides DBAPI connection methods.
- When a :class:`.Pool` is combined with an :class:`.Engine`,
- the :class:`.Engine` replaces this with its own
+ When a :class:`_pool.Pool` is combined with an :class:`_engine.Engine`,
+ the :class:`_engine.Engine` replaces this with its own
:class:`.Dialect`.
"""
which defaults to ``sys.stdout`` for output.. If set to the string
``"debug"``, the logging will include pool checkouts and checkins.
- The :paramref:`.Pool.echo` parameter can also be set from the
+ The :paramref:`_pool.Pool.echo` parameter can also be set from the
:func:`.create_engine` call by using the
:paramref:`.create_engine.echo_pool` parameter.
as it is handled by the engine creation strategy.
.. versionadded:: 1.1 - ``dialect`` is now a public parameter
- to the :class:`.Pool`.
+ to the :class:`_pool.Pool`.
:param pre_ping: if True, the pool will emit a "ping" (typically
"SELECT 1", but is dialect-specific) on the connection
connection.invalidate(exception)
def recreate(self):
- """Return a new :class:`.Pool`, of the same class as this one
+ """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` and create a new one in
+ to close out an entire :class:`_pool.Pool` and create a new one in
its place.
"""
return _ConnectionFairy._checkout(self)
def _return_conn(self, record):
- """Given a _ConnectionRecord, return it to the :class:`.Pool`.
+ """Given a _ConnectionRecord, return it to the :class:`_pool.Pool`.
This method is called when an instrumented DBAPI connection
has its ``close()`` method called.
class _ConnectionRecord(object):
"""Internal object which maintains an individual DBAPI connection
- referenced by a :class:`.Pool`.
+ referenced by a :class:`_pool.Pool`.
The :class:`._ConnectionRecord` object always exists for any particular
DBAPI connection whether or not that DBAPI connection has been
method is called, the DBAPI connection associated with this
:class:`._ConnectionRecord`
will be discarded, but the :class:`._ConnectionRecord` may be used again,
- in which case a new DBAPI connection is produced when the :class:`.Pool`
+ in which case a new DBAPI connection is produced when the
+ :class:`_pool.Pool`
next uses this record.
The :class:`._ConnectionRecord` is delivered along with connection
- pool events, including :meth:`.PoolEvents.connect` and
- :meth:`.PoolEvents.checkout`, however :class:`._ConnectionRecord` still
+ pool events, including :meth:`_events.PoolEvents.connect` and
+ :meth:`_events.PoolEvents.checkout`, however :class:`._ConnectionRecord`
+ still
remains an internal object whose API and internals may change.
.. seealso::
"""The ``.info`` dictionary associated with the DBAPI connection.
This dictionary is shared among the :attr:`._ConnectionFairy.info`
- and :attr:`.Connection.info` accessors.
+ and :attr:`_engine.Connection.info` accessors.
.. note::
This method is called for all connection invalidations, including
when the :meth:`._ConnectionFairy.invalidate` or
- :meth:`.Connection.invalidate` methods are called, as well as when any
+ :meth:`_engine.Connection.invalidate` methods are called,
+ as well as when any
so-called "automatic invalidation" condition occurs.
:param e: an exception object indicating a reason for the invalidation.
"""Proxies a DBAPI connection and provides return-on-dereference
support.
- This is an internal object used by the :class:`.Pool` implementation
+ This is an internal object used by the :class:`_pool.Pool` implementation
to provide context management to a DBAPI connection delivered by
- that :class:`.Pool`.
+ that :class:`_pool.Pool`.
The name "fairy" is inspired by the fact that the
:class:`._ConnectionFairy` object's lifespan is transitory, as it lasts
rather than directly against the dialect-level do_rollback() and
do_commit() methods.
- In practice, a :class:`.Connection` assigns a :class:`.Transaction` object
+ In practice, a :class:`_engine.Connection` assigns a :class:`.Transaction`
+ object
to this variable when one is in scope so that the :class:`.Transaction`
takes the job of committing or rolling back on return if
- :meth:`.Connection.close` is called while the :class:`.Transaction`
+ :meth:`_engine.Connection.close` is called while the :class:`.Transaction`
still exists.
This is essentially an "event handler" of sorts but is simplified as an
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:`._ConnectionFairy`. It is shared
- with the :attr:`._ConnectionRecord.info` and :attr:`.Connection.info`
+ with the :attr:`._ConnectionRecord.info` and
+ :attr:`_engine.Connection.info`
accessors.
The dictionary associated with a particular DBAPI connection is
"""Mark this connection as invalidated.
This method can be called directly, and is also called as a result
- of the :meth:`.Connection.invalidate` method. When invoked,
+ of the :meth:`_engine.Connection.invalidate` method. When invoked,
the DBAPI connection is immediately closed and discarded from
further use by the pool. The invalidation mechanism proceeds
via the :meth:`._ConnectionRecord.invalidate` internal method.
class PoolEvents(event.Events):
- """Available events for :class:`.Pool`.
+ """Available events for :class:`_pool.Pool`.
The methods here define the name of an event as well
as the names of members that are passed to listener
event.listen(Pool, 'checkout', my_on_checkout)
- In addition to accepting the :class:`.Pool` class and
- :class:`.Pool` instances, :class:`.PoolEvents` also accepts
- :class:`.Engine` objects and the :class:`.Engine` class as
+ In addition to accepting the :class:`_pool.Pool` class and
+ :class:`_pool.Pool` instances, :class:`_events.PoolEvents` also accepts
+ :class:`_engine.Engine` objects and the :class:`_engine.Engine` class as
targets, which will be resolved to the ``.pool`` attribute of the
- given engine or the :class:`.Pool` class::
+ given engine or the :class:`_pool.Pool` class::
engine = create_engine("postgresql://scott:tiger@localhost/test")
def connect(self, dbapi_connection, connection_record):
"""Called at the moment a particular DBAPI connection is first
- created for a given :class:`.Pool`.
+ created for a given :class:`_pool.Pool`.
This event allows one to capture the point directly after which
the DBAPI module-level ``.connect()`` method has been used in order
def first_connect(self, dbapi_connection, connection_record):
"""Called exactly once for the first time a DBAPI connection is
- checked out from a particular :class:`.Pool`.
+ checked out from a particular :class:`_pool.Pool`.
- The rationale for :meth:`.PoolEvents.first_connect` is to determine
+ The rationale for :meth:`_events.PoolEvents.first_connect`
+ is to determine
information about a particular series of database connections based
on the settings used for all connections. Since a particular
- :class:`.Pool` refers to a single "creator" function (which in terms
- of a :class:`.Engine` refers to the URL and connection options used),
+ :class:`_pool.Pool`
+ refers to a single "creator" function (which in terms
+ of a :class:`_engine.Engine`
+ refers to the URL and connection options used),
it is typically valid to make observations about a single connection
that can be safely assumed to be valid about all subsequent
connections, such as the database version, the server and client
using the new connection.
.. seealso:: :meth:`.ConnectionEvents.engine_connect` - a similar event
- which occurs upon creation of a new :class:`.Connection`.
+ which occurs upon creation of a new :class:`_engine.Connection`.
"""
pool argument.
- The :meth:`.PoolEvents.reset` event is usually followed by the
- :meth:`.PoolEvents.checkin` event is called, except in those
+ The :meth:`_events.PoolEvents.reset` event is usually followed by the
+ :meth:`_events.PoolEvents.checkin` event is called, except in those
cases where the connection is discarded immediately after reset.
:param dbapi_connection: a DBAPI connection.
class QueuePool(Pool):
- """A :class:`.Pool` that imposes a limit on the number of open connections.
+ """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` objects, unless the SQLite dialect is in use.
+ all :class:`_engine.Engine` objects, unless the SQLite dialect is in use.
"""
Construct a QueuePool.
:param creator: a callable function that returns a DB-API
- connection object, same as that of :paramref:`.Pool.creator`.
+ 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
:ref:`pool_disconnects`
:param \**kw: Other keyword arguments including
- :paramref:`.Pool.recycle`, :paramref:`.Pool.echo`,
- :paramref:`.Pool.reset_on_return` and others are passed to the
- :class:`.Pool` constructor.
+ :paramref:`_pool.Pool.recycle`, :paramref:`_pool.Pool.echo`,
+ :paramref:`_pool.Pool.reset_on_return` and others are passed to the
+ :class:`_pool.Pool` constructor.
"""
Pool.__init__(self, creator, **kw)
for production use.
- Options are the same as those of :class:`.Pool`, as well as:
+ 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 AssertionPool(Pool):
- """A :class:`.Pool` that allows at most one checked out connection at
+ """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
return new
def _deannotate(self, values=None, clone=False):
- """return a copy of this :class:`.ClauseElement` with annotations
+ """return a copy of this :class:`_expression.ClauseElement`
+ with annotations
removed.
:param values: optional tuple of individual values
return Annotated(self, values)
def _deannotate(self, values=None, clone=False):
- """return a copy of this :class:`.ClauseElement` with annotations
+ """return a copy of this :class:`_expression.ClauseElement`
+ with annotations
removed.
:param values: optional tuple of individual values
execution.
Execution options can be set on a per-statement or
- per :class:`.Connection` basis. Additionally, the
- :class:`.Engine` and ORM :class:`~.orm.query.Query` objects provide
+ per :class:`_engine.Connection` basis. Additionally, the
+ :class:`_engine.Engine` and ORM :class:`~.orm.query.Query`
+ objects provide
access to execution options which they in turn configure upon
connections.
Note that only a subset of possible execution options can be applied
to a statement - these include "autocommit" and "stream_results",
but not "isolation_level" or "compiled_cache".
- See :meth:`.Connection.execution_options` for a full list of
+ See :meth:`_engine.Connection.execution_options` for a full list of
possible options.
.. seealso::
- :meth:`.Connection.execution_options`
+ :meth:`_engine.Connection.execution_options`
- :meth:`.Query.execution_options`
+ :meth:`_query.Query.execution_options`
:meth:`.Executable.get_execution_options`
@util.deprecated_20(
":meth:`.Executable.execute`",
alternative="All statement execution in SQLAlchemy 2.0 is performed "
- "by the :meth:`.Connection.execute` method of :class:`.Connection`, "
+ "by the :meth:`_engine.Connection.execute` method of "
+ ":class:`_engine.Connection`, "
"or in the ORM by the :meth:`.Session.execute` method of "
":class:`.Session`.",
)
@util.deprecated_20(
":meth:`.Executable.scalar`",
alternative="All statement execution in SQLAlchemy 2.0 is performed "
- "by the :meth:`.Connection.execute` method of :class:`.Connection`, "
+ "by the :meth:`_engine.Connection.execute` method of "
+ ":class:`_engine.Connection`, "
"or in the ORM by the :meth:`.Session.execute` method of "
":class:`.Session`; the :meth:`.Result.scalar` method can then be "
"used to return a scalar result.",
@property
def bind(self):
- """Returns the :class:`.Engine` or :class:`.Connection` to
+ """Returns the :class:`_engine.Engine` or :class:`_engine.Connection`
+ to
which this :class:`.Executable` is bound, or None if none found.
This is a traversal which checks locally, then
class ColumnCollection(object):
- """Collection of :class:`.ColumnElement` instances, typically for
+ """Collection of :class:`_expression.ColumnElement` instances,
+ typically for
selectables.
- The :class:`.ColumnCollection` has both mapping- and sequence- like
- behaviors. A :class:`.ColumnCollection` usually stores :class:`.Column`
+ 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. The name for which a :class:`.Column` would
- be present is normally that of the :paramref:`.Column.key` parameter,
+ as attribute access style. The name for which a :class:`_schema.Column`
+ would
+ be present is normally that of the :paramref:`_schema.Column.key`
+ parameter,
however depending on the context, it may be stored under a special label
name::
>>> cc[1]
Column('y', Integer(), table=None)
- .. versionadded:: 1.4 :class:`.ColumnCollection` allows integer-based
+ .. versionadded:: 1.4 :class:`_expression.ColumnCollection`
+ allows integer-based
index access to the collection.
Iterating the collection yields the column expressions in order::
[Column('x', Integer(), table=None),
Column('y', Integer(), table=None)]
- The base :class:`.ColumnCollection` object can store duplicates, which can
+ 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**::
True
Or it can also mean the same column multiple times. These cases are
- supported as :class:`.ColumnCollection` is used to represent the columns in
+ 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:`.Table` and
+ 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:`.ColumnCollection` now stores duplicate
+ .. 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
return ImmutableColumnCollection(self)
def corresponding_column(self, column, require_embedded=False):
- """Given a :class:`.ColumnElement`, return the exported
- :class:`.ColumnElement` object from this :class:`.ColumnCollection`
- which corresponds to that original :class:`.ColumnElement` via a common
+ """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:`.ColumnElement` to be matched
+ :param column: the target :class:`_expression.ColumnElement`
+ to be matched
:param require_embedded: only return corresponding columns for
- the given :class:`.ColumnElement`, if the given
- :class:`.ColumnElement` is actually present within a sub-element
- of this :class:`.Selectable`. Normally the column will match if
+ 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:`.Selectable`.
+ columns of this :class:`expression.Selectable`.
.. seealso::
- :meth:`.Selectable.corresponding_column` - invokes this method
+ :meth:`expression.Selectable.corresponding_column`
+ - invokes this method
against the collection returned by
- :attr:`.Selectable.exported_columns`.
+ :attr:`expression.Selectable.exported_columns`.
.. versionchanged:: 1.4 the implementation for ``corresponding_column``
- was moved onto the :class:`.ColumnCollection` itself.
+ was moved onto the :class:`_expression.ColumnCollection` itself.
"""
class DedupeColumnCollection(ColumnCollection):
- """A :class:`.ColumnCollection` that maintains deduplicating behavior.
+ """A :class:`_expression.ColumnCollection`
+ that maintains deduplicating behavior.
- This is useful by schema level objects such as :class:`.Table` and
+ This is useful by schema level objects such as :class:`_schema.Table` and
:class:`.PrimaryKeyConstraint`. The collection includes more
sophisticated mutator methods as well to suit schema objects which
require mutable column collections.
:param dialect: :class:`.Dialect` to compile against.
- :param statement: :class:`.ClauseElement` to be compiled.
+ :param statement: :class:`_expression.ClauseElement` to be compiled.
:param bind: Optional Engine or Connection to compile this
statement against.
class SQLCompiler(Compiled):
"""Default implementation of :class:`.Compiled`.
- Compiles :class:`.ClauseElement` objects into SQL strings.
+ Compiles :class:`_expression.ClauseElement` objects into SQL strings.
"""
"""Optional :class:`.CompileState` object that maintains additional
state used by the compiler.
- Major executable objects such as :class:`~.sql.expression.Insert`,
- :class:`.Update`, :class:`.Delete`, :class:`.Select` will generate this
+ Major executable objects such as :class:`_expression.Insert`,
+ :class:`_expression.Update`, :class:`_expression.Delete`,
+ :class:`_expression.Select` will generate this
state when compiled in order to calculate additional information about the
object. For the top level object that is to be executed, the state can be
stored here where it can also have applicability towards result set
:param dialect: :class:`.Dialect` to be used
- :param statement: :class:`.ClauseElement` to be compiled
+ :param statement: :class:`_expression.ClauseElement` to be compiled
:param column_keys: a list of column names to be compiled into an
INSERT or UPDATE statement.
The :class:`.StrSQLCompiler` is invoked whenever a Core expression
element is directly stringified without calling upon the
- :meth:`.ClauseElement.compile` method. It can render a limited set
+ :meth:`_expression.ClauseElement.compile` method.
+ It can render a limited set
of non-standard SQL constructs to assist in basic stringification,
however for more substantial custom or dialect-specific SQL constructs,
- it will be necessary to make use of :meth:`.ClauseElement.compile`
+ it will be necessary to make use of
+ :meth:`_expression.ClauseElement.compile`
directly.
.. seealso::
"""
Placeholder for the value within a :class:`.BindParameter`
which is required to be present when the statement is passed
-to :meth:`.Connection.execute`.
+to :meth:`_engine.Connection.execute`.
-This symbol is typically used when a :func:`.expression.insert`
-or :func:`.expression.update` statement is compiled without parameter
+This symbol is typically used when a :func:`_expression.insert`
+or :func:`_expression.update` statement is compiled without parameter
values present.
""",
This DDL element.
:target:
- The :class:`.Table` or :class:`.MetaData` object which is the
+ 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:`.Connection` being used for DDL execution
+ The :class:`_engine.Connection` being used for DDL execution
:tables:
Optional keyword argument - a list of Table objects which are to
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:`.Table` or
- :class:`.MetaData` objects as targets. Basic templating support allows
+ 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::
):
"""Create a :class:`.CreateTable` construct.
- :param element: a :class:`.Table` that's the subject
+ :param element: a :class:`_schema.Table` that's the subject
of the CREATE
:param on: See the description for 'on' in :class:`.DDL`.
:param bind: See the description for 'bind' in :class:`.DDL`.
:param include_foreign_key_constraints: optional sequence of
- :class:`.ForeignKeyConstraint` objects that will be included
+ :class:`_schema.ForeignKeyConstraint` objects that will be included
inline within the CREATE construct; if omitted, all foreign key
constraints that do not specify use_alter=True are included.
class CreateColumn(_DDLCompiles):
- """Represent a :class:`.Column` as rendered in a CREATE TABLE statement,
+ """Represent a :class:`_schema.Column`
+ as rendered in a CREATE TABLE statement,
via the :class:`.CreateTable` construct.
This is provided to support custom column DDL within the generation
compiler extension documented in :ref:`sqlalchemy.ext.compiler_toplevel`
to extend :class:`.CreateColumn`.
- Typical integration is to examine the incoming :class:`.Column`
+ Typical integration is to examine the incoming :class:`_schema.Column`
object, and to redirect compilation if a particular flag or condition
is found::
for const in column.constraints)
return text
- The above construct can be applied to a :class:`.Table` as follows::
+ The above construct can be applied to a :class:`_schema.Table`
+ as follows::
from sqlalchemy import Table, Metadata, Column, Integer, String
from sqlalchemy import schema
metadata.create_all(conn)
- Above, the directives we've added to the :attr:`.Column.info` collection
+ Above, the directives we've added to the :attr:`_schema.Column.info`
+ collection
will be detected by our custom compilation scheme::
CREATE TABLE mytable (
columns when producing a ``CREATE TABLE``. This is accomplished by
creating a compilation rule that conditionally returns ``None``.
This is essentially how to produce the same effect as using the
- ``system=True`` argument on :class:`.Column`, which marks a column
+ ``system=True`` argument on :class:`_schema.Column`, which marks a column
as an implicitly-present "system" column.
- For example, suppose we wish to produce a :class:`.Table` which skips
+ For example, suppose we wish to produce a :class:`_schema.Table`
+ which skips
rendering of the PostgreSQL ``xmin`` column against the PostgreSQL
backend, but on other backends does render it, in anticipation of a
triggered rule. A conditional compilation rule could skip this name only
def sort_tables(tables, skip_fn=None, extra_dependencies=None):
- """sort a collection of :class:`.Table` objects based on dependency.
+ """sort a collection of :class:`_schema.Table` objects based on dependency
+ .
- This is a dependency-ordered sort which will emit :class:`.Table`
- objects such that they will follow their dependent :class:`.Table` objects.
+ This is a dependency-ordered sort which will emit :class:`_schema.Table`
+ objects such that they will follow their dependent :class:`_schema.Table`
+ objects.
Tables are dependent on another based on the presence of
- :class:`.ForeignKeyConstraint` objects as well as explicit dependencies
- added by :meth:`.Table.add_is_dependent_on`.
+ :class:`_schema.ForeignKeyConstraint`
+ objects as well as explicit dependencies
+ added by :meth:`_schema.Table.add_is_dependent_on`.
.. warning::
automatic resolution of dependency cycles between tables, which
are usually caused by mutually dependent foreign key constraints.
To resolve these cycles, either the
- :paramref:`.ForeignKeyConstraint.use_alter` parameter may be applied
+ :paramref:`_schema.ForeignKeyConstraint.use_alter`
+ parameter may be applied
to those constraints, or use the
- :func:`.sql.sort_tables_and_constraints` function which will break
+ :func:`_expression.sort_tables_and_constraints`
+ function which will break
out foreign key constraints involved in cycles separately.
- :param tables: a sequence of :class:`.Table` objects.
+ :param tables: a sequence of :class:`_schema.Table` objects.
:param skip_fn: optional callable which will be passed a
- :class:`.ForeignKey` object; if it returns True, this
+ :class:`_schema.ForeignKey` object; if it returns True, this
constraint will not be considered as a dependency. Note this is
**different** from the same parameter in
:func:`.sort_tables_and_constraints`, which is
- instead passed the owning :class:`.ForeignKeyConstraint` object.
+ instead passed the owning :class:`_schema.ForeignKeyConstraint` object.
:param extra_dependencies: a sequence of 2-tuples of tables which will
also be considered as dependent on each other.
:func:`.sort_tables_and_constraints`
- :meth:`.MetaData.sorted_tables` - uses this function to sort
+ :meth:`_schema.MetaData.sorted_tables` - uses this function to sort
"""
def sort_tables_and_constraints(
tables, filter_fn=None, extra_dependencies=None
):
- """sort a collection of :class:`.Table` / :class:`.ForeignKeyConstraint`
+ """sort a collection of :class:`_schema.Table` /
+ :class:`_schema.ForeignKeyConstraint`
objects.
This is a dependency-ordered sort which will emit tuples of
``(Table, [ForeignKeyConstraint, ...])`` such that each
- :class:`.Table` follows its dependent :class:`.Table` objects.
- Remaining :class:`.ForeignKeyConstraint` objects that are separate due to
+ :class:`_schema.Table` follows its dependent :class:`_schema.Table`
+ objects.
+ Remaining :class:`_schema.ForeignKeyConstraint`
+ objects that are separate due to
dependency rules not satisfied by the sort are emitted afterwards
as ``(None, [ForeignKeyConstraint ...])``.
Tables are dependent on another based on the presence of
- :class:`.ForeignKeyConstraint` objects, explicit dependencies
- added by :meth:`.Table.add_is_dependent_on`, as well as dependencies
+ :class:`_schema.ForeignKeyConstraint` objects, explicit dependencies
+ added by :meth:`_schema.Table.add_is_dependent_on`,
+ as well as dependencies
stated here using the :paramref:`~.sort_tables_and_constraints.skip_fn`
and/or :paramref:`~.sort_tables_and_constraints.extra_dependencies`
parameters.
- :param tables: a sequence of :class:`.Table` objects.
+ :param tables: a sequence of :class:`_schema.Table` objects.
:param filter_fn: optional callable which will be passed a
- :class:`.ForeignKeyConstraint` object, and returns a value based on
+ :class:`_schema.ForeignKeyConstraint` object,
+ and returns a value based on
whether this constraint should definitely be included or excluded as
an inline constraint, or neither. If it returns False, the constraint
will definitely be included as a dependency that cannot be subject
# This module is part of SQLAlchemy and is released under
# the MIT License: http://www.opensource.org/licenses/mit-license.php
"""
-Provide :class:`~.sql.expression.Insert`, :class:`.Update` and
-:class:`.Delete`.
+Provide :class:`_expression.Insert`, :class:`_expression.Update` and
+:class:`_expression.Delete`.
"""
from sqlalchemy.types import NullType
def bind(self):
"""Return a 'bind' linked to this :class:`.UpdateBase`
- or a :class:`.Table` associated with it.
+ or a :class:`_schema.Table` associated with it.
"""
return self._bind or self.table.bind
The given collection of column expressions should be derived from
the table that is
- the target of the INSERT, UPDATE, or DELETE. While :class:`.Column`
+ the target of the INSERT, UPDATE, or DELETE. While
+ :class:`_schema.Column`
objects are typical, the elements can also be expressions::
stmt = table.insert().returning(
The text of the hint is rendered in the appropriate
location for the database backend in use, relative
- to the :class:`.Table` that is the subject of this
+ to the :class:`_schema.Table` that is the subject of this
statement, or optionally to that of the given
- :class:`.Table` passed as the ``selectable`` argument.
+ :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
mytable.insert().with_hint("WITH (PAGLOCK)", dialect_name="mssql")
:param text: Text of the hint.
- :param selectable: optional :class:`.Table` that specifies
+ :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
r"""specify a fixed VALUES clause for an INSERT statement, or the SET
clause for an UPDATE.
- Note that the :class:`~.sql.expression.Insert` and :class:`.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:`.Connection.execute`.
+ 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.
onto the existing list of values.
:param \**kwargs: key value pairs representing the string key
- of a :class:`.Column` mapped to the value to be rendered into the
+ of a :class:`_schema.Column`
+ mapped to the value to be rendered into the
VALUES or SET clause::
users.insert().values(name="some name")
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:`~.sql.expression.Insert` or an
- :class:`.Update` construct.
+ based on whether this is an :class:`_expression.Insert` or an
+ :class:`_expression.Update` construct.
- For either an :class:`~.sql.expression.Insert` or :class:`.Update`
+ 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.update().values({"name": "some new name"})
Also for either form but more typically for the
- :class:`~.sql.expression.Insert` construct, a tuple that contains an
+ :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:`~.sql.expression.Insert` construct also supports being
+ 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,
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:`.Connection.execute`
+ 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.
.. versionchanged:: 1.0.0 an INSERT that uses a multiple-VALUES
clause, even a list of length one,
- implies that the :paramref:`.Insert.inline` flag is set to
+ implies that the :paramref:`_expression.Insert.inline`
+ flag is set to
True, indicating that the statement will not attempt to fetch
the "last inserted primary key" or other defaults. The
statement deals with an arbitrary number of rows, so the
The UPDATE construct also supports rendering the SET parameters
in a specific order. For this feature refer to the
- :meth:`.Update.ordered_values` method.
+ :meth:`_expression.Update.ordered_values` method.
.. seealso::
- :meth:`.Update.ordered_values`
+ :meth:`_expression.Update.ordered_values`
.. seealso::
:ref:`inserts_and_updates` - SQL Expression
Language Tutorial
- :func:`~.expression.insert` - produce an ``INSERT`` statement
+ :func:`_expression.insert` - produce an ``INSERT`` statement
- :func:`~.expression.update` - produce an ``UPDATE`` statement
+ :func:`_expression.update` - produce an ``UPDATE`` statement
"""
if self._select_names:
:meth:`.UpdateBase.returning` is not used simultaneously. The column
values will then be available on the result using the
:attr:`.ResultProxy.returned_defaults` accessor as a dictionary,
- referring to values keyed to the :class:`.Column` object as well as
+ referring to values keyed to the :class:`_schema.Column`
+ object as well as
its ``.key``.
This method differs from :meth:`.UpdateBase.returning` in these ways:
an efficient implementation for the ``eager_defaults`` feature of
:func:`.mapper`.
- :param cols: optional list of column key names or :class:`.Column`
+ :param cols: optional list of column key names or
+ :class:`_schema.Column`
objects. If omitted, all column expressions evaluated on the server
are added to the returning list.
class Insert(ValuesBase):
"""Represent an INSERT construct.
- The :class:`~.sql.expression.Insert` object is created using the
- :func:`~.expression.insert()` function.
+ The :class:`_expression.Insert` object is created using the
+ :func:`_expression.insert()` function.
.. seealso::
return_defaults=False,
**dialect_kw
):
- """Construct an :class:`~.sql.expression.Insert` object.
+ """Construct an :class:`_expression.Insert` object.
Similar functionality is available via the
- :meth:`~.TableClause.insert` method on
- :class:`~.schema.Table`.
+ :meth:`_expression.TableClause.insert` method on
+ :class:`_schema.Table`.
- :param table: :class:`.TableClause` which is the subject of the
+ :param table: :class:`_expression.TableClause`
+ which is the subject of the
insert.
:param values: collection of values to be inserted; see
- :meth:`.Insert.values` for a description of allowed formats here.
- Can be omitted entirely; a :class:`~.sql.expression.Insert` construct
+ :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:`.Connection.execute`.
+ 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;
@_generative
def inline(self):
- """Make this :class:`~.sql.expression.Insert` construct "inline" .
+ """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;
returning" feature for the statement.
- .. versionchanged:: 1.4 the :paramref:`.Insert.inline` parameter
- is now superseded by the :meth:`.Insert.inline` method.
+ .. versionchanged:: 1.4 the :paramref:`_expression.Insert.inline`
+ parameter
+ is now superseded by the :meth:`_expression.Insert.inline` method.
"""
self._inline = True
@_generative
def from_select(self, names, select, include_defaults=True):
- """Return a new :class:`~.sql.expression.Insert` construct which represents
+ """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:`.Column`
+ :param names: a sequence of string column names or
+ :class:`_schema.Column`
objects representing the target columns.
- :param select: a :func:`~.sql.expression.select` construct,
- :class:`.FromClause`
- or other construct which resolves into a :class:`.FromClause`,
- such as an ORM :class:`.Query` object, etc. The order of
+ :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:`.Column` objects
+ 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
will only be invoked **once** for the whole statement, and **not
per row**.
- .. versionadded:: 1.0.0 - :meth:`.Insert.from_select` now renders
+ .. versionadded:: 1.0.0 - :meth:`_expression.Insert.from_select`
+ now renders
Python-side and SQL expression column defaults into the
SELECT statement for columns otherwise not included in the
list of column names.
.. versionchanged:: 1.0.0 an INSERT that uses FROM SELECT
- implies that the :paramref:`.insert.inline` flag is set to
+ implies that the :paramref:`_expression.insert.inline`
+ flag is set to
True, indicating that the statement will not attempt to fetch
the "last inserted primary key" or other defaults. The statement
deals with an arbitrary number of rows, so the
class Update(DMLWhereBase, ValuesBase):
"""Represent an Update construct.
- The :class:`.Update` object is created using the :func:`update()`
+ The :class:`_expression.Update`
+ object is created using the :func:`update()`
function.
"""
preserve_parameter_order=False,
**dialect_kw
):
- r"""Construct an :class:`.Update` object.
+ r"""Construct an :class:`_expression.Update` object.
E.g.::
values(name='user #5')
Similar functionality is available via the
- :meth:`~.TableClause.update` method on
- :class:`.Table`::
+ :meth:`_expression.TableClause.update` method on
+ :class:`_schema.Table`::
stmt = users.update().\
where(users.c.id==5).\
values(name='user #5')
- :param table: A :class:`.Table` object representing the database
+ :param table: A :class:`_schema.Table`
+ object representing the database
table to be updated.
:param whereclause: Optional SQL expression describing the ``WHERE``
the ``SET`` clause generates for all columns.
Modern applications may prefer to use the generative
- :meth:`.Update.values` method to set the values of the
+ :meth:`_expression.Update.values` method to set the values of the
UPDATE statement.
:param inline:
- if True, SQL defaults present on :class:`.Column` objects via
+ if True, 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
:param preserve_parameter_order: if True, the update statement is
expected to receive parameters **only** via the
- :meth:`.Update.values` method, and they must be passed as a Python
+ :meth:`_expression.Update.values` method,
+ and they must be passed as a Python
``list`` of 2-tuples. The rendered UPDATE statement will emit the SET
clause for each referenced column maintaining this order.
.. seealso::
:ref:`updates_order_parameters` - illustrates the
- :meth:`.Update.ordered_values` method.
+ :meth:`_expression.Update.ordered_values` method.
If both ``values`` and compile-time bind parameters are present, the
compile-time bind parameters override the information specified
within ``values`` on a per-key basis.
- The keys within ``values`` can be either :class:`.Column`
+ The keys within ``values`` can be either :class:`_schema.Column`
objects or their string identifiers (specifically the "key" of the
- :class:`.Column`, normally but not necessarily equivalent to
+ :class:`_schema.Column`, normally but not necessarily equivalent to
its "name"). Normally, the
- :class:`.Column` objects used here are expected to be
- part of the target :class:`.Table` that is the table
+ :class:`_schema.Column` objects used here are expected to be
+ part of the target :class:`_schema.Table` that is the table
to be updated. However when using MySQL, a multiple-table
UPDATE statement can refer to columns from any of
the tables referred to in the WHERE clause.
The values referred to in ``values`` are typically:
* a literal data value (i.e. string, number, etc.)
- * a SQL expression, such as a related :class:`.Column`,
- a scalar-returning :func:`~.sql.expression.select` construct,
+ * a SQL expression, such as a related :class:`_schema.Column`,
+ a scalar-returning :func:`_expression.select` construct,
etc.
- when combining :func:`~.sql.expression.select` constructs within the
- values clause of an :func:`.update`
+ when combining :func:`_expression.select` constructs within the
+ values clause of an :func:`_expression.update`
construct, the subquery represented
- by the :func:`~.sql.expression.select` should be *correlated* to the
+ by the :func:`_expression.select` should be *correlated* to the
parent table, that is, providing criterion which links the table inside
the subquery to the outer table being updated::
.. seealso::
:ref:`updates_order_parameters` - full example of the
- :meth:`.Update.ordered_values` method.
+ :meth:`_expression.Update.ordered_values` method.
- .. versionchanged:: 1.4 The :meth:`.Update.ordered_values` method
- supersedes the :paramref:`.update.preserve_parameter_order`
+ .. 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.
"""
@_generative
def inline(self):
- """Make this :class:`.Update` construct "inline" .
+ """Make this :class:`_expression.Update` construct "inline" .
- When set, SQL defaults present on :class:`.Column` objects via the
+ 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:`.ResultProxy.last_updated_params`.
- .. versionchanged:: 1.4 the :paramref:`.update.inline` parameter
- is now superseded by the :meth:`.Update.inline` method.
+ .. versionchanged:: 1.4 the :paramref:`_expression.update.inline`
+ parameter
+ is now superseded by the :meth:`_expression.Update.inline` method.
"""
self._inline = True
class Delete(DMLWhereBase, UpdateBase):
"""Represent a DELETE construct.
- The :class:`.Delete` object is created using the :func:`delete()`
+ The :class:`_expression.Delete`
+ object is created using the :func:`delete()`
function.
"""
prefixes=None,
**dialect_kw
):
- r"""Construct :class:`.Delete` object.
+ r"""Construct :class:`_expression.Delete` object.
Similar functionality is available via the
- :meth:`~.TableClause.delete` method on
- :class:`~.schema.Table`.
+ :meth:`_expression.TableClause.delete` method on
+ :class:`_schema.Table`.
:param table: The table to delete rows from.
- :param whereclause: A :class:`.ClauseElement` describing the ``WHERE``
+ :param whereclause: A :class:`_expression.ClauseElement`
+ describing the ``WHERE``
condition of the ``DELETE`` statement. Note that the
:meth:`~Delete.where()` generative method may be used instead.
# This module is part of SQLAlchemy and is released under
# the MIT License: http://www.opensource.org/licenses/mit-license.php
-"""Core SQL expression elements, including :class:`.ClauseElement`,
-:class:`.ColumnElement`, and derived classes.
+"""Core SQL expression elements, including :class:`_expression.ClauseElement`,
+:class:`_expression.ColumnElement`, and derived classes.
"""
SELECT id, name FROM user WHERE id BETWEEN :id_1 AND :id_2
The :func:`.between` function is a standalone version of the
- :meth:`.ColumnElement.between` method available on all
+ :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:`.ColumnElement` subclass. For example,
+ the value is not a :class:`_expression.ColumnElement` subclass.
+ For example,
three fixed values can be compared as in::
print(between(5, 3, 7))
:param_1 BETWEEN :param_2 AND :param_3
- :param expr: a column expression, typically a :class:`.ColumnElement`
+ :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.
.. seealso::
- :meth:`.ColumnElement.between`
+ :meth:`_expression.ColumnElement.between`
"""
expr = coercions.expect(roles.ExpressionElementRole, expr)
r"""Return a literal clause, bound to a bind parameter.
Literal clauses are created automatically when non-
- :class:`.ClauseElement` objects (such as strings, ints, dates, etc.) are
- used in a comparison operation with a :class:`.ColumnElement` subclass,
+ :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.
"""Return a negation of the given clause, i.e. ``NOT(clause)``.
The ``~`` operator is also overloaded on all
- :class:`.ColumnElement` subclasses to produce the
+ :class:`_expression.ColumnElement` subclasses to produce the
same result.
"""
"""in the context of binary expression, convert the type of this
object to the one given.
- applies only to :class:`.ColumnElement` classes.
+ applies only to :class:`_expression.ColumnElement` classes.
"""
return self
\**kw are arguments consumed by subclass compare() methods and
may be used to modify the criteria for comparison.
- (see :class:`.ColumnElement`)
+ (see :class:`_expression.ColumnElement`)
"""
return traversals.compare(self, other, **kw)
def self_group(self, against=None):
# type: (Optional[Any]) -> ClauseElement
- """Apply a 'grouping' to this :class:`.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:`~.sql.expression.select`
+ larger expression, as well as by :func:`_expression.select`
constructs when placed into the FROM clause of another
- :func:`~.sql.expression.select`. (Note that subqueries should be
- normally created using the :meth:`.Select.alias` method, as many
+ :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
an expression like ``x OR (y AND z)`` - AND takes precedence
over OR.
- The base :meth:`self_group` method of :class:`.ClauseElement`
+ The base :meth:`self_group` method of
+ :class:`_expression.ClauseElement`
just returns self.
"""
return self
def _ungroup(self):
- """Return this :class:`.ClauseElement` without any groupings."""
+ """Return this :class:`_expression.ClauseElement` """
+ """without any groupings."""
return self
:param bind: An ``Engine`` or ``Connection`` from which a
``Compiled`` will be acquired. This argument takes precedence over
- this :class:`.ClauseElement`'s bound engine, if any.
+ this :class:`_expression.ClauseElement`'s bound engine, if any.
:param column_keys: Used for INSERT and UPDATE statements, a list of
column names which should be present in the VALUES clause of the
:param dialect: A ``Dialect`` instance from which a ``Compiled``
will be acquired. This argument takes precedence over the `bind`
- argument as well as this :class:`.ClauseElement`'s bound engine,
+ argument as well as this :class:`_expression.ClauseElement`
+ 's bound engine,
if any.
:param inline: Used for INSERT statements, for a dialect which does
"""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:`.ColumnElement` is the
- :class:`.Column` object, :class:`.ColumnElement` serves as the basis
+ 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:`.ColumnElement` is the ultimate base class for all such elements.
+ :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:`.ColumnElement` as
+ 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:`.ColumnElement` object, or a value which can be **coerced** into
+ :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:
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:`.ColumnElement`. The Python value will ultimately be sent
+ :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
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:`.ColumnElement` and sometimes a
- :class:`.SelectBase` expression. It is used within the ORM to
+ 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:`.ColumnElement` provides the ability to generate new
- :class:`.ColumnElement`
+ 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:`.ColumnElement` instances
- which are composed from other, more fundamental :class:`.ColumnElement`
+ 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:`.ColumnElement`::
+ of :class:`_expression.ColumnElement`::
>>> from sqlalchemy.sql import column
>>> column('a') + column('b')
.. seealso::
- :class:`.Column`
+ :class:`_schema.Column`
- :func:`.expression.column`
+ :func:`_expression.column`
"""
return s
def shares_lineage(self, othercolumn):
- """Return True if the given :class:`.ColumnElement`
- has a common ancestor to this :class:`.ColumnElement`."""
+ """Return True if the given :class:`_expression.ColumnElement`
+ has a common ancestor to this :class:`_expression.ColumnElement`."""
return bool(self.proxy_set.intersection(othercolumn.proxy_set))
def _make_proxy(
self, selectable, name=None, name_is_truncatable=False, **kw
):
- """Create a new :class:`.ColumnElement` representing this
- :class:`.ColumnElement` as it appears in the select list of a
+ """Create a new :class:`_expression.ColumnElement` representing this
+ :class:`_expression.ColumnElement`
+ as it appears in the select list of a
descending selectable.
"""
def cast(self, type_):
"""Produce a type cast, i.e. ``CAST(<expression> AS <type>)``.
- This is a shortcut to the :func:`~.expression.cast` function.
+ This is a shortcut to the :func:`_expression.cast` function.
.. seealso::
:ref:`coretutorial_casts`
- :func:`~.expression.cast`
+ :func:`_expression.cast`
- :func:`~.expression.type_coerce`
+ :func:`_expression.type_coerce`
.. versionadded:: 1.0.7
def label(self, name):
"""Produce a column label, i.e. ``<columnname> AS <name>``.
- This is a shortcut to the :func:`~.expression.label` function.
+ This is a shortcut to the :func:`_expression.label` function.
if 'name' is None, an anonymous label name will be generated.
class WrapsColumnExpression(object):
- """Mixin that defines a :class:`.ColumnElement` as a wrapper with special
+ """Mixin that defines a :class:`_expression.ColumnElement`
+ as a wrapper with special
labeling behavior for an expression that already has a name.
.. versionadded:: 1.4
r"""Produce a "bound expression".
The return value is an instance of :class:`.BindParameter`; this
- is a :class:`.ColumnElement` subclass which represents a so-called
+ 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 order to populate the value of ``:username`` above, the value
would typically be applied at execution time to a method
- like :meth:`.Connection.execute`::
+ like :meth:`_engine.Connection.execute`::
result = connection.execute(stmt, username='wendy')
expr = users_table.c.name == 'Wendy'
The above expression will produce a :class:`.BinaryExpression`
- construct, where the left side is the :class:`.Column` object
+ 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::
Similarly, :func:`.bindparam` is invoked automatically when working
with :term:`CRUD` statements as far as the "VALUES" portion is
- concerned. The :func:`~.sql.expression.insert` construct produces an
+ 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::
INSERT INTO "user" (name) VALUES (%(name)s)
{'name': 'Wendy'}
- The :class:`~.sql.expression.Insert` construct, at
+ 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:`.Connection.execute` method.
+ parameter we passed to the :meth:`_engine.Connection.execute` method.
:param key:
the key (e.g. the name) for this bind param.
result = connection.execute(t)
- The :class:`.Text` construct is produced using the :func:`.text`
+ The :class:`_expression.TextClause` construct is produced using the
+ :func:`_expression.text`
function; see that function for full documentation.
.. seealso::
- :func:`.text`
+ :func:`_expression.text`
"""
@classmethod
@_document_text_coercion("text", ":func:`.text`", ":paramref:`.text.text`")
def _create_text(cls, text, bind=None):
- r"""Construct a new :class:`.TextClause` clause, representing
+ r"""Construct a new :class:`_expression.TextClause` clause,
+ representing
a textual SQL string directly.
E.g.::
t = text("SELECT * FROM users")
result = connection.execute(t)
- The advantages :func:`.text` provides over a plain string are
+ 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
t = text("SELECT * FROM users WHERE name='\:username'")
- The :class:`.TextClause` construct includes methods which can
+ 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:`.TextClause.bindparams` method is used to provide bound
- parameter detail, and :meth:`.TextClause.columns` method allows
+ :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").\
for id, name in connection.execute(t):
print(id, name)
- The :func:`.text` construct is used in cases when
+ 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:`.text` is also used for the construction
+ :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 it supports
the :meth:`Executable.execution_options` method. For example,
- a :func:`.text` construct that should be subject to "autocommit"
+ a :func:`_expression.text`
+ construct that should be subject to "autocommit"
can be set explicitly so using the
:paramref:`.Connection.execution_options.autocommit` option::
execution_options(autocommit=True)
Note that SQLAlchemy's usual "autocommit" behavior applies to
- :func:`.text` constructs implicitly - that is, statements which begin
+ :func:`_expression.text` constructs implicitly - that is,
+ statements which begin
with a phrase such as ``INSERT``, ``UPDATE``, ``DELETE``,
or a variety of other phrases specific to certain backends, will
be eligible for autocommit if no transaction is in progress.
@_generative
def bindparams(self, *binds, **names_to_values):
"""Establish the values and/or types of bound parameters within
- this :class:`.TextClause` construct.
+ this :class:`_expression.TextClause` construct.
Given a text construct such as::
stmt = text("SELECT id, name FROM user WHERE name=:name "
"AND timestamp=:timestamp")
- the :meth:`.TextClause.bindparams` method can be used to establish
+ the :meth:`_expression.TextClause.bindparams`
+ method can be used to establish
the initial value of ``:name`` and ``:timestamp``,
using simple keyword arguments::
result = connection.execute(stmt,
timestamp=datetime.datetime(2012, 10, 8, 15, 12, 5))
- The :meth:`.TextClause.bindparams` method can be called repeatedly,
+ The :meth:`_expression.TextClause.bindparams`
+ method can be called repeatedly,
where it will re-use existing :class:`.BindParameter` objects to add
new information. For example, we can call
- :meth:`.TextClause.bindparams` first with typing information, and a
+ :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 "
timestamp=datetime.datetime(2012, 10, 8, 15, 12, 5)
)
- The :meth:`.TextClause.bindparams` method also supports the concept of
+ 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:`.text` constructs may be combined together without the names
+ :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::
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:`.text`
+ :paramref:`.BindParameter.unique` flag to work with
+ :func:`_expression.text`
constructs.
"""
@util.preload_module("sqlalchemy.sql.selectable")
def columns(self, *cols, **types):
- r"""Turn this :class:`.TextClause` object into a
- :class:`.TextualSelect` object that serves the same role as a SELECT
+ r"""Turn this :class:`_expression.TextClause` object into a
+ :class:`_expression.TextualSelect`
+ object that serves the same role as a SELECT
statement.
- The :class:`.TextualSelect` is part of the :class:`.SelectBase`
+ The :class:`_expression.TextualSelect` is part of the
+ :class:`_expression.SelectBase`
hierarchy and can be embedded into another statement by using the
- :meth:`.TextualSelect.subquery` method to produce a :class:`.Subquery`
+ :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
mytable.join(stmt, mytable.c.name == stmt.c.name)
).where(stmt.c.id > 5)
- Above, we pass a series of :func:`.column` elements to the
- :meth:`.TextClause.columns` method positionally. These :func:`.column`
+ 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:`.TextualSelect.selected_columns` column collection, which then
+ :attr:`_expression.TextualSelect.selected_columns` column collection,
+ which then
become part of the :attr:`.Subquery.c` collection after
- :meth:`.TextualSelect.subquery` is invoked.
+ :meth:`_expression.TextualSelect.subquery` is invoked.
- The column expressions we pass to :meth:`.TextClause.columns` may
+ 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.
for id, name, timestamp in connection.execute(stmt):
print(id, name, timestamp)
- The positional form of :meth:`.TextClause.columns` also provides the
+ 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:`.TextClause.columns`,
+ 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::
query = session.query(User).from_statement(stmt).options(
contains_eager(User.addresses))
- .. versionadded:: 1.1 the :meth:`.TextClause.columns` method now
+ .. versionadded:: 1.1 the :meth:`_expression.TextClause.columns`
+ method now
offers positional column targeting in the result set when
the column expressions are passed purely positionally.
- The :meth:`.TextClause.columns` method provides a direct
- route to calling :meth:`.FromClause.subquery` as well as
- :meth:`.SelectBase.cte` against a textual SELECT statement::
+ 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:`.ColumnElement` objects, typically
- :class:`.Column` objects from a :class:`.Table` or ORM level
+ :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.
)
The :func:`.and_` operation is also implicit in some cases;
- the :meth:`.Select.where` method for example can be invoked multiple
+ 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_`::
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:`.ColumnElement` constructs, are accepted
+ 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:`.literal_column` construct,
+ expression rendered inline, use the :func:`_expression.literal_column`
+ construct,
as in::
from sqlalchemy import case, literal_column
def literal_column(text, type_=None):
r"""Produce a :class:`.ColumnClause` object that has the
- :paramref:`.column.is_literal` flag set to True.
+ :paramref:`_expression.column.is_literal` flag set to True.
- :func:`.literal_column` is similar to :func:`.column`, except that
+ :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:`.column` stores a string name that
+ 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:`.literal_column` can be that, or any other arbitrary column-oriented
+ :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.
.. seealso::
- :func:`.column`
+ :func:`_expression.column`
- :func:`.text`
+ :func:`_expression.text`
:ref:`sqlexpression_literal_column`
with a specific type, but does not render the ``CAST`` expression
in SQL.
- :param expression: A SQL expression, such as a :class:`.ColumnElement`
+ :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.
class TypeCoerce(WrapsColumnExpression, ColumnElement):
"""Represent a Python-side type-coercion wrapper.
- :class:`.TypeCoerce` supplies the :func:`.expression.type_coerce`
+ :class:`.TypeCoerce` supplies the :func:`_expression.type_coerce`
function; see that function for usage details.
.. versionchanged:: 1.1 The :func:`.type_coerce` function now produces
.. seealso::
- :func:`.expression.type_coerce`
+ :func:`_expression.type_coerce`
:func:`.cast`
column remains separate in the list of result columns vs. other
type-coerced or direct values of the target column. In order to
provide a named label for the expression, use
- :meth:`.ColumnElement.label`::
+ :meth:`_expression.ColumnElement.label`::
stmt = select([
type_coerce(
except that it does not render the ``CAST`` expression in the resulting
statement.
- :param expression: A SQL expression, such as a :class:`.ColumnElement`
+ :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.
Like :func:`.asc` and :func:`.desc`, :func:`.nullsfirst` is typically
invoked from the column expression itself using
- :meth:`.ColumnElement.nullsfirst`, rather than as its standalone
+ :meth:`_expression.ColumnElement.nullsfirst`,
+ rather than as its standalone
function version, as in::
stmt = (select([users_table]).
:func:`.nullslast`
- :meth:`.Select.order_by`
+ :meth:`_expression.Select.order_by`
"""
return UnaryExpression(
Like :func:`.asc` and :func:`.desc`, :func:`.nullslast` is typically
invoked from the column expression itself using
- :meth:`.ColumnElement.nullslast`, rather than as its standalone
+ :meth:`_expression.ColumnElement.nullslast`,
+ rather than as its standalone
function version, as in::
stmt = select([users_table]).\
:func:`.nullsfirst`
- :meth:`.Select.order_by`
+ :meth:`_expression.Select.order_by`
"""
return UnaryExpression(
SELECT id, name FROM user ORDER BY name DESC
The :func:`.desc` function is a standalone version of the
- :meth:`.ColumnElement.desc` method available on all SQL expressions,
+ :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:`.ColumnElement` (e.g. scalar SQL expression)
+ :param column: A :class:`_expression.ColumnElement` (e.g.
+ scalar SQL expression)
with which to apply the :func:`.desc` operation.
.. seealso::
:func:`.nullslast`
- :meth:`.Select.order_by`
+ :meth:`_expression.Select.order_by`
"""
return UnaryExpression(
SELECT id, name FROM user ORDER BY name ASC
The :func:`.asc` function is a standalone version of the
- :meth:`.ColumnElement.asc` method available on all SQL expressions,
+ :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:`.ColumnElement` (e.g. scalar SQL expression)
+ :param column: A :class:`_expression.ColumnElement` (e.g.
+ scalar SQL expression)
with which to apply the :func:`.asc` operation.
.. seealso::
:func:`.nullslast`
- :meth:`.Select.order_by`
+ :meth:`_expression.Select.order_by`
"""
return UnaryExpression(
SELECT COUNT(DISTINCT name) FROM user
The :func:`.distinct` function is also available as a column-level
- method, e.g. :meth:`.ColumnElement.distinct`, as in::
+ 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:`.Select.distinct` method of :class:`.Select`,
+ :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
.. seealso::
- :meth:`.ColumnElement.distinct`
+ :meth:`_expression.ColumnElement.distinct`
- :meth:`.Select.distinct`
+ :meth:`_expression.Select.distinct`
:data:`.func`
.. seealso::
- :func:`.expression.all_`
+ :func:`_expression.all_`
"""
.. seealso::
- :func:`.expression.any_`
+ :func:`_expression.any_`
"""
Used against aggregate or so-called "window" functions,
for database backends that support window functions.
- :func:`~.expression.over` is usually called using
+ :func:`_expression.over` is usually called using
the :meth:`.FunctionElement.over` method, e.g.::
func.row_number().over(order_by=mytable.c.some_column)
:data:`.expression.func`
- :func:`.expression.within_group`
+ :func:`_expression.within_group`
"""
self.element = element
set aggregate" functions, including :class:`.percentile_cont`,
:class:`.rank`, :class:`.dense_rank`, etc.
- :func:`~.expression.within_group` is usually called using
+ :func:`_expression.within_group` is usually called using
the :meth:`.FunctionElement.within_group` method, e.g.::
from sqlalchemy import within_group
:data:`.expression.func`
- :func:`.expression.over`
+ :func:`_expression.over`
"""
self.element = element
from sqlalchemy import over, funcfilter
over(funcfilter(func.rank(), MyClass.y > 5), order_by='x')
- See :func:`~.expression.over` for a full description.
+ See :func:`_expression.over` for a full description.
"""
return Over(
def __init__(self, name, element, type_=None):
"""Return a :class:`Label` object for the
- given :class:`.ColumnElement`.
+ 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:`.ColumnElement.label` method on :class:`.ColumnElement`.
+ :meth:`_expression.ColumnElement.label` method on
+ :class:`_expression.ColumnElement`.
:param name: label name
- :param obj: a :class:`.ColumnElement`.
+ :param obj: a :class:`_expression.ColumnElement`.
"""
"""Represents a column expression from any textual string.
The :class:`.ColumnClause`, a lightweight analogue to the
- :class:`.Column` class, is typically invoked using the
- :func:`.column` function, as in::
+ :class:`_schema.Column` class, is typically invoked using the
+ :func:`_expression.column` function, as in::
from sqlalchemy import column
SELECT id, name FROM user
:class:`.ColumnClause` is the immediate superclass of the schema-specific
- :class:`.Column` object. While the :class:`.Column` class has all the
+ :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:`.Column` does, so in that sense is a "lightweight"
- version of :class:`.Column`.
+ 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:`.column`.
+ Full details on :class:`.ColumnClause` usage is at
+ :func:`_expression.column`.
.. seealso::
- :func:`.column`
+ :func:`_expression.column`
- :class:`.Column`
+ :class:`_schema.Column`
"""
"""Produce a :class:`.ColumnClause` object.
The :class:`.ColumnClause` is a lightweight analogue to the
- :class:`.Column` class. The :func:`.column` function can
+ :class:`_schema.Column` class. The :func:`_expression.column`
+ function can
be invoked with just a name alone, as in::
from sqlalchemy import column
SELECT id, name FROM user
- Once constructed, :func:`.column` may be used like any other SQL
- expression element such as within :func:`~.sql.expression.select`
+ 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:`.column` is assumed to be handled
+ 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:`.literal_column` instead, or pass ``True`` as the
- value of :paramref:`.column.is_literal`. Additionally, full SQL
- statements are best handled using the :func:`.text` construct.
+ 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:`.column` can be used in a table-like
+ :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:`.Table`) to produce
+ (which is the lightweight analogue to :class:`_schema.Table`
+ ) to produce
a working table construct with minimal boilerplate::
from sqlalchemy import table, column, select
stmt = select([user.c.description]).where(user.c.name == 'wendy')
- A :func:`.column` / :func:`.table` construct like that illustrated
+ 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:`.Table` counterpart.
+ :class:`_schema.MetaData`, DDL, or events, unlike its
+ :class:`_schema.Table` counterpart.
- .. versionchanged:: 1.0.0 :func:`.expression.column` can now
+ .. versionchanged:: 1.0.0 :func:`_expression.column` can now
be imported from the plain ``sqlalchemy`` namespace like any
other SQL element.
:param text: the text of the element.
- :param type: :class:`.types.TypeEngine` object which can associate
+ :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:`.literal_column()` function essentially invokes
- :func:`.column` while passing ``is_literal=True``.
+ :func:`_expression.literal_column()` function essentially invokes
+ :func:`_expression.column` while passing ``is_literal=True``.
.. seealso::
- :class:`.Column`
+ :class:`_schema.Column`
- :func:`.literal_column`
+ :func:`_expression.literal_column`
:func:`.table`
- :func:`.text`
+ :func:`_expression.text`
:ref:`sqlexpression_literal_column`
The :class:`.quoted_name` object is normally created automatically
when specifying the name for key schema constructs such as
- :class:`.Table`, :class:`.Column`, and others. The class can also be
+ :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 to use the :meth:`.Engine.has_table` method with
+ can be quoted. Such as to use the :meth:`_engine.Engine.has_table`
+ method with
an unconditionally quoted name::
from sqlalchemy import create_engine
In some situations, such as in migration scripts, we may be rendering
the above :class:`.CheckConstraint` with a name that's already been
converted. In order to make sure the name isn't double-modified, the
- new name is applied using the :func:`.schema.conv` marker. We can
+ new name is applied using the :func:`_schema.conv` marker. We can
use this explicitly as follows::
t = Table('t', m, Column('x', Integer),
CheckConstraint('x > 5', name=conv('ck_t_x5')))
- Where above, the :func:`.schema.conv` marker indicates that the constraint
+ Where above, the :func:`_schema.conv` marker indicates that the constraint
name here is final, and the name will render as ``"ck_t_x5"`` and not
``"ck_t_ck_t_x5"``
"""
Define event listeners for schema objects,
that is, :class:`.SchemaItem` and other :class:`.SchemaEventTarget`
- subclasses, including :class:`.MetaData`, :class:`.Table`,
- :class:`.Column`.
+ subclasses, including :class:`_schema.MetaData`, :class:`_schema.Table`,
+ :class:`_schema.Column`.
- :class:`.MetaData` and :class:`.Table` support events
+ :class:`_schema.MetaData` and :class:`_schema.Table` support events
specifically regarding when CREATE and DROP
DDL is emitted to the database.
Attachment events are also provided to customize
behavior whenever a child schema element is associated
- with a parent, such as, when a :class:`.Column` is associated
- with its :class:`.Table`, when a :class:`.ForeignKeyConstraint`
- is associated with a :class:`.Table`, etc.
+ with a parent, such as, when a :class:`_schema.Column` is associated
+ with its :class:`_schema.Table`, when a
+ :class:`_schema.ForeignKeyConstraint`
+ is associated with a :class:`_schema.Table`, etc.
Example using the ``after_create`` event::
For all :class:`.DDLEvent` events, the ``propagate=True`` keyword argument
will ensure that a given event handler is propagated to copies of the
- object, which are made when using the :meth:`.Table.tometadata` method::
+ object, which are made when using the :meth:`_schema.Table.tometadata`
+ method::
from sqlalchemy import DDL
event.listen(
new_table = some_table.tometadata(new_metadata)
The above :class:`.DDL` object will also be associated with the
- :class:`.Table` object represented by ``new_table``.
+ :class:`_schema.Table` object represented by ``new_table``.
.. seealso::
def before_create(self, target, connection, **kw):
r"""Called before CREATE statements are emitted.
- :param target: the :class:`.MetaData` or :class:`.Table`
+ :param target: the :class:`_schema.MetaData` or :class:`_schema.Table`
object which is the target of the event.
- :param connection: the :class:`.Connection` where the
+ :param connection: the :class:`_engine.Connection` where the
CREATE statement or statements will be emitted.
:param \**kw: additional keyword arguments relevant
to the event. The contents of this dictionary
modifier for this event; when True, the listener function will
be established for any copies made of the target object,
i.e. those copies that are generated when
- :meth:`.Table.tometadata` is used.
+ :meth:`_schema.Table.tometadata` is used.
"""
def after_create(self, target, connection, **kw):
r"""Called after CREATE statements are emitted.
- :param target: the :class:`.MetaData` or :class:`.Table`
+ :param target: the :class:`_schema.MetaData` or :class:`_schema.Table`
object which is the target of the event.
- :param connection: the :class:`.Connection` where the
+ :param connection: the :class:`_engine.Connection` where the
CREATE statement or statements have been emitted.
:param \**kw: additional keyword arguments relevant
to the event. The contents of this dictionary
modifier for this event; when True, the listener function will
be established for any copies made of the target object,
i.e. those copies that are generated when
- :meth:`.Table.tometadata` is used.
+ :meth:`_schema.Table.tometadata` is used.
"""
def before_drop(self, target, connection, **kw):
r"""Called before DROP statements are emitted.
- :param target: the :class:`.MetaData` or :class:`.Table`
+ :param target: the :class:`_schema.MetaData` or :class:`_schema.Table`
object which is the target of the event.
- :param connection: the :class:`.Connection` where the
+ :param connection: the :class:`_engine.Connection` where the
DROP statement or statements will be emitted.
:param \**kw: additional keyword arguments relevant
to the event. The contents of this dictionary
modifier for this event; when True, the listener function will
be established for any copies made of the target object,
i.e. those copies that are generated when
- :meth:`.Table.tometadata` is used.
+ :meth:`_schema.Table.tometadata` is used.
"""
def after_drop(self, target, connection, **kw):
r"""Called after DROP statements are emitted.
- :param target: the :class:`.MetaData` or :class:`.Table`
+ :param target: the :class:`_schema.MetaData` or :class:`_schema.Table`
object which is the target of the event.
- :param connection: the :class:`.Connection` where the
+ :param connection: the :class:`_engine.Connection` where the
DROP statement or statements have been emitted.
:param \**kw: additional keyword arguments relevant
to the event. The contents of this dictionary
modifier for this event; when True, the listener function will
be established for any copies made of the target object,
i.e. those copies that are generated when
- :meth:`.Table.tometadata` is used.
+ :meth:`_schema.Table.tometadata` is used.
"""
modifier for this event; when True, the listener function will
be established for any copies made of the target object,
i.e. those copies that are generated when
- :meth:`.Table.tometadata` is used.
+ :meth:`_schema.Table.tometadata` is used.
"""
modifier for this event; when True, the listener function will
be established for any copies made of the target object,
i.e. those copies that are generated when
- :meth:`.Table.tometadata` is used.
+ :meth:`_schema.Table.tometadata` is used.
"""
def column_reflect(self, inspector, table, column_info):
"""Called for each unit of 'column info' retrieved when
- a :class:`.Table` is being reflected.
+ a :class:`_schema.Table` is being reflected.
The dictionary of column information as returned by the
dialect is passed, and can be modified. The dictionary
* ``default`` - the column's server default value. This is
normally specified as a plain string SQL expression, however the
event can pass a :class:`.FetchedValue`, :class:`.DefaultClause`,
- or :func:`.sql.expression.text` object as well.
+ or :func:`_expression.text` object as well.
.. versionchanged:: 1.1.6
The :meth:`.DDLEvents.column_reflect` event allows a non
string :class:`.FetchedValue`,
- :func:`.sql.expression.text`, or derived object to be
+ :func:`_expression.text`, or derived object to be
specified as the value of ``default`` in the column
dictionary.
The event is called before any action is taken against
this dictionary, and the contents can be modified.
- The :class:`.Column` specific arguments ``info``, ``key``,
+ The :class:`_schema.Column` specific arguments ``info``, ``key``,
and ``quote`` can also be added to the dictionary and
- will be passed to the constructor of :class:`.Column`.
+ will be passed to the constructor of :class:`_schema.Column`.
Note that this event is only meaningful if either
- associated with the :class:`.Table` class across the
+ associated with the :class:`_schema.Table` class across the
board, e.g.::
from sqlalchemy.schema import Table
'column_reflect',
listen_for_reflect)
- ...or with a specific :class:`.Table` instance using
+ ...or with a specific :class:`_schema.Table` instance using
the ``listeners`` argument::
def listen_for_reflect(inspector, table, column_info):
])
This because the reflection process initiated by ``autoload=True``
- completes within the scope of the constructor for :class:`.Table`.
+ completes within the scope of the constructor for
+ :class:`_schema.Table`.
:func:`.event.listen` also accepts the ``propagate=True``
modifier for this event; when True, the listener function will
be established for any copies made of the target object,
i.e. those copies that are generated when
- :meth:`.Table.tometadata` is used.
+ :meth:`_schema.Table.tometadata` is used.
"""
an anonymously named column.
An interim approach to providing named columns for a function
- as a FROM clause is to build a :func:`~.sql.expression.select` with the
+ as a FROM clause is to build a :func:`_expression.select` with the
desired columns::
from sqlalchemy.sql import column
from sqlalchemy import over
over(func.row_number(), order_by='x')
- See :func:`~.expression.over` for a full description.
+ See :func:`_expression.over` for a full description.
"""
return Over(
set aggregate" functions, including :class:`.percentile_cont`,
:class:`.rank`, :class:`.dense_rank`, etc.
- See :func:`~.expression.within_group` for a full description.
+ See :func:`_expression.within_group` for a full description.
.. versionadded:: 1.1
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:`.relationship.primaryjoin` parameter. The return
+ with the :paramref:`_orm.relationship.primaryjoin` parameter.
+ The return
value is a containment object called :class:`.FunctionAsBinary`.
An ORM example is as follows::
return None
def alias(self, name=None, flat=False):
- r"""Produce a :class:`.Alias` construct against this
+ r"""Produce a :class:`_expression.Alias` construct against this
:class:`.FunctionElement`.
This construct wraps the function in a named alias which
return Alias._construct(self, name)
def select(self):
- """Produce a :func:`~.expression.select` construct
+ """Produce a :func:`_expression.select` construct
against this :class:`.FunctionElement`.
This is shorthand for::
produce a SELECT construct.
Note that :class:`.FunctionElement` can be passed to
- the :meth:`.Connectable.scalar` method of :class:`.Connection`
- or :class:`.Engine`.
+ the :meth:`.Connectable.scalar` method of :class:`_engine.Connection`
+ or :class:`_engine.Engine`.
"""
return self.select().execute().scalar()
produce a SELECT construct.
Note that :class:`.FunctionElement` can be passed to
- the :meth:`.Connectable.execute` method of :class:`.Connection`
- or :class:`.Engine`.
+ the :meth:`.Connectable.execute` method of :class:`_engine.Connection`
+ or :class:`_engine.Engine`.
"""
return self.select().execute()
: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:`.Connection` or :class:`.Engine`, where it will be
+ 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())
"""support for the ARRAY_AGG function.
The ``func.array_agg(expr)`` construct returns an expression of
- type :class:`.types.ARRAY`.
+ type :class:`_types.ARRAY`.
e.g.::
.. seealso::
- :func:`.postgresql.array_agg` - PostgreSQL-specific version that
- returns :class:`.postgresql.ARRAY`, which has PG-specific operators
+ :func:`_postgresql.array_agg` - PostgreSQL-specific version that
+ returns :class:`_postgresql.ARRAY`, which has PG-specific operators
added.
"""
modifier to supply a sort expression to operate upon.
The return type of this function is the same as the sort expression,
- or if the arguments are an array, an :class:`.types.ARRAY` of the sort
+ or if the arguments are an array, an :class:`_types.ARRAY` of the sort
expression's type.
.. versionadded:: 1.1
modifier to supply a sort expression to operate upon.
The return type of this function is the same as the sort expression,
- or if the arguments are an array, an :class:`.types.ARRAY` of the sort
+ or if the arguments are an array, an :class:`_types.ARRAY` of the sort
expression's type.
.. versionadded:: 1.1
r"""Implement the ``CUBE`` grouping operation.
This function is used as part of the GROUP BY of a statement,
- e.g. :meth:`.Select.group_by`::
+ e.g. :meth:`_expression.Select.group_by`::
stmt = select(
[func.sum(table.c.value), table.c.col_1, table.c.col_2]
r"""Implement the ``ROLLUP`` grouping operation.
This function is used as part of the GROUP BY of a statement,
- e.g. :meth:`.Select.group_by`::
+ e.g. :meth:`_expression.Select.group_by`::
stmt = select(
[func.sum(table.c.value), table.c.col_1, table.c.col_2]
r"""Implement the ``GROUPING SETS`` grouping operation.
This function is used as part of the GROUP BY of a statement,
- e.g. :meth:`.Select.group_by`::
+ e.g. :meth:`_expression.Select.group_by`::
stmt = select(
[func.sum(table.c.value), table.c.col_1, table.c.col_2]
When used with SQL expressions, results in an
AND operation, equivalent to
- :func:`~.expression.and_`, that is::
+ :func:`_expression.and_`, that is::
a & b
When used with SQL expressions, results in an
OR operation, equivalent to
- :func:`~.expression.or_`, that is::
+ :func:`_expression.or_`, that is::
a | b
When used with SQL expressions, results in a
NOT operation, equivalent to
- :func:`~.expression.not_`, that is::
+ :func:`_expression.not_`, that is::
~a
class ColumnOperators(Operators):
"""Defines boolean, comparison, and other operators for
- :class:`.ColumnElement` expressions.
+ :class:`_expression.ColumnElement` expressions.
By default, all methods call down to
:meth:`.operate` or :meth:`.reverse_operate`,
def eq(a, b):
return a == b
- The core column expression unit :class:`.ColumnElement`
+ The core column expression unit :class:`_expression.ColumnElement`
overrides :meth:`.Operators.operate` and others
- to return further :class:`.ColumnElement` constructs,
+ to return further :class:`_expression.ColumnElement` constructs,
so that the ``==`` operation above is replaced by a clause
construct.
.. versionadded:: 1.3 "expanding" bound parameters now support
empty lists
- * a :func:`~.sql.expression.select` construct, which is usually a
+ * a :func:`_expression.select` construct, which is usually a
correlated scalar select::
stmt.where(
WHERE COL IN (SELECT othertable.y
FROM othertable WHERE othertable.x = table.x)
- :param other: a list of literals, a :func:`~.sql.expression.select`
+ :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.
return self.operate(match_op, other, **kwargs)
def desc(self):
- """Produce a :func:`~.expression.desc` clause against the
+ """Produce a :func:`_expression.desc` clause against the
parent object."""
return self.operate(desc_op)
def asc(self):
- """Produce a :func:`~.expression.asc` clause against the
+ """Produce a :func:`_expression.asc` clause against the
parent object."""
return self.operate(asc_op)
def nullsfirst(self):
- """Produce a :func:`~.expression.nullsfirst` clause against the
+ """Produce a :func:`_expression.nullsfirst` clause against the
parent object."""
return self.operate(nullsfirst_op)
def nullslast(self):
- """Produce a :func:`~.expression.nullslast` clause against the
+ """Produce a :func:`_expression.nullslast` clause against the
parent object."""
return self.operate(nullslast_op)
def collate(self, collation):
- """Produce a :func:`~.expression.collate` clause against
+ """Produce a :func:`_expression.collate` clause against
the parent object, given the collation string.
.. seealso::
- :func:`~.expression.collate`
+ :func:`_expression.collate`
"""
return self.operate(collate, collation)
return self.reverse_operate(mod, other)
def between(self, cleft, cright, symmetric=False):
- """Produce a :func:`~.expression.between` clause against
+ """Produce a :func:`_expression.between` clause against
the parent object, given the lower and upper range.
"""
return self.operate(between_op, cleft, cright, symmetric=symmetric)
def distinct(self):
- """Produce a :func:`~.expression.distinct` clause against the
+ """Produce a :func:`_expression.distinct` clause against the
parent object.
"""
return self.operate(distinct_op)
def any_(self):
- """Produce a :func:`~.expression.any_` clause against the
+ """Produce a :func:`_expression.any_` clause against the
parent object.
This operator is only appropriate against a scalar subquery
.. seealso::
- :func:`~.expression.any_` - standalone version
+ :func:`_expression.any_` - standalone version
- :func:`~.expression.all_` - ALL operator
+ :func:`_expression.all_` - ALL operator
.. versionadded:: 1.1
return self.operate(any_op)
def all_(self):
- """Produce a :func:`~.expression.all_` clause against the
+ """Produce a :func:`_expression.all_` clause against the
parent object.
This operator is only appropriate against a scalar subquery
.. seealso::
- :func:`~.expression.all_` - standalone version
+ :func:`_expression.all_` - standalone version
- :func:`~.expression.any_` - ANY operator
+ :func:`_expression.any_` - ANY operator
.. versionadded:: 1.1
BLANK_SCHEMA = util.symbol(
"blank_schema",
- """Symbol indicating that a :class:`.Table` or :class:`.Sequence`
+ """Symbol indicating that a :class:`_schema.Table` or :class:`.Sequence`
should have 'None' for its schema, even if the parent
- :class:`.MetaData` has specified a schema.
+ :class:`_schema.MetaData` has specified a schema.
.. versionadded:: 1.0.14
The dictionary is automatically generated when first accessed.
It can also be specified in the constructor of some objects,
- such as :class:`.Table` and :class:`.Column`.
+ such as :class:`_schema.Table` and :class:`_schema.Column`.
"""
return {}
Column('value', String(50))
)
- The :class:`.Table` object constructs a unique instance of itself based
+ The :class:`_schema.Table`
+ object constructs a unique instance of itself based
on its name and optional schema name within the given
- :class:`.MetaData` object. Calling the :class:`.Table`
- constructor with the same name and same :class:`.MetaData` argument
- a second time will return the *same* :class:`.Table` object - in this way
- the :class:`.Table` constructor acts as a registry function.
+ :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::
: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:`.Table` within
- the owning :class:`.MetaData` collection.
- Additional calls to :class:`.Table` with the same name, metadata,
- and schema name will return the same :class:`.Table` object.
+ 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
``quote=True`` to the constructor, or use the :class:`.quoted_name`
construct to specify the name.
- :param metadata: a :class:`.MetaData` object which will contain this
+ :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:`.Connectable`.
:param \*args: Additional positional arguments are used primarily
- to add the list of :class:`.Column` objects contained within this
+ 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:`.ForeignKeyConstraint`.
+ :class:`.PrimaryKeyConstraint`, and
+ :class:`_schema.ForeignKeyConstraint`.
- :param autoload: Defaults to False, unless :paramref:`.Table.autoload_with`
- is set in which case it defaults to True; :class:`.Column` objects
+ :param autoload: Defaults to False, unless
+ :paramref:`_schema.Table.autoload_with`
+ is set in which case it defaults to True; :class:`_schema.Column`
+ objects
for this table should be reflected from the database, possibly
- augmenting or replacing existing :class:`.Column` objects that were
+ augmenting or replacing existing :class:`_schema.Column`
+ objects that were
explicitly specified.
- .. versionchanged:: 1.0.0 setting the :paramref:`.Table.autoload_with`
- parameter implies that :paramref:`.Table.autoload` will default
+ .. versionchanged:: 1.0.0 setting the
+ :paramref:`_schema.Table.autoload_with`
+ parameter implies that :paramref:`_schema.Table.autoload`
+ will default
to True.
.. seealso::
:ref:`metadata_reflection_toplevel`
:param autoload_replace: Defaults to ``True``; when using
- :paramref:`.Table.autoload`
- in conjunction with :paramref:`.Table.extend_existing`, indicates
- that :class:`.Column` objects present in the already-existing
- :class:`.Table` object should be replaced with columns of the same
+ :paramref:`_schema.Table.autoload`
+ 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:`.Column` objects
- specified programmatically within the call to :class:`.Table` that
- also is autoloading; those :class:`.Column` objects will always
+ 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:`.Table.extend_existing` is ``True``.
+ :paramref:`_schema.Table.extend_existing` is ``True``.
.. seealso::
- :paramref:`.Table.autoload`
+ :paramref:`_schema.Table.autoload`
- :paramref:`.Table.extend_existing`
+ :paramref:`_schema.Table.extend_existing`
- :param autoload_with: An :class:`.Engine` or :class:`.Connection` object,
- or a :class:`.Inspector` object as returned by :func:`.inspect`
- against one, with which this :class:`.Table` object will be reflected.
+ :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, it implies that
- :paramref:`.Table.autoload` is ``True``. If left unset, but
- :paramref:`.Table.autoload` is explicitly set to ``True``, an autoload
- operation will attempt to proceed by locating an :class:`.Engine` or
- :class:`.Connection` bound to the underlying :class:`.MetaData` object.
+ :paramref:`_schema.Table.autoload` is ``True``. If left unset, but
+ :paramref:`_schema.Table.autoload` is explicitly set to ``True``,
+ an autoload
+ operation will attempt to proceed by locating an
+ :class:`_engine.Engine` or
+ :class:`_engine.Connection` bound to the underlying
+ :class:`_schema.MetaData` object.
.. seealso::
- :paramref:`.Table.autoload`
+ :paramref:`_schema.Table.autoload`
:param extend_existing: When ``True``, indicates that if this
- :class:`.Table` is already present in the given :class:`.MetaData`,
+ :class:`_schema.Table` is already present in the given
+ :class:`_schema.MetaData`,
apply further arguments within the constructor to the existing
- :class:`.Table`.
-
- If :paramref:`.Table.extend_existing` or
- :paramref:`.Table.keep_existing` are not set, and the given name
- of the new :class:`.Table` refers to a :class:`.Table` that is
- already present in the target :class:`.MetaData` collection, and
- this :class:`.Table` specifies additional columns or other constructs
+ :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:`.Table`
- is specified that matches an existing :class:`.Table`, yet specifies
+ 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:`.Table.extend_existing` will also work in conjunction
- with :paramref:`.Table.autoload` to run a new reflection
- operation against the database, even if a :class:`.Table`
+ :paramref:`_schema.Table.extend_existing`
+ will also work in conjunction
+ with :paramref:`_schema.Table.autoload` 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:`.MetaData`; newly reflected :class:`.Column` objects
+ :class:`_schema.MetaData`; newly reflected :class:`_schema.Column`
+ objects
and other options will be added into the state of the
- :class:`.Table`, potentially overwriting existing columns
+ :class:`_schema.Table`, potentially overwriting existing columns
and options of the same name.
- As is always the case with :paramref:`.Table.autoload`,
- :class:`.Column` objects can be specified in the same :class:`.Table`
+ As is always the case with :paramref:`_schema.Table.autoload`,
+ :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:`.Column` objects
- both reflected from the database, as well as the given :class:`.Column`
+ 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,
.. seealso::
- :paramref:`.Table.autoload`
+ :paramref:`_schema.Table.autoload`
- :paramref:`.Table.autoload_replace`
+ :paramref:`_schema.Table.autoload_replace`
- :paramref:`.Table.keep_existing`
+ :paramref:`_schema.Table.keep_existing`
:param implicit_returning: True by default - indicates that
``Table`` object. Defaults to ``None`` which indicates all columns
should be reflected.
- :param resolve_fks: Whether or not to reflect :class:`.Table` objects
- related to this one via :class:`.ForeignKey` objects, when
- :paramref:`.Table.autoload` or :paramref:`.Table.autoload_with` is
+ :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` or
+ :paramref:`_schema.Table.autoload_with` is
specified. Defaults to True. Set to False to disable reflection of
- related tables as :class:`.ForeignKey` objects are encountered; may be
+ 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:`.MetaData` collection, or becomes present later, a
- :class:`.ForeignKey` object associated with this :class:`.Table` will
+ 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
:attr:`.SchemaItem.info` attribute of this object.
:param keep_existing: When ``True``, indicates that if this Table
- is already present in the given :class:`.MetaData`, ignore
+ is already present in the given :class:`_schema.MetaData`, ignore
further arguments within the constructor to the existing
- :class:`.Table`, and return the :class:`.Table` object as
+ :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:`.Table` on first call, but on
- subsequent calls will return the same :class:`.Table`,
+ 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:`.Table.extend_existing` or
- :paramref:`.Table.keep_existing` are not set, and the given name
- of the new :class:`.Table` refers to a :class:`.Table` that is
- already present in the target :class:`.MetaData` collection, and
- this :class:`.Table` specifies additional columns or other constructs
+ 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:`.Table`
- is specified that matches an existing :class:`.Table`, yet specifies
+ 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:`.Table.extend_existing`
+ :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:`.Table` before
+ of a listener function specific to this :class:`_schema.Table` before
the "autoload" process begins. Particularly useful for
the :meth:`.DDLEvents.column_reflect` event::
])
:param mustexist: When ``True``, indicates that this Table must already
- be present in the given :class:`.MetaData` collection, else
+ be present in the given :class:`_schema.MetaData` collection, else
an exception is raised.
:param prefixes:
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:`.MetaData` of this :class:`.Table` specifies its
- own :paramref:`.MetaData.schema` parameter, then that schema name will
- be applied to this :class:`.Table` if the schema parameter here is set
- to ``None``. To set a blank schema name on a :class:`.Table` that
- would otherwise use the schema set on the owning :class:`.MetaData`,
+ 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`.
.. versionadded:: 1.0.14 Added the :attr:`.BLANK_SCHEMA` symbol to
- allow a :class:`.Table` to have a blank schema name even when the
- parent :class:`.MetaData` specifies :paramref:`.MetaData.schema`.
+ allow a :class:`_schema.Table`
+ to have a blank schema name even when the
+ parent :class:`_schema.MetaData` specifies
+ :paramref:`_schema.MetaData.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
:param comment: Optional string that will render an SQL comment on table
creation.
- .. versionadded:: 1.2 Added the :paramref:`.Table.comment` parameter
- to :class:`.Table`.
+ .. 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>``.
metadata._remove_table(name, schema)
def __init__(self, *args, **kw):
- """Constructor for :class:`~.schema.Table`.
+ """Constructor for :class:`_schema.Table`.
This method is a no-op. See the top-level
- documentation for :class:`~.schema.Table`
+ documentation for :class:`_schema.Table`
for constructor arguments.
"""
@property
def foreign_key_constraints(self):
- """:class:`.ForeignKeyConstraint` objects referred to by this
- :class:`.Table`.
+ """:class:`_schema.ForeignKeyConstraint` objects referred to by this
+ :class:`_schema.Table`.
- This list is produced from the collection of :class:`.ForeignKey`
+ This list is produced from the collection of
+ :class:`_schema.ForeignKey`
objects currently associated.
.. versionadded:: 1.0.0
@property
def key(self):
- """Return the 'key' for this :class:`.Table`.
+ """Return the 'key' for this :class:`_schema.Table`.
This value is used as the dictionary key within the
- :attr:`.MetaData.tables` collection. It is typically the same
- as that of :attr:`.Table.name` for a table with no
- :attr:`.Table.schema` set; otherwise it is typically of the form
+ :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``.
"""
self._extra_dependencies.add(table)
def append_column(self, column):
- """Append a :class:`~.schema.Column` to this :class:`~.schema.Table`.
+ """Append a :class:`_schema.Column` to this :class:`_schema.Table`.
- The "key" of the newly added :class:`~.schema.Column`, i.e. the
+ 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
+ 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`
+ UPDATE, etc. statements generated from this :class:`_schema.Table`
construct.
Note that this does **not** change the definition of the table
column._set_parent_with_dispatch(self)
def append_constraint(self, constraint):
- """Append a :class:`~.schema.Constraint` to this
- :class:`~.schema.Table`.
+ """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.
+ :class:`_schema.Constraint` object.
Note that this does **not** produce the constraint within the
relational database automatically, for a table that already exists
@util.deprecated(
"1.4",
- "The :meth:`.Table.exists` method is deprecated and will be "
+ "The :meth:`_schema.Table.exists` method is deprecated and will be "
"removed in a future release. Please refer to "
- ":meth:`.Inspector.has_table`.",
+ ":meth:`_reflection.Inspector.has_table`.",
)
def exists(self, bind=None):
"""Return True if this table exists.
def create(self, bind=None, checkfirst=False):
"""Issue a ``CREATE`` statement for this
- :class:`.Table`, using the given :class:`.Connectable`
+ :class:`_schema.Table`, using the given :class:`.Connectable`
for connectivity.
.. seealso::
- :meth:`.MetaData.create_all`.
+ :meth:`_schema.MetaData.create_all`.
"""
def drop(self, bind=None, checkfirst=False):
"""Issue a ``DROP`` statement for this
- :class:`.Table`, using the given :class:`.Connectable`
+ :class:`_schema.Table`, using the given :class:`.Connectable`
for connectivity.
.. seealso::
- :meth:`.MetaData.drop_all`.
+ :meth:`_schema.MetaData.drop_all`.
"""
if bind is None:
referred_schema_fn=None,
name=None,
):
- """Return a copy of this :class:`.Table` associated with a different
- :class:`.MetaData`.
+ """Return a copy of this :class:`_schema.Table`
+ associated with a different
+ :class:`_schema.MetaData`.
E.g.::
m2 = MetaData()
user_copy = user.tometadata(m2)
- :param metadata: Target :class:`.MetaData` object, into which the
- new :class:`.Table` object will be created.
+ :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:`.Table`. If set to a string name, the new :class:`.Table`
+ :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:`.MetaData`, which is typically ``None`` as well, unless
+ :class:`_schema.MetaData`, which is typically ``None`` as well,
+ unless
set explicitly::
m2 = MetaData(schema='newschema')
: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:`.ForeignKeyConstraint`.
- The callable accepts this parent :class:`.Table`, the
+ 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:`.ForeignKeyConstraint` object, and the existing
+ :class:`_schema.ForeignKeyConstraint` object, and the existing
"target schema" of that constraint. The function should return the
string schema name that should be applied.
E.g.::
:param name: optional string name indicating the target table name.
If not specified or None, the table name is retained. This allows
- a :class:`.Table` to be copied to the same :class:`.MetaData` target
+ a :class:`_schema.Table` to be copied to the same
+ :class:`_schema.MetaData` target
with a new name.
.. versionadded:: 1.0.0
The name field may be omitted at construction time and applied
later, at any time before the Column is associated with a
- :class:`.Table`. This is to support convenient
+ :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
If the ``type`` is ``None`` or is omitted, it will first default to
the special type :class:`.NullType`. If and when this
- :class:`.Column` is made to refer to another column using
- :class:`.ForeignKey` and/or :class:`.ForeignKeyConstraint`, the type
+ :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:`.Column` object.
+ remote :class:`_schema.Column` object.
.. versionchanged:: 0.9.0
- Support for propagation of type to a :class:`.Column` from its
- :class:`.ForeignKey` object has been improved and should be
+ Support for propagation of type to a :class:`_schema.Column`
+ from its
+ :class:`_schema.ForeignKey` object has been improved and should be
more reliable and timely.
: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:`.ForeignKey`, :class:`.ColumnDefault`,
+ :class:`.Constraint`, :class:`_schema.ForeignKey`,
+ :class:`.ColumnDefault`,
:class:`.Sequence`, :class:`.Computed`. In some cases an
equivalent keyword argument is available such as ``server_default``,
``default`` and ``unique``.
(multi-column) primary keys, autoincrement is never implicitly
enabled; as always, ``autoincrement=True`` will allow for
at most one of those columns to be an "autoincrement" column.
- ``autoincrement=True`` may also be set on a :class:`.Column`
+ ``autoincrement=True`` may also be set on a
+ :class:`_schema.Column`
that has an explicit client-side or server-side default,
subject to limitations of the backend database and dialect.
* Part of the primary key
- * Not referring to another column via :class:`.ForeignKey`, unless
+ * Not referring to another column via :class:`_schema.ForeignKey`,
+ unless
the value is specified as ``'ignore_fk'``::
# turn on autoincrement for this column despite
:param default: A scalar, Python callable, or
- :class:`.ColumnElement` expression representing the
+ :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:`.Column.server_default`
+ Contrast this argument to
+ :paramref:`_schema.Column.server_default`
which creates a default generator on the database side.
.. seealso::
: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:`.Column.comment`
+ **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:`.Table`. When a key is provided,
+ ``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.
``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:`~.Column.primary_key` is also ``True``, in which case it
+ :paramref:`_schema.Column.primary_key` is also ``True``,
+ in which case it
defaults to ``False``. This parameter is only used when issuing
CREATE TABLE statements.
: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:`.Table` can be specified via an explicit
+ :class:`_schema.Table` can be specified via an explicit
:class:`.PrimaryKeyConstraint` object.
:param server_default: A :class:`.FetchedValue` instance, str, Unicode
:param comment: Optional string that will render an SQL comment on
table creation.
- .. versionadded:: 1.2 Added the :paramref:`.Column.comment`
- parameter to :class:`.Column`.
+ .. versionadded:: 1.2 Added the
+ :paramref:`_schema.Column.comment`
+ parameter to :class:`_schema.Column`.
"""
class ForeignKey(DialectKWArgs, SchemaItem):
"""Defines a dependency between two columns.
- ``ForeignKey`` is specified as an argument to a :class:`.Column` object,
+ ``ForeignKey`` is specified as an argument to a :class:`_schema.Column`
+ object,
e.g.::
t = Table("remote_table", metadata,
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:`.ForeignKeyConstraint`
+ 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:`.Column` which
- in turn is associated with a :class:`.Table`. Conversely,
- when :class:`.ForeignKeyConstraint` is applied to a :class:`.Table`,
+ 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:`.Column`, which are also
+ 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:`.ForeignKeyConstraint` object must be used, and applied
- to the :class:`.Table`. The associated ``ForeignKey`` objects
+ 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:`.Column` object are available in the `foreign_keys` collection
+ :class:`_schema.Column`
+ object are available in the `foreign_keys` collection
of that column.
Further examples of foreign key configuration are in
r"""
Construct a column-level FOREIGN KEY.
- The :class:`.ForeignKey` object when constructed generates a
- :class:`.ForeignKeyConstraint` which is associated with the parent
- :class:`.Table` object's collection of constraints.
+ 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:`.Column` object or a column name as a string:
+ :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
assigned ``key``.
:param use_alter: passed to the underlying
- :class:`.ForeignKeyConstraint` to indicate the constraint should
+ :class:`_schema.ForeignKeyConstraint`
+ to indicate the constraint should
be generated/dropped externally from the CREATE TABLE/ DROP TABLE
- statement. See :paramref:`.ForeignKeyConstraint.use_alter`
+ statement. See :paramref:`_schema.ForeignKeyConstraint.use_alter`
for further description.
.. seealso::
- :paramref:`.ForeignKeyConstraint.use_alter`
+ :paramref:`_schema.ForeignKeyConstraint.use_alter`
:ref:`use_alter`
: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:`.ForeignKeyConstraint`. See the documentation regarding
+ :class:`_schema.ForeignKeyConstraint`.
+ See the documentation regarding
an individual dialect at :ref:`dialect_toplevel` for detail on
documented arguments.
return "ForeignKey(%r)" % self._get_colspec()
def copy(self, schema=None):
- """Produce a copy of this :class:`.ForeignKey` object.
+ """Produce a copy of this :class:`_schema.ForeignKey` object.
- The new :class:`.ForeignKey` will not be bound
- to any :class:`.Column`.
+ The new :class:`_schema.ForeignKey` will not be bound
+ to any :class:`_schema.Column`.
This method is usually used by the internal
- copy procedures of :class:`.Column`, :class:`.Table`,
- and :class:`.MetaData`.
+ copy procedures of :class:`_schema.Column`, :class:`_schema.Table`,
+ and :class:`_schema.MetaData`.
- :param schema: The returned :class:`.ForeignKey` will
+ :param schema: The returned :class:`_schema.ForeignKey` will
reference the original table and column name, qualified
by the given string schema name.
def _get_colspec(self, schema=None, table_name=None):
"""Return a string based 'column specification' for this
- :class:`.ForeignKey`.
+ :class:`_schema.ForeignKey`.
This is usually the equivalent of the string-based "tablename.colname"
argument first passed to the object's constructor.
target_fullname = property(_get_colspec)
def references(self, table):
- """Return True if the given :class:`.Table` is referenced by this
- :class:`.ForeignKey`."""
+ """Return True if the given :class:`_schema.Table`
+ is referenced by this
+ :class:`_schema.ForeignKey`."""
return table.corresponding_column(self.column) is not None
def get_referent(self, table):
- """Return the :class:`.Column` in the given :class:`.Table`
- referenced by this :class:`.ForeignKey`.
+ """Return the :class:`_schema.Column` in the given
+ :class:`_schema.Table`
+ referenced by this :class:`_schema.ForeignKey`.
- Returns None if this :class:`.ForeignKey` does not reference the given
- :class:`.Table`.
+ Returns None if this :class:`_schema.ForeignKey`
+ does not reference the given
+ :class:`_schema.Table`.
"""
@util.memoized_property
def column(self):
- """Return the target :class:`.Column` referenced by this
- :class:`.ForeignKey`.
+ """Return the target :class:`_schema.Column` referenced by this
+ :class:`_schema.ForeignKey`.
If no target column has been established, an exception
is raised.
@util.deprecated_20(
":meth:`.DefaultGenerator.execute`",
alternative="All statement execution in SQLAlchemy 2.0 is performed "
- "by the :meth:`.Connection.execute` method of :class:`.Connection`, "
+ "by the :meth:`_engine.Connection.execute` method of "
+ ":class:`_engine.Connection`, "
"or in the ORM by the :meth:`.Session.execute` method of "
":class:`.Session`.",
)
:class:`.ColumnDefault` is generated automatically
whenever the ``default``, ``onupdate`` arguments of
- :class:`.Column` are used. A :class:`.ColumnDefault`
+ :class:`_schema.Column` are used. A :class:`.ColumnDefault`
can be passed positionally as well.
For example, the following::
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:`.ColumnElement`. The SQL expression will
+ :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
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:`.Connection` in use as well as the current
+ :class:`_engine.Connection` in use as well as the current
statement and parameters.
"""
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`
- or :class:`.Connection`, rendering the appropriate "next value" function
+ 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::
primary_key=True)
)
- When CREATE TABLE is emitted for the above :class:`.Table`, if the
+ 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.
: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:`.MetaData` is also present are the same
- as that of :paramref:`.Table.schema`.
+ 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
:param quote_schema: set the quoting preferences for the ``schema``
name.
- :param metadata: optional :class:`.MetaData` object which this
+ :param metadata: optional :class:`_schema.MetaData` object which this
:class:`.Sequence` will be associated with. A :class:`.Sequence`
- that is associated with a :class:`.MetaData` gains the following
+ that is associated with a :class:`_schema.MetaData`
+ gains the following
capabilities:
- * The :class:`.Sequence` will inherit the :paramref:`.MetaData.schema`
- parameter specified to the target :class:`.MetaData`, which
+ * 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:`.MetaData`
+ automatically use the engine bound to the :class:`_schema.MetaData`
object, if any.
- * The :meth:`.MetaData.create_all` and :meth:`.MetaData.drop_all`
+ * 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:`.Table` / :class:`.Column` that's a member of this
- :class:`.MetaData`.
+ :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:`.MetaData` via this parameter.
+ explicitly associated with the :class:`_schema.MetaData`
+ via this parameter.
.. seealso::
:paramref:`.Sequence.metadata` parameter.
:param for_update: Indicates this :class:`.Sequence`, when associated
- with a :class:`.Column`, should be invoked for UPDATE statements
+ 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.
:class:`.DefaultClause` is generated automatically
whenever the ``server_default``, ``server_onupdate`` arguments of
- :class:`.Column` are used. A :class:`.DefaultClause`
+ :class:`_schema.Column` are used. A :class:`.DefaultClause`
can be passed positionally as well.
For example, the following::
class ColumnCollectionMixin(object):
columns = None
- """A :class:`.ColumnCollection` of :class:`.Column` objects.
+ """A :class:`_expression.ColumnCollection` of :class:`_schema.Column`
+ objects.
This collection represents the columns which are referred to by
this object.
)
columns = None
- """A :class:`.ColumnCollection` representing the set of columns
+ """A :class:`_expression.ColumnCollection` representing the set of columns
for this constraint.
"""
"""Return True if this constraint contains the given column.
Note that this object also contains an attribute ``.columns``
- which is a :class:`.ColumnCollection` of :class:`.Column` objects.
+ which is a :class:`_expression.ColumnCollection` of
+ :class:`_schema.Column` objects.
"""
: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:`.text` object. If the textual
+ 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")
Defines a single column or composite FOREIGN KEY ... REFERENCES
constraint. For a no-frills, single column foreign key, adding a
- :class:`.ForeignKey` to the definition of a :class:`.Column` is a
+ :class:`_schema.ForeignKey` to the definition of a :class:`_schema.Column`
+ is a
shorthand equivalent for an unnamed, single column
- :class:`.ForeignKeyConstraint`.
+ :class:`_schema.ForeignKeyConstraint`.
Examples of foreign key configuration are in :ref:`metadata_foreignkeys`.
have been created, and drop it via an ALTER TABLE statement before
the full collection of tables are dropped.
- The use of :paramref:`.ForeignKeyConstraint.use_alter` is
+ 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:`.MetaData.create_all` and
- :meth:`.MetaData.drop_all` methods will perform this resolution
+ 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.
.. versionchanged:: 1.0.0 Automatic resolution of foreign key
cycles has been added, removing the need to use the
- :paramref:`.ForeignKeyConstraint.use_alter` in typical use
+ :paramref:`_schema.ForeignKeyConstraint.use_alter` in typical use
cases.
.. seealso::
self.elements.append(fk)
columns = None
- """A :class:`.ColumnCollection` representing the set of columns
+ """A :class:`_expression.ColumnCollection` representing the set of columns
for this constraint.
"""
elements = None
- """A sequence of :class:`.ForeignKey` objects.
+ """A sequence of :class:`_schema.ForeignKey` objects.
- Each :class:`.ForeignKey` represents a single referring column/referred
+ Each :class:`_schema.ForeignKey`
+ represents a single referring column/referred
column pair.
This collection is intended to be read-only.
@property
def referred_table(self):
- """The :class:`.Table` object to which this
- :class:`.ForeignKeyConstraint` references.
+ """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
@property
def column_keys(self):
"""Return a list of string keys representing the local
- columns in this :class:`.ForeignKeyConstraint`.
+ columns in this :class:`_schema.ForeignKeyConstraint`.
This list is either the original string arguments sent
- to the constructor of the :class:`.ForeignKeyConstraint`,
- or if the constraint has been initialized with :class:`.Column`
+ 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.
.. versionadded:: 1.0.0
"""A table-level PRIMARY KEY constraint.
The :class:`.PrimaryKeyConstraint` object is present automatically
- on any :class:`.Table` object; it is assigned a set of
- :class:`.Column` objects corresponding to those marked with
- the :paramref:`.Column.primary_key` flag::
+ 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),
primary_key=True, nullable=False)
)
- The primary key of a :class:`.Table` can also be specified by using
+ 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::
: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:`.Table` based on the
+ primary key column collection from the :class:`_schema.Table` based on the
flags::
my_table = Table('mytable', metadata,
.. versionadded:: 0.9.2 an empty :class:`.PrimaryKeyConstraint` may now
be specified for the purposes of establishing keyword arguments with
the constraint, independently of the specification of "primary key"
- columns within the :class:`.Table` itself; columns marked as
+ columns within the :class:`_schema.Table` itself; columns marked as
``primary_key=True`` will be gathered into the empty constraint's
column collection.
This is basically like putting a whole new
:class:`.PrimaryKeyConstraint` object on the parent
- :class:`.Table` object without actually replacing the object.
+ :class:`_schema.Table` object without actually replacing the object.
The ordering of the given list of columns is also maintained; these
columns will be appended to the list of columns after any which
Index("some_index", sometable.c.name)
For a no-frills, single column index, adding
- :class:`.Column` also supports ``index=True``::
+ :class:`_schema.Column` also supports ``index=True``::
sometable = Table("sometable", metadata,
Column("name", String(50), index=True)
Functional indexes are supported as well, typically by using the
:data:`.func` construct in conjunction with table-bound
- :class:`.Column` objects::
+ :class:`_schema.Column` objects::
Index("some_index", func.lower(sometable.c.name))
- An :class:`.Index` can also be manually associated with a :class:`.Table`,
+ An :class:`.Index` can also be manually associated with a
+ :class:`_schema.Table`,
either through inline declaration or using
- :meth:`.Table.append_constraint`. When this approach is used, the names
+ :meth:`_schema.Table.append_constraint`. When this approach is used,
+ the names
of the indexed columns can be specified as strings::
Table("sometable", metadata,
)
To support functional or expression-based indexes in this form, the
- :func:`.text` construct may be used::
+ :func:`_expression.text` construct may be used::
from sqlalchemy import text
Index("some_index", text("lower(name)"))
)
- .. versionadded:: 0.9.5 the :func:`.text` construct may be used to
+ .. versionadded:: 0.9.5 the :func:`_expression.text`
+ construct may be used to
specify :class:`.Index` expressions, provided the :class:`.Index`
- is explicitly associated with the :class:`.Table`.
+ is explicitly associated with the :class:`_schema.Table`.
.. seealso::
:param \*expressions:
Column expressions to include in the index. The expressions
- are normally instances of :class:`.Column`, but may also
+ are normally instances of :class:`_schema.Column`, but may also
be arbitrary SQL expressions which ultimately refer to a
- :class:`.Column`.
+ :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:`.Column.quote`.
+ :paramref:`_schema.Column.quote`.
:param info=None: Optional data dictionary which will be populated
into the :attr:`.SchemaItem.info` attribute of this object.
.. seealso::
- :meth:`.MetaData.create_all`.
+ :meth:`_schema.MetaData.create_all`.
"""
if bind is None:
.. seealso::
- :meth:`.MetaData.drop_all`.
+ :meth:`_schema.MetaData.drop_all`.
"""
if bind is None:
class MetaData(SchemaItem):
- """A collection of :class:`.Table` objects and their associated schema
+ """A collection of :class:`_schema.Table`
+ objects and their associated schema
constructs.
- Holds a collection of :class:`.Table` objects as well as
- an optional binding to an :class:`.Engine` or
- :class:`.Connection`. If bound, the :class:`.Table` objects
+ 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:`.Table` objects themselves are stored in the
- :attr:`.MetaData.tables` dictionary.
+ The :class:`_schema.Table` objects themselves are stored in the
+ :attr:`_schema.MetaData.tables` dictionary.
- :class:`.MetaData` is a thread-safe object for read operations.
- Construction of new tables within a single :class:`.MetaData` object,
+ :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::
Defaults to False. ``bind`` is required when this option is set.
:param schema:
- The default schema to use for the :class:`.Table`,
+ The default schema to use for the :class:`_schema.Table`,
:class:`.Sequence`, and potentially other objects associated with
- this :class:`.MetaData`. Defaults to ``None``.
+ this :class:`_schema.MetaData`. Defaults to ``None``.
- When this value is set, any :class:`.Table` or :class:`.Sequence`
+ When this value is set, any :class:`_schema.Table` or
+ :class:`.Sequence`
which specifies ``None`` for the schema parameter will instead
- have this schema name defined. To build a :class:`.Table`
+ have this schema name defined. To build a :class:`_schema.Table`
or :class:`.Sequence` that still has ``None`` for the schema
even when this parameter is present, use the :attr:`.BLANK_SCHEMA`
symbol.
.. note::
- As referred above, the :paramref:`.MetaData.schema` parameter
+ As referred above, the :paramref:`_schema.MetaData.schema`
+ parameter
only refers to the **default value** that will be applied to
- the :paramref:`.Table.schema` parameter of an incoming
- :class:`.Table` object. It does not refer to how the
- :class:`.Table` is catalogued within the :class:`.MetaData`,
- which remains consistent vs. a :class:`.MetaData` collection
- that does not define this parameter. The :class:`.Table`
- within the :class:`.MetaData` will still be keyed based on its
+ the :paramref:`_schema.Table.schema` parameter of an incoming
+ :class:`_schema.Table` object. It does not refer to how the
+ :class:`_schema.Table` is catalogued within the
+ :class:`_schema.MetaData`,
+ which remains consistent vs. a :class:`_schema.MetaData`
+ collection
+ that does not define this parameter. The
+ :class:`_schema.Table`
+ within the :class:`_schema.MetaData`
+ will still be keyed based on its
schema-qualified name, e.g.
``my_metadata.tables["some_schema.my_table"]``.
- The current behavior of the :class:`.ForeignKey` object is to
+ The current behavior of the :class:`_schema.ForeignKey`
+ object is to
circumvent this restriction, where it can locate a table given
the table name alone, where the schema will be assumed to be
present from this value as specified on the owning
- :class:`.MetaData` collection. However, this implies that a
+ :class:`_schema.MetaData` collection. However,
+ this implies that a
table qualified with BLANK_SCHEMA cannot currently be referred
- to by string name from :class:`.ForeignKey`. Other parts of
+ to by string name from :class:`_schema.ForeignKey`.
+ Other parts of
SQLAlchemy such as Declarative may not have similar behaviors
built in, however may do so in a future release, along with a
consistent method of referring to a table in BLANK_SCHEMA.
.. seealso::
- :paramref:`.Table.schema`
+ :paramref:`_schema.Table.schema`
:paramref:`.Sequence.schema`
:param quote_schema:
- Sets the ``quote_schema`` flag for those :class:`.Table`,
+ Sets the ``quote_schema`` flag for those :class:`_schema.Table`,
:class:`.Sequence`, and other objects which make usage of the
local ``schema`` name.
The keys of this dictionary may be:
* a constraint or Index class, e.g. the :class:`.UniqueConstraint`,
- :class:`.ForeignKeyConstraint` class, the :class:`.Index` class
+ :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,
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:`.Table` as arguments, returning a string
+ 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:`.Table` object
+ * ``%(table_name)s`` - the name of the :class:`_schema.Table`
+ object
associated with the constraint.
- * ``%(referred_table_name)s`` - the name of the :class:`.Table`
+ * ``%(referred_table_name)s`` - the name of the
+ :class:`_schema.Table`
object associated with the referencing target of a
- :class:`.ForeignKeyConstraint`.
+ :class:`_schema.ForeignKeyConstraint`.
- * ``%(column_0_name)s`` - the name of the :class:`.Column` at
+ * ``%(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:`.Column`
+ * ``%(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:`.Column`
+ * ``%(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:`.Column` or all :class:`.Columns`, separated with
+ :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:`.Column` or all :class:`.Columns`, separated with
+ :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:`.ForeignKeyConstraint`.
+ 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
self.bind = bind
tables = None
- """A dictionary of :class:`.Table` objects keyed to their name or "table key".
-
- The exact key is that determined by the :attr:`.Table.key` attribute;
- for a table with no :attr:`.Table.schema` attribute, this is the same
- as :attr:`.Table.name`. For a table with a schema, it is typically of the
+ """A dictionary of :class:`_schema.Table`
+ objects keyed to their name or "table key".
+
+ The exact key is that determined by the :attr:`_schema.Table.key`
+ attribute;
+ for a table with no :attr:`_schema.Table.schema` attribute,
+ this is the same
+ as :attr:`_schema.Table.name`. For a table with a schema,
+ it is typically of the
form ``schemaname.tablename``.
.. seealso::
- :attr:`.MetaData.sorted_tables`
+ :attr:`_schema.MetaData.sorted_tables`
"""
return self._bind is not None
def bind(self):
- """An :class:`.Engine` or :class:`.Connection` to which this
- :class:`.MetaData` is bound.
+ """An :class:`_engine.Engine` or :class:`_engine.Connection`
+ to which this
+ :class:`_schema.MetaData` is bound.
- Typically, a :class:`.Engine` is assigned to this attribute
+ Typically, a :class:`_engine.Engine` is assigned to this attribute
so that "implicit execution" may be used, or alternatively
as a means of providing engine binding information to an
ORM :class:`.Session` object::
@property
def sorted_tables(self):
- """Returns a list of :class:`.Table` objects sorted in order of
+ """Returns a list of :class:`_schema.Table` objects sorted in order of
foreign key dependency.
- The sorting will place :class:`.Table` objects that have dependencies
+ 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.
automatic resolution of dependency cycles between tables, which
are usually caused by mutually dependent foreign key constraints.
To resolve these cycles, either the
- :paramref:`.ForeignKeyConstraint.use_alter` parameter may be
+ :paramref:`_schema.ForeignKeyConstraint.use_alter`
+ parameter may be
applied to those constraints, or use the
- :func:`.schema.sort_tables_and_constraints` function which will
+ :func:`_schema.sort_tables_and_constraints` function which will
break out foreign key constraints involved in cycles separately.
.. seealso::
- :func:`.schema.sort_tables`
+ :func:`_schema.sort_tables`
- :func:`.schema.sort_tables_and_constraints`
+ :func:`_schema.sort_tables_and_constraints`
- :attr:`.MetaData.tables`
+ :attr:`_schema.MetaData.tables`
- :meth:`.Inspector.get_table_names`
+ :meth:`_reflection.Inspector.get_table_names`
- :meth:`.Inspector.get_sorted_table_and_fkc_names`
+ :meth:`_reflection.Inspector.get_sorted_table_and_fkc_names`
"""
:param schema:
Optional, query and reflect tables from an alternate schema.
- If None, the schema associated with this :class:`.MetaData`
+ If None, the schema associated with this :class:`_schema.MetaData`
is used, if any.
:param views:
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:`.Table` as
- :paramref:`.Table.extend_existing`.
+ :param extend_existing: Passed along to each :class:`_schema.Table` as
+ :paramref:`_schema.Table.extend_existing`.
.. versionadded:: 0.9.1
- :param autoload_replace: Passed along to each :class:`.Table` as
- :paramref:`.Table.autoload_replace`.
+ :param autoload_replace: Passed along to each :class:`_schema.Table`
+ as
+ :paramref:`_schema.Table.autoload_replace`.
.. versionadded:: 0.9.1
- :param resolve_fks: if True, reflect :class:`.Table` objects linked
- to :class:`.ForeignKey` objects located in each :class:`.Table`.
- For :meth:`.MetaData.reflect`, this has the effect of reflecting
+ :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:`.ForeignKey` objects are not followed to the :class:`.Table`
+ :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:`.ForeignKey` object will still resolve to its related
- :class:`.Table` after the :meth:`.MetaData.reflect` operation is
+ :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:`.Table.resolve_fks`
+ :paramref:`_schema.Table.resolve_fks`
:param \**dialect_kwargs: Additional keyword arguments not mentioned
above are dialect specific, and passed in the form
.. versionadded:: 0.9.2 - Added
:paramref:`.MetaData.reflect.**dialect_kwargs` to support
- dialect-level reflection options for all :class:`.Table`
+ dialect-level reflection options for all :class:`_schema.Table`
objects reflected.
"""
"""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:`.Column` object::
+ argument list of a :class:`_schema.Column` object::
from sqlalchemy import Computed
)
def __init__(self, sqltext, persisted=None):
"""Construct a GENERATED ALWAYS AS DDL construct to accompany a
- :class:`.Column`.
+ :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:`.text`
+ 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:`.text` object.
+ :func:`_expression.text` object.
:param persisted:
Optional, controls how this column should be persisted by the
# This module is part of SQLAlchemy and is released under
# the MIT License: http://www.opensource.org/licenses/mit-license.php
-"""The :class:`.FromClause` class of SQL expression elements, representing
+"""The :class:`_expression.FromClause` class of SQL expression elements,
+representing
SQL tables and derived rowsets.
"""
)
def subquery(alias, *args, **kwargs):
r"""Return an :class:`.Subquery` object derived
- from a :class:`.Select`.
+ from a :class:`_expression.Select`.
:param name: the alias name for the subquery
:param \*args, \**kwargs: all other arguments are passed through to the
- :func:`~.sql.expression.select` function.
+ :func:`_expression.select` function.
"""
return Select(*args, **kwargs).subquery(alias)
def _exported_columns_iterator(self):
"""An iterator of column objects that represents the "exported"
- columns of this :class:`.ReturnsRows`.
+ columns of this :class:`_expression.ReturnsRows`.
This is the same set of columns as are returned by
- :meth:`.ReturnsRows.exported_columns` except they are returned
+ :meth:`_expression.ReturnsRows.exported_columns`
+ except they are returned
as a simple iterator or sequence, rather than as a
- :class:`.ColumnCollection` namespace.
+ :class:`_expression.ColumnCollection` namespace.
Subclasses should re-implement this method to bypass the interim
- creation of the :class:`.ColumnCollection` if appropriate.
+ creation of the :class:`_expression.ColumnCollection` if appropriate.
"""
return iter(self.exported_columns)
@property
def exported_columns(self):
- """A :class:`.ColumnCollection` that represents the "exported"
- columns of this :class:`.ReturnsRows`.
+ """A :class:`_expression.ColumnCollection`
+ that represents the "exported"
+ columns of this :class:`_expression.ReturnsRows`.
The "exported" columns represent the collection of
- :class:`.ColumnElement` expressions that are rendered by this SQL
+ :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
.. seealso:
- :attr:`.FromClause.exported_columns`
+ :attr:`_expression.FromClause.exported_columns`
- :attr:`.SelectBase.exported_columns`
+ :attr:`_expression.SelectBase.exported_columns`
"""
raise NotImplementedError()
raise NotImplementedError()
def lateral(self, name=None):
- """Return a LATERAL alias of this :class:`.Selectable`.
+ """Return a LATERAL alias of this :class:`expression.Selectable`.
- The return value is the :class:`.Lateral` construct also
- provided by the top-level :func:`~.expression.lateral` function.
+ The return value is the :class:`_expression.Lateral` construct also
+ provided by the top-level :func:`_expression.lateral` function.
.. versionadded:: 1.1
@util.preload_module("sqlalchemy.sql.util")
def replace_selectable(self, old, alias):
"""replace all occurrences of FromClause 'old' with the given Alias
- object, returning a copy of this :class:`.FromClause`.
+ object, returning a copy of this :class:`_expression.FromClause`.
"""
return util.preloaded.sql_util.ClauseAdapter(alias).traverse(self)
def corresponding_column(self, column, require_embedded=False):
- """Given a :class:`.ColumnElement`, return the exported
- :class:`.ColumnElement` object from the
- :attr:`.Selectable.exported_columns`
- collection of this :class:`.Selectable` which corresponds to that
- original :class:`.ColumnElement` via a common ancestor
+ """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:`.ColumnElement` to be matched
+ :param column: the target :class:`_expression.ColumnElement`
+ to be matched
:param require_embedded: only return corresponding columns for
- the given :class:`.ColumnElement`, if the given
- :class:`.ColumnElement` is actually present within a sub-element
- of this :class:`.Selectable`. Normally the column will match if
+ 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:`.Selectable`.
+ columns of this :class:`expression.Selectable`.
.. seealso::
- :attr:`.Selectable.exported_columns` - the
- :class:`.ColumnCollection` that is used for the operation
+ :attr:`expression.Selectable.exported_columns` - the
+ :class:`_expression.ColumnCollection`
+ that is used for the operation
- :meth:`.ColumnCollection.corresponding_column` - implementation
+ :meth:`_expression.ColumnCollection.corresponding_column`
+ - implementation
method.
"""
@_generative
@_document_text_coercion(
"expr",
- ":meth:`.HasPrefixes.prefix_with`",
+ ":meth:`_expression.HasPrefixes.prefix_with`",
":paramref:`.HasPrefixes.prefix_with.*expr`",
)
def prefix_with(self, *expr, **kw):
"/*+ BKA(t1) */", dialect="mysql")
Multiple prefixes can be specified by multiple calls
- to :meth:`.prefix_with`.
+ to :meth:`_expression.HasPrefixes.prefix_with`.
- :param \*expr: textual or :class:`.ClauseElement` construct which
+ :param \*expr: textual or :class:`_expression.ClauseElement`
+ construct which
will be rendered following the INSERT, UPDATE, or DELETE
keyword.
:param \**kw: A single keyword 'dialect' is accepted. This is an
@_generative
@_document_text_coercion(
"expr",
- ":meth:`.HasSuffixes.suffix_with`",
+ ":meth:`_expression.HasSuffixes.suffix_with`",
":paramref:`.HasSuffixes.suffix_with.*expr`",
)
def suffix_with(self, *expr, **kw):
"cycle empno set y_cycle to 1 default 0", dialect="oracle")
Multiple suffixes can be specified by multiple calls
- to :meth:`.suffix_with`.
+ to :meth:`_expression.HasSuffixes.suffix_with`.
- :param \*expr: textual or :class:`.ClauseElement` construct which
+ :param \*expr: textual or :class:`_expression.ClauseElement`
+ construct which
will be rendered following the target clause.
:param \**kw: A single keyword 'dialect' is accepted. This is an
optional string dialect name which will
"""Represent an element that can be used within the ``FROM``
clause of a ``SELECT`` statement.
- The most common forms of :class:`.FromClause` are the
- :class:`.Table` and the :func:`~.sql.expression.select` constructs. Key
- features common to all :class:`.FromClause` objects include:
+ 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:`.ColumnElement` objects.
+ of :class:`_expression.ColumnElement` objects.
* a :attr:`.primary_key` attribute, which is a collection of all those
- :class:`.ColumnElement` objects that indicate the ``primary_key`` flag.
+ :class:`_expression.ColumnElement`
+ objects that indicate the ``primary_key`` flag.
* Methods to generate various derivations of a "from" clause, including
- :meth:`.FromClause.alias`, :meth:`.FromClause.join`,
- :meth:`.FromClause.select`.
+ :meth:`_expression.FromClause.alias`,
+ :meth:`_expression.FromClause.join`,
+ :meth:`_expression.FromClause.select`.
"""
_hide_froms = []
schema = None
- """Define the 'schema' attribute for this :class:`.FromClause`.
+ """Define the 'schema' attribute for this :class:`_expression.FromClause`.
This is typically ``None`` for most objects except that of
- :class:`.Table`, where it is taken as the value of the
- :paramref:`.Table.schema` argument.
+ :class:`_schema.Table`, where it is taken as the value of the
+ :paramref:`_schema.Table.schema` argument.
"""
_use_schema_map = False
def select(self, whereclause=None, **params):
- """return a SELECT of this :class:`.FromClause`.
+ """return a SELECT of this :class:`_expression.FromClause`.
.. seealso::
- :func:`~.sql.expression.select` - general purpose
+ :func:`_expression.select` - general purpose
method which allows for arbitrary column lists.
"""
return Select([self], whereclause, **params)
def join(self, right, onclause=None, isouter=False, full=False):
- """Return a :class:`.Join` from this :class:`.FromClause`
+ """Return a :class:`_expression.Join` from this
+ :class:`_expression.FromClause`
to another :class:`FromClause`.
E.g.::
JOIN address ON user.id = address.user_id
:param right: the right side of the join; this is any
- :class:`.FromClause` object such as a :class:`.Table` object, and
+ :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:`.FromClause.join` will attempt to
+ 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.
.. seealso::
- :func:`.join` - standalone function
+ :func:`_expression.join` - standalone function
- :class:`.Join` - the type of object produced
+ :class:`_expression.Join` - the type of object produced
"""
return Join(self, right, onclause, isouter, full)
def outerjoin(self, right, onclause=None, full=False):
- """Return a :class:`.Join` from this :class:`.FromClause`
+ """Return a :class:`_expression.Join` from this
+ :class:`_expression.FromClause`
to another :class:`FromClause`, with the "isouter" flag set to
True.
isouter=True)
:param right: the right side of the join; this is any
- :class:`.FromClause` object such as a :class:`.Table` object, and
+ :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:`.FromClause.join` will attempt to
+ 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
.. seealso::
- :meth:`.FromClause.join`
+ :meth:`_expression.FromClause.join`
- :class:`.Join`
+ :class:`_expression.Join`
"""
return Join(self, right, onclause, True, full)
def alias(self, name=None, flat=False):
- """return an alias of this :class:`.FromClause`.
+ """return an alias of this :class:`_expression.FromClause`.
E.g.::
a2 = some_table.alias('a2')
- The above code creates an :class:`.Alias` object which can be used
+ The above code creates an :class:`_expression.Alias`
+ object which can be used
as a FROM clause in any SELECT statement.
.. seealso::
:ref:`core_tutorial_aliases`
- :func:`~.expression.alias`
+ :func:`_expression.alias`
"""
return Alias._construct(self, name)
def tablesample(self, sampling, name=None, seed=None):
- """Return a TABLESAMPLE alias of this :class:`.FromClause`.
+ """Return a TABLESAMPLE alias of this :class:`_expression.FromClause`.
- The return value is the :class:`.TableSample` construct also
- provided by the top-level :func:`~.expression.tablesample` function.
+ The return value is the :class:`_expression.TableSample`
+ construct also
+ provided by the top-level :func:`_expression.tablesample` function.
.. versionadded:: 1.1
.. seealso::
- :func:`~.expression.tablesample` - usage guidelines and parameters
+ :func:`_expression.tablesample` - usage guidelines and parameters
"""
return TableSample._construct(self, sampling, name, seed)
@property
def exported_columns(self):
- """A :class:`.ColumnCollection` that represents the "exported"
- columns of this :class:`.Selectable`.
+ """A :class:`_expression.ColumnCollection`
+ that represents the "exported"
+ columns of this :class:`expression.Selectable`.
- The "exported" columns for a :class:`.FromClause` object are synonymous
- with the :attr:`.FromClause.columns` collection.
+ The "exported" columns for a :class:`_expression.FromClause`
+ object are synonymous
+ with the :attr:`_expression.FromClause.columns` collection.
.. versionadded:: 1.4
.. seealso:
- :attr:`.Selectable.exported_columns`
+ :attr:`expression.Selectable.exported_columns`
- :attr:`.SelectBase.exported_columns`
+ :attr:`_expression.SelectBase.exported_columns`
"""
@util.memoized_property
def columns(self):
- """A named-based collection of :class:`.ColumnElement` objects
- maintained by this :class:`.FromClause`.
+ """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
class Join(FromClause):
- """represent a ``JOIN`` construct between two :class:`.FromClause`
+ """represent a ``JOIN`` construct between two
+ :class:`_expression.FromClause`
elements.
- The public constructor function for :class:`.Join` is the module-level
- :func:`.join()` function, as well as the :meth:`.FromClause.join` method
- of any :class:`.FromClause` (e.g. such as :class:`.Table`).
+ 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:`.join`
+ :func:`_expression.join`
- :meth:`.FromClause.join`
+ :meth:`_expression.FromClause.join`
"""
_is_join = True
def __init__(self, left, right, onclause=None, isouter=False, full=False):
- """Construct a new :class:`.Join`.
+ """Construct a new :class:`_expression.Join`.
- The usual entrypoint here is the :func:`~.expression.join`
- function or the :meth:`.FromClause.join` method of any
- :class:`.FromClause` object.
+ The usual entrypoint here is the :func:`_expression.join`
+ function or the :meth:`_expression.FromClause.join` method of any
+ :class:`_expression.FromClause` object.
"""
self.left = coercions.expect(roles.FromClauseRole, left)
def _create_outerjoin(cls, left, right, onclause=None, full=False):
"""Return an ``OUTER JOIN`` clause element.
- The returned object is an instance of :class:`.Join`.
+ The returned object is an instance of :class:`_expression.Join`.
Similar functionality is also available via the
- :meth:`~.FromClause.outerjoin()` method on any
- :class:`.FromClause`.
+ :meth:`_expression.FromClause.outerjoin()` method on any
+ :class:`_expression.FromClause`.
:param left: The left side of the join.
derived from foreign key relationships established between
left and right otherwise.
- To chain joins together, use the :meth:`.FromClause.join` or
- :meth:`.FromClause.outerjoin` methods on the resulting
- :class:`.Join` object.
+ To chain joins together, use the :meth:`_expression.FromClause.join`
+ or
+ :meth:`_expression.FromClause.outerjoin` methods on the resulting
+ :class:`_expression.Join` object.
"""
return cls(left, right, onclause, isouter=True, full=full)
def _create_join(
cls, left, right, onclause=None, isouter=False, full=False
):
- """Produce a :class:`.Join` object, given two :class:`.FromClause`
+ """Produce a :class:`_expression.Join` object, given two
+ :class:`_expression.FromClause`
expressions.
E.g.::
JOIN address ON user.id = address.user_id
Similar functionality is available given any
- :class:`.FromClause` object (e.g. such as a :class:`.Table`) using
- the :meth:`.FromClause.join` method.
+ :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:`.FromClause` object such as a :class:`.Table` object, and
+ :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:`.FromClause.join` will attempt to
+ 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.
.. seealso::
- :meth:`.FromClause.join` - method form, based on a given left side
+ :meth:`_expression.FromClause.join` - method form,
+ based on a given left side
- :class:`.Join` - the type of object produced
+ :class:`_expression.Join` - the type of object produced
"""
)
def select(self, whereclause=None, **kwargs):
- r"""Create a :class:`.Select` from this :class:`.Join`.
+ r"""Create a :class:`_expression.Select` from this
+ :class:`_expression.Join`.
- The equivalent long-hand form, given a :class:`.Join` object
+ The equivalent long-hand form, given a :class:`_expression.Join`
+ object
``j``, is::
from sqlalchemy import select
@util.preload_module("sqlalchemy.sql.util")
def alias(self, name=None, flat=False):
- r"""return an alias of this :class:`.Join`.
+ r"""return an alias of this :class:`_expression.Join`.
The default behavior here is to first produce a SELECT
- construct from this :class:`.Join`, then to produce an
- :class:`.Alias` from that. So given a join of the form::
+ construct from this :class:`_expression.Join`, then to produce an
+ :class:`_expression.Alias` from that. So given a join of the form::
j = table_a.join(table_b, table_a.c.id == table_b.c.a_id)
FROM table_a
JOIN table_b ON table_a.id = table_b.a_id) AS anon_1
- The equivalent long-hand form, given a :class:`.Join` object
+ The equivalent long-hand form, given a :class:`_expression.Join`
+ object
``j``, is::
from sqlalchemy import select, alias
name=name
)
- The selectable produced by :meth:`.Join.alias` features the same
+ The selectable produced by :meth:`_expression.Join.alias`
+ features the same
columns as that of the two individual selectables presented under
a single name - the individual columns are "auto-labeled", meaning
- the ``.c.`` collection of the resulting :class:`.Alias` represents
+ the ``.c.`` collection of the resulting :class:`_expression.Alias`
+ represents
the names of the individual columns using a
``<tablename>_<columname>`` scheme::
j.c.table_a_id
j.c.table_b_a_id
- :meth:`.Join.alias` also features an alternate
+ :meth:`_expression.Join.alias` also features an alternate
option for aliasing joins which produces no enclosing SELECT and
does not normally apply labels to the column names. The
- ``flat=True`` option will call :meth:`.FromClause.alias`
+ ``flat=True`` option will call :meth:`_expression.FromClause.alias`
against the left and right sides individually.
Using this option, no new ``SELECT`` is produced;
we instead, from a construct as below::
ON table_b_1.id = table_c_1.b_id
) ON table_a_1.id = table_b_1.a_id
- The standalone :func:`~.expression.alias` function as well as the
- base :meth:`.FromClause.alias` method also support the ``flat=True``
+ The standalone :func:`_expression.alias` function as well as the
+ base :meth:`_expression.FromClause.alias`
+ method also support the ``flat=True``
argument as a no-op, so that the argument can be passed to the
``alias()`` method of any selectable.
:param name: name given to the alias.
:param flat: if True, produce an alias of the left and right
- sides of this :class:`.Join` and return the join of those
+ sides of this :class:`_expression.Join` and return the join of those
two selectables. This produces join expression that does not
include an enclosing SELECT.
:ref:`core_tutorial_aliases`
- :func:`~.expression.alias`
+ :func:`_expression.alias`
"""
sqlutil = util.preloaded.sql_util
sub-select within a SQL statement using the ``AS`` keyword (or
without the keyword on certain databases such as Oracle).
- This object is constructed from the :func:`~.expression.alias` module
- level function as well as the :meth:`.FromClause.alias` method available
- on all :class:`.FromClause` subclasses.
+ 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:`.FromClause.alias`
+ :meth:`_expression.FromClause.alias`
"""
@classmethod
def _factory(cls, selectable, name=None, flat=False):
- """Return an :class:`.Alias` object.
+ """Return an :class:`_expression.Alias` object.
- An :class:`.Alias` represents any :class:`.FromClause`
+ An :class:`_expression.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``.
- Similar functionality is available via the :meth:`~.FromClause.alias`
- method available on all :class:`.FromClause` subclasses. In terms of
- a SELECT object as generated from the :func:`~.sql.expression.select`
- function, the :meth:`.SelectBase.alias` method returns an
- :class:`.Alias` or similar object which represents a named,
+ Similar functionality is available via the
+ :meth:`_expression.FromClause.alias`
+ method available on all :class:`_expression.FromClause` subclasses.
+ In terms of
+ a SELECT object as generated from the :func:`_expression.select`
+ function, the :meth:`_expression.SelectBase.alias` method returns an
+ :class:`_expression.Alias` or similar object which represents a named,
parenthesized subquery.
- When an :class:`.Alias` is created from a :class:`.Table` object,
+ When an :class:`_expression.Alias` is created from a
+ :class:`_schema.Table` object,
this has the effect of the table being rendered
as ``tablename AS aliasname`` in a SELECT statement.
- For :func:`~.sql.expression.select` objects, the effect is that of
+ For :func:`_expression.select` objects, the effect is that of
creating a named subquery, i.e. ``(select ...) AS aliasname``.
The ``name`` parameter is optional, and provides the name
same name for each successive compilation of the same statement
object.
- :param selectable: any :class:`.FromClause` subclass,
+ :param selectable: any :class:`_expression.FromClause` subclass,
such as a table, select statement, etc.
:param name: string name to be assigned as the alias.
at compile time.
:param flat: Will be passed through to if the given selectable
- is an instance of :class:`.Join` - see :meth:`.Join.alias`
+ is an instance of :class:`_expression.Join` - see
+ :meth:`_expression.Join.alias`
for details.
"""
class Lateral(AliasedReturnsRows):
"""Represent a LATERAL subquery.
- This object is constructed from the :func:`~.expression.lateral` module
- level function as well as the :meth:`.FromClause.lateral` method available
- on all :class:`.FromClause` subclasses.
+ 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.
@classmethod
def _factory(cls, selectable, name=None):
- """Return a :class:`.Lateral` object.
+ """Return a :class:`_expression.Lateral` object.
- :class:`.Lateral` is an :class:`.Alias` subclass that represents
+ :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
class TableSample(AliasedReturnsRows):
"""Represent a TABLESAMPLE clause.
- This object is constructed from the :func:`~.expression.tablesample` module
- level function as well as the :meth:`.FromClause.tablesample` method
- available on all :class:`.FromClause` subclasses.
+ 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.
.. versionadded:: 1.1
.. seealso::
- :func:`~.expression.tablesample`
+ :func:`_expression.tablesample`
"""
@classmethod
def _factory(cls, selectable, sampling, name=None, seed=None):
- """Return a :class:`.TableSample` object.
+ """Return a :class:`_expression.TableSample` object.
- :class:`.TableSample` is an :class:`.Alias` subclass that represents
+ :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:`.FromClause` class via the
- :meth:`.FromClause.tablesample` method.
+ :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,
.. versionadded:: 1.1
:param sampling: a ``float`` percentage between 0 and 100 or
- :class:`.functions.Function`.
+ :class:`_functions.Function`.
:param name: optional alias name
class CTE(Generative, HasPrefixes, HasSuffixes, AliasedReturnsRows):
"""Represent a Common Table Expression.
- The :class:`.CTE` object is obtained using the
- :meth:`.SelectBase.cte` method from any selectable.
+ The :class:`_expression.CTE` object is obtained using the
+ :meth:`_expression.SelectBase.cte` method from any selectable.
See that method for complete examples.
"""
@classmethod
def _factory(cls, selectable, name=None, recursive=False):
- r"""Return a new :class:`.CTE`, or Common Table Expression instance.
+ r"""Return a new :class:`_expression.CTE`,
+ or Common Table Expression instance.
- Please see :meth:`.HasCte.cte` for detail on CTE usage.
+ Please see :meth:`_expression.HasCTE.cte` for detail on CTE usage.
"""
return coercions.expect(roles.HasCTERole, selectable).cte(
super(CTE, self)._init(selectable, name=name)
def alias(self, name=None, flat=False):
- """Return an :class:`.Alias` of this :class:`.CTE`.
+ """Return an :class:`_expression.Alias` of this
+ :class:`_expression.CTE`.
This method is a CTE-specific specialization of the
- :class:`.FromClause.alias` method.
+ :class:`_expression.FromClause.alias` method.
.. seealso::
:ref:`core_tutorial_aliases`
- :func:`~.expression.alias`
+ :func:`_expression.alias`
"""
return CTE._construct(
"""
def cte(self, name=None, recursive=False):
- r"""Return a new :class:`.CTE`, or Common Table Expression instance.
+ r"""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
.. versionchanged:: 1.1 Added support for UPDATE/INSERT/DELETE as
CTE, CTEs added to UPDATE/INSERT/DELETE.
- SQLAlchemy detects :class:`.CTE` objects, which are treated
- similarly to :class:`.Alias` objects, as special elements
+ 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:`.CTE.prefix_with` method may be
+ "NOT MATERIALIZED", the :meth:`_expression.CTE.prefix_with`
+ method may be
used to establish these.
.. versionchanged:: 1.3.13 Added support for prefixes.
.. seealso::
:meth:`.orm.query.Query.cte` - ORM version of
- :meth:`.HasCTE.cte`.
+ :meth:`_expression.HasCTE.cte`.
"""
return CTE._construct(self, name=name, recursive=recursive)
"""Represent a subquery of a SELECT.
A :class:`.Subquery` is created by invoking the
- :meth:`.SelectBase.subquery` method, or for convenience the
- :class:`.SelectBase.alias` method, on any :class:`.SelectBase` subclass
- which includes :class:`.Select`, :class:`.CompoundSelect`, and
- :class:`.TextualSelect`. As rendered in a FROM clause, it represents the
+ :meth:`_expression.SelectBase.subquery` method, or for convenience the
+ :class:`_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:`.Alias`
+ 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:`.Alias` and :class:`.Subquery` is that :class:`.Alias` always
- contains a :class:`.FromClause` object whereas :class:`.Subquery`
- always contains a :class:`.SelectBase` object.
+ :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
"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:`.Select.scalar_subquery` method of the "
- ":func:`~.sql.expression.select` "
+ ":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.scalar_subquery` method.",
+ "use the :meth:`_query.Query.scalar_subquery` method.",
)
def as_scalar(self):
return self.element._set_label_style(
This is a lightweight table object that has only a name and a
collection of columns, which are typically produced
- by the :func:`.expression.column` function::
+ by the :func:`_expression.column` function::
from sqlalchemy import table, column
column("description"),
)
- The :class:`.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 :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:`.MetaData`-level services. It's useful
+ 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`
+ statements when a more fully fledged :class:`_schema.Table`
is not on hand.
"""
named_with_column = True
implicit_returning = False
- """:class:`.TableClause` doesn't support having a primary key or column
+ """:class:`_expression.TableClause`
+ doesn't support having a primary key or column
-level defaults, so implicit returning doesn't apply."""
_autoincrement_column = None
"""No PK or default support so no autoincrement column."""
def __init__(self, name, *columns):
- """Produce a new :class:`.TableClause`.
+ """Produce a new :class:`_expression.TableClause`.
- The object returned is an instance of :class:`.TableClause`, which
+ The object returned is an instance of :class:`_expression.TableClause`
+ , which
represents the "syntactical" portion of the schema-level
- :class:`~.schema.Table` object.
+ :class:`_schema.Table` object.
It may be used to construct lightweight table constructs.
- .. versionchanged:: 1.0.0 :func:`.expression.table` can now
+ .. versionchanged:: 1.0.0 :func:`_expression.table` can now
be imported from the plain ``sqlalchemy`` namespace like any
other SQL element.
:param name: Name of the table.
- :param columns: A collection of :func:`.expression.column` constructs.
+ :param columns: A collection of :func:`_expression.column` constructs.
"""
@util.preload_module("sqlalchemy.sql.dml")
def insert(self, values=None, inline=False, **kwargs):
- """Generate an :func:`~.sql.expression.insert` construct against this
- :class:`.TableClause`.
+ """Generate an :func:`_expression.insert` construct against this
+ :class:`_expression.TableClause`.
E.g.::
table.insert().values(name='foo')
- See :func:`~.sql.expression.insert` for argument and usage information.
+ See :func:`_expression.insert` for argument and usage information.
"""
return util.preloaded.sql_dml.Insert(
@util.preload_module("sqlalchemy.sql.dml")
def update(self, whereclause=None, values=None, inline=False, **kwargs):
- """Generate an :func:`.update` construct against this
- :class:`.TableClause`.
+ """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:`.update` for argument and usage information.
+ See :func:`_expression.update` for argument and usage information.
"""
return util.preloaded.sql_dml.Update(
@util.preload_module("sqlalchemy.sql.dml")
def delete(self, whereclause=None, **kwargs):
- """Generate a :func:`.delete` construct against this
- :class:`.TableClause`.
+ """Generate a :func:`_expression.delete` construct against this
+ :class:`_expression.TableClause`.
E.g.::
table.delete().where(table.c.id==7)
- See :func:`.delete` for argument and usage information.
+ See :func:`_expression.delete` for argument and usage information.
"""
return util.preloaded.sql_dml.Delete(self, whereclause, **kwargs)
skip_locked=False,
key_share=False,
):
- """Represents arguments specified to :meth:`.Select.for_update`.
+ """Represents arguments specified to
+ :meth:`_expression.Select.for_update`.
"""
"""represent a ``VALUES`` construct that can be used as a FROM element
in a statement.
- The :class:`.Values` object is created from the
- :func:`~.sql.expression.values` function.
+ The :class:`_expression.Values` object is created from the
+ :func:`_expression.values` function.
.. versionadded:: 1.4
]
def __init__(self, *columns, **kw):
- r"""Construct a :class:`.Values` construct.
+ r"""Construct a :class:`_expression.Values` construct.
The column expressions and the actual data for
- :class:`.Values` are given in two separate steps. The
+ :class:`_expression.Values` are given in two separate steps. The
constructor receives the column expressions typically as
- :func:`.column` constructs, and the data is then passed via the
- :meth:`.Values.data` method as a list, which can be called multiple
+ :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
)
:param \*columns: column expressions, typically composed using
- :func:`.column` objects.
+ :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
@_generative
def alias(self, name, **kw):
- """Return a new :class:`.Values` construct that is a copy of this
+ """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
- :class:`.FromClause.alias` method.
+ :class:`_expression.FromClause.alias` method.
.. seealso::
:ref:`core_tutorial_aliases`
- :func:`~.expression.alias`
+ :func:`_expression.alias`
"""
self.name = name
@_generative
def lateral(self, name=None):
- """Return a new :class:`.Values` with the lateral flag set, so that
+ """Return a new :class:`_expression.Values` with the lateral flag set,
+ so that
it renders as LATERAL.
.. seealso::
- :func:`~.expression.lateral`
+ :func:`_expression.lateral`
"""
self._is_lateral = True
@_generative
def data(self, values):
- """Return a new :class:`.Values` construct, adding the given data
+ """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:`.Values` constructor.
+ column expressions given in the :class:`_expression.Values`
+ constructor.
"""
"""Base class for SELECT statements.
- This includes :class:`.Select`, :class:`.CompoundSelect` and
- :class:`.TextualSelect`.
+ This includes :class:`_expression.Select`,
+ :class:`_expression.CompoundSelect` and
+ :class:`_expression.TextualSelect`.
"""
@property
def selected_columns(self):
- """A :class:`.ColumnCollection` representing the columns that
+ """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:`.FromClause.columns` collection
- of a :class:`.FromClause` in that the columns within this collection
+ 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.
@property
def exported_columns(self):
- """A :class:`.ColumnCollection` that represents the "exported"
- columns of this :class:`.Selectable`.
+ """A :class:`_expression.ColumnCollection`
+ that represents the "exported"
+ columns of this :class:`expression.Selectable`.
- The "exported" columns for a :class:`.SelectBase` object are synonymous
- with the :attr:`.SelectBase.selected_columns` collection.
+ The "exported" columns for a :class:`_expression.SelectBase`
+ object are synonymous
+ with the :attr:`_expression.SelectBase.selected_columns` collection.
.. versionadded:: 1.4
.. seealso:
- :attr:`.Selectable.exported_columns`
+ :attr:`expression.Selectable.exported_columns`
- :attr:`.FromClause.exported_columns`
+ :attr:`_expression.FromClause.exported_columns`
"""
@property
@util.deprecated(
"1.4",
- "The :attr:`.SelectBase.c` and :attr:`.SelectBase.columns` attributes "
+ "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:`.SelectBase.subquery` first in order to create "
+ "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:`.SelectBase.selected_columns` attribute.",
+ "from, use the :attr:`_expression.SelectBase.selected_columns` "
+ "attribute.",
)
def c(self):
return self._implicit_subquery.columns
@util.deprecated(
"1.4",
- "The :meth:`.SelectBase.select` method is deprecated "
+ "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:`.SelectBase.subquery` first in order to create "
+ "Please call :meth:`_expression.SelectBase.subquery` "
+ "first in order to create "
"a subquery, which then can be seleted.",
)
def select(self, *arg, **kw):
@util.deprecated(
"1.4",
- "The :meth:`.SelectBase.join` method is deprecated "
+ "The :meth:`_expression.SelectBase.join` method is deprecated "
"and will be removed in a future release; this method implicitly "
"creates a subquery that should be explicit. "
- "Please call :meth:`.SelectBase.subquery` first in order to create "
+ "Please call :meth:`_expression.SelectBase.subquery` "
+ "first in order to create "
"a subquery, which then can be selected.",
)
def join(self, *arg, **kw):
@util.deprecated(
"1.4",
- "The :meth:`.SelectBase.outerjoin` method is deprecated "
+ "The :meth:`_expression.SelectBase.outerjoin` method is deprecated "
"and will be removed in a future release; this method implicitly "
"creates a subquery that should be explicit. "
- "Please call :meth:`.SelectBase.subquery` first in order to create "
+ "Please call :meth:`_expression.SelectBase.subquery` "
+ "first in order to create "
"a subquery, which then can be selected.",
)
def outerjoin(self, *arg, **kw):
@util.deprecated(
"1.4",
- "The :meth:`.SelectBase.as_scalar` method is deprecated and will be "
+ "The :meth:`_expression.SelectBase.as_scalar` "
+ "method is deprecated and will be "
"removed in a future release. Please refer to "
- ":meth:`.SelectBase.scalar_subquery`.",
+ ":meth:`_expression.SelectBase.scalar_subquery`.",
)
def as_scalar(self):
return self.scalar_subquery()
an enclosing SELECT.
Note that the scalar subquery differentiates from the FROM-level
- subquery that can be produced using the :meth:`.SelectBase.subquery`
+ subquery that can be produced using the
+ :meth:`_expression.SelectBase.subquery`
method.
.. versionchanged: 1.4 - the ``.as_scalar()`` method was renamed to
- :meth:`.SelectBase.scalar_subquery`.
+ :meth:`_expression.SelectBase.scalar_subquery`.
"""
if self._label_style is not LABEL_STYLE_NONE:
.. seealso::
- :meth:`~.SelectBase.as_scalar`.
+ :meth:`_expression.SelectBase.as_scalar`.
"""
return self.scalar_subquery().label(name)
def lateral(self, name=None):
- """Return a LATERAL alias of this :class:`.Selectable`.
+ """Return a LATERAL alias of this :class:`expression.Selectable`.
- The return value is the :class:`.Lateral` construct also
- provided by the top-level :func:`~.expression.lateral` function.
+ The return value is the :class:`_expression.Lateral` construct also
+ provided by the top-level :func:`_expression.lateral` function.
.. versionadded:: 1.1
return [self]
def subquery(self, name=None):
- """Return a subquery of this :class:`.SelectBase`.
+ """Return a subquery of this :class:`_expression.SelectBase`.
A subquery is from a SQL perspective a parentheized, named construct
that can be placed in the FROM clause of another SELECT statement.
SELECT anon_1.id, anon_1.name
FROM (SELECT table.id, table.name FROM table) AS anon_1
- Historically, :meth:`.SelectBase.subquery` is equivalent to calling
- the :meth:`.FromClause.alias` method on a FROM object; however,
- as a :class:`.SelectBase` object is not directly FROM object,
- the :meth:`.SelectBase.subquery` method provides clearer semantics.
+ 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
raise NotImplementedError()
def alias(self, name=None, flat=False):
- """Return a named subquery against this :class:`.SelectBase`.
+ """Return a named subquery against this
+ :class:`_expression.SelectBase`.
- For a :class:`.SelectBase` (as opposed to a :class:`.FromClause`),
+ 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:`.Alias` object that is used with a
- :class:`.FromClause`.
+ same as the :class:`_expression.Alias` object that is used with a
+ :class:`_expression.FromClause`.
- .. versionchanged:: 1.4 The :meth:`.SelectBase.alias` method is now
- a synonym for the :meth:`.SelectBase.subquery` method.
+ .. versionchanged:: 1.4 The :meth:`_expression.SelectBase.alias`
+ method is now
+ a synonym for the :meth:`_expression.SelectBase.subquery` method.
"""
return self.subquery(name=name)
class SelectStatementGrouping(GroupedElement, SelectBase):
- """Represent a grouping of a :class:`.SelectBase`.
+ """Represent a grouping of a :class:`_expression.SelectBase`.
This differs from :class:`.Subquery` in that we are still
an "inner" SELECT statement, this is strictly for grouping inside of
@property
def selected_columns(self):
- """A :class:`.ColumnCollection` representing the columns that
+ """A :class:`_expression.ColumnCollection`
+ representing the columns that
the embedded SELECT statement returns in its result set.
.. versionadded:: 1.4
class DeprecatedSelectBaseGenerations(object):
@util.deprecated(
"1.4",
- "The :meth:`.GenerativeSelect.append_order_by` method is deprecated "
+ "The :meth:`_expression.GenerativeSelect.append_order_by` "
+ "method is deprecated "
"and will be removed in a future release. Use the generative method "
- ":meth:`.GenerativeSelect.order_by`.",
+ ":meth:`_expression.GenerativeSelect.order_by`.",
)
def append_order_by(self, *clauses):
"""Append the given ORDER BY criterion applied to this selectable.
The criterion will be appended to any pre-existing ORDER BY criterion.
This is an **in-place** mutation method; the
- :meth:`~.GenerativeSelect.order_by` method is preferred, as it
+ :meth:`_expression.GenerativeSelect.order_by` method is preferred,
+ as it
provides standard :term:`method chaining`.
.. seealso::
- :meth:`.GenerativeSelect.order_by`
+ :meth:`_expression.GenerativeSelect.order_by`
"""
self.order_by.non_generative(self, *clauses)
@util.deprecated(
"1.4",
- "The :meth:`.GenerativeSelect.append_group_by` method is deprecated "
+ "The :meth:`_expression.GenerativeSelect.append_group_by` "
+ "method is deprecated "
"and will be removed in a future release. Use the generative method "
- ":meth:`.GenerativeSelect.group_by`.",
+ ":meth:`_expression.GenerativeSelect.group_by`.",
)
def append_group_by(self, *clauses):
"""Append the given GROUP BY criterion applied to this selectable.
The criterion will be appended to any pre-existing GROUP BY criterion.
This is an **in-place** mutation method; the
- :meth:`~.GenerativeSelect.group_by` method is preferred, as it
+ :meth:`_expression.GenerativeSelect.group_by` method is preferred,
+ as it
provides standard :term:`method chaining`.
.. seealso::
- :meth:`.GenerativeSelect.group_by`
+ :meth:`_expression.GenerativeSelect.group_by`
"""
self.group_by.non_generative(self, *clauses)
"""Base class for SELECT statements where additional elements can be
added.
- This serves as the base for :class:`.Select` and :class:`.CompoundSelect`
+ 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:`.TextualSelect`, which,
- while it subclasses :class:`.SelectBase` and is also a SELECT construct,
+ 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.
skip_locked=False,
key_share=False,
):
- """Specify a ``FOR UPDATE`` clause for this :class:`.GenerativeSelect`.
+ """Specify a ``FOR UPDATE`` clause for this
+ :class:`_expression.GenerativeSelect`.
E.g.::
``nowait``, will render ``FOR SHARE NOWAIT``.
:param of: SQL expression or list of SQL expression elements
- (typically :class:`.Column` objects or a compatible expression) which
+ (typically :class:`_schema.Column`
+ objects or a compatible expression) which
will render into a ``FOR UPDATE OF`` clause; supported by PostgreSQL
and Oracle. May render as a table or as a column depending on
backend.
support ``LIMIT`` will attempt to provide similar
functionality.
- .. versionchanged:: 1.0.0 - :meth:`.Select.limit` can now
+ .. versionchanged:: 1.0.0 - :meth:`_expression.Select.limit` can now
accept arbitrary SQL expressions as well as integer values.
:param limit: an integer LIMIT parameter, or a SQL expression
functionality.
- .. versionchanged:: 1.0.0 - :meth:`.Select.offset` can now
+ .. versionchanged:: 1.0.0 - :meth:`_expression.Select.offset` can now
accept arbitrary SQL expressions as well as integer values.
:param offset: an integer OFFSET parameter, or a SQL expression
stmt = select([table]).order_by(table.c.id, table.c.name)
- :param \*order_by: a series of :class:`.ColumnElement` constructs
+ :param \*order_by: a series of :class:`_expression.ColumnElement`
+ constructs
which will be used to generate an ORDER BY clause.
.. seealso::
stmt = select([table.c.name, func.max(table.c.stat)]).\
group_by(table.c.name)
- :param \*group_by: a series of :class:`.ColumnElement` constructs
+ :param \*group_by: a series of :class:`_expression.ColumnElement`
+ constructs
which will be used to generate an GROUP BY clause.
.. seealso::
.. seealso::
- :func:`.union`
+ :func:`_expression.union`
- :func:`.union_all`
+ :func:`_expression.union_all`
- :func:`.intersect`
+ :func:`_expression.intersect`
- :func:`.intersect_all`
+ :func:`_expression.intersect_all`
- :func:`.except`
+ :func:`_expression.except`
- :func:`.except_all`
+ :func:`_expression.except_all`
"""
r"""Return a ``UNION`` of multiple selectables.
The returned object is an instance of
- :class:`.CompoundSelect`.
+ :class:`_expression.CompoundSelect`.
A similar :func:`union()` method is available on all
- :class:`.FromClause` subclasses.
+ :class:`_expression.FromClause` subclasses.
\*selects
- a list of :class:`.Select` instances.
+ a list of :class:`_expression.Select` instances.
\**kwargs
available keyword arguments are the same as those of
r"""Return a ``UNION ALL`` of multiple selectables.
The returned object is an instance of
- :class:`.CompoundSelect`.
+ :class:`_expression.CompoundSelect`.
A similar :func:`union_all()` method is available on all
- :class:`.FromClause` subclasses.
+ :class:`_expression.FromClause` subclasses.
\*selects
- a list of :class:`.Select` instances.
+ a list of :class:`_expression.Select` instances.
\**kwargs
available keyword arguments are the same as those of
r"""Return an ``EXCEPT`` of multiple selectables.
The returned object is an instance of
- :class:`.CompoundSelect`.
+ :class:`_expression.CompoundSelect`.
\*selects
- a list of :class:`.Select` instances.
+ a list of :class:`_expression.Select` instances.
\**kwargs
available keyword arguments are the same as those of
r"""Return an ``EXCEPT ALL`` of multiple selectables.
The returned object is an instance of
- :class:`.CompoundSelect`.
+ :class:`_expression.CompoundSelect`.
\*selects
- a list of :class:`.Select` instances.
+ a list of :class:`_expression.Select` instances.
\**kwargs
available keyword arguments are the same as those of
r"""Return an ``INTERSECT`` of multiple selectables.
The returned object is an instance of
- :class:`.CompoundSelect`.
+ :class:`_expression.CompoundSelect`.
\*selects
- a list of :class:`.Select` instances.
+ a list of :class:`_expression.Select` instances.
\**kwargs
available keyword arguments are the same as those of
r"""Return an ``INTERSECT ALL`` of multiple selectables.
The returned object is an instance of
- :class:`.CompoundSelect`.
+ :class:`_expression.CompoundSelect`.
\*selects
- a list of :class:`.Select` instances.
+ a list of :class:`_expression.Select` instances.
\**kwargs
available keyword arguments are the same as those of
@property
def selected_columns(self):
- """A :class:`.ColumnCollection` representing the columns that
+ """A :class:`_expression.ColumnCollection`
+ representing the columns that
this SELECT statement or similar construct returns in its result set.
- For a :class:`.CompoundSelect`, the
- :attr:`.CompoundSelect.selected_columns` attribute returns the selected
+ 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.
class DeprecatedSelectGenerations(object):
@util.deprecated(
"1.4",
- "The :meth:`.Select.append_correlation` method is deprecated "
+ "The :meth:`_expression.Select.append_correlation` "
+ "method is deprecated "
"and will be removed in a future release. Use the generative "
- "method :meth:`.Select.correlate`.",
+ "method :meth:`_expression.Select.correlate`.",
)
def append_correlation(self, fromclause):
"""append the given correlation expression to this select()
construct.
This is an **in-place** mutation method; the
- :meth:`~.Select.correlate` method is preferred, as it provides
+ :meth:`_expression.Select.correlate` method is preferred,
+ as it provides
standard :term:`method chaining`.
"""
@util.deprecated(
"1.4",
- "The :meth:`.Select.append_column` method is deprecated "
+ "The :meth:`_expression.Select.append_column` method is deprecated "
"and will be removed in a future release. Use the generative "
- "method :meth:`.Select.column`.",
+ "method :meth:`_expression.Select.column`.",
)
def append_column(self, column):
"""append the given column expression to the columns clause of this
my_select.append_column(some_table.c.new_column)
This is an **in-place** mutation method; the
- :meth:`~.Select.column` method is preferred, as it provides standard
+ :meth:`_expression.Select.column` method is preferred,
+ as it provides standard
:term:`method chaining`.
- See the documentation for :meth:`.Select.with_only_columns`
+ See the documentation for :meth:`_expression.Select.with_only_columns`
for guidelines on adding /replacing the columns of a
- :class:`.Select` object.
+ :class:`_expression.Select` object.
"""
self.add_columns.non_generative(self, column)
@util.deprecated(
"1.4",
- "The :meth:`.Select.append_prefix` method is deprecated "
+ "The :meth:`_expression.Select.append_prefix` method is deprecated "
"and will be removed in a future release. Use the generative "
- "method :meth:`.Select.prefix_with`.",
+ "method :meth:`_expression.Select.prefix_with`.",
)
def append_prefix(self, clause):
"""append the given columns clause prefix expression to this select()
construct.
This is an **in-place** mutation method; the
- :meth:`~.Select.prefix_with` method is preferred, as it provides
+ :meth:`_expression.Select.prefix_with` method is preferred,
+ as it provides
standard :term:`method chaining`.
"""
@util.deprecated(
"1.4",
- "The :meth:`.Select.append_whereclause` method is deprecated "
+ "The :meth:`_expression.Select.append_whereclause` "
+ "method is deprecated "
"and will be removed in a future release. Use the generative "
- "method :meth:`.Select.where`.",
+ "method :meth:`_expression.Select.where`.",
)
def append_whereclause(self, whereclause):
"""append the given expression to this select() construct's WHERE
The expression will be joined to existing WHERE criterion via AND.
This is an **in-place** mutation method; the
- :meth:`~.Select.where` method is preferred, as it provides standard
+ :meth:`_expression.Select.where` method is preferred,
+ as it provides standard
:term:`method chaining`.
"""
@util.deprecated(
"1.4",
- "The :meth:`.Select.append_having` method is deprecated "
+ "The :meth:`_expression.Select.append_having` method is deprecated "
"and will be removed in a future release. Use the generative "
- "method :meth:`.Select.having`.",
+ "method :meth:`_expression.Select.having`.",
)
def append_having(self, having):
"""append the given expression to this select() construct's HAVING
The expression will be joined to existing HAVING criterion via AND.
This is an **in-place** mutation method; the
- :meth:`~.Select.having` method is preferred, as it provides standard
+ :meth:`_expression.Select.having` method is preferred,
+ as it provides standard
:term:`method chaining`.
"""
@util.deprecated(
"1.4",
- "The :meth:`.Select.append_from` method is deprecated "
+ "The :meth:`_expression.Select.append_from` method is deprecated "
"and will be removed in a future release. Use the generative "
- "method :meth:`.Select.select_from`.",
+ "method :meth:`_expression.Select.select_from`.",
)
def append_from(self, fromclause):
"""append the given FromClause expression to this select() construct's
FROM clause.
This is an **in-place** mutation method; the
- :meth:`~.Select.select_from` method is preferred, as it provides
+ :meth:`_expression.Select.select_from` method is preferred,
+ as it provides
standard :term:`method chaining`.
"""
@classmethod
def _create_select(cls, *entities):
- r"""Construct a new :class:`.Select` using the 2.x style API.
+ r"""Construct a new :class:`_expression.Select` using the 2.
+ x style API.
.. versionadded:: 2.0 - the :func:`.future.select` construct is
the same construct as the one returned by
- :func:`.sql.expression.select`, except that the function only
+ :func:`_expression.select`, except that the function only
accepts the "columns clause" entities up front; the rest of the
state of the SELECT should be built up using generative methods.
Similar functionality is also available via the
- :meth:`.FromClause.select` method on any :class:`.FromClause`.
+ :meth:`_expression.FromClause.select` method on any
+ :class:`_expression.FromClause`.
.. seealso::
:ref:`coretutorial_selecting` - Core Tutorial description of
- :func:`~.sql.expression.select`.
+ :func:`_expression.select`.
:param \*entities:
Entities to SELECT from. For Core usage, this is typically a series
- of :class:`.ColumnElement` and / or :class:`.FromClause`
+ 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:`.FromClause` (typically :class:`.Table` or :class:`.Alias`
- objects), the :attr:`.FromClause.c` collection is extracted
- to form a collection of :class:`.ColumnElement` objects.
-
- This parameter will also accept :class:`.Text` constructs as
+ :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.
"""
suffixes=None,
**kwargs
):
- """Construct a new :class:`.Select` using the 1.x style API.
+ """Construct a new :class:`_expression.Select` using the 1.x style API
+ .
Similar functionality is also available via the
- :meth:`.FromClause.select` method on any :class:`.FromClause`.
+ :meth:`_expression.FromClause.select` method on any
+ :class:`_expression.FromClause`.
- All arguments which accept :class:`.ClauseElement` arguments also
+ All arguments which accept :class:`_expression.ClauseElement`
+ arguments also
accept string arguments, which will be converted as appropriate into
- either :func:`.text()` or :func:`.literal_column()` constructs.
+ either :func:`_expression.text()` or
+ :func:`_expression.literal_column()` constructs.
.. seealso::
:ref:`coretutorial_selecting` - Core Tutorial description of
- :func:`~.sql.expression.select`.
+ :func:`_expression.select`.
:param columns:
- A list of :class:`.ColumnElement` or :class:`.FromClause`
+ A list of :class:`_expression.ColumnElement` or
+ :class:`_expression.FromClause`
objects which will form the columns clause of the resulting
statement. For those objects that are instances of
- :class:`.FromClause` (typically :class:`.Table` or :class:`.Alias`
- objects), the :attr:`.FromClause.c` collection is extracted
- to form a collection of :class:`.ColumnElement` objects.
-
- This parameter will also accept :class:`.Text` constructs as
+ :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.
.. note::
- The :paramref:`.select.columns` parameter is not available
- in the method form of :func:`~.sql.expression.select`, e.g.
- :meth:`.FromClause.select`.
+ The :paramref:`_expression.select.columns`
+ parameter is not available
+ in the method form of :func:`_expression.select`, e.g.
+ :meth:`_expression.FromClause.select`.
.. seealso::
- :meth:`.Select.column`
+ :meth:`_expression.Select.column`
- :meth:`.Select.with_only_columns`
+ :meth:`_expression.Select.with_only_columns`
:param whereclause:
- A :class:`.ClauseElement` expression which will be used to form the
+ A :class:`_expression.ClauseElement`
+ expression which will be used to form the
``WHERE`` clause. It is typically preferable to add WHERE
- criterion to an existing :class:`.Select` using method chaining
- with :meth:`.Select.where`.
+ criterion to an existing :class:`_expression.Select`
+ using method chaining
+ with :meth:`_expression.Select.where`.
.. seealso::
- :meth:`.Select.where`
+ :meth:`_expression.Select.where`
:param from_obj:
- A list of :class:`.ClauseElement` objects which will be added to the
+ A list of :class:`_expression.ClauseElement`
+ objects which will be added to the
``FROM`` clause of the resulting statement. This is equivalent
- to calling :meth:`.Select.select_from` using method chaining on
- an existing :class:`.Select` object.
+ to calling :meth:`_expression.Select.select_from`
+ using method chaining on
+ an existing :class:`_expression.Select` object.
.. seealso::
- :meth:`.Select.select_from` - full description of explicit
+ :meth:`_expression.Select.select_from`
+ - full description of explicit
FROM clause specification.
:param bind=None:
- an :class:`~.Engine` or :class:`~.Connection` instance
+ an :class:`_engine.Engine` or :class:`_engine.Connection` instance
to which the
- resulting :class:`.Select` object will be bound. The
- :class:`.Select` object will otherwise automatically bind to
+ resulting :class:`_expression.Select` object will be bound. The
+ :class:`_expression.Select`
+ object will otherwise automatically bind to
whatever :class:`~.base.Connectable` instances can be located within
- its contained :class:`.ClauseElement` members.
+ its contained :class:`_expression.ClauseElement` members.
:param correlate=True:
- indicates that this :class:`.Select` object should have its
- contained :class:`.FromClause` elements "correlated" to an enclosing
- :class:`.Select` object. It is typically preferable to specify
- correlations on an existing :class:`.Select` construct using
- :meth:`.Select.correlate`.
+ indicates that this :class:`_expression.Select`
+ object should have its
+ contained :class:`_expression.FromClause`
+ elements "correlated" to an enclosing
+ :class:`_expression.Select` object.
+ It is typically preferable to specify
+ correlations on an existing :class:`_expression.Select`
+ construct using
+ :meth:`_expression.Select.correlate`.
.. seealso::
- :meth:`.Select.correlate` - full description of correlation.
+ :meth:`_expression.Select.correlate`
+ - full description of correlation.
:param distinct=False:
when ``True``, applies a ``DISTINCT`` qualifier to the columns
is understood by the PostgreSQL dialect to render the
``DISTINCT ON (<columns>)`` syntax.
- ``distinct`` is also available on an existing :class:`.Select`
- object via the :meth:`~.Select.distinct` method.
+ ``distinct`` is also available on an existing
+ :class:`_expression.Select`
+ object via the :meth:`_expression.Select.distinct` method.
.. seealso::
- :meth:`.Select.distinct`
+ :meth:`_expression.Select.distinct`
:param group_by:
- a list of :class:`.ClauseElement` objects which will comprise the
+ a list of :class:`_expression.ClauseElement`
+ objects which will comprise the
``GROUP BY`` clause of the resulting select. This parameter
is typically specified more naturally using the
- :meth:`.Select.group_by` method on an existing :class:`.Select`.
+ :meth:`_expression.Select.group_by` method on an existing
+ :class:`_expression.Select`.
.. seealso::
- :meth:`.Select.group_by`
+ :meth:`_expression.Select.group_by`
:param having:
- a :class:`.ClauseElement` that will comprise the ``HAVING`` clause
+ a :class:`_expression.ClauseElement`
+ that will comprise the ``HAVING`` clause
of the resulting select when ``GROUP BY`` is used. This parameter
is typically specified more naturally using the
- :meth:`.Select.having` method on an existing :class:`.Select`.
+ :meth:`_expression.Select.having` method on an existing
+ :class:`_expression.Select`.
.. seealso::
- :meth:`.Select.having`
+ :meth:`_expression.Select.having`
:param limit=None:
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. This parameter is typically specified more
- naturally using the :meth:`.Select.limit` method on an existing
- :class:`.Select`.
+ naturally using the :meth:`_expression.Select.limit`
+ method on an existing
+ :class:`_expression.Select`.
.. seealso::
- :meth:`.Select.limit`
+ :meth:`_expression.Select.limit`
:param offset=None:
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. This parameter is typically specified more naturally
- using the :meth:`.Select.offset` method on an existing
- :class:`.Select`.
+ using the :meth:`_expression.Select.offset` method on an existing
+ :class:`_expression.Select`.
.. seealso::
- :meth:`.Select.offset`
+ :meth:`_expression.Select.offset`
:param order_by:
- a scalar or list of :class:`.ClauseElement` objects which will
+ a scalar or list of :class:`_expression.ClauseElement`
+ objects which will
comprise the ``ORDER BY`` clause of the resulting select.
This parameter is typically specified more naturally using the
- :meth:`.Select.order_by` method on an existing :class:`.Select`.
+ :meth:`_expression.Select.order_by` method on an existing
+ :class:`_expression.Select`.
.. seealso::
- :meth:`.Select.order_by`
+ :meth:`_expression.Select.order_by`
:param use_labels=False:
when ``True``, the statement will be generated using labels
column with its parent table's (or aliases) name so that name
conflicts between columns in different tables don't occur.
The format of the label is <tablename>_<column>. The "c"
- collection of the resulting :class:`.Select` object will use these
+ collection of the resulting :class:`_expression.Select`
+ object will use these
names as well for targeting column members.
This parameter can also be specified on an existing
- :class:`.Select` object using the :meth:`.Select.apply_labels`
+ :class:`_expression.Select` object using the
+ :meth:`_expression.Select.apply_labels`
method.
.. seealso::
- :meth:`.Select.apply_labels`
+ :meth:`_expression.Select.apply_labels`
"""
util.warn_deprecated_20(
return self._compile_state_factory(self, None)._get_display_froms()
def with_statement_hint(self, text, dialect_name="*"):
- """add a statement hint to this :class:`.Select`.
+ """add a statement hint to this :class:`_expression.Select`.
- This method is similar to :meth:`.Select.with_hint` except that
+ 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.
.. seealso::
- :meth:`.Select.with_hint`
+ :meth:`_expression.Select.with_hint`
:meth:.`.Select.prefix_with` - generic SELECT prefixing which also
can suit some database-specific HINT syntaxes such as MySQL
@_generative
def with_hint(self, selectable, text, dialect_name="*"):
r"""Add an indexing or other executional context hint for the given
- selectable to this :class:`.Select`.
+ selectable to this :class:`_expression.Select`.
The text of the hint is rendered in the appropriate
location for the database backend in use, relative
- to the given :class:`.Table` or :class:`.Alias` passed as the
+ 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
.. seealso::
- :meth:`.Select.with_statement_hint`
+ :meth:`_expression.Select.with_statement_hint`
"""
if selectable is None:
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:`.Select.exported_columns` collection.
+ :attr:`_expression.Select.exported_columns` collection.
"""
my_select = my_select.add_columns(table.c.new_column)
- See the documentation for :meth:`.Select.with_only_columns`
+ See the documentation for
+ :meth:`_expression.Select.with_only_columns`
for guidelines on adding /replacing the columns of a
- :class:`.Select` object.
+ :class:`_expression.Select` object.
"""
# memoizations should be cleared here as of
@util.deprecated(
"1.4",
- "The :meth:`.Select.column` method is deprecated and will "
+ "The :meth:`_expression.Select.column` method is deprecated and will "
"be removed in a future release. Please use "
- ":meth:`.Select.add_columns`",
+ ":meth:`_expression.Select.add_columns`",
)
def column(self, column):
"""return a new select() construct with the given column expression
my_select = my_select.column(table.c.new_column)
- See the documentation for :meth:`.Select.with_only_columns`
+ See the documentation for
+ :meth:`_expression.Select.with_only_columns`
for guidelines on adding /replacing the columns of a
- :class:`.Select` object.
+ :class:`_expression.Select` object.
"""
return self.add_columns(column)
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:`.apply_labels` does.
+ table-qualified labels as :meth:`_expression.Select.apply_labels` 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
@_generative
def with_only_columns(self, columns):
- r"""Return a new :func:`~.sql.expression.select` construct with its columns
+ r"""Return a new :func:`_expression.select` construct with its columns
clause replaced with the given columns.
This method is exactly equivalent to as if the original
- :func:`~.sql.expression.select` had been called with the given columns
+ :func:`_expression.select` had been called with the given columns
clause. I.e. a statement::
s = select([table1.c.a, table1.c.b])
The preferred way to maintain a specific FROM clause
in the construct, assuming it won't be represented anywhere
else (i.e. not in the WHERE clause, etc.) is to set it using
- :meth:`.Select.select_from`::
+ :meth:`_expression.Select.select_from`::
>>> s1 = select([table1.c.a, table2.c.b]).\
... select_from(table1.join(table2,
SELECT t2.b FROM t1 JOIN t2 ON t1.a=t2.a
Care should also be taken to use the correct set of column objects
- passed to :meth:`.Select.with_only_columns`. Since the method is
- essentially equivalent to calling the :func:`~.sql.expression.select`
+ passed to :meth:`_expression.Select.with_only_columns`.
+ Since the method is
+ essentially equivalent to calling the :func:`_expression.select`
construct in the first place with the given columns, the columns passed
- to :meth:`.Select.with_only_columns` should usually be a subset of
- those which were passed to the :func:`~.sql.expression.select`
+ to :meth:`_expression.Select.with_only_columns`
+ should usually be a subset of
+ those which were passed to the :func:`_expression.select`
construct, not those which are available from the ``.c`` collection of
- that :func:`~.sql.expression.select`. That is::
+ that :func:`_expression.select`. That is::
s = select([table1.c.a, table1.c.b]).select_from(table1)
s = s.with_only_columns([table1.c.b])
FROM (SELECT t1.a AS a, t1.b AS b
FROM t1), t1
- Since the :func:`~.sql.expression.select` construct is essentially
+ Since the :func:`_expression.select` construct is essentially
being asked to select both from ``table1`` as well as itself.
"""
@property
def _whereclause(self):
- """Legacy, return the WHERE clause as a :class:`.BooleanClauseList`"""
+ """Legacy, return the WHERE clause as a """
+ """:class:`_expression.BooleanClauseList`"""
return and_(*self._where_criteria)
@_generative
def select_from(self, *froms):
- r"""return a new :func:`~.sql.expression.select` construct with the
+ r"""return a new :func:`_expression.select` construct with the
given FROM expression(s)
merged into its list of FROM objects.
)
The "from" list is a unique set on the identity of each element,
- so adding an already present :class:`.Table` or other selectable
- will have no effect. Passing a :class:`.Join` that refers
- to an already present :class:`.Table` or other selectable will have
+ 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:`.Select.select_from` is to
+ 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
@_generative
def correlate(self, *fromclauses):
- r"""return a new :class:`.Select` which will correlate the given FROM
- clauses to that of an enclosing :class:`.Select`.
+ r"""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:`.Select` object's
+ Calling this method turns off the :class:`_expression.Select` object's
default behavior of "auto-correlation". Normally, FROM elements
- which appear in a :class:`.Select` that encloses this one via
+ 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:`.Select`
+ :term:`columns clause` will be omitted from this
+ :class:`_expression.Select`
object's :term:`FROM clause`.
Setting an explicit correlation collection using the
- :meth:`.Select.correlate` method provides a fixed list of FROM objects
+ :meth:`_expression.Select.correlate`
+ method provides a fixed list of FROM objects
that can potentially take place in this process.
- When :meth:`.Select.correlate` is used to apply specific FROM clauses
+ 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:`.Select`
- object is, relative to an enclosing :class:`.Select` which refers to
+ 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:`.Select`. Multi-level correlation ensures that the link
- between enclosed and enclosing :class:`.Select` is always via
+ :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:`.Select` object will correlate
+ 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: a list of one or more :class:`.FromClause`
+ :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:`.Select.correlate_except`
+ :meth:`_expression.Select.correlate_except`
:ref:`correlated_subqueries`
@_generative
def correlate_except(self, *fromclauses):
- r"""return a new :class:`.Select` which will omit the given FROM
+ r"""return a new :class:`_expression.Select`
+ which will omit the given FROM
clauses from the auto-correlation process.
- Calling :meth:`.Select.correlate_except` turns off the
- :class:`.Select` object's default behavior of
+ 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, the :class:`.Select` object will correlate
+ If ``None`` is passed, the :class:`_expression.Select`
+ object will correlate
all of its FROM entries.
- :param \*fromclauses: a list of one or more :class:`.FromClause`
+ :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:`.Select.correlate`
+ :meth:`_expression.Select.correlate`
:ref:`correlated_subqueries`
@HasMemoized.memoized_attribute
def selected_columns(self):
- """A :class:`.ColumnCollection` representing the columns that
+ """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:`.FromClause.columns` collection
- of a :class:`.FromClause` in that the columns within this collection
+ 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:`~.sql.expression.select` construct, the collection here is
+ For a :func:`_expression.select` construct, the collection here is
exactly what would be rendered inside the "SELECT" statement, and the
- :class:`.ColumnElement` objects are directly present as they were
+ :class:`_expression.ColumnElement`
+ objects are directly present as they were
given, e.g.::
col1 = column('q', Integer)
Above, ``stmt.selected_columns`` would be a collection that contains
the ``col1`` and ``col2`` objects directly. For a statement that is
- against a :class:`.Table` or other :class:`.FromClause`, the collection
- will use the :class:`.ColumnElement` objects that are in the
- :attr:`.FromClause.c` collection of the from element.
+ 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.
.. versionadded:: 1.4
@_generative
def where(self, crit):
"""Apply a WHERE clause to the SELECT statement referred to
- by this :class:`.ScalarSelect`.
+ by this :class:`_expression.ScalarSelect`.
"""
self.element = self.element.where(crit)
_from_objects = []
def __init__(self, *args, **kwargs):
- """Construct a new :class:`.Exists` against an existing
- :class:`.Select` object.
+ """Construct a new :class:`_expression.Exists` against an existing
+ :class:`_expression.Select` object.
Calling styles are of the following forms::
return e
def select_from(self, clause):
- """return a new :class:`.Exists` construct, applying the given
- expression to the :meth:`.Select.select_from` method of the select
+ """return a new :class:`_expression.Exists` construct,
+ applying the given
+ expression to the :meth:`_expression.Select.select_from`
+ method of the select
statement contained.
"""
class TextualSelect(SelectBase):
- """Wrap a :class:`.TextClause` construct within a :class:`.SelectBase`
+ """Wrap a :class:`_expression.TextClause` construct within a
+ :class:`_expression.SelectBase`
interface.
- This allows the :class:`.TextClause` object to gain a ``.c`` collection
- and other FROM-like capabilities such as :meth:`.FromClause.alias`,
- :meth:`.SelectBase.cte`, etc.
+ 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:`.TextualSelect` construct is produced via the
- :meth:`.TextClause.columns` method - see that method for details.
+ The :class:`_expression.TextualSelect` construct is produced via the
+ :meth:`_expression.TextClause.columns`
+ method - see that method for details.
- .. versionchanged:: 1.4 the :class:`.TextualSelect` class was renamed
+ .. 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:`.text`
+ :func:`_expression.text`
- :meth:`.TextClause.columns` - primary creation interface.
+ :meth:`_expression.TextClause.columns` - primary creation interface.
"""
@HasMemoized.memoized_attribute
def selected_columns(self):
- """A :class:`.ColumnCollection` representing the columns that
+ """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:`.FromClause.columns` collection
- of a :class:`.FromClause` in that the columns within this collection
+ 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:`.TextualSelect` construct, the collection contains the
- :class:`.ColumnElement` objects that were passed to the constructor,
- typically via the :meth:`.TextClause.columns` method.
+ 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
In the vast majority of cases, the :class:`.Unicode` or
:class:`.UnicodeText` datatypes should be used for a
- :class:`.Column` that expects to store non-ascii data. These
+ :class:`_schema.Column` that expects to store non-ascii data.
+ These
datatypes will ensure that the correct types are used on the
database side as well as set up the correct Unicode behaviors
under Python 2.
.. seealso::
:paramref:`.create_engine.convert_unicode` -
- :class:`.Engine`-wide parameter
+ :class:`_engine.Engine`-wide parameter
:param unicode_error: Optional, a method to use to handle Unicode
conversion errors. Behaves like the ``errors`` keyword argument to
"""
Create a Unicode-converting Text type.
- Parameters are the same as that of :class:`.Text`,
+ Parameters are the same as that of :class:`_expression.TextClause`,
with the exception that ``convert_unicode``
defaults to ``True``.
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,
+ timezone support, use at least the :class:`_types.TIMESTAMP` datatype,
if not the dialect-specific datatype object.
"""
: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
+ 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.
:meth:`.DDLEvents.before_parent_attach` and
:meth:`.DDLEvents.after_parent_attach` events, where the events fire off
surrounding the association of the type object with a parent
- :class:`.Column`.
+ :class:`_schema.Column`.
.. seealso::
.. seealso::
- :class:`.postgresql.ENUM` - PostgreSQL-specific type,
+ :class:`_postgresql.ENUM` - PostgreSQL-specific type,
which has additional functionality.
:class:`.mysql.ENUM` - MySQL-specific type
The ``schema`` of the :class:`.Enum` type does not
by default make use of the ``schema`` established on the
- owning :class:`.Table`. If this behavior is desired,
+ owning :class:`_schema.Table`. If this behavior is desired,
set the ``inherit_schema`` flag to ``True``.
:param quote: Set explicit quoting preferences for the type's name.
:param inherit_schema: When ``True``, the "schema" from the owning
- :class:`.Table` will be copied to the "schema" attribute of this
+ :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:`.Table.tometadata` operation.
+ :meth:`_schema.Table.tometadata` operation.
:param validate_strings: when True, string values that are being
passed to the database in a SQL statement will be checked
class JSON(Indexable, TypeEngine):
"""Represent a SQL JSON type.
- .. note:: :class:`.types.JSON` is provided as a facade for vendor-specific
+ .. 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:
* SQLite as of version 3.9
- :class:`.types.JSON` is part of the Core in support of the growing
+ :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.::
+ The :class:`_types.JSON` type stores arbitrary JSON format data, e.g.::
data_table = Table('data_table', metadata,
Column('id', Integer, primary_key=True),
**JSON-Specific Expression Operators**
- The :class:`.types.JSON` datatype provides these additional SQL operations:
+ The :class:`_types.JSON`
+ datatype provides these additional SQL operations:
* Keyed index operations::
.. versionadded:: 1.3.11
Additional operations may be available from the dialect-specific versions
- of :class:`.types.JSON`, such as :class:`.postgresql.JSON` and
- :class:`.postgresql.JSONB` which both offer additional PostgreSQL-specific
+ of :class:`_types.JSON`, such as :class:`_postgresql.JSON` and
+ :class:`_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:`.JSON` by default, so that
+ 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
**Detecting Changes in JSON columns when using the ORM**
- The :class:`.JSON` type, when used with the SQLAlchemy ORM, does not
+ 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. This extension will
allow "in-place" changes to the datastructure to produce events which
**Support for JSON null vs. SQL NULL**
- When working with NULL values, the :class:`.JSON` type recommends the
+ 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,
conn.execute(table.insert(), json_value=null())
To insert or select against a value that is JSON ``"null"``, use the
- constant :attr:`.JSON.NULL`::
+ constant :attr:`_types.JSON.NULL`::
conn.execute(table.insert(), json_value=JSON.NULL)
- The :class:`.JSON` type supports a flag
- :paramref:`.JSON.none_as_null` which when set to True will result
+ 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:`.JSON.NULL` and :func:`.null` in order to indicate NULL
+ :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:`.JSON.none_as_null` in these cases.
+ :paramref:`_types.JSON.none_as_null` in these cases.
**Customizing the JSON Serializer**
- The JSON serializer and deserializer used by :class:`.JSON` defaults to
+ 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.
.. seealso::
- :class:`.postgresql.JSON`
+ :class:`_postgresql.JSON`
- :class:`.postgresql.JSONB`
+ :class:`_postgresql.JSONB`
:class:`.mysql.JSON`
- :class:`.sqlite.JSON`
+ :class:`_sqlite.JSON`
.. versionadded:: 1.1
This value is used to force the JSON value of ``"null"`` to be
used as the value. A value of Python ``None`` will be recognized
either as SQL NULL or JSON ``"null"``, based on the setting
- of the :paramref:`.JSON.none_as_null` flag; the :attr:`.JSON.NULL`
+ of the :paramref:`_types.JSON.none_as_null` flag; the
+ :attr:`_types.JSON.NULL`
constant can be used to always resolve to JSON ``"null"`` regardless
- of this setting. This is in contrast to the :func:`.sql.null` construct,
+ of this setting. This is in contrast to the :func:`_expression.null`
+ construct,
which always resolves to SQL NULL. E.g.::
from sqlalchemy import null
session.commit()
In order to set JSON NULL as a default value for a column, the most
- transparent method is to use :func:`.text`::
+ transparent method is to use :func:`_expression.text`::
Table(
'my_table', metadata,
Column('json_data', JSON, default=text("'null'"))
)
- While it is possible to use :attr:`.JSON.NULL` in this context, the
- :attr:`.JSON.NULL` value will be returned as the value of the column,
+ While it is possible to use :attr:`_types.JSON.NULL` in this context, the
+ :attr:`_types.JSON.NULL` value will be returned as the value of the column
+ ,
which in the context of the ORM or other repurposing of the default
value, may not be desirable. Using a SQL expression means the value
will be re-fetched from the database within the context of retrieving
"""
def __init__(self, none_as_null=False):
- """Construct a :class:`.types.JSON` type.
+ """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
.. note::
- :paramref:`.JSON.none_as_null` does **not** apply to the
- values passed to :paramref:`.Column.default` and
- :paramref:`.Column.server_default`; a value of ``None``
+ :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".
.. seealso::
"""
class Comparator(Indexable.Comparator, Concatenable.Comparator):
- """Define comparison operations for :class:`.types.JSON`."""
+ """Define comparison operations for :class:`_types.JSON`."""
def _setup_getitem(self, index):
if not isinstance(index, util.string_types) and isinstance(
@property
def should_evaluate_none(self):
- """Alias of :attr:`.JSON.none_as_null`"""
+ """Alias of :attr:`_types.JSON.none_as_null`"""
return not self.none_as_null
@should_evaluate_none.setter
.. 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
- :class:`.postgresql.ARRAY` type directly when using ARRAY types
+ :class:`_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:`.array_agg` which explicitly involve
+ :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"
+ An :class:`_types.ARRAY` type is constructed given the "type"
of element::
mytable = Table("mytable", metadata,
data=[1,2,3]
)
- The :class:`.types.ARRAY` type can be constructed given a fixed number
+ The :class:`_types.ARRAY` type can be constructed given a fixed number
of dimensions::
mytable = Table("mytable", metadata,
>>> 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
+ 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
+ SQL expressions of type :class:`_types.ARRAY` have support for "index" and
"slice" behavior. The Python ``[]`` operator works normally here, given
integer indexes or slices. Arrays default to 1-based indexing.
The operator produces binary expression
select([mytable.c.data[5], mytable.c.data[2:7]])
- as well as UPDATE statements when the :meth:`.Update.values` method
+ as well as UPDATE statements when the :meth:`_expression.Update.values`
+ method
is used::
mytable.update().values({
mytable.c.data[2:7]: [1, 2, 3]
})
- The :class:`.types.ARRAY` type also provides for the operators
+ 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.
+ :class:`_types.ARRAY` also provides additional operators.
.. versionadded:: 1.1.0
.. seealso::
- :class:`.postgresql.ARRAY`
+ :class:`_postgresql.ARRAY`
"""
class Comparator(Indexable.Comparator, Concatenable.Comparator):
- """Define comparison operations for :class:`.types.ARRAY`.
+ """Define comparison operations for :class:`_types.ARRAY`.
More operators are available on the dialect-specific form
of this type. See :class:`.postgresql.ARRAY.Comparator`.
.. seealso::
- :func:`.sql.expression.any_`
+ :func:`_expression.any_`
:meth:`.types.ARRAY.Comparator.all`
.. seealso::
- :func:`.sql.expression.all_`
+ :func:`_expression.all_`
:meth:`.types.ARRAY.Comparator.any`
def __init__(
self, item_type, as_tuple=False, dimensions=None, zero_indexes=False
):
- """Construct an :class:`.types.ARRAY`.
+ """Construct an :class:`_types.ARRAY`.
E.g.::
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.
+ :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.
"""The SQL TIMESTAMP type.
- :class:`~.types.TIMESTAMP` datatypes have support for timezone
+ :class:`_types.TIMESTAMP` datatypes have support for timezone
storage on some backends, such as PostgreSQL and Oracle. Use the
:paramref:`~types.TIMESTAMP.timezone` argument in order to enable
"TIMESTAMP WITH TIMEZONE" for these backends.
__visit_name__ = "TIMESTAMP"
def __init__(self, timezone=False):
- """Construct a new :class:`.TIMESTAMP`.
+ """Construct a new :class:`_types.TIMESTAMP`.
:param timezone: boolean. Indicates that the TIMESTAMP type should
enable timezone support, if available on the target database.
by the :class:`.Dialect`
* When constructing SQL expressions using plain Python objects of
unknown types (e.g. ``somecolumn == my_special_object``)
- * When a new :class:`.Column` is created, and the given type is passed
+ * When a new :class:`_schema.Column` is created,
+ and the given type is passed
as ``None`` or is not passed at all.
The :class:`.NullType` can be used within SQL expression invocation
:class:`.NullType` will result in a :exc:`.CompileError` if the compiler
is asked to render the type itself, such as if it is used in a
:func:`.cast` operation or within a schema creation operation such as that
- invoked by :meth:`.MetaData.create_all` or the :class:`.CreateTable`
+ invoked by :meth:`_schema.MetaData.create_all` or the
+ :class:`.CreateTable`
construct.
"""
each one; these bound parameters must be consulted in order to
execute the statement with the correct parameters.
- a :class:`.ClauseElement` structure that does not implement
+ a :class:`_expression.ClauseElement` structure that does not implement
a :meth:`._gen_cache_key` method and does not implement a
:attr:`.traverse_internals` attribute will not be cacheable; when
such an element is embedded into a larger structure, this method
This method determines the type of a resulting binary expression
given two source types and an operator. For example, two
- :class:`.Column` objects, both of the type :class:`.Integer`, will
+ :class:`_schema.Column` objects, both of the type
+ :class:`.Integer`, will
produce a :class:`.BinaryExpression` that also has the type
:class:`.Integer` when compared via the addition (``+``) operator.
However, using the addition operator with an :class:`.Integer`
comparator_factory = Comparator
"""A :class:`.TypeEngine.Comparator` class which will apply
- to operations performed by owning :class:`.ColumnElement` objects.
+ to operations performed by owning :class:`_expression.ColumnElement`
+ objects.
The :attr:`.comparator_factory` attribute is a hook consulted by
the core expression system when column and SQL expression operations
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
+ 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:`.Column.default` or
- :paramref:`.Column.server_default`; in these cases, ``None``
+ of ``None`` passed to :paramref:`_schema.Column.default` or
+ :paramref:`_schema.Column.server_default`; in these cases,
+ ``None``
still means "no default".
.. versionadded:: 1.1
The ``get_col_spec()`` method will in most cases receive a keyword
argument ``type_expression`` which refers to the owning expression
- of the type as being compiled, such as a :class:`.Column` or
+ of the type as being compiled, such as a :class:`_schema.Column` or
:func:`.cast` construct. This keyword is only sent if the method
accepts keyword arguments (e.g. ``**kw``) in its argument signature;
introspection is used to check for this in order to support legacy
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 :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::
"""Visit a :class:`.HasCacheKey` object."""
dp_clauseelement = symbol("CE")
- """Visit a :class:`.ClauseElement` object."""
+ """Visit a :class:`_expression.ClauseElement` object."""
dp_fromclause_canonical_column_collection = symbol("FC")
- """Visit a :class:`.FromClause` object in the context of the
+ """Visit a :class:`_expression.FromClause` object in the context of the
``columns`` attribute.
The column collection is "canonical", meaning it is the originally
defined location of the :class:`.ColumnClause` objects. Right now
- this means that the object being visited is a :class:`.TableClause`
- or :class:`.Table` object only.
+ this means that the object being visited is a
+ :class:`_expression.TableClause`
+ or :class:`_schema.Table` object only.
"""
dp_clauseelement_tuples = symbol("CT")
- """Visit a list of tuples which contain :class:`.ClauseElement`
+ """Visit a list of tuples which contain :class:`_expression.ClauseElement`
objects.
"""
dp_clauseelement_list = symbol("CL")
- """Visit a list of :class:`.ClauseElement` objects.
+ """Visit a list of :class:`_expression.ClauseElement` objects.
"""
dp_clauseelement_unordered_set = symbol("CU")
- """Visit an unordered set of :class:`.ClauseElement` objects. """
+ """Visit an unordered set of :class:`_expression.ClauseElement`
+ objects. """
dp_fromclause_ordered_set = symbol("CO")
- """Visit an ordered set of :class:`.FromClause` objects. """
+ """Visit an ordered set of :class:`_expression.FromClause` objects. """
dp_string = symbol("S")
"""Visit a plain string value.
"""visit a dialect options structure."""
dp_string_clauseelement_dict = symbol("CD")
- """Visit a dictionary of string keys to :class:`.ClauseElement`
+ """Visit a dictionary of string keys to :class:`_expression.ClauseElement`
objects.
"""
"""
dp_prefix_sequence = symbol("PS")
- """Visit the sequence represented by :class:`.HasPrefixes`
- or :class:`.HasSuffixes`.
+ """Visit the sequence represented by :class:`_expression.HasPrefixes`
+ or :class:`_expression.HasSuffixes`.
"""
dp_table_hint_list = symbol("TH")
- """Visit the ``_hints`` collection of a :class:`.Select` object.
+ """Visit the ``_hints`` collection of a :class:`_expression.Select` object
+ .
"""
dp_statement_hint_list = symbol("SH")
- """Visit the ``_statement_hints`` collection of a :class:`.Select`
+ """Visit the ``_statement_hints`` collection of a
+ :class:`_expression.Select`
object.
"""
"""
dp_dml_ordered_values = symbol("DML_OV")
- """visit the values() ordered tuple list of an :class:`.Update` object."""
+ """visit the values() ordered tuple list of an
+ :class:`_expression.Update` object."""
dp_dml_values = symbol("DML_V")
"""visit the values() dictionary of a :class:`.ValuesBase`
dp_dml_multi_values = symbol("DML_MV")
"""visit the values() multi-valued list of dictionaries of an
- :class:`~.sql.expression.Insert` object.
+ :class:`_expression.Insert` object.
"""
class ExtendedInternalTraversal(InternalTraversal):
"""defines additional symbols that are useful in caching applications.
- Traversals for :class:`.ClauseElement` objects only need to use
+ Traversals for :class:`_expression.ClauseElement` objects only need to use
those symbols present in :class:`.InternalTraversal`. However, for
additional caching use cases within the ORM, symbols dealing with the
:class:`.HasCacheKey` class are added here.
The central API feature used by the :func:`.visitors.iterate` and
:func:`.visitors.iterate_depthfirst` functions is the
- :meth:`.ClauseElement.get_children` method of :class:`.ClauseElement`
- objects. This method should return all the :class:`.ClauseElement` objects
- which are associated with a particular :class:`.ClauseElement` object.
+ :meth:`_expression.ClauseElement.get_children` method of
+ :class:`_expression.ClauseElement`
+ objects. This method should return all the
+ :class:`_expression.ClauseElement` objects
+ which are associated with a particular :class:`_expression.ClauseElement`
+ object.
For example, a :class:`.Case` structure will refer to a series of
- :class:`.ColumnElement` objects within its "whens" and "else\_" member
+ :class:`_expression.ColumnElement`
+ objects within its "whens" and "else\_" member
variables.
- :param obj: :class:`.ClauseElement` structure to be traversed
+ :param obj: :class:`_expression.ClauseElement` structure to be traversed
:param opts: dictionary of iteration options. This dictionary is usually
empty in modern usage.
traversal is configured to be depth-first.
- :param obj: :class:`.ClauseElement` structure to be traversed
+ :param obj: :class:`_expression.ClauseElement` structure to be traversed
:param opts: dictionary of iteration options. This dictionary is usually
empty in modern usage.
functions.
:param iterator: an iterable or sequence which will yield
- :class:`.ClauseElement` structures; the iterator is assumed to be the
+ :class:`_expression.ClauseElement`
+ structures; the iterator is assumed to be the
product of the :func:`.visitors.iterate` or
:func:`.visitors.iterate_depthfirst` functions.
- :param obj: the :class:`.ClauseElement` that was used as the target of the
+ :param obj: the :class:`_expression.ClauseElement`
+ that was used as the target of the
:func:`.iterate` or :func:`.iterate_depthfirst` function.
:param visitors: dictionary of visit functions. See :func:`.traverse`
The iteration of objects uses the :func:`.visitors.iterate` function,
which does a breadth-first traversal using a stack.
- :param obj: :class:`.ClauseElement` structure to be traversed
+ :param obj: :class:`_expression.ClauseElement` structure to be traversed
:param opts: dictionary of iteration options. This dictionary is usually
empty in modern usage.
The central API feature used by the :func:`.visitors.cloned_traverse`
and :func:`.visitors.replacement_traverse` functions, in addition to the
- :meth:`.ClauseElement.get_children` function that is used to achieve
- the iteration, is the :meth:`.ClauseElement._copy_internals` method.
- For a :class:`.ClauseElement` structure to support cloning and replacement
+ :meth:`_expression.ClauseElement.get_children`
+ function that is used to achieve
+ the iteration, is the :meth:`_expression.ClauseElement._copy_internals`
+ method.
+ For a :class:`_expression.ClauseElement`
+ structure to support cloning and replacement
traversals correctly, it needs to be able to pass a cloning function into
its internal members in order to make copies of them.
projects / thirdparty / sqlalchemy / sqlalchemy.git / commitdiff
