Fixed bug where :meth:`.Table.update` and :meth:`.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:`.select`.
+ now consistent with that of :func:`~.sql.expression.select`.
.. change::
:tags: bug, postgresql
:tickets: 2815
:versions: 0.9.0b1
- A :func:`.select` that is made to refer to itself in its FROM clause,
+ A :func:`~.sql.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.
:tags: feature, sql
:tickets: 722
- Added new method to the :func:`.insert` construct
+ Added new method to the :func:`~.sql.expression.insert` construct
:meth:`.Insert.from_select`. Given a list of columns and
a selectable, renders ``INSERT INTO (table) (columns) SELECT ..``.
:tags: feature, sql
:versions: 0.9.0b1
- The :func:`.update`, :func:`.insert`, and :func:`.delete` constructs
+ The :func:`.update`, :func:`~.sql.expression.insert`, and :func:`.delete` constructs
will now interpret ORM entities as target tables to be operated upon,
e.g.::
:tags: sql, feature
:tickets: 2623
- The :class:`.Insert` construct now supports multi-valued inserts,
+ The :class:`~.sql.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, orm, bug
:tickets: 2595
- The auto-correlation feature of :func:`.select`, and
+ The auto-correlation feature of :func:`~.sql.expression.select`, and
by proxy that of :class:`.Query`, will not
take effect for a SELECT statement that is being
rendered directly in the FROM list of the enclosing
:tickets: 3069
:versions: 1.0.0b1
- Fixed bug where multi-valued :class:`.Insert` construct would fail
+ Fixed bug where multi-valued :class:`~.sql.expression.Insert` construct would fail
to check subsequent values entries beyond the first one given
for literal SQL expressions.
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:`.select` construct,
+ "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
ORM either.
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:`.Insert` and :class:`.Delete`, and also
+ :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
can now specify acceptable argument lists for these constructs, allowing
is added with the new :meth:`.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:`.select`, and also includes support for the
+ argument of :func:`~.sql.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`.
Pull request courtesy Mario Lassnig.
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:`.Insert` or
+ passed to :meth:`.ValuesBase.values` for an :class:`~.sql.expression.Insert` or
:class:`.Update` construct, within the compilation phase of the
construct.
:tags: feature, sql
:tickets: 722
- Added new method to the :func:`.insert` construct
+ Added new method to the :func:`~.sql.expression.insert` construct
:meth:`.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
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:`.Insert`
+ 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
erroneous column present subsequent to compilation of the
- :class:`.Insert`, and the :class:`.Insert` statement itself would
+ :class:`~.sql.expression.Insert`, and the :class:`~.sql.expression.Insert` statement itself would
fail on a second compile attempt due to duplicate bound parameters.
.. change::
:tickets: 2992
The implicit conversion of strings to :func:`.text` constructs
- when passed to most builder methods of :func:`.select` as
+ when passed to most builder methods of :func:`~.sql.expression.select` as
well as :class:`.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
:tickets: 3169
Using :meth:`.Insert.from_select` now implies ``inline=True``
- on :func:`.insert`. This helps to fix a bug where an
+ on :func:`~.sql.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
:tickets: 3880
Fixed bug where literal_binds compiler flag was not honored by the
- :class:`.Insert` construct for the "multiple values" feature; the
+ :class:`~.sql.expression.Insert` construct for the "multiple values" feature; the
subsequent values are now rendered as literals.
.. change:: 3877
adaptation of this clause wasn't considered. Note that in 1.2 only,
a selectable introduced by :meth:`.Query.subquery` is still not adapted
due to :ticket:`4304`; the selectable needs to be produced by the
- :func:`.select` function to be the right side of the "lateral" join.
+ :func:`~.sql.expression.select` function to be the right side of the "lateral" join.
.. change::
:tags: bug, oracle
:tickets: 4193
Fixed 1.2 regression in ORM versioning feature where a mapping against a
- :func:`.select` or :func:`.alias` that also used a versioning column
+ :func:`~.sql.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`.
Changed the name of the ``.values`` attribute of the new MySQL
INSERT..ON DUPLICATE KEY UPDATE construct to ``.inserted``, as
- :class:`.Insert` already has a method called :meth:`.Insert.values`.
+ :class:`~.sql.expression.Insert` already has a method called :meth:`.Insert.values`.
The ``.inserted`` attribute ultimately renders the MySQL ``VALUES()``
function.
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:`.select` and then string SQL statement from
+ running it into a :func:`~.sql.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.
:tags: bug, sql
:tickets: 5028
- Fixed bug where "distinct" keyword passed to :func:`.select` would not
+ Fixed bug where "distinct" keyword passed to :func:`~.sql.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:`.select` will ultimately
+ keyword argument and the others passed to :func:`~.sql.expression.select` will ultimately
be deprecated for SQLAlchemy 2.0.
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:`.insert` constructs. Pull request courtesy Yuval Dinari.
+ :func:`~.sql.expression.insert` constructs. Pull request courtesy Yuval Dinari.
.. seealso::
and other :class:`.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:`.select` constructs were used previously in other similar kinds of
+ :func:`~.sql.expression.select` constructs were used previously in other similar kinds of
routines, due to a cached value not being cleared.
.. change::
:tickets: 4481
Fully removed the behavior of strings passed directly as components of a
- :func:`.select` or :class:`.Query` object being coerced to :func:`.text`
+ :func:`~.sql.expression.select` or :class:`.Query` object being coerced to :func:`.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
derivations from :attr:`.Query.statement` would not correctly be adapted
when used in a new :class:`.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:`.select` object
+ removes the "no adaptation" annotation from the :func:`~.sql.expression.select` object
produced by the :attr:`.Query.statement` accessor.
.. change::
While the SQL expressions used with :meth:`.Query.filter`,
such as ``User.id == 5``, have always been compatible for
-use with core constructs such as :func:`.select`, the mapped
-class itself would not be recognized when passed to :func:`.select`,
+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`.
A new SQL registration system allows a mapped class to be
accepted as a FROM clause within the core::
New Method :meth:`.Select.correlate_except`
-------------------------------------------
-:func:`.select` now has a method :meth:`.Select.correlate_except`
+:func:`~.sql.expression.select` now has a method :meth:`.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
stmt = table.update().prefix_with("LOW_PRIORITY", dialect="mysql")
The method is new in addition to those which already existed
-on :func:`.insert`, :func:`.select` and :class:`.Query`.
+on :func:`~.sql.expression.insert`, :func:`~.sql.expression.select` and :class:`.Query`.
.. seealso::
:ticket:`2320`
-:attr:`.Column.key` is honored in the :attr:`.Select.c` attribute of :func:`.select` with :meth:`.Select.apply_labels`
+:attr:`.Column.key` is honored in the :attr:`.Select.c` attribute of :func:`~.sql.expression.select` with :meth:`.Select.apply_labels`
-----------------------------------------------------------------------------------------------------------------------
Users of the expression system know that :meth:`.Select.apply_labels`
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:`.select` construct or other
+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`
where it will be used to render an ``INSERT .. SELECT`` construct::
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:`.Insert` or :class:`.Update` construct is compiled,
+operation occurs when an :class:`~.sql.expression.Insert` or :class:`.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:`.Insert` or :class:`.Update`::
+Similarly, this operation occurs in an :class:`~.sql.expression.Insert` or :class:`.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:`.Insert` or :class:`.Update` statement
+:func:`.bindparam` within an :class:`~.sql.expression.Insert` or :class:`.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.
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:`.select` construct where virtually all components of it
+using a :func:`~.sql.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
Where note also that :func:`.table` and :func:`.column` can now
be imported from "sqlalchemy" without the "sql" part.
-The behavior here applies to :func:`.select` as well as to key methods
+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`.
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:`.select` or :class:`.Query` that refers to some column name or named
+:func:`~.sql.expression.select` or :class:`.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([
--------------------------------------------------------------
Using :meth:`.Insert.from_select` now implies ``inline=True``
-on :func:`.insert`. This helps to fix a bug where an
+on :func:`~.sql.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
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:`.Insert` object, via :func:`sqlalchemy.dialects.postgresql.dml.insert`.
-This :class:`.Insert` subclass adds two new methods :meth:`.Insert.on_conflict_do_update`
+: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
supported by PostgreSQL 9.5 in this area::
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:`.select` object within, as well as the compilation of the :func:`.select`
+:func:`~.sql.expression.select` object within, as well as the compilation of the :func:`~.sql.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.
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:`.Insert` construct that specifies
+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
function is called multiple times, once for each parameter set, however there
was no way to know which subset of keys in
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:`.select` can no longer
-be embedded inside of another :func:`.select` directly, without explicitly
-turning the inner :func:`.select` into a subquery first. This is historically
+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`;
both methods do the same thing. The object returned is now :class:`.Subquery`,
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:`.select` and
+Along with the above change, the general capability of :func:`~.sql.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:`.select` construct to implicitly create subqueries
+ability of the :func:`~.sql.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
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`
hierarchy in SQLAlchemy 2.0, so that the ORM will have a "``select()``"
-construct that extends directly from the existing :func:`.select` object,
+construct that extends directly from the existing :func:`~.sql.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
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:`.select` construct at query execution time and inspects
+algorithm to a :func:`~.sql.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
SELECT objects and derived FROM clauses allow for duplicate columns and column labels
-------------------------------------------------------------------------------------
-This change allows that the :func:`.select` construct now allows for duplicate
+This change allows that the :func:`~.sql.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
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:`.select` uses :meth:`.Select.where` to add
+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
:class:`.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:`.select` gained
+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
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:`.select` does, to
+eventually support production of all the SQL that :func:`~.sql.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:`.select` to be the single way that one constructs a SELECT construct.
+of :func:`~.sql.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.
-For ORM use however, one can construct a :func:`.select` using ORM objects, and
+For ORM use however, one can construct a :func:`~.sql.expression.select` using ORM objects, and
then when delivered to the ``.invoke()`` or ``.execute()`` method of
:class:`.Session`, it will be interpreted appropriately::
:tickets: 4194
Fixed bug where a versioning column specified on a mapper against a
- :func:`.select` construct where the version_id_col itself were against the
+ :func:`~.sql.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:`.select` object no
+ the changes in :ticket:`4617`, by fact that a :func:`~.sql.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.
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:`.select` objects.
+ the role and behavior of :func:`~.sql.expression.select` objects.
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:`.select` construct in the FROM clause of another
- :func:`.select` requires first that it be wrapped in a subquery first,
+ 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`
method, and is now also available through the use of
:meth:`.SelectBase.subquery`. This was usually a requirement in any
:tags: change, orm
:tickets: 4617
- The ORM will now warn when asked to coerce a :func:`.select` construct into
+ The ORM will now warn when asked to coerce a :func:`~.sql.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
as well as within the :func:`.with_polymorphic` function. When a
- :class:`.SelectBase` (which is what's produced by :func:`.select`) or
+ :class:`.SelectBase` (which is what's produced by :func:`~.sql.expression.select`) or
:class:`.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 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:`.select` object or :class:`.Query` object.
+ invoked directly from ` :func:`~.sql.expression.select` object or :class:`.Query` object.
- This change is part of the larger change to convert :func:`.select` objects
+ This change is part of the larger change to convert :func:`~.sql.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: change,engine
:tickets: 4753
- The :func:`.select` construct and related constructs now allow for
+ The :func:`~.sql.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
result.close()
Above, we associate an :class:`.Engine` with a :class:`.MetaData` object using
-the special attribute :attr:`.MetaData.bind`. The :func:`.select` construct produced
+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`.
return func.ST_AsText(col, type_=self)
We can apply the ``Geometry`` type into :class:`.Table` metadata
-and use it in a :func:`.select` construct::
+and use it in a :func:`~.sql.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:`.select` against a :func:`.label` of our expression, the string
+a :func:`~.sql.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')]))
For a single statement that is being executed using "executemany" style, e.g.
with multiple parameter sets passed to :meth:`.Connection.execute`, the user-
defined function is called once for each set of parameters. For the use case of
-a multi-valued :class:`.Insert` construct (e.g. with more than one VALUES
+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
is also called once for each set of parameters.
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:`.Insert` construct that specifies the
+may not be used. An :class:`~.sql.expression.Insert` construct that specifies the
:paramref:`~.expression.insert.inline` flag will always render default expressions
inline.
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:`.Insert`
+: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
returned.
========================
INSERT, UPDATE and DELETE statements build on a hierarchy starting
-with :class:`.UpdateBase`. The :class:`.Insert` and :class:`.Update`
+with :class:`.UpdateBase`. The :class:`~.sql.expression.Insert` and :class:`.Update`
constructs build on the intermediary :class:`.ValuesBase`.
.. module:: sqlalchemy.sql.expression
statement.
The "executemany" style of invocation is available for each of the
-:func:`.insert`, :func:`.update` and :func:`.delete` constructs.
+:func:`~.sql.expression.insert`, :func:`.update` and :func:`.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:`.select` function:
+statements is the :func:`~.sql.expression.select` function:
.. sourcecode:: pycon+sql
FROM users
()
-Above, we issued a basic :func:`.select` call, placing the ``users`` table
+Above, we issued a basic :func:`~.sql.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
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:`.select` construct only has a list
+and a "FROM table" part, our :func:`~.sql.expression.select` construct only has a list
containing columns. How does this work ? Let's try putting *two* tables into
-our :func:`.select` statement:
+our :func:`~.sql.expression.select` statement:
.. 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:`.select`
+So that looks a lot better, we added an expression to our :func:`~.sql.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:`.select`
+like the :class:`~.expression.Insert` and :func:`~.sql.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
============
-We'd like to show off some of our operators inside of :func:`.select`
+We'd like to show off some of our operators inside of :func:`~.sql.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_`,
(', ', 'm', 'z', '%@aol.com', '%@msn.com')
[(u'Wendy Williams, wendy@aol.com',)]
-The way that we can build up a :func:`.select` construct through successive
+The way that we can build up a :func:`~.sql.expression.select` construct through successive
method calls is called :term:`method chaining`.
.. _sqlexpression_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:`.select` object. The :func:`~.expression.select` construct provides the "geometry"
+:func:`~.sql.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:
{stop}[(u'Wendy Williams, wendy@aol.com',)]
.. versionchanged:: 1.0.0
- The :func:`.select` construct emits warnings when string SQL
+ The :func:`~.sql.expression.select` construct emits warnings when string SQL
fragments are coerced to :func:`.text`, and :func:`.text` should
be used explicitly. See :ref:`migration_2992` for background.
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:`.select` construct, we can refer to it directly by passing the
+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`,
among others. This will refer to the named label and also prevent the
expression from being rendered twice. Label names that resolve to columns
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:`.select` construct:
+``addresses``, and then use them both within a :func:`~.sql.expression.select` construct:
.. sourcecode:: pycon+sql
also a :class:`.FromClause` object that may be part of any enclosing SELECT
using the same techniques one would use for a :class:`.Alias`.
-We can self-join the ``users`` table back to the :func:`.select` we've created
+We can self-join the ``users`` table back to the :func:`~.sql.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:`.select` construct. But if we want to make a
+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
join:
... )
users JOIN addresses ON addresses.email_address LIKE users.name || :name_1
-When we create a :func:`.select` construct, SQLAlchemy looks around at the
+When we create a :func:`~.sql.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:
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:`.select` construct can be modified to act as a
+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:
which is an adapter around the original :class:`.~expression.Select`
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:`.select`:
+other column within another :func:`~.sql.expression.select`:
.. sourcecode:: pycon+sql
--------------------------------------------------------------------------------------
This refers to a change made as of SQLAlchemy 1.4 where a SELECT statement as generated
-by a function such as :func:`.select`, but also including things like unions and textual
+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
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
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:`.select` constructs and the like, **does not** need any primary key
+ :func:`~.sql.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).
The ``str()`` builtin, or an equivalent, can be invoked on ORM
:class:`.Query` object as well as any statement such as that of
-:func:`.select`, :func:`.insert` etc. and also any expression fragment, such
+:func:`~.sql.expression.select`, :func:`~.sql.expression.insert` etc. and also any expression fragment, such
as::
>>> from sqlalchemy import column
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:`.select` object as well. While it may appear that a "single table
+ :func:`~.sql.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 ``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:`.select` which links a set of column objects
+Below it is linked to a :func:`~.sql.expression.select` which links a set of column objects
to a string SQL statement::
# label the columns of the addresses table
lastname = Column(String(50))
fullname = column_property(firstname + " " + lastname)
-Correlated subqueries may be used as well. Below we use the :func:`.select`
+Correlated subqueries may be used as well. Below we use the :func:`~.sql.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:`.select` construct like the following::
+In the above example, we define a :func:`~.sql.expression.select` construct like the following::
select([func.count(Address.id)]).\
where(Address.user_id==id).\
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:`.select` may be omitted from the FROM list (that is, correlated
+FROM clause of this :func:`~.sql.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
---------------------------------------------
The bulk methods offer performance that under particular circumstances
-can be close to that of using the core :class:`.Insert` and
+can be close to that of using the core :class:`~.sql.expression.Insert` and
:class:`.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
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:`.Insert` construct; if the
+ automatically when using a core :class:`~.sql.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
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:`.insert`
+detect when an INSERT construct, created using a core :func:`~.sql.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
semicolon. This is the same behavior as was provided by the
``use_batch_mode=True`` flag.
-* ``'values'``- For Core :func:`.insert` constructs only (including those
+* ``'values'``- For Core :func:`~.sql.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:`.insert` construct where the format is predictable. For all other
+ :func:`~.sql.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
corresponding to the list of primary key columns
in the target table.
- This only applies to single row :func:`.insert`
+ This only applies to single row :func:`~.sql.expression.insert`
constructs which did not explicitly specify
:meth:`.Insert.returning`.
@property
def selectable(self):
- """The :func:`.select` construct this :class:`.Mapper` selects from
- by default.
+ """The :func:`~.sql.expression.select` construct this
+ :class:`.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
: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:`.select` construct is executed), or via string names of
- the form ``<tablename>_<colname>``.
+ when a :func:`~.sql.expression.select` construct is executed), or
+
via string names of the form ``<tablename>_<colname>``.
"""
pk_cols = self.primary_key
to all columns.
:param reduce_columns: if True, :meth:`.Select.reduce_columns` will
- be called on the resulting :func:`.select` construct,
+ be called on the resulting :func:`~.sql.expression.select` construct,
to remove same-named columns where one also refers to the other
via foreign key or WHERE clause equivalence.
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:`.select` constructs, with either the one
- or two-argument forms::
+ :class:`.Table` constructs and other selectables such as :func:`.alias`
+ and :func:`~.sql.expression.select` constructs, with either the one or
+ two-argument forms::
addresses_q = select([Address.user_id]).\
where(Address.email_address.endswith("@bar.com")).\
session.query(MyClass, my_alias).filter(MyClass.id > my_alias.id)
- 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:`.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.
+ 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.
+ 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:`.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 ORM-mapped in this case.
+ :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
+ 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.
: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:`.select` construct that
- is compatible with the mapping. By default, a simple anonymous
- alias of the mapped table is generated.
+ to which the class is mapped, or to a :func:`~.sql.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
"""Optional :class:`.CompileState` object that maintains additional
state used by the compiler.
- Major executable objects such as :class:`.Insert`, :class:`.Update`,
- :class:`.Delete`, :class:`.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 processing.
+ Major executable objects such as :class:`~.sql.expression.Insert`,
+ :class:`.Update`, :class:`.Delete`, :class:`.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
+ processing.
.. versionadded:: 1.4
# This module is part of SQLAlchemy and is released under
# the MIT License: http://www.opensource.org/licenses/mit-license.php
"""
-Provide :class:`.Insert`, :class:`.Update` and :class:`.Delete`.
+Provide :class:`~.sql.expression.Insert`, :class:`.Update` and
+:class:`.Delete`.
"""
from sqlalchemy.types import NullType
r"""specify a fixed VALUES clause for an INSERT statement, or the SET
clause for an UPDATE.
- Note that the :class:`.Insert` and :class:`.Update` constructs support
+ Note that the :class:`~.sql.expression.Insert` and :class:`.Update`
+ constructs support
per-execution time formatting of the VALUES and/or SET clauses,
based on the arguments passed to :meth:`.Connection.execute`.
However, the :meth:`.ValuesBase.values` method can be used to "fix" a
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:`.Insert` or an :class:`.Update`
- construct.
+ based on whether this is an :class:`~.sql.expression.Insert` or an
+ :class:`.Update` construct.
- For either an :class:`.Insert` or :class:`.Update` construct, a
- single dictionary can be passed, which works the same as that of
- the kwargs form::
+ For either an :class:`~.sql.expression.Insert` or :class:`.Update`
+ construct, a single dictionary can be passed, which works the same as
+ that of the kwargs form::
users.insert().values({"name": "some name"})
users.update().values({"name": "some new name"})
- Also for either form but more typically for the :class:`.Insert`
- construct, a tuple that contains an entry for every column in the
- table is also accepted::
+ Also for either form but more typically for the
+ :class:`~.sql.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:`.Insert` construct also supports being passed a list
- of dictionaries or full-table-tuples, which on the server will
- render the less common SQL syntax of "multiple values" - this
- syntax is supported on backends such as SQLite, PostgreSQL, MySQL,
- but not necessarily others::
+ The :class:`~.sql.expression.Insert` construct also supports being
+ passed a list of dictionaries or full-table-tuples, which on the
+ server will render the less common SQL syntax of "multiple values" -
+ this syntax is supported on backends such as SQLite, PostgreSQL,
+ MySQL, but not necessarily others::
users.insert().values([
{"name": "some name"},
class Insert(ValuesBase):
"""Represent an INSERT construct.
- The :class:`.Insert` object is created using the
+ The :class:`~.sql.expression.Insert` object is created using the
:func:`~.expression.insert()` function.
.. seealso::
return_defaults=False,
**dialect_kw
):
- """Construct an :class:`.Insert` object.
+ """Construct an :class:`~.sql.expression.Insert` object.
Similar functionality is available via the
:meth:`~.TableClause.insert` method on
: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:`.Insert` construct will also
- dynamically render the VALUES clause at execution time based on
- the parameters passed to :meth:`.Connection.execute`.
+ Can be omitted entirely; a :class:`~.sql.expression.Insert` construct
+ will also dynamically render the VALUES clause at execution time
+ based on the parameters passed to :meth:`.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:`.Insert` construct "inline" .
+ """Make this :class:`~.sql.expression.Insert` construct "inline" .
When set, no attempt will be made to retrieve the
SQL-generated default values to be provided within the statement;
@_generative
def from_select(self, names, select, include_defaults=True):
- """Return a new :class:`.Insert` construct which represents
+ """Return a new :class:`~.sql.expression.Insert` construct which represents
an ``INSERT...FROM SELECT`` statement.
e.g.::
:param names: a sequence of string column names or :class:`.Column`
objects representing the target columns.
- :param select: a :func:`.select` construct, :class:`.FromClause`
+ :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
columns returned from this FROM clause should correspond to the
* a literal data value (i.e. string, number, etc.)
* a SQL expression, such as a related :class:`.Column`,
- a scalar-returning :func:`.select` construct,
+ a scalar-returning :func:`~.sql.expression.select` construct,
etc.
- When combining :func:`.select` constructs within the values
- clause of an :func:`.update` construct,
- the subquery represented by the :func:`.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::
+ when combining :func:`~.sql.expression.select` constructs within the
+ values clause of an :func:`.update` construct, the subquery represented
+ by the :func:`~.sql.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::
users.update().values(
name=select([addresses.c.email_address]).\
# type: (Optional[Any]) -> ClauseElement
"""Apply a 'grouping' to this :class:`.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:`.select` constructs when placed into
- the FROM clause of another :func:`.select`. (Note that
- subqueries should be normally created using the
- :meth:`.Select.alias` method, as many platforms require
- nested SELECT statements to be named).
+ 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`
+ 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
+ platforms require nested SELECT statements to be named).
As expressions are composed together, the application of
:meth:`self_group` is automatic - end-user code should never
while the placeholder ``:name_1`` is rendered in the appropriate form
for the target database, in this case the PostgreSQL database.
- Similarly, :func:`.bindparam` is invoked automatically
- when working with :term:`CRUD` statements as far as the "VALUES"
- portion is concerned. The :func:`.insert` construct produces an
- ``INSERT`` expression which will, at statement execution time,
- generate bound placeholders based on the arguments passed, as in::
+ 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
+ ``INSERT`` expression which will, at statement execution time, generate
+ bound placeholders based on the arguments passed, as in::
stmt = users_table.insert()
result = connection.execute(stmt, name='Wendy')
INSERT INTO "user" (name) VALUES (%(name)s)
{'name': 'Wendy'}
- The :class:`.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.
+ The :class:`~.sql.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.
:param key:
the key (e.g. the name) for this bind param.
SELECT id, name FROM user
Once constructed, :func:`.column` may be used like any other SQL
- expression element such as within :func:`.select` constructs::
+ expression element such as within :func:`~.sql.expression.select`
+ constructs::
from sqlalchemy.sql import column
an anonymously named column.
An interim approach to providing named columns for a function
- as a FROM clause is to build a :func:`.select` with the
+ as a FROM clause is to build a :func:`~.sql.expression.select` with the
desired columns::
from sqlalchemy.sql import column
.. versionadded:: 1.3 "expanding" bound parameters now support
empty lists
- * a :func:`.select` construct, which is usually a correlated
- scalar select::
+ * a :func:`~.sql.expression.select` construct, which is usually a
+ correlated scalar select::
stmt.where(
column.in_(
WHERE COL IN (SELECT othertable.y
FROM othertable WHERE othertable.x = table.x)
- :param other: a list of literals, a :func:`.select` construct,
- or a :func:`.bindparam` construct that includes the
+ :param other: a list of literals, a :func:`~.sql.expression.select`
+ construct, or a :func:`.bindparam` construct that includes the
:paramref:`.bindparam.expanding` flag set to True.
"""
:param name: the alias name for the subquery
:param \*args, \**kwargs: all other arguments are passed through to the
- :func:`.select` function.
+ :func:`~.sql.expression.select` function.
"""
return Select(*args, **kwargs).subquery(alias)
clause of a ``SELECT`` statement.
The most common forms of :class:`.FromClause` are the
- :class:`.Table` and the :func:`.select` constructs. Key
+ :class:`.Table` and the :func:`~.sql.expression.select` constructs. Key
features common to all :class:`.FromClause` objects include:
* a :attr:`.c` collection, which provides per-name access to a collection
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:`.select` function, the
- :meth:`.SelectBase.alias` method returns an :class:`.Alias` or
- similar object which represents a named, parenthesized subquery.
+ 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,
+ parenthesized subquery.
When an :class:`.Alias` is created from a :class:`.Table` object,
this has the effect of the table being rendered
as ``tablename AS aliasname`` in a SELECT statement.
- For :func:`.select` objects, the effect is that of creating a named
- subquery, i.e. ``(select ...) AS aliasname``.
+ For :func:`~.sql.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
to use in the rendered SQL. If blank, an "anonymous" name
"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:`.select` "
+ ":meth:`.Select.scalar_subquery` method of the "
+ ":func:`~.sql.expression.select` "
"construct before constructing a subquery object, or with the ORM "
"use the :meth:`.Query.scalar_subquery` method.",
)
@util.preload_module("sqlalchemy.sql.dml")
def insert(self, values=None, inline=False, **kwargs):
- """Generate an :func:`.insert` construct against this
+ """Generate an :func:`~.sql.expression.insert` construct against this
:class:`.TableClause`.
E.g.::
table.insert().values(name='foo')
- See :func:`.insert` for argument and usage information.
+ See :func:`~.sql.expression.insert` for argument and usage information.
"""
return util.preloaded.sql_dml.Insert(
.. seealso::
:ref:`coretutorial_selecting` - Core Tutorial description of
- :func:`.select`.
+ :func:`~.sql.expression.select`.
:param \*entities:
Entities to SELECT from. For Core usage, this is typically a series
.. seealso::
:ref:`coretutorial_selecting` - Core Tutorial description of
- :func:`.select`.
+ :func:`~.sql.expression.select`.
:param columns:
A list of :class:`.ColumnElement` or :class:`.FromClause`
.. note::
The :paramref:`.select.columns` parameter is not available
- in the method form of :func:`.select`, e.g.
+ in the method form of :func:`~.sql.expression.select`, e.g.
:meth:`.FromClause.select`.
.. seealso::
@_generative
def with_only_columns(self, columns):
- r"""Return a new :func:`.select` construct with its columns
+ r"""Return a new :func:`~.sql.expression.select` construct with its columns
clause replaced with the given columns.
This method is exactly equivalent to as if the original
- :func:`.select` had been called with the given columns
+ :func:`~.sql.expression.select` had been called with the given columns
clause. I.e. a statement::
s = select([table1.c.a, table1.c.b])
>>> print(s2)
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:`.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:`.select` construct, not those which are available
- from the ``.c`` collection of that :func:`.select`. That
- is::
+ 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`
+ 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`
+ construct, not those which are available from the ``.c`` collection of
+ that :func:`~.sql.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:`.select` construct is essentially being
- asked to select both from ``table1`` as well as itself.
+ Since the :func:`~.sql.expression.select` construct is essentially
+ being asked to select both from ``table1`` as well as itself.
"""
self._reset_memoizations()
@_generative
def select_from(self, *froms):
- r"""return a new :func:`.select` construct with the
+ r"""return a new :func:`~.sql.expression.select` construct with the
given FROM expression(s)
merged into its list of FROM objects.
must be applied first which provides for the necessary parenthesization
required by SQL.
- For a :func:`.select` construct, the collection here is exactly what
- would be rendered inside the "SELECT" statement, and the
+ For a :func:`~.sql.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
given, e.g.::
dp_dml_multi_values = symbol("DML_MV")
"""visit the values() multi-valued list of dictionaries of an
- :class:`.Insert` object.
+ :class:`~.sql.expression.Insert` object.
"""
identity = C4DAFEE1
[flake8]
-show-source = true
+show-source = false
enable-extensions = G
# E203 is due to https://github.com/PyCQA/pycodestyle/issues/373
ignore =
projects / thirdparty / sqlalchemy / sqlalchemy.git / commitdiff
