Documentation Source Text

Check-in [d508b9e21c]
Login

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Additional cleanup in the SQL language documentation.
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: d508b9e21cd6cd2b22f571f00906c5cb7bf4b03d
User & Date: drh 2009-12-13 23:03:41
Context
2009-12-14
17:41
For the requirements matrix, scan evidence marks in the original source code, not in the amalgamation. Updates to SQL comment documentation. check-in: dca51f132e user: drh tags: trunk
2009-12-13
23:03
Additional cleanup in the SQL language documentation. check-in: d508b9e21c user: drh tags: trunk
22:20
Updates to the SQL language documentation - mostly to fix requirements marks. check-in: b80a69c002 user: drh tags: trunk
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to pages/lang.in.

1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
....
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435

1436
1437
1438
1439
1440
1441
1442
....
2155
2156
2157
2158
2159
2160
2161
2162
2163
2164
2165
2166
2167
2168
2169
2170
2171
2172
2173
2174
2175
2176
2177
2178
2179
....
2501
2502
2503
2504
2505
2506
2507
2508
2509
2510
2511
2512
2513
2514
2515
....
2557
2558
2559
2560
2561
2562
2563
2564
2565
2566
2567
2568
2569
2570
2571
2572
2573
....
2774
2775
2776
2777
2778
2779
2780
2781
2782
2783
2784
2785
2786
2787
2788
<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.

<tcl>hd_puts "^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 it's lower/upper case
equivalent (i.e. case-insensitive matching).)^  (A bug: ^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.)<p>"</tcl>

................................................................................
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>

<tcl>hd_fragment between BETWEEN</tcl>
<h3>The BETWEEN operator</h3>
<p>^(The BETWEEN operator is equivalent to a pair of comparisons.
"<i>a</i> <b>BETWEEN</b> <i>b</i> <b>AND</b> <i>c</i>" is 
equivalent to 
"<i>a</i><b>&gt;=</b><i>b</i> <b>AND</b> <i>a</i><b>&lt;=</b><i>c</i>".)^

^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.

<tcl>hd_fragment case {CASE expression}</tcl>
<h3>The CASE expression</h3>
<p>A CASE expression serves a role similar to IF-THEN-ELSE in other
programming languages.  ^WHEN expressions are evaluated from left to
................................................................................
  arbitrary.
}

funcdef {max(X)} {*maxAggFunc *agg_max {max() aggregate function}} {
  ^The max() aggregate function
  returns the maximum value of all values in the group.
  ^The maximum value is the value that would be returned last in an
  ORDER BY on the same column.  ^NULL is returned if and only if there are
  no non-NULL values in the group.
}

funcdef {min(X)} {*minAggFunc *agg_min {min() aggregate function}} {
  ^The min() aggregate function
  returns the minimum non-NULL value of all values in the group.
  ^The minimum value is the first non-NULL value that would appear
  in an ORDER BY of the column.
  ^NULL is returned if and only if there are no non-NULL values in the 
  group.
}

funcdef {sum(X) total(X)} {
  *sumFunc *sum *total
  {sum() aggregate function}
  {total() aggregate function}
} {
................................................................................

<h3>Restrictions on UPDATE Statements Within CREATE TRIGGER</h3>

<p>^There are additional syntax restrictions on UPDATE statements that
occur within the body of a [CREATE TRIGGER] statement.  ^The <i>table-name</i>
of the UPDATE must be unqualified. 
^(In other words, the <i>database-name</i><b>.</b> prefix 
on the table name of the UPDATE is not allowed within triggers. 
^The table to be updated must be in the same
database as the table to which the trigger is attached.</p>

<p>^The INDEXED BY and NOT INDEXED clauses are not allowed on UPDATE
statements within triggers.</p>

<p>^The LIMIT clause for UPDATE is unsupported within triggers.</p>
................................................................................

<p>^VACUUM only works on the main database.
It is not possible to VACUUM an attached database file.</p>

<p>^The VACUUM command will fail if there is an active transaction.
^The VACUUM command is a no-op for in-memory databases.</p>

<p>^As of SQLite version 3.1, an alternative to using the VACUUM command
is auto-vacuum mode, enabled using the 
[auto_vacuum] pragma.  ^When [auto_vacuum] is enabled for a database, 
large deletes cause
the size of the database file to shrink.  However, [auto_vacuum]
also causes excess fragmentation of the database file.  ^And [auto_vacuum]
does not compact partially filled pages of the database as VACUUM
does.</p>

<p>^The [page_size] and/or [auto_vacuum] mode of a database can be changed
................................................................................
<p>
<blockquote>
<table>
<tr>	<td valign="top"><b>'keyword'</b></td><td width="20"></td>
	<td>^A keyword in single quotes is a string literal.</td></tr>

<tr>	<td valign="top"><b>"keyword"</b></td><td></td>
	<td>^A keyword in double-quotes is an identifier</td></tr>

<tr>	<td valign="top"><b>&#91;keyword&#93;</b></td><td></td>
	<td>^A keyword enclosed in square brackets is 
        an identifier.  This is not standard SQL.  This quoting mechanism
        is used by MS Access and SQL Server and is included in SQLite for
        compatibility.</td></tr>








|







 







|
|

|
>







 







|
|







|
|







 







|







 







|

|







 







|







1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
....
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
....
2156
2157
2158
2159
2160
2161
2162
2163
2164
2165
2166
2167
2168
2169
2170
2171
2172
2173
2174
2175
2176
2177
2178
2179
2180
....
2502
2503
2504
2505
2506
2507
2508
2509
2510
2511
2512
2513
2514
2515
2516
....
2558
2559
2560
2561
2562
2563
2564
2565
2566
2567
2568
2569
2570
2571
2572
2573
2574
....
2775
2776
2777
2778
2779
2780
2781
2782
2783
2784
2785
2786
2787
2788
2789
<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.

<tcl>hd_puts "^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).)^  (A bug: ^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.)<p>"</tcl>

................................................................................
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>

<tcl>hd_fragment between BETWEEN</tcl>
<h3>The BETWEEN operator</h3>
<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.

<tcl>hd_fragment case {CASE expression}</tcl>
<h3>The CASE expression</h3>
<p>A CASE expression serves a role similar to IF-THEN-ELSE in other
programming languages.  ^WHEN expressions are evaluated from left to
................................................................................
  arbitrary.
}

funcdef {max(X)} {*maxAggFunc *agg_max {max() aggregate function}} {
  ^The max() aggregate function
  returns the maximum value of all values in the group.
  ^The maximum value is the value that would be returned last in an
  ORDER BY on the same column.  ^Aggregate max() returns NULL 
  if and only if there are no non-NULL values in the group.
}

funcdef {min(X)} {*minAggFunc *agg_min {min() aggregate function}} {
  ^The min() aggregate function
  returns the minimum non-NULL value of all values in the group.
  ^The minimum value is the first non-NULL value that would appear
  in an ORDER BY of the column.
  ^Aggregate min() returns NULL if and only if there are no non-NULL
  values in the group.
}

funcdef {sum(X) total(X)} {
  *sumFunc *sum *total
  {sum() aggregate function}
  {total() aggregate function}
} {
................................................................................

<h3>Restrictions on UPDATE Statements Within CREATE TRIGGER</h3>

<p>^There are additional syntax restrictions on UPDATE statements that
occur within the body of a [CREATE TRIGGER] statement.  ^The <i>table-name</i>
of the UPDATE must be unqualified. 
^(In other words, the <i>database-name</i><b>.</b> prefix 
on the table name of the UPDATE is not allowed within triggers.)^
^The table to be updated must be in the same
database as the table to which the trigger is attached.</p>

<p>^The INDEXED BY and NOT INDEXED clauses are not allowed on UPDATE
statements within triggers.</p>

<p>^The LIMIT clause for UPDATE is unsupported within triggers.</p>
................................................................................

<p>^VACUUM only works on the main database.
It is not possible to VACUUM an attached database file.</p>

<p>^The VACUUM command will fail if there is an active transaction.
^The VACUUM command is a no-op for in-memory databases.</p>

<p>^(As of SQLite version 3.1, an alternative to using the VACUUM command
is auto-vacuum mode, enabled using the 
[auto_vacuum] pragma.)^  ^When [auto_vacuum] is enabled for a database, 
large deletes cause
the size of the database file to shrink.  However, [auto_vacuum]
also causes excess fragmentation of the database file.  ^And [auto_vacuum]
does not compact partially filled pages of the database as VACUUM
does.</p>

<p>^The [page_size] and/or [auto_vacuum] mode of a database can be changed
................................................................................
<p>
<blockquote>
<table>
<tr>	<td valign="top"><b>'keyword'</b></td><td width="20"></td>
	<td>^A keyword in single quotes is a string literal.</td></tr>

<tr>	<td valign="top"><b>"keyword"</b></td><td></td>
	<td>^A keyword in double-quotes is an identifier.</td></tr>

<tr>	<td valign="top"><b>&#91;keyword&#93;</b></td><td></td>
	<td>^A keyword enclosed in square brackets is 
        an identifier.  This is not standard SQL.  This quoting mechanism
        is used by MS Access and SQL Server and is included in SQLite for
        compatibility.</td></tr>