root/campo-sirio
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
campo-sirio/libraries/SQLite3/sqlite-doc-3330000/lang_expr.html
Alessandro Bonazzi 5c7aa8c1c0 Patch level : 12.0 no-patch 
Files correlati     :
Commento            :

Aggiunta documentazione di sqlite 3
2020-11-29 00:32:36 +01:00

911 lines
42 KiB
HTML
Raw Blame History

<!DOCTYPE html>
<html><head>
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<link href="sqlite.css" rel="stylesheet">
<title>SQL Language Expressions</title>
<!-- path= -->
</head>
<body>
<div class=nosearch>
<a href="index.html">
<img class="logo" src="images/sqlite370_banner.gif" alt="SQLite" border="0">
</a>
<div><!-- IE hack to prevent disappearing logo --></div>
<div class="tagline desktoponly">
Small. Fast. Reliable.<br>Choose any three.
</div>
<div class="menu mainmenu">
<ul>
<li><a href="index.html">Home</a>
<li class='mobileonly'><a href="javascript:void(0)" onclick='toggle_div("submenu")'>Menu</a>
<li class='wideonly'><a href='about.html'>About</a>
<li class='desktoponly'><a href="docs.html">Documentation</a>
<li class='desktoponly'><a href="download.html">Download</a>
<li class='wideonly'><a href='copyright.html'>License</a>
<li class='desktoponly'><a href="support.html">Support</a>
<li class='desktoponly'><a href="prosupport.html">Purchase</a>
<li class='search' id='search_menubutton'>
<a href="javascript:void(0)" onclick='toggle_search()'>Search</a>
</ul>
</div>
<div class="menu submenu" id="submenu">
<ul>
<li><a href='about.html'>About</a>
<li><a href='docs.html'>Documentation</a>
<li><a href='download.html'>Download</a>
<li><a href='support.html'>Support</a>
<li><a href='prosupport.html'>Purchase</a>
</ul>
</div>
<div class="searchmenu" id="searchmenu">
<form method="GET" action="search">
<select name="s" id="searchtype">
<option value="d">Search Documentation</option>
<option value="c">Search Changelog</option>
</select>
<input type="text" name="q" id="searchbox" value="">
<input type="submit" value="Go">
</form>
</div>
</div>
<script>
function toggle_div(nm) {
var w = document.getElementById(nm);
if( w.style.display=="block" ){
w.style.display = "none";
}else{
w.style.display = "block";
}
}
function toggle_search() {
var w = document.getElementById("searchmenu");
if( w.style.display=="block" ){
w.style.display = "none";
} else {
w.style.display = "block";
setTimeout(function(){
document.getElementById("searchbox").focus()
}, 30);
}
}
function div_off(nm){document.getElementById(nm).style.display="none";}
window.onbeforeunload = function(e){div_off("submenu");}
/* Disable the Search feature if we are not operating from CGI, since */
/* Search is accomplished using CGI and will not work without it. */
if( !location.origin || !location.origin.match || !location.origin.match(/http/) ){
document.getElementById("search_menubutton").style.display = "none";
}
/* Used by the Hide/Show button beside syntax diagrams, to toggle the */
function hideorshow(btn,obj){
var x = document.getElementById(obj);
var b = document.getElementById(btn);
if( x.style.display!='none' ){
x.style.display = 'none';
b.innerHTML='show';
}else{
x.style.display = '';
b.innerHTML='hide';
}
return false;
}
</script>
</div>
<div class=fancy>
<div class=nosearch>
<div class="fancy_title">
SQL Language Expressions
</div>
<div class="fancy_toc">
<a onclick="toggle_toc()">
<span class="fancy_toc_mark" id="toc_mk">&#x25ba;</span>
Table Of Contents
</a>
<div id="toc_sub"><div class="fancy-toc1"><a href="#syntax">1. Syntax</a></div>
<div class="fancy-toc1"><a href="#operators">2. Operators</a></div>
<div class="fancy-toc1"><a href="#literal_values_constants_">3. Literal Values (Constants)</a></div>
<div class="fancy-toc1"><a href="#parameters">4. Parameters</a></div>
<div class="fancy-toc1"><a href="#the_like_glob_regexp_and_match_operators">5. The LIKE, GLOB, REGEXP, and MATCH operators</a></div>
<div class="fancy-toc1"><a href="#the_between_operator">6. The BETWEEN operator</a></div>
<div class="fancy-toc1"><a href="#the_case_expression">7. The CASE expression</a></div>
<div class="fancy-toc1"><a href="#the_in_and_not_in_operators">8. The IN and NOT IN operators</a></div>
<div class="fancy-toc1"><a href="#table_column_names">9. Table Column Names</a></div>
<div class="fancy-toc1"><a href="#the_exists_operator">10. The EXISTS operator</a></div>
<div class="fancy-toc1"><a href="#subquery_expressions">11. Subquery Expressions</a></div>
<div class="fancy-toc1"><a href="#correlated_subqueries">12. Correlated Subqueries</a></div>
<div class="fancy-toc1"><a href="#cast_expressions">13. CAST expressions</a></div>
<div class="fancy-toc1"><a href="#boolean_expressions">14. Boolean Expressions</a></div>
<div class="fancy-toc1"><a href="#functions">15. Functions</a></div>
</div>
</div>
<script>
function toggle_toc(){
var sub = document.getElementById("toc_sub")
var mk = document.getElementById("toc_mk")
if( sub.style.display!="block" ){
sub.style.display = "block";
mk.innerHTML = "&#x25bc;";
} else {
sub.style.display = "none";
mk.innerHTML = "&#x25ba;";
}
}
</script>
</div>
<h1 id="syntax"><span>1. </span>Syntax</h1>
<p><b><a href="syntax/expr.html">expr:</a></b>
<button id='x1651' onclick='hideorshow("x1651","x1652")'>hide</button></p>
<div id='x1652' class='imgcontainer'>
<img alt="syntax diagram expr" src="images/syntax/expr.gif" />
<p><b><a href="syntax/filter-clause.html">filter-clause:</a></b>
<button id='x1653' onclick='hideorshow("x1653","x1654")'>show</button></p>
<div id='x1654' style='display:none;' class='imgcontainer'>
<img alt="syntax diagram filter-clause" src="images/syntax/filter-clause.gif" />
</div>
<p><b><a href="syntax/literal-value.html">literal-value:</a></b>
<button id='x1655' onclick='hideorshow("x1655","x1656")'>show</button></p>
<div id='x1656' style='display:none;' class='imgcontainer'>
<img alt="syntax diagram literal-value" src="images/syntax/literal-value.gif" />
</div>
<p><b><a href="syntax/over-clause.html">over-clause:</a></b>
<button id='x1657' onclick='hideorshow("x1657","x1658")'>show</button></p>
<div id='x1658' style='display:none;' class='imgcontainer'>
<img alt="syntax diagram over-clause" src="images/syntax/over-clause.gif" />
<p><b><a href="syntax/frame-spec.html">frame-spec:</a></b>
<button id='x1659' onclick='hideorshow("x1659","x1660")'>show</button></p>
<div id='x1660' style='display:none;' class='imgcontainer'>
<img alt="syntax diagram frame-spec" src="images/syntax/frame-spec.gif" />
</div>
<p><b><a href="syntax/ordering-term.html">ordering-term:</a></b>
<button id='x1661' onclick='hideorshow("x1661","x1662")'>show</button></p>
<div id='x1662' style='display:none;' class='imgcontainer'>
<img alt="syntax diagram ordering-term" src="images/syntax/ordering-term.gif" />
</div>
</div>
<p><b><a href="syntax/raise-function.html">raise-function:</a></b>
<button id='x1663' onclick='hideorshow("x1663","x1664")'>show</button></p>
<div id='x1664' style='display:none;' class='imgcontainer'>
<img alt="syntax diagram raise-function" src="images/syntax/raise-function.gif" />
</div>
<p><b><a href="syntax/select-stmt.html">select-stmt:</a></b>
<button id='x1665' onclick='hideorshow("x1665","x1666")'>show</button></p>
<div id='x1666' style='display:none;' class='imgcontainer'>
<img alt="syntax diagram select-stmt" src="images/syntax/select-stmt.gif" />
<p><b><a href="syntax/common-table-expression.html">common-table-expression:</a></b>
<button id='x1667' onclick='hideorshow("x1667","x1668")'>show</button></p>
<div id='x1668' style='display:none;' class='imgcontainer'>
<img alt="syntax diagram common-table-expression" src="images/syntax/common-table-expression.gif" />
</div>
<p><b><a href="syntax/compound-operator.html">compound-operator:</a></b>
<button id='x1669' onclick='hideorshow("x1669","x1670")'>show</button></p>
<div id='x1670' style='display:none;' class='imgcontainer'>
<img alt="syntax diagram compound-operator" src="images/syntax/compound-operator.gif" />
</div>
<p><b><a href="syntax/join-clause.html">join-clause:</a></b>
<button id='x1671' onclick='hideorshow("x1671","x1672")'>show</button></p>
<div id='x1672' style='display:none;' class='imgcontainer'>
<img alt="syntax diagram join-clause" src="images/syntax/join-clause.gif" />
<p><b><a href="syntax/join-constraint.html">join-constraint:</a></b>
<button id='x1673' onclick='hideorshow("x1673","x1674")'>show</button></p>
<div id='x1674' style='display:none;' class='imgcontainer'>
<img alt="syntax diagram join-constraint" src="images/syntax/join-constraint.gif" />
</div>
<p><b><a href="syntax/join-operator.html">join-operator:</a></b>
<button id='x1675' onclick='hideorshow("x1675","x1676")'>show</button></p>
<div id='x1676' style='display:none;' class='imgcontainer'>
<img alt="syntax diagram join-operator" src="images/syntax/join-operator.gif" />
</div>
</div>
<p><b><a href="syntax/ordering-term.html">ordering-term:</a></b>
<button id='x1677' onclick='hideorshow("x1677","x1678")'>show</button></p>
<div id='x1678' style='display:none;' class='imgcontainer'>
<img alt="syntax diagram ordering-term" src="images/syntax/ordering-term.gif" />
</div>
<p><b><a href="syntax/result-column.html">result-column:</a></b>
<button id='x1679' onclick='hideorshow("x1679","x1680")'>show</button></p>
<div id='x1680' style='display:none;' class='imgcontainer'>
<img alt="syntax diagram result-column" src="images/syntax/result-column.gif" />
</div>
<p><b><a href="syntax/table-or-subquery.html">table-or-subquery:</a></b>
<button id='x1681' onclick='hideorshow("x1681","x1682")'>show</button></p>
<div id='x1682' style='display:none;' class='imgcontainer'>
<img alt="syntax diagram table-or-subquery" src="images/syntax/table-or-subquery.gif" />
</div>
<p><b><a href="syntax/window-defn.html">window-defn:</a></b>
<button id='x1683' onclick='hideorshow("x1683","x1684")'>show</button></p>
<div id='x1684' style='display:none;' class='imgcontainer'>
<img alt="syntax diagram window-defn" src="images/syntax/window-defn.gif" />
<p><b><a href="syntax/frame-spec.html">frame-spec:</a></b>
<button id='x1685' onclick='hideorshow("x1685","x1686")'>show</button></p>
<div id='x1686' style='display:none;' class='imgcontainer'>
<img alt="syntax diagram frame-spec" src="images/syntax/frame-spec.gif" />
</div>
</div>
</div>
<p><b><a href="syntax/type-name.html">type-name:</a></b>
<button id='x1687' onclick='hideorshow("x1687","x1688")'>show</button></p>
<div id='x1688' style='display:none;' class='imgcontainer'>
<img alt="syntax diagram type-name" src="images/syntax/type-name.gif" />
<p><b><a href="syntax/signed-number.html">signed-number:</a></b>
<button id='x1689' onclick='hideorshow("x1689","x1690")'>show</button></p>
<div id='x1690' style='display:none;' class='imgcontainer'>
<img alt="syntax diagram signed-number" src="images/syntax/signed-number.gif" />
</div>
</div>
</div>
<a name="binaryops"></a>
<h1 id="operators"><span>2. </span>Operators</h1>
<p>SQLite understands the following binary operators, in order from
highest to lowest precedence:</p>
<blockquote><pre>
<font color="#2c2cf0"><big>||
* / %
+ -
&lt;&lt; &gt;&gt; &amp; |
&lt; &lt;= &gt; &gt;=
= == != &lt;&gt; </big>IS IS NOT IN LIKE GLOB MATCH REGEXP
AND
OR</font>
</pre></blockquote>
<p>Supported unary prefix operators are these:</p>
<blockquote><pre>
<font color="#2c2cf0"><big>- + ~ NOT</big></font>
</pre></blockquote>
<a name="collateop"></a>
<p>The COLLATE operator is a unary postfix
operator that assigns a <a href="datatype3.html#collation">collating sequence</a> to an expression.
The COLLATE operator has a higher precedence (binds more tightly) than any
binary operator and any unary prefix operator except "~".
(COLLATE and "~" are associative so their binding order does not matter.)
The collating sequence set by the COLLATE operator overrides the
collating sequence determined by the COLLATE clause in a table
<a href="lang_createtable.html#tablecoldef">column definition</a>.
See the <a href="datatype3.html#collation">detailed discussion on collating sequences</a>
in the <a href="datatype3.html">Datatype In SQLite3</a> document for additional information.
</p>
<p>The unary operator <font color="#2c2cf0"><big>+</big></font> is a no-op. It can be applied
to strings, numbers, blobs or NULL and it always returns a result
with the same value as the operand.</p>
<p>Note that there are two variations of the equals and not equals
operators. Equals can be either
<font color="#2c2cf0"><big>=</big></font> or <font color="#2c2cf0"><big>==</big></font>.
The non-equals operator can be either
<font color="#2c2cf0"><big>!=</big></font> or <font color="#2c2cf0"><big>&lt;&gt;</big></font>.
The <font color="#2c2cf0"><big>||</big></font> operator is "concatenate" - it joins together
the two strings of its operands.
The operator <font color="#2c2cf0"><big>%</big></font> outputs the integer value of its left
operand modulo its right operand. In other words, the
operator <font color="#2c2cf0"><big>%</big></font> works in SQLite the same as it does
in ANSI-C.</p>
<p>The result of any binary operator is either a numeric value or
NULL, except for the <font color="#2c2cf0"><big>||</big></font> concatenation operator which always
evaluates to either NULL or a text value.</p><a name="isisnot"></a>
<p>The <font color="#2c2cf0"><big>IS</big></font> and <font color="#2c2cf0"><big>IS NOT</big></font> operators work
like <font color="#2c2cf0"><big>=</big></font> and <font color="#2c2cf0"><big>!=</big></font> except when one or both of the
operands are NULL. In this case, if both operands are NULL, then the
IS operator evaluates to 1 (true) and the IS NOT operator evaluates
to 0 (false). If one operand is NULL and the other is not, then the
IS operator evaluates to 0 (false) and the IS NOT operator is 1 (true).
It is not possible for an IS or IS NOT expression to evaluate to NULL.
Operators <font color="#2c2cf0"><big>IS</big></font> and <font color="#2c2cf0"><big>IS NOT</big></font> have the same
precedence as <font color="#2c2cf0"><big>=</big></font>.<a name="litvalue"></a>
</p><h1 id="literal_values_constants_"><span>3. </span>Literal Values (Constants)</h1>
<p>
A literal value represents a constant.
Literal values may be integers, floating point numbers, strings,
BLOBs, or NULLs.
</p><p>
The syntax for integer and floating point literals (collectively
"numeric literals") is shown by the following diagram:</p>
<p><b><a href="syntax/numeric-literal.html">numeric-literal:</a></b></p><div class='imgcontainer'>
<img alt="syntax diagram numeric-literal" src="images/syntax/numeric-literal.gif"></img>
</div>
<p>
If a numeric literal has a decimal point or an exponentiation
clause or if its magnitude is less than -9223372036854775808 or
greater than 9223372036854775807, then it is a floating point literal.
Otherwise is it is an integer literal.
The "E" character that begins the exponentiation
clause of a floating point literal can be either upper or lower case.
The "." character is always used
as the decimal point even if the locale setting specifies "," for
this role - the use of "," for the decimal point would result in
syntactic ambiguity.
<a name="hexint"></a>
</p><p>Hexadecimal integer literals follow the C-language notation of
"0x" or "0X" followed by hexadecimal digits.
For example, 0x1234 means the same as 4660
and 0x8000000000000000 means the same as -9223372036854775808.
Hexadecimal integer literals are interpreted as 64-bit
two's-complement integers and are thus limited
to sixteen significant digits of precision.
Support for hexadecimal integers was added to SQLite
version 3.8.6 (2014-08-15).
For backwards compatibility, the "0x" hexadecimal integer
notation is only understood by the SQL language parser, not by the
type conversions routines.
String variables that
contain text formatted like hexadecimal integers are not
interpreted as hexadecimal integers when coercing the string value
into an integer due to a <a href="lang_expr.html#castexpr">CAST expression</a> or for a <a href="datatype3.html#affinity">column affinity</a>
transformation or prior to performing a numeric operation or for
any other run-time conversions. When coercing a
string value in the format of a hexadecimal integer into an integer
value, the conversion process stops when the 'x' character is seen
so the resulting integer value is always zero.
SQLite only understands the hexadecimal integer notation when it
appears in the SQL statement text, not when it appears as
part of the content of the database.
</p><p> A string constant is formed by enclosing the
string in single quotes ('). A single quote within the string can
be encoded by putting two single quotes in a row - as in Pascal.
C-style escapes using the backslash character are not supported because
they are not standard SQL.
</p><p> BLOB literals are string literals containing hexadecimal data and
preceded by a single "x" or "X" character. Example: X'53514C697465'
</p><p>
A literal value can also be the token "NULL".
</p>
<a name="varparam"></a>
<h1 id="parameters"><span>4. </span>Parameters</h1>
<p>
A "variable" or "parameter" token
specifies a placeholder in the expression for a
value that is filled in at runtime using the
<a href="c3ref/bind_blob.html">sqlite3_bind()</a> family of C/C++ interfaces.
Parameters can take several forms:
</p>
<blockquote>
<table>
<tr>
<td align="right" valign="top"><b>?</b><i>NNN</i></td><td width="20"></td>
<td>A question mark followed by a number <i>NNN</i> holds a spot for the
NNN-th parameter. NNN must be between 1 and <a href="limits.html#max_variable_number">SQLITE_MAX_VARIABLE_NUMBER</a>.
</td>
</tr>
<tr>
<td align="right" valign="top"><b>?</b></td><td width="20"></td>
<td>A question mark that is not followed by a number creates a parameter
with a number one greater than the largest parameter number already assigned.
If this means the parameter number is greater than
<a href="limits.html#max_variable_number">SQLITE_MAX_VARIABLE_NUMBER</a>, it is an error.
This parameter format is provided for compatibility with other database
engines. But because it is easy to miscount the question marks, the
use of this parameter format is discouraged. Programmers are encouraged
to use one of the symbolic formats below or the ?NNN format above instead.
</td>
</tr>
<tr>
<td align="right" valign="top"><b>:</b><i>AAAA</i></td><td width="20"></td>
<td>A colon followed by an identifier name holds a spot for a
<a href="c3ref/bind_parameter_name.html">named parameter</a> with the name :AAAA.
Named parameters are also numbered. The number assigned is one greater than
the largest parameter number already assigned. If this means the parameter
would be assigned a number greater than <a href="limits.html#max_variable_number">SQLITE_MAX_VARIABLE_NUMBER</a>, it is
an error. To avoid confusion, it is best to avoid mixing named and numbered
parameters.</td>
</tr>
<tr>
<td align="right" valign="top"><b>@</b><i>AAAA</i></td><td width="20"></td>
<td>An "at" sign works exactly like a colon, except that the name of
the parameter created is @AAAA.</td>
</tr>
<tr>
<td align="right" valign="top"><b>$</b><i>AAAA</i></td><td width="20"></td>
<td>A dollar-sign followed by an identifier name also holds a spot for a named
parameter with the name $AAAA. The identifier name in this case can include
one or more occurrences of "::" and a suffix enclosed in "(...)" containing
any text at all. This syntax is the form of a variable name in the
<a href="http://www.tcl-lang.org/">Tcl programming language</a>. The presence
of this syntax results from the fact that SQLite is really a
<a href="tclsqlite.html">Tcl extension</a> that has escaped into the wild.</td>
</tr>
</table>
</blockquote>
<p>Parameters that are not assigned values using
<a href="c3ref/bind_blob.html">sqlite3_bind()</a> are treated
as NULL. The <a href="c3ref/bind_parameter_index.html">sqlite3_bind_parameter_index()</a> interface can be used
to translate a symbolic parameter name into its equivalent numeric index.</p>
<p>The maximum parameter number is set at compile-time by
the <a href="limits.html#max_variable_number">SQLITE_MAX_VARIABLE_NUMBER</a> macro. An individual <a href="c3ref/sqlite3.html">database connection</a>
D can reduce its maximum parameter number below the compile-time maximum
using the <a href="c3ref/limit.html">sqlite3_limit</a>(D, <a href="c3ref/c_limit_attached.html#sqlitelimitvariablenumber">SQLITE_LIMIT_VARIABLE_NUMBER</a>,...) interface.
</p>
<a name="like"></a>
<h1 id="the_like_glob_regexp_and_match_operators"><span>5. </span>The LIKE, GLOB, REGEXP, and MATCH operators</h1>
<p>The LIKE operator does a pattern matching comparison. The operand
to the right of the LIKE operator contains the pattern and the left hand
operand contains the string to match against the pattern.
A percent symbol ("%") in the LIKE pattern matches any
sequence of zero or more characters in the string. An underscore
("_") in the LIKE pattern matches any single character in the
string. Any other character matches itself or its lower/upper case
equivalent (i.e. case-insensitive matching).
<u>Important Note:</u> SQLite only
understands upper/lower case for ASCII characters by default. The
LIKE operator is case sensitive by default for unicode characters that are
beyond the ASCII range. For example,
the expression <b>'a'&nbsp;LIKE&nbsp;'A'</b>
is TRUE but <b>'&aelig;'&nbsp;LIKE&nbsp;'&AElig;'</b> is FALSE.
The ICU extension to SQLite includes an enhanced version of the
LIKE operator that does case folding across all unicode characters.</p>
<p>If the optional ESCAPE clause is present, then the expression
following the ESCAPE keyword must evaluate to a string consisting of
a single character. This character may be used in the LIKE pattern
to include literal percent or underscore characters. The escape
character followed by a percent symbol (%), underscore (_), or a second
instance of the escape character itself matches a
literal percent symbol, underscore, or a single escape character,
respectively.
</p><p>The infix LIKE operator is implemented by calling the
application-defined SQL functions <a href="lang_corefunc.html#like">like(<i>Y</i>,<i>X</i>)</a> or
<a href="lang_corefunc.html#like">like(<i>Y</i>,<i>X</i>,<i>Z</i>)</a>.</p>
<p>The LIKE operator can be made case sensitive using the
<a href="pragma.html#pragma_case_sensitive_like">case_sensitive_like pragma</a>.</p>
<a name="glob"></a>
<p>The GLOB operator is similar to LIKE but uses the Unix
file globbing syntax for its wildcards. Also, GLOB is case
sensitive, unlike LIKE. Both GLOB and LIKE may be preceded by
the NOT keyword to invert the sense of the test. The infix GLOB
operator is implemented by calling the function
<a href="lang_corefunc.html#glob">glob(<i>Y</i>,<i>X</i>)</a> and can be modified by overriding
that function.</p>
<a name="regexp"></a>
<p>The REGEXP operator is a special syntax for the regexp()
user function. No regexp() user function is defined by default
and so use of the REGEXP operator will normally result in an
error message. If an <a href="appfunc.html">application-defined SQL function</a> named "regexp"
is added at run-time, then the "<i>X</i> REGEXP <i>Y</i>" operator will
be implemented as a call to "regexp(<i>Y</i>,<i>X</i>)".</p>
<a name="match"></a>
<p>The MATCH operator is a special syntax for the match()
application-defined function. The default match() function implementation
raises an exception and is not really useful for anything.
But extensions can override the match() function with more
helpful logic.</p>
<a name="between"></a>
<h1 id="the_between_operator"><span>6. </span>The BETWEEN operator</h1>
<p>The BETWEEN operator is logically equivalent to a pair of comparisons.
"<i>x</i> <b>BETWEEN</b> <i>y</i> <b>AND</b> <i>z</i>" is
equivalent to
"<i>x</i><b>&gt;=</b><i>y</i> <b>AND</b> <i>x</i><b>&lt;=</b><i>z</i>" except
that with BETWEEN, the <i>x</i> expression is only evaluated once.
The precedence of the BETWEEN operator is the same as the precedence
as operators <b>==</b> and <b>!=</b> and <b>LIKE</b> and groups left to right.
<a name="case"></a>
</p><h1 id="the_case_expression"><span>7. </span>The CASE expression</h1>
<p>A CASE expression serves a role similar to IF-THEN-ELSE in other
programming languages.
</p><p>The optional expression that occurs in between the CASE keyword and the
first WHEN keyword is called the "base" expression. There are two
fundamental forms
of the CASE expression: those with a base expression and those without.
</p><p>In a CASE without a base expression, each WHEN expression is evaluated
and the result treated as a boolean, starting with the leftmost and continuing
to the right. The result of the CASE expression is the evaluation of the THEN
expression that corresponds to the first WHEN expression that evaluates to
true. Or, if none of the WHEN expressions evaluate to true, the result of
evaluating the ELSE expression, if any. If there is no ELSE expression and
none of the WHEN expressions are true, then the overall result is NULL.
</p><p>A NULL result is considered untrue when evaluating WHEN terms.
</p><p>In a CASE with a base expression, the base expression is evaluated just
once and the result is compared against the evaluation of each WHEN
expression from left to right. The result of the CASE expression is the
evaluation of the THEN expression that corresponds to the first WHEN
expression for which the comparison is true. Or, if none of the WHEN
expressions evaluate to a value equal to the base expression, the result
of evaluating the ELSE expression, if any. If there is no ELSE expression and
none of the WHEN expressions produce a result equal to the base expression,
the overall result is NULL.
</p><p>When comparing a base expression against a WHEN expression, the same
collating sequence, affinity, and NULL-handling rules apply as if the
base expression and WHEN expression are respectively the left- and
right-hand operands of an <big><b>=</b></big> operator.</p>
<p>If the base
expression is NULL then the result of the CASE is always the result
of evaluating the ELSE expression if it exists, or NULL if it does not.
</p><p>Both forms of the CASE expression use lazy, or short-circuit,
evaluation.
</p><p>The only difference between the following two CASE expressions is that
the <i>x</i> expression is evaluated exactly once in the first example but
might be evaluated multiple times in the second:
</p><ul><pre>
<li>CASE x WHEN w1 THEN r1 WHEN w2 THEN r2 ELSE r3 END
</li><li>CASE WHEN x=w1 THEN r1 WHEN x=w2 THEN r2 ELSE r3 END
</li></pre></ul>
<p>The built-in <a href="lang_corefunc.html#iif">iif(x,y,z) SQL function</a> is logically
equivalent to "CASE WHEN x THEN y ELSE z END". The iif() function
is found in SQL Server and is included in SQLite for compatibility.
Some developers prefer the iif() function because it is more
concise.
<a name="in_op"></a>
</p><h1 id="the_in_and_not_in_operators"><span>8. </span>The IN and NOT IN operators</h1>
<p>The IN and NOT IN operators take an expression on the
left and a list of values or a subquery on the right.
When the right operand of an IN or NOT IN operator is a subquery, the
subquery must have the same number of columns as there are columns in
the <a href="rowvalue.html">row value</a> of the left operand. The subquery on the
right of an IN or NOT IN operator must be a scalar subquery if the left
expression is not a <a href="rowvalue.html">row value</a> expression.
If the right operand of an IN or NOT IN operator is a list of values,
each of those values must be scalars and the left expression must also
be a scalar.
The right-hand side of an IN or NOT IN operator can be a
table <i>name</i> or <a href="vtab.html#tabfunc2">table-valued function</a> <i>name</i> in which
case the right-hand side is understood to be subquery of
the form "(SELECT * FROM <i>name</i>)".
When the right operand is an empty set, the result of IN is false and the
result of NOT IN is true, regardless of the left operand and even if the
left operand is NULL.
</p><p>The result of an IN or NOT IN operator is determined by the following
matrix:
</p><blockquote>
<table border="1">
<tr>
<th>Left operand <br>is NULL
</th><th>Right operand <br>contains NULL
</th><th>Right operand <br>is an empty set
</th><th>Left operand found <br>within right operand
</th><th>Result of <br>IN operator
</th><th>Result of <br>NOT IN operator
</th></tr><tr>
<td align="center">no
</td><td align="center">no
</td><td align="center">no
</td><td align="center">no
</td><td align="center">false
</td><td align="center">true
</td></tr><tr>
<td align="center">does not matter
</td><td align="center">no
</td><td align="center">yes
</td><td align="center">no
</td><td align="center">false
</td><td align="center">true
</td></tr><tr>
<td align="center">no
</td><td align="center">does not matter
</td><td align="center">no
</td><td align="center">yes
</td><td align="center">true
</td><td align="center">false
</td></tr><tr>
<td align="center">no
</td><td align="center">yes
</td><td align="center">no
</td><td align="center">no
</td><td align="center">NULL
</td><td align="center">NULL
</td></tr><tr>
<td align="center">yes
</td><td align="center">does not matter
</td><td align="center">no
</td><td align="center">does not matter
</td><td align="center">NULL
</td><td align="center">NULL
</td></tr></table>
</blockquote>
<p>Note that SQLite allows the parenthesized list of scalar values on
the right-hand side of an IN or NOT IN operator to be an empty list but
most other SQL database database engines and the SQL92 standard require
the list to contain at least one element.</p>
<h1 id="table_column_names"><span>9. </span>Table Column Names</h1>
<p>A column name can be any of the names defined in the <a href="lang_createtable.html">CREATE TABLE</a>
statement or one of the following special identifiers: "<b>ROWID</b>",
"<b>OID</b>", or "<b>_ROWID_</b>".
The three special identifiers describe the
unique integer key (the <a href="lang_createtable.html#rowid">rowid</a>) associated with every
row of every table and so are not available on <a href="withoutrowid.html">WITHOUT ROWID</a> tables.
The special identifiers only refer to the row key if the <a href="lang_createtable.html">CREATE TABLE</a>
statement does not define a real column with the same name.
The rowid can be used anywhere a regular
column can be used.</p>
<a name="exists_op"></a>
<h1 id="the_exists_operator"><span>10. </span>The EXISTS operator</h1>
<p>The EXISTS operator always evaluates to one of the integer values 0
and 1. If executing the SELECT statement specified as the right-hand
operand of the EXISTS operator would return one or more rows, then the
EXISTS operator evaluates to 1. If executing the SELECT would return
no rows at all, then the EXISTS operator evaluates to 0.
</p><p>The number of columns in each row returned by the SELECT statement
(if any) and the specific values returned have no effect on the results
of the EXISTS operator. In particular, rows containing NULL values are
not handled any differently from rows without NULL values.
<a name="subq"></a>
</p><h1 id="subquery_expressions"><span>11. </span>Subquery Expressions</h1>
<p>A <a href="lang_select.html">SELECT</a> statement enclosed in parentheses is a subquery.
All types of SELECT statement, including
aggregate and compound SELECT queries (queries with keywords like
UNION or EXCEPT) are allowed as scalar subqueries.
The value of a subquery expression is the first row of the result
from the enclosed <a href="lang_select.html">SELECT</a> statement.
The value of a subquery expression is NULL if the enclosed
<a href="lang_select.html">SELECT</a> statement returns no rows.
</p><p>A subquery that returns a single column is a scalar subquery and can
be used most anywhere.
A subquery that returns two or more columns is a <a href="rowvalue.html">row value</a>
subquery and can only be used as the operand of a comparison operator.
<a name="cosub"></a>
</p><h1 id="correlated_subqueries"><span>12. </span>Correlated Subqueries</h1>
<p>A <a href="lang_select.html">SELECT</a> statement used as either a scalar subquery or as the
right-hand operand of an IN, NOT IN or EXISTS expression may contain
references to columns in the outer query. Such a subquery is known as
a correlated subquery. A correlated subquery is reevaluated each time
its result is required. An uncorrelated subquery is evaluated only once
and the result reused as necessary.
<a name="castexpr"></a>
</p><h1 id="cast_expressions"><span>13. </span>CAST expressions</h1>
<p>A CAST expression of the form "CAST(<i>expr</i> AS <i>type-name</i>)"
is used to convert the value of <i>expr</i> to
a different <a href="datatype3.html#storageclasses">storage class</a> specified by <span class='yyterm'>type-name</span>.
A CAST conversion is similar to the conversion that takes
place when a <a href="datatype3.html#affinity">column affinity</a> is applied to a value except that with
the CAST operator the conversion always takes place even if the conversion
lossy and irreversible, whereas column affinity only changes the data type
of a value if the change is lossless and reversible.
</p><p>If the value of <i>expr</i> is NULL, then the result of the CAST
expression is also NULL. Otherwise, the storage class of the result
is determined by applying the <a href="datatype3.html#affname">rules for determining column affinity</a> to
the <span class='yyterm'>type-name</span>.
</p><blockquote>
<table border="1">
<tr>
<th> Affinity of <span class='yyterm'><nobr>type-name</nobr></span>
</th><th> Conversion Processing
</th></tr><tr>
<td> NONE
</td><td> Casting a value to a <span class='yyterm'>type-name</span> with no affinity
causes the value to
be converted into a BLOB. Casting to a BLOB consists of first casting
the value to TEXT in the <a href="pragma.html#pragma_encoding">encoding</a> of the database connection, then
interpreting the resulting byte sequence as a BLOB instead of as TEXT.
</td></tr><tr>
<td> TEXT
</td><td> To cast a BLOB value to TEXT, the sequence of bytes that make up the
BLOB is interpreted as text encoded using the database encoding.
<p>
Casting an INTEGER or REAL value into TEXT renders the value as if via
<a href="c3ref/mprintf.html">sqlite3_snprintf()</a> except that the resulting TEXT uses the <a href="pragma.html#pragma_encoding">encoding</a> of
the database connection.
</p></td></tr><tr>
<td> REAL
</td><td> When casting a BLOB value to a REAL, the value is first converted to
TEXT.
<p>When casting a TEXT value to REAL, the longest possible prefix of
the value that can be interpreted as a real number is extracted from
the TEXT value and the remainder ignored. Any leading spaces in the
TEXT value are ignored when converging from TEXT to REAL. If there is
no prefix that can be interpreted as a real number, the result of the
conversion is 0.0.
</p></td></tr><tr>
<td> INTEGER
</td><td> When casting a BLOB value to INTEGER, the value is first converted to
TEXT.
<p>When casting a TEXT value to INTEGER, the longest possible prefix of
the value that can be interpreted as an integer number is extracted from
the TEXT value and the remainder ignored. Any leading spaces in the
TEXT value when converting from TEXT to INTEGER are ignored. If there
is no prefix that can be interpreted as an integer number, the result
of the conversion is 0. If the prefix integer is greater than
+9223372036854775807 then the result of the cast is exactly
+9223372036854775807. Similarly, if the prefix integer is
less than -9223372036854775808 then the result of the cast is
exactly -9223372036854775808.
</p><p>When casting to INTEGER, if the text looks like a floating point
value with an exponent, the exponent will be ignored because it is
no part of the integer prefix. For example,
"(CAST '123e+5' AS INTEGER)" results in 123, not in 12300000.
</p><p> The CAST operator understands decimal
integers only &mdash; conversion of <a href="lang_expr.html#hexint">hexadecimal integers</a> stops
at the "x" in the "0x" prefix of the hexadecimal integer string
and thus result of the CAST is always zero.
</p><p>A cast of a REAL value into an INTEGER results in the integer
between the REAL value and zero that is closest to the REAL value.
If a REAL is greater than the greatest possible signed
integer (+9223372036854775807) then the result is the greatest possible
signed integer and if the REAL is less than the least possible signed
integer (-9223372036854775808) then the result is the least possible
signed integer.
</p><p>Prior to SQLite version 3.8.2 (2013-12-06),
casting a REAL value greater than
+9223372036854775807.0 into an integer resulted in the most negative
integer, -9223372036854775808. This behavior was meant to emulate the
behavior of x86/x64 hardware when doing the equivalent cast.
</p></td></tr><tr>
<td> NUMERIC
</td><td> Casting a TEXT or BLOB value into NUMERIC yields either an INTEGER or
a REAL result.
If the input text looks like an integer (there is no decimal point nor
exponent) and the value is small enough to fit in a 64-bit signed integer,
then the result will be INTEGER.
Input text that looks like floating point (there is a decimal point and/or
an exponent) and the text describes a value that
can be losslessly converted back and forth between IEEE 754 64-bit float and a
51-bit signed integer, then the result is INTEGER.
(In the previous sentence, a 51-bit integer is specified since that is one
bit less than the length of the mantissa of an IEEE 754 64-bit float and
thus provides a 1-bit of margin for the text-to-float conversion operation.)
Any text input that describes a value outside the range of a 64-bit
signed integer yields a REAL result.
<p> Casting a REAL or INTEGER value to NUMERIC is a no-op, even if a real
value could be losslessly converted to an integer.
</p></td></tr>
</table>
</blockquote>
<p>Note that the result from casting any non-BLOB value into a
BLOB and the result from casting any BLOB value into a non-BLOB value
may be different depending on whether the database <a href="pragma.html#pragma_encoding">encoding</a> is UTF-8,
UTF-16be, or UTF-16le.
<a name="booleanexpr"></a>
</p><h1 id="boolean_expressions"><span>14. </span>Boolean Expressions</h1>
<p>The SQL language features several contexts where an expression is
evaluated and the result converted to a boolean (true or false) value. These
contexts are:
</p><ul>
<li> the WHERE clause of a SELECT, UPDATE or DELETE statement,
</li><li> the ON or USING clause of a join in a SELECT statement,
</li><li> the HAVING clause of a SELECT statement,
</li><li> the WHEN clause of an SQL trigger, and
</li><li> the WHEN clause or clauses of some CASE expressions.
</li></ul>
<p>To convert the results of an SQL expression to a boolean value, SQLite
first casts the result to a NUMERIC value in the same way as a
<a href="lang_expr.html#castexpr">CAST expression</a>. A numeric zero value (integer value 0 or real
value 0.0) is considered to be false. A NULL value is still NULL.
All other values are considered true.
</p><p>For example, the values NULL, 0.0, 0, 'english' and '0' are all considered
to be false. Values 1, 1.0, 0.1, -0.1 and '1english' are considered to
be true.
</p><p>Beginning with SQLite 3.23.0 (2018-04-02), SQLite recognizes the
identifiers "TRUE" and "FALSE" as boolean literals, if and only if those
identifiers are not already used for some other meaning. If there already
exists columns or tables or other objects named TRUE or FALSE, then for
the sake of backwards compatibility, the TRUE and FALSE identifiers refer
to those other objects, not to the boolean values.
</p><p>The boolean identifiers TRUE and FALSE are usually just aliases for
the integer values 1 and 0, respectively. However, if TRUE or FALSE
occur on the right-hand side of an IS operator, then they form new
unary postfix operators "IS TRUE" and "IS FALSE" which test the boolean
value of the operand on the left.
</p><h1 id="functions"><span>15. </span>Functions</h1>
<p>SQLite supports many <a href="lang_corefunc.html">simple</a>, <a href="lang_aggfunc.html">aggregate</a>,
and <a href="windowfunctions.html">window</a>
SQL functions. For presentation purposes, simple functions are further
subdivided into <a href="lang_corefunc.html">core functions</a>, <a href="lang_datefunc.html">date-time functions</a>,
and <a href="json1.html">JSON functions</a>.
Applications can add new functions, written in C/C++, using the
<a href="c3ref/create_function.html">sqlite3_create_function()</a> interface.
</p>
<p>
The main expression bubble diagram above shows a single syntax for
all function invocations. But this is merely to simplify the expression
bubble diagram. In reality, each type of function has a slightly different
syntax, shown below. The function invocation syntax shown in the main
expression bubble diagram is the union of the three syntaxes shown here:
<p><b><a href="syntax/simple-function-invocation.html">simple-function-invocation:</a></b></p><div class='imgcontainer'>
<img alt="syntax diagram simple-function-invocation" src="images/syntax/simple-function-invocation.gif"></img>
</div>
<p><b><a href="syntax/aggregate-function-invocation.html">aggregate-function-invocation:</a></b></p><div class='imgcontainer'>
<img alt="syntax diagram aggregate-function-invocation" src="images/syntax/aggregate-function-invocation.gif"></img>
</div>
<p><b><a href="syntax/window-function-invocation.html">window-function-invocation:</a></b></p><div class='imgcontainer'>
<img alt="syntax diagram window-function-invocation" src="images/syntax/window-function-invocation.gif"></img>
</div>
</p><p>
The OVER clause is required for <a href="windowfunctions.html">window functions</a> and is prohibited
otherwise. The DISTINCT keyword is only allowed in <a href="lang_aggfunc.html">aggregate functions</a>.
The FILTER clause may not appear on a <a href="lang_corefunc.html">simple function</a>.
</p><p>It is possible to have an aggregate function with the same name as a
simple function, as long as the number of arguments for the two forms of the
function are different. For example, the <a href="lang_aggfunc.html#maxggunc">max()</a> function with a
single argument is an aggregate and the <a href="lang_corefunc.html#maxoreunc">max()</a> function with two or more
arguments is a simple function. Aggregate functions can usually also
be used as window functions.
</p>
Reference in New Issue View Git Blame Copy Permalink