operators.collate, type_=expr.type)
def between(expr, lower_bound, upper_bound):
- """Produce ``BETWEEN`` predicate clause.
+ """Produce a ``BETWEEN`` predicate clause.
E.g.::
class BindParameter(ColumnElement):
- """Represent a "bound expression" for usage in a SQL construct.
+ """Represent a "bound expression".
:class:`.BindParameter` is invoked explicitly using the
:func:`.bindparam` function, as in::
isoutparam=False,
_compared_to_operator=None,
_compared_to_type=None):
- """Produce a "bound expression" for usage in a SQL construct.
+ """Produce a "bound expression".
The return value is an instance of :class:`.BindParameter`; this
is a :class:`.ColumnElement` subclass which represents a so-called
@classmethod
def and_(cls, *clauses):
- """Produce a conjunction of clauses joined by ``AND``.
+ """Produce a conjunction of expressions joined by ``AND``.
E.g.::
@classmethod
def or_(cls, *clauses):
- """Produce a conjunction of clauses joined by ``OR``.
+ """Produce a conjunction of expressions joined by ``OR``.
E.g.::
__visit_name__ = 'case'
def __init__(self, whens, value=None, else_=None):
- """Produce a ``CASE`` expression for usage in a SQL construct.
+ """Produce a ``CASE`` expression.
The ``CASE`` construct in SQL is a conditional object that
acts somewhat analogously to an "if/then" construct in other
(where it is called the 'operator') or right (where it is called the
'modifier') of the column expression.
+ :class:`.UnaryExpression` is the basis for several unary operators
+ including those used by :func:`.desc`, :func:`.asc`, :func:`.distinct`,
+ :func:`.nullsfirst` and :func:`.nullslast`.
+
"""
__visit_name__ = 'unary'
@classmethod
def _create_desc(cls, column):
- """Return a descending ``ORDER BY`` clause element.
+ """Produce a descending ``ORDER BY`` clause element.
e.g.::
@classmethod
def _create_asc(cls, column):
- """Return an ascending ``ORDER BY`` clause element.
+ """Produce an ascending ``ORDER BY`` clause element.
e.g.::
class ColumnClause(Immutable, ColumnElement):
- """Represents a generic column expression from any textual string.
+ """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::
+
+ from sqlalchemy.sql import column
+
+ id, name = column("id"), column("name")
+ stmt = select([id, name]).select_from("user")
+
+ The above statement would produce SQL like::
+
+ 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
that :class:`.Column` does, so in that sense is a "lightweight" version
of :class:`.Column`.
- :class:`.ColumnClause` is constructed by itself typically via
- the :func:`~.expression.column` function. The datatype is optional.
- It may be placed directly
- into constructs such as :func:`.select` constructs::
+ Full details on :class:`.ColumnClause` usage is at :func:`.column`.
- from sqlalchemy.sql import column, select
+ .. seealso::
- c1, c2 = column("c1"), column("c2")
- s = select([c1, c2]).where(c1==5)
+ :func:`.column`
- There is also a variant on :func:`~.expression.column` known
- as :func:`~.expression.literal_column` - the difference is that
- in the latter case, the string value is assumed to be an exact
- expression, rather than a column name, so that no quoting rules
- or similar are applied::
+ :class:`.Column`
- from sqlalchemy.sql import literal_column, select
+ """
+ __visit_name__ = 'column'
- s = select([literal_column("5 + 7")])
+ onupdate = default = server_default = server_onupdate = None
- :class:`.ColumnClause` can also be used in a table-like
- fashion by combining the :func:`~.expression.column` function
- with the :func:`~.expression.table` function, to produce
- a "lightweight" form of table metadata::
+ _memoized_property = util.group_expirable_memoized_property()
- from sqlalchemy.sql import table, column
+ def __init__(self, text, type_=None, is_literal=False, _selectable=None):
+ """Produce a :class:`.ColumnClause` object.
- user = table("user",
- column("id"),
- column("name"),
- column("description"),
- )
+ The :class:`.ColumnClause` is a lightweight analogue to the
+ :class:`.Column` class. The :func:`.column` function can
+ be invoked with just a name alone, as in::
- The above construct can be created in an ad-hoc fashion and is
- not associated with any :class:`.schema.MetaData`, unlike it's
- more full fledged :class:`.schema.Table` counterpart.
+ from sqlalchemy.sql import column
- .. seealso::
+ id, name = column("id"), column("name")
+ stmt = select([id, name]).select_from("user")
- :class:`.Column`
+ The above statement would produce SQL like::
- :ref:`metadata_toplevel`
+ SELECT id, name FROM user
- """
- __visit_name__ = 'column'
+ Once constructed, :func:`.column` may be used like any other SQL expression
+ element such as within :func:`.select` constructs::
- onupdate = default = server_default = server_onupdate = None
+ from sqlalchemy.sql import column
- _memoized_property = util.group_expirable_memoized_property()
+ id, name = column("id"), column("name")
+ stmt = select([id, name]).select_from("user")
- def __init__(self, text, type_=None, is_literal=False, _selectable=None):
- """Construct a :class:`.ColumnClause` object.
+ The text handled by :func:`.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.
+
+ :func:`.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
+ a working table construct with minimal boilerplate::
+
+ from sqlalchemy.sql import table, column
+
+ user = table("user",
+ column("id"),
+ column("name"),
+ column("description"),
+ )
+
+ stmt = select([user.c.description]).where(user.c.name == 'wendy')
+
+ A :func:`.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.
:param text: the text of the element.
: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 is usually used to create such a
- :class:`.ColumnClause`.
+ :func:`.literal_column()` function essentially invokes :func:`.column`
+ while passing ``is_literal=True``.
+
+ .. seealso::
+
+ :class:`.Column`
- :param text: the name of the column. Quoting rules will be applied
- to the clause like any other column name. For textual column constructs
- that are not to be quoted, use the :func:`literal_column` function.
+ :func:`.literal_column`
- :param type\_: an optional :class:`~sqlalchemy.types.TypeEngine` object
- which will provide result-set translation for this column.
+ :func:`.text`
+ :ref:`metadata_toplevel`
"""
projects / thirdparty / sqlalchemy / sqlalchemy.git / commitdiff
