From: drh Date: Wed, 14 Aug 2002 00:08:12 +0000 (+0000) Subject: Update documentation to better explain the typelessness of SQLite and to X-Git-Tag: version-3.6.10~5363 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=fbe4375cae82c7a5c100fe88e7fffbb28a586c06;p=thirdparty%2Fsqlite.git Update documentation to better explain the typelessness of SQLite and to describe the distinction between text and numeric data. (CVS 711) FossilOrigin-Name: 4ff0f578eca4a8672cf570923e6c015c3ba6b9f4 --- diff --git a/main.mk b/main.mk index aca99211a4..deaa3d75e4 100644 --- a/main.mk +++ b/main.mk @@ -299,6 +299,9 @@ download.html: $(TOP)/www/download.tcl omitted.html: $(TOP)/www/omitted.tcl tclsh $(TOP)/www/omitted.tcl >omitted.html +datatypes.html: $(TOP)/www/datatypes.tcl + tclsh $(TOP)/www/datatypes.tcl >datatypes.html + # Files to be published on the website. # @@ -320,7 +323,8 @@ DOC = \ faq.html \ formatchng.html \ conflict.html \ - omitted.html + omitted.html \ + datatypes.html doc: $(DOC) mkdir -p doc diff --git a/manifest b/manifest index e7b4faaea7..1b4dc12fd2 100644 --- a/manifest +++ b/manifest @@ -1,5 +1,5 @@ -C Make\sthe\sdistinction\sbetween\stext\sand\snumeric\sdata.\s(CVS\s710) -D 2002-08-13T23:02:57 +C Update\sdocumentation\sto\sbetter\sexplain\sthe\stypelessness\sof\sSQLite\sand\sto\ndescribe\sthe\sdistinction\sbetween\stext\sand\snumeric\sdata.\s(CVS\s711) +D 2002-08-14T00:08:13 F Makefile.in 6291a33b87d2a395aafd7646ee1ed562c6f2c28c F Makefile.linux-gcc b86a99c493a5bfb402d1d9178dcdc4bd4b32f906 F README f1de682fbbd94899d50aca13d387d1b3fd3be2dd @@ -14,7 +14,7 @@ F doc/report1.txt a031aaf37b185e4fa540223cb516d3bccec7eeac F install-sh 9d4de14ab9fb0facae2f48780b874848cbf2f895 F libtool c56e618713c9510a103bda6b95f3ea3900dcacd6 F ltmain.sh e9ed72eb1d690f447c13945eaf69e28af531eda1 -F main.mk 34e976d914ac76ba90a93d2b7c41c1a7498e8c59 +F main.mk 6f0f1cfd611e5ead3e7487b0e8b60ccb17d9fc0b F publish.sh a7a8d23e6525bd25d4f5ba9b0fc6edc107d94050 F spec.template 238f7db425a78dc1bb7682e56e3834c7270a3f5e F sqlite.1 83f4a9d37bdf2b7ef079a82d54eaf2e3509ee6ea @@ -131,19 +131,21 @@ F www/c_interface.tcl fb87b825b9032b9aa941694c5c9c5aee9424467e F www/changes.tcl df6f06b1aa97ef285c744bf19ec3efddf707b05f F www/conflict.tcl 81dd21f9a679e60aae049e9dd8ab53d59570cda2 F www/crosscompile.tcl 3622ebbe518927a3854a12de51344673eb2dd060 +F www/datatypes.tcl c18a57dd02ba12bbede52f24ae9325f7fc1bf463 F www/download.tcl 29aa6679ca29621d10613f60ebbbda18f4b91c49 F www/dynload.tcl 02eb8273aa78cfa9070dd4501dca937fb22b466c F www/faq.tcl e5a752ff431a8408ae24a91ab88ded2dfe699e16 F www/formatchng.tcl b4449e065d2da38b6563bdf12cf46cfe1d4d765e -F www/index.tcl 47945cc79706e9f2caf797330412c112d54ad72b -F www/lang.tcl 8c3d0bda030f110c754b5edbad75eddf5dbe2ed1 +F www/index.tcl 9af69527a26895ec56ad920d4c51541c3e5643a6 +F www/lang.tcl 902f677258ee63dd8f6677b54118f354a1d824b6 F www/mingw.tcl f1c7c0a7f53387dd9bb4f8c7e8571b7561510ebc +F www/omitted.tcl 7a6d6598e6a6a09bf54a02e0aff0f29e407d9f11 F www/opcode.tcl 33c5f2061a05c5d227c72b84c080b3bf74c74f8b F www/speed.tcl 7fc83f1b018e1ecc451838449542c3079ed12425 F www/sqlite.tcl ae3dcfb077e53833b59d4fcc94d8a12c50a44098 F www/tclsqlite.tcl 1db15abeb446aad0caf0b95b8b9579720e4ea331 F www/vdbe.tcl 2013852c27a02a091d39a766bc87cff329f21218 -P 92c403f485390bbd83a5be472e61c974f76d46b1 -R 4eff7fd5f3310391432b7a4cfb68c2be +P 310ac4fbaf0ed63f98bfacb55259960be03b0c8b +R 66d58d14066d17fd95f1b8c2d419e072 U drh -Z 8efada5c2bc32cebfca6eea0d127d8d7 +Z caee8504007932315996b27a5456db2c diff --git a/manifest.uuid b/manifest.uuid index fded00607f..cbccd3f550 100644 --- a/manifest.uuid +++ b/manifest.uuid @@ -1 +1 @@ -310ac4fbaf0ed63f98bfacb55259960be03b0c8b \ No newline at end of file +4ff0f578eca4a8672cf570923e6c015c3ba6b9f4 \ No newline at end of file diff --git a/www/datatypes.tcl b/www/datatypes.tcl new file mode 100644 index 0000000000..d15db1b4b4 --- /dev/null +++ b/www/datatypes.tcl @@ -0,0 +1,199 @@ +# +# Run this script to generated a datatypes.html output file +# +set rcsid {$Id: datatypes.tcl,v 1.1 2002/08/14 00:08:13 drh Exp $} + +puts { + + Datatypes In SQLite + + +

+Datatypes In SQLite +

+} +puts "

+(This page was last modified on [lrange $rcsid 3 4] UTC) +

" + +puts {

1.0   Typelessness

+

+SQLite is "typeless". This means that you can store any +kind of data you want in any column of any table, regardless of the +declared datatype of that column. +(See the one exception to this rule in section 2.0 below.) +This behavior is a feature, not +a bug. A database is suppose to store and retrieve data and it +should not matter to the database what format that data is in. +The strong typing system found in most other SQL engines and +codified in the SQL language spec is a misfeature - +it is an example of the implementation showing through into the +interface. SQLite seeks to overcome this misfeature by allowing +you to store any kind of data into any kind of column and by +allowing flexibility in the specification of datatypes. +

+ +

+A datatype to SQLite is any sequence of zero or more names +optionally followed by a parenthesized lists of one or two +signed integers. Notice in particular that a datatype may +be zero or more names. That means that an empty +string is a valid datatype as far as SQLite is concerned. +So you can declare tables where the datatype of each column +is left unspecified, like this: +

+ +
+CREATE TABLE ex1(a,b,c);
+
+ +

+Even though SQLite allows the datatype to be omitted, it is +still a good idea to include it in your CREATE TABLE statements, +since the data type often serves as a good hint to other +programmers about what you intend to put in the column. And +if you ever port your code to another database engine, that +other engine will probably require a datatype of some kind. +SQLite accepts all the usual datatypes. For example: +

+ +
+CREATE TABLE ex2(
+  a VARCHAR(10),
+  b NVARCHAR(15),
+  c TEXT,
+  d INTEGER,
+  e FLOAT,
+  f BOOLEAN,
+  g CLOB,
+  h BLOB,
+  i TIMESTAMP,
+  j NUMERIC(10,5)
+  k VARYING CHARACTER (24),
+  l NATIVE VARYING CHAR(16)
+);
+
+ +

+And so forth. Basically any sequence of names optionally followed by +one or two signed integers in parentheses will do. +

+ +

2.0   The INTEGER PRIMARY KEY

+ +

+One exception to the typelessness of SQLite is a column whose type +is INTEGER PRIMARY KEY. (And you must use "INTEGER" not "INT". +A column of type INT PRIMARY KEY is typeless just like any other.) +INTEGER PRIMARY KEY columns must contain a 32-bit signed integer. Any +attempt to insert non-integer data will result in an error. +

+ +

+INTEGER PRIMARY KEY columns can be used to implement the equivalent +of AUTOINCREMENT. If you try to insert a NULL into an INTEGER PRIMARY +KEY column, the column will actually be filled with a integer that is +one greater than the largest key already in the table. Or if the +largest key is 2147483647, then the column will be filled with a +random integer. Either way, the INTEGER PRIMARY KEY column will be +assigned a unique integer. You can retrieve this integer using +the sqlite_last_insert_rowid() API function or using the +last_insert_rowid() SQL function is a subsequent SELECT statement. +

+ +

3.0   Comparison and Sort Order

+ +

+SQLite is typeless for the purpose of deciding what data is allowed +to be stored in a column. But some notion of type comes into play +when sorting and comparing data. For these purposes, a column or +an expression can be one of two types: numeric and text. +The sort or comparison may give different results depending on which +type of data is being sorted or compared. +

+ +

+If data is of type text then the comparison is determined by +the standard C data comparison functions memcmp() or +strcmp(). The comparison looks at bytes from two inputs one +by one and returns the first non-zero difference. +String are '\000' terminated so shorter +strings sort before longer strings, as you would expect. +

+ +

+For numeric data, this situation is more complex. If both strings +being compared look like well-formed numbers, then they are converted +into floating point values using atof() and compared numerically. +If one input is not a well-formed number but the other is, then the +number is considered to be less than the non-number. If neither inputs +is a well-formed number, then strcmp() is used to do the +comparison. +

+ +

+Do not be confused by the fact that a column might have a "numeric" +datatype. This does not mean that the column can contain only numbers. +It merely means that if the column does contain a number, that number +will sort in numerical order. +

+ +

+For both text and numeric values, NULL sorts before any other value. +A comparison of any value against NULL using operators like "<" or +">=" is always false. +

+ +

4.0   How SQLite Determines Datatypes

+ +

+For SQLite version 2.6.3 and earlier, all values used the numeric datatype. +The text datatype appears in version 2.7.0 and later. In the sequel it +is assumed that you are using version 2.7.0 or later of SQLite. +

+ +

+For an expression, the datatype of the result is often determined by +the outermost operator. For example, arithmatic operators ("+", "*", "%") +always return a numeric results. The string concatenation operator +("||") returns a text result. And so forth. If you are ever in doubt +about the datatype of an expression you can use the special typeof() +SQL function to determine what the datatype is. For example: +

+ +
+sqlite> SELECT typeof('abc'+123);
+numeric
+sqlite> SELECT typeof('abc'||123);
+text
+
+ +

+For table columns, the datatype is determined by the datatype declaration +of the CREATE TABLE statement. The datatype is text if and only if +the type declaration contains one or more of the following strings: +

+ +
+BLOB
+CHAR
+CLOB
+TEXT +
+ +

+The search for these strings in the type declaration is case insensitive, +of course. If any of the above strings occur anywhere in the type +declaration, then the datatype of the column is text. Otherwise the +datatype is numeric. Note in particular that the datatype for columns +with an empty type declaration is numeric. +

+} + +puts { +

+

+Back to the SQLite Home Page +

+ +} diff --git a/www/index.tcl b/www/index.tcl index efbc62c05e..8fbacd6509 100644 --- a/www/index.tcl +++ b/www/index.tcl @@ -1,7 +1,7 @@ # # Run this TCL script to generate HTML for the index.html file. # -set rcsid {$Id: index.tcl,v 1.64 2002/08/13 20:45:41 drh Exp $} +set rcsid {$Id: index.tcl,v 1.65 2002/08/14 00:08:13 drh Exp $} puts { SQLite: An SQL Database Engine In A C Library @@ -132,6 +132,7 @@ puts {

Documentation

  • Frequently Asked Questions are available online.
  • Information on the sqlite command-line utility.
    • +
  • SQLite is typeless.
  • The SQL Language subset understood by SQLite.
  • The C/C++ Interface.
  • The Tcl Binding to SQLite.
    • diff --git a/www/lang.tcl b/www/lang.tcl index f5d3099c95..cc0099d76e 100644 --- a/www/lang.tcl +++ b/www/lang.tcl @@ -1,7 +1,7 @@ # # Run this Tcl script to generate the sqlite.html file. # -set rcsid {$Id: lang.tcl,v 1.41 2002/06/25 01:09:13 drh Exp $} +set rcsid {$Id: lang.tcl,v 1.42 2002/08/14 00:08:13 drh Exp $} puts { @@ -282,7 +282,9 @@ for use by the engine.

    Each column definition is the name of the column followed by the datatype for that column, then one or more optional column constraints. -The datatype for the column is (usually) ignored and may be omitted. +SQLite is typeless. +The datatype for the column does not constraint what data may be put +in that column. All information is stored as null-terminated strings. The UNIQUE constraint causes an index to be created on the specified columns. This index must contain unique keys. diff --git a/www/omitted.tcl b/www/omitted.tcl new file mode 100644 index 0000000000..e14b94bcf6 --- /dev/null +++ b/www/omitted.tcl @@ -0,0 +1,91 @@ +# +# Run this script to generated a omitted.html output file +# +set rcsid {$Id: omitted.tcl,v 1.1 2002/08/14 00:08:14 drh Exp $} + +puts { + + SQL Features That SQLite Does Not Implement + + +

    +SQL Features That SQLite Does Not Implement +

    +} +puts "

    +(This page was last modified on [lrange $rcsid 3 4] UTC) +

    " + +puts { +

    +Rather than try to list all the features of SQL92 that SQLite does +support, it is much easier to list those that it does not. +The following are features of of SQL92 that SQLite does not implement. +

    + + +} + +proc feature {name desc} { + puts "" + puts "" +} + +feature {RIGHT and FULL OUTER JOIN} { + LEFT OUTER JOIN is implemented, but not RIGHT OUTER JOIN or + FULL OUTER JOIN. +} + +feature {CHECK constraints} { + CHECK constraints are parsed but they are not enforced. + NOT NULL and UNIQUE constraints are enforced, however. +} + +feature {FOREIGN KEY constraints} { + FOREIGN KEY constraints are parsed but are ignored. +} + +feature {GRANT and REVOKE} { + Since SQLite reads and writes an ordinary disk file, the + only access permissions that can be applied are the normal + file access permissions of the underlying operating system. + The GRANT and REVOKE commands commonly found on client/server + RDBMSes are not implemented because they would be meaningless + for an embedded database engine. +} + +feature {DELETE, INSERT, and UPDATE on VIEWs} { + VIEWs in SQLite are read-only. But you can create a trigger + that fires on an attempt to DELETE, INSERT, or UPDATE a view and do + what you need in the body of the trigger. +} + +feature {ALTER TABLE} { + To change a table you have to delete it (saving its contents to a temporary + table) and recreate it from scratch. +} + +feature {The COUNT(DISTINCT X) function} { + You can accomplish the same thing using a subquery, like this:
    +   SELECT count(x) FROM (SELECT DISTINCT x FROM tbl); +} + +feature {Variable subqueries} { + Subqueries must be static. They are evaluated only once. They must not, + therefore, refer to variables in the containing query. +} + +puts { +
    $name$desc
    + +

    +If you find other SQL92 features that SQLite does not support, please +send e-mail to drh@hwaci.com so they +can be added to this list. +

    +

    +

    +Back to the SQLite Home Page +

    + +}