File: //usr/share/doc/python-sqlalchemy-0.9.8/doc/core/sqlelement.html
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>
Column Elements and Expressions
—
SQLAlchemy 0.9 Documentation
</title>
<!-- begin iterate through SQLA + sphinx environment css_files -->
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<link rel="stylesheet" href="../_static/docs.css" type="text/css" />
<link rel="stylesheet" href="../_static/sphinx_paramlinks.css" type="text/css" />
<link rel="stylesheet" href="../_static/changelog.css" type="text/css" />
<!-- end iterate through SQLA + sphinx environment css_files -->
<!-- begin layout.mako headers -->
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../',
VERSION: '0.9.8',
COLLAPSE_MODINDEX: false,
FILE_SUFFIX: '.html'
};
</script>
<!-- begin iterate through sphinx environment script_files -->
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<!-- end iterate through sphinx environment script_files -->
<script type="text/javascript" src="../_static/detectmobile.js"></script>
<script type="text/javascript" src="../_static/init.js"></script>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="top" title="SQLAlchemy 0.9 Documentation" href="../index.html" />
<link rel="up" title="SQL Statements and Expressions API" href="expression_api.html" />
<link rel="next" title="Selectables, Tables, FROM objects" href="selectable.html" />
<link rel="prev" title="SQL Statements and Expressions API" href="expression_api.html" />
<!-- end layout.mako headers -->
</head>
<body>
<div id="docs-container">
<div id="docs-top-navigation-container" class="body-background">
<div id="docs-header">
<div id="docs-version-header">
Release: <span class="version-num">0.9.8</span> | Release Date: October 13, 2014
</div>
<h1>SQLAlchemy 0.9 Documentation</h1>
</div>
</div>
<div id="docs-body-container">
<div id="fixed-sidebar" class="withsidebar">
<div id="docs-sidebar-popout">
<h3><a href="../index.html">SQLAlchemy 0.9 Documentation</a></h3>
<p id="sidebar-paginate">
<a href="expression_api.html" title="SQL Statements and Expressions API">Up</a> |
<a href="expression_api.html" title="SQL Statements and Expressions API">Prev</a> |
<a href="selectable.html" title="Selectables, Tables, FROM objects">Next</a>
</p>
<p id="sidebar-topnav">
<a href="../index.html">Contents</a> |
<a href="../genindex.html">Index</a>
</p>
<div id="sidebar-search">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" size="12" /> <input type="submit" value="Search" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<div id="docs-sidebar">
<h3><a href="#">
Column Elements and Expressions
</a></h3>
<ul>
<li><a class="reference internal" href="#">Column Elements and Expressions</a></li>
</ul>
</div>
</div>
<div id="docs-body" class="withsidebar" >
<div class="section" id="module-sqlalchemy.sql.expression">
<span id="column-elements-and-expressions"></span><h1>Column Elements and Expressions<a class="headerlink" href="#module-sqlalchemy.sql.expression" title="Permalink to this headline">¶</a></h1>
<p>The most fundamental part of the SQL expression API are the “column elements”,
which allow for basic SQL expression support. The core of all SQL expression
constructs is the <a class="reference internal" href="#sqlalchemy.sql.expression.ClauseElement" title="sqlalchemy.sql.expression.ClauseElement"><tt class="xref py py-class docutils literal"><span class="pre">ClauseElement</span></tt></a>, which is the base for several
sub-branches. The <a class="reference internal" href="#sqlalchemy.sql.expression.ColumnElement" title="sqlalchemy.sql.expression.ColumnElement"><tt class="xref py py-class docutils literal"><span class="pre">ColumnElement</span></tt></a> class is the fundamental unit
used to construct any kind of typed SQL expression.</p>
<dl class="function">
<dt id="sqlalchemy.sql.expression.and_">
<tt class="descclassname">sqlalchemy.sql.expression.</tt><tt class="descname">and_</tt><big>(</big><em>*clauses</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.and_" title="Permalink to this definition">¶</a></dt>
<dd><p>Produce a conjunction of expressions joined by <tt class="docutils literal"><span class="pre">AND</span></tt>.</p>
<p>E.g.:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="kn">import</span> <span class="n">and_</span>
<span class="n">stmt</span> <span class="o">=</span> <span class="n">select</span><span class="p">([</span><span class="n">users_table</span><span class="p">])</span><span class="o">.</span><span class="n">where</span><span class="p">(</span>
<span class="n">and_</span><span class="p">(</span>
<span class="n">users_table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">name</span> <span class="o">==</span> <span class="s">'wendy'</span><span class="p">,</span>
<span class="n">users_table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">enrolled</span> <span class="o">==</span> <span class="bp">True</span>
<span class="p">)</span>
<span class="p">)</span></pre></div>
</div>
<p>The <a class="reference internal" href="#sqlalchemy.sql.expression.and_" title="sqlalchemy.sql.expression.and_"><tt class="xref py py-func docutils literal"><span class="pre">and_()</span></tt></a> conjunction is also available using the
Python <tt class="docutils literal"><span class="pre">&</span></tt> operator (though note that compound expressions
need to be parenthesized in order to function with Python
operator precedence behavior):</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">stmt</span> <span class="o">=</span> <span class="n">select</span><span class="p">([</span><span class="n">users_table</span><span class="p">])</span><span class="o">.</span><span class="n">where</span><span class="p">(</span>
<span class="p">(</span><span class="n">users_table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">name</span> <span class="o">==</span> <span class="s">'wendy'</span><span class="p">)</span> <span class="o">&</span>
<span class="p">(</span><span class="n">users_table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">enrolled</span> <span class="o">==</span> <span class="bp">True</span><span class="p">)</span>
<span class="p">)</span></pre></div>
</div>
<p>The <a class="reference internal" href="#sqlalchemy.sql.expression.and_" title="sqlalchemy.sql.expression.and_"><tt class="xref py py-func docutils literal"><span class="pre">and_()</span></tt></a> operation is also implicit in some cases;
the <a class="reference internal" href="selectable.html#sqlalchemy.sql.expression.Select.where" title="sqlalchemy.sql.expression.Select.where"><tt class="xref py py-meth docutils literal"><span class="pre">Select.where()</span></tt></a> method for example can be invoked multiple
times against a statement, which will have the effect of each
clause being combined using <a class="reference internal" href="#sqlalchemy.sql.expression.and_" title="sqlalchemy.sql.expression.and_"><tt class="xref py py-func docutils literal"><span class="pre">and_()</span></tt></a>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">stmt</span> <span class="o">=</span> <span class="n">select</span><span class="p">([</span><span class="n">users_table</span><span class="p">])</span><span class="o">.</span>\
<span class="n">where</span><span class="p">(</span><span class="n">users_table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">name</span> <span class="o">==</span> <span class="s">'wendy'</span><span class="p">)</span><span class="o">.</span>\
<span class="n">where</span><span class="p">(</span><span class="n">users_table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">enrolled</span> <span class="o">==</span> <span class="bp">True</span><span class="p">)</span></pre></div>
</div>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p class="last"><a class="reference internal" href="#sqlalchemy.sql.expression.or_" title="sqlalchemy.sql.expression.or_"><tt class="xref py py-func docutils literal"><span class="pre">or_()</span></tt></a></p>
</div>
</dd></dl>
<dl class="function">
<dt id="sqlalchemy.sql.expression.asc">
<tt class="descclassname">sqlalchemy.sql.expression.</tt><tt class="descname">asc</tt><big>(</big><em>column</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.asc" title="Permalink to this definition">¶</a></dt>
<dd><p>Produce an ascending <tt class="docutils literal"><span class="pre">ORDER</span> <span class="pre">BY</span></tt> clause element.</p>
<p>e.g.:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="kn">import</span> <span class="n">asc</span>
<span class="n">stmt</span> <span class="o">=</span> <span class="n">select</span><span class="p">([</span><span class="n">users_table</span><span class="p">])</span><span class="o">.</span><span class="n">order_by</span><span class="p">(</span><span class="n">asc</span><span class="p">(</span><span class="n">users_table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">name</span><span class="p">))</span></pre></div>
</div>
<p>will produce SQL as:</p>
<div class="highlight-python"><pre>SELECT id, name FROM user ORDER BY name ASC</pre>
</div>
<p>The <a class="reference internal" href="#sqlalchemy.sql.expression.asc" title="sqlalchemy.sql.expression.asc"><tt class="xref py py-func docutils literal"><span class="pre">asc()</span></tt></a> function is a standalone version of the
<a class="reference internal" href="#sqlalchemy.sql.expression.ColumnElement.asc" title="sqlalchemy.sql.expression.ColumnElement.asc"><tt class="xref py py-meth docutils literal"><span class="pre">ColumnElement.asc()</span></tt></a> method available on all SQL expressions,
e.g.:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">stmt</span> <span class="o">=</span> <span class="n">select</span><span class="p">([</span><span class="n">users_table</span><span class="p">])</span><span class="o">.</span><span class="n">order_by</span><span class="p">(</span><span class="n">users_table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">name</span><span class="o">.</span><span class="n">asc</span><span class="p">())</span></pre></div>
</div>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><span class="target" id="sqlalchemy.sql.expression.asc.params.column"></span><strong>column</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.asc.params.column">¶</a> – A <a class="reference internal" href="#sqlalchemy.sql.expression.ColumnElement" title="sqlalchemy.sql.expression.ColumnElement"><tt class="xref py py-class docutils literal"><span class="pre">ColumnElement</span></tt></a> (e.g. scalar SQL expression)
with which to apply the <a class="reference internal" href="#sqlalchemy.sql.expression.asc" title="sqlalchemy.sql.expression.asc"><tt class="xref py py-func docutils literal"><span class="pre">asc()</span></tt></a> operation.</td>
</tr>
</tbody>
</table>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p><a class="reference internal" href="#sqlalchemy.sql.expression.desc" title="sqlalchemy.sql.expression.desc"><tt class="xref py py-func docutils literal"><span class="pre">desc()</span></tt></a></p>
<p><a class="reference internal" href="#sqlalchemy.sql.expression.nullsfirst" title="sqlalchemy.sql.expression.nullsfirst"><tt class="xref py py-func docutils literal"><span class="pre">nullsfirst()</span></tt></a></p>
<p><a class="reference internal" href="#sqlalchemy.sql.expression.nullslast" title="sqlalchemy.sql.expression.nullslast"><tt class="xref py py-func docutils literal"><span class="pre">nullslast()</span></tt></a></p>
<p class="last"><a class="reference internal" href="selectable.html#sqlalchemy.sql.expression.Select.order_by" title="sqlalchemy.sql.expression.Select.order_by"><tt class="xref py py-meth docutils literal"><span class="pre">Select.order_by()</span></tt></a></p>
</div>
</dd></dl>
<dl class="function">
<dt id="sqlalchemy.sql.expression.between">
<tt class="descclassname">sqlalchemy.sql.expression.</tt><tt class="descname">between</tt><big>(</big><em>expr</em>, <em>lower_bound</em>, <em>upper_bound</em>, <em>symmetric=False</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.between" title="Permalink to this definition">¶</a></dt>
<dd><p>Produce a <tt class="docutils literal"><span class="pre">BETWEEN</span></tt> predicate clause.</p>
<p>E.g.:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="kn">import</span> <span class="n">between</span>
<span class="n">stmt</span> <span class="o">=</span> <span class="n">select</span><span class="p">([</span><span class="n">users_table</span><span class="p">])</span><span class="o">.</span><span class="n">where</span><span class="p">(</span><span class="n">between</span><span class="p">(</span><span class="n">users_table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">id</span><span class="p">,</span> <span class="mi">5</span><span class="p">,</span> <span class="mi">7</span><span class="p">))</span></pre></div>
</div>
<p>Would produce SQL resembling:</p>
<div class="highlight-python"><pre>SELECT id, name FROM user WHERE id BETWEEN :id_1 AND :id_2</pre>
</div>
<p>The <a class="reference internal" href="#sqlalchemy.sql.expression.between" title="sqlalchemy.sql.expression.between"><tt class="xref py py-func docutils literal"><span class="pre">between()</span></tt></a> function is a standalone version of the
<a class="reference internal" href="#sqlalchemy.sql.expression.ColumnElement.between" title="sqlalchemy.sql.expression.ColumnElement.between"><tt class="xref py py-meth docutils literal"><span class="pre">ColumnElement.between()</span></tt></a> method available on all
SQL expressions, as in:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">stmt</span> <span class="o">=</span> <span class="n">select</span><span class="p">([</span><span class="n">users_table</span><span class="p">])</span><span class="o">.</span><span class="n">where</span><span class="p">(</span><span class="n">users_table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">id</span><span class="o">.</span><span class="n">between</span><span class="p">(</span><span class="mi">5</span><span class="p">,</span> <span class="mi">7</span><span class="p">))</span></pre></div>
</div>
<p>All arguments passed to <a class="reference internal" href="#sqlalchemy.sql.expression.between" title="sqlalchemy.sql.expression.between"><tt class="xref py py-func docutils literal"><span class="pre">between()</span></tt></a>, including the left side
column expression, are coerced from Python scalar values if a
the value is not a <a class="reference internal" href="#sqlalchemy.sql.expression.ColumnElement" title="sqlalchemy.sql.expression.ColumnElement"><tt class="xref py py-class docutils literal"><span class="pre">ColumnElement</span></tt></a> subclass. For example,
three fixed values can be compared as in:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">print</span><span class="p">(</span><span class="n">between</span><span class="p">(</span><span class="mi">5</span><span class="p">,</span> <span class="mi">3</span><span class="p">,</span> <span class="mi">7</span><span class="p">))</span></pre></div>
</div>
<p>Which would produce:</p>
<div class="highlight-python"><pre>:param_1 BETWEEN :param_2 AND :param_3</pre>
</div>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><span class="target" id="sqlalchemy.sql.expression.between.params.expr"></span><strong>expr</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.between.params.expr">¶</a> – a column expression, typically a <a class="reference internal" href="#sqlalchemy.sql.expression.ColumnElement" title="sqlalchemy.sql.expression.ColumnElement"><tt class="xref py py-class docutils literal"><span class="pre">ColumnElement</span></tt></a>
instance or alternatively a Python scalar expression to be coerced
into a column expression, serving as the left side of the <tt class="docutils literal"><span class="pre">BETWEEN</span></tt>
expression.</li>
<li><span class="target" id="sqlalchemy.sql.expression.between.params.lower_bound"></span><strong>lower_bound</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.between.params.lower_bound">¶</a> – a column or Python scalar expression serving as the
lower bound of the right side of the <tt class="docutils literal"><span class="pre">BETWEEN</span></tt> expression.</li>
<li><span class="target" id="sqlalchemy.sql.expression.between.params.upper_bound"></span><strong>upper_bound</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.between.params.upper_bound">¶</a> – a column or Python scalar expression serving as the
upper bound of the right side of the <tt class="docutils literal"><span class="pre">BETWEEN</span></tt> expression.</li>
<li><span class="target" id="sqlalchemy.sql.expression.between.params.symmetric"></span><strong>symmetric</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.between.params.symmetric">¶</a> – <p>if True, will render ” BETWEEN SYMMETRIC ”. Note
that not all databases support this syntax.</p>
<div class="versionadded">
<p><span>New in version 0.9.5.</span></p>
</div>
</li>
</ul>
</td>
</tr>
</tbody>
</table>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p class="last"><a class="reference internal" href="#sqlalchemy.sql.expression.ColumnElement.between" title="sqlalchemy.sql.expression.ColumnElement.between"><tt class="xref py py-meth docutils literal"><span class="pre">ColumnElement.between()</span></tt></a></p>
</div>
</dd></dl>
<dl class="function">
<dt id="sqlalchemy.sql.expression.bindparam">
<tt class="descclassname">sqlalchemy.sql.expression.</tt><tt class="descname">bindparam</tt><big>(</big><em>key</em>, <em>value=symbol('NO_ARG')</em>, <em>type_=None</em>, <em>unique=False</em>, <em>required=symbol('NO_ARG')</em>, <em>quote=None</em>, <em>callable_=None</em>, <em>isoutparam=False</em>, <em>_compared_to_operator=None</em>, <em>_compared_to_type=None</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.bindparam" title="Permalink to this definition">¶</a></dt>
<dd><p>Produce a “bound expression”.</p>
<p>The return value is an instance of <a class="reference internal" href="#sqlalchemy.sql.expression.BindParameter" title="sqlalchemy.sql.expression.BindParameter"><tt class="xref py py-class docutils literal"><span class="pre">BindParameter</span></tt></a>; this
is a <a class="reference internal" href="#sqlalchemy.sql.expression.ColumnElement" title="sqlalchemy.sql.expression.ColumnElement"><tt class="xref py py-class docutils literal"><span class="pre">ColumnElement</span></tt></a> 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.</p>
<p>In SQLAlchemy, the <a class="reference internal" href="#sqlalchemy.sql.expression.bindparam" title="sqlalchemy.sql.expression.bindparam"><tt class="xref py py-func docutils literal"><span class="pre">bindparam()</span></tt></a> construct has
the ability to carry along the actual value that will be ultimately
used at expression time. In this way, it serves not just as
a “placeholder” for eventual population, but also as a means of
representing so-called “unsafe” values which should not be rendered
directly in a SQL statement, but rather should be passed along
to the <a class="reference internal" href="../glossary.html#term-dbapi"><em class="xref std std-term">DBAPI</em></a> as values which need to be correctly escaped
and potentially handled for type-safety.</p>
<p>When using <a class="reference internal" href="#sqlalchemy.sql.expression.bindparam" title="sqlalchemy.sql.expression.bindparam"><tt class="xref py py-func docutils literal"><span class="pre">bindparam()</span></tt></a> explicitly, the use case is typically
one of traditional deferment of parameters; the <a class="reference internal" href="#sqlalchemy.sql.expression.bindparam" title="sqlalchemy.sql.expression.bindparam"><tt class="xref py py-func docutils literal"><span class="pre">bindparam()</span></tt></a>
construct accepts a name which can then be referred to at execution
time:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="kn">import</span> <span class="n">bindparam</span>
<span class="n">stmt</span> <span class="o">=</span> <span class="n">select</span><span class="p">([</span><span class="n">users_table</span><span class="p">])</span><span class="o">.</span>\
<span class="n">where</span><span class="p">(</span><span class="n">users_table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">name</span> <span class="o">==</span> <span class="n">bindparam</span><span class="p">(</span><span class="s">'username'</span><span class="p">))</span></pre></div>
</div>
<p>The above statement, when rendered, will produce SQL similar to:</p>
<div class="highlight-python"><pre>SELECT id, name FROM user WHERE name = :username</pre>
</div>
<p>In order to populate the value of <tt class="docutils literal"><span class="pre">:username</span></tt> above, the value
would typically be applied at execution time to a method
like <a class="reference internal" href="connections.html#sqlalchemy.engine.Connection.execute" title="sqlalchemy.engine.Connection.execute"><tt class="xref py py-meth docutils literal"><span class="pre">Connection.execute()</span></tt></a>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">result</span> <span class="o">=</span> <span class="n">connection</span><span class="o">.</span><span class="n">execute</span><span class="p">(</span><span class="n">stmt</span><span class="p">,</span> <span class="n">username</span><span class="o">=</span><span class="s">'wendy'</span><span class="p">)</span></pre></div>
</div>
<p>Explicit use of <a class="reference internal" href="#sqlalchemy.sql.expression.bindparam" title="sqlalchemy.sql.expression.bindparam"><tt class="xref py py-func docutils literal"><span class="pre">bindparam()</span></tt></a> is also common when producing
UPDATE or DELETE statements that are to be invoked multiple times,
where the WHERE criterion of the statement is to change on each
invocation, such as:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">stmt</span> <span class="o">=</span> <span class="p">(</span><span class="n">users_table</span><span class="o">.</span><span class="n">update</span><span class="p">()</span><span class="o">.</span>
<span class="n">where</span><span class="p">(</span><span class="n">user_table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">name</span> <span class="o">==</span> <span class="n">bindparam</span><span class="p">(</span><span class="s">'username'</span><span class="p">))</span><span class="o">.</span>
<span class="n">values</span><span class="p">(</span><span class="n">fullname</span><span class="o">=</span><span class="n">bindparam</span><span class="p">(</span><span class="s">'fullname'</span><span class="p">))</span>
<span class="p">)</span>
<span class="n">connection</span><span class="o">.</span><span class="n">execute</span><span class="p">(</span>
<span class="n">stmt</span><span class="p">,</span> <span class="p">[{</span><span class="s">"username"</span><span class="p">:</span> <span class="s">"wendy"</span><span class="p">,</span> <span class="s">"fullname"</span><span class="p">:</span> <span class="s">"Wendy Smith"</span><span class="p">},</span>
<span class="p">{</span><span class="s">"username"</span><span class="p">:</span> <span class="s">"jack"</span><span class="p">,</span> <span class="s">"fullname"</span><span class="p">:</span> <span class="s">"Jack Jones"</span><span class="p">},</span>
<span class="p">]</span>
<span class="p">)</span></pre></div>
</div>
<p>SQLAlchemy’s Core expression system makes wide use of
<a class="reference internal" href="#sqlalchemy.sql.expression.bindparam" title="sqlalchemy.sql.expression.bindparam"><tt class="xref py py-func docutils literal"><span class="pre">bindparam()</span></tt></a> in an implicit sense. It is typical that Python
literal values passed to virtually all SQL expression functions are
coerced into fixed <a class="reference internal" href="#sqlalchemy.sql.expression.bindparam" title="sqlalchemy.sql.expression.bindparam"><tt class="xref py py-func docutils literal"><span class="pre">bindparam()</span></tt></a> constructs. For example, given
a comparison operation such as:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">expr</span> <span class="o">=</span> <span class="n">users_table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">name</span> <span class="o">==</span> <span class="s">'Wendy'</span></pre></div>
</div>
<p>The above expression will produce a <a class="reference internal" href="#sqlalchemy.sql.expression.BinaryExpression" title="sqlalchemy.sql.expression.BinaryExpression"><tt class="xref py py-class docutils literal"><span class="pre">BinaryExpression</span></tt></a>
construct, where the left side is the <a class="reference internal" href="metadata.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal"><span class="pre">Column</span></tt></a> object
representing the <tt class="docutils literal"><span class="pre">name</span></tt> column, and the right side is a
<a class="reference internal" href="#sqlalchemy.sql.expression.BindParameter" title="sqlalchemy.sql.expression.BindParameter"><tt class="xref py py-class docutils literal"><span class="pre">BindParameter</span></tt></a> representing the literal value:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">print</span><span class="p">(</span><span class="nb">repr</span><span class="p">(</span><span class="n">expr</span><span class="o">.</span><span class="n">right</span><span class="p">))</span>
<span class="n">BindParameter</span><span class="p">(</span><span class="s">'%(4327771088 name)s'</span><span class="p">,</span> <span class="s">'Wendy'</span><span class="p">,</span> <span class="n">type_</span><span class="o">=</span><span class="n">String</span><span class="p">())</span></pre></div>
</div>
<p>The expression above will render SQL such as:</p>
<div class="highlight-python"><pre>user.name = :name_1</pre>
</div>
<p>Where the <tt class="docutils literal"><span class="pre">:name_1</span></tt> parameter name is an anonymous name. The
actual string <tt class="docutils literal"><span class="pre">Wendy</span></tt> is not in the rendered string, but is carried
along where it is later used within statement execution. If we
invoke a statement like the following:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">stmt</span> <span class="o">=</span> <span class="n">select</span><span class="p">([</span><span class="n">users_table</span><span class="p">])</span><span class="o">.</span><span class="n">where</span><span class="p">(</span><span class="n">users_table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">name</span> <span class="o">==</span> <span class="s">'Wendy'</span><span class="p">)</span>
<span class="n">result</span> <span class="o">=</span> <span class="n">connection</span><span class="o">.</span><span class="n">execute</span><span class="p">(</span><span class="n">stmt</span><span class="p">)</span></pre></div>
</div>
<p>We would see SQL logging output as:</p>
<div class="highlight-python"><pre>SELECT "user".id, "user".name
FROM "user"
WHERE "user".name = %(name_1)s
{'name_1': 'Wendy'}</pre>
</div>
<p>Above, we see that <tt class="docutils literal"><span class="pre">Wendy</span></tt> is passed as a parameter to the database,
while the placeholder <tt class="docutils literal"><span class="pre">:name_1</span></tt> is rendered in the appropriate form
for the target database, in this case the Postgresql database.</p>
<p>Similarly, <a class="reference internal" href="#sqlalchemy.sql.expression.bindparam" title="sqlalchemy.sql.expression.bindparam"><tt class="xref py py-func docutils literal"><span class="pre">bindparam()</span></tt></a> is invoked automatically
when working with <a class="reference internal" href="../glossary.html#term-crud"><em class="xref std std-term">CRUD</em></a> statements as far as the “VALUES”
portion is concerned. The <a class="reference internal" href="dml.html#sqlalchemy.sql.expression.insert" title="sqlalchemy.sql.expression.insert"><tt class="xref py py-func docutils literal"><span class="pre">insert()</span></tt></a> construct produces an
<tt class="docutils literal"><span class="pre">INSERT</span></tt> expression which will, at statement execution time,
generate bound placeholders based on the arguments passed, as in:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">stmt</span> <span class="o">=</span> <span class="n">users_table</span><span class="o">.</span><span class="n">insert</span><span class="p">()</span>
<span class="n">result</span> <span class="o">=</span> <span class="n">connection</span><span class="o">.</span><span class="n">execute</span><span class="p">(</span><span class="n">stmt</span><span class="p">,</span> <span class="n">name</span><span class="o">=</span><span class="s">'Wendy'</span><span class="p">)</span></pre></div>
</div>
<p>The above will produce SQL output as:</p>
<div class="highlight-python"><pre>INSERT INTO "user" (name) VALUES (%(name)s)
{'name': 'Wendy'}</pre>
</div>
<p>The <a class="reference internal" href="dml.html#sqlalchemy.sql.expression.Insert" title="sqlalchemy.sql.expression.Insert"><tt class="xref py py-class docutils literal"><span class="pre">Insert</span></tt></a> construct, at compilation/execution time,
rendered a single <a class="reference internal" href="#sqlalchemy.sql.expression.bindparam" title="sqlalchemy.sql.expression.bindparam"><tt class="xref py py-func docutils literal"><span class="pre">bindparam()</span></tt></a> mirroring the column
name <tt class="docutils literal"><span class="pre">name</span></tt> as a result of the single <tt class="docutils literal"><span class="pre">name</span></tt> parameter
we passed to the <a class="reference internal" href="connections.html#sqlalchemy.engine.Connection.execute" title="sqlalchemy.engine.Connection.execute"><tt class="xref py py-meth docutils literal"><span class="pre">Connection.execute()</span></tt></a> method.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><span class="target" id="sqlalchemy.sql.expression.bindparam.params.key"></span><strong>key</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.bindparam.params.key">¶</a> – the key (e.g. the name) for this bind param.
Will be used in the generated
SQL statement for dialects that use named parameters. This
value may be modified when part of a compilation operation,
if other <a class="reference internal" href="#sqlalchemy.sql.expression.BindParameter" title="sqlalchemy.sql.expression.BindParameter"><tt class="xref py py-class docutils literal"><span class="pre">BindParameter</span></tt></a> objects exist with the same
key, or if its length is too long and truncation is
required.</li>
<li><span class="target" id="sqlalchemy.sql.expression.bindparam.params.value"></span><strong>value</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.bindparam.params.value">¶</a> – Initial value for this bind param. Will be used at statement
execution time as the value for this parameter passed to the
DBAPI, if no other value is indicated to the statement execution
method for this particular parameter name. Defaults to <tt class="docutils literal"><span class="pre">None</span></tt>.</li>
<li><span class="target" id="sqlalchemy.sql.expression.bindparam.params.callable_"></span><strong>callable_</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.bindparam.params.callable_">¶</a> – A callable function that takes the place of “value”. The function
will be called at statement execution time to determine the
ultimate value. Used for scenarios where the actual bind
value cannot be determined at the point at which the clause
construct is created, but embedded bind values are still desirable.</li>
<li><span class="target" id="sqlalchemy.sql.expression.bindparam.params.type_"></span><strong>type_</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.bindparam.params.type_">¶</a> – <p>A <a class="reference internal" href="types.html#sqlalchemy.types.TypeEngine" title="sqlalchemy.types.TypeEngine"><tt class="xref py py-class docutils literal"><span class="pre">TypeEngine</span></tt></a> class or instance representing an optional
datatype for this <a class="reference internal" href="#sqlalchemy.sql.expression.bindparam" title="sqlalchemy.sql.expression.bindparam"><tt class="xref py py-func docutils literal"><span class="pre">bindparam()</span></tt></a>. If not passed, a type
may be determined automatically for the bind, based on the given
value; for example, trivial Python types such as <tt class="docutils literal"><span class="pre">str</span></tt>,
<tt class="docutils literal"><span class="pre">int</span></tt>, <tt class="docutils literal"><span class="pre">bool</span></tt>
may result in the <a class="reference internal" href="types.html#sqlalchemy.types.String" title="sqlalchemy.types.String"><tt class="xref py py-class docutils literal"><span class="pre">String</span></tt></a>, <a class="reference internal" href="types.html#sqlalchemy.types.Integer" title="sqlalchemy.types.Integer"><tt class="xref py py-class docutils literal"><span class="pre">Integer</span></tt></a> or
<a class="reference internal" href="types.html#sqlalchemy.types.Boolean" title="sqlalchemy.types.Boolean"><tt class="xref py py-class docutils literal"><span class="pre">Boolean</span></tt></a> types being autoamtically selected.</p>
<p>The type of a <a class="reference internal" href="#sqlalchemy.sql.expression.bindparam" title="sqlalchemy.sql.expression.bindparam"><tt class="xref py py-func docutils literal"><span class="pre">bindparam()</span></tt></a> is significant especially in that
the type will apply pre-processing to the value before it is
passed to the database. For example, a <a class="reference internal" href="#sqlalchemy.sql.expression.bindparam" title="sqlalchemy.sql.expression.bindparam"><tt class="xref py py-func docutils literal"><span class="pre">bindparam()</span></tt></a> which
refers to a datetime value, and is specified as holding the
<a class="reference internal" href="types.html#sqlalchemy.types.DateTime" title="sqlalchemy.types.DateTime"><tt class="xref py py-class docutils literal"><span class="pre">DateTime</span></tt></a> type, may apply conversion needed to the
value (such as stringification on SQLite) before passing the value
to the database.</p>
</li>
<li><span class="target" id="sqlalchemy.sql.expression.bindparam.params.unique"></span><strong>unique</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.bindparam.params.unique">¶</a> – if True, the key name of this <a class="reference internal" href="#sqlalchemy.sql.expression.BindParameter" title="sqlalchemy.sql.expression.BindParameter"><tt class="xref py py-class docutils literal"><span class="pre">BindParameter</span></tt></a> will be
modified if another <a class="reference internal" href="#sqlalchemy.sql.expression.BindParameter" title="sqlalchemy.sql.expression.BindParameter"><tt class="xref py py-class docutils literal"><span class="pre">BindParameter</span></tt></a> of the same name
already has been located within the containing
expression. This flag is used generally by the internals
when producing so-called “anonymous” bound expressions, it
isn’t generally applicable to explicitly-named <a class="reference internal" href="#sqlalchemy.sql.expression.bindparam" title="sqlalchemy.sql.expression.bindparam"><tt class="xref py py-func docutils literal"><span class="pre">bindparam()</span></tt></a>
constructs.</li>
<li><span class="target" id="sqlalchemy.sql.expression.bindparam.params.required"></span><strong>required</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.bindparam.params.required">¶</a> – <p>If <tt class="docutils literal"><span class="pre">True</span></tt>, a value is required at execution time. If not passed,
it defaults to <tt class="docutils literal"><span class="pre">True</span></tt> if neither <a class="reference internal" href="#sqlalchemy.sql.expression.bindparam.params.value" title="sqlalchemy.sql.expression.bindparam"><tt class="xref py py-paramref docutils literal"><span class="pre">bindparam.value</span></tt></a>
or <a class="reference internal" href="#sqlalchemy.sql.expression.bindparam.params.callable" title="sqlalchemy.sql.expression.bindparam"><tt class="xref py py-paramref docutils literal"><span class="pre">bindparam.callable</span></tt></a> were passed. If either of these
parameters are present, then <a class="reference internal" href="#sqlalchemy.sql.expression.bindparam.params.required" title="sqlalchemy.sql.expression.bindparam"><tt class="xref py py-paramref docutils literal"><span class="pre">bindparam.required</span></tt></a>
defaults to <tt class="docutils literal"><span class="pre">False</span></tt>.</p>
<div class="versionchanged">
<p><span>Changed in version 0.8: </span>If the <tt class="docutils literal"><span class="pre">required</span></tt> flag is not specified,
it will be set automatically to <tt class="docutils literal"><span class="pre">True</span></tt> or <tt class="docutils literal"><span class="pre">False</span></tt> depending
on whether or not the <tt class="docutils literal"><span class="pre">value</span></tt> or <tt class="docutils literal"><span class="pre">callable</span></tt> parameters
were specified.</p>
</div>
</li>
<li><span class="target" id="sqlalchemy.sql.expression.bindparam.params.quote"></span><strong>quote</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.bindparam.params.quote">¶</a> – True if this parameter name requires quoting and is not
currently known as a SQLAlchemy reserved word; this currently
only applies to the Oracle backend, where bound names must
sometimes be quoted.</li>
<li><span class="target" id="sqlalchemy.sql.expression.bindparam.params.isoutparam"></span><strong>isoutparam</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.bindparam.params.isoutparam">¶</a> – if True, the parameter should be treated like a stored procedure
“OUT” parameter. This applies to backends such as Oracle which
support OUT parameters.</li>
</ul>
</td>
</tr>
</tbody>
</table>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p><a class="reference internal" href="tutorial.html#coretutorial-bind-param"><em>Bind Parameter Objects</em></a></p>
<p><a class="reference internal" href="tutorial.html#coretutorial-insert-expressions"><em>Insert Expressions</em></a></p>
<p class="last"><a class="reference internal" href="#sqlalchemy.sql.expression.outparam" title="sqlalchemy.sql.expression.outparam"><tt class="xref py py-func docutils literal"><span class="pre">outparam()</span></tt></a></p>
</div>
</dd></dl>
<dl class="function">
<dt id="sqlalchemy.sql.expression.case">
<tt class="descclassname">sqlalchemy.sql.expression.</tt><tt class="descname">case</tt><big>(</big><em>whens</em>, <em>value=None</em>, <em>else_=None</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.case" title="Permalink to this definition">¶</a></dt>
<dd><p>Produce a <tt class="docutils literal"><span class="pre">CASE</span></tt> expression.</p>
<p>The <tt class="docutils literal"><span class="pre">CASE</span></tt> construct in SQL is a conditional object that
acts somewhat analogously to an “if/then” construct in other
languages. It returns an instance of <a class="reference internal" href="#sqlalchemy.sql.expression.Case" title="sqlalchemy.sql.expression.Case"><tt class="xref py py-class docutils literal"><span class="pre">Case</span></tt></a>.</p>
<p><a class="reference internal" href="#sqlalchemy.sql.expression.case" title="sqlalchemy.sql.expression.case"><tt class="xref py py-func docutils literal"><span class="pre">case()</span></tt></a> in its usual form is passed a list of “when”
constructs, that is, a list of conditions and results as tuples:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="kn">import</span> <span class="n">case</span>
<span class="n">stmt</span> <span class="o">=</span> <span class="n">select</span><span class="p">([</span><span class="n">users_table</span><span class="p">])</span><span class="o">.</span>\
<span class="n">where</span><span class="p">(</span>
<span class="n">case</span><span class="p">(</span>
<span class="p">[</span>
<span class="p">(</span><span class="n">users_table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">name</span> <span class="o">==</span> <span class="s">'wendy'</span><span class="p">,</span> <span class="s">'W'</span><span class="p">),</span>
<span class="p">(</span><span class="n">users_table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">name</span> <span class="o">==</span> <span class="s">'jack'</span><span class="p">,</span> <span class="s">'J'</span><span class="p">)</span>
<span class="p">],</span>
<span class="n">else_</span><span class="o">=</span><span class="s">'E'</span>
<span class="p">)</span>
<span class="p">)</span></pre></div>
</div>
<p>The above statement will produce SQL resembling:</p>
<div class="highlight-python"><pre>SELECT id, name FROM user
WHERE CASE
WHEN (name = :name_1) THEN :param_1
WHEN (name = :name_2) THEN :param_2
ELSE :param_3
END</pre>
</div>
<p>When simple equality expressions of several values against a single
parent column are needed, <a class="reference internal" href="#sqlalchemy.sql.expression.case" title="sqlalchemy.sql.expression.case"><tt class="xref py py-func docutils literal"><span class="pre">case()</span></tt></a> also has a “shorthand” format
used via the
<a class="reference internal" href="#sqlalchemy.sql.expression.case.params.value" title="sqlalchemy.sql.expression.case"><tt class="xref py py-paramref docutils literal"><span class="pre">case.value</span></tt></a> parameter, which is passed a column
expression to be compared. In this form, the <a class="reference internal" href="#sqlalchemy.sql.expression.case.params.whens" title="sqlalchemy.sql.expression.case"><tt class="xref py py-paramref docutils literal"><span class="pre">case.whens</span></tt></a>
parameter is passed as a dictionary containing expressions to be
compared against keyed to result expressions. The statement below is
equivalent to the preceding statement:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">stmt</span> <span class="o">=</span> <span class="n">select</span><span class="p">([</span><span class="n">users_table</span><span class="p">])</span><span class="o">.</span>\
<span class="n">where</span><span class="p">(</span>
<span class="n">case</span><span class="p">(</span>
<span class="p">{</span><span class="s">"wendy"</span><span class="p">:</span> <span class="s">"W"</span><span class="p">,</span> <span class="s">"jack"</span><span class="p">:</span> <span class="s">"J"</span><span class="p">},</span>
<span class="n">value</span><span class="o">=</span><span class="n">users_table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">name</span><span class="p">,</span>
<span class="n">else_</span><span class="o">=</span><span class="s">'E'</span>
<span class="p">)</span>
<span class="p">)</span></pre></div>
</div>
<p>The values which are accepted as result values in
<a class="reference internal" href="#sqlalchemy.sql.expression.case.params.whens" title="sqlalchemy.sql.expression.case"><tt class="xref py py-paramref docutils literal"><span class="pre">case.whens</span></tt></a> as well as with <a class="reference internal" href="#sqlalchemy.sql.expression.case.params.else_" title="sqlalchemy.sql.expression.case"><tt class="xref py py-paramref docutils literal"><span class="pre">case.else_</span></tt></a> are
coerced from Python literals into <a class="reference internal" href="#sqlalchemy.sql.expression.bindparam" title="sqlalchemy.sql.expression.bindparam"><tt class="xref py py-func docutils literal"><span class="pre">bindparam()</span></tt></a> constructs.
SQL expressions, e.g. <a class="reference internal" href="#sqlalchemy.sql.expression.ColumnElement" title="sqlalchemy.sql.expression.ColumnElement"><tt class="xref py py-class docutils literal"><span class="pre">ColumnElement</span></tt></a> constructs, are accepted
as well. To coerce a literal string expression into a constant
expression rendered inline, use the <a class="reference internal" href="#sqlalchemy.sql.expression.literal_column" title="sqlalchemy.sql.expression.literal_column"><tt class="xref py py-func docutils literal"><span class="pre">literal_column()</span></tt></a> construct,
as in:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="kn">import</span> <span class="n">case</span><span class="p">,</span> <span class="n">literal_column</span>
<span class="n">case</span><span class="p">(</span>
<span class="p">[</span>
<span class="p">(</span>
<span class="n">orderline</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">qty</span> <span class="o">></span> <span class="mi">100</span><span class="p">,</span>
<span class="n">literal_column</span><span class="p">(</span><span class="s">"'greaterthan100'"</span><span class="p">)</span>
<span class="p">),</span>
<span class="p">(</span>
<span class="n">orderline</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">qty</span> <span class="o">></span> <span class="mi">10</span><span class="p">,</span>
<span class="n">literal_column</span><span class="p">(</span><span class="s">"'greaterthan10'"</span><span class="p">)</span>
<span class="p">)</span>
<span class="p">],</span>
<span class="n">else_</span><span class="o">=</span><span class="n">literal_column</span><span class="p">(</span><span class="s">"'lessthan10'"</span><span class="p">)</span>
<span class="p">)</span></pre></div>
</div>
<p>The above will render the given constants without using bound
parameters for the result values (but still for the comparison
values), as in:</p>
<div class="highlight-python"><pre>CASE
WHEN (orderline.qty > :qty_1) THEN 'greaterthan100'
WHEN (orderline.qty > :qty_2) THEN 'greaterthan10'
ELSE 'lessthan10'
END</pre>
</div>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><span class="target" id="sqlalchemy.sql.expression.case.params.whens"></span><strong>whens</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.case.params.whens">¶</a> – <p>The criteria to be compared against,
<a class="reference internal" href="#sqlalchemy.sql.expression.case.params.whens" title="sqlalchemy.sql.expression.case"><tt class="xref py py-paramref docutils literal"><span class="pre">case.whens</span></tt></a> accepts two different forms, based on
whether or not <a class="reference internal" href="#sqlalchemy.sql.expression.case.params.value" title="sqlalchemy.sql.expression.case"><tt class="xref py py-paramref docutils literal"><span class="pre">case.value</span></tt></a> is used.</p>
<p>In the first form, it accepts a list of 2-tuples; each 2-tuple
consists of <tt class="docutils literal"><span class="pre">(<sql</span> <span class="pre">expression>,</span> <span class="pre"><value>)</span></tt>, where the SQL
expression is a boolean expression and “value” is a resulting value,
e.g.:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">case</span><span class="p">([</span>
<span class="p">(</span><span class="n">users_table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">name</span> <span class="o">==</span> <span class="s">'wendy'</span><span class="p">,</span> <span class="s">'W'</span><span class="p">),</span>
<span class="p">(</span><span class="n">users_table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">name</span> <span class="o">==</span> <span class="s">'jack'</span><span class="p">,</span> <span class="s">'J'</span><span class="p">)</span>
<span class="p">])</span></pre></div>
</div>
<p>In the second form, it accepts a Python dictionary of comparison
values mapped to a resulting value; this form requires
<a class="reference internal" href="#sqlalchemy.sql.expression.case.params.value" title="sqlalchemy.sql.expression.case"><tt class="xref py py-paramref docutils literal"><span class="pre">case.value</span></tt></a> to be present, and values will be compared
using the <tt class="docutils literal"><span class="pre">==</span></tt> operator, e.g.:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">case</span><span class="p">(</span>
<span class="p">{</span><span class="s">"wendy"</span><span class="p">:</span> <span class="s">"W"</span><span class="p">,</span> <span class="s">"jack"</span><span class="p">:</span> <span class="s">"J"</span><span class="p">},</span>
<span class="n">value</span><span class="o">=</span><span class="n">users_table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">name</span>
<span class="p">)</span></pre></div>
</div>
</li>
<li><span class="target" id="sqlalchemy.sql.expression.case.params.value"></span><strong>value</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.case.params.value">¶</a> – An optional SQL expression which will be used as a
fixed “comparison point” for candidate values within a dictionary
passed to <a class="reference internal" href="#sqlalchemy.sql.expression.case.params.whens" title="sqlalchemy.sql.expression.case"><tt class="xref py py-paramref docutils literal"><span class="pre">case.whens</span></tt></a>.</li>
<li><span class="target" id="sqlalchemy.sql.expression.case.params.else_"></span><strong>else_</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.case.params.else_">¶</a> – An optional SQL expression which will be the evaluated
result of the <tt class="docutils literal"><span class="pre">CASE</span></tt> construct if all expressions within
<a class="reference internal" href="#sqlalchemy.sql.expression.case.params.whens" title="sqlalchemy.sql.expression.case"><tt class="xref py py-paramref docutils literal"><span class="pre">case.whens</span></tt></a> evaluate to false. When omitted, most
databases will produce a result of NULL if none of the “when”
expressions evaulate to true.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="function">
<dt id="sqlalchemy.sql.expression.cast">
<tt class="descclassname">sqlalchemy.sql.expression.</tt><tt class="descname">cast</tt><big>(</big><em>expression</em>, <em>type_</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.cast" title="Permalink to this definition">¶</a></dt>
<dd><p>Produce a <tt class="docutils literal"><span class="pre">CAST</span></tt> expression.</p>
<p><a class="reference internal" href="#sqlalchemy.sql.expression.cast" title="sqlalchemy.sql.expression.cast"><tt class="xref py py-func docutils literal"><span class="pre">cast()</span></tt></a> returns an instance of <a class="reference internal" href="#sqlalchemy.sql.expression.Cast" title="sqlalchemy.sql.expression.Cast"><tt class="xref py py-class docutils literal"><span class="pre">Cast</span></tt></a>.</p>
<p>E.g.:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="kn">import</span> <span class="n">cast</span><span class="p">,</span> <span class="n">Numeric</span>
<span class="n">stmt</span> <span class="o">=</span> <span class="n">select</span><span class="p">([</span>
<span class="n">cast</span><span class="p">(</span><span class="n">product_table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">unit_price</span><span class="p">,</span> <span class="n">Numeric</span><span class="p">(</span><span class="mi">10</span><span class="p">,</span> <span class="mi">4</span><span class="p">))</span>
<span class="p">])</span></pre></div>
</div>
<p>The above statement will produce SQL resembling:</p>
<div class="highlight-python"><pre>SELECT CAST(unit_price AS NUMERIC(10, 4)) FROM product</pre>
</div>
<p>The <a class="reference internal" href="#sqlalchemy.sql.expression.cast" title="sqlalchemy.sql.expression.cast"><tt class="xref py py-func docutils literal"><span class="pre">cast()</span></tt></a> function performs two distinct functions when
used. The first is that it renders the <tt class="docutils literal"><span class="pre">CAST</span></tt> expression within
the resulting SQL string. The second is that it associates the given
type (e.g. <a class="reference internal" href="types.html#sqlalchemy.types.TypeEngine" title="sqlalchemy.types.TypeEngine"><tt class="xref py py-class docutils literal"><span class="pre">TypeEngine</span></tt></a> class or instance) with the column
expression on the Python side, which means the expression will take
on the expression operator behavior associated with that type,
as well as the bound-value handling and result-row-handling behavior
of the type.</p>
<div class="versionchanged">
<p><span>Changed in version 0.9.0: </span><a class="reference internal" href="#sqlalchemy.sql.expression.cast" title="sqlalchemy.sql.expression.cast"><tt class="xref py py-func docutils literal"><span class="pre">cast()</span></tt></a> now applies the given type
to the expression such that it takes effect on the bound-value,
e.g. the Python-to-database direction, in addition to the
result handling, e.g. database-to-Python, direction.</p>
</div>
<p>An alternative to <a class="reference internal" href="#sqlalchemy.sql.expression.cast" title="sqlalchemy.sql.expression.cast"><tt class="xref py py-func docutils literal"><span class="pre">cast()</span></tt></a> is the <a class="reference internal" href="#sqlalchemy.sql.expression.type_coerce" title="sqlalchemy.sql.expression.type_coerce"><tt class="xref py py-func docutils literal"><span class="pre">type_coerce()</span></tt></a> function.
This function performs the second task of associating an expression
with a specific type, but does not render the <tt class="docutils literal"><span class="pre">CAST</span></tt> expression
in SQL.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><span class="target" id="sqlalchemy.sql.expression.cast.params.expression"></span><strong>expression</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.cast.params.expression">¶</a> – A SQL expression, such as a <a class="reference internal" href="#sqlalchemy.sql.expression.ColumnElement" title="sqlalchemy.sql.expression.ColumnElement"><tt class="xref py py-class docutils literal"><span class="pre">ColumnElement</span></tt></a>
expression or a Python string which will be coerced into a bound
literal value.</li>
<li><span class="target" id="sqlalchemy.sql.expression.cast.params.type_"></span><strong>type_</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.cast.params.type_">¶</a> – A <a class="reference internal" href="types.html#sqlalchemy.types.TypeEngine" title="sqlalchemy.types.TypeEngine"><tt class="xref py py-class docutils literal"><span class="pre">TypeEngine</span></tt></a> class or instance indicating
the type to which the <tt class="docutils literal"><span class="pre">CAST</span></tt> should apply.</li>
</ul>
</td>
</tr>
</tbody>
</table>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p class="last"><a class="reference internal" href="#sqlalchemy.sql.expression.type_coerce" title="sqlalchemy.sql.expression.type_coerce"><tt class="xref py py-func docutils literal"><span class="pre">type_coerce()</span></tt></a> - Python-side type coercion without emitting
CAST.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="sqlalchemy.sql.expression.column">
<tt class="descclassname">sqlalchemy.sql.expression.</tt><tt class="descname">column</tt><big>(</big><em>text</em>, <em>type_=None</em>, <em>is_literal=False</em>, <em>_selectable=None</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.column" title="Permalink to this definition">¶</a></dt>
<dd><p>Produce a <a class="reference internal" href="#sqlalchemy.sql.expression.ColumnClause" title="sqlalchemy.sql.expression.ColumnClause"><tt class="xref py py-class docutils literal"><span class="pre">ColumnClause</span></tt></a> object.</p>
<p>The <a class="reference internal" href="#sqlalchemy.sql.expression.ColumnClause" title="sqlalchemy.sql.expression.ColumnClause"><tt class="xref py py-class docutils literal"><span class="pre">ColumnClause</span></tt></a> is a lightweight analogue to the
<a class="reference internal" href="metadata.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal"><span class="pre">Column</span></tt></a> class. The <a class="reference internal" href="#sqlalchemy.sql.expression.column" title="sqlalchemy.sql.expression.column"><tt class="xref py py-func docutils literal"><span class="pre">column()</span></tt></a> function can
be invoked with just a name alone, as in:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">sqlalchemy.sql</span> <span class="kn">import</span> <span class="n">column</span>
<span class="nb">id</span><span class="p">,</span> <span class="n">name</span> <span class="o">=</span> <span class="n">column</span><span class="p">(</span><span class="s">"id"</span><span class="p">),</span> <span class="n">column</span><span class="p">(</span><span class="s">"name"</span><span class="p">)</span>
<span class="n">stmt</span> <span class="o">=</span> <span class="n">select</span><span class="p">([</span><span class="nb">id</span><span class="p">,</span> <span class="n">name</span><span class="p">])</span><span class="o">.</span><span class="n">select_from</span><span class="p">(</span><span class="s">"user"</span><span class="p">)</span></pre></div>
</div>
<p>The above statement would produce SQL like:</p>
<div class="highlight-python"><pre>SELECT id, name FROM user</pre>
</div>
<p>Once constructed, <a class="reference internal" href="#sqlalchemy.sql.expression.column" title="sqlalchemy.sql.expression.column"><tt class="xref py py-func docutils literal"><span class="pre">column()</span></tt></a> may be used like any other SQL
expression element such as within <a class="reference internal" href="selectable.html#sqlalchemy.sql.expression.select" title="sqlalchemy.sql.expression.select"><tt class="xref py py-func docutils literal"><span class="pre">select()</span></tt></a> constructs:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">sqlalchemy.sql</span> <span class="kn">import</span> <span class="n">column</span>
<span class="nb">id</span><span class="p">,</span> <span class="n">name</span> <span class="o">=</span> <span class="n">column</span><span class="p">(</span><span class="s">"id"</span><span class="p">),</span> <span class="n">column</span><span class="p">(</span><span class="s">"name"</span><span class="p">)</span>
<span class="n">stmt</span> <span class="o">=</span> <span class="n">select</span><span class="p">([</span><span class="nb">id</span><span class="p">,</span> <span class="n">name</span><span class="p">])</span><span class="o">.</span><span class="n">select_from</span><span class="p">(</span><span class="s">"user"</span><span class="p">)</span></pre></div>
</div>
<p>The text handled by <a class="reference internal" href="#sqlalchemy.sql.expression.column" title="sqlalchemy.sql.expression.column"><tt class="xref py py-func docutils literal"><span class="pre">column()</span></tt></a> 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 <a class="reference internal" href="#sqlalchemy.sql.expression.literal_column" title="sqlalchemy.sql.expression.literal_column"><tt class="xref py py-func docutils literal"><span class="pre">literal_column()</span></tt></a> instead, or pass <tt class="docutils literal"><span class="pre">True</span></tt> as the
value of <a class="reference internal" href="#sqlalchemy.sql.expression.column.params.is_literal" title="sqlalchemy.sql.expression.column"><tt class="xref py py-paramref docutils literal"><span class="pre">column.is_literal</span></tt></a>. Additionally, full SQL
statements are best handled using the <a class="reference internal" href="#sqlalchemy.sql.expression.text" title="sqlalchemy.sql.expression.text"><tt class="xref py py-func docutils literal"><span class="pre">text()</span></tt></a> construct.</p>
<p><a class="reference internal" href="#sqlalchemy.sql.expression.column" title="sqlalchemy.sql.expression.column"><tt class="xref py py-func docutils literal"><span class="pre">column()</span></tt></a> can be used in a table-like
fashion by combining it with the <a class="reference internal" href="selectable.html#sqlalchemy.sql.expression.table" title="sqlalchemy.sql.expression.table"><tt class="xref py py-func docutils literal"><span class="pre">table()</span></tt></a> function
(which is the lightweight analogue to <a class="reference internal" href="metadata.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal"><span class="pre">Table</span></tt></a>) to produce
a working table construct with minimal boilerplate:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">sqlalchemy.sql</span> <span class="kn">import</span> <span class="n">table</span><span class="p">,</span> <span class="n">column</span>
<span class="n">user</span> <span class="o">=</span> <span class="n">table</span><span class="p">(</span><span class="s">"user"</span><span class="p">,</span>
<span class="n">column</span><span class="p">(</span><span class="s">"id"</span><span class="p">),</span>
<span class="n">column</span><span class="p">(</span><span class="s">"name"</span><span class="p">),</span>
<span class="n">column</span><span class="p">(</span><span class="s">"description"</span><span class="p">),</span>
<span class="p">)</span>
<span class="n">stmt</span> <span class="o">=</span> <span class="n">select</span><span class="p">([</span><span class="n">user</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">description</span><span class="p">])</span><span class="o">.</span><span class="n">where</span><span class="p">(</span><span class="n">user</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">name</span> <span class="o">==</span> <span class="s">'wendy'</span><span class="p">)</span></pre></div>
</div>
<p>A <a class="reference internal" href="#sqlalchemy.sql.expression.column" title="sqlalchemy.sql.expression.column"><tt class="xref py py-func docutils literal"><span class="pre">column()</span></tt></a> / <a class="reference internal" href="selectable.html#sqlalchemy.sql.expression.table" title="sqlalchemy.sql.expression.table"><tt class="xref py py-func docutils literal"><span class="pre">table()</span></tt></a> construct like that illustrated
above can be created in an
ad-hoc fashion and is not associated with any
<a class="reference internal" href="metadata.html#sqlalchemy.schema.MetaData" title="sqlalchemy.schema.MetaData"><tt class="xref py py-class docutils literal"><span class="pre">schema.MetaData</span></tt></a>, DDL, or events, unlike its
<a class="reference internal" href="metadata.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal"><span class="pre">Table</span></tt></a> counterpart.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><span class="target" id="sqlalchemy.sql.expression.column.params.text"></span><strong>text</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.column.params.text">¶</a> – the text of the element.</li>
<li><span class="target" id="sqlalchemy.sql.expression.column.params.type"></span><strong>type</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.column.params.type">¶</a> – <a class="reference internal" href="types.html#sqlalchemy.types.TypeEngine" title="sqlalchemy.types.TypeEngine"><tt class="xref py py-class docutils literal"><span class="pre">types.TypeEngine</span></tt></a> object which can associate
this <a class="reference internal" href="#sqlalchemy.sql.expression.ColumnClause" title="sqlalchemy.sql.expression.ColumnClause"><tt class="xref py py-class docutils literal"><span class="pre">ColumnClause</span></tt></a> with a type.</li>
<li><span class="target" id="sqlalchemy.sql.expression.column.params.is_literal"></span><strong>is_literal</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.column.params.is_literal">¶</a> – if True, the <a class="reference internal" href="#sqlalchemy.sql.expression.ColumnClause" title="sqlalchemy.sql.expression.ColumnClause"><tt class="xref py py-class docutils literal"><span class="pre">ColumnClause</span></tt></a> 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
<a class="reference internal" href="#sqlalchemy.sql.expression.literal_column" title="sqlalchemy.sql.expression.literal_column"><tt class="xref py py-func docutils literal"><span class="pre">literal_column()</span></tt></a> function essentially invokes
<a class="reference internal" href="#sqlalchemy.sql.expression.column" title="sqlalchemy.sql.expression.column"><tt class="xref py py-func docutils literal"><span class="pre">column()</span></tt></a> while passing <tt class="docutils literal"><span class="pre">is_literal=True</span></tt>.</li>
</ul>
</td>
</tr>
</tbody>
</table>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p><a class="reference internal" href="metadata.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal"><span class="pre">Column</span></tt></a></p>
<p><a class="reference internal" href="#sqlalchemy.sql.expression.literal_column" title="sqlalchemy.sql.expression.literal_column"><tt class="xref py py-func docutils literal"><span class="pre">literal_column()</span></tt></a></p>
<p><a class="reference internal" href="selectable.html#sqlalchemy.sql.expression.table" title="sqlalchemy.sql.expression.table"><tt class="xref py py-func docutils literal"><span class="pre">table()</span></tt></a></p>
<p><a class="reference internal" href="#sqlalchemy.sql.expression.text" title="sqlalchemy.sql.expression.text"><tt class="xref py py-func docutils literal"><span class="pre">text()</span></tt></a></p>
<p class="last"><a class="reference internal" href="tutorial.html#sqlexpression-literal-column"><em>Using More Specific Text with table(), literal_column(), and column()</em></a></p>
</div>
</dd></dl>
<dl class="function">
<dt id="sqlalchemy.sql.expression.collate">
<tt class="descclassname">sqlalchemy.sql.expression.</tt><tt class="descname">collate</tt><big>(</big><em>expression</em>, <em>collation</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.collate" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the clause <tt class="docutils literal"><span class="pre">expression</span> <span class="pre">COLLATE</span> <span class="pre">collation</span></tt>.</p>
<p>e.g.:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">collate</span><span class="p">(</span><span class="n">mycolumn</span><span class="p">,</span> <span class="s">'utf8_bin'</span><span class="p">)</span></pre></div>
</div>
<p>produces:</p>
<div class="highlight-python"><pre>mycolumn COLLATE utf8_bin</pre>
</div>
</dd></dl>
<dl class="function">
<dt id="sqlalchemy.sql.expression.desc">
<tt class="descclassname">sqlalchemy.sql.expression.</tt><tt class="descname">desc</tt><big>(</big><em>column</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.desc" title="Permalink to this definition">¶</a></dt>
<dd><p>Produce a descending <tt class="docutils literal"><span class="pre">ORDER</span> <span class="pre">BY</span></tt> clause element.</p>
<p>e.g.:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="kn">import</span> <span class="n">desc</span>
<span class="n">stmt</span> <span class="o">=</span> <span class="n">select</span><span class="p">([</span><span class="n">users_table</span><span class="p">])</span><span class="o">.</span><span class="n">order_by</span><span class="p">(</span><span class="n">desc</span><span class="p">(</span><span class="n">users_table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">name</span><span class="p">))</span></pre></div>
</div>
<p>will produce SQL as:</p>
<div class="highlight-python"><pre>SELECT id, name FROM user ORDER BY name DESC</pre>
</div>
<p>The <a class="reference internal" href="#sqlalchemy.sql.expression.desc" title="sqlalchemy.sql.expression.desc"><tt class="xref py py-func docutils literal"><span class="pre">desc()</span></tt></a> function is a standalone version of the
<a class="reference internal" href="#sqlalchemy.sql.expression.ColumnElement.desc" title="sqlalchemy.sql.expression.ColumnElement.desc"><tt class="xref py py-meth docutils literal"><span class="pre">ColumnElement.desc()</span></tt></a> method available on all SQL expressions,
e.g.:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">stmt</span> <span class="o">=</span> <span class="n">select</span><span class="p">([</span><span class="n">users_table</span><span class="p">])</span><span class="o">.</span><span class="n">order_by</span><span class="p">(</span><span class="n">users_table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">name</span><span class="o">.</span><span class="n">desc</span><span class="p">())</span></pre></div>
</div>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><span class="target" id="sqlalchemy.sql.expression.desc.params.column"></span><strong>column</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.desc.params.column">¶</a> – A <a class="reference internal" href="#sqlalchemy.sql.expression.ColumnElement" title="sqlalchemy.sql.expression.ColumnElement"><tt class="xref py py-class docutils literal"><span class="pre">ColumnElement</span></tt></a> (e.g. scalar SQL expression)
with which to apply the <a class="reference internal" href="#sqlalchemy.sql.expression.desc" title="sqlalchemy.sql.expression.desc"><tt class="xref py py-func docutils literal"><span class="pre">desc()</span></tt></a> operation.</td>
</tr>
</tbody>
</table>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p><a class="reference internal" href="#sqlalchemy.sql.expression.asc" title="sqlalchemy.sql.expression.asc"><tt class="xref py py-func docutils literal"><span class="pre">asc()</span></tt></a></p>
<p><a class="reference internal" href="#sqlalchemy.sql.expression.nullsfirst" title="sqlalchemy.sql.expression.nullsfirst"><tt class="xref py py-func docutils literal"><span class="pre">nullsfirst()</span></tt></a></p>
<p><a class="reference internal" href="#sqlalchemy.sql.expression.nullslast" title="sqlalchemy.sql.expression.nullslast"><tt class="xref py py-func docutils literal"><span class="pre">nullslast()</span></tt></a></p>
<p class="last"><a class="reference internal" href="selectable.html#sqlalchemy.sql.expression.Select.order_by" title="sqlalchemy.sql.expression.Select.order_by"><tt class="xref py py-meth docutils literal"><span class="pre">Select.order_by()</span></tt></a></p>
</div>
</dd></dl>
<dl class="function">
<dt id="sqlalchemy.sql.expression.distinct">
<tt class="descclassname">sqlalchemy.sql.expression.</tt><tt class="descname">distinct</tt><big>(</big><em>expr</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.distinct" title="Permalink to this definition">¶</a></dt>
<dd><p>Produce an column-expression-level unary <tt class="docutils literal"><span class="pre">DISTINCT</span></tt> clause.</p>
<p>This applies the <tt class="docutils literal"><span class="pre">DISTINCT</span></tt> keyword to an individual column
expression, and is typically contained within an aggregate function,
as in:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="kn">import</span> <span class="n">distinct</span><span class="p">,</span> <span class="n">func</span>
<span class="n">stmt</span> <span class="o">=</span> <span class="n">select</span><span class="p">([</span><span class="n">func</span><span class="o">.</span><span class="n">count</span><span class="p">(</span><span class="n">distinct</span><span class="p">(</span><span class="n">users_table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">name</span><span class="p">))])</span></pre></div>
</div>
<p>The above would produce an expression resembling:</p>
<div class="highlight-python"><pre>SELECT COUNT(DISTINCT name) FROM user</pre>
</div>
<p>The <a class="reference internal" href="#sqlalchemy.sql.expression.distinct" title="sqlalchemy.sql.expression.distinct"><tt class="xref py py-func docutils literal"><span class="pre">distinct()</span></tt></a> function is also available as a column-level
method, e.g. <a class="reference internal" href="#sqlalchemy.sql.expression.ColumnElement.distinct" title="sqlalchemy.sql.expression.ColumnElement.distinct"><tt class="xref py py-meth docutils literal"><span class="pre">ColumnElement.distinct()</span></tt></a>, as in:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">stmt</span> <span class="o">=</span> <span class="n">select</span><span class="p">([</span><span class="n">func</span><span class="o">.</span><span class="n">count</span><span class="p">(</span><span class="n">users_table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">name</span><span class="o">.</span><span class="n">distinct</span><span class="p">())])</span></pre></div>
</div>
<p>The <a class="reference internal" href="#sqlalchemy.sql.expression.distinct" title="sqlalchemy.sql.expression.distinct"><tt class="xref py py-func docutils literal"><span class="pre">distinct()</span></tt></a> operator is different from the
<a class="reference internal" href="selectable.html#sqlalchemy.sql.expression.Select.distinct" title="sqlalchemy.sql.expression.Select.distinct"><tt class="xref py py-meth docutils literal"><span class="pre">Select.distinct()</span></tt></a> method of <a class="reference internal" href="selectable.html#sqlalchemy.sql.expression.Select" title="sqlalchemy.sql.expression.Select"><tt class="xref py py-class docutils literal"><span class="pre">Select</span></tt></a>,
which produces a <tt class="docutils literal"><span class="pre">SELECT</span></tt> statement
with <tt class="docutils literal"><span class="pre">DISTINCT</span></tt> applied to the result set as a whole,
e.g. a <tt class="docutils literal"><span class="pre">SELECT</span> <span class="pre">DISTINCT</span></tt> expression. See that method for further
information.</p>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p><a class="reference internal" href="#sqlalchemy.sql.expression.ColumnElement.distinct" title="sqlalchemy.sql.expression.ColumnElement.distinct"><tt class="xref py py-meth docutils literal"><span class="pre">ColumnElement.distinct()</span></tt></a></p>
<p><a class="reference internal" href="selectable.html#sqlalchemy.sql.expression.Select.distinct" title="sqlalchemy.sql.expression.Select.distinct"><tt class="xref py py-meth docutils literal"><span class="pre">Select.distinct()</span></tt></a></p>
<p class="last"><a class="reference internal" href="#sqlalchemy.sql.expression.func" title="sqlalchemy.sql.expression.func"><tt class="xref py py-data docutils literal"><span class="pre">func</span></tt></a></p>
</div>
</dd></dl>
<dl class="function">
<dt id="sqlalchemy.sql.expression.extract">
<tt class="descclassname">sqlalchemy.sql.expression.</tt><tt class="descname">extract</tt><big>(</big><em>field</em>, <em>expr</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.extract" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a <a class="reference internal" href="#sqlalchemy.sql.expression.Extract" title="sqlalchemy.sql.expression.Extract"><tt class="xref py py-class docutils literal"><span class="pre">Extract</span></tt></a> construct.</p>
<p>This is typically available as <a class="reference internal" href="#sqlalchemy.sql.expression.extract" title="sqlalchemy.sql.expression.extract"><tt class="xref py py-func docutils literal"><span class="pre">extract()</span></tt></a>
as well as <tt class="docutils literal"><span class="pre">func.extract</span></tt> from the
<a class="reference internal" href="#sqlalchemy.sql.expression.func" title="sqlalchemy.sql.expression.func"><tt class="xref py py-data docutils literal"><span class="pre">func</span></tt></a> namespace.</p>
</dd></dl>
<dl class="function">
<dt id="sqlalchemy.sql.expression.false">
<tt class="descclassname">sqlalchemy.sql.expression.</tt><tt class="descname">false</tt><big>(</big><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.false" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a constant <a class="reference internal" href="#sqlalchemy.sql.elements.False_" title="sqlalchemy.sql.elements.False_"><tt class="xref py py-class docutils literal"><span class="pre">False_</span></tt></a> construct.</p>
<p>E.g.:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="kn">import</span> <span class="n">false</span>
<span class="gp">>>> </span><span class="k">print</span> <span class="n">select</span><span class="p">([</span><span class="n">t</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">x</span><span class="p">])</span><span class="o">.</span><span class="n">where</span><span class="p">(</span><span class="n">false</span><span class="p">())</span>
<span class="go">SELECT x FROM t WHERE false</span></pre></div>
</div>
<p>A backend which does not support true/false constants will render as
an expression against 1 or 0:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="k">print</span> <span class="n">select</span><span class="p">([</span><span class="n">t</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">x</span><span class="p">])</span><span class="o">.</span><span class="n">where</span><span class="p">(</span><span class="n">false</span><span class="p">())</span>
<span class="go">SELECT x FROM t WHERE 0 = 1</span></pre></div>
</div>
<p>The <a class="reference internal" href="#sqlalchemy.sql.expression.true" title="sqlalchemy.sql.expression.true"><tt class="xref py py-func docutils literal"><span class="pre">true()</span></tt></a> and <a class="reference internal" href="#sqlalchemy.sql.expression.false" title="sqlalchemy.sql.expression.false"><tt class="xref py py-func docutils literal"><span class="pre">false()</span></tt></a> constants also feature
“short circuit” operation within an <a class="reference internal" href="#sqlalchemy.sql.expression.and_" title="sqlalchemy.sql.expression.and_"><tt class="xref py py-func docutils literal"><span class="pre">and_()</span></tt></a> or <a class="reference internal" href="#sqlalchemy.sql.expression.or_" title="sqlalchemy.sql.expression.or_"><tt class="xref py py-func docutils literal"><span class="pre">or_()</span></tt></a>
conjunction:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="k">print</span> <span class="n">select</span><span class="p">([</span><span class="n">t</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">x</span><span class="p">])</span><span class="o">.</span><span class="n">where</span><span class="p">(</span><span class="n">or_</span><span class="p">(</span><span class="n">t</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">x</span> <span class="o">></span> <span class="mi">5</span><span class="p">,</span> <span class="n">true</span><span class="p">()))</span>
<span class="go">SELECT x FROM t WHERE true</span>
<span class="gp">>>> </span><span class="k">print</span> <span class="n">select</span><span class="p">([</span><span class="n">t</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">x</span><span class="p">])</span><span class="o">.</span><span class="n">where</span><span class="p">(</span><span class="n">and_</span><span class="p">(</span><span class="n">t</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">x</span> <span class="o">></span> <span class="mi">5</span><span class="p">,</span> <span class="n">false</span><span class="p">()))</span>
<span class="go">SELECT x FROM t WHERE false</span></pre></div>
</div>
<div class="versionchanged">
<p><span>Changed in version 0.9: </span><a class="reference internal" href="#sqlalchemy.sql.expression.true" title="sqlalchemy.sql.expression.true"><tt class="xref py py-func docutils literal"><span class="pre">true()</span></tt></a> and <a class="reference internal" href="#sqlalchemy.sql.expression.false" title="sqlalchemy.sql.expression.false"><tt class="xref py py-func docutils literal"><span class="pre">false()</span></tt></a> feature
better integrated behavior within conjunctions and on dialects
that don’t support true/false constants.</p>
</div>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p class="last"><a class="reference internal" href="#sqlalchemy.sql.expression.true" title="sqlalchemy.sql.expression.true"><tt class="xref py py-func docutils literal"><span class="pre">true()</span></tt></a></p>
</div>
</dd></dl>
<dl class="data">
<dt id="sqlalchemy.sql.expression.func">
<tt class="descclassname">sqlalchemy.sql.expression.</tt><tt class="descname">func</tt><em class="property"> = <sqlalchemy.sql.functions._FunctionGenerator object at 0x10371c4d0></em><a class="headerlink" href="#sqlalchemy.sql.expression.func" title="Permalink to this definition">¶</a></dt>
<dd><p>Generate SQL function expressions.</p>
<p><a class="reference internal" href="#sqlalchemy.sql.expression.func" title="sqlalchemy.sql.expression.func"><tt class="xref py py-data docutils literal"><span class="pre">func</span></tt></a> is a special object instance which generates SQL
functions based on name-based attributes, e.g.:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="k">print</span> <span class="n">func</span><span class="o">.</span><span class="n">count</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span>
<span class="go">count(:param_1)</span></pre></div>
</div>
<p>The element is a column-oriented SQL element like any other, and is
used in that way:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="k">print</span> <span class="n">select</span><span class="p">([</span><span class="n">func</span><span class="o">.</span><span class="n">count</span><span class="p">(</span><span class="n">table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">id</span><span class="p">)])</span>
<span class="go">SELECT count(sometable.id) FROM sometable</span></pre></div>
</div>
<p>Any name can be given to <a class="reference internal" href="#sqlalchemy.sql.expression.func" title="sqlalchemy.sql.expression.func"><tt class="xref py py-data docutils literal"><span class="pre">func</span></tt></a>. If the function name is unknown to
SQLAlchemy, it will be rendered exactly as is. For common SQL functions
which SQLAlchemy is aware of, the name may be interpreted as a <em>generic
function</em> which will be compiled appropriately to the target database:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="k">print</span> <span class="n">func</span><span class="o">.</span><span class="n">current_timestamp</span><span class="p">()</span>
<span class="go">CURRENT_TIMESTAMP</span></pre></div>
</div>
<p>To call functions which are present in dot-separated packages,
specify them in the same manner:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="k">print</span> <span class="n">func</span><span class="o">.</span><span class="n">stats</span><span class="o">.</span><span class="n">yield_curve</span><span class="p">(</span><span class="mi">5</span><span class="p">,</span> <span class="mi">10</span><span class="p">)</span>
<span class="go">stats.yield_curve(:yield_curve_1, :yield_curve_2)</span></pre></div>
</div>
<p>SQLAlchemy can be made aware of the return type of functions to enable
type-specific lexical and result-based behavior. For example, to ensure
that a string-based function returns a Unicode value and is similarly
treated as a string in expressions, specify
<a class="reference internal" href="types.html#sqlalchemy.types.Unicode" title="sqlalchemy.types.Unicode"><tt class="xref py py-class docutils literal"><span class="pre">Unicode</span></tt></a> as the type:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="k">print</span> <span class="n">func</span><span class="o">.</span><span class="n">my_string</span><span class="p">(</span><span class="s">u'hi'</span><span class="p">,</span> <span class="n">type_</span><span class="o">=</span><span class="n">Unicode</span><span class="p">)</span> <span class="o">+</span> <span class="s">' '</span> <span class="o">+</span> \
<span class="gp">... </span><span class="n">func</span><span class="o">.</span><span class="n">my_string</span><span class="p">(</span><span class="s">u'there'</span><span class="p">,</span> <span class="n">type_</span><span class="o">=</span><span class="n">Unicode</span><span class="p">)</span>
<span class="go">my_string(:my_string_1) || :my_string_2 || my_string(:my_string_3)</span></pre></div>
</div>
<p>The object returned by a <a class="reference internal" href="#sqlalchemy.sql.expression.func" title="sqlalchemy.sql.expression.func"><tt class="xref py py-data docutils literal"><span class="pre">func</span></tt></a> call is usually an instance of
<a class="reference internal" href="functions.html#sqlalchemy.sql.functions.Function" title="sqlalchemy.sql.functions.Function"><tt class="xref py py-class docutils literal"><span class="pre">Function</span></tt></a>.
This object meets the “column” interface, including comparison and labeling
functions. The object can also be passed the <a class="reference internal" href="connections.html#sqlalchemy.engine.Connectable.execute" title="sqlalchemy.engine.Connectable.execute"><tt class="xref py py-meth docutils literal"><span class="pre">execute()</span></tt></a>
method of a <a class="reference internal" href="connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal"><span class="pre">Connection</span></tt></a> or <a class="reference internal" href="connections.html#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><tt class="xref py py-class docutils literal"><span class="pre">Engine</span></tt></a>, where it will be
wrapped inside of a SELECT statement first:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">print</span> <span class="n">connection</span><span class="o">.</span><span class="n">execute</span><span class="p">(</span><span class="n">func</span><span class="o">.</span><span class="n">current_timestamp</span><span class="p">())</span><span class="o">.</span><span class="n">scalar</span><span class="p">()</span></pre></div>
</div>
<p>In a few exception cases, the <a class="reference internal" href="#sqlalchemy.sql.expression.func" title="sqlalchemy.sql.expression.func"><tt class="xref py py-data docutils literal"><span class="pre">func</span></tt></a> accessor
will redirect a name to a built-in expression such as <a class="reference internal" href="#sqlalchemy.sql.expression.cast" title="sqlalchemy.sql.expression.cast"><tt class="xref py py-func docutils literal"><span class="pre">cast()</span></tt></a>
or <a class="reference internal" href="#sqlalchemy.sql.expression.extract" title="sqlalchemy.sql.expression.extract"><tt class="xref py py-func docutils literal"><span class="pre">extract()</span></tt></a>, as these names have well-known meaning
but are not exactly the same as “functions” from a SQLAlchemy
perspective.</p>
<div class="versionadded">
<p><span>New in version 0.8: </span><a class="reference internal" href="#sqlalchemy.sql.expression.func" title="sqlalchemy.sql.expression.func"><tt class="xref py py-data docutils literal"><span class="pre">func</span></tt></a> can return non-function expression
constructs for common quasi-functional names like <a class="reference internal" href="#sqlalchemy.sql.expression.cast" title="sqlalchemy.sql.expression.cast"><tt class="xref py py-func docutils literal"><span class="pre">cast()</span></tt></a>
and <a class="reference internal" href="#sqlalchemy.sql.expression.extract" title="sqlalchemy.sql.expression.extract"><tt class="xref py py-func docutils literal"><span class="pre">extract()</span></tt></a>.</p>
</div>
<p>Functions which are interpreted as “generic” functions know how to
calculate their return type automatically. For a listing of known generic
functions, see <a class="reference internal" href="functions.html#generic-functions"><em>SQL and Generic Functions</em></a>.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p>The <a class="reference internal" href="#sqlalchemy.sql.expression.func" title="sqlalchemy.sql.expression.func"><tt class="xref py py-data docutils literal"><span class="pre">func</span></tt></a> construct has only limited support for calling
standalone “stored procedures”, especially those with special
parameterization concerns.</p>
<p class="last">See the section <a class="reference internal" href="connections.html#stored-procedures"><em>Calling Stored Procedures</em></a> for details on how to use
the DBAPI-level <tt class="docutils literal"><span class="pre">callproc()</span></tt> method for fully traditional stored
procedures.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="sqlalchemy.sql.expression.label">
<tt class="descclassname">sqlalchemy.sql.expression.</tt><tt class="descname">label</tt><big>(</big><em>name</em>, <em>element</em>, <em>type_=None</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.label" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a <a class="reference internal" href="#sqlalchemy.sql.expression.Label" title="sqlalchemy.sql.expression.Label"><tt class="xref py py-class docutils literal"><span class="pre">Label</span></tt></a> object for the
given <a class="reference internal" href="#sqlalchemy.sql.expression.ColumnElement" title="sqlalchemy.sql.expression.ColumnElement"><tt class="xref py py-class docutils literal"><span class="pre">ColumnElement</span></tt></a>.</p>
<p>A label changes the name of an element in the columns clause of a
<tt class="docutils literal"><span class="pre">SELECT</span></tt> statement, typically via the <tt class="docutils literal"><span class="pre">AS</span></tt> SQL keyword.</p>
<p>This functionality is more conveniently available via the
<a class="reference internal" href="#sqlalchemy.sql.expression.ColumnElement.label" title="sqlalchemy.sql.expression.ColumnElement.label"><tt class="xref py py-meth docutils literal"><span class="pre">ColumnElement.label()</span></tt></a> method on <a class="reference internal" href="#sqlalchemy.sql.expression.ColumnElement" title="sqlalchemy.sql.expression.ColumnElement"><tt class="xref py py-class docutils literal"><span class="pre">ColumnElement</span></tt></a>.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><span class="target" id="sqlalchemy.sql.expression.label.params.name"></span><strong>name</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.label.params.name">¶</a> – label name</li>
<li><span class="target" id="sqlalchemy.sql.expression.label.params.obj"></span><strong>obj</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.label.params.obj">¶</a> – a <a class="reference internal" href="#sqlalchemy.sql.expression.ColumnElement" title="sqlalchemy.sql.expression.ColumnElement"><tt class="xref py py-class docutils literal"><span class="pre">ColumnElement</span></tt></a>.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="function">
<dt id="sqlalchemy.sql.expression.literal">
<tt class="descclassname">sqlalchemy.sql.expression.</tt><tt class="descname">literal</tt><big>(</big><em>value</em>, <em>type_=None</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.literal" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a literal clause, bound to a bind parameter.</p>
<p>Literal clauses are created automatically when non-
<a class="reference internal" href="#sqlalchemy.sql.expression.ClauseElement" title="sqlalchemy.sql.expression.ClauseElement"><tt class="xref py py-class docutils literal"><span class="pre">ClauseElement</span></tt></a> objects (such as strings, ints, dates, etc.) are
used in a comparison operation with a <a class="reference internal" href="#sqlalchemy.sql.expression.ColumnElement" title="sqlalchemy.sql.expression.ColumnElement"><tt class="xref py py-class docutils literal"><span class="pre">ColumnElement</span></tt></a> subclass,
such as a <a class="reference internal" href="metadata.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal"><span class="pre">Column</span></tt></a> object. Use this function
to force the generation of a literal clause, which will be created as a
<a class="reference internal" href="#sqlalchemy.sql.expression.BindParameter" title="sqlalchemy.sql.expression.BindParameter"><tt class="xref py py-class docutils literal"><span class="pre">BindParameter</span></tt></a> with a bound value.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><span class="target" id="sqlalchemy.sql.expression.literal.params.value"></span><strong>value</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.literal.params.value">¶</a> – the value to be bound. Can be any Python object supported by
the underlying DB-API, or is translatable via the given type argument.</li>
<li><span class="target" id="sqlalchemy.sql.expression.literal.params.type_"></span><strong>type_</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.literal.params.type_">¶</a> – an optional <a class="reference internal" href="types.html#sqlalchemy.types.TypeEngine" title="sqlalchemy.types.TypeEngine"><tt class="xref py py-class docutils literal"><span class="pre">TypeEngine</span></tt></a> which
will provide bind-parameter translation for this literal.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="function">
<dt id="sqlalchemy.sql.expression.literal_column">
<tt class="descclassname">sqlalchemy.sql.expression.</tt><tt class="descname">literal_column</tt><big>(</big><em>text</em>, <em>type_=None</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.literal_column" title="Permalink to this definition">¶</a></dt>
<dd><p>Produce a <a class="reference internal" href="#sqlalchemy.sql.expression.ColumnClause" title="sqlalchemy.sql.expression.ColumnClause"><tt class="xref py py-class docutils literal"><span class="pre">ColumnClause</span></tt></a> object that has the
<a class="reference internal" href="#sqlalchemy.sql.expression.column.params.is_literal" title="sqlalchemy.sql.expression.column"><tt class="xref py py-paramref docutils literal"><span class="pre">column.is_literal</span></tt></a> flag set to True.</p>
<p><a class="reference internal" href="#sqlalchemy.sql.expression.literal_column" title="sqlalchemy.sql.expression.literal_column"><tt class="xref py py-func docutils literal"><span class="pre">literal_column()</span></tt></a> is similar to <a class="reference internal" href="#sqlalchemy.sql.expression.column" title="sqlalchemy.sql.expression.column"><tt class="xref py py-func docutils literal"><span class="pre">column()</span></tt></a>, except that
it is more often used as a “standalone” column expression that renders
exactly as stated; while <a class="reference internal" href="#sqlalchemy.sql.expression.column" title="sqlalchemy.sql.expression.column"><tt class="xref py py-func docutils literal"><span class="pre">column()</span></tt></a> stores a string name that
will be assumed to be part of a table and may be quoted as such,
<a class="reference internal" href="#sqlalchemy.sql.expression.literal_column" title="sqlalchemy.sql.expression.literal_column"><tt class="xref py py-func docutils literal"><span class="pre">literal_column()</span></tt></a> can be that, or any other arbitrary column-oriented
expression.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><span class="target" id="sqlalchemy.sql.expression.literal_column.params.text"></span><strong>text</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.literal_column.params.text">¶</a> – the text of the expression; can be any SQL expression.
Quoting rules will not be applied. To specify a column-name expression
which should be subject to quoting rules, use the <a class="reference internal" href="#sqlalchemy.sql.expression.column" title="sqlalchemy.sql.expression.column"><tt class="xref py py-func docutils literal"><span class="pre">column()</span></tt></a>
function.</li>
<li><span class="target" id="sqlalchemy.sql.expression.literal_column.params.type_"></span><strong>type_</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.literal_column.params.type_">¶</a> – an optional <a class="reference internal" href="types.html#sqlalchemy.types.TypeEngine" title="sqlalchemy.types.TypeEngine"><tt class="xref py py-class docutils literal"><span class="pre">TypeEngine</span></tt></a>
object which will
provide result-set translation and additional expression semantics for
this column. If left as None the type will be NullType.</li>
</ul>
</td>
</tr>
</tbody>
</table>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p><a class="reference internal" href="#sqlalchemy.sql.expression.column" title="sqlalchemy.sql.expression.column"><tt class="xref py py-func docutils literal"><span class="pre">column()</span></tt></a></p>
<p><a class="reference internal" href="#sqlalchemy.sql.expression.text" title="sqlalchemy.sql.expression.text"><tt class="xref py py-func docutils literal"><span class="pre">text()</span></tt></a></p>
<p class="last"><a class="reference internal" href="tutorial.html#sqlexpression-literal-column"><em>Using More Specific Text with table(), literal_column(), and column()</em></a></p>
</div>
</dd></dl>
<dl class="function">
<dt id="sqlalchemy.sql.expression.not_">
<tt class="descclassname">sqlalchemy.sql.expression.</tt><tt class="descname">not_</tt><big>(</big><em>clause</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.not_" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a negation of the given clause, i.e. <tt class="docutils literal"><span class="pre">NOT(clause)</span></tt>.</p>
<p>The <tt class="docutils literal"><span class="pre">~</span></tt> operator is also overloaded on all
<a class="reference internal" href="#sqlalchemy.sql.expression.ColumnElement" title="sqlalchemy.sql.expression.ColumnElement"><tt class="xref py py-class docutils literal"><span class="pre">ColumnElement</span></tt></a> subclasses to produce the
same result.</p>
</dd></dl>
<dl class="function">
<dt id="sqlalchemy.sql.expression.null">
<tt class="descclassname">sqlalchemy.sql.expression.</tt><tt class="descname">null</tt><big>(</big><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.null" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a constant <a class="reference internal" href="#sqlalchemy.sql.elements.Null" title="sqlalchemy.sql.elements.Null"><tt class="xref py py-class docutils literal"><span class="pre">Null</span></tt></a> construct.</p>
</dd></dl>
<dl class="function">
<dt id="sqlalchemy.sql.expression.nullsfirst">
<tt class="descclassname">sqlalchemy.sql.expression.</tt><tt class="descname">nullsfirst</tt><big>(</big><em>column</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.nullsfirst" title="Permalink to this definition">¶</a></dt>
<dd><p>Produce the <tt class="docutils literal"><span class="pre">NULLS</span> <span class="pre">FIRST</span></tt> modifier for an <tt class="docutils literal"><span class="pre">ORDER</span> <span class="pre">BY</span></tt> expression.</p>
<p><a class="reference internal" href="#sqlalchemy.sql.expression.nullsfirst" title="sqlalchemy.sql.expression.nullsfirst"><tt class="xref py py-func docutils literal"><span class="pre">nullsfirst()</span></tt></a> is intended to modify the expression produced
by <a class="reference internal" href="#sqlalchemy.sql.expression.asc" title="sqlalchemy.sql.expression.asc"><tt class="xref py py-func docutils literal"><span class="pre">asc()</span></tt></a> or <a class="reference internal" href="#sqlalchemy.sql.expression.desc" title="sqlalchemy.sql.expression.desc"><tt class="xref py py-func docutils literal"><span class="pre">desc()</span></tt></a>, and indicates how NULL values
should be handled when they are encountered during ordering:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="kn">import</span> <span class="n">desc</span><span class="p">,</span> <span class="n">nullsfirst</span>
<span class="n">stmt</span> <span class="o">=</span> <span class="n">select</span><span class="p">([</span><span class="n">users_table</span><span class="p">])</span><span class="o">.</span>\
<span class="n">order_by</span><span class="p">(</span><span class="n">nullsfirst</span><span class="p">(</span><span class="n">desc</span><span class="p">(</span><span class="n">users_table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">name</span><span class="p">)))</span></pre></div>
</div>
<p>The SQL expression from the above would resemble:</p>
<div class="highlight-python"><pre>SELECT id, name FROM user ORDER BY name DESC NULLS FIRST</pre>
</div>
<p>Like <a class="reference internal" href="#sqlalchemy.sql.expression.asc" title="sqlalchemy.sql.expression.asc"><tt class="xref py py-func docutils literal"><span class="pre">asc()</span></tt></a> and <a class="reference internal" href="#sqlalchemy.sql.expression.desc" title="sqlalchemy.sql.expression.desc"><tt class="xref py py-func docutils literal"><span class="pre">desc()</span></tt></a>, <a class="reference internal" href="#sqlalchemy.sql.expression.nullsfirst" title="sqlalchemy.sql.expression.nullsfirst"><tt class="xref py py-func docutils literal"><span class="pre">nullsfirst()</span></tt></a> is typically
invoked from the column expression itself using
<a class="reference internal" href="#sqlalchemy.sql.expression.ColumnElement.nullsfirst" title="sqlalchemy.sql.expression.ColumnElement.nullsfirst"><tt class="xref py py-meth docutils literal"><span class="pre">ColumnElement.nullsfirst()</span></tt></a>, rather than as its standalone
function version, as in:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">stmt</span> <span class="o">=</span> <span class="p">(</span><span class="n">select</span><span class="p">([</span><span class="n">users_table</span><span class="p">])</span><span class="o">.</span>
<span class="n">order_by</span><span class="p">(</span><span class="n">users_table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">name</span><span class="o">.</span><span class="n">desc</span><span class="p">()</span><span class="o">.</span><span class="n">nullsfirst</span><span class="p">())</span>
<span class="p">)</span></pre></div>
</div>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p><a class="reference internal" href="#sqlalchemy.sql.expression.asc" title="sqlalchemy.sql.expression.asc"><tt class="xref py py-func docutils literal"><span class="pre">asc()</span></tt></a></p>
<p><a class="reference internal" href="#sqlalchemy.sql.expression.desc" title="sqlalchemy.sql.expression.desc"><tt class="xref py py-func docutils literal"><span class="pre">desc()</span></tt></a></p>
<p><a class="reference internal" href="#sqlalchemy.sql.expression.nullslast" title="sqlalchemy.sql.expression.nullslast"><tt class="xref py py-func docutils literal"><span class="pre">nullslast()</span></tt></a></p>
<p class="last"><a class="reference internal" href="selectable.html#sqlalchemy.sql.expression.Select.order_by" title="sqlalchemy.sql.expression.Select.order_by"><tt class="xref py py-meth docutils literal"><span class="pre">Select.order_by()</span></tt></a></p>
</div>
</dd></dl>
<dl class="function">
<dt id="sqlalchemy.sql.expression.nullslast">
<tt class="descclassname">sqlalchemy.sql.expression.</tt><tt class="descname">nullslast</tt><big>(</big><em>column</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.nullslast" title="Permalink to this definition">¶</a></dt>
<dd><p>Produce the <tt class="docutils literal"><span class="pre">NULLS</span> <span class="pre">LAST</span></tt> modifier for an <tt class="docutils literal"><span class="pre">ORDER</span> <span class="pre">BY</span></tt> expression.</p>
<p><a class="reference internal" href="#sqlalchemy.sql.expression.nullslast" title="sqlalchemy.sql.expression.nullslast"><tt class="xref py py-func docutils literal"><span class="pre">nullslast()</span></tt></a> is intended to modify the expression produced
by <a class="reference internal" href="#sqlalchemy.sql.expression.asc" title="sqlalchemy.sql.expression.asc"><tt class="xref py py-func docutils literal"><span class="pre">asc()</span></tt></a> or <a class="reference internal" href="#sqlalchemy.sql.expression.desc" title="sqlalchemy.sql.expression.desc"><tt class="xref py py-func docutils literal"><span class="pre">desc()</span></tt></a>, and indicates how NULL values
should be handled when they are encountered during ordering:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="kn">import</span> <span class="n">desc</span><span class="p">,</span> <span class="n">nullslast</span>
<span class="n">stmt</span> <span class="o">=</span> <span class="n">select</span><span class="p">([</span><span class="n">users_table</span><span class="p">])</span><span class="o">.</span>\
<span class="n">order_by</span><span class="p">(</span><span class="n">nullslast</span><span class="p">(</span><span class="n">desc</span><span class="p">(</span><span class="n">users_table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">name</span><span class="p">)))</span></pre></div>
</div>
<p>The SQL expression from the above would resemble:</p>
<div class="highlight-python"><pre>SELECT id, name FROM user ORDER BY name DESC NULLS LAST</pre>
</div>
<p>Like <a class="reference internal" href="#sqlalchemy.sql.expression.asc" title="sqlalchemy.sql.expression.asc"><tt class="xref py py-func docutils literal"><span class="pre">asc()</span></tt></a> and <a class="reference internal" href="#sqlalchemy.sql.expression.desc" title="sqlalchemy.sql.expression.desc"><tt class="xref py py-func docutils literal"><span class="pre">desc()</span></tt></a>, <a class="reference internal" href="#sqlalchemy.sql.expression.nullslast" title="sqlalchemy.sql.expression.nullslast"><tt class="xref py py-func docutils literal"><span class="pre">nullslast()</span></tt></a> is typically
invoked from the column expression itself using
<a class="reference internal" href="#sqlalchemy.sql.expression.ColumnElement.nullslast" title="sqlalchemy.sql.expression.ColumnElement.nullslast"><tt class="xref py py-meth docutils literal"><span class="pre">ColumnElement.nullslast()</span></tt></a>, rather than as its standalone
function version, as in:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">stmt</span> <span class="o">=</span> <span class="n">select</span><span class="p">([</span><span class="n">users_table</span><span class="p">])</span><span class="o">.</span>\
<span class="n">order_by</span><span class="p">(</span><span class="n">users_table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">name</span><span class="o">.</span><span class="n">desc</span><span class="p">()</span><span class="o">.</span><span class="n">nullslast</span><span class="p">())</span></pre></div>
</div>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p><a class="reference internal" href="#sqlalchemy.sql.expression.asc" title="sqlalchemy.sql.expression.asc"><tt class="xref py py-func docutils literal"><span class="pre">asc()</span></tt></a></p>
<p><a class="reference internal" href="#sqlalchemy.sql.expression.desc" title="sqlalchemy.sql.expression.desc"><tt class="xref py py-func docutils literal"><span class="pre">desc()</span></tt></a></p>
<p><a class="reference internal" href="#sqlalchemy.sql.expression.nullsfirst" title="sqlalchemy.sql.expression.nullsfirst"><tt class="xref py py-func docutils literal"><span class="pre">nullsfirst()</span></tt></a></p>
<p class="last"><a class="reference internal" href="selectable.html#sqlalchemy.sql.expression.Select.order_by" title="sqlalchemy.sql.expression.Select.order_by"><tt class="xref py py-meth docutils literal"><span class="pre">Select.order_by()</span></tt></a></p>
</div>
</dd></dl>
<dl class="function">
<dt id="sqlalchemy.sql.expression.or_">
<tt class="descclassname">sqlalchemy.sql.expression.</tt><tt class="descname">or_</tt><big>(</big><em>*clauses</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.or_" title="Permalink to this definition">¶</a></dt>
<dd><p>Produce a conjunction of expressions joined by <tt class="docutils literal"><span class="pre">OR</span></tt>.</p>
<p>E.g.:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="kn">import</span> <span class="n">or_</span>
<span class="n">stmt</span> <span class="o">=</span> <span class="n">select</span><span class="p">([</span><span class="n">users_table</span><span class="p">])</span><span class="o">.</span><span class="n">where</span><span class="p">(</span>
<span class="n">or_</span><span class="p">(</span>
<span class="n">users_table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">name</span> <span class="o">==</span> <span class="s">'wendy'</span><span class="p">,</span>
<span class="n">users_table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">name</span> <span class="o">==</span> <span class="s">'jack'</span>
<span class="p">)</span>
<span class="p">)</span></pre></div>
</div>
<p>The <a class="reference internal" href="#sqlalchemy.sql.expression.or_" title="sqlalchemy.sql.expression.or_"><tt class="xref py py-func docutils literal"><span class="pre">or_()</span></tt></a> conjunction is also available using the
Python <tt class="docutils literal"><span class="pre">|</span></tt> operator (though note that compound expressions
need to be parenthesized in order to function with Python
operator precedence behavior):</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">stmt</span> <span class="o">=</span> <span class="n">select</span><span class="p">([</span><span class="n">users_table</span><span class="p">])</span><span class="o">.</span><span class="n">where</span><span class="p">(</span>
<span class="p">(</span><span class="n">users_table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">name</span> <span class="o">==</span> <span class="s">'wendy'</span><span class="p">)</span> <span class="o">|</span>
<span class="p">(</span><span class="n">users_table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">name</span> <span class="o">==</span> <span class="s">'jack'</span><span class="p">)</span>
<span class="p">)</span></pre></div>
</div>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p class="last"><a class="reference internal" href="#sqlalchemy.sql.expression.and_" title="sqlalchemy.sql.expression.and_"><tt class="xref py py-func docutils literal"><span class="pre">and_()</span></tt></a></p>
</div>
</dd></dl>
<dl class="function">
<dt id="sqlalchemy.sql.expression.outparam">
<tt class="descclassname">sqlalchemy.sql.expression.</tt><tt class="descname">outparam</tt><big>(</big><em>key</em>, <em>type_=None</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.outparam" title="Permalink to this definition">¶</a></dt>
<dd><p>Create an ‘OUT’ parameter for usage in functions (stored procedures),
for databases which support them.</p>
<p>The <tt class="docutils literal"><span class="pre">outparam</span></tt> can be used like a regular function parameter.
The “output” value will be available from the
<a class="reference internal" href="connections.html#sqlalchemy.engine.ResultProxy" title="sqlalchemy.engine.ResultProxy"><tt class="xref py py-class docutils literal"><span class="pre">ResultProxy</span></tt></a> object via its <tt class="docutils literal"><span class="pre">out_parameters</span></tt>
attribute, which returns a dictionary containing the values.</p>
</dd></dl>
<dl class="function">
<dt id="sqlalchemy.sql.expression.over">
<tt class="descclassname">sqlalchemy.sql.expression.</tt><tt class="descname">over</tt><big>(</big><em>func</em>, <em>partition_by=None</em>, <em>order_by=None</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.over" title="Permalink to this definition">¶</a></dt>
<dd><p>Produce an <a class="reference internal" href="#sqlalchemy.sql.expression.Over" title="sqlalchemy.sql.expression.Over"><tt class="xref py py-class docutils literal"><span class="pre">Over</span></tt></a> object against a function.</p>
<p>Used against aggregate or so-called “window” functions,
for database backends that support window functions.</p>
<p>E.g.:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="kn">import</span> <span class="n">over</span>
<span class="n">over</span><span class="p">(</span><span class="n">func</span><span class="o">.</span><span class="n">row_number</span><span class="p">(),</span> <span class="n">order_by</span><span class="o">=</span><span class="s">'x'</span><span class="p">)</span></pre></div>
</div>
<p>Would produce “ROW_NUMBER() OVER(ORDER BY x)”.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><span class="target" id="sqlalchemy.sql.expression.over.params.func"></span><strong>func</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.over.params.func">¶</a> – a <a class="reference internal" href="functions.html#sqlalchemy.sql.functions.FunctionElement" title="sqlalchemy.sql.functions.FunctionElement"><tt class="xref py py-class docutils literal"><span class="pre">FunctionElement</span></tt></a> construct, typically
generated by <a class="reference internal" href="#sqlalchemy.sql.expression.func" title="sqlalchemy.sql.expression.func"><tt class="xref py py-data docutils literal"><span class="pre">func</span></tt></a>.</li>
<li><span class="target" id="sqlalchemy.sql.expression.over.params.partition_by"></span><strong>partition_by</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.over.params.partition_by">¶</a> – a column element or string, or a list
of such, that will be used as the PARTITION BY clause
of the OVER construct.</li>
<li><span class="target" id="sqlalchemy.sql.expression.over.params.order_by"></span><strong>order_by</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.over.params.order_by">¶</a> – a column element or string, or a list
of such, that will be used as the ORDER BY clause
of the OVER construct.</li>
</ul>
</td>
</tr>
</tbody>
</table>
<p>This function is also available from the <a class="reference internal" href="#sqlalchemy.sql.expression.func" title="sqlalchemy.sql.expression.func"><tt class="xref py py-data docutils literal"><span class="pre">func</span></tt></a>
construct itself via the <a class="reference internal" href="functions.html#sqlalchemy.sql.functions.FunctionElement.over" title="sqlalchemy.sql.functions.FunctionElement.over"><tt class="xref py py-meth docutils literal"><span class="pre">FunctionElement.over()</span></tt></a> method.</p>
<div class="versionadded">
<p><span>New in version 0.7.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="sqlalchemy.sql.expression.text">
<tt class="descclassname">sqlalchemy.sql.expression.</tt><tt class="descname">text</tt><big>(</big><em>text</em>, <em>bind=None</em>, <em>bindparams=None</em>, <em>typemap=None</em>, <em>autocommit=None</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.text" title="Permalink to this definition">¶</a></dt>
<dd><p>Construct a new <a class="reference internal" href="#sqlalchemy.sql.expression.TextClause" title="sqlalchemy.sql.expression.TextClause"><tt class="xref py py-class docutils literal"><span class="pre">TextClause</span></tt></a> clause, representing
a textual SQL string directly.</p>
<p>E.g.:</p>
<div class="highlight-python"><pre>fom sqlalchemy import text
t = text("SELECT * FROM users")
result = connection.execute(t)</pre>
</div>
<p>The advantages <a class="reference internal" href="#sqlalchemy.sql.expression.text" title="sqlalchemy.sql.expression.text"><tt class="xref py py-func docutils literal"><span class="pre">text()</span></tt></a> provides over a plain string are
backend-neutral support for bind parameters, per-statement
execution options, as well as
bind parameter and result-column typing behavior, allowing
SQLAlchemy type constructs to play a role when executing
a statement that is specified literally. The construct can also
be provided with a <tt class="docutils literal"><span class="pre">.c</span></tt> collection of column elements, allowing
it to be embedded in other SQL expression constructs as a subquery.</p>
<p>Bind parameters are specified by name, using the format <tt class="docutils literal"><span class="pre">:name</span></tt>.
E.g.:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">t</span> <span class="o">=</span> <span class="n">text</span><span class="p">(</span><span class="s">"SELECT * FROM users WHERE id=:user_id"</span><span class="p">)</span>
<span class="n">result</span> <span class="o">=</span> <span class="n">connection</span><span class="o">.</span><span class="n">execute</span><span class="p">(</span><span class="n">t</span><span class="p">,</span> <span class="n">user_id</span><span class="o">=</span><span class="mi">12</span><span class="p">)</span></pre></div>
</div>
<p>For SQL statements where a colon is required verbatim, as within
an inline string, use a backslash to escape:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">t</span> <span class="o">=</span> <span class="n">text</span><span class="p">(</span><span class="s">"SELECT * FROM users WHERE name='\:username'"</span><span class="p">)</span></pre></div>
</div>
<p>The <a class="reference internal" href="#sqlalchemy.sql.expression.TextClause" title="sqlalchemy.sql.expression.TextClause"><tt class="xref py py-class docutils literal"><span class="pre">TextClause</span></tt></a> 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
<a class="reference internal" href="#sqlalchemy.sql.expression.TextClause.bindparams" title="sqlalchemy.sql.expression.TextClause.bindparams"><tt class="xref py py-meth docutils literal"><span class="pre">TextClause.bindparams()</span></tt></a> method is used to provide bound
parameter detail, and <a class="reference internal" href="#sqlalchemy.sql.expression.TextClause.columns" title="sqlalchemy.sql.expression.TextClause.columns"><tt class="xref py py-meth docutils literal"><span class="pre">TextClause.columns()</span></tt></a> method allows
specification of return columns including names and types:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">t</span> <span class="o">=</span> <span class="n">text</span><span class="p">(</span><span class="s">"SELECT * FROM users WHERE id=:user_id"</span><span class="p">)</span><span class="o">.</span>\
<span class="n">bindparams</span><span class="p">(</span><span class="n">user_id</span><span class="o">=</span><span class="mi">7</span><span class="p">)</span><span class="o">.</span>\
<span class="n">columns</span><span class="p">(</span><span class="nb">id</span><span class="o">=</span><span class="n">Integer</span><span class="p">,</span> <span class="n">name</span><span class="o">=</span><span class="n">String</span><span class="p">)</span>
<span class="k">for</span> <span class="nb">id</span><span class="p">,</span> <span class="n">name</span> <span class="ow">in</span> <span class="n">connection</span><span class="o">.</span><span class="n">execute</span><span class="p">(</span><span class="n">t</span><span class="p">):</span>
<span class="k">print</span><span class="p">(</span><span class="nb">id</span><span class="p">,</span> <span class="n">name</span><span class="p">)</span></pre></div>
</div>
<p>The <a class="reference internal" href="#sqlalchemy.sql.expression.text" title="sqlalchemy.sql.expression.text"><tt class="xref py py-func docutils literal"><span class="pre">text()</span></tt></a> construct is used internally in cases when
a literal string is specified for part of a larger query, such as
when a string is specified to the <a class="reference internal" href="selectable.html#sqlalchemy.sql.expression.Select.where" title="sqlalchemy.sql.expression.Select.where"><tt class="xref py py-meth docutils literal"><span class="pre">Select.where()</span></tt></a> method of
<a class="reference internal" href="selectable.html#sqlalchemy.sql.expression.Select" title="sqlalchemy.sql.expression.Select"><tt class="xref py py-class docutils literal"><span class="pre">Select</span></tt></a>. In those cases, the same
bind parameter syntax is applied:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">s</span> <span class="o">=</span> <span class="n">select</span><span class="p">([</span><span class="n">users</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">id</span><span class="p">,</span> <span class="n">users</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">name</span><span class="p">])</span><span class="o">.</span><span class="n">where</span><span class="p">(</span><span class="s">"id=:user_id"</span><span class="p">)</span>
<span class="n">result</span> <span class="o">=</span> <span class="n">connection</span><span class="o">.</span><span class="n">execute</span><span class="p">(</span><span class="n">s</span><span class="p">,</span> <span class="n">user_id</span><span class="o">=</span><span class="mi">12</span><span class="p">)</span></pre></div>
</div>
<p>Using <a class="reference internal" href="#sqlalchemy.sql.expression.text" title="sqlalchemy.sql.expression.text"><tt class="xref py py-func docutils literal"><span class="pre">text()</span></tt></a> explicitly usually implies the construction
of a full, standalone statement. As such, SQLAlchemy refers
to it as an <a class="reference internal" href="selectable.html#sqlalchemy.sql.expression.Executable" title="sqlalchemy.sql.expression.Executable"><tt class="xref py py-class docutils literal"><span class="pre">Executable</span></tt></a> object, and it supports
the <a class="reference internal" href="selectable.html#sqlalchemy.sql.expression.Executable.execution_options" title="sqlalchemy.sql.expression.Executable.execution_options"><tt class="xref py py-meth docutils literal"><span class="pre">Executable.execution_options()</span></tt></a> method. For example,
a <a class="reference internal" href="#sqlalchemy.sql.expression.text" title="sqlalchemy.sql.expression.text"><tt class="xref py py-func docutils literal"><span class="pre">text()</span></tt></a> construct that should be subject to “autocommit”
can be set explicitly so using the
<a class="reference internal" href="connections.html#sqlalchemy.engine.Connection.execution_options.params.autocommit" title="sqlalchemy.engine.Connection.execution_options"><tt class="xref py py-paramref docutils literal"><span class="pre">Connection.execution_options.autocommit</span></tt></a> option:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">t</span> <span class="o">=</span> <span class="n">text</span><span class="p">(</span><span class="s">"EXEC my_procedural_thing()"</span><span class="p">)</span><span class="o">.</span>\
<span class="n">execution_options</span><span class="p">(</span><span class="n">autocommit</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span></pre></div>
</div>
<p>Note that SQLAlchemy’s usual “autocommit” behavior applies to
<a class="reference internal" href="#sqlalchemy.sql.expression.text" title="sqlalchemy.sql.expression.text"><tt class="xref py py-func docutils literal"><span class="pre">text()</span></tt></a> constructs implicitly - that is, statements which begin
with a phrase such as <tt class="docutils literal"><span class="pre">INSERT</span></tt>, <tt class="docutils literal"><span class="pre">UPDATE</span></tt>, <tt class="docutils literal"><span class="pre">DELETE</span></tt>,
or a variety of other phrases specific to certain backends, will
be eligible for autocommit if no transaction is in progress.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><span class="target" id="sqlalchemy.sql.expression.text.params.text"></span><strong>text</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.text.params.text">¶</a> – the text of the SQL statement to be created. use <tt class="docutils literal"><span class="pre">:<param></span></tt>
to specify bind parameters; they will be compiled to their
engine-specific format.</li>
<li><span class="target" id="sqlalchemy.sql.expression.text.params.autocommit"></span><strong>autocommit</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.text.params.autocommit">¶</a> – Deprecated. Use .execution_options(autocommit=<True|False>)
to set the autocommit option.</li>
<li><span class="target" id="sqlalchemy.sql.expression.text.params.bind"></span><strong>bind</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.text.params.bind">¶</a> – an optional connection or engine to be used for this text query.</li>
<li><span class="target" id="sqlalchemy.sql.expression.text.params.bindparams"></span><strong>bindparams</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.text.params.bindparams">¶</a> – <p>Deprecated. A list of <a class="reference internal" href="#sqlalchemy.sql.expression.bindparam" title="sqlalchemy.sql.expression.bindparam"><tt class="xref py py-func docutils literal"><span class="pre">bindparam()</span></tt></a> instances used to
provide information about parameters embedded in the statement.
This argument now invokes the <a class="reference internal" href="#sqlalchemy.sql.expression.TextClause.bindparams" title="sqlalchemy.sql.expression.TextClause.bindparams"><tt class="xref py py-meth docutils literal"><span class="pre">TextClause.bindparams()</span></tt></a>
method on the construct before returning it. E.g.:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">stmt</span> <span class="o">=</span> <span class="n">text</span><span class="p">(</span><span class="s">"SELECT * FROM table WHERE id=:id"</span><span class="p">,</span>
<span class="n">bindparams</span><span class="o">=</span><span class="p">[</span><span class="n">bindparam</span><span class="p">(</span><span class="s">'id'</span><span class="p">,</span> <span class="n">value</span><span class="o">=</span><span class="mi">5</span><span class="p">,</span> <span class="n">type_</span><span class="o">=</span><span class="n">Integer</span><span class="p">)])</span></pre></div>
</div>
<p>Is equivalent to:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">stmt</span> <span class="o">=</span> <span class="n">text</span><span class="p">(</span><span class="s">"SELECT * FROM table WHERE id=:id"</span><span class="p">)</span><span class="o">.</span>\
<span class="n">bindparams</span><span class="p">(</span><span class="n">bindparam</span><span class="p">(</span><span class="s">'id'</span><span class="p">,</span> <span class="n">value</span><span class="o">=</span><span class="mi">5</span><span class="p">,</span> <span class="n">type_</span><span class="o">=</span><span class="n">Integer</span><span class="p">))</span></pre></div>
</div>
<div class="deprecated">
<p><span>Deprecated since version 0.9.0: </span>the <a class="reference internal" href="#sqlalchemy.sql.expression.TextClause.bindparams" title="sqlalchemy.sql.expression.TextClause.bindparams"><tt class="xref py py-meth docutils literal"><span class="pre">TextClause.bindparams()</span></tt></a> method
supersedes the <tt class="docutils literal"><span class="pre">bindparams</span></tt> argument to <a class="reference internal" href="#sqlalchemy.sql.expression.text" title="sqlalchemy.sql.expression.text"><tt class="xref py py-func docutils literal"><span class="pre">text()</span></tt></a>.</p>
</div>
</li>
<li><span class="target" id="sqlalchemy.sql.expression.text.params.typemap"></span><strong>typemap</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.text.params.typemap">¶</a> – <p>Deprecated. A dictionary mapping the names of columns
represented in the columns clause of a <tt class="docutils literal"><span class="pre">SELECT</span></tt> statement
to type objects,
which will be used to perform post-processing on columns within
the result set. This parameter now invokes the
<a class="reference internal" href="#sqlalchemy.sql.expression.TextClause.columns" title="sqlalchemy.sql.expression.TextClause.columns"><tt class="xref py py-meth docutils literal"><span class="pre">TextClause.columns()</span></tt></a> method, which returns a
<a class="reference internal" href="selectable.html#sqlalchemy.sql.expression.TextAsFrom" title="sqlalchemy.sql.expression.TextAsFrom"><tt class="xref py py-class docutils literal"><span class="pre">TextAsFrom</span></tt></a> construct that gains a <tt class="docutils literal"><span class="pre">.c</span></tt> collection and
can be embedded in other expressions. E.g.:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">stmt</span> <span class="o">=</span> <span class="n">text</span><span class="p">(</span><span class="s">"SELECT * FROM table"</span><span class="p">,</span>
<span class="n">typemap</span><span class="o">=</span><span class="p">{</span><span class="s">'id'</span><span class="p">:</span> <span class="n">Integer</span><span class="p">,</span> <span class="s">'name'</span><span class="p">:</span> <span class="n">String</span><span class="p">},</span>
<span class="p">)</span></pre></div>
</div>
<p>Is equivalent to:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">stmt</span> <span class="o">=</span> <span class="n">text</span><span class="p">(</span><span class="s">"SELECT * FROM table"</span><span class="p">)</span><span class="o">.</span><span class="n">columns</span><span class="p">(</span><span class="nb">id</span><span class="o">=</span><span class="n">Integer</span><span class="p">,</span>
<span class="n">name</span><span class="o">=</span><span class="n">String</span><span class="p">)</span></pre></div>
</div>
<p>Or alternatively:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">sqlalchemy.sql</span> <span class="kn">import</span> <span class="n">column</span>
<span class="n">stmt</span> <span class="o">=</span> <span class="n">text</span><span class="p">(</span><span class="s">"SELECT * FROM table"</span><span class="p">)</span><span class="o">.</span><span class="n">columns</span><span class="p">(</span>
<span class="n">column</span><span class="p">(</span><span class="s">'id'</span><span class="p">,</span> <span class="n">Integer</span><span class="p">),</span>
<span class="n">column</span><span class="p">(</span><span class="s">'name'</span><span class="p">,</span> <span class="n">String</span><span class="p">)</span>
<span class="p">)</span></pre></div>
</div>
<div class="deprecated">
<p><span>Deprecated since version 0.9.0: </span>the <a class="reference internal" href="#sqlalchemy.sql.expression.TextClause.columns" title="sqlalchemy.sql.expression.TextClause.columns"><tt class="xref py py-meth docutils literal"><span class="pre">TextClause.columns()</span></tt></a> method
supersedes the <tt class="docutils literal"><span class="pre">typemap</span></tt> argument to <a class="reference internal" href="#sqlalchemy.sql.expression.text" title="sqlalchemy.sql.expression.text"><tt class="xref py py-func docutils literal"><span class="pre">text()</span></tt></a>.</p>
</div>
</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="function">
<dt id="sqlalchemy.sql.expression.true">
<tt class="descclassname">sqlalchemy.sql.expression.</tt><tt class="descname">true</tt><big>(</big><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.true" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a constant <a class="reference internal" href="#sqlalchemy.sql.elements.True_" title="sqlalchemy.sql.elements.True_"><tt class="xref py py-class docutils literal"><span class="pre">True_</span></tt></a> construct.</p>
<p>E.g.:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="kn">import</span> <span class="n">true</span>
<span class="gp">>>> </span><span class="k">print</span> <span class="n">select</span><span class="p">([</span><span class="n">t</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">x</span><span class="p">])</span><span class="o">.</span><span class="n">where</span><span class="p">(</span><span class="n">true</span><span class="p">())</span>
<span class="go">SELECT x FROM t WHERE true</span></pre></div>
</div>
<p>A backend which does not support true/false constants will render as
an expression against 1 or 0:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="k">print</span> <span class="n">select</span><span class="p">([</span><span class="n">t</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">x</span><span class="p">])</span><span class="o">.</span><span class="n">where</span><span class="p">(</span><span class="n">true</span><span class="p">())</span>
<span class="go">SELECT x FROM t WHERE 1 = 1</span></pre></div>
</div>
<p>The <a class="reference internal" href="#sqlalchemy.sql.expression.true" title="sqlalchemy.sql.expression.true"><tt class="xref py py-func docutils literal"><span class="pre">true()</span></tt></a> and <a class="reference internal" href="#sqlalchemy.sql.expression.false" title="sqlalchemy.sql.expression.false"><tt class="xref py py-func docutils literal"><span class="pre">false()</span></tt></a> constants also feature
“short circuit” operation within an <a class="reference internal" href="#sqlalchemy.sql.expression.and_" title="sqlalchemy.sql.expression.and_"><tt class="xref py py-func docutils literal"><span class="pre">and_()</span></tt></a> or <a class="reference internal" href="#sqlalchemy.sql.expression.or_" title="sqlalchemy.sql.expression.or_"><tt class="xref py py-func docutils literal"><span class="pre">or_()</span></tt></a>
conjunction:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="k">print</span> <span class="n">select</span><span class="p">([</span><span class="n">t</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">x</span><span class="p">])</span><span class="o">.</span><span class="n">where</span><span class="p">(</span><span class="n">or_</span><span class="p">(</span><span class="n">t</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">x</span> <span class="o">></span> <span class="mi">5</span><span class="p">,</span> <span class="n">true</span><span class="p">()))</span>
<span class="go">SELECT x FROM t WHERE true</span>
<span class="gp">>>> </span><span class="k">print</span> <span class="n">select</span><span class="p">([</span><span class="n">t</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">x</span><span class="p">])</span><span class="o">.</span><span class="n">where</span><span class="p">(</span><span class="n">and_</span><span class="p">(</span><span class="n">t</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">x</span> <span class="o">></span> <span class="mi">5</span><span class="p">,</span> <span class="n">false</span><span class="p">()))</span>
<span class="go">SELECT x FROM t WHERE false</span></pre></div>
</div>
<div class="versionchanged">
<p><span>Changed in version 0.9: </span><a class="reference internal" href="#sqlalchemy.sql.expression.true" title="sqlalchemy.sql.expression.true"><tt class="xref py py-func docutils literal"><span class="pre">true()</span></tt></a> and <a class="reference internal" href="#sqlalchemy.sql.expression.false" title="sqlalchemy.sql.expression.false"><tt class="xref py py-func docutils literal"><span class="pre">false()</span></tt></a> feature
better integrated behavior within conjunctions and on dialects
that don’t support true/false constants.</p>
</div>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p class="last"><a class="reference internal" href="#sqlalchemy.sql.expression.false" title="sqlalchemy.sql.expression.false"><tt class="xref py py-func docutils literal"><span class="pre">false()</span></tt></a></p>
</div>
</dd></dl>
<dl class="function">
<dt id="sqlalchemy.sql.expression.tuple_">
<tt class="descclassname">sqlalchemy.sql.expression.</tt><tt class="descname">tuple_</tt><big>(</big><em>*clauses</em>, <em>**kw</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.tuple_" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a <a class="reference internal" href="#sqlalchemy.sql.expression.Tuple" title="sqlalchemy.sql.expression.Tuple"><tt class="xref py py-class docutils literal"><span class="pre">Tuple</span></tt></a>.</p>
<p>Main usage is to produce a composite IN construct:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="kn">import</span> <span class="n">tuple_</span>
<span class="n">tuple_</span><span class="p">(</span><span class="n">table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">col1</span><span class="p">,</span> <span class="n">table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">col2</span><span class="p">)</span><span class="o">.</span><span class="n">in_</span><span class="p">(</span>
<span class="p">[(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">),</span> <span class="p">(</span><span class="mi">5</span><span class="p">,</span> <span class="mi">12</span><span class="p">),</span> <span class="p">(</span><span class="mi">10</span><span class="p">,</span> <span class="mi">19</span><span class="p">)]</span>
<span class="p">)</span></pre></div>
</div>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">The composite IN construct is not supported by all backends,
and is currently known to work on Postgresql and MySQL,
but not SQLite. Unsupported backends will raise
a subclass of <a class="reference internal" href="exceptions.html#sqlalchemy.exc.DBAPIError" title="sqlalchemy.exc.DBAPIError"><tt class="xref py py-class docutils literal"><span class="pre">DBAPIError</span></tt></a> when such
an expression is invoked.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="sqlalchemy.sql.expression.type_coerce">
<tt class="descclassname">sqlalchemy.sql.expression.</tt><tt class="descname">type_coerce</tt><big>(</big><em>expression</em>, <em>type_</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.type_coerce" title="Permalink to this definition">¶</a></dt>
<dd><p>Associate a SQL expression with a particular type, without rendering
<tt class="docutils literal"><span class="pre">CAST</span></tt>.</p>
<p>E.g.:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="kn">import</span> <span class="n">type_coerce</span>
<span class="n">stmt</span> <span class="o">=</span> <span class="n">select</span><span class="p">([</span><span class="n">type_coerce</span><span class="p">(</span><span class="n">log_table</span><span class="o">.</span><span class="n">date_string</span><span class="p">,</span> <span class="n">StringDateTime</span><span class="p">())])</span></pre></div>
</div>
<p>The above construct will produce SQL that is usually otherwise unaffected
by the <a class="reference internal" href="#sqlalchemy.sql.expression.type_coerce" title="sqlalchemy.sql.expression.type_coerce"><tt class="xref py py-func docutils literal"><span class="pre">type_coerce()</span></tt></a> call:</p>
<div class="highlight-python"><pre>SELECT date_string FROM log</pre>
</div>
<p>However, when result rows are fetched, the <tt class="docutils literal"><span class="pre">StringDateTime</span></tt> type
will be applied to result rows on behalf of the <tt class="docutils literal"><span class="pre">date_string</span></tt> column.</p>
<p>A type that features bound-value handling will also have that behavior
take effect when literal values or <a class="reference internal" href="#sqlalchemy.sql.expression.bindparam" title="sqlalchemy.sql.expression.bindparam"><tt class="xref py py-func docutils literal"><span class="pre">bindparam()</span></tt></a> constructs are
passed to <a class="reference internal" href="#sqlalchemy.sql.expression.type_coerce" title="sqlalchemy.sql.expression.type_coerce"><tt class="xref py py-func docutils literal"><span class="pre">type_coerce()</span></tt></a> as targets.
For example, if a type implements the <a class="reference internal" href="types.html#sqlalchemy.types.TypeEngine.bind_expression" title="sqlalchemy.types.TypeEngine.bind_expression"><tt class="xref py py-meth docutils literal"><span class="pre">TypeEngine.bind_expression()</span></tt></a>
method or <a class="reference internal" href="types.html#sqlalchemy.types.TypeEngine.bind_processor" title="sqlalchemy.types.TypeEngine.bind_processor"><tt class="xref py py-meth docutils literal"><span class="pre">TypeEngine.bind_processor()</span></tt></a> method or equivalent,
these functions will take effect at statement compilation/execution time
when a literal value is passed, as in:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="c"># bound-value handling of MyStringType will be applied to the</span>
<span class="c"># literal value "some string"</span>
<span class="n">stmt</span> <span class="o">=</span> <span class="n">select</span><span class="p">([</span><span class="n">type_coerce</span><span class="p">(</span><span class="s">"some string"</span><span class="p">,</span> <span class="n">MyStringType</span><span class="p">)])</span></pre></div>
</div>
<p><a class="reference internal" href="#sqlalchemy.sql.expression.type_coerce" title="sqlalchemy.sql.expression.type_coerce"><tt class="xref py py-func docutils literal"><span class="pre">type_coerce()</span></tt></a> is similar to the <a class="reference internal" href="#sqlalchemy.sql.expression.cast" title="sqlalchemy.sql.expression.cast"><tt class="xref py py-func docutils literal"><span class="pre">cast()</span></tt></a> function,
except that it does not render the <tt class="docutils literal"><span class="pre">CAST</span></tt> expression in the resulting
statement.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><span class="target" id="sqlalchemy.sql.expression.type_coerce.params.expression"></span><strong>expression</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.type_coerce.params.expression">¶</a> – A SQL expression, such as a <a class="reference internal" href="#sqlalchemy.sql.expression.ColumnElement" title="sqlalchemy.sql.expression.ColumnElement"><tt class="xref py py-class docutils literal"><span class="pre">ColumnElement</span></tt></a>
expression or a Python string which will be coerced into a bound literal
value.</li>
<li><span class="target" id="sqlalchemy.sql.expression.type_coerce.params.type_"></span><strong>type_</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.type_coerce.params.type_">¶</a> – A <a class="reference internal" href="types.html#sqlalchemy.types.TypeEngine" title="sqlalchemy.types.TypeEngine"><tt class="xref py py-class docutils literal"><span class="pre">TypeEngine</span></tt></a> class or instance indicating
the type to which the expression is coerced.</li>
</ul>
</td>
</tr>
</tbody>
</table>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p class="last"><a class="reference internal" href="#sqlalchemy.sql.expression.cast" title="sqlalchemy.sql.expression.cast"><tt class="xref py py-func docutils literal"><span class="pre">cast()</span></tt></a></p>
</div>
</dd></dl>
<dl class="class">
<dt id="sqlalchemy.sql.expression.BinaryExpression">
<em class="property">class </em><tt class="descclassname">sqlalchemy.sql.expression.</tt><tt class="descname">BinaryExpression</tt><big>(</big><em>left</em>, <em>right</em>, <em>operator</em>, <em>type_=None</em>, <em>negate=None</em>, <em>modifiers=None</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.BinaryExpression" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference internal" href="#sqlalchemy.sql.expression.ColumnElement" title="sqlalchemy.sql.expression.ColumnElement"><tt class="xref py py-class docutils literal"><span class="pre">sqlalchemy.sql.expression.ColumnElement</span></tt></a></p>
<p>Represent an expression that is <tt class="docutils literal"><span class="pre">LEFT</span> <span class="pre"><operator></span> <span class="pre">RIGHT</span></tt>.</p>
<p>A <a class="reference internal" href="#sqlalchemy.sql.expression.BinaryExpression" title="sqlalchemy.sql.expression.BinaryExpression"><tt class="xref py py-class docutils literal"><span class="pre">BinaryExpression</span></tt></a> is generated automatically
whenever two column expressions are used in a Python binary expression:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">sqlalchemy.sql</span> <span class="kn">import</span> <span class="n">column</span>
<span class="gp">>>> </span><span class="n">column</span><span class="p">(</span><span class="s">'a'</span><span class="p">)</span> <span class="o">+</span> <span class="n">column</span><span class="p">(</span><span class="s">'b'</span><span class="p">)</span>
<span class="go"><sqlalchemy.sql.expression.BinaryExpression object at 0x101029dd0></span>
<span class="gp">>>> </span><span class="k">print</span> <span class="n">column</span><span class="p">(</span><span class="s">'a'</span><span class="p">)</span> <span class="o">+</span> <span class="n">column</span><span class="p">(</span><span class="s">'b'</span><span class="p">)</span>
<span class="go">a + b</span></pre></div>
</div>
<dl class="method">
<dt id="sqlalchemy.sql.expression.BinaryExpression.compare">
<tt class="descname">compare</tt><big>(</big><em>other</em>, <em>**kw</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.BinaryExpression.compare" title="Permalink to this definition">¶</a></dt>
<dd><p>Compare this <a class="reference internal" href="#sqlalchemy.sql.expression.BinaryExpression" title="sqlalchemy.sql.expression.BinaryExpression"><tt class="xref py py-class docutils literal"><span class="pre">BinaryExpression</span></tt></a> against the
given <a class="reference internal" href="#sqlalchemy.sql.expression.BinaryExpression" title="sqlalchemy.sql.expression.BinaryExpression"><tt class="xref py py-class docutils literal"><span class="pre">BinaryExpression</span></tt></a>.</p>
</dd></dl>
</dd></dl>
<dl class="class">
<dt id="sqlalchemy.sql.expression.BindParameter">
<em class="property">class </em><tt class="descclassname">sqlalchemy.sql.expression.</tt><tt class="descname">BindParameter</tt><big>(</big><em>key</em>, <em>value=symbol('NO_ARG')</em>, <em>type_=None</em>, <em>unique=False</em>, <em>required=symbol('NO_ARG')</em>, <em>quote=None</em>, <em>callable_=None</em>, <em>isoutparam=False</em>, <em>_compared_to_operator=None</em>, <em>_compared_to_type=None</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.BindParameter" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference internal" href="#sqlalchemy.sql.expression.ColumnElement" title="sqlalchemy.sql.expression.ColumnElement"><tt class="xref py py-class docutils literal"><span class="pre">sqlalchemy.sql.expression.ColumnElement</span></tt></a></p>
<p>Represent a “bound expression”.</p>
<p><a class="reference internal" href="#sqlalchemy.sql.expression.BindParameter" title="sqlalchemy.sql.expression.BindParameter"><tt class="xref py py-class docutils literal"><span class="pre">BindParameter</span></tt></a> is invoked explicitly using the
<a class="reference internal" href="#sqlalchemy.sql.expression.bindparam" title="sqlalchemy.sql.expression.bindparam"><tt class="xref py py-func docutils literal"><span class="pre">bindparam()</span></tt></a> function, as in:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="kn">import</span> <span class="n">bindparam</span>
<span class="n">stmt</span> <span class="o">=</span> <span class="n">select</span><span class="p">([</span><span class="n">users_table</span><span class="p">])</span><span class="o">.</span>\
<span class="n">where</span><span class="p">(</span><span class="n">users_table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">name</span> <span class="o">==</span> <span class="n">bindparam</span><span class="p">(</span><span class="s">'username'</span><span class="p">))</span></pre></div>
</div>
<p>Detailed discussion of how <a class="reference internal" href="#sqlalchemy.sql.expression.BindParameter" title="sqlalchemy.sql.expression.BindParameter"><tt class="xref py py-class docutils literal"><span class="pre">BindParameter</span></tt></a> is used is
at <a class="reference internal" href="#sqlalchemy.sql.expression.bindparam" title="sqlalchemy.sql.expression.bindparam"><tt class="xref py py-func docutils literal"><span class="pre">bindparam()</span></tt></a>.</p>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p class="last"><a class="reference internal" href="#sqlalchemy.sql.expression.bindparam" title="sqlalchemy.sql.expression.bindparam"><tt class="xref py py-func docutils literal"><span class="pre">bindparam()</span></tt></a></p>
</div>
<dl class="method">
<dt id="sqlalchemy.sql.expression.BindParameter.__init__">
<tt class="descname">__init__</tt><big>(</big><em>key</em>, <em>value=symbol('NO_ARG')</em>, <em>type_=None</em>, <em>unique=False</em>, <em>required=symbol('NO_ARG')</em>, <em>quote=None</em>, <em>callable_=None</em>, <em>isoutparam=False</em>, <em>_compared_to_operator=None</em>, <em>_compared_to_type=None</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.BindParameter.__init__" title="Permalink to this definition">¶</a></dt>
<dd><p>Construct a new <a class="reference internal" href="#sqlalchemy.sql.expression.BindParameter" title="sqlalchemy.sql.expression.BindParameter"><tt class="xref py py-class docutils literal"><span class="pre">BindParameter</span></tt></a> object.</p>
<p>This constructor is mirrored as a public API function; see <a class="reference internal" href="#sqlalchemy.sql.expression.bindparam" title="sqlalchemy.sql.expression.bindparam"><tt class="xref py py-func docutils literal"><span class="pre">bindparam()</span></tt></a> for a full usage and argument description.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.sql.expression.BindParameter.compare">
<tt class="descname">compare</tt><big>(</big><em>other</em>, <em>**kw</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.BindParameter.compare" title="Permalink to this definition">¶</a></dt>
<dd><p>Compare this <a class="reference internal" href="#sqlalchemy.sql.expression.BindParameter" title="sqlalchemy.sql.expression.BindParameter"><tt class="xref py py-class docutils literal"><span class="pre">BindParameter</span></tt></a> to the given
clause.</p>
</dd></dl>
<dl class="attribute">
<dt id="sqlalchemy.sql.expression.BindParameter.effective_value">
<tt class="descname">effective_value</tt><a class="headerlink" href="#sqlalchemy.sql.expression.BindParameter.effective_value" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the value of this bound parameter,
taking into account if the <tt class="docutils literal"><span class="pre">callable</span></tt> parameter
was set.</p>
<p>The <tt class="docutils literal"><span class="pre">callable</span></tt> value will be evaluated
and returned if present, else <tt class="docutils literal"><span class="pre">value</span></tt>.</p>
</dd></dl>
</dd></dl>
<dl class="class">
<dt id="sqlalchemy.sql.expression.Case">
<em class="property">class </em><tt class="descclassname">sqlalchemy.sql.expression.</tt><tt class="descname">Case</tt><big>(</big><em>whens</em>, <em>value=None</em>, <em>else_=None</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.Case" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference internal" href="#sqlalchemy.sql.expression.ColumnElement" title="sqlalchemy.sql.expression.ColumnElement"><tt class="xref py py-class docutils literal"><span class="pre">sqlalchemy.sql.expression.ColumnElement</span></tt></a></p>
<p>Represent a <tt class="docutils literal"><span class="pre">CASE</span></tt> expression.</p>
<p><a class="reference internal" href="#sqlalchemy.sql.expression.Case" title="sqlalchemy.sql.expression.Case"><tt class="xref py py-class docutils literal"><span class="pre">Case</span></tt></a> is produced using the <a class="reference internal" href="#sqlalchemy.sql.expression.case" title="sqlalchemy.sql.expression.case"><tt class="xref py py-func docutils literal"><span class="pre">case()</span></tt></a> factory function,
as in:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="kn">import</span> <span class="n">case</span>
<span class="n">stmt</span> <span class="o">=</span> <span class="n">select</span><span class="p">([</span><span class="n">users_table</span><span class="p">])</span><span class="o">.</span>\
<span class="n">where</span><span class="p">(</span>
<span class="n">case</span><span class="p">(</span>
<span class="p">[</span>
<span class="p">(</span><span class="n">users_table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">name</span> <span class="o">==</span> <span class="s">'wendy'</span><span class="p">,</span> <span class="s">'W'</span><span class="p">),</span>
<span class="p">(</span><span class="n">users_table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">name</span> <span class="o">==</span> <span class="s">'jack'</span><span class="p">,</span> <span class="s">'J'</span><span class="p">)</span>
<span class="p">],</span>
<span class="n">else_</span><span class="o">=</span><span class="s">'E'</span>
<span class="p">)</span>
<span class="p">)</span></pre></div>
</div>
<p>Details on <a class="reference internal" href="#sqlalchemy.sql.expression.Case" title="sqlalchemy.sql.expression.Case"><tt class="xref py py-class docutils literal"><span class="pre">Case</span></tt></a> usage is at <a class="reference internal" href="#sqlalchemy.sql.expression.case" title="sqlalchemy.sql.expression.case"><tt class="xref py py-func docutils literal"><span class="pre">case()</span></tt></a>.</p>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p class="last"><a class="reference internal" href="#sqlalchemy.sql.expression.case" title="sqlalchemy.sql.expression.case"><tt class="xref py py-func docutils literal"><span class="pre">case()</span></tt></a></p>
</div>
<dl class="method">
<dt id="sqlalchemy.sql.expression.Case.__init__">
<tt class="descname">__init__</tt><big>(</big><em>whens</em>, <em>value=None</em>, <em>else_=None</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.Case.__init__" title="Permalink to this definition">¶</a></dt>
<dd><p>Construct a new <a class="reference internal" href="#sqlalchemy.sql.expression.Case" title="sqlalchemy.sql.expression.Case"><tt class="xref py py-class docutils literal"><span class="pre">Case</span></tt></a> object.</p>
<p>This constructor is mirrored as a public API function; see <a class="reference internal" href="#sqlalchemy.sql.expression.case" title="sqlalchemy.sql.expression.case"><tt class="xref py py-func docutils literal"><span class="pre">case()</span></tt></a> for a full usage and argument description.</p>
</dd></dl>
</dd></dl>
<dl class="class">
<dt id="sqlalchemy.sql.expression.Cast">
<em class="property">class </em><tt class="descclassname">sqlalchemy.sql.expression.</tt><tt class="descname">Cast</tt><big>(</big><em>expression</em>, <em>type_</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.Cast" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference internal" href="#sqlalchemy.sql.expression.ColumnElement" title="sqlalchemy.sql.expression.ColumnElement"><tt class="xref py py-class docutils literal"><span class="pre">sqlalchemy.sql.expression.ColumnElement</span></tt></a></p>
<p>Represent a <tt class="docutils literal"><span class="pre">CAST</span></tt> expression.</p>
<p><a class="reference internal" href="#sqlalchemy.sql.expression.Cast" title="sqlalchemy.sql.expression.Cast"><tt class="xref py py-class docutils literal"><span class="pre">Cast</span></tt></a> is produced using the <a class="reference internal" href="#sqlalchemy.sql.expression.cast" title="sqlalchemy.sql.expression.cast"><tt class="xref py py-func docutils literal"><span class="pre">cast()</span></tt></a> factory function,
as in:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="kn">import</span> <span class="n">cast</span><span class="p">,</span> <span class="n">Numeric</span>
<span class="n">stmt</span> <span class="o">=</span> <span class="n">select</span><span class="p">([</span>
<span class="n">cast</span><span class="p">(</span><span class="n">product_table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">unit_price</span><span class="p">,</span> <span class="n">Numeric</span><span class="p">(</span><span class="mi">10</span><span class="p">,</span> <span class="mi">4</span><span class="p">))</span>
<span class="p">])</span></pre></div>
</div>
<p>Details on <a class="reference internal" href="#sqlalchemy.sql.expression.Cast" title="sqlalchemy.sql.expression.Cast"><tt class="xref py py-class docutils literal"><span class="pre">Cast</span></tt></a> usage is at <a class="reference internal" href="#sqlalchemy.sql.expression.cast" title="sqlalchemy.sql.expression.cast"><tt class="xref py py-func docutils literal"><span class="pre">cast()</span></tt></a>.</p>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p class="last"><a class="reference internal" href="#sqlalchemy.sql.expression.cast" title="sqlalchemy.sql.expression.cast"><tt class="xref py py-func docutils literal"><span class="pre">cast()</span></tt></a></p>
</div>
<dl class="method">
<dt id="sqlalchemy.sql.expression.Cast.__init__">
<tt class="descname">__init__</tt><big>(</big><em>expression</em>, <em>type_</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.Cast.__init__" title="Permalink to this definition">¶</a></dt>
<dd><p>Construct a new <a class="reference internal" href="#sqlalchemy.sql.expression.Cast" title="sqlalchemy.sql.expression.Cast"><tt class="xref py py-class docutils literal"><span class="pre">Cast</span></tt></a> object.</p>
<p>This constructor is mirrored as a public API function; see <a class="reference internal" href="#sqlalchemy.sql.expression.cast" title="sqlalchemy.sql.expression.cast"><tt class="xref py py-func docutils literal"><span class="pre">cast()</span></tt></a> for a full usage and argument description.</p>
</dd></dl>
</dd></dl>
<dl class="class">
<dt id="sqlalchemy.sql.expression.ClauseElement">
<em class="property">class </em><tt class="descclassname">sqlalchemy.sql.expression.</tt><tt class="descname">ClauseElement</tt><a class="headerlink" href="#sqlalchemy.sql.expression.ClauseElement" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <tt class="xref py py-class docutils literal"><span class="pre">sqlalchemy.sql.visitors.Visitable</span></tt></p>
<p>Base class for elements of a programmatically constructed SQL
expression.</p>
<dl class="method">
<dt id="sqlalchemy.sql.expression.ClauseElement.compare">
<tt class="descname">compare</tt><big>(</big><em>other</em>, <em>**kw</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.ClauseElement.compare" title="Permalink to this definition">¶</a></dt>
<dd><p>Compare this ClauseElement to the given ClauseElement.</p>
<p>Subclasses should override the default behavior, which is a
straight identity comparison.</p>
<p>**kw are arguments consumed by subclass compare() methods and
may be used to modify the criteria for comparison.
(see <a class="reference internal" href="#sqlalchemy.sql.expression.ColumnElement" title="sqlalchemy.sql.expression.ColumnElement"><tt class="xref py py-class docutils literal"><span class="pre">ColumnElement</span></tt></a>)</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.sql.expression.ClauseElement.compile">
<tt class="descname">compile</tt><big>(</big><em>bind=None</em>, <em>dialect=None</em>, <em>**kw</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.ClauseElement.compile" title="Permalink to this definition">¶</a></dt>
<dd><p>Compile this SQL expression.</p>
<p>The return value is a <a class="reference internal" href="internals.html#sqlalchemy.engine.interfaces.Compiled" title="sqlalchemy.engine.interfaces.Compiled"><tt class="xref py py-class docutils literal"><span class="pre">Compiled</span></tt></a> object.
Calling <tt class="docutils literal"><span class="pre">str()</span></tt> or <tt class="docutils literal"><span class="pre">unicode()</span></tt> on the returned value will yield a
string representation of the result. The
<a class="reference internal" href="internals.html#sqlalchemy.engine.interfaces.Compiled" title="sqlalchemy.engine.interfaces.Compiled"><tt class="xref py py-class docutils literal"><span class="pre">Compiled</span></tt></a> object also can return a
dictionary of bind parameter names and values
using the <tt class="docutils literal"><span class="pre">params</span></tt> accessor.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><span class="target" id="sqlalchemy.sql.expression.ClauseElement.compile.params.bind"></span><strong>bind</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.ClauseElement.compile.params.bind">¶</a> – An <tt class="docutils literal"><span class="pre">Engine</span></tt> or <tt class="docutils literal"><span class="pre">Connection</span></tt> from which a
<tt class="docutils literal"><span class="pre">Compiled</span></tt> will be acquired. This argument takes precedence over
this <a class="reference internal" href="#sqlalchemy.sql.expression.ClauseElement" title="sqlalchemy.sql.expression.ClauseElement"><tt class="xref py py-class docutils literal"><span class="pre">ClauseElement</span></tt></a>‘s bound engine, if any.</li>
<li><span class="target" id="sqlalchemy.sql.expression.ClauseElement.compile.params.column_keys"></span><strong>column_keys</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.ClauseElement.compile.params.column_keys">¶</a> – Used for INSERT and UPDATE statements, a list of
column names which should be present in the VALUES clause of the
compiled statement. If <tt class="docutils literal"><span class="pre">None</span></tt>, all columns from the target table
object are rendered.</li>
<li><span class="target" id="sqlalchemy.sql.expression.ClauseElement.compile.params.dialect"></span><strong>dialect</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.ClauseElement.compile.params.dialect">¶</a> – A <tt class="docutils literal"><span class="pre">Dialect</span></tt> instance from which a <tt class="docutils literal"><span class="pre">Compiled</span></tt>
will be acquired. This argument takes precedence over the <cite>bind</cite>
argument as well as this <a class="reference internal" href="#sqlalchemy.sql.expression.ClauseElement" title="sqlalchemy.sql.expression.ClauseElement"><tt class="xref py py-class docutils literal"><span class="pre">ClauseElement</span></tt></a>‘s bound engine,
if any.</li>
<li><span class="target" id="sqlalchemy.sql.expression.ClauseElement.compile.params.inline"></span><strong>inline</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.ClauseElement.compile.params.inline">¶</a> – Used for INSERT statements, for a dialect which does
not support inline retrieval of newly generated primary key
columns, will force the expression used to create the new primary
key value to be rendered inline within the INSERT statement’s
VALUES clause. This typically refers to Sequence execution but may
also refer to any server-side default generation function
associated with a primary key <cite>Column</cite>.</li>
<li><span class="target" id="sqlalchemy.sql.expression.ClauseElement.compile.params.compile_kwargs"></span><strong>compile_kwargs</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.ClauseElement.compile.params.compile_kwargs">¶</a> – <p>optional dictionary of additional parameters
that will be passed through to the compiler within all “visit”
methods. This allows any custom flag to be passed through to
a custom compilation construct, for example. It is also used
for the case of passing the <tt class="docutils literal"><span class="pre">literal_binds</span></tt> flag through:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">sqlalchemy.sql</span> <span class="kn">import</span> <span class="n">table</span><span class="p">,</span> <span class="n">column</span><span class="p">,</span> <span class="n">select</span>
<span class="n">t</span> <span class="o">=</span> <span class="n">table</span><span class="p">(</span><span class="s">'t'</span><span class="p">,</span> <span class="n">column</span><span class="p">(</span><span class="s">'x'</span><span class="p">))</span>
<span class="n">s</span> <span class="o">=</span> <span class="n">select</span><span class="p">([</span><span class="n">t</span><span class="p">])</span><span class="o">.</span><span class="n">where</span><span class="p">(</span><span class="n">t</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">x</span> <span class="o">==</span> <span class="mi">5</span><span class="p">)</span>
<span class="k">print</span> <span class="n">s</span><span class="o">.</span><span class="n">compile</span><span class="p">(</span><span class="n">compile_kwargs</span><span class="o">=</span><span class="p">{</span><span class="s">"literal_binds"</span><span class="p">:</span> <span class="bp">True</span><span class="p">})</span></pre></div>
</div>
<div class="versionadded">
<p><span>New in version 0.9.0.</span></p>
</div>
</li>
</ul>
</td>
</tr>
</tbody>
</table>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p class="last"><a class="reference internal" href="../faq.html#faq-sql-expression-string"><em>How do I render SQL expressions as strings, possibly with bound parameters inlined?</em></a></p>
</div>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.sql.expression.ClauseElement.get_children">
<tt class="descname">get_children</tt><big>(</big><em>**kwargs</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.ClauseElement.get_children" title="Permalink to this definition">¶</a></dt>
<dd><p>Return immediate child elements of this <a class="reference internal" href="#sqlalchemy.sql.expression.ClauseElement" title="sqlalchemy.sql.expression.ClauseElement"><tt class="xref py py-class docutils literal"><span class="pre">ClauseElement</span></tt></a>.</p>
<p>This is used for visit traversal.</p>
<p>**kwargs may contain flags that change the collection that is
returned, for example to return a subset of items in order to
cut down on larger traversals, or to return child items from a
different context (such as schema-level collections instead of
clause-level).</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.sql.expression.ClauseElement.params">
<tt class="descname">params</tt><big>(</big><em>*optionaldict</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.ClauseElement.params" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a copy with <a class="reference internal" href="#sqlalchemy.sql.expression.bindparam" title="sqlalchemy.sql.expression.bindparam"><tt class="xref py py-func docutils literal"><span class="pre">bindparam()</span></tt></a> elements replaced.</p>
<p>Returns a copy of this ClauseElement with <a class="reference internal" href="#sqlalchemy.sql.expression.bindparam" title="sqlalchemy.sql.expression.bindparam"><tt class="xref py py-func docutils literal"><span class="pre">bindparam()</span></tt></a>
elements replaced with values taken from the given dictionary:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">clause</span> <span class="o">=</span> <span class="n">column</span><span class="p">(</span><span class="s">'x'</span><span class="p">)</span> <span class="o">+</span> <span class="n">bindparam</span><span class="p">(</span><span class="s">'foo'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="k">print</span> <span class="n">clause</span><span class="o">.</span><span class="n">compile</span><span class="p">()</span><span class="o">.</span><span class="n">params</span>
<span class="go">{'foo':None}</span>
<span class="gp">>>> </span><span class="k">print</span> <span class="n">clause</span><span class="o">.</span><span class="n">params</span><span class="p">({</span><span class="s">'foo'</span><span class="p">:</span><span class="mi">7</span><span class="p">})</span><span class="o">.</span><span class="n">compile</span><span class="p">()</span><span class="o">.</span><span class="n">params</span>
<span class="go">{'foo':7}</span></pre></div>
</div>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.sql.expression.ClauseElement.self_group">
<tt class="descname">self_group</tt><big>(</big><em>against=None</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.ClauseElement.self_group" title="Permalink to this definition">¶</a></dt>
<dd><p>Apply a ‘grouping’ to this <a class="reference internal" href="#sqlalchemy.sql.expression.ClauseElement" title="sqlalchemy.sql.expression.ClauseElement"><tt class="xref py py-class docutils literal"><span class="pre">ClauseElement</span></tt></a>.</p>
<p>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 <a class="reference internal" href="selectable.html#sqlalchemy.sql.expression.select" title="sqlalchemy.sql.expression.select"><tt class="xref py py-func docutils literal"><span class="pre">select()</span></tt></a> constructs when placed into
the FROM clause of another <a class="reference internal" href="selectable.html#sqlalchemy.sql.expression.select" title="sqlalchemy.sql.expression.select"><tt class="xref py py-func docutils literal"><span class="pre">select()</span></tt></a>. (Note that
subqueries should be normally created using the
<a class="reference internal" href="selectable.html#sqlalchemy.sql.expression.Select.alias" title="sqlalchemy.sql.expression.Select.alias"><tt class="xref py py-meth docutils literal"><span class="pre">Select.alias()</span></tt></a> method, as many platforms require
nested SELECT statements to be named).</p>
<p>As expressions are composed together, the application of
<a class="reference internal" href="#sqlalchemy.sql.expression.ClauseElement.self_group" title="sqlalchemy.sql.expression.ClauseElement.self_group"><tt class="xref py py-meth docutils literal"><span class="pre">self_group()</span></tt></a> is automatic - end-user code should never
need to use this method directly. Note that SQLAlchemy’s
clause constructs take operator precedence into account -
so parenthesis might not be needed, for example, in
an expression like <tt class="docutils literal"><span class="pre">x</span> <span class="pre">OR</span> <span class="pre">(y</span> <span class="pre">AND</span> <span class="pre">z)</span></tt> - AND takes precedence
over OR.</p>
<p>The base <a class="reference internal" href="#sqlalchemy.sql.expression.ClauseElement.self_group" title="sqlalchemy.sql.expression.ClauseElement.self_group"><tt class="xref py py-meth docutils literal"><span class="pre">self_group()</span></tt></a> method of <a class="reference internal" href="#sqlalchemy.sql.expression.ClauseElement" title="sqlalchemy.sql.expression.ClauseElement"><tt class="xref py py-class docutils literal"><span class="pre">ClauseElement</span></tt></a>
just returns self.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.sql.expression.ClauseElement.unique_params">
<tt class="descname">unique_params</tt><big>(</big><em>*optionaldict</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.ClauseElement.unique_params" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a copy with <a class="reference internal" href="#sqlalchemy.sql.expression.bindparam" title="sqlalchemy.sql.expression.bindparam"><tt class="xref py py-func docutils literal"><span class="pre">bindparam()</span></tt></a> elements replaced.</p>
<p>Same functionality as <tt class="docutils literal"><span class="pre">params()</span></tt>, except adds <cite>unique=True</cite>
to affected bind parameters so that multiple statements can be
used.</p>
</dd></dl>
</dd></dl>
<dl class="class">
<dt id="sqlalchemy.sql.expression.ClauseList">
<em class="property">class </em><tt class="descclassname">sqlalchemy.sql.expression.</tt><tt class="descname">ClauseList</tt><big>(</big><em>*clauses</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.ClauseList" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference internal" href="#sqlalchemy.sql.expression.ClauseElement" title="sqlalchemy.sql.expression.ClauseElement"><tt class="xref py py-class docutils literal"><span class="pre">sqlalchemy.sql.expression.ClauseElement</span></tt></a></p>
<p>Describe a list of clauses, separated by an operator.</p>
<p>By default, is comma-separated, such as a column listing.</p>
<dl class="method">
<dt id="sqlalchemy.sql.expression.ClauseList.compare">
<tt class="descname">compare</tt><big>(</big><em>other</em>, <em>**kw</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.ClauseList.compare" title="Permalink to this definition">¶</a></dt>
<dd><p>Compare this <a class="reference internal" href="#sqlalchemy.sql.expression.ClauseList" title="sqlalchemy.sql.expression.ClauseList"><tt class="xref py py-class docutils literal"><span class="pre">ClauseList</span></tt></a> to the given <a class="reference internal" href="#sqlalchemy.sql.expression.ClauseList" title="sqlalchemy.sql.expression.ClauseList"><tt class="xref py py-class docutils literal"><span class="pre">ClauseList</span></tt></a>,
including a comparison of all the clause items.</p>
</dd></dl>
</dd></dl>
<dl class="class">
<dt id="sqlalchemy.sql.expression.ColumnClause">
<em class="property">class </em><tt class="descclassname">sqlalchemy.sql.expression.</tt><tt class="descname">ColumnClause</tt><big>(</big><em>text</em>, <em>type_=None</em>, <em>is_literal=False</em>, <em>_selectable=None</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.ColumnClause" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <tt class="xref py py-class docutils literal"><span class="pre">sqlalchemy.sql.expression.Immutable</span></tt>, <a class="reference internal" href="#sqlalchemy.sql.expression.ColumnElement" title="sqlalchemy.sql.expression.ColumnElement"><tt class="xref py py-class docutils literal"><span class="pre">sqlalchemy.sql.expression.ColumnElement</span></tt></a></p>
<p>Represents a column expression from any textual string.</p>
<p>The <a class="reference internal" href="#sqlalchemy.sql.expression.ColumnClause" title="sqlalchemy.sql.expression.ColumnClause"><tt class="xref py py-class docutils literal"><span class="pre">ColumnClause</span></tt></a>, a lightweight analogue to the
<a class="reference internal" href="metadata.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal"><span class="pre">Column</span></tt></a> class, is typically invoked using the
<a class="reference internal" href="#sqlalchemy.sql.expression.column" title="sqlalchemy.sql.expression.column"><tt class="xref py py-func docutils literal"><span class="pre">column()</span></tt></a> function, as in:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">sqlalchemy.sql</span> <span class="kn">import</span> <span class="n">column</span>
<span class="nb">id</span><span class="p">,</span> <span class="n">name</span> <span class="o">=</span> <span class="n">column</span><span class="p">(</span><span class="s">"id"</span><span class="p">),</span> <span class="n">column</span><span class="p">(</span><span class="s">"name"</span><span class="p">)</span>
<span class="n">stmt</span> <span class="o">=</span> <span class="n">select</span><span class="p">([</span><span class="nb">id</span><span class="p">,</span> <span class="n">name</span><span class="p">])</span><span class="o">.</span><span class="n">select_from</span><span class="p">(</span><span class="s">"user"</span><span class="p">)</span></pre></div>
</div>
<p>The above statement would produce SQL like:</p>
<div class="highlight-python"><pre>SELECT id, name FROM user</pre>
</div>
<p><a class="reference internal" href="#sqlalchemy.sql.expression.ColumnClause" title="sqlalchemy.sql.expression.ColumnClause"><tt class="xref py py-class docutils literal"><span class="pre">ColumnClause</span></tt></a> is the immediate superclass of the schema-specific
<a class="reference internal" href="metadata.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal"><span class="pre">Column</span></tt></a> object. While the <a class="reference internal" href="metadata.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal"><span class="pre">Column</span></tt></a> class has all the
same capabilities as <a class="reference internal" href="#sqlalchemy.sql.expression.ColumnClause" title="sqlalchemy.sql.expression.ColumnClause"><tt class="xref py py-class docutils literal"><span class="pre">ColumnClause</span></tt></a>, the <a class="reference internal" href="#sqlalchemy.sql.expression.ColumnClause" title="sqlalchemy.sql.expression.ColumnClause"><tt class="xref py py-class docutils literal"><span class="pre">ColumnClause</span></tt></a>
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 <a class="reference internal" href="metadata.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal"><span class="pre">Column</span></tt></a> does, so in that sense is a “lightweight”
version of <a class="reference internal" href="metadata.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal"><span class="pre">Column</span></tt></a>.</p>
<p>Full details on <a class="reference internal" href="#sqlalchemy.sql.expression.ColumnClause" title="sqlalchemy.sql.expression.ColumnClause"><tt class="xref py py-class docutils literal"><span class="pre">ColumnClause</span></tt></a> usage is at <a class="reference internal" href="#sqlalchemy.sql.expression.column" title="sqlalchemy.sql.expression.column"><tt class="xref py py-func docutils literal"><span class="pre">column()</span></tt></a>.</p>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p><a class="reference internal" href="#sqlalchemy.sql.expression.column" title="sqlalchemy.sql.expression.column"><tt class="xref py py-func docutils literal"><span class="pre">column()</span></tt></a></p>
<p class="last"><a class="reference internal" href="metadata.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal"><span class="pre">Column</span></tt></a></p>
</div>
<dl class="method">
<dt id="sqlalchemy.sql.expression.ColumnClause.__init__">
<tt class="descname">__init__</tt><big>(</big><em>text</em>, <em>type_=None</em>, <em>is_literal=False</em>, <em>_selectable=None</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.ColumnClause.__init__" title="Permalink to this definition">¶</a></dt>
<dd><p>Construct a new <a class="reference internal" href="#sqlalchemy.sql.expression.ColumnClause" title="sqlalchemy.sql.expression.ColumnClause"><tt class="xref py py-class docutils literal"><span class="pre">ColumnClause</span></tt></a> object.</p>
<p>This constructor is mirrored as a public API function; see <a class="reference internal" href="#sqlalchemy.sql.expression.column" title="sqlalchemy.sql.expression.column"><tt class="xref py py-func docutils literal"><span class="pre">column()</span></tt></a> for a full usage and argument description.</p>
</dd></dl>
</dd></dl>
<dl class="class">
<dt id="sqlalchemy.sql.expression.ColumnCollection">
<em class="property">class </em><tt class="descclassname">sqlalchemy.sql.expression.</tt><tt class="descname">ColumnCollection</tt><big>(</big><em>*columns</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.ColumnCollection" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <tt class="xref py py-class docutils literal"><span class="pre">sqlalchemy.util._collections.OrderedProperties</span></tt></p>
<p>An ordered dictionary that stores a list of ColumnElement
instances.</p>
<p>Overrides the <tt class="docutils literal"><span class="pre">__eq__()</span></tt> method to produce SQL clauses between
sets of correlated columns.</p>
<dl class="method">
<dt id="sqlalchemy.sql.expression.ColumnCollection.add">
<tt class="descname">add</tt><big>(</big><em>column</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.ColumnCollection.add" title="Permalink to this definition">¶</a></dt>
<dd><p>Add a column to this collection.</p>
<p>The key attribute of the column will be used as the hash key
for this dictionary.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.sql.expression.ColumnCollection.replace">
<tt class="descname">replace</tt><big>(</big><em>column</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.ColumnCollection.replace" title="Permalink to this definition">¶</a></dt>
<dd><p>add the given column to this collection, removing unaliased
versions of this column as well as existing columns with the
same key.</p>
<blockquote>
<div><p>e.g.:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">t</span> <span class="o">=</span> <span class="n">Table</span><span class="p">(</span><span class="s">'sometable'</span><span class="p">,</span> <span class="n">metadata</span><span class="p">,</span> <span class="n">Column</span><span class="p">(</span><span class="s">'col1'</span><span class="p">,</span> <span class="n">Integer</span><span class="p">))</span>
<span class="n">t</span><span class="o">.</span><span class="n">columns</span><span class="o">.</span><span class="n">replace</span><span class="p">(</span><span class="n">Column</span><span class="p">(</span><span class="s">'col1'</span><span class="p">,</span> <span class="n">Integer</span><span class="p">,</span> <span class="n">key</span><span class="o">=</span><span class="s">'columnone'</span><span class="p">))</span></pre></div>
</div>
<p>will remove the original ‘col1’ from the collection, and add
the new column under the name ‘columnname’.</p>
</div></blockquote>
<p>Used by schema.Column to override columns during table reflection.</p>
</dd></dl>
</dd></dl>
<dl class="class">
<dt id="sqlalchemy.sql.expression.ColumnElement">
<em class="property">class </em><tt class="descclassname">sqlalchemy.sql.expression.</tt><tt class="descname">ColumnElement</tt><a class="headerlink" href="#sqlalchemy.sql.expression.ColumnElement" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference internal" href="#sqlalchemy.sql.operators.ColumnOperators" title="sqlalchemy.sql.operators.ColumnOperators"><tt class="xref py py-class docutils literal"><span class="pre">sqlalchemy.sql.operators.ColumnOperators</span></tt></a>, <a class="reference internal" href="#sqlalchemy.sql.expression.ClauseElement" title="sqlalchemy.sql.expression.ClauseElement"><tt class="xref py py-class docutils literal"><span class="pre">sqlalchemy.sql.expression.ClauseElement</span></tt></a></p>
<p>Represent a column-oriented SQL expression suitable for usage in the
“columns” clause, WHERE clause etc. of a statement.</p>
<p>While the most familiar kind of <a class="reference internal" href="#sqlalchemy.sql.expression.ColumnElement" title="sqlalchemy.sql.expression.ColumnElement"><tt class="xref py py-class docutils literal"><span class="pre">ColumnElement</span></tt></a> is the
<a class="reference internal" href="metadata.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal"><span class="pre">Column</span></tt></a> object, <a class="reference internal" href="#sqlalchemy.sql.expression.ColumnElement" title="sqlalchemy.sql.expression.ColumnElement"><tt class="xref py py-class docutils literal"><span class="pre">ColumnElement</span></tt></a> 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 <tt class="docutils literal"><span class="pre">NULL</span></tt>, etc.
<a class="reference internal" href="#sqlalchemy.sql.expression.ColumnElement" title="sqlalchemy.sql.expression.ColumnElement"><tt class="xref py py-class docutils literal"><span class="pre">ColumnElement</span></tt></a> is the ultimate base class for all such elements.</p>
<p>A wide variety of SQLAlchemy Core functions work at the SQL expression
level, and are intended to accept instances of <a class="reference internal" href="#sqlalchemy.sql.expression.ColumnElement" title="sqlalchemy.sql.expression.ColumnElement"><tt class="xref py py-class docutils literal"><span class="pre">ColumnElement</span></tt></a> 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
<a class="reference internal" href="#sqlalchemy.sql.expression.ColumnElement" title="sqlalchemy.sql.expression.ColumnElement"><tt class="xref py py-class docutils literal"><span class="pre">ColumnElement</span></tt></a> object, or a value which can be <strong>coerced</strong> into
one. The coercion rules followed by most, but not all, SQLAlchemy Core
functions with regards to SQL expressions are as follows:</p>
<blockquote>
<div><ul class="simple">
<li>a literal Python value, such as a string, integer or floating
point value, boolean, datetime, <tt class="docutils literal"><span class="pre">Decimal</span></tt> object, or virtually
any other Python object, will be coerced into a “literal bound
value”. This generally means that a <a class="reference internal" href="#sqlalchemy.sql.expression.bindparam" title="sqlalchemy.sql.expression.bindparam"><tt class="xref py py-func docutils literal"><span class="pre">bindparam()</span></tt></a> will be
produced featuring the given value embedded into the construct; the
resulting <a class="reference internal" href="#sqlalchemy.sql.expression.BindParameter" title="sqlalchemy.sql.expression.BindParameter"><tt class="xref py py-class docutils literal"><span class="pre">BindParameter</span></tt></a> object is an instance of
<a class="reference internal" href="#sqlalchemy.sql.expression.ColumnElement" title="sqlalchemy.sql.expression.ColumnElement"><tt class="xref py py-class docutils literal"><span class="pre">ColumnElement</span></tt></a>. The Python value will ultimately be sent
to the DBAPI at execution time as a paramterized argument to the
<tt class="docutils literal"><span class="pre">execute()</span></tt> or <tt class="docutils literal"><span class="pre">executemany()</span></tt> methods, after SQLAlchemy
type-specific converters (e.g. those provided by any associated
<a class="reference internal" href="types.html#sqlalchemy.types.TypeEngine" title="sqlalchemy.types.TypeEngine"><tt class="xref py py-class docutils literal"><span class="pre">TypeEngine</span></tt></a> objects) are applied to the value.</li>
<li>any special object value, typically ORM-level constructs, which
feature a method called <tt class="docutils literal"><span class="pre">__clause_element__()</span></tt>. 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 <a class="reference internal" href="#sqlalchemy.sql.expression.ColumnElement" title="sqlalchemy.sql.expression.ColumnElement"><tt class="xref py py-class docutils literal"><span class="pre">ColumnElement</span></tt></a> expression. The
<tt class="docutils literal"><span class="pre">__clause_element__()</span></tt> method, if present, should return a
<a class="reference internal" href="#sqlalchemy.sql.expression.ColumnElement" title="sqlalchemy.sql.expression.ColumnElement"><tt class="xref py py-class docutils literal"><span class="pre">ColumnElement</span></tt></a> instance. The primary use of
<tt class="docutils literal"><span class="pre">__clause_element__()</span></tt> within SQLAlchemy is that of class-bound
attributes on ORM-mapped classes; a <tt class="docutils literal"><span class="pre">User</span></tt> class which contains a
mapped attribute named <tt class="docutils literal"><span class="pre">.name</span></tt> will have a method
<tt class="docutils literal"><span class="pre">User.name.__clause_element__()</span></tt> which when invoked returns the
<a class="reference internal" href="metadata.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal"><span class="pre">Column</span></tt></a> called <tt class="docutils literal"><span class="pre">name</span></tt> associated with the mapped table.</li>
<li>The Python <tt class="docutils literal"><span class="pre">None</span></tt> value is typically interpreted as <tt class="docutils literal"><span class="pre">NULL</span></tt>,
which in SQLAlchemy Core produces an instance of <a class="reference internal" href="#sqlalchemy.sql.expression.null" title="sqlalchemy.sql.expression.null"><tt class="xref py py-func docutils literal"><span class="pre">null()</span></tt></a>.</li>
</ul>
</div></blockquote>
<p>A <a class="reference internal" href="#sqlalchemy.sql.expression.ColumnElement" title="sqlalchemy.sql.expression.ColumnElement"><tt class="xref py py-class docutils literal"><span class="pre">ColumnElement</span></tt></a> provides the ability to generate new
<a class="reference internal" href="#sqlalchemy.sql.expression.ColumnElement" title="sqlalchemy.sql.expression.ColumnElement"><tt class="xref py py-class docutils literal"><span class="pre">ColumnElement</span></tt></a>
objects using Python expressions. This means that Python operators
such as <tt class="docutils literal"><span class="pre">==</span></tt>, <tt class="docutils literal"><span class="pre">!=</span></tt> and <tt class="docutils literal"><span class="pre"><</span></tt> are overloaded to mimic SQL operations,
and allow the instantiation of further <a class="reference internal" href="#sqlalchemy.sql.expression.ColumnElement" title="sqlalchemy.sql.expression.ColumnElement"><tt class="xref py py-class docutils literal"><span class="pre">ColumnElement</span></tt></a> instances
which are composed from other, more fundamental <a class="reference internal" href="#sqlalchemy.sql.expression.ColumnElement" title="sqlalchemy.sql.expression.ColumnElement"><tt class="xref py py-class docutils literal"><span class="pre">ColumnElement</span></tt></a>
objects. For example, two <a class="reference internal" href="#sqlalchemy.sql.expression.ColumnClause" title="sqlalchemy.sql.expression.ColumnClause"><tt class="xref py py-class docutils literal"><span class="pre">ColumnClause</span></tt></a> objects can be added
together with the addition operator <tt class="docutils literal"><span class="pre">+</span></tt> to produce
a <a class="reference internal" href="#sqlalchemy.sql.expression.BinaryExpression" title="sqlalchemy.sql.expression.BinaryExpression"><tt class="xref py py-class docutils literal"><span class="pre">BinaryExpression</span></tt></a>.
Both <a class="reference internal" href="#sqlalchemy.sql.expression.ColumnClause" title="sqlalchemy.sql.expression.ColumnClause"><tt class="xref py py-class docutils literal"><span class="pre">ColumnClause</span></tt></a> and <a class="reference internal" href="#sqlalchemy.sql.expression.BinaryExpression" title="sqlalchemy.sql.expression.BinaryExpression"><tt class="xref py py-class docutils literal"><span class="pre">BinaryExpression</span></tt></a> are subclasses
of <a class="reference internal" href="#sqlalchemy.sql.expression.ColumnElement" title="sqlalchemy.sql.expression.ColumnElement"><tt class="xref py py-class docutils literal"><span class="pre">ColumnElement</span></tt></a>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">sqlalchemy.sql</span> <span class="kn">import</span> <span class="n">column</span>
<span class="gp">>>> </span><span class="n">column</span><span class="p">(</span><span class="s">'a'</span><span class="p">)</span> <span class="o">+</span> <span class="n">column</span><span class="p">(</span><span class="s">'b'</span><span class="p">)</span>
<span class="go"><sqlalchemy.sql.expression.BinaryExpression object at 0x101029dd0></span>
<span class="gp">>>> </span><span class="k">print</span> <span class="n">column</span><span class="p">(</span><span class="s">'a'</span><span class="p">)</span> <span class="o">+</span> <span class="n">column</span><span class="p">(</span><span class="s">'b'</span><span class="p">)</span>
<span class="go">a + b</span></pre></div>
</div>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p><a class="reference internal" href="metadata.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal"><span class="pre">Column</span></tt></a></p>
<p class="last"><a class="reference internal" href="#sqlalchemy.sql.expression.column" title="sqlalchemy.sql.expression.column"><tt class="xref py py-func docutils literal"><span class="pre">expression.column()</span></tt></a></p>
</div>
<dl class="method">
<dt id="sqlalchemy.sql.expression.ColumnElement.__eq__">
<tt class="descname">__eq__</tt><big>(</big><em>other</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.ColumnElement.__eq__" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <a class="reference internal" href="#sqlalchemy.sql.operators.ColumnOperators.__eq__" title="sqlalchemy.sql.operators.ColumnOperators.__eq__"><tt class="xref py py-meth docutils literal"><span class="pre">__eq__()</span></tt></a> <em>method of</em> <a class="reference internal" href="#sqlalchemy.sql.operators.ColumnOperators" title="sqlalchemy.sql.operators.ColumnOperators"><tt class="xref py py-class docutils literal"><span class="pre">ColumnOperators</span></tt></a></div>
<p>Implement the <tt class="docutils literal"><span class="pre">==</span></tt> operator.</p>
<p>In a column context, produces the clause <tt class="docutils literal"><span class="pre">a</span> <span class="pre">=</span> <span class="pre">b</span></tt>.
If the target is <tt class="docutils literal"><span class="pre">None</span></tt>, produces <tt class="docutils literal"><span class="pre">a</span> <span class="pre">IS</span> <span class="pre">NULL</span></tt>.</p>
</dd></dl>
<dl class="attribute">
<dt id="sqlalchemy.sql.expression.ColumnElement.__init__">
<tt class="descname">__init__</tt><a class="headerlink" href="#sqlalchemy.sql.expression.ColumnElement.__init__" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <tt class="xref py py-attr docutils literal"><span class="pre">__init__</span></tt> <em>attribute of</em> <tt class="xref py py-class docutils literal"><span class="pre">object</span></tt></div>
<p>x.__init__(...) initializes x; see help(type(x)) for signature</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.sql.expression.ColumnElement.__le__">
<tt class="descname">__le__</tt><big>(</big><em>other</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.ColumnElement.__le__" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <a class="reference internal" href="#sqlalchemy.sql.operators.ColumnOperators.__le__" title="sqlalchemy.sql.operators.ColumnOperators.__le__"><tt class="xref py py-meth docutils literal"><span class="pre">__le__()</span></tt></a> <em>method of</em> <a class="reference internal" href="#sqlalchemy.sql.operators.ColumnOperators" title="sqlalchemy.sql.operators.ColumnOperators"><tt class="xref py py-class docutils literal"><span class="pre">ColumnOperators</span></tt></a></div>
<p>Implement the <tt class="docutils literal"><span class="pre"><=</span></tt> operator.</p>
<p>In a column context, produces the clause <tt class="docutils literal"><span class="pre">a</span> <span class="pre"><=</span> <span class="pre">b</span></tt>.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.sql.expression.ColumnElement.__lt__">
<tt class="descname">__lt__</tt><big>(</big><em>other</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.ColumnElement.__lt__" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <a class="reference internal" href="#sqlalchemy.sql.operators.ColumnOperators.__lt__" title="sqlalchemy.sql.operators.ColumnOperators.__lt__"><tt class="xref py py-meth docutils literal"><span class="pre">__lt__()</span></tt></a> <em>method of</em> <a class="reference internal" href="#sqlalchemy.sql.operators.ColumnOperators" title="sqlalchemy.sql.operators.ColumnOperators"><tt class="xref py py-class docutils literal"><span class="pre">ColumnOperators</span></tt></a></div>
<p>Implement the <tt class="docutils literal"><span class="pre"><</span></tt> operator.</p>
<p>In a column context, produces the clause <tt class="docutils literal"><span class="pre">a</span> <span class="pre"><</span> <span class="pre">b</span></tt>.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.sql.expression.ColumnElement.__ne__">
<tt class="descname">__ne__</tt><big>(</big><em>other</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.ColumnElement.__ne__" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <a class="reference internal" href="#sqlalchemy.sql.operators.ColumnOperators.__ne__" title="sqlalchemy.sql.operators.ColumnOperators.__ne__"><tt class="xref py py-meth docutils literal"><span class="pre">__ne__()</span></tt></a> <em>method of</em> <a class="reference internal" href="#sqlalchemy.sql.operators.ColumnOperators" title="sqlalchemy.sql.operators.ColumnOperators"><tt class="xref py py-class docutils literal"><span class="pre">ColumnOperators</span></tt></a></div>
<p>Implement the <tt class="docutils literal"><span class="pre">!=</span></tt> operator.</p>
<p>In a column context, produces the clause <tt class="docutils literal"><span class="pre">a</span> <span class="pre">!=</span> <span class="pre">b</span></tt>.
If the target is <tt class="docutils literal"><span class="pre">None</span></tt>, produces <tt class="docutils literal"><span class="pre">a</span> <span class="pre">IS</span> <span class="pre">NOT</span> <span class="pre">NULL</span></tt>.</p>
</dd></dl>
<dl class="attribute">
<dt id="sqlalchemy.sql.expression.ColumnElement.anon_label">
<tt class="descname">anon_label</tt><a class="headerlink" href="#sqlalchemy.sql.expression.ColumnElement.anon_label" title="Permalink to this definition">¶</a></dt>
<dd><p>provides a constant ‘anonymous label’ for this ColumnElement.</p>
<p>This is a label() expression which will be named at compile time.
The same label() is returned each time anon_label is called so
that expressions can reference anon_label multiple times, producing
the same label name at compile time.</p>
<p>the compiler uses this function automatically at compile time
for expressions that are known to be ‘unnamed’ like binary
expressions and function calls.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.sql.expression.ColumnElement.asc">
<tt class="descname">asc</tt><big>(</big><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.ColumnElement.asc" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <a class="reference internal" href="#sqlalchemy.sql.operators.ColumnOperators.asc" title="sqlalchemy.sql.operators.ColumnOperators.asc"><tt class="xref py py-meth docutils literal"><span class="pre">asc()</span></tt></a> <em>method of</em> <a class="reference internal" href="#sqlalchemy.sql.operators.ColumnOperators" title="sqlalchemy.sql.operators.ColumnOperators"><tt class="xref py py-class docutils literal"><span class="pre">ColumnOperators</span></tt></a></div>
<p>Produce a <a class="reference internal" href="#sqlalchemy.sql.expression.asc" title="sqlalchemy.sql.expression.asc"><tt class="xref py py-func docutils literal"><span class="pre">asc()</span></tt></a> clause against the
parent object.</p>
</dd></dl>
<dl class="attribute">
<dt id="sqlalchemy.sql.expression.ColumnElement.base_columns">
<tt class="descname">base_columns</tt><a class="headerlink" href="#sqlalchemy.sql.expression.ColumnElement.base_columns" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<dl class="method">
<dt id="sqlalchemy.sql.expression.ColumnElement.between">
<tt class="descname">between</tt><big>(</big><em>cleft</em>, <em>cright</em>, <em>symmetric=False</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.ColumnElement.between" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <a class="reference internal" href="#sqlalchemy.sql.operators.ColumnOperators.between" title="sqlalchemy.sql.operators.ColumnOperators.between"><tt class="xref py py-meth docutils literal"><span class="pre">between()</span></tt></a> <em>method of</em> <a class="reference internal" href="#sqlalchemy.sql.operators.ColumnOperators" title="sqlalchemy.sql.operators.ColumnOperators"><tt class="xref py py-class docutils literal"><span class="pre">ColumnOperators</span></tt></a></div>
<p>Produce a <a class="reference internal" href="#sqlalchemy.sql.expression.between" title="sqlalchemy.sql.expression.between"><tt class="xref py py-func docutils literal"><span class="pre">between()</span></tt></a> clause against
the parent object, given the lower and upper range.</p>
</dd></dl>
<dl class="attribute">
<dt id="sqlalchemy.sql.expression.ColumnElement.bind">
<tt class="descname">bind</tt><em class="property"> = None</em><a class="headerlink" href="#sqlalchemy.sql.expression.ColumnElement.bind" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<dl class="method">
<dt id="sqlalchemy.sql.expression.ColumnElement.collate">
<tt class="descname">collate</tt><big>(</big><em>collation</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.ColumnElement.collate" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <a class="reference internal" href="#sqlalchemy.sql.operators.ColumnOperators.collate" title="sqlalchemy.sql.operators.ColumnOperators.collate"><tt class="xref py py-meth docutils literal"><span class="pre">collate()</span></tt></a> <em>method of</em> <a class="reference internal" href="#sqlalchemy.sql.operators.ColumnOperators" title="sqlalchemy.sql.operators.ColumnOperators"><tt class="xref py py-class docutils literal"><span class="pre">ColumnOperators</span></tt></a></div>
<p>Produce a <a class="reference internal" href="#sqlalchemy.sql.expression.collate" title="sqlalchemy.sql.expression.collate"><tt class="xref py py-func docutils literal"><span class="pre">collate()</span></tt></a> clause against
the parent object, given the collation string.</p>
</dd></dl>
<dl class="attribute">
<dt id="sqlalchemy.sql.expression.ColumnElement.comparator">
<tt class="descname">comparator</tt><a class="headerlink" href="#sqlalchemy.sql.expression.ColumnElement.comparator" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<dl class="method">
<dt id="sqlalchemy.sql.expression.ColumnElement.compare">
<tt class="descname">compare</tt><big>(</big><em>other</em>, <em>use_proxies=False</em>, <em>equivalents=None</em>, <em>**kw</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.ColumnElement.compare" title="Permalink to this definition">¶</a></dt>
<dd><p>Compare this ColumnElement to another.</p>
<p>Special arguments understood:</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><span class="target" id="sqlalchemy.sql.expression.ColumnElement.compare.params.use_proxies"></span><strong>use_proxies</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.ColumnElement.compare.params.use_proxies">¶</a> – when True, consider two columns that
share a common base column as equivalent (i.e. shares_lineage())</li>
<li><span class="target" id="sqlalchemy.sql.expression.ColumnElement.compare.params.equivalents"></span><strong>equivalents</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.ColumnElement.compare.params.equivalents">¶</a> – a dictionary of columns as keys mapped to sets
of columns. If the given “other” column is present in this
dictionary, if any of the columns in the corresponding set() pass
the comparison test, the result is True. This is used to expand the
comparison to other columns that may be known to be equivalent to
this one via foreign key or other criterion.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.sql.expression.ColumnElement.compile">
<tt class="descname">compile</tt><big>(</big><em>bind=None</em>, <em>dialect=None</em>, <em>**kw</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.ColumnElement.compile" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <a class="reference internal" href="#sqlalchemy.sql.expression.ClauseElement.compile" title="sqlalchemy.sql.expression.ClauseElement.compile"><tt class="xref py py-meth docutils literal"><span class="pre">compile()</span></tt></a> <em>method of</em> <a class="reference internal" href="#sqlalchemy.sql.expression.ClauseElement" title="sqlalchemy.sql.expression.ClauseElement"><tt class="xref py py-class docutils literal"><span class="pre">ClauseElement</span></tt></a></div>
<p>Compile this SQL expression.</p>
<p>The return value is a <a class="reference internal" href="internals.html#sqlalchemy.engine.interfaces.Compiled" title="sqlalchemy.engine.interfaces.Compiled"><tt class="xref py py-class docutils literal"><span class="pre">Compiled</span></tt></a> object.
Calling <tt class="docutils literal"><span class="pre">str()</span></tt> or <tt class="docutils literal"><span class="pre">unicode()</span></tt> on the returned value will yield a
string representation of the result. The
<a class="reference internal" href="internals.html#sqlalchemy.engine.interfaces.Compiled" title="sqlalchemy.engine.interfaces.Compiled"><tt class="xref py py-class docutils literal"><span class="pre">Compiled</span></tt></a> object also can return a
dictionary of bind parameter names and values
using the <tt class="docutils literal"><span class="pre">params</span></tt> accessor.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><span class="target" id="sqlalchemy.sql.expression.ColumnElement.compile.params.bind"></span><strong>bind</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.ColumnElement.compile.params.bind">¶</a> – An <tt class="docutils literal"><span class="pre">Engine</span></tt> or <tt class="docutils literal"><span class="pre">Connection</span></tt> from which a
<tt class="docutils literal"><span class="pre">Compiled</span></tt> will be acquired. This argument takes precedence over
this <a class="reference internal" href="#sqlalchemy.sql.expression.ClauseElement" title="sqlalchemy.sql.expression.ClauseElement"><tt class="xref py py-class docutils literal"><span class="pre">ClauseElement</span></tt></a>‘s bound engine, if any.</li>
<li><span class="target" id="sqlalchemy.sql.expression.ColumnElement.compile.params.column_keys"></span><strong>column_keys</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.ColumnElement.compile.params.column_keys">¶</a> – Used for INSERT and UPDATE statements, a list of
column names which should be present in the VALUES clause of the
compiled statement. If <tt class="docutils literal"><span class="pre">None</span></tt>, all columns from the target table
object are rendered.</li>
<li><span class="target" id="sqlalchemy.sql.expression.ColumnElement.compile.params.dialect"></span><strong>dialect</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.ColumnElement.compile.params.dialect">¶</a> – A <tt class="docutils literal"><span class="pre">Dialect</span></tt> instance from which a <tt class="docutils literal"><span class="pre">Compiled</span></tt>
will be acquired. This argument takes precedence over the <cite>bind</cite>
argument as well as this <a class="reference internal" href="#sqlalchemy.sql.expression.ClauseElement" title="sqlalchemy.sql.expression.ClauseElement"><tt class="xref py py-class docutils literal"><span class="pre">ClauseElement</span></tt></a>‘s bound engine,
if any.</li>
<li><span class="target" id="sqlalchemy.sql.expression.ColumnElement.compile.params.inline"></span><strong>inline</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.ColumnElement.compile.params.inline">¶</a> – Used for INSERT statements, for a dialect which does
not support inline retrieval of newly generated primary key
columns, will force the expression used to create the new primary
key value to be rendered inline within the INSERT statement’s
VALUES clause. This typically refers to Sequence execution but may
also refer to any server-side default generation function
associated with a primary key <cite>Column</cite>.</li>
<li><span class="target" id="sqlalchemy.sql.expression.ColumnElement.compile.params.compile_kwargs"></span><strong>compile_kwargs</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.ColumnElement.compile.params.compile_kwargs">¶</a> – <p>optional dictionary of additional parameters
that will be passed through to the compiler within all “visit”
methods. This allows any custom flag to be passed through to
a custom compilation construct, for example. It is also used
for the case of passing the <tt class="docutils literal"><span class="pre">literal_binds</span></tt> flag through:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">sqlalchemy.sql</span> <span class="kn">import</span> <span class="n">table</span><span class="p">,</span> <span class="n">column</span><span class="p">,</span> <span class="n">select</span>
<span class="n">t</span> <span class="o">=</span> <span class="n">table</span><span class="p">(</span><span class="s">'t'</span><span class="p">,</span> <span class="n">column</span><span class="p">(</span><span class="s">'x'</span><span class="p">))</span>
<span class="n">s</span> <span class="o">=</span> <span class="n">select</span><span class="p">([</span><span class="n">t</span><span class="p">])</span><span class="o">.</span><span class="n">where</span><span class="p">(</span><span class="n">t</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">x</span> <span class="o">==</span> <span class="mi">5</span><span class="p">)</span>
<span class="k">print</span> <span class="n">s</span><span class="o">.</span><span class="n">compile</span><span class="p">(</span><span class="n">compile_kwargs</span><span class="o">=</span><span class="p">{</span><span class="s">"literal_binds"</span><span class="p">:</span> <span class="bp">True</span><span class="p">})</span></pre></div>
</div>
<div class="versionadded">
<p><span>New in version 0.9.0.</span></p>
</div>
</li>
</ul>
</td>
</tr>
</tbody>
</table>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p class="last"><a class="reference internal" href="../faq.html#faq-sql-expression-string"><em>How do I render SQL expressions as strings, possibly with bound parameters inlined?</em></a></p>
</div>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.sql.expression.ColumnElement.concat">
<tt class="descname">concat</tt><big>(</big><em>other</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.ColumnElement.concat" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <a class="reference internal" href="#sqlalchemy.sql.operators.ColumnOperators.concat" title="sqlalchemy.sql.operators.ColumnOperators.concat"><tt class="xref py py-meth docutils literal"><span class="pre">concat()</span></tt></a> <em>method of</em> <a class="reference internal" href="#sqlalchemy.sql.operators.ColumnOperators" title="sqlalchemy.sql.operators.ColumnOperators"><tt class="xref py py-class docutils literal"><span class="pre">ColumnOperators</span></tt></a></div>
<p>Implement the ‘concat’ operator.</p>
<p>In a column context, produces the clause <tt class="docutils literal"><span class="pre">a</span> <span class="pre">||</span> <span class="pre">b</span></tt>,
or uses the <tt class="docutils literal"><span class="pre">concat()</span></tt> operator on MySQL.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.sql.expression.ColumnElement.contains">
<tt class="descname">contains</tt><big>(</big><em>other</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.ColumnElement.contains" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <a class="reference internal" href="#sqlalchemy.sql.operators.ColumnOperators.contains" title="sqlalchemy.sql.operators.ColumnOperators.contains"><tt class="xref py py-meth docutils literal"><span class="pre">contains()</span></tt></a> <em>method of</em> <a class="reference internal" href="#sqlalchemy.sql.operators.ColumnOperators" title="sqlalchemy.sql.operators.ColumnOperators"><tt class="xref py py-class docutils literal"><span class="pre">ColumnOperators</span></tt></a></div>
<p>Implement the ‘contains’ operator.</p>
<p>In a column context, produces the clause <tt class="docutils literal"><span class="pre">LIKE</span> <span class="pre">'%<other>%'</span></tt></p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.sql.expression.ColumnElement.desc">
<tt class="descname">desc</tt><big>(</big><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.ColumnElement.desc" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <a class="reference internal" href="#sqlalchemy.sql.operators.ColumnOperators.desc" title="sqlalchemy.sql.operators.ColumnOperators.desc"><tt class="xref py py-meth docutils literal"><span class="pre">desc()</span></tt></a> <em>method of</em> <a class="reference internal" href="#sqlalchemy.sql.operators.ColumnOperators" title="sqlalchemy.sql.operators.ColumnOperators"><tt class="xref py py-class docutils literal"><span class="pre">ColumnOperators</span></tt></a></div>
<p>Produce a <a class="reference internal" href="#sqlalchemy.sql.expression.desc" title="sqlalchemy.sql.expression.desc"><tt class="xref py py-func docutils literal"><span class="pre">desc()</span></tt></a> clause against the
parent object.</p>
</dd></dl>
<dl class="attribute">
<dt id="sqlalchemy.sql.expression.ColumnElement.description">
<tt class="descname">description</tt><em class="property"> = None</em><a class="headerlink" href="#sqlalchemy.sql.expression.ColumnElement.description" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<dl class="method">
<dt id="sqlalchemy.sql.expression.ColumnElement.distinct">
<tt class="descname">distinct</tt><big>(</big><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.ColumnElement.distinct" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <a class="reference internal" href="#sqlalchemy.sql.operators.ColumnOperators.distinct" title="sqlalchemy.sql.operators.ColumnOperators.distinct"><tt class="xref py py-meth docutils literal"><span class="pre">distinct()</span></tt></a> <em>method of</em> <a class="reference internal" href="#sqlalchemy.sql.operators.ColumnOperators" title="sqlalchemy.sql.operators.ColumnOperators"><tt class="xref py py-class docutils literal"><span class="pre">ColumnOperators</span></tt></a></div>
<p>Produce a <a class="reference internal" href="#sqlalchemy.sql.expression.distinct" title="sqlalchemy.sql.expression.distinct"><tt class="xref py py-func docutils literal"><span class="pre">distinct()</span></tt></a> clause against the
parent object.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.sql.expression.ColumnElement.endswith">
<tt class="descname">endswith</tt><big>(</big><em>other</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.ColumnElement.endswith" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <a class="reference internal" href="#sqlalchemy.sql.operators.ColumnOperators.endswith" title="sqlalchemy.sql.operators.ColumnOperators.endswith"><tt class="xref py py-meth docutils literal"><span class="pre">endswith()</span></tt></a> <em>method of</em> <a class="reference internal" href="#sqlalchemy.sql.operators.ColumnOperators" title="sqlalchemy.sql.operators.ColumnOperators"><tt class="xref py py-class docutils literal"><span class="pre">ColumnOperators</span></tt></a></div>
<p>Implement the ‘endswith’ operator.</p>
<p>In a column context, produces the clause <tt class="docutils literal"><span class="pre">LIKE</span> <span class="pre">'%<other>'</span></tt></p>
</dd></dl>
<dl class="attribute">
<dt id="sqlalchemy.sql.expression.ColumnElement.expression">
<tt class="descname">expression</tt><a class="headerlink" href="#sqlalchemy.sql.expression.ColumnElement.expression" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a column expression.</p>
<p>Part of the inspection interface; returns self.</p>
</dd></dl>
<dl class="attribute">
<dt id="sqlalchemy.sql.expression.ColumnElement.foreign_keys">
<tt class="descname">foreign_keys</tt><em class="property"> = []</em><a class="headerlink" href="#sqlalchemy.sql.expression.ColumnElement.foreign_keys" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<dl class="method">
<dt id="sqlalchemy.sql.expression.ColumnElement.get_children">
<tt class="descname">get_children</tt><big>(</big><em>**kwargs</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.ColumnElement.get_children" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <a class="reference internal" href="#sqlalchemy.sql.expression.ClauseElement.get_children" title="sqlalchemy.sql.expression.ClauseElement.get_children"><tt class="xref py py-meth docutils literal"><span class="pre">get_children()</span></tt></a> <em>method of</em> <a class="reference internal" href="#sqlalchemy.sql.expression.ClauseElement" title="sqlalchemy.sql.expression.ClauseElement"><tt class="xref py py-class docutils literal"><span class="pre">ClauseElement</span></tt></a></div>
<p>Return immediate child elements of this <a class="reference internal" href="#sqlalchemy.sql.expression.ClauseElement" title="sqlalchemy.sql.expression.ClauseElement"><tt class="xref py py-class docutils literal"><span class="pre">ClauseElement</span></tt></a>.</p>
<p>This is used for visit traversal.</p>
<p>**kwargs may contain flags that change the collection that is
returned, for example to return a subset of items in order to
cut down on larger traversals, or to return child items from a
different context (such as schema-level collections instead of
clause-level).</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.sql.expression.ColumnElement.ilike">
<tt class="descname">ilike</tt><big>(</big><em>other</em>, <em>escape=None</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.ColumnElement.ilike" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <a class="reference internal" href="#sqlalchemy.sql.operators.ColumnOperators.ilike" title="sqlalchemy.sql.operators.ColumnOperators.ilike"><tt class="xref py py-meth docutils literal"><span class="pre">ilike()</span></tt></a> <em>method of</em> <a class="reference internal" href="#sqlalchemy.sql.operators.ColumnOperators" title="sqlalchemy.sql.operators.ColumnOperators"><tt class="xref py py-class docutils literal"><span class="pre">ColumnOperators</span></tt></a></div>
<p>Implement the <tt class="docutils literal"><span class="pre">ilike</span></tt> operator.</p>
<p>In a column context, produces the clause <tt class="docutils literal"><span class="pre">a</span> <span class="pre">ILIKE</span> <span class="pre">other</span></tt>.</p>
<p>E.g.:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">select</span><span class="p">([</span><span class="n">sometable</span><span class="p">])</span><span class="o">.</span><span class="n">where</span><span class="p">(</span><span class="n">sometable</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">column</span><span class="o">.</span><span class="n">ilike</span><span class="p">(</span><span class="s">"</span><span class="si">%f</span><span class="s">oobar%"</span><span class="p">))</span></pre></div>
</div>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><span class="target" id="sqlalchemy.sql.expression.ColumnElement.ilike.params.other"></span><strong>other</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.ColumnElement.ilike.params.other">¶</a> – expression to be compared</li>
<li><span class="target" id="sqlalchemy.sql.expression.ColumnElement.ilike.params.escape"></span><strong>escape</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.ColumnElement.ilike.params.escape">¶</a> – <p>optional escape character, renders the <tt class="docutils literal"><span class="pre">ESCAPE</span></tt>
keyword, e.g.:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">somecolumn</span><span class="o">.</span><span class="n">ilike</span><span class="p">(</span><span class="s">"foo/%bar"</span><span class="p">,</span> <span class="n">escape</span><span class="o">=</span><span class="s">"/"</span><span class="p">)</span></pre></div>
</div>
</li>
</ul>
</td>
</tr>
</tbody>
</table>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p class="last"><a class="reference internal" href="#sqlalchemy.sql.operators.ColumnOperators.like" title="sqlalchemy.sql.operators.ColumnOperators.like"><tt class="xref py py-meth docutils literal"><span class="pre">ColumnOperators.like()</span></tt></a></p>
</div>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.sql.expression.ColumnElement.in_">
<tt class="descname">in_</tt><big>(</big><em>other</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.ColumnElement.in_" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <a class="reference internal" href="#sqlalchemy.sql.operators.ColumnOperators.in_" title="sqlalchemy.sql.operators.ColumnOperators.in_"><tt class="xref py py-meth docutils literal"><span class="pre">in_()</span></tt></a> <em>method of</em> <a class="reference internal" href="#sqlalchemy.sql.operators.ColumnOperators" title="sqlalchemy.sql.operators.ColumnOperators"><tt class="xref py py-class docutils literal"><span class="pre">ColumnOperators</span></tt></a></div>
<p>Implement the <tt class="docutils literal"><span class="pre">in</span></tt> operator.</p>
<p>In a column context, produces the clause <tt class="docutils literal"><span class="pre">a</span> <span class="pre">IN</span> <span class="pre">other</span></tt>.
“other” may be a tuple/list of column expressions,
or a <a class="reference internal" href="selectable.html#sqlalchemy.sql.expression.select" title="sqlalchemy.sql.expression.select"><tt class="xref py py-func docutils literal"><span class="pre">select()</span></tt></a> construct.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.sql.expression.ColumnElement.is_">
<tt class="descname">is_</tt><big>(</big><em>other</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.ColumnElement.is_" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <a class="reference internal" href="#sqlalchemy.sql.operators.ColumnOperators.is_" title="sqlalchemy.sql.operators.ColumnOperators.is_"><tt class="xref py py-meth docutils literal"><span class="pre">is_()</span></tt></a> <em>method of</em> <a class="reference internal" href="#sqlalchemy.sql.operators.ColumnOperators" title="sqlalchemy.sql.operators.ColumnOperators"><tt class="xref py py-class docutils literal"><span class="pre">ColumnOperators</span></tt></a></div>
<p>Implement the <tt class="docutils literal"><span class="pre">IS</span></tt> operator.</p>
<p>Normally, <tt class="docutils literal"><span class="pre">IS</span></tt> is generated automatically when comparing to a
value of <tt class="docutils literal"><span class="pre">None</span></tt>, which resolves to <tt class="docutils literal"><span class="pre">NULL</span></tt>. However, explicit
usage of <tt class="docutils literal"><span class="pre">IS</span></tt> may be desirable if comparing to boolean values
on certain platforms.</p>
<div class="versionadded">
<p><span>New in version 0.7.9.</span></p>
</div>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p class="last"><a class="reference internal" href="#sqlalchemy.sql.operators.ColumnOperators.isnot" title="sqlalchemy.sql.operators.ColumnOperators.isnot"><tt class="xref py py-meth docutils literal"><span class="pre">ColumnOperators.isnot()</span></tt></a></p>
</div>
</dd></dl>
<dl class="attribute">
<dt id="sqlalchemy.sql.expression.ColumnElement.is_clause_element">
<tt class="descname">is_clause_element</tt><em class="property"> = True</em><a class="headerlink" href="#sqlalchemy.sql.expression.ColumnElement.is_clause_element" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<dl class="attribute">
<dt id="sqlalchemy.sql.expression.ColumnElement.is_selectable">
<tt class="descname">is_selectable</tt><em class="property"> = False</em><a class="headerlink" href="#sqlalchemy.sql.expression.ColumnElement.is_selectable" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<dl class="method">
<dt id="sqlalchemy.sql.expression.ColumnElement.isnot">
<tt class="descname">isnot</tt><big>(</big><em>other</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.ColumnElement.isnot" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <a class="reference internal" href="#sqlalchemy.sql.operators.ColumnOperators.isnot" title="sqlalchemy.sql.operators.ColumnOperators.isnot"><tt class="xref py py-meth docutils literal"><span class="pre">isnot()</span></tt></a> <em>method of</em> <a class="reference internal" href="#sqlalchemy.sql.operators.ColumnOperators" title="sqlalchemy.sql.operators.ColumnOperators"><tt class="xref py py-class docutils literal"><span class="pre">ColumnOperators</span></tt></a></div>
<p>Implement the <tt class="docutils literal"><span class="pre">IS</span> <span class="pre">NOT</span></tt> operator.</p>
<p>Normally, <tt class="docutils literal"><span class="pre">IS</span> <span class="pre">NOT</span></tt> is generated automatically when comparing to a
value of <tt class="docutils literal"><span class="pre">None</span></tt>, which resolves to <tt class="docutils literal"><span class="pre">NULL</span></tt>. However, explicit
usage of <tt class="docutils literal"><span class="pre">IS</span> <span class="pre">NOT</span></tt> may be desirable if comparing to boolean values
on certain platforms.</p>
<div class="versionadded">
<p><span>New in version 0.7.9.</span></p>
</div>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p class="last"><a class="reference internal" href="#sqlalchemy.sql.operators.ColumnOperators.is_" title="sqlalchemy.sql.operators.ColumnOperators.is_"><tt class="xref py py-meth docutils literal"><span class="pre">ColumnOperators.is_()</span></tt></a></p>
</div>
</dd></dl>
<dl class="attribute">
<dt id="sqlalchemy.sql.expression.ColumnElement.key">
<tt class="descname">key</tt><em class="property"> = None</em><a class="headerlink" href="#sqlalchemy.sql.expression.ColumnElement.key" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<dl class="method">
<dt id="sqlalchemy.sql.expression.ColumnElement.label">
<tt class="descname">label</tt><big>(</big><em>name</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.ColumnElement.label" title="Permalink to this definition">¶</a></dt>
<dd><p>Produce a column label, i.e. <tt class="docutils literal"><span class="pre"><columnname></span> <span class="pre">AS</span> <span class="pre"><name></span></tt>.</p>
<p>This is a shortcut to the <a class="reference internal" href="#sqlalchemy.sql.expression.label" title="sqlalchemy.sql.expression.label"><tt class="xref py py-func docutils literal"><span class="pre">label()</span></tt></a> function.</p>
<p>if ‘name’ is None, an anonymous label name will be generated.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.sql.expression.ColumnElement.like">
<tt class="descname">like</tt><big>(</big><em>other</em>, <em>escape=None</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.ColumnElement.like" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <a class="reference internal" href="#sqlalchemy.sql.operators.ColumnOperators.like" title="sqlalchemy.sql.operators.ColumnOperators.like"><tt class="xref py py-meth docutils literal"><span class="pre">like()</span></tt></a> <em>method of</em> <a class="reference internal" href="#sqlalchemy.sql.operators.ColumnOperators" title="sqlalchemy.sql.operators.ColumnOperators"><tt class="xref py py-class docutils literal"><span class="pre">ColumnOperators</span></tt></a></div>
<p>Implement the <tt class="docutils literal"><span class="pre">like</span></tt> operator.</p>
<p>In a column context, produces the clause <tt class="docutils literal"><span class="pre">a</span> <span class="pre">LIKE</span> <span class="pre">other</span></tt>.</p>
<p>E.g.:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">select</span><span class="p">([</span><span class="n">sometable</span><span class="p">])</span><span class="o">.</span><span class="n">where</span><span class="p">(</span><span class="n">sometable</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">column</span><span class="o">.</span><span class="n">like</span><span class="p">(</span><span class="s">"</span><span class="si">%f</span><span class="s">oobar%"</span><span class="p">))</span></pre></div>
</div>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><span class="target" id="sqlalchemy.sql.expression.ColumnElement.like.params.other"></span><strong>other</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.ColumnElement.like.params.other">¶</a> – expression to be compared</li>
<li><span class="target" id="sqlalchemy.sql.expression.ColumnElement.like.params.escape"></span><strong>escape</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.ColumnElement.like.params.escape">¶</a> – <p>optional escape character, renders the <tt class="docutils literal"><span class="pre">ESCAPE</span></tt>
keyword, e.g.:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">somecolumn</span><span class="o">.</span><span class="n">like</span><span class="p">(</span><span class="s">"foo/%bar"</span><span class="p">,</span> <span class="n">escape</span><span class="o">=</span><span class="s">"/"</span><span class="p">)</span></pre></div>
</div>
</li>
</ul>
</td>
</tr>
</tbody>
</table>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p class="last"><a class="reference internal" href="#sqlalchemy.sql.operators.ColumnOperators.ilike" title="sqlalchemy.sql.operators.ColumnOperators.ilike"><tt class="xref py py-meth docutils literal"><span class="pre">ColumnOperators.ilike()</span></tt></a></p>
</div>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.sql.expression.ColumnElement.match">
<tt class="descname">match</tt><big>(</big><em>other</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.ColumnElement.match" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <a class="reference internal" href="#sqlalchemy.sql.operators.ColumnOperators.match" title="sqlalchemy.sql.operators.ColumnOperators.match"><tt class="xref py py-meth docutils literal"><span class="pre">match()</span></tt></a> <em>method of</em> <a class="reference internal" href="#sqlalchemy.sql.operators.ColumnOperators" title="sqlalchemy.sql.operators.ColumnOperators"><tt class="xref py py-class docutils literal"><span class="pre">ColumnOperators</span></tt></a></div>
<p>Implements a database-specific ‘match’ operator.</p>
<p><a class="reference internal" href="#sqlalchemy.sql.operators.ColumnOperators.match" title="sqlalchemy.sql.operators.ColumnOperators.match"><tt class="xref py py-meth docutils literal"><span class="pre">match()</span></tt></a> attempts to resolve to
a MATCH-like function or operator provided by the backend.
Examples include:</p>
<ul class="simple">
<li>Postgresql - renders <tt class="docutils literal"><span class="pre">x</span> <span class="pre">@@</span> <span class="pre">to_tsquery(y)</span></tt></li>
<li>MySQL - renders <tt class="docutils literal"><span class="pre">MATCH</span> <span class="pre">(x)</span> <span class="pre">AGAINST</span> <span class="pre">(y</span> <span class="pre">IN</span> <span class="pre">BOOLEAN</span> <span class="pre">MODE)</span></tt></li>
<li>Oracle - renders <tt class="docutils literal"><span class="pre">CONTAINS(x,</span> <span class="pre">y)</span></tt></li>
<li>other backends may provide special implementations;
some backends such as SQLite have no support.</li>
</ul>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.sql.expression.ColumnElement.notilike">
<tt class="descname">notilike</tt><big>(</big><em>other</em>, <em>escape=None</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.ColumnElement.notilike" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <a class="reference internal" href="#sqlalchemy.sql.operators.ColumnOperators.notilike" title="sqlalchemy.sql.operators.ColumnOperators.notilike"><tt class="xref py py-meth docutils literal"><span class="pre">notilike()</span></tt></a> <em>method of</em> <a class="reference internal" href="#sqlalchemy.sql.operators.ColumnOperators" title="sqlalchemy.sql.operators.ColumnOperators"><tt class="xref py py-class docutils literal"><span class="pre">ColumnOperators</span></tt></a></div>
<p>implement the <tt class="docutils literal"><span class="pre">NOT</span> <span class="pre">ILIKE</span></tt> operator.</p>
<p>This is equivalent to using negation with
<a class="reference internal" href="#sqlalchemy.sql.operators.ColumnOperators.ilike" title="sqlalchemy.sql.operators.ColumnOperators.ilike"><tt class="xref py py-meth docutils literal"><span class="pre">ColumnOperators.ilike()</span></tt></a>, i.e. <tt class="docutils literal"><span class="pre">~x.ilike(y)</span></tt>.</p>
<div class="versionadded">
<p><span>New in version 0.8.</span></p>
</div>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p class="last"><a class="reference internal" href="#sqlalchemy.sql.operators.ColumnOperators.ilike" title="sqlalchemy.sql.operators.ColumnOperators.ilike"><tt class="xref py py-meth docutils literal"><span class="pre">ColumnOperators.ilike()</span></tt></a></p>
</div>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.sql.expression.ColumnElement.notin_">
<tt class="descname">notin_</tt><big>(</big><em>other</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.ColumnElement.notin_" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <a class="reference internal" href="#sqlalchemy.sql.operators.ColumnOperators.notin_" title="sqlalchemy.sql.operators.ColumnOperators.notin_"><tt class="xref py py-meth docutils literal"><span class="pre">notin_()</span></tt></a> <em>method of</em> <a class="reference internal" href="#sqlalchemy.sql.operators.ColumnOperators" title="sqlalchemy.sql.operators.ColumnOperators"><tt class="xref py py-class docutils literal"><span class="pre">ColumnOperators</span></tt></a></div>
<p>implement the <tt class="docutils literal"><span class="pre">NOT</span> <span class="pre">IN</span></tt> operator.</p>
<p>This is equivalent to using negation with
<a class="reference internal" href="#sqlalchemy.sql.operators.ColumnOperators.in_" title="sqlalchemy.sql.operators.ColumnOperators.in_"><tt class="xref py py-meth docutils literal"><span class="pre">ColumnOperators.in_()</span></tt></a>, i.e. <tt class="docutils literal"><span class="pre">~x.in_(y)</span></tt>.</p>
<div class="versionadded">
<p><span>New in version 0.8.</span></p>
</div>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p class="last"><a class="reference internal" href="#sqlalchemy.sql.operators.ColumnOperators.in_" title="sqlalchemy.sql.operators.ColumnOperators.in_"><tt class="xref py py-meth docutils literal"><span class="pre">ColumnOperators.in_()</span></tt></a></p>
</div>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.sql.expression.ColumnElement.notlike">
<tt class="descname">notlike</tt><big>(</big><em>other</em>, <em>escape=None</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.ColumnElement.notlike" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <a class="reference internal" href="#sqlalchemy.sql.operators.ColumnOperators.notlike" title="sqlalchemy.sql.operators.ColumnOperators.notlike"><tt class="xref py py-meth docutils literal"><span class="pre">notlike()</span></tt></a> <em>method of</em> <a class="reference internal" href="#sqlalchemy.sql.operators.ColumnOperators" title="sqlalchemy.sql.operators.ColumnOperators"><tt class="xref py py-class docutils literal"><span class="pre">ColumnOperators</span></tt></a></div>
<p>implement the <tt class="docutils literal"><span class="pre">NOT</span> <span class="pre">LIKE</span></tt> operator.</p>
<p>This is equivalent to using negation with
<a class="reference internal" href="#sqlalchemy.sql.operators.ColumnOperators.like" title="sqlalchemy.sql.operators.ColumnOperators.like"><tt class="xref py py-meth docutils literal"><span class="pre">ColumnOperators.like()</span></tt></a>, i.e. <tt class="docutils literal"><span class="pre">~x.like(y)</span></tt>.</p>
<div class="versionadded">
<p><span>New in version 0.8.</span></p>
</div>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p class="last"><a class="reference internal" href="#sqlalchemy.sql.operators.ColumnOperators.like" title="sqlalchemy.sql.operators.ColumnOperators.like"><tt class="xref py py-meth docutils literal"><span class="pre">ColumnOperators.like()</span></tt></a></p>
</div>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.sql.expression.ColumnElement.nullsfirst">
<tt class="descname">nullsfirst</tt><big>(</big><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.ColumnElement.nullsfirst" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <a class="reference internal" href="#sqlalchemy.sql.operators.ColumnOperators.nullsfirst" title="sqlalchemy.sql.operators.ColumnOperators.nullsfirst"><tt class="xref py py-meth docutils literal"><span class="pre">nullsfirst()</span></tt></a> <em>method of</em> <a class="reference internal" href="#sqlalchemy.sql.operators.ColumnOperators" title="sqlalchemy.sql.operators.ColumnOperators"><tt class="xref py py-class docutils literal"><span class="pre">ColumnOperators</span></tt></a></div>
<p>Produce a <a class="reference internal" href="#sqlalchemy.sql.expression.nullsfirst" title="sqlalchemy.sql.expression.nullsfirst"><tt class="xref py py-func docutils literal"><span class="pre">nullsfirst()</span></tt></a> clause against the
parent object.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.sql.expression.ColumnElement.nullslast">
<tt class="descname">nullslast</tt><big>(</big><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.ColumnElement.nullslast" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <a class="reference internal" href="#sqlalchemy.sql.operators.ColumnOperators.nullslast" title="sqlalchemy.sql.operators.ColumnOperators.nullslast"><tt class="xref py py-meth docutils literal"><span class="pre">nullslast()</span></tt></a> <em>method of</em> <a class="reference internal" href="#sqlalchemy.sql.operators.ColumnOperators" title="sqlalchemy.sql.operators.ColumnOperators"><tt class="xref py py-class docutils literal"><span class="pre">ColumnOperators</span></tt></a></div>
<p>Produce a <a class="reference internal" href="#sqlalchemy.sql.expression.nullslast" title="sqlalchemy.sql.expression.nullslast"><tt class="xref py py-func docutils literal"><span class="pre">nullslast()</span></tt></a> clause against the
parent object.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.sql.expression.ColumnElement.op">
<tt class="descname">op</tt><big>(</big><em>opstring</em>, <em>precedence=0</em>, <em>is_comparison=False</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.ColumnElement.op" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <a class="reference internal" href="#sqlalchemy.sql.operators.Operators.op" title="sqlalchemy.sql.operators.Operators.op"><tt class="xref py py-meth docutils literal"><span class="pre">op()</span></tt></a> <em>method of</em> <a class="reference internal" href="#sqlalchemy.sql.operators.Operators" title="sqlalchemy.sql.operators.Operators"><tt class="xref py py-class docutils literal"><span class="pre">Operators</span></tt></a></div>
<p>produce a generic operator function.</p>
<p>e.g.:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">somecolumn</span><span class="o">.</span><span class="n">op</span><span class="p">(</span><span class="s">"*"</span><span class="p">)(</span><span class="mi">5</span><span class="p">)</span></pre></div>
</div>
<p>produces:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">somecolumn</span> <span class="o">*</span> <span class="mi">5</span></pre></div>
</div>
<p>This function can also be used to make bitwise operators explicit. For
example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">somecolumn</span><span class="o">.</span><span class="n">op</span><span class="p">(</span><span class="s">'&'</span><span class="p">)(</span><span class="mh">0xff</span><span class="p">)</span></pre></div>
</div>
<p>is a bitwise AND of the value in <tt class="docutils literal"><span class="pre">somecolumn</span></tt>.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><span class="target" id="sqlalchemy.sql.expression.ColumnElement.op.params.operator"></span><strong>operator</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.ColumnElement.op.params.operator">¶</a> – a string which will be output as the infix operator
between this element and the expression passed to the
generated function.</li>
<li><span class="target" id="sqlalchemy.sql.expression.ColumnElement.op.params.precedence"></span><strong>precedence</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.ColumnElement.op.params.precedence">¶</a> – <p>precedence to apply to the operator, when
parenthesizing expressions. A lower number will cause the expression
to be parenthesized when applied against another operator with
higher precedence. The default value of <tt class="docutils literal"><span class="pre">0</span></tt> is lower than all
operators except for the comma (<tt class="docutils literal"><span class="pre">,</span></tt>) and <tt class="docutils literal"><span class="pre">AS</span></tt> operators.
A value of 100 will be higher or equal to all operators, and -100
will be lower than or equal to all operators.</p>
<div class="versionadded">
<p><span>New in version 0.8: </span>- added the ‘precedence’ argument.</p>
</div>
</li>
<li><span class="target" id="sqlalchemy.sql.expression.ColumnElement.op.params.is_comparison"></span><strong>is_comparison</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.expression.ColumnElement.op.params.is_comparison">¶</a> – <p>if True, the operator will be considered as a
“comparison” operator, that is which evaulates to a boolean
true/false value, like <tt class="docutils literal"><span class="pre">==</span></tt>, <tt class="docutils literal"><span class="pre">></span></tt>, etc. This flag should be set
so that ORM relationships can establish that the operator is a
comparison operator when used in a custom join condition.</p>
<div class="versionadded">
<p><span>New in version 0.9.2: </span>- added the
<a class="reference internal" href="#sqlalchemy.sql.operators.Operators.op.params.is_comparison" title="sqlalchemy.sql.operators.Operators.op"><tt class="xref py py-paramref docutils literal"><span class="pre">Operators.op.is_comparison</span></tt></a> flag.</p>
</div>
</li>
</ul>
</td>
</tr>
</tbody>
</table>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p><a class="reference internal" href="types.html#types-operators"><em>Redefining and Creating New Operators</em></a></p>
<p class="last"><a class="reference internal" href="../orm/relationships.html#relationship-custom-operator"><em>Using custom operators in join conditions</em></a></p>
</div>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.sql.expression.ColumnElement.operate">
<tt class="descname">operate</tt><big>(</big><em>op</em>, <em>*other</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.ColumnElement.operate" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<dl class="method">
<dt id="sqlalchemy.sql.expression.ColumnElement.params">
<tt class="descname">params</tt><big>(</big><em>*optionaldict</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.ColumnElement.params" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <a class="reference internal" href="#sqlalchemy.sql.expression.ClauseElement.params" title="sqlalchemy.sql.expression.ClauseElement.params"><tt class="xref py py-meth docutils literal"><span class="pre">params()</span></tt></a> <em>method of</em> <a class="reference internal" href="#sqlalchemy.sql.expression.ClauseElement" title="sqlalchemy.sql.expression.ClauseElement"><tt class="xref py py-class docutils literal"><span class="pre">ClauseElement</span></tt></a></div>
<p>Return a copy with <a class="reference internal" href="#sqlalchemy.sql.expression.bindparam" title="sqlalchemy.sql.expression.bindparam"><tt class="xref py py-func docutils literal"><span class="pre">bindparam()</span></tt></a> elements replaced.</p>
<p>Returns a copy of this ClauseElement with <a class="reference internal" href="#sqlalchemy.sql.expression.bindparam" title="sqlalchemy.sql.expression.bindparam"><tt class="xref py py-func docutils literal"><span class="pre">bindparam()</span></tt></a>
elements replaced with values taken from the given dictionary:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">clause</span> <span class="o">=</span> <span class="n">column</span><span class="p">(</span><span class="s">'x'</span><span class="p">)</span> <span class="o">+</span> <span class="n">bindparam</span><span class="p">(</span><span class="s">'foo'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="k">print</span> <span class="n">clause</span><span class="o">.</span><span class="n">compile</span><span class="p">()</span><span class="o">.</span><span class="n">params</span>
<span class="go">{'foo':None}</span>
<span class="gp">>>> </span><span class="k">print</span> <span class="n">clause</span><span class="o">.</span><span class="n">params</span><span class="p">({</span><span class="s">'foo'</span><span class="p">:</span><span class="mi">7</span><span class="p">})</span><span class="o">.</span><span class="n">compile</span><span class="p">()</span><span class="o">.</span><span class="n">params</span>
<span class="go">{'foo':7}</span></pre></div>
</div>
</dd></dl>
<dl class="attribute">
<dt id="sqlalchemy.sql.expression.ColumnElement.primary_key">
<tt class="descname">primary_key</tt><em class="property"> = False</em><a class="headerlink" href="#sqlalchemy.sql.expression.ColumnElement.primary_key" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<dl class="attribute">
<dt id="sqlalchemy.sql.expression.ColumnElement.proxy_set">
<tt class="descname">proxy_set</tt><a class="headerlink" href="#sqlalchemy.sql.expression.ColumnElement.proxy_set" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<dl class="method">
<dt id="sqlalchemy.sql.expression.ColumnElement.reverse_operate">
<tt class="descname">reverse_operate</tt><big>(</big><em>op</em>, <em>other</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.ColumnElement.reverse_operate" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<dl class="method">
<dt id="sqlalchemy.sql.expression.ColumnElement.self_group">
<tt class="descname">self_group</tt><big>(</big><em>against=None</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.ColumnElement.self_group" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<dl class="method">
<dt id="sqlalchemy.sql.expression.ColumnElement.shares_lineage">
<tt class="descname">shares_lineage</tt><big>(</big><em>othercolumn</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.ColumnElement.shares_lineage" title="Permalink to this definition">¶</a></dt>
<dd><p>Return True if the given <a class="reference internal" href="#sqlalchemy.sql.expression.ColumnElement" title="sqlalchemy.sql.expression.ColumnElement"><tt class="xref py py-class docutils literal"><span class="pre">ColumnElement</span></tt></a>
has a common ancestor to this <a class="reference internal" href="#sqlalchemy.sql.expression.ColumnElement" title="sqlalchemy.sql.expression.ColumnElement"><tt class="xref py py-class docutils literal"><span class="pre">ColumnElement</span></tt></a>.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.sql.expression.ColumnElement.startswith">
<tt class="descname">startswith</tt><big>(</big><em>other</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.ColumnElement.startswith" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <a class="reference internal" href="#sqlalchemy.sql.operators.ColumnOperators.startswith" title="sqlalchemy.sql.operators.ColumnOperators.startswith"><tt class="xref py py-meth docutils literal"><span class="pre">startswith()</span></tt></a> <em>method of</em> <a class="reference internal" href="#sqlalchemy.sql.operators.ColumnOperators" title="sqlalchemy.sql.operators.ColumnOperators"><tt class="xref py py-class docutils literal"><span class="pre">ColumnOperators</span></tt></a></div>
<p>Implement the <tt class="docutils literal"><span class="pre">startwith</span></tt> operator.</p>
<p>In a column context, produces the clause <tt class="docutils literal"><span class="pre">LIKE</span> <span class="pre">'<other>%'</span></tt></p>
</dd></dl>
<dl class="attribute">
<dt id="sqlalchemy.sql.expression.ColumnElement.supports_execution">
<tt class="descname">supports_execution</tt><em class="property"> = False</em><a class="headerlink" href="#sqlalchemy.sql.expression.ColumnElement.supports_execution" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<dl class="attribute">
<dt id="sqlalchemy.sql.expression.ColumnElement.timetuple">
<tt class="descname">timetuple</tt><em class="property"> = None</em><a class="headerlink" href="#sqlalchemy.sql.expression.ColumnElement.timetuple" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<dl class="attribute">
<dt id="sqlalchemy.sql.expression.ColumnElement.type">
<tt class="descname">type</tt><a class="headerlink" href="#sqlalchemy.sql.expression.ColumnElement.type" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<dl class="method">
<dt id="sqlalchemy.sql.expression.ColumnElement.unique_params">
<tt class="descname">unique_params</tt><big>(</big><em>*optionaldict</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.ColumnElement.unique_params" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <a class="reference internal" href="#sqlalchemy.sql.expression.ClauseElement.unique_params" title="sqlalchemy.sql.expression.ClauseElement.unique_params"><tt class="xref py py-meth docutils literal"><span class="pre">unique_params()</span></tt></a> <em>method of</em> <a class="reference internal" href="#sqlalchemy.sql.expression.ClauseElement" title="sqlalchemy.sql.expression.ClauseElement"><tt class="xref py py-class docutils literal"><span class="pre">ClauseElement</span></tt></a></div>
<p>Return a copy with <a class="reference internal" href="#sqlalchemy.sql.expression.bindparam" title="sqlalchemy.sql.expression.bindparam"><tt class="xref py py-func docutils literal"><span class="pre">bindparam()</span></tt></a> elements replaced.</p>
<p>Same functionality as <tt class="docutils literal"><span class="pre">params()</span></tt>, except adds <cite>unique=True</cite>
to affected bind parameters so that multiple statements can be
used.</p>
</dd></dl>
</dd></dl>
<dl class="class">
<dt id="sqlalchemy.sql.operators.ColumnOperators">
<em class="property">class </em><tt class="descclassname">sqlalchemy.sql.operators.</tt><tt class="descname">ColumnOperators</tt><a class="headerlink" href="#sqlalchemy.sql.operators.ColumnOperators" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference internal" href="#sqlalchemy.sql.operators.Operators" title="sqlalchemy.sql.operators.Operators"><tt class="xref py py-class docutils literal"><span class="pre">sqlalchemy.sql.operators.Operators</span></tt></a></p>
<p>Defines boolean, comparison, and other operators for
<a class="reference internal" href="#sqlalchemy.sql.expression.ColumnElement" title="sqlalchemy.sql.expression.ColumnElement"><tt class="xref py py-class docutils literal"><span class="pre">ColumnElement</span></tt></a> expressions.</p>
<p>By default, all methods call down to
<a class="reference internal" href="#sqlalchemy.sql.operators.Operators.operate" title="sqlalchemy.sql.operators.Operators.operate"><tt class="xref py py-meth docutils literal"><span class="pre">operate()</span></tt></a> or <a class="reference internal" href="#sqlalchemy.sql.expression.ColumnElement.reverse_operate" title="sqlalchemy.sql.expression.ColumnElement.reverse_operate"><tt class="xref py py-meth docutils literal"><span class="pre">reverse_operate()</span></tt></a>,
passing in the appropriate operator function from the
Python builtin <tt class="docutils literal"><span class="pre">operator</span></tt> module or
a SQLAlchemy-specific operator function from
<tt class="xref py py-mod docutils literal"><span class="pre">sqlalchemy.expression.operators</span></tt>. For example
the <tt class="docutils literal"><span class="pre">__eq__</span></tt> function:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">def</span> <span class="nf">__eq__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">other</span><span class="p">):</span>
<span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">operate</span><span class="p">(</span><span class="n">operators</span><span class="o">.</span><span class="n">eq</span><span class="p">,</span> <span class="n">other</span><span class="p">)</span></pre></div>
</div>
<p>Where <tt class="docutils literal"><span class="pre">operators.eq</span></tt> is essentially:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">def</span> <span class="nf">eq</span><span class="p">(</span><span class="n">a</span><span class="p">,</span> <span class="n">b</span><span class="p">):</span>
<span class="k">return</span> <span class="n">a</span> <span class="o">==</span> <span class="n">b</span></pre></div>
</div>
<p>The core column expression unit <a class="reference internal" href="#sqlalchemy.sql.expression.ColumnElement" title="sqlalchemy.sql.expression.ColumnElement"><tt class="xref py py-class docutils literal"><span class="pre">ColumnElement</span></tt></a>
overrides <a class="reference internal" href="#sqlalchemy.sql.operators.Operators.operate" title="sqlalchemy.sql.operators.Operators.operate"><tt class="xref py py-meth docutils literal"><span class="pre">Operators.operate()</span></tt></a> and others
to return further <a class="reference internal" href="#sqlalchemy.sql.expression.ColumnElement" title="sqlalchemy.sql.expression.ColumnElement"><tt class="xref py py-class docutils literal"><span class="pre">ColumnElement</span></tt></a> constructs,
so that the <tt class="docutils literal"><span class="pre">==</span></tt> operation above is replaced by a clause
construct.</p>
<p>See also:</p>
<p><a class="reference internal" href="types.html#types-operators"><em>Redefining and Creating New Operators</em></a></p>
<p><a class="reference internal" href="types.html#sqlalchemy.types.TypeEngine.comparator_factory" title="sqlalchemy.types.TypeEngine.comparator_factory"><tt class="xref py py-attr docutils literal"><span class="pre">TypeEngine.comparator_factory</span></tt></a></p>
<p><a class="reference internal" href="#sqlalchemy.sql.operators.ColumnOperators" title="sqlalchemy.sql.operators.ColumnOperators"><tt class="xref py py-class docutils literal"><span class="pre">ColumnOperators</span></tt></a></p>
<p><a class="reference internal" href="../orm/internals.html#sqlalchemy.orm.interfaces.PropComparator" title="sqlalchemy.orm.interfaces.PropComparator"><tt class="xref py py-class docutils literal"><span class="pre">PropComparator</span></tt></a></p>
<dl class="method">
<dt id="sqlalchemy.sql.operators.ColumnOperators.__add__">
<tt class="descname">__add__</tt><big>(</big><em>other</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.operators.ColumnOperators.__add__" title="Permalink to this definition">¶</a></dt>
<dd><p>Implement the <tt class="docutils literal"><span class="pre">+</span></tt> operator.</p>
<p>In a column context, produces the clause <tt class="docutils literal"><span class="pre">a</span> <span class="pre">+</span> <span class="pre">b</span></tt>
if the parent object has non-string affinity.
If the parent object has a string affinity,
produces the concatenation operator, <tt class="docutils literal"><span class="pre">a</span> <span class="pre">||</span> <span class="pre">b</span></tt> -
see <a class="reference internal" href="#sqlalchemy.sql.operators.ColumnOperators.concat" title="sqlalchemy.sql.operators.ColumnOperators.concat"><tt class="xref py py-meth docutils literal"><span class="pre">ColumnOperators.concat()</span></tt></a>.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.sql.operators.ColumnOperators.__and__">
<tt class="descname">__and__</tt><big>(</big><em>other</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.operators.ColumnOperators.__and__" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <a class="reference internal" href="#sqlalchemy.sql.operators.Operators.__and__" title="sqlalchemy.sql.operators.Operators.__and__"><tt class="xref py py-meth docutils literal"><span class="pre">__and__()</span></tt></a> <em>method of</em> <a class="reference internal" href="#sqlalchemy.sql.operators.Operators" title="sqlalchemy.sql.operators.Operators"><tt class="xref py py-class docutils literal"><span class="pre">Operators</span></tt></a></div>
<p>Implement the <tt class="docutils literal"><span class="pre">&</span></tt> operator.</p>
<p>When used with SQL expressions, results in an
AND operation, equivalent to
<a class="reference internal" href="#sqlalchemy.sql.expression.and_" title="sqlalchemy.sql.expression.and_"><tt class="xref py py-func docutils literal"><span class="pre">and_()</span></tt></a>, that is:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">a</span> <span class="o">&</span> <span class="n">b</span></pre></div>
</div>
<p>is equivalent to:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="kn">import</span> <span class="n">and_</span>
<span class="n">and_</span><span class="p">(</span><span class="n">a</span><span class="p">,</span> <span class="n">b</span><span class="p">)</span></pre></div>
</div>
<p>Care should be taken when using <tt class="docutils literal"><span class="pre">&</span></tt> regarding
operator precedence; the <tt class="docutils literal"><span class="pre">&</span></tt> operator has the highest precedence.
The operands should be enclosed in parenthesis if they contain
further sub expressions:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="p">(</span><span class="n">a</span> <span class="o">==</span> <span class="mi">2</span><span class="p">)</span> <span class="o">&</span> <span class="p">(</span><span class="n">b</span> <span class="o">==</span> <span class="mi">4</span><span class="p">)</span></pre></div>
</div>
</dd></dl>
<dl class="attribute">
<dt id="sqlalchemy.sql.operators.ColumnOperators.__delattr__">
<tt class="descname">__delattr__</tt><a class="headerlink" href="#sqlalchemy.sql.operators.ColumnOperators.__delattr__" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <tt class="xref py py-attr docutils literal"><span class="pre">__delattr__</span></tt> <em>attribute of</em> <tt class="xref py py-class docutils literal"><span class="pre">object</span></tt></div>
<p>x.__delattr__(‘name’) <==> del x.name</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.sql.operators.ColumnOperators.__div__">
<tt class="descname">__div__</tt><big>(</big><em>other</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.operators.ColumnOperators.__div__" title="Permalink to this definition">¶</a></dt>
<dd><p>Implement the <tt class="docutils literal"><span class="pre">/</span></tt> operator.</p>
<p>In a column context, produces the clause <tt class="docutils literal"><span class="pre">a</span> <span class="pre">/</span> <span class="pre">b</span></tt>.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.sql.operators.ColumnOperators.__eq__">
<tt class="descname">__eq__</tt><big>(</big><em>other</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.operators.ColumnOperators.__eq__" title="Permalink to this definition">¶</a></dt>
<dd><p>Implement the <tt class="docutils literal"><span class="pre">==</span></tt> operator.</p>
<p>In a column context, produces the clause <tt class="docutils literal"><span class="pre">a</span> <span class="pre">=</span> <span class="pre">b</span></tt>.
If the target is <tt class="docutils literal"><span class="pre">None</span></tt>, produces <tt class="docutils literal"><span class="pre">a</span> <span class="pre">IS</span> <span class="pre">NULL</span></tt>.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.sql.operators.ColumnOperators.__format__">
<tt class="descname">__format__</tt><big>(</big><big>)</big><a class="headerlink" href="#sqlalchemy.sql.operators.ColumnOperators.__format__" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <tt class="xref py py-meth docutils literal"><span class="pre">__format__()</span></tt> <em>method of</em> <tt class="xref py py-class docutils literal"><span class="pre">object</span></tt></div>
<p>default object formatter</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.sql.operators.ColumnOperators.__ge__">
<tt class="descname">__ge__</tt><big>(</big><em>other</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.operators.ColumnOperators.__ge__" title="Permalink to this definition">¶</a></dt>
<dd><p>Implement the <tt class="docutils literal"><span class="pre">>=</span></tt> operator.</p>
<p>In a column context, produces the clause <tt class="docutils literal"><span class="pre">a</span> <span class="pre">>=</span> <span class="pre">b</span></tt>.</p>
</dd></dl>
<dl class="attribute">
<dt id="sqlalchemy.sql.operators.ColumnOperators.__getattribute__">
<tt class="descname">__getattribute__</tt><a class="headerlink" href="#sqlalchemy.sql.operators.ColumnOperators.__getattribute__" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <tt class="xref py py-attr docutils literal"><span class="pre">__getattribute__</span></tt> <em>attribute of</em> <tt class="xref py py-class docutils literal"><span class="pre">object</span></tt></div>
<p>x.__getattribute__(‘name’) <==> x.name</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.sql.operators.ColumnOperators.__getitem__">
<tt class="descname">__getitem__</tt><big>(</big><em>index</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.operators.ColumnOperators.__getitem__" title="Permalink to this definition">¶</a></dt>
<dd><p>Implement the [] operator.</p>
<p>This can be used by some database-specific types
such as Postgresql ARRAY and HSTORE.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.sql.operators.ColumnOperators.__gt__">
<tt class="descname">__gt__</tt><big>(</big><em>other</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.operators.ColumnOperators.__gt__" title="Permalink to this definition">¶</a></dt>
<dd><p>Implement the <tt class="docutils literal"><span class="pre">></span></tt> operator.</p>
<p>In a column context, produces the clause <tt class="docutils literal"><span class="pre">a</span> <span class="pre">></span> <span class="pre">b</span></tt>.</p>
</dd></dl>
<dl class="attribute">
<dt id="sqlalchemy.sql.operators.ColumnOperators.__hash__">
<tt class="descname">__hash__</tt><a class="headerlink" href="#sqlalchemy.sql.operators.ColumnOperators.__hash__" title="Permalink to this definition">¶</a></dt>
<dd><p>x.__hash__() <==> hash(x)</p>
</dd></dl>
<dl class="attribute">
<dt id="sqlalchemy.sql.operators.ColumnOperators.__init__">
<tt class="descname">__init__</tt><a class="headerlink" href="#sqlalchemy.sql.operators.ColumnOperators.__init__" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <tt class="xref py py-attr docutils literal"><span class="pre">__init__</span></tt> <em>attribute of</em> <tt class="xref py py-class docutils literal"><span class="pre">object</span></tt></div>
<p>x.__init__(...) initializes x; see help(type(x)) for signature</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.sql.operators.ColumnOperators.__invert__">
<tt class="descname">__invert__</tt><big>(</big><big>)</big><a class="headerlink" href="#sqlalchemy.sql.operators.ColumnOperators.__invert__" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <a class="reference internal" href="#sqlalchemy.sql.operators.Operators.__invert__" title="sqlalchemy.sql.operators.Operators.__invert__"><tt class="xref py py-meth docutils literal"><span class="pre">__invert__()</span></tt></a> <em>method of</em> <a class="reference internal" href="#sqlalchemy.sql.operators.Operators" title="sqlalchemy.sql.operators.Operators"><tt class="xref py py-class docutils literal"><span class="pre">Operators</span></tt></a></div>
<p>Implement the <tt class="docutils literal"><span class="pre">~</span></tt> operator.</p>
<p>When used with SQL expressions, results in a
NOT operation, equivalent to
<a class="reference internal" href="#sqlalchemy.sql.expression.not_" title="sqlalchemy.sql.expression.not_"><tt class="xref py py-func docutils literal"><span class="pre">not_()</span></tt></a>, that is:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="o">~</span><span class="n">a</span></pre></div>
</div>
<p>is equivalent to:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="kn">import</span> <span class="n">not_</span>
<span class="n">not_</span><span class="p">(</span><span class="n">a</span><span class="p">)</span></pre></div>
</div>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.sql.operators.ColumnOperators.__le__">
<tt class="descname">__le__</tt><big>(</big><em>other</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.operators.ColumnOperators.__le__" title="Permalink to this definition">¶</a></dt>
<dd><p>Implement the <tt class="docutils literal"><span class="pre"><=</span></tt> operator.</p>
<p>In a column context, produces the clause <tt class="docutils literal"><span class="pre">a</span> <span class="pre"><=</span> <span class="pre">b</span></tt>.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.sql.operators.ColumnOperators.__lshift__">
<tt class="descname">__lshift__</tt><big>(</big><em>other</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.operators.ColumnOperators.__lshift__" title="Permalink to this definition">¶</a></dt>
<dd><p>implement the << operator.</p>
<p>Not used by SQLAlchemy core, this is provided
for custom operator systems which want to use
<< as an extension point.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.sql.operators.ColumnOperators.__lt__">
<tt class="descname">__lt__</tt><big>(</big><em>other</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.operators.ColumnOperators.__lt__" title="Permalink to this definition">¶</a></dt>
<dd><p>Implement the <tt class="docutils literal"><span class="pre"><</span></tt> operator.</p>
<p>In a column context, produces the clause <tt class="docutils literal"><span class="pre">a</span> <span class="pre"><</span> <span class="pre">b</span></tt>.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.sql.operators.ColumnOperators.__mod__">
<tt class="descname">__mod__</tt><big>(</big><em>other</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.operators.ColumnOperators.__mod__" title="Permalink to this definition">¶</a></dt>
<dd><p>Implement the <tt class="docutils literal"><span class="pre">%</span></tt> operator.</p>
<p>In a column context, produces the clause <tt class="docutils literal"><span class="pre">a</span> <span class="pre">%</span> <span class="pre">b</span></tt>.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.sql.operators.ColumnOperators.__mul__">
<tt class="descname">__mul__</tt><big>(</big><em>other</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.operators.ColumnOperators.__mul__" title="Permalink to this definition">¶</a></dt>
<dd><p>Implement the <tt class="docutils literal"><span class="pre">*</span></tt> operator.</p>
<p>In a column context, produces the clause <tt class="docutils literal"><span class="pre">a</span> <span class="pre">*</span> <span class="pre">b</span></tt>.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.sql.operators.ColumnOperators.__ne__">
<tt class="descname">__ne__</tt><big>(</big><em>other</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.operators.ColumnOperators.__ne__" title="Permalink to this definition">¶</a></dt>
<dd><p>Implement the <tt class="docutils literal"><span class="pre">!=</span></tt> operator.</p>
<p>In a column context, produces the clause <tt class="docutils literal"><span class="pre">a</span> <span class="pre">!=</span> <span class="pre">b</span></tt>.
If the target is <tt class="docutils literal"><span class="pre">None</span></tt>, produces <tt class="docutils literal"><span class="pre">a</span> <span class="pre">IS</span> <span class="pre">NOT</span> <span class="pre">NULL</span></tt>.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.sql.operators.ColumnOperators.__neg__">
<tt class="descname">__neg__</tt><big>(</big><big>)</big><a class="headerlink" href="#sqlalchemy.sql.operators.ColumnOperators.__neg__" title="Permalink to this definition">¶</a></dt>
<dd><p>Implement the <tt class="docutils literal"><span class="pre">-</span></tt> operator.</p>
<p>In a column context, produces the clause <tt class="docutils literal"><span class="pre">-a</span></tt>.</p>
</dd></dl>
<dl class="staticmethod">
<dt id="sqlalchemy.sql.operators.ColumnOperators.__new__">
<em class="property">static </em><tt class="descname">__new__</tt><big>(</big><em>S</em>, <em>...</em><big>)</big> → a new object with type S, a subtype of T<a class="headerlink" href="#sqlalchemy.sql.operators.ColumnOperators.__new__" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <tt class="xref py py-meth docutils literal"><span class="pre">__new__()</span></tt> <em>method of</em> <tt class="xref py py-class docutils literal"><span class="pre">object</span></tt></div>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.sql.operators.ColumnOperators.__or__">
<tt class="descname">__or__</tt><big>(</big><em>other</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.operators.ColumnOperators.__or__" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <a class="reference internal" href="#sqlalchemy.sql.operators.Operators.__or__" title="sqlalchemy.sql.operators.Operators.__or__"><tt class="xref py py-meth docutils literal"><span class="pre">__or__()</span></tt></a> <em>method of</em> <a class="reference internal" href="#sqlalchemy.sql.operators.Operators" title="sqlalchemy.sql.operators.Operators"><tt class="xref py py-class docutils literal"><span class="pre">Operators</span></tt></a></div>
<p>Implement the <tt class="docutils literal"><span class="pre">|</span></tt> operator.</p>
<p>When used with SQL expressions, results in an
OR operation, equivalent to
<a class="reference internal" href="#sqlalchemy.sql.expression.or_" title="sqlalchemy.sql.expression.or_"><tt class="xref py py-func docutils literal"><span class="pre">or_()</span></tt></a>, that is:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">a</span> <span class="o">|</span> <span class="n">b</span></pre></div>
</div>
<p>is equivalent to:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="kn">import</span> <span class="n">or_</span>
<span class="n">or_</span><span class="p">(</span><span class="n">a</span><span class="p">,</span> <span class="n">b</span><span class="p">)</span></pre></div>
</div>
<p>Care should be taken when using <tt class="docutils literal"><span class="pre">|</span></tt> regarding
operator precedence; the <tt class="docutils literal"><span class="pre">|</span></tt> operator has the highest precedence.
The operands should be enclosed in parenthesis if they contain
further sub expressions:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="p">(</span><span class="n">a</span> <span class="o">==</span> <span class="mi">2</span><span class="p">)</span> <span class="o">|</span> <span class="p">(</span><span class="n">b</span> <span class="o">==</span> <span class="mi">4</span><span class="p">)</span></pre></div>
</div>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.sql.operators.ColumnOperators.__radd__">
<tt class="descname">__radd__</tt><big>(</big><em>other</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.operators.ColumnOperators.__radd__" title="Permalink to this definition">¶</a></dt>
<dd><p>Implement the <tt class="docutils literal"><span class="pre">+</span></tt> operator in reverse.</p>
<p>See <a class="reference internal" href="#sqlalchemy.sql.operators.ColumnOperators.__add__" title="sqlalchemy.sql.operators.ColumnOperators.__add__"><tt class="xref py py-meth docutils literal"><span class="pre">ColumnOperators.__add__()</span></tt></a>.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.sql.operators.ColumnOperators.__rdiv__">
<tt class="descname">__rdiv__</tt><big>(</big><em>other</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.operators.ColumnOperators.__rdiv__" title="Permalink to this definition">¶</a></dt>
<dd><p>Implement the <tt class="docutils literal"><span class="pre">/</span></tt> operator in reverse.</p>
<p>See <a class="reference internal" href="#sqlalchemy.sql.operators.ColumnOperators.__div__" title="sqlalchemy.sql.operators.ColumnOperators.__div__"><tt class="xref py py-meth docutils literal"><span class="pre">ColumnOperators.__div__()</span></tt></a>.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.sql.operators.ColumnOperators.__reduce__">
<tt class="descname">__reduce__</tt><big>(</big><big>)</big><a class="headerlink" href="#sqlalchemy.sql.operators.ColumnOperators.__reduce__" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <tt class="xref py py-meth docutils literal"><span class="pre">__reduce__()</span></tt> <em>method of</em> <tt class="xref py py-class docutils literal"><span class="pre">object</span></tt></div>
<p>helper for pickle</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.sql.operators.ColumnOperators.__reduce_ex__">
<tt class="descname">__reduce_ex__</tt><big>(</big><big>)</big><a class="headerlink" href="#sqlalchemy.sql.operators.ColumnOperators.__reduce_ex__" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <tt class="xref py py-meth docutils literal"><span class="pre">__reduce_ex__()</span></tt> <em>method of</em> <tt class="xref py py-class docutils literal"><span class="pre">object</span></tt></div>
<p>helper for pickle</p>
</dd></dl>
<dl class="attribute">
<dt id="sqlalchemy.sql.operators.ColumnOperators.__repr__">
<tt class="descname">__repr__</tt><a class="headerlink" href="#sqlalchemy.sql.operators.ColumnOperators.__repr__" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <tt class="xref py py-attr docutils literal"><span class="pre">__repr__</span></tt> <em>attribute of</em> <tt class="xref py py-class docutils literal"><span class="pre">object</span></tt></div>
<p>x.__repr__() <==> repr(x)</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.sql.operators.ColumnOperators.__rmul__">
<tt class="descname">__rmul__</tt><big>(</big><em>other</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.operators.ColumnOperators.__rmul__" title="Permalink to this definition">¶</a></dt>
<dd><p>Implement the <tt class="docutils literal"><span class="pre">*</span></tt> operator in reverse.</p>
<p>See <a class="reference internal" href="#sqlalchemy.sql.operators.ColumnOperators.__mul__" title="sqlalchemy.sql.operators.ColumnOperators.__mul__"><tt class="xref py py-meth docutils literal"><span class="pre">ColumnOperators.__mul__()</span></tt></a>.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.sql.operators.ColumnOperators.__rshift__">
<tt class="descname">__rshift__</tt><big>(</big><em>other</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.operators.ColumnOperators.__rshift__" title="Permalink to this definition">¶</a></dt>
<dd><p>implement the >> operator.</p>
<p>Not used by SQLAlchemy core, this is provided
for custom operator systems which want to use
>> as an extension point.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.sql.operators.ColumnOperators.__rsub__">
<tt class="descname">__rsub__</tt><big>(</big><em>other</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.operators.ColumnOperators.__rsub__" title="Permalink to this definition">¶</a></dt>
<dd><p>Implement the <tt class="docutils literal"><span class="pre">-</span></tt> operator in reverse.</p>
<p>See <a class="reference internal" href="#sqlalchemy.sql.operators.ColumnOperators.__sub__" title="sqlalchemy.sql.operators.ColumnOperators.__sub__"><tt class="xref py py-meth docutils literal"><span class="pre">ColumnOperators.__sub__()</span></tt></a>.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.sql.operators.ColumnOperators.__rtruediv__">
<tt class="descname">__rtruediv__</tt><big>(</big><em>other</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.operators.ColumnOperators.__rtruediv__" title="Permalink to this definition">¶</a></dt>
<dd><p>Implement the <tt class="docutils literal"><span class="pre">//</span></tt> operator in reverse.</p>
<p>See <a class="reference internal" href="#sqlalchemy.sql.operators.ColumnOperators.__truediv__" title="sqlalchemy.sql.operators.ColumnOperators.__truediv__"><tt class="xref py py-meth docutils literal"><span class="pre">ColumnOperators.__truediv__()</span></tt></a>.</p>
</dd></dl>
<dl class="attribute">
<dt id="sqlalchemy.sql.operators.ColumnOperators.__setattr__">
<tt class="descname">__setattr__</tt><a class="headerlink" href="#sqlalchemy.sql.operators.ColumnOperators.__setattr__" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <tt class="xref py py-attr docutils literal"><span class="pre">__setattr__</span></tt> <em>attribute of</em> <tt class="xref py py-class docutils literal"><span class="pre">object</span></tt></div>
<p>x.__setattr__(‘name’, value) <==> x.name = value</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.sql.operators.ColumnOperators.__sizeof__">
<tt class="descname">__sizeof__</tt><big>(</big><big>)</big> → int<a class="headerlink" href="#sqlalchemy.sql.operators.ColumnOperators.__sizeof__" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <tt class="xref py py-meth docutils literal"><span class="pre">__sizeof__()</span></tt> <em>method of</em> <tt class="xref py py-class docutils literal"><span class="pre">object</span></tt></div>
<p>size of object in memory, in bytes</p>
</dd></dl>
<dl class="attribute">
<dt id="sqlalchemy.sql.operators.ColumnOperators.__str__">
<tt class="descname">__str__</tt><a class="headerlink" href="#sqlalchemy.sql.operators.ColumnOperators.__str__" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <tt class="xref py py-attr docutils literal"><span class="pre">__str__</span></tt> <em>attribute of</em> <tt class="xref py py-class docutils literal"><span class="pre">object</span></tt></div>
<p>x.__str__() <==> str(x)</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.sql.operators.ColumnOperators.__sub__">
<tt class="descname">__sub__</tt><big>(</big><em>other</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.operators.ColumnOperators.__sub__" title="Permalink to this definition">¶</a></dt>
<dd><p>Implement the <tt class="docutils literal"><span class="pre">-</span></tt> operator.</p>
<p>In a column context, produces the clause <tt class="docutils literal"><span class="pre">a</span> <span class="pre">-</span> <span class="pre">b</span></tt>.</p>
</dd></dl>
<dl class="staticmethod">
<dt id="sqlalchemy.sql.operators.ColumnOperators.__subclasshook__">
<em class="property">static </em><tt class="descname">__subclasshook__</tt><big>(</big><big>)</big><a class="headerlink" href="#sqlalchemy.sql.operators.ColumnOperators.__subclasshook__" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <tt class="xref py py-meth docutils literal"><span class="pre">__subclasshook__()</span></tt> <em>method of</em> <tt class="xref py py-class docutils literal"><span class="pre">object</span></tt></div>
<p>Abstract classes can override this to customize issubclass().</p>
<p>This is invoked early on by abc.ABCMeta.__subclasscheck__().
It should return True, False or NotImplemented. If it returns
NotImplemented, the normal algorithm is used. Otherwise, it
overrides the normal algorithm (and the outcome is cached).</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.sql.operators.ColumnOperators.__truediv__">
<tt class="descname">__truediv__</tt><big>(</big><em>other</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.operators.ColumnOperators.__truediv__" title="Permalink to this definition">¶</a></dt>
<dd><p>Implement the <tt class="docutils literal"><span class="pre">//</span></tt> operator.</p>
<p>In a column context, produces the clause <tt class="docutils literal"><span class="pre">a</span> <span class="pre">/</span> <span class="pre">b</span></tt>.</p>
</dd></dl>
<dl class="attribute">
<dt id="sqlalchemy.sql.operators.ColumnOperators.__weakref__">
<tt class="descname">__weakref__</tt><a class="headerlink" href="#sqlalchemy.sql.operators.ColumnOperators.__weakref__" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <a class="reference internal" href="#sqlalchemy.sql.operators.Operators.__weakref__" title="sqlalchemy.sql.operators.Operators.__weakref__"><tt class="xref py py-attr docutils literal"><span class="pre">__weakref__</span></tt></a> <em>attribute of</em> <a class="reference internal" href="#sqlalchemy.sql.operators.Operators" title="sqlalchemy.sql.operators.Operators"><tt class="xref py py-class docutils literal"><span class="pre">Operators</span></tt></a></div>
<p>list of weak references to the object (if defined)</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.sql.operators.ColumnOperators.asc">
<tt class="descname">asc</tt><big>(</big><big>)</big><a class="headerlink" href="#sqlalchemy.sql.operators.ColumnOperators.asc" title="Permalink to this definition">¶</a></dt>
<dd><p>Produce a <a class="reference internal" href="#sqlalchemy.sql.expression.asc" title="sqlalchemy.sql.expression.asc"><tt class="xref py py-func docutils literal"><span class="pre">asc()</span></tt></a> clause against the
parent object.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.sql.operators.ColumnOperators.between">
<tt class="descname">between</tt><big>(</big><em>cleft</em>, <em>cright</em>, <em>symmetric=False</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.operators.ColumnOperators.between" title="Permalink to this definition">¶</a></dt>
<dd><p>Produce a <a class="reference internal" href="#sqlalchemy.sql.expression.between" title="sqlalchemy.sql.expression.between"><tt class="xref py py-func docutils literal"><span class="pre">between()</span></tt></a> clause against
the parent object, given the lower and upper range.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.sql.operators.ColumnOperators.collate">
<tt class="descname">collate</tt><big>(</big><em>collation</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.operators.ColumnOperators.collate" title="Permalink to this definition">¶</a></dt>
<dd><p>Produce a <a class="reference internal" href="#sqlalchemy.sql.expression.collate" title="sqlalchemy.sql.expression.collate"><tt class="xref py py-func docutils literal"><span class="pre">collate()</span></tt></a> clause against
the parent object, given the collation string.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.sql.operators.ColumnOperators.concat">
<tt class="descname">concat</tt><big>(</big><em>other</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.operators.ColumnOperators.concat" title="Permalink to this definition">¶</a></dt>
<dd><p>Implement the ‘concat’ operator.</p>
<p>In a column context, produces the clause <tt class="docutils literal"><span class="pre">a</span> <span class="pre">||</span> <span class="pre">b</span></tt>,
or uses the <tt class="docutils literal"><span class="pre">concat()</span></tt> operator on MySQL.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.sql.operators.ColumnOperators.contains">
<tt class="descname">contains</tt><big>(</big><em>other</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.operators.ColumnOperators.contains" title="Permalink to this definition">¶</a></dt>
<dd><p>Implement the ‘contains’ operator.</p>
<p>In a column context, produces the clause <tt class="docutils literal"><span class="pre">LIKE</span> <span class="pre">'%<other>%'</span></tt></p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.sql.operators.ColumnOperators.desc">
<tt class="descname">desc</tt><big>(</big><big>)</big><a class="headerlink" href="#sqlalchemy.sql.operators.ColumnOperators.desc" title="Permalink to this definition">¶</a></dt>
<dd><p>Produce a <a class="reference internal" href="#sqlalchemy.sql.expression.desc" title="sqlalchemy.sql.expression.desc"><tt class="xref py py-func docutils literal"><span class="pre">desc()</span></tt></a> clause against the
parent object.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.sql.operators.ColumnOperators.distinct">
<tt class="descname">distinct</tt><big>(</big><big>)</big><a class="headerlink" href="#sqlalchemy.sql.operators.ColumnOperators.distinct" title="Permalink to this definition">¶</a></dt>
<dd><p>Produce a <a class="reference internal" href="#sqlalchemy.sql.expression.distinct" title="sqlalchemy.sql.expression.distinct"><tt class="xref py py-func docutils literal"><span class="pre">distinct()</span></tt></a> clause against the
parent object.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.sql.operators.ColumnOperators.endswith">
<tt class="descname">endswith</tt><big>(</big><em>other</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.operators.ColumnOperators.endswith" title="Permalink to this definition">¶</a></dt>
<dd><p>Implement the ‘endswith’ operator.</p>
<p>In a column context, produces the clause <tt class="docutils literal"><span class="pre">LIKE</span> <span class="pre">'%<other>'</span></tt></p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.sql.operators.ColumnOperators.ilike">
<tt class="descname">ilike</tt><big>(</big><em>other</em>, <em>escape=None</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.operators.ColumnOperators.ilike" title="Permalink to this definition">¶</a></dt>
<dd><p>Implement the <tt class="docutils literal"><span class="pre">ilike</span></tt> operator.</p>
<p>In a column context, produces the clause <tt class="docutils literal"><span class="pre">a</span> <span class="pre">ILIKE</span> <span class="pre">other</span></tt>.</p>
<p>E.g.:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">select</span><span class="p">([</span><span class="n">sometable</span><span class="p">])</span><span class="o">.</span><span class="n">where</span><span class="p">(</span><span class="n">sometable</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">column</span><span class="o">.</span><span class="n">ilike</span><span class="p">(</span><span class="s">"</span><span class="si">%f</span><span class="s">oobar%"</span><span class="p">))</span></pre></div>
</div>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><span class="target" id="sqlalchemy.sql.operators.ColumnOperators.ilike.params.other"></span><strong>other</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.operators.ColumnOperators.ilike.params.other">¶</a> – expression to be compared</li>
<li><span class="target" id="sqlalchemy.sql.operators.ColumnOperators.ilike.params.escape"></span><strong>escape</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.operators.ColumnOperators.ilike.params.escape">¶</a> – <p>optional escape character, renders the <tt class="docutils literal"><span class="pre">ESCAPE</span></tt>
keyword, e.g.:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">somecolumn</span><span class="o">.</span><span class="n">ilike</span><span class="p">(</span><span class="s">"foo/%bar"</span><span class="p">,</span> <span class="n">escape</span><span class="o">=</span><span class="s">"/"</span><span class="p">)</span></pre></div>
</div>
</li>
</ul>
</td>
</tr>
</tbody>
</table>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p class="last"><a class="reference internal" href="#sqlalchemy.sql.operators.ColumnOperators.like" title="sqlalchemy.sql.operators.ColumnOperators.like"><tt class="xref py py-meth docutils literal"><span class="pre">ColumnOperators.like()</span></tt></a></p>
</div>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.sql.operators.ColumnOperators.in_">
<tt class="descname">in_</tt><big>(</big><em>other</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.operators.ColumnOperators.in_" title="Permalink to this definition">¶</a></dt>
<dd><p>Implement the <tt class="docutils literal"><span class="pre">in</span></tt> operator.</p>
<p>In a column context, produces the clause <tt class="docutils literal"><span class="pre">a</span> <span class="pre">IN</span> <span class="pre">other</span></tt>.
“other” may be a tuple/list of column expressions,
or a <a class="reference internal" href="selectable.html#sqlalchemy.sql.expression.select" title="sqlalchemy.sql.expression.select"><tt class="xref py py-func docutils literal"><span class="pre">select()</span></tt></a> construct.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.sql.operators.ColumnOperators.is_">
<tt class="descname">is_</tt><big>(</big><em>other</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.operators.ColumnOperators.is_" title="Permalink to this definition">¶</a></dt>
<dd><p>Implement the <tt class="docutils literal"><span class="pre">IS</span></tt> operator.</p>
<p>Normally, <tt class="docutils literal"><span class="pre">IS</span></tt> is generated automatically when comparing to a
value of <tt class="docutils literal"><span class="pre">None</span></tt>, which resolves to <tt class="docutils literal"><span class="pre">NULL</span></tt>. However, explicit
usage of <tt class="docutils literal"><span class="pre">IS</span></tt> may be desirable if comparing to boolean values
on certain platforms.</p>
<div class="versionadded">
<p><span>New in version 0.7.9.</span></p>
</div>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p class="last"><a class="reference internal" href="#sqlalchemy.sql.operators.ColumnOperators.isnot" title="sqlalchemy.sql.operators.ColumnOperators.isnot"><tt class="xref py py-meth docutils literal"><span class="pre">ColumnOperators.isnot()</span></tt></a></p>
</div>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.sql.operators.ColumnOperators.isnot">
<tt class="descname">isnot</tt><big>(</big><em>other</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.operators.ColumnOperators.isnot" title="Permalink to this definition">¶</a></dt>
<dd><p>Implement the <tt class="docutils literal"><span class="pre">IS</span> <span class="pre">NOT</span></tt> operator.</p>
<p>Normally, <tt class="docutils literal"><span class="pre">IS</span> <span class="pre">NOT</span></tt> is generated automatically when comparing to a
value of <tt class="docutils literal"><span class="pre">None</span></tt>, which resolves to <tt class="docutils literal"><span class="pre">NULL</span></tt>. However, explicit
usage of <tt class="docutils literal"><span class="pre">IS</span> <span class="pre">NOT</span></tt> may be desirable if comparing to boolean values
on certain platforms.</p>
<div class="versionadded">
<p><span>New in version 0.7.9.</span></p>
</div>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p class="last"><a class="reference internal" href="#sqlalchemy.sql.operators.ColumnOperators.is_" title="sqlalchemy.sql.operators.ColumnOperators.is_"><tt class="xref py py-meth docutils literal"><span class="pre">ColumnOperators.is_()</span></tt></a></p>
</div>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.sql.operators.ColumnOperators.like">
<tt class="descname">like</tt><big>(</big><em>other</em>, <em>escape=None</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.operators.ColumnOperators.like" title="Permalink to this definition">¶</a></dt>
<dd><p>Implement the <tt class="docutils literal"><span class="pre">like</span></tt> operator.</p>
<p>In a column context, produces the clause <tt class="docutils literal"><span class="pre">a</span> <span class="pre">LIKE</span> <span class="pre">other</span></tt>.</p>
<p>E.g.:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">select</span><span class="p">([</span><span class="n">sometable</span><span class="p">])</span><span class="o">.</span><span class="n">where</span><span class="p">(</span><span class="n">sometable</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">column</span><span class="o">.</span><span class="n">like</span><span class="p">(</span><span class="s">"</span><span class="si">%f</span><span class="s">oobar%"</span><span class="p">))</span></pre></div>
</div>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><span class="target" id="sqlalchemy.sql.operators.ColumnOperators.like.params.other"></span><strong>other</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.operators.ColumnOperators.like.params.other">¶</a> – expression to be compared</li>
<li><span class="target" id="sqlalchemy.sql.operators.ColumnOperators.like.params.escape"></span><strong>escape</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.operators.ColumnOperators.like.params.escape">¶</a> – <p>optional escape character, renders the <tt class="docutils literal"><span class="pre">ESCAPE</span></tt>
keyword, e.g.:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">somecolumn</span><span class="o">.</span><span class="n">like</span><span class="p">(</span><span class="s">"foo/%bar"</span><span class="p">,</span> <span class="n">escape</span><span class="o">=</span><span class="s">"/"</span><span class="p">)</span></pre></div>
</div>
</li>
</ul>
</td>
</tr>
</tbody>
</table>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p class="last"><a class="reference internal" href="#sqlalchemy.sql.operators.ColumnOperators.ilike" title="sqlalchemy.sql.operators.ColumnOperators.ilike"><tt class="xref py py-meth docutils literal"><span class="pre">ColumnOperators.ilike()</span></tt></a></p>
</div>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.sql.operators.ColumnOperators.match">
<tt class="descname">match</tt><big>(</big><em>other</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.operators.ColumnOperators.match" title="Permalink to this definition">¶</a></dt>
<dd><p>Implements a database-specific ‘match’ operator.</p>
<p><a class="reference internal" href="#sqlalchemy.sql.operators.ColumnOperators.match" title="sqlalchemy.sql.operators.ColumnOperators.match"><tt class="xref py py-meth docutils literal"><span class="pre">match()</span></tt></a> attempts to resolve to
a MATCH-like function or operator provided by the backend.
Examples include:</p>
<ul class="simple">
<li>Postgresql - renders <tt class="docutils literal"><span class="pre">x</span> <span class="pre">@@</span> <span class="pre">to_tsquery(y)</span></tt></li>
<li>MySQL - renders <tt class="docutils literal"><span class="pre">MATCH</span> <span class="pre">(x)</span> <span class="pre">AGAINST</span> <span class="pre">(y</span> <span class="pre">IN</span> <span class="pre">BOOLEAN</span> <span class="pre">MODE)</span></tt></li>
<li>Oracle - renders <tt class="docutils literal"><span class="pre">CONTAINS(x,</span> <span class="pre">y)</span></tt></li>
<li>other backends may provide special implementations;
some backends such as SQLite have no support.</li>
</ul>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.sql.operators.ColumnOperators.notilike">
<tt class="descname">notilike</tt><big>(</big><em>other</em>, <em>escape=None</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.operators.ColumnOperators.notilike" title="Permalink to this definition">¶</a></dt>
<dd><p>implement the <tt class="docutils literal"><span class="pre">NOT</span> <span class="pre">ILIKE</span></tt> operator.</p>
<p>This is equivalent to using negation with
<a class="reference internal" href="#sqlalchemy.sql.operators.ColumnOperators.ilike" title="sqlalchemy.sql.operators.ColumnOperators.ilike"><tt class="xref py py-meth docutils literal"><span class="pre">ColumnOperators.ilike()</span></tt></a>, i.e. <tt class="docutils literal"><span class="pre">~x.ilike(y)</span></tt>.</p>
<div class="versionadded">
<p><span>New in version 0.8.</span></p>
</div>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p class="last"><a class="reference internal" href="#sqlalchemy.sql.operators.ColumnOperators.ilike" title="sqlalchemy.sql.operators.ColumnOperators.ilike"><tt class="xref py py-meth docutils literal"><span class="pre">ColumnOperators.ilike()</span></tt></a></p>
</div>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.sql.operators.ColumnOperators.notin_">
<tt class="descname">notin_</tt><big>(</big><em>other</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.operators.ColumnOperators.notin_" title="Permalink to this definition">¶</a></dt>
<dd><p>implement the <tt class="docutils literal"><span class="pre">NOT</span> <span class="pre">IN</span></tt> operator.</p>
<p>This is equivalent to using negation with
<a class="reference internal" href="#sqlalchemy.sql.operators.ColumnOperators.in_" title="sqlalchemy.sql.operators.ColumnOperators.in_"><tt class="xref py py-meth docutils literal"><span class="pre">ColumnOperators.in_()</span></tt></a>, i.e. <tt class="docutils literal"><span class="pre">~x.in_(y)</span></tt>.</p>
<div class="versionadded">
<p><span>New in version 0.8.</span></p>
</div>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p class="last"><a class="reference internal" href="#sqlalchemy.sql.operators.ColumnOperators.in_" title="sqlalchemy.sql.operators.ColumnOperators.in_"><tt class="xref py py-meth docutils literal"><span class="pre">ColumnOperators.in_()</span></tt></a></p>
</div>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.sql.operators.ColumnOperators.notlike">
<tt class="descname">notlike</tt><big>(</big><em>other</em>, <em>escape=None</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.operators.ColumnOperators.notlike" title="Permalink to this definition">¶</a></dt>
<dd><p>implement the <tt class="docutils literal"><span class="pre">NOT</span> <span class="pre">LIKE</span></tt> operator.</p>
<p>This is equivalent to using negation with
<a class="reference internal" href="#sqlalchemy.sql.operators.ColumnOperators.like" title="sqlalchemy.sql.operators.ColumnOperators.like"><tt class="xref py py-meth docutils literal"><span class="pre">ColumnOperators.like()</span></tt></a>, i.e. <tt class="docutils literal"><span class="pre">~x.like(y)</span></tt>.</p>
<div class="versionadded">
<p><span>New in version 0.8.</span></p>
</div>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p class="last"><a class="reference internal" href="#sqlalchemy.sql.operators.ColumnOperators.like" title="sqlalchemy.sql.operators.ColumnOperators.like"><tt class="xref py py-meth docutils literal"><span class="pre">ColumnOperators.like()</span></tt></a></p>
</div>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.sql.operators.ColumnOperators.nullsfirst">
<tt class="descname">nullsfirst</tt><big>(</big><big>)</big><a class="headerlink" href="#sqlalchemy.sql.operators.ColumnOperators.nullsfirst" title="Permalink to this definition">¶</a></dt>
<dd><p>Produce a <a class="reference internal" href="#sqlalchemy.sql.expression.nullsfirst" title="sqlalchemy.sql.expression.nullsfirst"><tt class="xref py py-func docutils literal"><span class="pre">nullsfirst()</span></tt></a> clause against the
parent object.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.sql.operators.ColumnOperators.nullslast">
<tt class="descname">nullslast</tt><big>(</big><big>)</big><a class="headerlink" href="#sqlalchemy.sql.operators.ColumnOperators.nullslast" title="Permalink to this definition">¶</a></dt>
<dd><p>Produce a <a class="reference internal" href="#sqlalchemy.sql.expression.nullslast" title="sqlalchemy.sql.expression.nullslast"><tt class="xref py py-func docutils literal"><span class="pre">nullslast()</span></tt></a> clause against the
parent object.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.sql.operators.ColumnOperators.op">
<tt class="descname">op</tt><big>(</big><em>opstring</em>, <em>precedence=0</em>, <em>is_comparison=False</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.operators.ColumnOperators.op" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <a class="reference internal" href="#sqlalchemy.sql.operators.Operators.op" title="sqlalchemy.sql.operators.Operators.op"><tt class="xref py py-meth docutils literal"><span class="pre">op()</span></tt></a> <em>method of</em> <a class="reference internal" href="#sqlalchemy.sql.operators.Operators" title="sqlalchemy.sql.operators.Operators"><tt class="xref py py-class docutils literal"><span class="pre">Operators</span></tt></a></div>
<p>produce a generic operator function.</p>
<p>e.g.:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">somecolumn</span><span class="o">.</span><span class="n">op</span><span class="p">(</span><span class="s">"*"</span><span class="p">)(</span><span class="mi">5</span><span class="p">)</span></pre></div>
</div>
<p>produces:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">somecolumn</span> <span class="o">*</span> <span class="mi">5</span></pre></div>
</div>
<p>This function can also be used to make bitwise operators explicit. For
example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">somecolumn</span><span class="o">.</span><span class="n">op</span><span class="p">(</span><span class="s">'&'</span><span class="p">)(</span><span class="mh">0xff</span><span class="p">)</span></pre></div>
</div>
<p>is a bitwise AND of the value in <tt class="docutils literal"><span class="pre">somecolumn</span></tt>.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><span class="target" id="sqlalchemy.sql.operators.ColumnOperators.op.params.operator"></span><strong>operator</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.operators.ColumnOperators.op.params.operator">¶</a> – a string which will be output as the infix operator
between this element and the expression passed to the
generated function.</li>
<li><span class="target" id="sqlalchemy.sql.operators.ColumnOperators.op.params.precedence"></span><strong>precedence</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.operators.ColumnOperators.op.params.precedence">¶</a> – <p>precedence to apply to the operator, when
parenthesizing expressions. A lower number will cause the expression
to be parenthesized when applied against another operator with
higher precedence. The default value of <tt class="docutils literal"><span class="pre">0</span></tt> is lower than all
operators except for the comma (<tt class="docutils literal"><span class="pre">,</span></tt>) and <tt class="docutils literal"><span class="pre">AS</span></tt> operators.
A value of 100 will be higher or equal to all operators, and -100
will be lower than or equal to all operators.</p>
<div class="versionadded">
<p><span>New in version 0.8: </span>- added the ‘precedence’ argument.</p>
</div>
</li>
<li><span class="target" id="sqlalchemy.sql.operators.ColumnOperators.op.params.is_comparison"></span><strong>is_comparison</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.operators.ColumnOperators.op.params.is_comparison">¶</a> – <p>if True, the operator will be considered as a
“comparison” operator, that is which evaulates to a boolean
true/false value, like <tt class="docutils literal"><span class="pre">==</span></tt>, <tt class="docutils literal"><span class="pre">></span></tt>, etc. This flag should be set
so that ORM relationships can establish that the operator is a
comparison operator when used in a custom join condition.</p>
<div class="versionadded">
<p><span>New in version 0.9.2: </span>- added the
<a class="reference internal" href="#sqlalchemy.sql.operators.Operators.op.params.is_comparison" title="sqlalchemy.sql.operators.Operators.op"><tt class="xref py py-paramref docutils literal"><span class="pre">Operators.op.is_comparison</span></tt></a> flag.</p>
</div>
</li>
</ul>
</td>
</tr>
</tbody>
</table>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p><a class="reference internal" href="types.html#types-operators"><em>Redefining and Creating New Operators</em></a></p>
<p class="last"><a class="reference internal" href="../orm/relationships.html#relationship-custom-operator"><em>Using custom operators in join conditions</em></a></p>
</div>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.sql.operators.ColumnOperators.operate">
<tt class="descname">operate</tt><big>(</big><em>op</em>, <em>*other</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.operators.ColumnOperators.operate" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <a class="reference internal" href="#sqlalchemy.sql.operators.Operators.operate" title="sqlalchemy.sql.operators.Operators.operate"><tt class="xref py py-meth docutils literal"><span class="pre">operate()</span></tt></a> <em>method of</em> <a class="reference internal" href="#sqlalchemy.sql.operators.Operators" title="sqlalchemy.sql.operators.Operators"><tt class="xref py py-class docutils literal"><span class="pre">Operators</span></tt></a></div>
<p>Operate on an argument.</p>
<p>This is the lowest level of operation, raises
<tt class="xref py py-class docutils literal"><span class="pre">NotImplementedError</span></tt> by default.</p>
<p>Overriding this on a subclass can allow common
behavior to be applied to all operations.
For example, overriding <a class="reference internal" href="#sqlalchemy.sql.operators.ColumnOperators" title="sqlalchemy.sql.operators.ColumnOperators"><tt class="xref py py-class docutils literal"><span class="pre">ColumnOperators</span></tt></a>
to apply <tt class="docutils literal"><span class="pre">func.lower()</span></tt> to the left and right
side:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">class</span> <span class="nc">MyComparator</span><span class="p">(</span><span class="n">ColumnOperators</span><span class="p">):</span>
<span class="k">def</span> <span class="nf">operate</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">op</span><span class="p">,</span> <span class="n">other</span><span class="p">):</span>
<span class="k">return</span> <span class="n">op</span><span class="p">(</span><span class="n">func</span><span class="o">.</span><span class="n">lower</span><span class="p">(</span><span class="bp">self</span><span class="p">),</span> <span class="n">func</span><span class="o">.</span><span class="n">lower</span><span class="p">(</span><span class="n">other</span><span class="p">))</span></pre></div>
</div>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><span class="target" id="sqlalchemy.sql.operators.ColumnOperators.operate.params.op"></span><strong>op</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.operators.ColumnOperators.operate.params.op">¶</a> – Operator callable.</li>
<li><span class="target" id="sqlalchemy.sql.operators.ColumnOperators.operate.params.*other"></span><strong>*other</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.operators.ColumnOperators.operate.params.*other">¶</a> – the ‘other’ side of the operation. Will
be a single scalar for most operations.</li>
<li><span class="target" id="sqlalchemy.sql.operators.ColumnOperators.operate.params.**kwargs"></span><strong>**kwargs</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.operators.ColumnOperators.operate.params.**kwargs">¶</a> – modifiers. These may be passed by special
operators such as <tt class="xref py py-meth docutils literal"><span class="pre">ColumnOperators.contains()</span></tt>.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.sql.operators.ColumnOperators.reverse_operate">
<tt class="descname">reverse_operate</tt><big>(</big><em>op</em>, <em>other</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.operators.ColumnOperators.reverse_operate" title="Permalink to this definition">¶</a></dt>
<dd><div class="inherited-member container">
<em>inherited from the</em> <a class="reference internal" href="#sqlalchemy.sql.operators.Operators.reverse_operate" title="sqlalchemy.sql.operators.Operators.reverse_operate"><tt class="xref py py-meth docutils literal"><span class="pre">reverse_operate()</span></tt></a> <em>method of</em> <a class="reference internal" href="#sqlalchemy.sql.operators.Operators" title="sqlalchemy.sql.operators.Operators"><tt class="xref py py-class docutils literal"><span class="pre">Operators</span></tt></a></div>
<p>Reverse operate on an argument.</p>
<p>Usage is the same as <tt class="xref py py-meth docutils literal"><span class="pre">operate()</span></tt>.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.sql.operators.ColumnOperators.startswith">
<tt class="descname">startswith</tt><big>(</big><em>other</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.operators.ColumnOperators.startswith" title="Permalink to this definition">¶</a></dt>
<dd><p>Implement the <tt class="docutils literal"><span class="pre">startwith</span></tt> operator.</p>
<p>In a column context, produces the clause <tt class="docutils literal"><span class="pre">LIKE</span> <span class="pre">'<other>%'</span></tt></p>
</dd></dl>
<dl class="attribute">
<dt id="sqlalchemy.sql.operators.ColumnOperators.timetuple">
<tt class="descname">timetuple</tt><em class="property"> = None</em><a class="headerlink" href="#sqlalchemy.sql.operators.ColumnOperators.timetuple" title="Permalink to this definition">¶</a></dt>
<dd><p>Hack, allows datetime objects to be compared on the LHS.</p>
</dd></dl>
</dd></dl>
<dl class="class">
<dt id="sqlalchemy.sql.base.DialectKWArgs">
<em class="property">class </em><tt class="descclassname">sqlalchemy.sql.base.</tt><tt class="descname">DialectKWArgs</tt><a class="headerlink" href="#sqlalchemy.sql.base.DialectKWArgs" title="Permalink to this definition">¶</a></dt>
<dd><p>Establish the ability for a class to have dialect-specific arguments
with defaults and constructor validation.</p>
<p>The <a class="reference internal" href="#sqlalchemy.sql.base.DialectKWArgs" title="sqlalchemy.sql.base.DialectKWArgs"><tt class="xref py py-class docutils literal"><span class="pre">DialectKWArgs</span></tt></a> interacts with the
<a class="reference internal" href="internals.html#sqlalchemy.engine.default.DefaultDialect.construct_arguments" title="sqlalchemy.engine.default.DefaultDialect.construct_arguments"><tt class="xref py py-attr docutils literal"><span class="pre">DefaultDialect.construct_arguments</span></tt></a> present on a dialect.</p>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p class="last"><a class="reference internal" href="internals.html#sqlalchemy.engine.default.DefaultDialect.construct_arguments" title="sqlalchemy.engine.default.DefaultDialect.construct_arguments"><tt class="xref py py-attr docutils literal"><span class="pre">DefaultDialect.construct_arguments</span></tt></a></p>
</div>
<dl class="classmethod">
<dt id="sqlalchemy.sql.base.DialectKWArgs.argument_for">
<em class="property">classmethod </em><tt class="descname">argument_for</tt><big>(</big><em>dialect_name</em>, <em>argument_name</em>, <em>default</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.base.DialectKWArgs.argument_for" title="Permalink to this definition">¶</a></dt>
<dd><p>Add a new kind of dialect-specific keyword argument for this class.</p>
<p>E.g.:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">Index</span><span class="o">.</span><span class="n">argument_for</span><span class="p">(</span><span class="s">"mydialect"</span><span class="p">,</span> <span class="s">"length"</span><span class="p">,</span> <span class="bp">None</span><span class="p">)</span>
<span class="n">some_index</span> <span class="o">=</span> <span class="n">Index</span><span class="p">(</span><span class="s">'a'</span><span class="p">,</span> <span class="s">'b'</span><span class="p">,</span> <span class="n">mydialect_length</span><span class="o">=</span><span class="mi">5</span><span class="p">)</span></pre></div>
</div>
<p>The <a class="reference internal" href="#sqlalchemy.sql.base.DialectKWArgs.argument_for" title="sqlalchemy.sql.base.DialectKWArgs.argument_for"><tt class="xref py py-meth docutils literal"><span class="pre">DialectKWArgs.argument_for()</span></tt></a> method is a per-argument
way adding extra arguments to the
<a class="reference internal" href="internals.html#sqlalchemy.engine.default.DefaultDialect.construct_arguments" title="sqlalchemy.engine.default.DefaultDialect.construct_arguments"><tt class="xref py py-attr docutils literal"><span class="pre">DefaultDialect.construct_arguments</span></tt></a> dictionary. This
dictionary provides a list of argument names accepted by various
schema-level constructs on behalf of a dialect.</p>
<p>New dialects should typically specify this dictionary all at once as a
data member of the dialect class. The use case for ad-hoc addition of
argument names is typically for end-user code that is also using
a custom compilation scheme which consumes the additional arguments.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><span class="target" id="sqlalchemy.sql.base.DialectKWArgs.argument_for.params.dialect_name"></span><strong>dialect_name</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.base.DialectKWArgs.argument_for.params.dialect_name">¶</a> – name of a dialect. The dialect must be
locatable, else a <tt class="xref py py-class docutils literal"><span class="pre">NoSuchModuleError</span></tt> is raised. The
dialect must also include an existing
<a class="reference internal" href="internals.html#sqlalchemy.engine.default.DefaultDialect.construct_arguments" title="sqlalchemy.engine.default.DefaultDialect.construct_arguments"><tt class="xref py py-attr docutils literal"><span class="pre">DefaultDialect.construct_arguments</span></tt></a> collection, indicating
that it participates in the keyword-argument validation and default
system, else <tt class="xref py py-class docutils literal"><span class="pre">ArgumentError</span></tt> is raised. If the dialect does
not include this collection, then any keyword argument can be
specified on behalf of this dialect already. All dialects packaged
within SQLAlchemy include this collection, however for third party
dialects, support may vary.</li>
<li><span class="target" id="sqlalchemy.sql.base.DialectKWArgs.argument_for.params.argument_name"></span><strong>argument_name</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.base.DialectKWArgs.argument_for.params.argument_name">¶</a> – name of the parameter.</li>
<li><span class="target" id="sqlalchemy.sql.base.DialectKWArgs.argument_for.params.default"></span><strong>default</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.base.DialectKWArgs.argument_for.params.default">¶</a> – default value of the parameter.</li>
</ul>
</td>
</tr>
</tbody>
</table>
<div class="versionadded">
<p><span>New in version 0.9.4.</span></p>
</div>
</dd></dl>
<dl class="attribute">
<dt id="sqlalchemy.sql.base.DialectKWArgs.dialect_kwargs">
<tt class="descname">dialect_kwargs</tt><a class="headerlink" href="#sqlalchemy.sql.base.DialectKWArgs.dialect_kwargs" title="Permalink to this definition">¶</a></dt>
<dd><p>A collection of keyword arguments specified as dialect-specific
options to this construct.</p>
<p>The arguments are present here in their original <tt class="docutils literal"><span class="pre"><dialect>_<kwarg></span></tt>
format. Only arguments that were actually passed are included;
unlike the <a class="reference internal" href="#sqlalchemy.sql.base.DialectKWArgs.dialect_options" title="sqlalchemy.sql.base.DialectKWArgs.dialect_options"><tt class="xref py py-attr docutils literal"><span class="pre">DialectKWArgs.dialect_options</span></tt></a> collection, which
contains all options known by this dialect including defaults.</p>
<p>The collection is also writable; keys are accepted of the
form <tt class="docutils literal"><span class="pre"><dialect>_<kwarg></span></tt> where the value will be assembled
into the list of options.</p>
<div class="versionadded">
<p><span>New in version 0.9.2.</span></p>
</div>
<div class="versionchanged">
<p><span>Changed in version 0.9.4: </span>The <a class="reference internal" href="#sqlalchemy.sql.base.DialectKWArgs.dialect_kwargs" title="sqlalchemy.sql.base.DialectKWArgs.dialect_kwargs"><tt class="xref py py-attr docutils literal"><span class="pre">DialectKWArgs.dialect_kwargs</span></tt></a>
collection is now writable.</p>
</div>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p class="last"><a class="reference internal" href="#sqlalchemy.sql.base.DialectKWArgs.dialect_options" title="sqlalchemy.sql.base.DialectKWArgs.dialect_options"><tt class="xref py py-attr docutils literal"><span class="pre">DialectKWArgs.dialect_options</span></tt></a> - nested dictionary form</p>
</div>
</dd></dl>
<dl class="attribute">
<dt id="sqlalchemy.sql.base.DialectKWArgs.dialect_options">
<tt class="descname">dialect_options</tt><a class="headerlink" href="#sqlalchemy.sql.base.DialectKWArgs.dialect_options" title="Permalink to this definition">¶</a></dt>
<dd><p>A collection of keyword arguments specified as dialect-specific
options to this construct.</p>
<p>This is a two-level nested registry, keyed to <tt class="docutils literal"><span class="pre"><dialect_name></span></tt>
and <tt class="docutils literal"><span class="pre"><argument_name></span></tt>. For example, the <tt class="docutils literal"><span class="pre">postgresql_where</span></tt>
argument would be locatable as:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">arg</span> <span class="o">=</span> <span class="n">my_object</span><span class="o">.</span><span class="n">dialect_options</span><span class="p">[</span><span class="s">'postgresql'</span><span class="p">][</span><span class="s">'where'</span><span class="p">]</span></pre></div>
</div>
<div class="versionadded">
<p><span>New in version 0.9.2.</span></p>
</div>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p class="last"><a class="reference internal" href="#sqlalchemy.sql.base.DialectKWArgs.dialect_kwargs" title="sqlalchemy.sql.base.DialectKWArgs.dialect_kwargs"><tt class="xref py py-attr docutils literal"><span class="pre">DialectKWArgs.dialect_kwargs</span></tt></a> - flat dictionary form</p>
</div>
</dd></dl>
<dl class="attribute">
<dt id="sqlalchemy.sql.base.DialectKWArgs.kwargs">
<tt class="descname">kwargs</tt><a class="headerlink" href="#sqlalchemy.sql.base.DialectKWArgs.kwargs" title="Permalink to this definition">¶</a></dt>
<dd><p>A synonym for <a class="reference internal" href="#sqlalchemy.sql.base.DialectKWArgs.dialect_kwargs" title="sqlalchemy.sql.base.DialectKWArgs.dialect_kwargs"><tt class="xref py py-attr docutils literal"><span class="pre">DialectKWArgs.dialect_kwargs</span></tt></a>.</p>
</dd></dl>
</dd></dl>
<dl class="class">
<dt id="sqlalchemy.sql.expression.Extract">
<em class="property">class </em><tt class="descclassname">sqlalchemy.sql.expression.</tt><tt class="descname">Extract</tt><big>(</big><em>field</em>, <em>expr</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.Extract" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference internal" href="#sqlalchemy.sql.expression.ColumnElement" title="sqlalchemy.sql.expression.ColumnElement"><tt class="xref py py-class docutils literal"><span class="pre">sqlalchemy.sql.expression.ColumnElement</span></tt></a></p>
<p>Represent a SQL EXTRACT clause, <tt class="docutils literal"><span class="pre">extract(field</span> <span class="pre">FROM</span> <span class="pre">expr)</span></tt>.</p>
<dl class="method">
<dt id="sqlalchemy.sql.expression.Extract.__init__">
<tt class="descname">__init__</tt><big>(</big><em>field</em>, <em>expr</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.Extract.__init__" title="Permalink to this definition">¶</a></dt>
<dd><p>Construct a new <a class="reference internal" href="#sqlalchemy.sql.expression.Extract" title="sqlalchemy.sql.expression.Extract"><tt class="xref py py-class docutils literal"><span class="pre">Extract</span></tt></a> object.</p>
<p>This constructor is mirrored as a public API function; see <a class="reference internal" href="#sqlalchemy.sql.expression.extract" title="sqlalchemy.sql.expression.extract"><tt class="xref py py-func docutils literal"><span class="pre">extract()</span></tt></a> for a full usage and argument description.</p>
</dd></dl>
</dd></dl>
<dl class="class">
<dt id="sqlalchemy.sql.elements.False_">
<em class="property">class </em><tt class="descclassname">sqlalchemy.sql.elements.</tt><tt class="descname">False_</tt><a class="headerlink" href="#sqlalchemy.sql.elements.False_" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference internal" href="#sqlalchemy.sql.expression.ColumnElement" title="sqlalchemy.sql.expression.ColumnElement"><tt class="xref py py-class docutils literal"><span class="pre">sqlalchemy.sql.expression.ColumnElement</span></tt></a></p>
<p>Represent the <tt class="docutils literal"><span class="pre">false</span></tt> keyword, or equivalent, in a SQL statement.</p>
<p><a class="reference internal" href="#sqlalchemy.sql.elements.False_" title="sqlalchemy.sql.elements.False_"><tt class="xref py py-class docutils literal"><span class="pre">False_</span></tt></a> is accessed as a constant via the
<a class="reference internal" href="#sqlalchemy.sql.expression.false" title="sqlalchemy.sql.expression.false"><tt class="xref py py-func docutils literal"><span class="pre">false()</span></tt></a> function.</p>
</dd></dl>
<dl class="class">
<dt id="sqlalchemy.sql.expression.Label">
<em class="property">class </em><tt class="descclassname">sqlalchemy.sql.expression.</tt><tt class="descname">Label</tt><big>(</big><em>name</em>, <em>element</em>, <em>type_=None</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.Label" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference internal" href="#sqlalchemy.sql.expression.ColumnElement" title="sqlalchemy.sql.expression.ColumnElement"><tt class="xref py py-class docutils literal"><span class="pre">sqlalchemy.sql.expression.ColumnElement</span></tt></a></p>
<p>Represents a column label (AS).</p>
<p>Represent a label, as typically applied to any column-level
element using the <tt class="docutils literal"><span class="pre">AS</span></tt> sql keyword.</p>
<dl class="method">
<dt id="sqlalchemy.sql.expression.Label.__init__">
<tt class="descname">__init__</tt><big>(</big><em>name</em>, <em>element</em>, <em>type_=None</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.Label.__init__" title="Permalink to this definition">¶</a></dt>
<dd><p>Construct a new <a class="reference internal" href="#sqlalchemy.sql.expression.Label" title="sqlalchemy.sql.expression.Label"><tt class="xref py py-class docutils literal"><span class="pre">Label</span></tt></a> object.</p>
<p>This constructor is mirrored as a public API function; see <a class="reference internal" href="#sqlalchemy.sql.expression.label" title="sqlalchemy.sql.expression.label"><tt class="xref py py-func docutils literal"><span class="pre">label()</span></tt></a> for a full usage and argument description.</p>
</dd></dl>
</dd></dl>
<dl class="class">
<dt id="sqlalchemy.sql.elements.Null">
<em class="property">class </em><tt class="descclassname">sqlalchemy.sql.elements.</tt><tt class="descname">Null</tt><a class="headerlink" href="#sqlalchemy.sql.elements.Null" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference internal" href="#sqlalchemy.sql.expression.ColumnElement" title="sqlalchemy.sql.expression.ColumnElement"><tt class="xref py py-class docutils literal"><span class="pre">sqlalchemy.sql.expression.ColumnElement</span></tt></a></p>
<p>Represent the NULL keyword in a SQL statement.</p>
<p><a class="reference internal" href="#sqlalchemy.sql.elements.Null" title="sqlalchemy.sql.elements.Null"><tt class="xref py py-class docutils literal"><span class="pre">Null</span></tt></a> is accessed as a constant via the
<a class="reference internal" href="#sqlalchemy.sql.expression.null" title="sqlalchemy.sql.expression.null"><tt class="xref py py-func docutils literal"><span class="pre">null()</span></tt></a> function.</p>
</dd></dl>
<dl class="class">
<dt id="sqlalchemy.sql.expression.Over">
<em class="property">class </em><tt class="descclassname">sqlalchemy.sql.expression.</tt><tt class="descname">Over</tt><big>(</big><em>func</em>, <em>partition_by=None</em>, <em>order_by=None</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.Over" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference internal" href="#sqlalchemy.sql.expression.ColumnElement" title="sqlalchemy.sql.expression.ColumnElement"><tt class="xref py py-class docutils literal"><span class="pre">sqlalchemy.sql.expression.ColumnElement</span></tt></a></p>
<p>Represent an OVER clause.</p>
<p>This is a special operator against a so-called
“window” function, as well as any aggregate function,
which produces results relative to the result set
itself. It’s supported only by certain database
backends.</p>
<dl class="method">
<dt id="sqlalchemy.sql.expression.Over.__init__">
<tt class="descname">__init__</tt><big>(</big><em>func</em>, <em>partition_by=None</em>, <em>order_by=None</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.Over.__init__" title="Permalink to this definition">¶</a></dt>
<dd><p>Construct a new <a class="reference internal" href="#sqlalchemy.sql.expression.Over" title="sqlalchemy.sql.expression.Over"><tt class="xref py py-class docutils literal"><span class="pre">Over</span></tt></a> object.</p>
<p>This constructor is mirrored as a public API function; see <a class="reference internal" href="#sqlalchemy.sql.expression.over" title="sqlalchemy.sql.expression.over"><tt class="xref py py-func docutils literal"><span class="pre">over()</span></tt></a> for a full usage and argument description.</p>
</dd></dl>
</dd></dl>
<dl class="class">
<dt id="sqlalchemy.sql.expression.TextClause">
<em class="property">class </em><tt class="descclassname">sqlalchemy.sql.expression.</tt><tt class="descname">TextClause</tt><big>(</big><em>text</em>, <em>bind=None</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.TextClause" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference internal" href="selectable.html#sqlalchemy.sql.expression.Executable" title="sqlalchemy.sql.expression.Executable"><tt class="xref py py-class docutils literal"><span class="pre">sqlalchemy.sql.expression.Executable</span></tt></a>, <a class="reference internal" href="#sqlalchemy.sql.expression.ClauseElement" title="sqlalchemy.sql.expression.ClauseElement"><tt class="xref py py-class docutils literal"><span class="pre">sqlalchemy.sql.expression.ClauseElement</span></tt></a></p>
<p>Represent a literal SQL text fragment.</p>
<p>E.g.:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="kn">import</span> <span class="n">text</span>
<span class="n">t</span> <span class="o">=</span> <span class="n">text</span><span class="p">(</span><span class="s">"SELECT * FROM users"</span><span class="p">)</span>
<span class="n">result</span> <span class="o">=</span> <span class="n">connection</span><span class="o">.</span><span class="n">execute</span><span class="p">(</span><span class="n">t</span><span class="p">)</span></pre></div>
</div>
<p>The <a class="reference internal" href="types.html#sqlalchemy.types.Text" title="sqlalchemy.types.Text"><tt class="xref py py-class docutils literal"><span class="pre">Text</span></tt></a> construct is produced using the <a class="reference internal" href="#sqlalchemy.sql.expression.text" title="sqlalchemy.sql.expression.text"><tt class="xref py py-func docutils literal"><span class="pre">text()</span></tt></a>
function; see that function for full documentation.</p>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p class="last"><a class="reference internal" href="#sqlalchemy.sql.expression.text" title="sqlalchemy.sql.expression.text"><tt class="xref py py-func docutils literal"><span class="pre">text()</span></tt></a></p>
</div>
<dl class="method">
<dt id="sqlalchemy.sql.expression.TextClause.bindparams">
<tt class="descname">bindparams</tt><big>(</big><em>*binds</em>, <em>**names_to_values</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.TextClause.bindparams" title="Permalink to this definition">¶</a></dt>
<dd><p>Establish the values and/or types of bound parameters within
this <a class="reference internal" href="#sqlalchemy.sql.expression.TextClause" title="sqlalchemy.sql.expression.TextClause"><tt class="xref py py-class docutils literal"><span class="pre">TextClause</span></tt></a> construct.</p>
<p>Given a text construct such as:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="kn">import</span> <span class="n">text</span>
<span class="n">stmt</span> <span class="o">=</span> <span class="n">text</span><span class="p">(</span><span class="s">"SELECT id, name FROM user WHERE name=:name "</span>
<span class="s">"AND timestamp=:timestamp"</span><span class="p">)</span></pre></div>
</div>
<p>the <a class="reference internal" href="#sqlalchemy.sql.expression.TextClause.bindparams" title="sqlalchemy.sql.expression.TextClause.bindparams"><tt class="xref py py-meth docutils literal"><span class="pre">TextClause.bindparams()</span></tt></a> method can be used to establish
the initial value of <tt class="docutils literal"><span class="pre">:name</span></tt> and <tt class="docutils literal"><span class="pre">:timestamp</span></tt>,
using simple keyword arguments:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">stmt</span> <span class="o">=</span> <span class="n">stmt</span><span class="o">.</span><span class="n">bindparams</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s">'jack'</span><span class="p">,</span>
<span class="n">timestamp</span><span class="o">=</span><span class="n">datetime</span><span class="o">.</span><span class="n">datetime</span><span class="p">(</span><span class="mi">2012</span><span class="p">,</span> <span class="mi">10</span><span class="p">,</span> <span class="mi">8</span><span class="p">,</span> <span class="mi">15</span><span class="p">,</span> <span class="mi">12</span><span class="p">,</span> <span class="mi">5</span><span class="p">))</span></pre></div>
</div>
<p>Where above, new <a class="reference internal" href="#sqlalchemy.sql.expression.BindParameter" title="sqlalchemy.sql.expression.BindParameter"><tt class="xref py py-class docutils literal"><span class="pre">BindParameter</span></tt></a> objects
will be generated with the names <tt class="docutils literal"><span class="pre">name</span></tt> and <tt class="docutils literal"><span class="pre">timestamp</span></tt>, and
values of <tt class="docutils literal"><span class="pre">jack</span></tt> and <tt class="docutils literal"><span class="pre">datetime.datetime(2012,</span> <span class="pre">10,</span> <span class="pre">8,</span> <span class="pre">15,</span> <span class="pre">12,</span> <span class="pre">5)</span></tt>,
respectively. The types will be
inferred from the values given, in this case <a class="reference internal" href="types.html#sqlalchemy.types.String" title="sqlalchemy.types.String"><tt class="xref py py-class docutils literal"><span class="pre">String</span></tt></a> and
<a class="reference internal" href="types.html#sqlalchemy.types.DateTime" title="sqlalchemy.types.DateTime"><tt class="xref py py-class docutils literal"><span class="pre">DateTime</span></tt></a>.</p>
<p>When specific typing behavior is needed, the positional <tt class="docutils literal"><span class="pre">*binds</span></tt>
argument can be used in which to specify <a class="reference internal" href="#sqlalchemy.sql.expression.bindparam" title="sqlalchemy.sql.expression.bindparam"><tt class="xref py py-func docutils literal"><span class="pre">bindparam()</span></tt></a> constructs
directly. These constructs must include at least the <tt class="docutils literal"><span class="pre">key</span></tt>
argument, then an optional value and type:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="kn">import</span> <span class="n">bindparam</span>
<span class="n">stmt</span> <span class="o">=</span> <span class="n">stmt</span><span class="o">.</span><span class="n">bindparams</span><span class="p">(</span>
<span class="n">bindparam</span><span class="p">(</span><span class="s">'name'</span><span class="p">,</span> <span class="n">value</span><span class="o">=</span><span class="s">'jack'</span><span class="p">,</span> <span class="n">type_</span><span class="o">=</span><span class="n">String</span><span class="p">),</span>
<span class="n">bindparam</span><span class="p">(</span><span class="s">'timestamp'</span><span class="p">,</span> <span class="n">type_</span><span class="o">=</span><span class="n">DateTime</span><span class="p">)</span>
<span class="p">)</span></pre></div>
</div>
<p>Above, we specified the type of <a class="reference internal" href="types.html#sqlalchemy.types.DateTime" title="sqlalchemy.types.DateTime"><tt class="xref py py-class docutils literal"><span class="pre">DateTime</span></tt></a> for the
<tt class="docutils literal"><span class="pre">timestamp</span></tt> bind, and the type of <a class="reference internal" href="types.html#sqlalchemy.types.String" title="sqlalchemy.types.String"><tt class="xref py py-class docutils literal"><span class="pre">String</span></tt></a> for the <tt class="docutils literal"><span class="pre">name</span></tt>
bind. In the case of <tt class="docutils literal"><span class="pre">name</span></tt> we also set the default value of
<tt class="docutils literal"><span class="pre">"jack"</span></tt>.</p>
<p>Additional bound parameters can be supplied at statement execution
time, e.g.:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">result</span> <span class="o">=</span> <span class="n">connection</span><span class="o">.</span><span class="n">execute</span><span class="p">(</span><span class="n">stmt</span><span class="p">,</span>
<span class="n">timestamp</span><span class="o">=</span><span class="n">datetime</span><span class="o">.</span><span class="n">datetime</span><span class="p">(</span><span class="mi">2012</span><span class="p">,</span> <span class="mi">10</span><span class="p">,</span> <span class="mi">8</span><span class="p">,</span> <span class="mi">15</span><span class="p">,</span> <span class="mi">12</span><span class="p">,</span> <span class="mi">5</span><span class="p">))</span></pre></div>
</div>
<p>The <a class="reference internal" href="#sqlalchemy.sql.expression.TextClause.bindparams" title="sqlalchemy.sql.expression.TextClause.bindparams"><tt class="xref py py-meth docutils literal"><span class="pre">TextClause.bindparams()</span></tt></a> method can be called repeatedly,
where it will re-use existing <a class="reference internal" href="#sqlalchemy.sql.expression.BindParameter" title="sqlalchemy.sql.expression.BindParameter"><tt class="xref py py-class docutils literal"><span class="pre">BindParameter</span></tt></a> objects to add
new information. For example, we can call
<a class="reference internal" href="#sqlalchemy.sql.expression.TextClause.bindparams" title="sqlalchemy.sql.expression.TextClause.bindparams"><tt class="xref py py-meth docutils literal"><span class="pre">TextClause.bindparams()</span></tt></a> first with typing information, and a
second time with value information, and it will be combined:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">stmt</span> <span class="o">=</span> <span class="n">text</span><span class="p">(</span><span class="s">"SELECT id, name FROM user WHERE name=:name "</span>
<span class="s">"AND timestamp=:timestamp"</span><span class="p">)</span>
<span class="n">stmt</span> <span class="o">=</span> <span class="n">stmt</span><span class="o">.</span><span class="n">bindparams</span><span class="p">(</span>
<span class="n">bindparam</span><span class="p">(</span><span class="s">'name'</span><span class="p">,</span> <span class="n">type_</span><span class="o">=</span><span class="n">String</span><span class="p">),</span>
<span class="n">bindparam</span><span class="p">(</span><span class="s">'timestamp'</span><span class="p">,</span> <span class="n">type_</span><span class="o">=</span><span class="n">DateTime</span><span class="p">)</span>
<span class="p">)</span>
<span class="n">stmt</span> <span class="o">=</span> <span class="n">stmt</span><span class="o">.</span><span class="n">bindparams</span><span class="p">(</span>
<span class="n">name</span><span class="o">=</span><span class="s">'jack'</span><span class="p">,</span>
<span class="n">timestamp</span><span class="o">=</span><span class="n">datetime</span><span class="o">.</span><span class="n">datetime</span><span class="p">(</span><span class="mi">2012</span><span class="p">,</span> <span class="mi">10</span><span class="p">,</span> <span class="mi">8</span><span class="p">,</span> <span class="mi">15</span><span class="p">,</span> <span class="mi">12</span><span class="p">,</span> <span class="mi">5</span><span class="p">)</span>
<span class="p">)</span></pre></div>
</div>
<div class="versionadded">
<p><span>New in version 0.9.0: </span>The <a class="reference internal" href="#sqlalchemy.sql.expression.TextClause.bindparams" title="sqlalchemy.sql.expression.TextClause.bindparams"><tt class="xref py py-meth docutils literal"><span class="pre">TextClause.bindparams()</span></tt></a> method
supersedes the argument <tt class="docutils literal"><span class="pre">bindparams</span></tt> passed to
<a class="reference internal" href="#sqlalchemy.sql.expression.text" title="sqlalchemy.sql.expression.text"><tt class="xref py py-func docutils literal"><span class="pre">text()</span></tt></a>.</p>
</div>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.sql.expression.TextClause.columns">
<tt class="descname">columns</tt><big>(</big><em>*cols</em>, <em>**types</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.TextClause.columns" title="Permalink to this definition">¶</a></dt>
<dd><p>Turn this <a class="reference internal" href="#sqlalchemy.sql.expression.TextClause" title="sqlalchemy.sql.expression.TextClause"><tt class="xref py py-class docutils literal"><span class="pre">TextClause</span></tt></a> object into a <a class="reference internal" href="selectable.html#sqlalchemy.sql.expression.TextAsFrom" title="sqlalchemy.sql.expression.TextAsFrom"><tt class="xref py py-class docutils literal"><span class="pre">TextAsFrom</span></tt></a>
object that can be embedded into another statement.</p>
<p>This function essentially bridges the gap between an entirely
textual SELECT statement and the SQL expression language concept
of a “selectable”:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">sqlalchemy.sql</span> <span class="kn">import</span> <span class="n">column</span><span class="p">,</span> <span class="n">text</span>
<span class="n">stmt</span> <span class="o">=</span> <span class="n">text</span><span class="p">(</span><span class="s">"SELECT id, name FROM some_table"</span><span class="p">)</span>
<span class="n">stmt</span> <span class="o">=</span> <span class="n">stmt</span><span class="o">.</span><span class="n">columns</span><span class="p">(</span><span class="n">column</span><span class="p">(</span><span class="s">'id'</span><span class="p">),</span> <span class="n">column</span><span class="p">(</span><span class="s">'name'</span><span class="p">))</span><span class="o">.</span><span class="n">alias</span><span class="p">(</span><span class="s">'st'</span><span class="p">)</span>
<span class="n">stmt</span> <span class="o">=</span> <span class="n">select</span><span class="p">([</span><span class="n">mytable</span><span class="p">])</span><span class="o">.</span>\
<span class="n">select_from</span><span class="p">(</span>
<span class="n">mytable</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">stmt</span><span class="p">,</span> <span class="n">mytable</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">name</span> <span class="o">==</span> <span class="n">stmt</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">name</span><span class="p">)</span>
<span class="p">)</span><span class="o">.</span><span class="n">where</span><span class="p">(</span><span class="n">stmt</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">id</span> <span class="o">></span> <span class="mi">5</span><span class="p">)</span></pre></div>
</div>
<p>Above, we used untyped <a class="reference internal" href="#sqlalchemy.sql.expression.column" title="sqlalchemy.sql.expression.column"><tt class="xref py py-func docutils literal"><span class="pre">column()</span></tt></a> elements. These can also have
types specified, which will impact how the column behaves in
expressions as well as determining result set behavior:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">stmt</span> <span class="o">=</span> <span class="n">text</span><span class="p">(</span><span class="s">"SELECT id, name, timestamp FROM some_table"</span><span class="p">)</span>
<span class="n">stmt</span> <span class="o">=</span> <span class="n">stmt</span><span class="o">.</span><span class="n">columns</span><span class="p">(</span>
<span class="n">column</span><span class="p">(</span><span class="s">'id'</span><span class="p">,</span> <span class="n">Integer</span><span class="p">),</span>
<span class="n">column</span><span class="p">(</span><span class="s">'name'</span><span class="p">,</span> <span class="n">Unicode</span><span class="p">),</span>
<span class="n">column</span><span class="p">(</span><span class="s">'timestamp'</span><span class="p">,</span> <span class="n">DateTime</span><span class="p">)</span>
<span class="p">)</span>
<span class="k">for</span> <span class="nb">id</span><span class="p">,</span> <span class="n">name</span><span class="p">,</span> <span class="n">timestamp</span> <span class="ow">in</span> <span class="n">connection</span><span class="o">.</span><span class="n">execute</span><span class="p">(</span><span class="n">stmt</span><span class="p">):</span>
<span class="k">print</span><span class="p">(</span><span class="nb">id</span><span class="p">,</span> <span class="n">name</span><span class="p">,</span> <span class="n">timestamp</span><span class="p">)</span></pre></div>
</div>
<p>Keyword arguments allow just the names and types of columns to be
specified, where the <a class="reference internal" href="#sqlalchemy.sql.expression.column" title="sqlalchemy.sql.expression.column"><tt class="xref py py-func docutils literal"><span class="pre">column()</span></tt></a> elements will be generated
automatically:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">stmt</span> <span class="o">=</span> <span class="n">text</span><span class="p">(</span><span class="s">"SELECT id, name, timestamp FROM some_table"</span><span class="p">)</span>
<span class="n">stmt</span> <span class="o">=</span> <span class="n">stmt</span><span class="o">.</span><span class="n">columns</span><span class="p">(</span>
<span class="nb">id</span><span class="o">=</span><span class="n">Integer</span><span class="p">,</span>
<span class="n">name</span><span class="o">=</span><span class="n">Unicode</span><span class="p">,</span>
<span class="n">timestamp</span><span class="o">=</span><span class="n">DateTime</span>
<span class="p">)</span>
<span class="k">for</span> <span class="nb">id</span><span class="p">,</span> <span class="n">name</span><span class="p">,</span> <span class="n">timestamp</span> <span class="ow">in</span> <span class="n">connection</span><span class="o">.</span><span class="n">execute</span><span class="p">(</span><span class="n">stmt</span><span class="p">):</span>
<span class="k">print</span><span class="p">(</span><span class="nb">id</span><span class="p">,</span> <span class="n">name</span><span class="p">,</span> <span class="n">timestamp</span><span class="p">)</span></pre></div>
</div>
<p>The <a class="reference internal" href="#sqlalchemy.sql.expression.TextClause.columns" title="sqlalchemy.sql.expression.TextClause.columns"><tt class="xref py py-meth docutils literal"><span class="pre">TextClause.columns()</span></tt></a> method provides a direct
route to calling <a class="reference internal" href="selectable.html#sqlalchemy.sql.expression.FromClause.alias" title="sqlalchemy.sql.expression.FromClause.alias"><tt class="xref py py-meth docutils literal"><span class="pre">FromClause.alias()</span></tt></a> as well as
<a class="reference internal" href="selectable.html#sqlalchemy.sql.expression.SelectBase.cte" title="sqlalchemy.sql.expression.SelectBase.cte"><tt class="xref py py-meth docutils literal"><span class="pre">SelectBase.cte()</span></tt></a> against a textual SELECT statement:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">stmt</span> <span class="o">=</span> <span class="n">stmt</span><span class="o">.</span><span class="n">columns</span><span class="p">(</span><span class="nb">id</span><span class="o">=</span><span class="n">Integer</span><span class="p">,</span> <span class="n">name</span><span class="o">=</span><span class="n">String</span><span class="p">)</span><span class="o">.</span><span class="n">cte</span><span class="p">(</span><span class="s">'st'</span><span class="p">)</span>
<span class="n">stmt</span> <span class="o">=</span> <span class="n">select</span><span class="p">([</span><span class="n">sometable</span><span class="p">])</span><span class="o">.</span><span class="n">where</span><span class="p">(</span><span class="n">sometable</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">id</span> <span class="o">==</span> <span class="n">stmt</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">id</span><span class="p">)</span></pre></div>
</div>
<div class="versionadded">
<p><span>New in version 0.9.0: </span><a class="reference internal" href="#sqlalchemy.sql.expression.text" title="sqlalchemy.sql.expression.text"><tt class="xref py py-func docutils literal"><span class="pre">text()</span></tt></a> can now be converted into a
fully featured “selectable” construct using the
<a class="reference internal" href="#sqlalchemy.sql.expression.TextClause.columns" title="sqlalchemy.sql.expression.TextClause.columns"><tt class="xref py py-meth docutils literal"><span class="pre">TextClause.columns()</span></tt></a> method. This method supersedes the
<tt class="docutils literal"><span class="pre">typemap</span></tt> argument to <a class="reference internal" href="#sqlalchemy.sql.expression.text" title="sqlalchemy.sql.expression.text"><tt class="xref py py-func docutils literal"><span class="pre">text()</span></tt></a>.</p>
</div>
</dd></dl>
</dd></dl>
<dl class="class">
<dt id="sqlalchemy.sql.expression.Tuple">
<em class="property">class </em><tt class="descclassname">sqlalchemy.sql.expression.</tt><tt class="descname">Tuple</tt><big>(</big><em>*clauses</em>, <em>**kw</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.Tuple" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference internal" href="#sqlalchemy.sql.expression.ClauseList" title="sqlalchemy.sql.expression.ClauseList"><tt class="xref py py-class docutils literal"><span class="pre">sqlalchemy.sql.expression.ClauseList</span></tt></a>, <a class="reference internal" href="#sqlalchemy.sql.expression.ColumnElement" title="sqlalchemy.sql.expression.ColumnElement"><tt class="xref py py-class docutils literal"><span class="pre">sqlalchemy.sql.expression.ColumnElement</span></tt></a></p>
<p>Represent a SQL tuple.</p>
<dl class="method">
<dt id="sqlalchemy.sql.expression.Tuple.__init__">
<tt class="descname">__init__</tt><big>(</big><em>*clauses</em>, <em>**kw</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.Tuple.__init__" title="Permalink to this definition">¶</a></dt>
<dd><p>Construct a new <a class="reference internal" href="#sqlalchemy.sql.expression.Tuple" title="sqlalchemy.sql.expression.Tuple"><tt class="xref py py-class docutils literal"><span class="pre">Tuple</span></tt></a> object.</p>
<p>This constructor is mirrored as a public API function; see <a class="reference internal" href="#sqlalchemy.sql.expression.tuple_" title="sqlalchemy.sql.expression.tuple_"><tt class="xref py py-func docutils literal"><span class="pre">tuple_()</span></tt></a> for a full usage and argument description.</p>
</dd></dl>
</dd></dl>
<dl class="class">
<dt id="sqlalchemy.sql.elements.True_">
<em class="property">class </em><tt class="descclassname">sqlalchemy.sql.elements.</tt><tt class="descname">True_</tt><a class="headerlink" href="#sqlalchemy.sql.elements.True_" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference internal" href="#sqlalchemy.sql.expression.ColumnElement" title="sqlalchemy.sql.expression.ColumnElement"><tt class="xref py py-class docutils literal"><span class="pre">sqlalchemy.sql.expression.ColumnElement</span></tt></a></p>
<p>Represent the <tt class="docutils literal"><span class="pre">true</span></tt> keyword, or equivalent, in a SQL statement.</p>
<p><a class="reference internal" href="#sqlalchemy.sql.elements.True_" title="sqlalchemy.sql.elements.True_"><tt class="xref py py-class docutils literal"><span class="pre">True_</span></tt></a> is accessed as a constant via the
<a class="reference internal" href="#sqlalchemy.sql.expression.true" title="sqlalchemy.sql.expression.true"><tt class="xref py py-func docutils literal"><span class="pre">true()</span></tt></a> function.</p>
</dd></dl>
<dl class="class">
<dt id="sqlalchemy.sql.operators.custom_op">
<em class="property">class </em><tt class="descclassname">sqlalchemy.sql.operators.</tt><tt class="descname">custom_op</tt><big>(</big><em>opstring</em>, <em>precedence=0</em>, <em>is_comparison=False</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.operators.custom_op" title="Permalink to this definition">¶</a></dt>
<dd><p>Represent a ‘custom’ operator.</p>
<p><a class="reference internal" href="#sqlalchemy.sql.operators.custom_op" title="sqlalchemy.sql.operators.custom_op"><tt class="xref py py-class docutils literal"><span class="pre">custom_op</span></tt></a> is normally instantitated when the
<a class="reference internal" href="#sqlalchemy.sql.operators.ColumnOperators.op" title="sqlalchemy.sql.operators.ColumnOperators.op"><tt class="xref py py-meth docutils literal"><span class="pre">ColumnOperators.op()</span></tt></a> method is used to create a
custom operator callable. The class can also be used directly
when programmatically constructing expressions. E.g.
to represent the “factorial” operation:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">sqlalchemy.sql</span> <span class="kn">import</span> <span class="n">UnaryExpression</span>
<span class="kn">from</span> <span class="nn">sqlalchemy.sql</span> <span class="kn">import</span> <span class="n">operators</span>
<span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="kn">import</span> <span class="n">Numeric</span>
<span class="n">unary</span> <span class="o">=</span> <span class="n">UnaryExpression</span><span class="p">(</span><span class="n">table</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">somecolumn</span><span class="p">,</span>
<span class="n">modifier</span><span class="o">=</span><span class="n">operators</span><span class="o">.</span><span class="n">custom_op</span><span class="p">(</span><span class="s">"!"</span><span class="p">),</span>
<span class="n">type_</span><span class="o">=</span><span class="n">Numeric</span><span class="p">)</span></pre></div>
</div>
</dd></dl>
<dl class="class">
<dt id="sqlalchemy.sql.operators.Operators">
<em class="property">class </em><tt class="descclassname">sqlalchemy.sql.operators.</tt><tt class="descname">Operators</tt><a class="headerlink" href="#sqlalchemy.sql.operators.Operators" title="Permalink to this definition">¶</a></dt>
<dd><p>Base of comparison and logical operators.</p>
<p>Implements base methods
<a class="reference internal" href="#sqlalchemy.sql.operators.Operators.operate" title="sqlalchemy.sql.operators.Operators.operate"><tt class="xref py py-meth docutils literal"><span class="pre">operate()</span></tt></a> and
<a class="reference internal" href="#sqlalchemy.sql.operators.Operators.reverse_operate" title="sqlalchemy.sql.operators.Operators.reverse_operate"><tt class="xref py py-meth docutils literal"><span class="pre">reverse_operate()</span></tt></a>, as well as
<a class="reference internal" href="#sqlalchemy.sql.operators.Operators.__and__" title="sqlalchemy.sql.operators.Operators.__and__"><tt class="xref py py-meth docutils literal"><span class="pre">__and__()</span></tt></a>,
<a class="reference internal" href="#sqlalchemy.sql.operators.Operators.__or__" title="sqlalchemy.sql.operators.Operators.__or__"><tt class="xref py py-meth docutils literal"><span class="pre">__or__()</span></tt></a>,
<a class="reference internal" href="#sqlalchemy.sql.operators.Operators.__invert__" title="sqlalchemy.sql.operators.Operators.__invert__"><tt class="xref py py-meth docutils literal"><span class="pre">__invert__()</span></tt></a>.</p>
<p>Usually is used via its most common subclass
<a class="reference internal" href="#sqlalchemy.sql.operators.ColumnOperators" title="sqlalchemy.sql.operators.ColumnOperators"><tt class="xref py py-class docutils literal"><span class="pre">ColumnOperators</span></tt></a>.</p>
<dl class="method">
<dt id="sqlalchemy.sql.operators.Operators.__and__">
<tt class="descname">__and__</tt><big>(</big><em>other</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.operators.Operators.__and__" title="Permalink to this definition">¶</a></dt>
<dd><p>Implement the <tt class="docutils literal"><span class="pre">&</span></tt> operator.</p>
<p>When used with SQL expressions, results in an
AND operation, equivalent to
<a class="reference internal" href="#sqlalchemy.sql.expression.and_" title="sqlalchemy.sql.expression.and_"><tt class="xref py py-func docutils literal"><span class="pre">and_()</span></tt></a>, that is:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">a</span> <span class="o">&</span> <span class="n">b</span></pre></div>
</div>
<p>is equivalent to:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="kn">import</span> <span class="n">and_</span>
<span class="n">and_</span><span class="p">(</span><span class="n">a</span><span class="p">,</span> <span class="n">b</span><span class="p">)</span></pre></div>
</div>
<p>Care should be taken when using <tt class="docutils literal"><span class="pre">&</span></tt> regarding
operator precedence; the <tt class="docutils literal"><span class="pre">&</span></tt> operator has the highest precedence.
The operands should be enclosed in parenthesis if they contain
further sub expressions:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="p">(</span><span class="n">a</span> <span class="o">==</span> <span class="mi">2</span><span class="p">)</span> <span class="o">&</span> <span class="p">(</span><span class="n">b</span> <span class="o">==</span> <span class="mi">4</span><span class="p">)</span></pre></div>
</div>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.sql.operators.Operators.__invert__">
<tt class="descname">__invert__</tt><big>(</big><big>)</big><a class="headerlink" href="#sqlalchemy.sql.operators.Operators.__invert__" title="Permalink to this definition">¶</a></dt>
<dd><p>Implement the <tt class="docutils literal"><span class="pre">~</span></tt> operator.</p>
<p>When used with SQL expressions, results in a
NOT operation, equivalent to
<a class="reference internal" href="#sqlalchemy.sql.expression.not_" title="sqlalchemy.sql.expression.not_"><tt class="xref py py-func docutils literal"><span class="pre">not_()</span></tt></a>, that is:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="o">~</span><span class="n">a</span></pre></div>
</div>
<p>is equivalent to:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="kn">import</span> <span class="n">not_</span>
<span class="n">not_</span><span class="p">(</span><span class="n">a</span><span class="p">)</span></pre></div>
</div>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.sql.operators.Operators.__or__">
<tt class="descname">__or__</tt><big>(</big><em>other</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.operators.Operators.__or__" title="Permalink to this definition">¶</a></dt>
<dd><p>Implement the <tt class="docutils literal"><span class="pre">|</span></tt> operator.</p>
<p>When used with SQL expressions, results in an
OR operation, equivalent to
<a class="reference internal" href="#sqlalchemy.sql.expression.or_" title="sqlalchemy.sql.expression.or_"><tt class="xref py py-func docutils literal"><span class="pre">or_()</span></tt></a>, that is:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">a</span> <span class="o">|</span> <span class="n">b</span></pre></div>
</div>
<p>is equivalent to:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="kn">import</span> <span class="n">or_</span>
<span class="n">or_</span><span class="p">(</span><span class="n">a</span><span class="p">,</span> <span class="n">b</span><span class="p">)</span></pre></div>
</div>
<p>Care should be taken when using <tt class="docutils literal"><span class="pre">|</span></tt> regarding
operator precedence; the <tt class="docutils literal"><span class="pre">|</span></tt> operator has the highest precedence.
The operands should be enclosed in parenthesis if they contain
further sub expressions:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="p">(</span><span class="n">a</span> <span class="o">==</span> <span class="mi">2</span><span class="p">)</span> <span class="o">|</span> <span class="p">(</span><span class="n">b</span> <span class="o">==</span> <span class="mi">4</span><span class="p">)</span></pre></div>
</div>
</dd></dl>
<dl class="attribute">
<dt id="sqlalchemy.sql.operators.Operators.__weakref__">
<tt class="descname">__weakref__</tt><a class="headerlink" href="#sqlalchemy.sql.operators.Operators.__weakref__" title="Permalink to this definition">¶</a></dt>
<dd><p>list of weak references to the object (if defined)</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.sql.operators.Operators.op">
<tt class="descname">op</tt><big>(</big><em>opstring</em>, <em>precedence=0</em>, <em>is_comparison=False</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.operators.Operators.op" title="Permalink to this definition">¶</a></dt>
<dd><p>produce a generic operator function.</p>
<p>e.g.:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">somecolumn</span><span class="o">.</span><span class="n">op</span><span class="p">(</span><span class="s">"*"</span><span class="p">)(</span><span class="mi">5</span><span class="p">)</span></pre></div>
</div>
<p>produces:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">somecolumn</span> <span class="o">*</span> <span class="mi">5</span></pre></div>
</div>
<p>This function can also be used to make bitwise operators explicit. For
example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">somecolumn</span><span class="o">.</span><span class="n">op</span><span class="p">(</span><span class="s">'&'</span><span class="p">)(</span><span class="mh">0xff</span><span class="p">)</span></pre></div>
</div>
<p>is a bitwise AND of the value in <tt class="docutils literal"><span class="pre">somecolumn</span></tt>.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><span class="target" id="sqlalchemy.sql.operators.Operators.op.params.operator"></span><strong>operator</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.operators.Operators.op.params.operator">¶</a> – a string which will be output as the infix operator
between this element and the expression passed to the
generated function.</li>
<li><span class="target" id="sqlalchemy.sql.operators.Operators.op.params.precedence"></span><strong>precedence</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.operators.Operators.op.params.precedence">¶</a> – <p>precedence to apply to the operator, when
parenthesizing expressions. A lower number will cause the expression
to be parenthesized when applied against another operator with
higher precedence. The default value of <tt class="docutils literal"><span class="pre">0</span></tt> is lower than all
operators except for the comma (<tt class="docutils literal"><span class="pre">,</span></tt>) and <tt class="docutils literal"><span class="pre">AS</span></tt> operators.
A value of 100 will be higher or equal to all operators, and -100
will be lower than or equal to all operators.</p>
<div class="versionadded">
<p><span>New in version 0.8: </span>- added the ‘precedence’ argument.</p>
</div>
</li>
<li><span class="target" id="sqlalchemy.sql.operators.Operators.op.params.is_comparison"></span><strong>is_comparison</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.operators.Operators.op.params.is_comparison">¶</a> – <p>if True, the operator will be considered as a
“comparison” operator, that is which evaulates to a boolean
true/false value, like <tt class="docutils literal"><span class="pre">==</span></tt>, <tt class="docutils literal"><span class="pre">></span></tt>, etc. This flag should be set
so that ORM relationships can establish that the operator is a
comparison operator when used in a custom join condition.</p>
<div class="versionadded">
<p><span>New in version 0.9.2: </span>- added the
<a class="reference internal" href="#sqlalchemy.sql.operators.Operators.op.params.is_comparison" title="sqlalchemy.sql.operators.Operators.op"><tt class="xref py py-paramref docutils literal"><span class="pre">Operators.op.is_comparison</span></tt></a> flag.</p>
</div>
</li>
</ul>
</td>
</tr>
</tbody>
</table>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p><a class="reference internal" href="types.html#types-operators"><em>Redefining and Creating New Operators</em></a></p>
<p class="last"><a class="reference internal" href="../orm/relationships.html#relationship-custom-operator"><em>Using custom operators in join conditions</em></a></p>
</div>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.sql.operators.Operators.operate">
<tt class="descname">operate</tt><big>(</big><em>op</em>, <em>*other</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.operators.Operators.operate" title="Permalink to this definition">¶</a></dt>
<dd><p>Operate on an argument.</p>
<p>This is the lowest level of operation, raises
<tt class="xref py py-class docutils literal"><span class="pre">NotImplementedError</span></tt> by default.</p>
<p>Overriding this on a subclass can allow common
behavior to be applied to all operations.
For example, overriding <a class="reference internal" href="#sqlalchemy.sql.operators.ColumnOperators" title="sqlalchemy.sql.operators.ColumnOperators"><tt class="xref py py-class docutils literal"><span class="pre">ColumnOperators</span></tt></a>
to apply <tt class="docutils literal"><span class="pre">func.lower()</span></tt> to the left and right
side:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">class</span> <span class="nc">MyComparator</span><span class="p">(</span><span class="n">ColumnOperators</span><span class="p">):</span>
<span class="k">def</span> <span class="nf">operate</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">op</span><span class="p">,</span> <span class="n">other</span><span class="p">):</span>
<span class="k">return</span> <span class="n">op</span><span class="p">(</span><span class="n">func</span><span class="o">.</span><span class="n">lower</span><span class="p">(</span><span class="bp">self</span><span class="p">),</span> <span class="n">func</span><span class="o">.</span><span class="n">lower</span><span class="p">(</span><span class="n">other</span><span class="p">))</span></pre></div>
</div>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><span class="target" id="sqlalchemy.sql.operators.Operators.operate.params.op"></span><strong>op</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.operators.Operators.operate.params.op">¶</a> – Operator callable.</li>
<li><span class="target" id="sqlalchemy.sql.operators.Operators.operate.params.*other"></span><strong>*other</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.operators.Operators.operate.params.*other">¶</a> – the ‘other’ side of the operation. Will
be a single scalar for most operations.</li>
<li><span class="target" id="sqlalchemy.sql.operators.Operators.operate.params.**kwargs"></span><strong>**kwargs</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.sql.operators.Operators.operate.params.**kwargs">¶</a> – modifiers. These may be passed by special
operators such as <tt class="xref py py-meth docutils literal"><span class="pre">ColumnOperators.contains()</span></tt>.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.sql.operators.Operators.reverse_operate">
<tt class="descname">reverse_operate</tt><big>(</big><em>op</em>, <em>other</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.operators.Operators.reverse_operate" title="Permalink to this definition">¶</a></dt>
<dd><p>Reverse operate on an argument.</p>
<p>Usage is the same as <tt class="xref py py-meth docutils literal"><span class="pre">operate()</span></tt>.</p>
</dd></dl>
</dd></dl>
<dl class="class">
<dt id="sqlalchemy.sql.elements.quoted_name">
<em class="property">class </em><tt class="descclassname">sqlalchemy.sql.elements.</tt><tt class="descname">quoted_name</tt><a class="headerlink" href="#sqlalchemy.sql.elements.quoted_name" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <tt class="xref py py-class docutils literal"><span class="pre">__builtin__.unicode</span></tt></p>
<p>Represent a SQL identifier combined with quoting preferences.</p>
<p><a class="reference internal" href="#sqlalchemy.sql.elements.quoted_name" title="sqlalchemy.sql.elements.quoted_name"><tt class="xref py py-class docutils literal"><span class="pre">quoted_name</span></tt></a> is a Python unicode/str subclass which
represents a particular identifier name along with a
<tt class="docutils literal"><span class="pre">quote</span></tt> flag. This <tt class="docutils literal"><span class="pre">quote</span></tt> flag, when set to
<tt class="docutils literal"><span class="pre">True</span></tt> or <tt class="docutils literal"><span class="pre">False</span></tt>, overrides automatic quoting behavior
for this identifier in order to either unconditionally quote
or to not quote the name. If left at its default of <tt class="docutils literal"><span class="pre">None</span></tt>,
quoting behavior is applied to the identifier on a per-backend basis
based on an examination of the token itself.</p>
<p>A <a class="reference internal" href="#sqlalchemy.sql.elements.quoted_name" title="sqlalchemy.sql.elements.quoted_name"><tt class="xref py py-class docutils literal"><span class="pre">quoted_name</span></tt></a> object with <tt class="docutils literal"><span class="pre">quote=True</span></tt> is also
prevented from being modified in the case of a so-called
“name normalize” option. Certain database backends, such as
Oracle, Firebird, and DB2 “normalize” case-insensitive names
as uppercase. The SQLAlchemy dialects for these backends
convert from SQLAlchemy’s lower-case-means-insensitive convention
to the upper-case-means-insensitive conventions of those backends.
The <tt class="docutils literal"><span class="pre">quote=True</span></tt> flag here will prevent this conversion from occurring
to support an identifier that’s quoted as all lower case against
such a backend.</p>
<p>The <a class="reference internal" href="#sqlalchemy.sql.elements.quoted_name" title="sqlalchemy.sql.elements.quoted_name"><tt class="xref py py-class docutils literal"><span class="pre">quoted_name</span></tt></a> object is normally created automatically
when specifying the name for key schema constructs such as
<a class="reference internal" href="metadata.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal"><span class="pre">Table</span></tt></a>, <a class="reference internal" href="metadata.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal"><span class="pre">Column</span></tt></a>, 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 <a class="reference internal" href="connections.html#sqlalchemy.engine.Engine.has_table" title="sqlalchemy.engine.Engine.has_table"><tt class="xref py py-meth docutils literal"><span class="pre">Engine.has_table()</span></tt></a> method with
an unconditionally quoted name:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">sqlaclchemy</span> <span class="kn">import</span> <span class="n">create_engine</span>
<span class="kn">from</span> <span class="nn">sqlalchemy.sql.elements</span> <span class="kn">import</span> <span class="n">quoted_name</span>
<span class="n">engine</span> <span class="o">=</span> <span class="n">create_engine</span><span class="p">(</span><span class="s">"oracle+cx_oracle://some_dsn"</span><span class="p">)</span>
<span class="n">engine</span><span class="o">.</span><span class="n">has_table</span><span class="p">(</span><span class="n">quoted_name</span><span class="p">(</span><span class="s">"some_table"</span><span class="p">,</span> <span class="bp">True</span><span class="p">))</span></pre></div>
</div>
<p>The above logic will run the “has table” logic against the Oracle backend,
passing the name exactly as <tt class="docutils literal"><span class="pre">"some_table"</span></tt> without converting to
upper case.</p>
<div class="versionadded">
<p><span>New in version 0.9.0.</span></p>
</div>
</dd></dl>
<dl class="class">
<dt id="sqlalchemy.sql.expression.UnaryExpression">
<em class="property">class </em><tt class="descclassname">sqlalchemy.sql.expression.</tt><tt class="descname">UnaryExpression</tt><big>(</big><em>element</em>, <em>operator=None</em>, <em>modifier=None</em>, <em>type_=None</em>, <em>negate=None</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.UnaryExpression" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference internal" href="#sqlalchemy.sql.expression.ColumnElement" title="sqlalchemy.sql.expression.ColumnElement"><tt class="xref py py-class docutils literal"><span class="pre">sqlalchemy.sql.expression.ColumnElement</span></tt></a></p>
<p>Define a ‘unary’ expression.</p>
<p>A unary expression has a single column expression
and an operator. The operator can be placed on the left
(where it is called the ‘operator’) or right (where it is called the
‘modifier’) of the column expression.</p>
<p><a class="reference internal" href="#sqlalchemy.sql.expression.UnaryExpression" title="sqlalchemy.sql.expression.UnaryExpression"><tt class="xref py py-class docutils literal"><span class="pre">UnaryExpression</span></tt></a> is the basis for several unary operators
including those used by <a class="reference internal" href="#sqlalchemy.sql.expression.desc" title="sqlalchemy.sql.expression.desc"><tt class="xref py py-func docutils literal"><span class="pre">desc()</span></tt></a>, <a class="reference internal" href="#sqlalchemy.sql.expression.asc" title="sqlalchemy.sql.expression.asc"><tt class="xref py py-func docutils literal"><span class="pre">asc()</span></tt></a>, <a class="reference internal" href="#sqlalchemy.sql.expression.distinct" title="sqlalchemy.sql.expression.distinct"><tt class="xref py py-func docutils literal"><span class="pre">distinct()</span></tt></a>,
<a class="reference internal" href="#sqlalchemy.sql.expression.nullsfirst" title="sqlalchemy.sql.expression.nullsfirst"><tt class="xref py py-func docutils literal"><span class="pre">nullsfirst()</span></tt></a> and <a class="reference internal" href="#sqlalchemy.sql.expression.nullslast" title="sqlalchemy.sql.expression.nullslast"><tt class="xref py py-func docutils literal"><span class="pre">nullslast()</span></tt></a>.</p>
<dl class="method">
<dt id="sqlalchemy.sql.expression.UnaryExpression.compare">
<tt class="descname">compare</tt><big>(</big><em>other</em>, <em>**kw</em><big>)</big><a class="headerlink" href="#sqlalchemy.sql.expression.UnaryExpression.compare" title="Permalink to this definition">¶</a></dt>
<dd><p>Compare this <a class="reference internal" href="#sqlalchemy.sql.expression.UnaryExpression" title="sqlalchemy.sql.expression.UnaryExpression"><tt class="xref py py-class docutils literal"><span class="pre">UnaryExpression</span></tt></a> against the given
<a class="reference internal" href="#sqlalchemy.sql.expression.ClauseElement" title="sqlalchemy.sql.expression.ClauseElement"><tt class="xref py py-class docutils literal"><span class="pre">ClauseElement</span></tt></a>.</p>
</dd></dl>
</dd></dl>
</div>
</div>
</div>
<div id="docs-bottom-navigation" class="docs-navigation-links">
Previous:
<a href="expression_api.html" title="previous chapter">SQL Statements and Expressions API</a>
Next:
<a href="selectable.html" title="next chapter">Selectables, Tables, FROM objects</a>
<div id="docs-copyright">
© <a href="../copyright.html">Copyright</a> 2007-2014, the SQLAlchemy authors and contributors.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.2b1.
</div>
</div>
</div>
</body>
</html>