doc.go 91.1 KB
Newer Older
cznic's avatar
A+C  
cznic committed
1
// Copyright 2014 The ql Authors. All rights reserved.
cznic's avatar
cznic committed
2 3 4 5 6 7
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.

//MAYBE set operations
//MAYBE +=, -=, ...

cznic's avatar
cznic committed
8 9
//TODO verify there's a graceful failure for a 2G+ blob on a 32 bit machine.

10
// Package ql implements a pure Go embedded SQL database engine.
cznic's avatar
cznic committed
11
//
12 13
// QL is a member of the SQL family of languages. It is less complex and less
// powerful than SQL (whichever specification SQL is considered to be).
cznic's avatar
cznic committed
14
//
cznic's avatar
cznic committed
15 16
// Change list
//
17 18 19 20 21
// 2016-07-29: Release v1.0.6 enables alternatively using = instead of == for
// equality oparation.
//
// 	https://github.com/cznic/ql/issues/131
//
22 23 24 25 26
// 2016-07-11: Release v1.0.5 undoes vendoring of lldb. QL now uses stable lldb
// (github.com/cznic/lldb).
//
// 	https://github.com/cznic/ql/issues/128
//
cznic's avatar
cznic committed
27 28 29 30
// 2016-07-06: Release v1.0.4 fixes a panic when closing the WAL file.
//
//	https://github.com/cznic/ql/pull/127
//
cznic's avatar
cznic committed
31 32
// 2016-04-03: Release v1.0.3 fixes a data race.
//
cznic's avatar
cznic committed
33
//	https://github.com/cznic/ql/issues/126
cznic's avatar
cznic committed
34
//
cznic's avatar
cznic committed
35 36
// 2016-03-23: Release v1.0.2 vendors github.com/cznic/exp/lldb and
// github.com/camlistore/go4/lock.
cznic's avatar
cznic committed
37
//
cznic's avatar
cznic committed
38 39 40 41 42 43
// 2016-03-17: Release v1.0.1 adjusts for latest goyacc. Parser error messages
// are improved and changed, but their exact form is not considered a API
// change.
//
// 2016-03-05: The current version has been tagged v1.0.0.
//
cznic's avatar
cznic committed
44 45 46
// 2015-06-15: To improve compatibility with other SQL implementations, the
// count built-in aggregate function now accepts * as its argument.
//
cznic's avatar
cznic committed
47 48
// 2015-05-29: The execution planner was rewritten from scratch. It should use
// indices in all places where they were used before plus in some additional
cznic's avatar
cznic committed
49 50 51 52
// situations.  It is possible to investigate the plan using the newly added
// EXPLAIN statement.  The QL tool is handy for such analysis. If the planner
// would have used an index, but no such exists, the plan includes hints in
// form of copy/paste ready CREATE INDEX statements.
cznic's avatar
cznic committed
53 54 55 56 57 58
//
// The planner is still quite simple and a lot of work on it is yet ahead. You
// can help this process by filling an issue with a schema and query which
// fails to use an index or indices when it should, in your opinion. Bonus
// points for including output of `ql 'explain <query>'`.
//
59 60 61 62 63 64 65 66 67 68
// 2015-05-09: The grammar of the CREATE INDEX statement now accepts an
// expression list instead of a single expression, which was further limited to
// just a column name or the built-in id().  As a side effect, composite
// indices are now functional. However, the values in the expression-list style
// index are not yet used by other statements or the statement/query planner.
// The composite index is useful while having UNIQUE clause to check for
// semantically duplicate rows before they get added to the table or when such
// a row is mutated using the UPDATE statement and the expression-list style
// index tuple of the row is thus recomputed.
//
69 70 71 72 73
// 2015-05-02: The Schema field of table __Table now correctly reflects any
// column constraints and/or defaults. Also, the (*DB).Info method now has that
// information provided in new ColumInfo fields NotNull, Constraint and
// Default.
//
cznic's avatar
cznic committed
74 75
// 2015-04-20: Added support for {LEFT,RIGHT,FULL} [OUTER] JOIN.
//
cznic's avatar
cznic committed
76
// 2015-04-18: Column definitions can now have constraints and defaults.
cznic's avatar
cznic committed
77
// Details are discussed in the "Constraints and defaults" chapter below the
cznic's avatar
cznic committed
78 79
// CREATE TABLE statement documentation.
//
cznic's avatar
cznic committed
80 81 82
// 2015-03-06: New built-in functions formatFloat and formatInt. Thanks
// urandom! (https://github.com/urandom)
//
83 84 85
// 2015-02-16: IN predicate now accepts a SELECT statement. See the updated
// "Predicates" section.
//
86 87 88 89 90 91 92
// 2015-01-17: Logical operators || and && have now alternative spellings: OR
// and AND (case insensitive).  AND was a keyword before, but OR is a new one.
// This can possibly break existing queries. For the record, it's a good idea
// to not use any name appearing in, for example, [7] in your queries as the
// list of QL's keywords may expand for gaining better compatibility with
// existing SQL "standards".
//
93 94 95 96 97 98 99 100 101 102 103 104
// 2015-01-12: ACID guarantees were tightened at the cost of performance in
// some cases. The write collecting window mechanism, a formerly used
// implementation detail, was removed. Inserting rows one by one in a
// transaction is now slow. I mean very slow. Try to avoid inserting single
// rows in a transaction. Instead, whenever possible, perform batch updates of
// tens to, say thousands of rows in a single transaction. See also:
// http://www.sqlite.org/faq.html#q19, the discussed synchronization principles
// involved are the same as for QL, modulo minor details.
//
// Note: A side effect is that closing a DB before exiting an application, both
// for the Go API and through database/sql driver, is no more required,
// strictly speaking. Beware that exiting an application while there is an open
cznic's avatar
cznic committed
105
// (uncommitted) transaction in progress means losing the transaction data.
106 107 108 109
// However, the DB will not become corrupted because of not closing it. Nor
// that was the case before, but formerly failing to close a DB could have
// resulted in losing the data of the last transaction.
//
110 111
// 2014-09-21: id() now optionally accepts a single argument - a table name.
//
cznic's avatar
cznic committed
112 113
// 2014-09-01: Added the DB.Flush() method and the LIKE pattern matching
// predicate.
cznic's avatar
cznic committed
114
//
cznic's avatar
cznic committed
115 116 117
// 2014-08-08: The built in functions max and min now accept also time values.
// Thanks opennota! (https://github.com/opennota)
//
118 119
// 2014-06-05: RecordSet interface extended by new methods FirstRow and Rows.
//
120 121
// 2014-06-02: Indices on id() are now used by SELECT statements.
//
cznic's avatar
cznic committed
122 123
// 2014-05-07: Introduction of Marshal, Schema, Unmarshal.
//
124 125
// 2014-04-15:
//
cznic's avatar
cznic committed
126
// Added optional IF NOT EXISTS clause to CREATE INDEX and optional IF EXISTS
127 128
// clause to DROP INDEX.
//
129 130 131 132 133 134
// 2014-04-12:
//
// The column Unique in the virtual table __Index was renamed to IsUnique
// because the old name is a keyword. Unfortunately, this is a breaking change,
// sorry.
//
cznic's avatar
cznic committed
135
// 2014-04-11: Introduction of LIMIT, OFFSET.
cznic's avatar
cznic committed
136
//
cznic's avatar
cznic committed
137 138
// 2014-04-10: Introduction of query rewriting.
//
cznic's avatar
cznic committed
139
// 2014-04-07: Introduction of indices.
cznic's avatar
cznic committed
140
//
141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158
// Building non CGO QL
//
// QL imports zappy[8], a block-based compressor, which speeds up its
// performance by using a C version of the compression/decompression
// algorithms.  If a CGO-free (pure Go) version of QL, or an app using QL, is
// required, please include 'purego' in the -tags option of go
// {build,get,install}. For example:
//
//	$ go get -tags purego github.com/cznic/ql
//
// If zappy was installed before installing QL, it might be necessary to
// rebuild zappy first (or rebuild QL with all its dependencies using the -a
// option):
//
//	$ touch "$GOPATH"/src/github.com/cznic/zappy/*.go
//	$ go install -tags purego github.com/cznic/zappy
//	$ go install github.com/cznic/ql
//
cznic's avatar
cznic committed
159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268
// Notation
//
// The syntax is specified using Extended Backus-Naur Form (EBNF)
//
// 	Production  = production_name "=" [ Expression ] "." .
// 	Expression  = Alternative { "|" Alternative } .
// 	Alternative = Term { Term } .
// 	Term        = production_name | token [ "…" token ] | Group | Option | Repetition .
// 	Group       = "(" Expression ")" .
// 	Option      = "[" Expression "]" .
// 	Repetition  = "{" Expression "}" .
// 	Productions are expressions constructed from terms and the following operators, in increasing precedence
//
// 	|   alternation
// 	()  grouping
// 	[]  option (0 or 1 times)
// 	{}  repetition (0 to n times)
//
// Lower-case production names are used to identify lexical tokens.
// Non-terminals are in CamelCase. Lexical tokens are enclosed in double quotes
// "" or back quotes ``.
//
// The form a … b represents the set of characters from a through b as
// alternatives. The horizontal ellipsis … is also used elsewhere in the spec
// to informally denote various enumerations or code snippets that are not
// further specified.
//
// QL source code representation
//
// QL source code is Unicode text encoded in UTF-8. The text is not
// canonicalized, so a single accented code point is distinct from the same
// character constructed from combining an accent and a letter; those are
// treated as two code points.  For simplicity, this document will use the
// unqualified term character to refer to a Unicode code point in the source
// text.
//
// Each code point is distinct; for instance, upper and lower case letters are
// different characters.
//
// Implementation restriction: For compatibility with other tools, the parser
// may disallow the NUL character (U+0000) in the statement.
//
// Implementation restriction: A byte order mark is disallowed anywhere in QL
// statements.
//
// Characters
//
// The following terms are used to denote specific character classes
//
//  newline        = . // the Unicode code point U+000A
//  unicode_char   = . // an arbitrary Unicode code point except newline
//  ascii_letter   = "a" … "z" | "A" … "Z" .
//
// Letters and digits
//
// The underscore character _ (U+005F) is considered a letter.
//
//  letter        = ascii_letter | "_" .
//  decimal_digit = "0" … "9" .
//  octal_digit   = "0" … "7" .
//  hex_digit     = "0" … "9" | "A" … "F" | "a" … "f" .
//
// Lexical elements
//
// Lexical elements are comments, tokens, identifiers, keywords, operators and
// delimiters, integer, floating-point, imaginary, rune and string literals and
// QL parameters.
//
// Comments
//
// There are three forms of comments
//
// Line comments start with the character sequence // or -- and stop at the end
// of the line. A line comment acts like a space.
//
// General comments start with the character sequence /* and continue through
// the character sequence */. A general comment acts like a space.
//
// Comments do not nest.
//
// Tokens
//
// Tokens form the vocabulary of QL. There are four classes: identifiers,
// keywords, operators and delimiters, and literals. White space, formed from
// spaces (U+0020), horizontal tabs (U+0009), carriage returns (U+000D), and
// newlines (U+000A), is ignored except as it separates tokens that would
// otherwise combine into a single token.
//
// Semicolons
//
// The formal grammar uses semicolons ";" as separators of QL statements. A
// single QL statement or the last QL statement in a list of statements can
// have an optional semicolon terminator. (Actually a separator from the
// following empty statement.)
//
// Identifiers
//
// Identifiers name entities such as tables or record set columns. An
// identifier is a sequence of one or more letters and digits. The first
// character in an identifier must be a letter.
//
//  identifier = letter { letter | decimal_digit } .
//
// For example
//
// 	price
// 	_tmp42
// 	Sales
//
// No identifiers are predeclared, however note that no keyword can be used as
cznic's avatar
cznic committed
269 270 271 272 273
// an identifier.  Identifiers starting with two underscores are used for meta
// data virtual tables names. For forward compatibility, users should generally
// avoid using any identifiers starting with two underscores. For example
//
//	__Column
274
//	__Column2
cznic's avatar
cznic committed
275 276
//	__Index
//	__Table
cznic's avatar
cznic committed
277 278 279 280 281
//
// Keywords
//
// The following keywords are reserved and may not be used as identifiers.
//
cznic's avatar
cznic committed
282 283 284 285 286 287 288 289 290 291 292 293
//	ADD      COLUMN      false     int32   ORDER     uint16
//	ALTER    complex128  float     int64   OUTER     uint32
//	AND      complex64   float32   int8    RIGHT     uint64
//	AS       CREATE      float64   INTO    SELECT    uint8
//	ASC      DEFAULT     FROM      JOIN    SET       UNIQUE
//	BETWEEN  DELETE      GROUP     LEFT    string    UPDATE
//	bigint   DESC        IF        LIMIT   TABLE     VALUES
//	bigrat   DISTINCT    IN        LIKE    time      WHERE
//	blob     DROP        INDEX     NOT     true
//	bool     duration    INSERT    NULL    OR
//	BY       EXISTS      int       OFFSET  TRUNCATE
//	byte     EXPLAIN     int16     ON      uint
cznic's avatar
cznic committed
294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315
//
// Keywords are not case sensitive.
//
// Operators and Delimiters
//
// The following character sequences represent operators, delimiters, and other
// special tokens
//
// 	+    &    &&    ==    !=    (    )
// 	-    |    ||    <     <=    [    ]
// 	*    ^          >     >=    ,    ;
// 	/    <<         =           .
// 	%    >>         !
// 	     &^
//
// Operators consisting of more than one character are referred to by names in
// the rest of the documentation
//
//  andand = "&&" .
//  andnot = "&^" .
//  lsh    = "<<" .
//  le     = "<=" .
316
//  eq     = "==" | "=" .
cznic's avatar
cznic committed
317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526
//  ge     = ">=" .
//  neq    = "!=" .
//  oror   = "||" .
//  rsh    = ">>" .
//
// Integer literals
//
// An integer literal is a sequence of digits representing an integer constant.
// An optional prefix sets a non-decimal base: 0 for octal, 0x or 0X for
// hexadecimal.  In hexadecimal literals, letters a-f and A-F represent values
// 10 through 15.
//
//  int_lit     = decimal_lit | octal_lit | hex_lit .
//  decimal_lit = ( "1" … "9" ) { decimal_digit } .
//  octal_lit   = "0" { octal_digit } .
//  hex_lit     = "0" ( "x" | "X" ) hex_digit { hex_digit } .
//
// For example
//
// 	42
// 	0600
// 	0xBadFace
// 	1701411834604692
//
// Floating-point literals
//
// A floating-point literal is a decimal representation of a floating-point
// constant. It has an integer part, a decimal point, a fractional part, and an
// exponent part. The integer and fractional part comprise decimal digits; the
// exponent part is an e or E followed by an optionally signed decimal
// exponent.  One of the integer part or the fractional part may be elided; one
// of the decimal point or the exponent may be elided.
//
//  float_lit = decimals "." [ decimals ] [ exponent ] |
//              decimals exponent |
//              "." decimals [ exponent ] .
//  decimals  = decimal_digit { decimal_digit } .
//  exponent  = ( "e" | "E" ) [ "+" | "-" ] decimals .
//
// For example
//
// 	0.
// 	72.40
// 	072.40  // == 72.40
// 	2.71828
// 	1.e+0
// 	6.67428e-11
// 	1E6
// 	.25
// 	.12345E+5
//
// Imaginary literals
//
// An imaginary literal is a decimal representation of the imaginary part of a
// complex constant. It consists of a floating-point literal or decimal integer
// followed by the lower-case letter i.
//
//  imaginary_lit = (decimals | float_lit) "i" .
//
// For example
//
// 	0i
// 	011i  // == 11i
// 	0.i
// 	2.71828i
// 	1.e+0i
// 	6.67428e-11i
// 	1E6i
// 	.25i
// 	.12345E+5i
//
// Rune literals
//
// A rune literal represents a rune constant, an integer value identifying a
// Unicode code point. A rune literal is expressed as one or more characters
// enclosed in single quotes. Within the quotes, any character may appear
// except single quote and newline. A single quoted character represents the
// Unicode value of the character itself, while multi-character sequences
// beginning with a backslash encode values in various formats.
//
// The simplest form represents the single character within the quotes; since
// QL statements are Unicode characters encoded in UTF-8, multiple
// UTF-8-encoded bytes may represent a single integer value. For instance, the
// literal 'a' holds a single byte representing a literal a, Unicode U+0061,
// value 0x61, while 'ä' holds two bytes (0xc3 0xa4) representing a literal
// a-dieresis, U+00E4, value 0xe4.
//
// Several backslash escapes allow arbitrary values to be encoded as ASCII
// text.  There are four ways to represent the integer value as a numeric
// constant: \x followed by exactly two hexadecimal digits; \u followed by
// exactly four hexadecimal digits; \U followed by exactly eight hexadecimal
// digits, and a plain backslash \ followed by exactly three octal digits. In
// each case the value of the literal is the value represented by the digits in
// the corresponding base.
//
// Although these representations all result in an integer, they have different
// valid ranges. Octal escapes must represent a value between 0 and 255
// inclusive.  Hexadecimal escapes satisfy this condition by construction. The
// escapes \u and \U represent Unicode code points so within them some values
// are illegal, in particular those above 0x10FFFF and surrogate halves.
//
// After a backslash, certain single-character escapes represent special
// values
//
// 	\a   U+0007 alert or bell
// 	\b   U+0008 backspace
// 	\f   U+000C form feed
// 	\n   U+000A line feed or newline
// 	\r   U+000D carriage return
// 	\t   U+0009 horizontal tab
// 	\v   U+000b vertical tab
// 	\\   U+005c backslash
// 	\'   U+0027 single quote  (valid escape only within rune literals)
// 	\"   U+0022 double quote  (valid escape only within string literals)
//
// All other sequences starting with a backslash are illegal inside rune
// literals.
//
//  rune_lit         = "'" ( unicode_value | byte_value ) "'" .
//  unicode_value    = unicode_char | little_u_value | big_u_value | escaped_char .
//  byte_value       = octal_byte_value | hex_byte_value .
//  octal_byte_value = `\` octal_digit octal_digit octal_digit .
//  hex_byte_value   = `\` "x" hex_digit hex_digit .
//  little_u_value   = `\` "u" hex_digit hex_digit hex_digit hex_digit .
//  big_u_value      = `\` "U" hex_digit hex_digit hex_digit hex_digit
//                             hex_digit hex_digit hex_digit hex_digit .
//  escaped_char     = `\` ( "a" | "b" | "f" | "n" | "r" | "t" | "v" | `\` | "'" | `"` ) .
//
// For example
//
// 	'a'
// 	'ä'
// 	'本'
// 	'\t'
// 	'\000'
// 	'\007'
// 	'\377'
// 	'\x07'
// 	'\xff'
// 	'\u12e4'
// 	'\U00101234'
// 	'aa'         // illegal: too many characters
// 	'\xa'        // illegal: too few hexadecimal digits
// 	'\0'         // illegal: too few octal digits
// 	'\uDFFF'     // illegal: surrogate half
// 	'\U00110000' // illegal: invalid Unicode code point
//
// String literals
//
// A string literal represents a string constant obtained from concatenating a
// sequence of characters. There are two forms: raw string literals and
// interpreted string literals.
//
// Raw string literals are character sequences between back quotes ``. Within
// the quotes, any character is legal except back quote. The value of a raw
// string literal is the string composed of the uninterpreted (implicitly
// UTF-8-encoded) characters between the quotes; in particular, backslashes
// have no special meaning and the string may contain newlines. Carriage
// returns inside raw string literals are discarded from the raw string value.
//
// Interpreted string literals are character sequences between double quotes
// "".  The text between the quotes, which may not contain newlines, forms the
// value of the literal, with backslash escapes interpreted as they are in rune
// literals (except that \' is illegal and \" is legal), with the same
// restrictions. The three-digit octal (\nnn) and two-digit hexadecimal (\xnn)
// escapes represent individual bytes of the resulting string; all other
// escapes represent the (possibly multi-byte) UTF-8 encoding of individual
// characters. Thus inside a string literal \377 and \xFF represent a single
// byte of value 0xFF=255, while ÿ, \u00FF, \U000000FF and \xc3\xbf represent
// the two bytes 0xc3 0xbf of the UTF-8 encoding of character U+00FF.
//
//  string_lit             = raw_string_lit | interpreted_string_lit .
//  raw_string_lit         = "`" { unicode_char | newline } "`" .
//  interpreted_string_lit = `"` { unicode_value | byte_value } `"` .
//
// For example
//
// 	`abc`  // same as "abc"
// 	`\n
// 	\n`    // same as "\\n\n\\n"
// 	"\n"
// 	""
// 	"Hello, world!\n"
// 	"日本語"
// 	"\u65e5本\U00008a9e"
// 	"\xff\u00FF"
// 	"\uD800"       // illegal: surrogate half
// 	"\U00110000"   // illegal: invalid Unicode code point
//
// These examples all represent the same string
//
// 	"日本語"                                 // UTF-8 input text
// 	`日本語`                                 // UTF-8 input text as a raw literal
// 	"\u65e5\u672c\u8a9e"                    // the explicit Unicode code points
// 	"\U000065e5\U0000672c\U00008a9e"        // the explicit Unicode code points
// 	"\xe6\x97\xa5\xe6\x9c\xac\xe8\xaa\x9e"  // the explicit UTF-8 bytes
//
// If the statement source represents a character as two code points, such as a
// combining form involving an accent and a letter, the result will be an error
// if placed in a rune literal (it is not a single code point), and will appear
// as two code points if placed in a string literal.
//
// QL parameters
//
// Literals are assigned their values from the respective text representation
// at "compile" (parse) time. QL parameters provide the same functionality as
// literals, but their value is assigned at execution time from an expression
// list passed to DB.Run or DB.Execute. Using '?' or '$' is completely
// equivalent.
//
527
//  ql_parameter = ( "?" | "$" ) "1" … "9" { "0" … "9" } .
cznic's avatar
cznic committed
528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553
//
// For example
//
// 	SELECT DepartmentID
// 	FROM department
// 	WHERE DepartmentID == ?1
// 	ORDER BY DepartmentName;
//
// 	SELECT employee.LastName
// 	FROM department, employee
// 	WHERE department.DepartmentID == $1 && employee.LastName > $2
// 	ORDER BY DepartmentID;
//
// Constants
//
// Keywords 'false' and 'true' (not case sensitive) represent the two possible
// constant values of type bool (also not case sensitive).
//
// Keyword 'NULL' (not case sensitive) represents an untyped constant which is
// assignable to any type. NULL is distinct from any other value of any type.
//
// Types
//
// A type determines the set of values and operations specific to values of
// that type. A type is specified by a type name.
//
cznic's avatar
cznic committed
554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577
//  Type = "bigint"      // http://golang.org/pkg/math/big/#Int
//       | "bigrat"      // http://golang.org/pkg/math/big/#Rat
//       | "blob"        // []byte
//       | "bool"
//       | "byte"        // alias for uint8
//       | "complex128"
//       | "complex64"
//       | "duration"    // http://golang.org/pkg/time/#Duration
//       | "float"       // alias for float64
//       | "float32"
//       | "float64"
//       | "int"         // alias for int64
//       | "int16"
//       | "int32"
//       | "int64"
//       | "int8"
//       | "rune"        // alias for int32
//       | "string"
//       | "time"        // http://golang.org/pkg/time/#Time
//       | "uint"        // alias for uint64
//       | "uint16"
//       | "uint32"
//       | "uint64"
//       | "uint8" .
cznic's avatar
cznic committed
578 579 580 581
//
// Named instances of the boolean, numeric, and string types are keywords. The
// names are not case sensitive.
//
cznic's avatar
cznic committed
582 583 584 585
// Note: The blob type is exchanged between the back end and the API as []byte.
// On 32 bit platforms this limits the size which the implementation can handle
// to 2G.
//
cznic's avatar
cznic committed
586 587 588 589 590
// Boolean types
//
// A boolean type represents the set of Boolean truth values denoted by the
// predeclared constants true and false. The predeclared boolean type is bool.
//
cznic's avatar
cznic committed
591 592 593 594 595 596
// Duration type
//
// A duration type represents the elapsed time between two instants as an int64
// nanosecond count. The representation limits the largest representable
// duration to approximately 290 years.
//
cznic's avatar
cznic committed
597 598 599 600 601 602 603 604 605 606 607 608 609 610
// Numeric types
//
// A numeric type represents sets of integer or floating-point values. The
// predeclared architecture-independent numeric types are
//
// 	uint8       the set of all unsigned  8-bit integers (0 to 255)
// 	uint16      the set of all unsigned 16-bit integers (0 to 65535)
// 	uint32      the set of all unsigned 32-bit integers (0 to 4294967295)
// 	uint64      the set of all unsigned 64-bit integers (0 to 18446744073709551615)
//
// 	int8        the set of all signed  8-bit integers (-128 to 127)
// 	int16       the set of all signed 16-bit integers (-32768 to 32767)
// 	int32       the set of all signed 32-bit integers (-2147483648 to 2147483647)
// 	int64       the set of all signed 64-bit integers (-9223372036854775808 to 9223372036854775807)
cznic's avatar
cznic committed
611
// 	duration    the set of all signed 64-bit integers (-9223372036854775808 to 9223372036854775807)
cznic's avatar
cznic committed
612
//	bigint      the set of all integers
cznic's avatar
cznic committed
613
//
cznic's avatar
cznic committed
614 615
//	bigrat      the set of all rational numbers
//
cznic's avatar
cznic committed
616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631
// 	float32     the set of all IEEE-754 32-bit floating-point numbers
// 	float64     the set of all IEEE-754 64-bit floating-point numbers
//
// 	complex64   the set of all complex numbers with float32 real and imaginary parts
// 	complex128  the set of all complex numbers with float64 real and imaginary parts
//
// 	byte        alias for uint8
// 	float       alias for float64
// 	int         alias for int64
// 	rune        alias for int32
// 	uint        alias for uint64
//
// The value of an n-bit integer is n bits wide and represented using two's
// complement arithmetic.
//
// Conversions are required when different numeric types are mixed in an
cznic's avatar
cznic committed
632
// expression or assignment.
cznic's avatar
cznic committed
633 634 635 636 637 638 639 640 641 642
//
// String types
//
// A string type represents the set of string values. A string value is a
// (possibly empty) sequence of bytes. The case insensitive keyword for the
// string type is 'string'.
//
// The length of a string (its size in bytes) can be discovered using the
// built-in function len.
//
cznic's avatar
cznic committed
643 644 645 646 647 648
// Time types
//
// A time type represents an instant in time with nanosecond precision. Each
// time has associated with it a location, consulted when computing the
// presentation form of the time.
//
cznic's avatar
cznic committed
649 650 651 652
// Predeclared functions
//
// The following functions are implicitly declared
//
653
//	avg          complex     contains    count       date
654
//	day          formatTime  formatFloat formatInt
655 656 657 658 659
//	hasPrefix    hasSuffix   hour        hours       id
//	imag         len         max         min         minute
//	minutes      month       nanosecond  nanoseconds now
//	parseTime    real        second      seconds     since
//	sum          timeIn      weekday     year        yearDay
cznic's avatar
cznic committed
660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697
//
// Expressions
//
// An expression specifies the computation of a value by applying operators and
// functions to operands.
//
// Operands
//
// Operands denote the elementary values in an expression. An operand may be a
// literal, a (possibly qualified) identifier denoting a constant or a function
// or a table/record set column, or a parenthesized expression.
//
//  Operand = Literal | QualifiedIdent | "(" Expression ")" .
//  Literal = "FALSE" | "NULL" | "TRUE"
//  	| float_lit | imaginary_lit | int_lit | rune_lit | string_lit
//  	| ql_parameter .
//
// Qualified identifiers
//
// A qualified identifier is an identifier qualified with a table/record set
// name prefix.
//
//  QualifiedIdent = identifier [ "." identifier ] .
//
// For example
//
// 	invoice.Num	// might denote column 'Num' from table 'invoice'
//
// Primary expressions
//
// Primary expression are the operands for unary and binary expressions.
//
//  PrimaryExpression = Operand
//              | Conversion
//              | PrimaryExpression Index
//              | PrimaryExpression Slice
//              | PrimaryExpression Call .
//
cznic's avatar
cznic committed
698
//  Call  = "(" [ "*" | ExpressionList ] ")" . // * only in count(*).
cznic's avatar
cznic committed
699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715
//  Index = "[" Expression "]" .
//  Slice = "[" [ Expression ] ":" [ Expression ] "]" .
//
// For example
//
// 	x
// 	2
// 	(s + ".txt")
// 	f(3.1415, true)
// 	s[i : j + 1]
//
// Index expressions
//
// A primary expression of the form
//
// 	s[x]
//
cznic's avatar
cznic committed
716
// denotes the element of a string indexed by x. Its type is byte. The value x
cznic's avatar
cznic committed
717 718
// is called the index.  The following rules apply
//
cznic's avatar
cznic committed
719 720
// - The index x must be of integer type except bigint or duration; it is in
// range if 0 <= x < len(s), otherwise it is out of range.
cznic's avatar
cznic committed
721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758
//
// - A constant index must be non-negative and representable by a value of type
// int.
//
// - A constant index must be in range if the string a is a literal.
//
// - If x is out of range at run time, a run-time error occurs.
//
// - s[x] is the byte at index x and the type of s[x] is byte.
//
// If s is NULL or x is NULL then the result is NULL.
//
// Otherwise s[x] is illegal.
//
// Slices
//
// For a string, the primary expression
//
// 	s[low : high]
//
// constructs a substring. The indices low and high select which elements
// appear in the result. The result has indices starting at 0 and length equal
// to high - low.
//
// For convenience, any of the indices may be omitted. A missing low index
// defaults to zero; a missing high index defaults to the length of the sliced
// operand
//
// 	s[2:]  // same s[2 : len(s)]
// 	s[:3]  // same as s[0 : 3]
// 	s[:]   // same as s[0 : len(s)]
//
// The indices low and high are in range if 0 <= low <= high <= len(a),
// otherwise they are out of range. A constant index must be non-negative and
// representable by a value of type int. If both indices are constant, they
// must satisfy low <= high. If the indices are out of range at run time, a
// run-time error occurs.
//
cznic's avatar
cznic committed
759
// Integer values of type bigint or duration cannot be used as indices.
cznic's avatar
cznic committed
760
//
cznic's avatar
cznic committed
761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786
// If s is NULL the result is NULL. If low or high is not omitted and is NULL
// then the result is NULL.
//
// Calls
//
// Given an identifier f denoting a predeclared function,
//
// 	f(a1, a2, … an)
//
// calls f with arguments a1, a2, … an. Arguments are evaluated before the
// function is called. The type of the expression is the result type of f.
//
// 	complex(x, y)
// 	len(name)
//
// In a function call, the function value and arguments are evaluated in the
// usual order. After they are evaluated, the parameters of the call are passed
// by value to the function and the called function begins execution. The
// return value of the function is passed by value when the function returns.
//
// Calling an undefined function causes a compile-time error.
//
// Operators
//
// Operators combine operands into expressions.
//
787
//  Expression = Term { ( oror | "OR" ) Term } .
cznic's avatar
cznic committed
788 789
//
//  ExpressionList = Expression { "," Expression } [ "," ].
cznic's avatar
cznic committed
790 791
//  Factor =  PrimaryFactor  { ( ge | ">" | le | "<" | neq | eq | "LIKE" ) PrimaryFactor } [ Predicate ] .
//  PrimaryFactor = PrimaryTerm  { ( "^" | "|" | "-" | "+" ) PrimaryTerm } .
cznic's avatar
cznic committed
792
//  PrimaryTerm = UnaryExpr { ( andnot | "&" | lsh | rsh | "%" | "/" | "*" ) UnaryExpr } .
793
//  Term = Factor { ( andand | "AND" ) Factor } .
cznic's avatar
cznic committed
794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810
//  UnaryExpr = [ "^" | "!" | "-" | "+" ] PrimaryExpression .
//
// Comparisons are discussed elsewhere. For other binary operators, the operand
// types must be identical unless the operation involves shifts or untyped
// constants. For operations involving constants only, see the section on
// constant expressions.
//
// Except for shift operations, if one operand is an untyped constant and the
// other operand is not, the constant is converted to the type of the other
// operand.
//
// The right operand in a shift expression must have unsigned integer type or
// be an untyped constant that can be converted to unsigned integer type. If
// the left operand of a non-constant shift expression is an untyped constant,
// the type of the constant is what it would be if the shift expression were
// replaced by its left operand alone.
//
cznic's avatar
cznic committed
811 812 813 814 815 816
// Pattern matching
//
// Expressions of the form
//
//	expr1 LIKE expr2
//
817
// yield a boolean value true if expr2, a regular expression, matches expr1
cznic's avatar
cznic committed
818 819 820
// (see also [6]).  Both expression must be of type string. If any one of the
// expressions is NULL the result is NULL.
//
cznic's avatar
cznic committed
821 822 823
// Predicates
//
// Predicates are special form expressions having a boolean result type.
cznic's avatar
cznic committed
824
//
cznic's avatar
cznic committed
825 826 827 828 829 830 831 832 833 834 835 836 837 838 839
// Expressions of the form
//
//	expr IN ( expr1, expr2, expr3, ... )		// case A
//
//	expr NOT IN ( expr1, expr2, expr3, ... )	// case B
//
// are equivalent, including NULL handling, to
//
//	expr == expr1 || expr == expr2 || expr == expr3 || ...	// case A
//
//	expr != expr1 && expr != expr2 && expr != expr3 && ...	// case B
//
// The types of involved expressions must be comparable as defined in
// "Comparison operators".
//
840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873
// Another form of the IN predicate creates the expression list from a result
// of a SelectStmt.
//
//	DELETE FROM t WHERE id() IN (SELECT id_t FROM u WHERE inactive_days > 365)
//
// The SelectStmt must select only one column. The produced expression list is
// resource limited by the memory available to the process. NULL values
// produced by the SelectStmt are ignored, but if all records of the SelectStmt
// are NULL the predicate yields NULL. The select statement is evaluated only
// once. If the type of expr is not the same as the type of the field returned
// by the SelectStmt then the set operation yields false. The type of the
// column returned by the SelectStmt must be one of the simple (non blob-like)
// types:
//
//	bool
//	byte         // alias uint8
//	complex128
//	complex64
//	float        // alias float64
//	float32
//	float64
//	int          // alias int64
//	int16
//	int32
//	int64
//	int8
//	rune         // alias int32
//	string
//	uint         // alias uint64
//	uint16
//	uint32
//	uint64
//	uint8
//
cznic's avatar
cznic committed
874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891
// Expressions of the form
//
//	expr BETWEEN low AND high	// case A
//
//	expr NOT BETWEEN low AND high	// case B
//
// are equivalent, including NULL handling, to
//
//	expr >= low && expr <= high	// case A
//
//	expr < low || expr > high	// case B
//
// The types of involved expressions must be ordered as defined in "Comparison
// operators".
//
//  Predicate = (
//  			[ "NOT" ] (
//  			  "IN" "(" ExpressionList ")"
cznic's avatar
cznic committed
892
//  			| "IN" "(" SelectStmt [ ";" ] ")"
cznic's avatar
cznic committed
893 894
//  			| "BETWEEN" PrimaryFactor "AND" PrimaryFactor
//  			)
cznic's avatar
cznic committed
895
//              |       "IS" [ "NOT" ] "NULL"
cznic's avatar
cznic committed
896 897 898 899 900 901 902 903
//  	).
//
// Expressions of the form
//
//	expr IS NULL		// case A
//
//	expr IS NOT NULL	// case B
//
904
// yield a boolean value true if expr does not have a specific type (case A) or
cznic's avatar
cznic committed
905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938
// if expr has a specific type (case B). In other cases the result is a boolean
// value false.
//
// Operator precedence
//
// Unary operators have the highest precedence.
//
// There are five precedence levels for binary operators. Multiplication
// operators bind strongest, followed by addition operators, comparison
// operators, && (logical AND), and finally || (logical OR)
//
// 	Precedence    Operator
// 	    5             *  /  %  <<  >>  &  &^
// 	    4             +  -  |  ^
// 	    3             ==  !=  <  <=  >  >=
// 	    2             &&
// 	    1             ||
//
// Binary operators of the same precedence associate from left to right. For
// instance, x / y * z is the same as (x / y) * z.
//
// 	+x
// 	23 + 3*x[i]
// 	x <= f()
// 	^a >> b
// 	f() || g()
// 	x == y+1 && z > 0
//
// Note that the operator precedence is reflected explicitly by the grammar.
//
// Arithmetic operators
//
// Arithmetic operators apply to numeric values and yield a result of the same
// type as the first operand. The four standard arithmetic operators (+, -, *,
cznic's avatar
cznic committed
939 940 941
// /) apply to integer, rational, floating-point, and complex types; + also
// applies to strings; +,- also applies to times.  All other arithmetic
// operators apply to integers only.
cznic's avatar
cznic committed
942
//
cznic's avatar
cznic committed
943
// 	+    sum                    integers, rationals, floats, complex values, strings
cznic's avatar
cznic committed
944
// 	-    difference             integers, rationals, floats, complex values, times
cznic's avatar
cznic committed
945 946
// 	*    product                integers, rationals, floats, complex values
// 	/    quotient               integers, rationals, floats, complex values
cznic's avatar
cznic committed
947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962
// 	%    remainder              integers
//
// 	&    bitwise AND            integers
// 	|    bitwise OR             integers
// 	^    bitwise XOR            integers
// 	&^   bit clear (AND NOT)    integers
//
// 	<<   left shift             integer << unsigned integer
// 	>>   right shift            integer >> unsigned integer
//
// Strings can be concatenated using the + operator
//
// 	"hi" + string(c) + " and good bye"
//
// String addition creates a new string by concatenating the operands.
//
963
// A value of type duration can be added to or subtracted from a value of type time.
cznic's avatar
cznic committed
964 965
//
//	now() + duration("1h")	// time after 1 hour from now
cznic's avatar
cznic committed
966
//	duration("1h") + now()	// time after 1 hour from now
cznic's avatar
cznic committed
967
//	now() - duration("1h")	// time before 1 hour from now
cznic's avatar
cznic committed
968
//	duration("1h") - now()	// illegal, negative times do not exist
cznic's avatar
cznic committed
969 970 971 972
//
// Times can subtracted from each other producing a value of type duration.
//
//	now() - t0	// elapsed time since t0
cznic's avatar
cznic committed
973
//	now() + now()	// illegal, operator + not defined for times
cznic's avatar
cznic committed
974
//
cznic's avatar
cznic committed
975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041
// For two integer values x and y, the integer quotient q = x / y and remainder
// r = x % y satisfy the following relationships
//
// 	x = q*y + r  and  |r| < |y|
//
// with x / y truncated towards zero ("truncated division").
//
// 	 x     y     x / y     x % y
// 	 5     3       1         2
// 	-5     3      -1        -2
// 	 5    -3      -1         2
// 	-5    -3       1        -2
//
// As an exception to this rule, if the dividend x is the most negative value
// for the int type of x, the quotient q = x / -1 is equal to x (and r = 0).
//
// 				 x, q
// 	int8                     -128
// 	int16                  -32768
// 	int32             -2147483648
// 	int64    -9223372036854775808
//
// If the divisor is a constant expression, it must not be zero. If the divisor
// is zero at run time, a run-time error occurs. If the dividend is
// non-negative and the divisor is a constant power of 2, the division may be
// replaced by a right shift, and computing the remainder may be replaced by a
// bitwise AND operation
//
// 	 x     x / 4     x % 4     x >> 2     x & 3
// 	 11      2         3         2          3
// 	-11     -2        -3        -3          1
//
// The shift operators shift the left operand by the shift count specified by
// the right operand. They implement arithmetic shifts if the left operand is a
// signed integer and logical shifts if it is an unsigned integer. There is no
// upper limit on the shift count. Shifts behave as if the left operand is
// shifted n times by 1 for a shift count of n. As a result, x << 1 is the same
// as x*2 and x >> 1 is the same as x/2 but truncated towards negative
// infinity.
//
// For integer operands, the unary operators +, -, and ^ are defined as follows
//
// 	+x                          is 0 + x
// 	-x    negation              is 0 - x
// 	^x    bitwise complement    is m ^ x  with m = "all bits set to 1" for unsigned x
// 	                                      and  m = -1 for signed x
//
// For floating-point and complex numbers, +x is the same as x, while -x is the
// negation of x. The result of a floating-point or complex division by zero is
// not specified beyond the IEEE-754 standard; whether a run-time error occurs
// is implementation-specific.
//
// Whenever any operand of any arithmetic operation, unary or binary, is NULL,
// as well as in the case of the string concatenating operation, the result is
// NULL.
//
//	42*NULL		// the result is NULL
//	NULL/x		// the result is NULL
//	"foo"+NULL	// the result is NULL
//
// Integer overflow
//
// For unsigned integer values, the operations +, -, *, and << are computed
// modulo 2n, where n is the bit width of the unsigned integer's type. Loosely
// speaking, these unsigned integer operations discard high bits upon overflow,
// and expressions may rely on ``wrap around''.
//
cznic's avatar
cznic committed
1042 1043 1044 1045 1046 1047 1048
// For signed integers with a finite bit width, the operations +, -, *, and <<
// may legally overflow and the resulting value exists and is deterministically
// defined by the signed integer representation, the operation, and its
// operands. No exception is raised as a result of overflow. An evaluator may
// not optimize an expression under the assumption that overflow does not
// occur. For instance, it may not assume that x < x + 1 is always true.
//
cznic's avatar
cznic committed
1049 1050
// Integers of type bigint and rationals do not overflow but their handling is
// limited by the memory resources available to the program.
cznic's avatar
cznic committed
1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072
//
// Comparison operators
//
// Comparison operators compare two operands and yield a boolean value.
//
// 	==    equal
// 	!=    not equal
// 	<     less
// 	<=    less or equal
// 	>     greater
// 	>=    greater or equal
//
// In any comparison, the first operand must be of same type as is the second
// operand, or vice versa.
//
// The equality operators == and != apply to operands that are comparable. The
// ordering operators <, <=, >, and >= apply to operands that are ordered.
// These terms and the result of the comparisons are defined as follows
//
// - Boolean values are comparable. Two boolean values are equal if they are
// either both true or both false.
//
cznic's avatar
cznic committed
1073 1074
// - Complex values are comparable. Two complex values u and v are equal if
// both real(u) == real(v) and imag(u) == imag(v).
cznic's avatar
cznic committed
1075
//
cznic's avatar
cznic committed
1076 1077
// - Integer values are comparable and ordered, in the usual way. Note that
// durations are integers.
cznic's avatar
cznic committed
1078
//
cznic's avatar
cznic committed
1079 1080 1081
// - Floating point values are comparable and ordered, as defined by the
// IEEE-754 standard.
//
cznic's avatar
cznic committed
1082
// - Rational values are comparable and ordered, in the usual way.
cznic's avatar
cznic committed
1083 1084 1085
//
// - String values are comparable and ordered, lexically byte-wise.
//
cznic's avatar
cznic committed
1086 1087
// - Time values are comparable and ordered.
//
cznic's avatar
cznic committed
1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 1132 1133 1134 1135 1136 1137 1138 1139 1140 1141 1142 1143 1144 1145 1146 1147 1148 1149 1150 1151 1152 1153 1154 1155 1156 1157 1158 1159 1160 1161 1162 1163
// Whenever any operand of any comparison operation is NULL, the result is
// NULL.
//
// Note that slices are always of type string.
//
// Logical operators
//
// Logical operators apply to boolean values and yield a boolean result. The
// right operand is evaluated conditionally.
//
// 	&&    conditional AND    p && q  is  "if p then q else false"
// 	||    conditional OR     p || q  is  "if p then true else q"
// 	!     NOT                !p      is  "not p"
//
// The truth tables for logical operations with NULL values
//
// 	+-------+-------+---------+---------+
// 	|   p   |   q   |  p || q |  p && q |
// 	+-------+-------+---------+---------+
// 	| true  | true  | *true   |  true   |
// 	| true  | false | *true   |  false  |
// 	| true  | NULL  | *true   |  NULL   |
// 	| false | true  |  true   | *false  |
// 	| false | false |  false  | *false  |
// 	| false | NULL  |  NULL   | *false  |
// 	| NULL  | true  |  true   |  NULL   |
// 	| NULL  | false |  NULL   |  false  |
// 	| NULL  | NULL  |  NULL   |  NULL   |
// 	+-------+-------+---------+---------+
// 	 * indicates q is not evaluated.
//
// 	+-------+-------+
// 	|   p   |  !p   |
// 	+-------+-------+
// 	| true  | false |
// 	| false | true  |
// 	| NULL  | NULL  |
// 	+-------+-------+
//
// Conversions
//
// Conversions are expressions of the form T(x) where T is a type and x is an
// expression that can be converted to type T.
//
//  Conversion = Type "(" Expression ")" .
//
// A constant value x can be converted to type T in any of these cases:
//
// - x is representable by a value of type T.
//
// - x is a floating-point constant, T is a floating-point type, and x is
// representable by a value of type T after rounding using IEEE 754
// round-to-even rules. The constant T(x) is the rounded value.
//
// - x is an integer constant and T is a string type. The same rule as for
// non-constant x applies in this case.
//
// Converting a constant yields a typed constant as result.
//
// 	float32(2.718281828)     // 2.718281828 of type float32
// 	complex128(1)            // 1.0 + 0.0i of type complex128
// 	float32(0.49999999)      // 0.5 of type float32
// 	string('x')              // "x" of type string
// 	string(0x266c)           // "♬" of type string
// 	"foo" + "bar"            // "foobar"
// 	int(1.2)                 // illegal: 1.2 cannot be represented as an int
// 	string(65.0)             // illegal: 65.0 is not an integer constant
//
// A non-constant value x can be converted to type T in any of these cases:
//
// - x has type T.
//
// - x's type and T are both integer or floating point types.
//
// - x's type and T are both complex types.
//
cznic's avatar
cznic committed
1164
// - x is an integer, except bigint or duration, and T is a string type.
cznic's avatar
cznic committed
1165 1166 1167 1168 1169 1170 1171 1172 1173 1174 1175 1176 1177 1178 1179 1180 1181 1182 1183 1184 1185 1186 1187 1188 1189 1190 1191 1192 1193 1194 1195 1196 1197 1198 1199
//
// Specific rules apply to (non-constant) conversions between numeric types or
// to and from a string type. These conversions may change the representation
// of x and incur a run-time cost. All other conversions only change the type
// but not the representation of x.
//
// A conversion of NULL to any type yields NULL.
//
// Conversions between numeric types
//
// For the conversion of non-constant numeric values, the following rules
// apply
//
// 1. When converting between integer types, if the value is a signed integer,
// it is sign extended to implicit infinite precision; otherwise it is zero
// extended.  It is then truncated to fit in the result type's size. For
// example, if v == uint16(0x10F0), then uint32(int8(v)) == 0xFFFFFFF0. The
// conversion always yields a valid value; there is no indication of overflow.
//
// 2. When converting a floating-point number to an integer, the fraction is
// discarded (truncation towards zero).
//
// 3. When converting an integer or floating-point number to a floating-point
// type, or a complex number to another complex type, the result value is
// rounded to the precision specified by the destination type. For instance,
// the value of a variable x of type float32 may be stored using additional
// precision beyond that of an IEEE-754 32-bit number, but float32(x)
// represents the result of rounding x's value to 32-bit precision. Similarly,
// x + 0.1 may use more than 32 bits of precision, but float32(x + 0.1) does
// not.
//
// In all non-constant conversions involving floating-point or complex values,
// if the result type cannot represent the value the conversion succeeds but
// the result value is implementation-dependent.
//
cznic's avatar
cznic committed
1200
// Conversions to and from a string type
cznic's avatar
cznic committed
1201
//
cznic's avatar
cznic committed
1202
// 1. Converting a signed or unsigned integer value to a string type yields a
cznic's avatar
cznic committed
1203 1204 1205 1206 1207 1208 1209 1210
// string containing the UTF-8 representation of the integer. Values outside
// the range of valid Unicode code points are converted to "\uFFFD".
//
// 	string('a')       // "a"
// 	string(-1)        // "\ufffd" == "\xef\xbf\xbd"
// 	string(0xf8)      // "\u00f8" == "ø" == "\xc3\xb8"
// 	string(0x65e5)    // "\u65e5" == "日" == "\xe6\x97\xa5"
//
cznic's avatar
cznic committed
1211 1212 1213 1214 1215 1216 1217 1218 1219 1220 1221 1222 1223
// 2. Converting a blob to a string type yields a string whose successive bytes
// are the elements of the blob.
//
//	string(b /* []byte{'h', 'e', 'l', 'l', '\xc3', '\xb8'} */)   // "hellø"
//	string(b /* []byte{} */)                                     // ""
//	string(b /* []byte(nil) */)                                  // ""
//
// 3. Converting a value of a string type to a blob yields a blob whose
// successive elements are the bytes of the string.
//
//	blob("hellø")   // []byte{'h', 'e', 'l', 'l', '\xc3', '\xb8'}
//	blob("")        // []byte{}
//
cznic's avatar
cznic committed
1224 1225
// 4. Converting a value of a bigint type to a string yields a string
// containing the decimal decimal representation of the integer.
cznic's avatar
cznic committed
1226 1227 1228 1229 1230 1231
//
//	string(M9)	// "2305843009213693951"
//
// 5. Converting a value of a string type to a bigint yields a bigint value
// containing the integer represented by the string value. A prefix of “0x” or
// “0X” selects base 16; the “0” prefix selects base 8, and a “0b” or “0B”
cznic's avatar
cznic committed
1232 1233
// prefix selects base 2. Otherwise the value is interpreted in base 10. An
// error occurs if the string value is not in any valid format.
cznic's avatar
cznic committed
1234 1235 1236 1237
//
//	bigint("2305843009213693951")		// M9
//	bigint("0x1ffffffffffffffffffffff")	// M10 == 2^89-1
//
cznic's avatar
cznic committed
1238 1239 1240 1241 1242 1243 1244 1245 1246 1247 1248 1249 1250 1251 1252
// 6. Converting a value of a rational type to a string yields a string
// containing the decimal decimal representation of the rational in the form
// "a/b" (even if b == 1).
//
//	string(bigrat(355)/bigrat(113))	// "355/113"
//
// 7. Converting a value of a string type to a bigrat yields a bigrat value
// containing the rational represented by the string value. The string can be
// given as a fraction "a/b" or as a floating-point number optionally followed
// by an exponent. An error occurs if the string value is not in any valid
// format.
//
//	bigrat("1.2e-34")
//	bigrat("355/113")
//
cznic's avatar
cznic committed
1253 1254 1255 1256 1257 1258 1259 1260 1261 1262 1263 1264 1265 1266 1267 1268
// 8. Converting a value of a duration type to a string returns a string
// representing the duration in the form "72h3m0.5s". Leading zero units are
// omitted. As a special case, durations less than one second format using a
// smaller unit (milli-, micro-, or nanoseconds) to ensure that the leading
// digit is non-zero. The zero duration formats as 0, with no unit.
//
//	string(elapsed)	// "1h", for example
//
// 9. Converting a string value to a duration yields a duration represented by
// the string.  A duration string is a possibly signed sequence of decimal
// numbers, each with optional fraction and a unit suffix, such as "300ms",
// "-1.5h" or "2h45m". Valid time units are "ns", "us" (or "µs"), "ms", "s",
// "m", "h".
//
//	duration("1m")	// http://golang.org/pkg/time/#Minute
//
cznic's avatar
cznic committed
1269 1270 1271 1272 1273
// 10. Converting a time value to a string returns the time formatted using the
// format string
//
//	"2006-01-02 15:04:05.999999999 -0700 MST"
//
cznic's avatar
cznic committed
1274 1275 1276 1277 1278 1279 1280 1281 1282 1283 1284 1285 1286 1287 1288 1289 1290 1291 1292 1293 1294
// Order of evaluation
//
// When evaluating the operands of an expression or of function calls,
// operations are evaluated in lexical left-to-right order.
//
// For example, in the evaluation of
//
// 	g(h(), i()+x[j()], c)
//
// the function calls and evaluation of c happen in the order h(), i(), j(), c.
//
// Floating-point operations within a single expression are evaluated according
// to the associativity of the operators. Explicit parentheses affect the
// evaluation by overriding the default associativity. In the expression x + (y
// + z) the addition y + z is performed before adding x.
//
// Statements
//
// Statements control execution.
//
//  Statement =  EmptyStmt | AlterTableStmt | BeginTransactionStmt | CommitStmt
1295 1296
//  	| CreateIndexStmt | CreateTableStmt | DeleteFromStmt | DropIndexStmt
//  	| DropTableStmt | InsertIntoStmt | RollbackStmt | SelectStmt
cznic's avatar
cznic committed
1297
//  	| TruncateTableStmt | UpdateStmt | ExplainStmt.
cznic's avatar
cznic committed
1298 1299 1300 1301 1302 1303 1304 1305 1306 1307 1308 1309 1310
//
//  StatementList = Statement { ";" Statement } .
//
// Empty statements
//
// The empty statement does nothing.
//
//  EmptyStmt = .
//
// ALTER TABLE
//
// Alter table statements modify existing tables.  With the ADD clause it adds
// a new column to the table. The column must not exist. With the DROP clause
cznic's avatar
cznic committed
1311 1312 1313
// it removes an existing column from a table. The column must exist and it
// must be not the only (last) column of the table. IOW, there cannot be a
// table with no columns.
cznic's avatar
cznic committed
1314 1315 1316 1317 1318 1319 1320 1321 1322 1323
//
//  AlterTableStmt = "ALTER" "TABLE" TableName ( "ADD" ColumnDef | "DROP" "COLUMN"  ColumnName ) .
//
// For example
//
//	BEGIN TRANSACTION;
// 		ALTER TABLE Stock ADD Qty int;
// 		ALTER TABLE Income DROP COLUMN Taxes;
//	COMMIT;
//
1324 1325 1326 1327
// When adding a column to a table with existing data, the constraint clause of
// the ColumnDef cannot be used. Adding a constrained column to an empty table
// is fine.
//
cznic's avatar
cznic committed
1328 1329 1330 1331 1332 1333 1334 1335 1336 1337 1338 1339 1340 1341 1342 1343 1344 1345 1346 1347 1348
// BEGIN TRANSACTION
//
// Begin transactions statements introduce a new transaction level. Every
// transaction level must be eventually balanced by exactly one of COMMIT or
// ROLLBACK statements. Note that when a transaction is roll-backed because of
// a statement failure then no explicit balancing of the respective BEGIN
// TRANSACTION is statement is required nor permitted.
//
// Failure to properly balance any opened transaction level may cause dead
// locks and/or lose of data updated in the uppermost opened but never properly
// closed transaction level.
//
//  BeginTransactionStmt = "BEGIN" "TRANSACTION" .
//
// For example
//
//	BEGIN TRANSACTION;
//		INSERT INTO foo VALUES (42, 3.14);
//		INSERT INTO foo VALUES (-1, 2.78);
//	COMMIT;
//
1349 1350 1351 1352 1353 1354 1355 1356 1357 1358 1359 1360 1361 1362 1363 1364 1365 1366 1367 1368 1369 1370 1371
// Mandatory transactions
//
// A database cannot be updated (mutated) outside of a transaction. Statements
// requiring a transaction
//
//	ALTER TABLE
//	COMMIT
//	CREATE INDEX
//	CREATE TABLE
//	DELETE FROM
//	DROP INDEX
//	DROP TABLE
//	INSERT INTO
//	ROLLBACK
//	TRUNCATE TABLE
//	UPDATE
//
// A database is effectively read only outside of a transaction. Statements not
// requiring a transaction
//
//	BEGIN TRANSACTION
//	SELECT FROM
//
cznic's avatar
cznic committed
1372 1373 1374 1375 1376 1377 1378 1379 1380 1381 1382 1383 1384 1385 1386
// COMMIT
//
// The commit statement closes the innermost transaction nesting level. If
// that's the outermost level then the updates to the DB made by the
// transaction are atomically made persistent.
//
//  CommitStmt = "COMMIT" .
//
// For example
//
//	BEGIN TRANSACTION;
//		INSERT INTO AccountA (Amount) VALUES ($1);
//		INSERT INTO AccountB (Amount) VALUES (-$1);
//	COMMIT;
//
1387 1388 1389 1390
// CREATE INDEX
//
// Create index statements create new indices. Index is a named projection of
// ordered values of a table column to the respective records. As a special
1391 1392
// case the id() of the record can be indexed. Index name must not be the same
// as any of the existing tables and it also cannot be the same as of any
1393
// column name of the table the index is on.
1394
//
1395
//  CreateIndexStmt = "CREATE" [ "UNIQUE" ] "INDEX" [ "IF" "NOT" "EXISTS" ]
1396
//  	IndexName "ON" TableName "(" ExpressionList ")" .
1397 1398 1399 1400 1401 1402 1403 1404 1405 1406 1407 1408 1409 1410 1411 1412
//
// For example
//
//	BEGIN TRANSACTION;
//		CREATE TABLE Orders (CustomerID int, Date time);
//		CREATE INDEX OrdersID ON Orders (id());
//		CREATE INDEX OrdersDate ON Orders (Date);
//		CREATE TABLE Items (OrderID int, ProductID int, Qty int);
//		CREATE INDEX ItemsOrderID ON Items (OrderID);
//	COMMIT;
//
// Now certain SELECT statements may use the indices to speed up joins and/or
// to speed up record set filtering when the WHERE clause is used; or the
// indices might be used to improve the performance when the ORDER BY clause is
// present.
//
1413 1414
// The UNIQUE modifier requires the indexed values tuple to be index-wise
// unique or have all values NULL.
cznic's avatar
cznic committed
1415
//
1416 1417 1418
// The optional IF NOT EXISTS clause makes the statement a no operation if the
// index already exists.
//
1419 1420 1421 1422 1423 1424 1425 1426 1427 1428 1429 1430 1431
// Simple index
//
// A simple index consists of only one expression which must be either a column
// name or the built-in id().
//
// Expression list index
//
// A more complex and more general index is one that consists of more than one
// expression or its single expression does not qualify as a simple index. In
// this case the type of all expressions in the list must be one of the non
// blob-like types.
//
// Note: Blob-like types are blob, bigint, bigrat, time and duration.
1432
//
cznic's avatar
cznic committed
1433 1434 1435
// CREATE TABLE
//
// Create table statements create new tables. A column definition declares the
1436 1437
// column name and type. Table names and column names are case sensitive.
// Neither a table or an index of the same name may exist in the DB.
cznic's avatar
cznic committed
1438
//
1439 1440
//  CreateTableStmt = "CREATE" "TABLE" [ "IF" "NOT" "EXISTS" ] TableName
//  	"(" ColumnDef { "," ColumnDef } [ "," ] ")" .
cznic's avatar
cznic committed
1441
//
cznic's avatar
cznic committed
1442
//  ColumnDef = ColumnName Type [ "NOT" "NULL" | Expression ] [ "DEFAULT" Expression ] .
cznic's avatar
cznic committed
1443 1444 1445 1446 1447 1448
//  ColumnName = identifier .
//  TableName = identifier .
//
// For example
//
//	BEGIN TRANSACTION;
cznic's avatar
cznic committed
1449
// 		CREATE TABLE department (
cznic's avatar
cznic committed
1450 1451 1452
// 			DepartmentID   int,
// 			DepartmentName string,
// 		);
cznic's avatar
cznic committed
1453
// 		CREATE TABLE employee (
cznic's avatar
cznic committed
1454 1455 1456 1457 1458
// 			LastName	string,
// 			DepartmentID	int,
// 		);
//	COMMIT;
//
1459 1460
// The optional IF NOT EXISTS clause makes the statement a no operation if the
// table already exists.
cznic's avatar
cznic committed
1461
//
1462 1463 1464 1465 1466 1467 1468 1469 1470 1471 1472 1473 1474
// The optional constraint clause has two forms. The first one is found in many
// SQL dialects.
//
//	BEGIN TRANSACTION;
// 		CREATE TABLE department (
// 			DepartmentID   int,
// 			DepartmentName string NOT NULL,
// 		);
//	COMMIT;
//
// This form prevents the data in column DepartmentName to be NULL.
//
// The second form allows an arbitrary boolean expression to be used to
cznic's avatar
cznic committed
1475
// validate the column. If the value of the expression is true then the
cznic's avatar
cznic committed
1476
// validation succeeded. If the value of the expression is false or NULL then
cznic's avatar
cznic committed
1477 1478
// the validation fails. If the value of the expression is not of type bool an
// error occurs.
1479 1480 1481 1482 1483 1484 1485 1486
//
//	BEGIN TRANSACTION;
// 		CREATE TABLE department (
// 			DepartmentID   int,
// 			DepartmentName string DepartmentName IN ("HQ", "R/D", "Lab", "HR"),
// 		);
//	COMMIT;
//
cznic's avatar
cznic committed
1487 1488 1489 1490 1491 1492 1493 1494 1495 1496 1497 1498 1499
//	BEGIN TRANSACTION;
// 		CREATE TABLE t (
//			TimeStamp time TimeStamp < now() && since(TimeStamp) < duration("10s"),
//			Event string Event != "" && Event like "[0-9]+:[ \t]+.*",
//		);
//	COMMIT;
//
// The optional DEFAULT clause is an expression which, if present, is
// substituted instead of a NULL value when the colum is assigned a value.
//
//	BEGIN TRANSACTION;
// 		CREATE TABLE department (
// 			DepartmentID   int,
cznic's avatar
cznic committed
1500
// 			DepartmentName string DepartmentName IN ("HQ", "R/D", "Lab", "HR") DEFAULT "HQ",
cznic's avatar
cznic committed
1501 1502 1503
// 		);
//	COMMIT;
//
cznic's avatar
cznic committed
1504 1505 1506 1507 1508 1509 1510 1511 1512 1513 1514
// Note that the constraint and/or default expressions may refer to other
// columns by name:
//
//	BEGIN TRANSACTION;
//		CREATE TABLE t (
//			a int,
//			b int b > a && b < c DEFAULT (a+c)/2,
//			c int,
//	);
//	COMMIT;
//
cznic's avatar
cznic committed
1515
//
cznic's avatar
cznic committed
1516
// Constraints and defaults
cznic's avatar
cznic committed
1517 1518 1519 1520 1521 1522 1523 1524 1525 1526 1527 1528 1529 1530 1531 1532 1533 1534 1535 1536
//
// When a table row is inserted by the INSERT INTO statement or when a table
// row is updated by the UPDATE statement, the order of operations is as
// follows:
//
// 1. The new values of the affected columns are set and the values of all the
// row columns become the named values which can be referred to in default
// expressions evaluated in step 2.
//
// 2. If any row column value is NULL and the DEFAULT clause is present in the
// column's definition, the default expression is evaluated and its value is
// set as the respective column value.
//
// 3. The values, potentially updated, of row columns become the named values
// which can be referred to in constraint expressions evaluated during step 4.
//
// 4. All row columns which definition has the constraint clause present will
// have that constraint checked. If any constraint violation is detected, the
// overall operation fails and no changes to the table are made.
//
cznic's avatar
cznic committed
1537 1538 1539 1540 1541 1542 1543 1544 1545 1546
// DELETE FROM
//
// Delete from statements remove rows from a table, which must exist.
//
//  DeleteFromStmt = "DELETE" "FROM" TableName [ WhereClause ] .
//
// For example
//
//	BEGIN TRANSACTION;
//		DELETE FROM DepartmentID
cznic's avatar
cznic committed
1547
//		WHERE DepartmentName == "Ponies";
cznic's avatar
cznic committed
1548 1549
//	COMMIT;
//
1550
// If the WHERE clause is not present then all rows are removed and the
cznic's avatar
cznic committed
1551 1552
// statement is equivalent to the TRUNCATE TABLE statement.
//
1553 1554 1555 1556
// DROP INDEX
//
// Drop index statements remove indices from the DB. The index must exist.
//
1557
//  DropIndexStmt = "DROP" "INDEX" [ "IF" "EXISTS" ] IndexName .
1558 1559 1560 1561 1562 1563 1564 1565
//  IndexName = identifier .
//
// For example
//
//	BEGIN TRANSACTION;
//		DROP INDEX ItemsOrderID;
//	COMMIT;
//
1566 1567 1568
// The optional IF EXISTS clause makes the statement a no operation if the
// index does not exist.
//
cznic's avatar
cznic committed
1569 1570 1571 1572
// DROP TABLE
//
// Drop table statements remove tables from the DB. The table must exist.
//
1573
//  DropTableStmt = "DROP" "TABLE" [ "IF" "EXISTS" ] TableName .
cznic's avatar
cznic committed
1574 1575 1576 1577 1578 1579 1580
//
// For example
//
//	BEGIN TRANSACTION;
// 		DROP TABLE Inventory;
//	COMMIT;
//
1581 1582 1583
// The optional IF EXISTS clause makes the statement a no operation if the
// table does not exist.
//
cznic's avatar
cznic committed
1584 1585 1586 1587 1588 1589 1590 1591 1592 1593 1594 1595 1596 1597 1598 1599 1600 1601 1602 1603 1604 1605 1606 1607 1608 1609 1610 1611 1612 1613 1614 1615 1616 1617 1618 1619 1620 1621 1622 1623 1624 1625 1626 1627 1628
// INSERT INTO
//
// Insert into statements insert new rows into tables. New rows come from
// literal data, if using the VALUES clause, or are a result of select
// statement. In the later case the select statement is fully evaluated before
// the insertion of any rows is performed, allowing to insert values calculated
// from the same table rows are to be inserted into. If the ColumnNameList part
// is omitted then the number of values inserted in the row must be the same as
// are columns in the table. If the ColumnNameList part is present then the
// number of values per row must be same as the same number of column names.
// All other columns of the record are set to NULL.  The type of the value
// assigned to a column must be the same as is the column's type or the value
// must be NULL.
//
//  InsertIntoStmt = "INSERT" "INTO" TableName [ "(" ColumnNameList ")" ] ( Values | SelectStmt ) .
//
//  ColumnNameList = ColumnName { "," ColumnName } [ "," ] .
//  Values = "VALUES" "(" ExpressionList ")" { "," "(" ExpressionList ")" } [ "," ] .
//
// For example
//
//	BEGIN TRANSACTION;
// 		INSERT INTO department (DepartmentID) VALUES (42);
//
// 		INSERT INTO department (
// 			DepartmentName,
// 			DepartmentID,
// 		)
// 		VALUES (
// 			"R&D",
// 			42,
// 		);
//
// 		INSERT INTO department VALUES
//			(42, "R&D"),
//			(17, "Sales"),
// 		;
//	COMMIT;
//
//	BEGIN TRANSACTION;
//		INSERT INTO department (DepartmentName, DepartmentID)
//		SELECT DepartmentName+"/headquarters", DepartmentID+1000
//		FROM department;
//	COMMIT;
//
cznic's avatar
cznic committed
1629 1630 1631
// If any of the columns of the table were defined using the optional
// constraints clause or the optional defaults clause then those are processed
// on a per row basis. The details are discussed in the "Constraints and
cznic's avatar
cznic committed
1632
// defaults" chapter below the CREATE TABLE statement documentation.
cznic's avatar
cznic committed
1633
//
cznic's avatar
cznic committed
1634 1635 1636 1637 1638 1639 1640 1641 1642 1643 1644 1645 1646 1647 1648 1649 1650 1651 1652 1653 1654 1655 1656 1657 1658 1659 1660 1661 1662 1663 1664 1665
// Explain statement
//
// Explain statement produces a recordset consisting of lines of text which
// describe the execution plan of a statement, if any.
//
//  ExplainStmt = "EXPLAIN" Statement .
//
// For example, the QL tool treats the explain statement specially and outputs
// the joined lines:
//
//	$ ql 'create table t(i int); create table u(j int)'
//	$ ql 'explain select * from t, u where t.i > 42 && u.j < 314'
//	┌Compute Cartesian product of
//	│   ┌Iterate all rows of table "t"
//	│   └Output field names ["i"]
//	│   ┌Iterate all rows of table "u"
//	│   └Output field names ["j"]
//	└Output field names ["t.i" "u.j"]
//	┌Filter on t.i > 42 && u.j < 314
//	│Possibly useful indices
//	│CREATE INDEX xt_i ON t(i);
//	│CREATE INDEX xu_j ON u(j);
//	└Output field names ["t.i" "u.j"]
//	$ ql 'CREATE INDEX xt_i ON t(i); CREATE INDEX xu_j ON u(j);'
//	$ ql 'explain select * from t, u where t.i > 42 && u.j < 314'
//	┌Compute Cartesian product of
//	│   ┌Iterate all rows of table "t" using index "xt_i" where i > 42
//	│   └Output field names ["i"]
//	│   ┌Iterate all rows of table "u" using index "xu_j" where j < 314
//	│   └Output field names ["j"]
//	└Output field names ["t.i" "u.j"]
//	$ ql 'explain select * from t where i > 12 and i between 10 and 20 and i < 42'
cznic's avatar
cznic committed
1666
//	┌Iterate all rows of table "t" using index "xt_i" where i > 12 && i <= 20
cznic's avatar
cznic committed
1667 1668 1669 1670 1671 1672 1673 1674 1675 1676 1677 1678 1679 1680 1681 1682 1683 1684 1685 1686 1687 1688 1689 1690 1691 1692 1693 1694 1695
//	└Output field names ["i"]
//	$
//
// The explanation may aid in uderstanding how a statement/query would be
// executed and if indices are used as expected - or which indices may possibly
// improve the statement performance.  The create index statements above were
// directly copy/pasted in the terminal from the suggestions provided by the
// filter recordset pipeline part returned by the explain statement.
//
// If the statement has nothing special in its plan, the result is the original
// statement.
//
//	$ ql 'explain delete from t where 42 < i'
//	DELETE FROM t WHERE i > 42;
//	$
//
// To get an explanation of the select statement of the IN predicate, use the EXPLAIN
// statement with that particular select statement.
//
//	$ ql 'explain select * from t where i in (select j from u where j > 0)'
//	┌Iterate all rows of table "t"
//	└Output field names ["i"]
//	┌Filter on i IN (SELECT j FROM u WHERE j > 0;)
//	└Output field names ["i"]
//	$ ql 'explain select j from u where j > 0'
//	┌Iterate all rows of table "u" using index "xu_j" where j > 0
//	└Output field names ["j"]
//	$
//
cznic's avatar
cznic committed
1696 1697 1698 1699
// ROLLBACK
//
// The rollback statement closes the innermost transaction nesting level
// discarding any updates to the DB made by it. If that's the outermost level
cznic's avatar
cznic committed
1700
// then the effects on the DB are as if the transaction never happened.
cznic's avatar
cznic committed
1701 1702 1703 1704 1705 1706 1707 1708 1709 1710 1711 1712 1713 1714 1715 1716 1717 1718 1719 1720 1721 1722 1723 1724 1725 1726 1727 1728 1729 1730 1731 1732
//
//  RollbackStmt = "ROLLBACK" .
//
// For example
//
//	// First statement list
//	BEGIN TRANSACTION
//		SELECT * INTO tmp FROM foo;
//		INSERT INTO tmp SELECT * from bar;
//		SELECT * from tmp;
//
// The (temporary) record set from the last statement is returned and can be
// processed by the client.
//
//	// Second statement list
//	ROLLBACK;
//
// In this case the rollback is the same as 'DROP TABLE tmp;' but it can be a
// more complex operation.
//
// SELECT FROM
//
// Select from statements produce recordsets. The optional DISTINCT modifier
// ensures all rows in the result recordset are unique. Either all of the
// resulting fields are returned ('*') or only those named in FieldList.
//
// RecordSetList is a list of table names or parenthesized select statements,
// optionally (re)named using the AS clause.
//
// The result can be filtered using a WhereClause and orderd by the OrderBy
// clause.
//
cznic's avatar
cznic committed
1733
//  SelectStmt = "SELECT" [ "DISTINCT" ] ( "*" | FieldList ) "FROM" RecordSetList
1734 1735 1736
//  	[ JoinClause ] [ WhereClause ] [ GroupByClause ] [ OrderBy ] [ Limit ] [ Offset ].
//
//  JoinClause = ( "LEFT" | "RIGHT" | "FULL" ) [ "OUTER" ] "JOIN" RecordSet "ON" Expression .
cznic's avatar
cznic committed
1737
//
cznic's avatar
cznic committed
1738
//  RecordSet = ( TableName | "(" SelectStmt [ ";" ] ")" ) [ "AS" identifier ] .
cznic's avatar
cznic committed
1739 1740 1741 1742 1743 1744 1745 1746 1747 1748 1749 1750 1751 1752 1753 1754 1755 1756 1757 1758 1759 1760 1761 1762 1763 1764 1765 1766 1767 1768 1769 1770 1771 1772 1773 1774 1775 1776 1777 1778 1779 1780 1781 1782 1783 1784 1785 1786 1787 1788 1789 1790 1791 1792 1793 1794 1795 1796 1797 1798 1799 1800 1801 1802 1803 1804 1805 1806 1807 1808 1809 1810 1811 1812
//  RecordSetList = RecordSet { "," RecordSet } [ "," ] .
//
// For example
//
// 	SELECT * FROM Stock;
//
// 	SELECT DepartmentID
// 	FROM department
// 	WHERE DepartmentID == 42
// 	ORDER BY DepartmentName;
//
// 	SELECT employee.LastName
// 	FROM department, employee
// 	WHERE department.DepartmentID == employee.DepartmentID
// 	ORDER BY DepartmentID;
//
// If Recordset is a nested, parenthesized SelectStmt then it must be given a
// name using the AS clause if its field are to be accessible in expressions.
//
// 	SELECT a.b, c.d
// 	FROM
// 		x AS a,
// 		(
// 			SELECT * FROM y;
// 		) AS c
//	WHERE a.e > c.e;
//
// Fields naming rules
//
// A field is an named expression. Identifiers, not used as a type in
// conversion or a function name in the Call clause, denote names of (other)
// fields, values of which should be used in the expression.
//
//  Field = Expression [ "AS" identifier ] .
//
// The expression can be named using the AS clause.  If the AS clause is not
// present and the expression consists solely of a field name, then that field
// name is used as the name of the resulting field. Otherwise the field is
// unnamed.
//
// For example
//
//	SELECT 314, 42 as AUQLUE, DepartmentID, DepartmentID+1000, LastName as Name from employee;
//	// Fields are []string{"", "AUQLUE", "DepartmentID", "", "Name"}
//
// The SELECT statement can optionally enumerate the desired/resulting fields
// in a list.
//
//  FieldList = Field { "," Field } [ "," ] .
//
// No two identical field names can appear in the list.
//
//	SELECT DepartmentID, LastName, DepartmentID from employee;
//	// duplicate field name "DepartmentID"
//
//	SELECT DepartmentID, LastName, DepartmentID as ID2 from employee;
//	// works
//
// When more than one record set is used in the FROM clause record set list,
// the result record set field names are rewritten to be qualified using
// the record set names.
//
//	SELECT * FROM employee, department;
//	// Fields are []string{"employee.LastName", "employee.DepartmentID", "department.DepartmentID", "department.DepartmentName"
//
// If a particular record set doesn't have a name, its respective fields became
// unnamed.
//
//	SELECT * FROM employee as e, ( SELECT * FROM department);
//	// Fields are []string{"e.LastName", "e.DepartmentID", "", ""
//
//	SELECT * FROM employee AS e, ( SELECT * FROM department) AS d;
//	// Fields are []string{"e.LastName", "e.DepartmentID", "d.DepartmentID", "d.DepartmentName"
//
cznic's avatar
cznic committed
1813 1814 1815 1816 1817 1818 1819 1820 1821 1822 1823 1824 1825 1826 1827 1828 1829 1830 1831
// Outer joins
//
// The optional JOIN clause, for example
//
//	SELECT *
//	FROM a
//	LEFT OUTER JOIN b ON expr;
//
// is mostly equal to
//
//	SELECT *
//	FROM a, b
//	WHERE expr;
//
// except that the rows from a which, when they appear in the cross join, never
// made expr to evaluate to true, are combined with a virtual row from b,
// containing all nulls, and added to the result set. For the RIGHT JOIN
// variant the discussed rules are used for rows from b not satisfying expr ==
// true and the virtual, all-null row "comes" from a. The FULL JOIN adds the
cznic's avatar
cznic committed
1832 1833
// respective rows which would be otherwise provided by the separate executions
// of the LEFT JOIN and RIGHT JOIN variants. For more thorough OUTER JOIN
cznic's avatar
cznic committed
1834 1835
// discussion please see the Wikipedia article at [10].
//
cznic's avatar
cznic committed
1836 1837 1838 1839 1840 1841 1842 1843 1844 1845 1846 1847 1848 1849 1850 1851 1852 1853 1854 1855 1856 1857 1858 1859 1860 1861 1862 1863 1864 1865 1866 1867 1868 1869 1870 1871 1872 1873 1874
// Recordset ordering
//
// Resultins rows of a SELECT statement can be optionally ordered by the ORDER
// BY clause.  Collating proceeds by considering the expressions in the
// expression list left to right until a collating order is determined. Any
// possibly remaining expressions are not evaluated.
//
//  OrderBy = "ORDER" "BY" ExpressionList [ "ASC" | "DESC" ] .
//
// All of the expression values must yield an ordered type or NULL. Ordered
// types are defined in "Comparison operators". Collating of elements having a
// NULL value is different compared to what the comparison operators yield in
// expression evaluation (NULL result instead of a boolean value).
//
// Below, T denotes a non NULL value of any QL type.
//
// 	NULL < T
//
// NULL collates before any non NULL value (is considered smaller than T).
//
//	NULL == NULL
//
// Two NULLs have no collating order (are considered equal).
//
// Recordset filtering
//
// The WHERE clause restricts records considered by some statements, like
// SELECT FROM, DELETE FROM, or UPDATE.
//
//	expression value	consider the record
//	----------------	-------------------
//	true			yes
//	false or NULL		no
//
// It is an error if the expression evaluates to a non null value of non bool
// type.
//
//  WhereClause = "WHERE" Expression .
//
cznic's avatar
cznic committed
1875 1876 1877 1878 1879 1880 1881 1882 1883 1884 1885 1886 1887 1888 1889 1890 1891 1892 1893
// Recordset grouping
//
// The GROUP BY clause is used to project rows having common values into a
// smaller set of rows.
//
// For example
//
//	SELECT Country, sum(Qty) FROM Sales GROUP BY Country;
//
//	SELECT Country, Product FROM Sales GROUP BY Country, Product;
//
//	SELECT DISTINCT Country, Product FROM Sales;
//
// Using the GROUP BY without any aggregate functions in the selected fields is
// in certain cases equal to using the DISTINCT modifier. The last two examples
// above produce the same resultsets.
//
//  GroupByClause = "GROUP BY" ColumnNameList .
//
1894 1895 1896 1897 1898 1899 1900 1901 1902 1903 1904 1905 1906 1907 1908 1909 1910 1911 1912 1913 1914 1915 1916 1917 1918 1919 1920 1921 1922 1923 1924 1925 1926 1927 1928 1929
// Skipping records
//
// The optional OFFSET clause allows to ignore first N records.  For example
//
//	SELECT * FROM t OFFSET 10;
//
// The above will produce only rows 11, 12, ... of the record set, if they
// exist. The value of the expression must a non negative integer, but not
// bigint or duration.
//
//  Offset = "OFFSET" Expression .
//
// Limiting the result set size
//
// The optional LIMIT clause allows to ignore all but first N records.  For
// example
//
//	SELECT * FROM t LIMIT 10;
//
// The above will return at most the first 10 records of the record set. The
// value of the expression must a non negative integer, but not bigint or
// duration.
//
//  Limit = "Limit" Expression .
//
// The LIMIT and OFFSET clauses can be combined. For example
//
//	SELECT * FROM t LIMIT 5 OFFSET 3;
//
// Considering table t has, say 10 records, the above will produce only records
// 4 - 8.
//
//	#1:	Ignore 1/3
//	#2:	Ignore 2/3
//	#3:	Ignore 3/3
//	#4:	Return 1/5
1930
//	#5:	Return 2/5
1931 1932 1933 1934 1935 1936
//	#6:	Return 3/5
//	#7:	Return 4/5
//	#8:	Return 5/5
//
// After returning record #8, no more result rows/records are computed.
//
cznic's avatar
cznic committed
1937 1938 1939 1940 1941
// Select statement evaluation order
//
// 1. The FROM clause is evaluated, producing a Cartesian product of its source
// record sets (tables or nested SELECT statements).
//
1942 1943 1944 1945 1946
// 2. If present, the JOIN cluase is evaluated on the result set of the
// previous evaluation and the recordset specified by the JOIN clause. (...
// JOIN Recordset ON ...)
//
// 3. If present, the WHERE clause is evaluated on the result set of the
1947 1948
// previous evaluation.
//
1949
// 4. If present, the GROUP BY clause is evaluated on the result set of the
1950 1951
// previous evaluation(s).
//
1952
// 5. The SELECT field expressions are evaluated on the result set of the
1953 1954
// previous evaluation(s).
//
1955
// 6. If present, the DISTINCT modifier is evaluated on the result set of the
1956
// previous evaluation(s).
cznic's avatar
cznic committed
1957
//
1958
// 7. If present, the ORDER BY clause is evaluated on the result set of the
1959
// previous evaluation(s).
cznic's avatar
cznic committed
1960
//
1961
// 8. If present, the OFFSET clause is evaluated on the result set of the
1962 1963
// previous evaluation(s). The offset expression is evaluated once for the
// first record produced by the previous evaluations.
cznic's avatar
cznic committed
1964
//
1965
// 9. If present, the LIMIT clause is evaluated on the result set of the
1966 1967
// previous evaluation(s). The limit expression is evaluated once for the first
// record produced by the previous evaluations.
cznic's avatar
cznic committed
1968
//
cznic's avatar
cznic committed
1969 1970 1971 1972 1973 1974 1975 1976 1977 1978 1979 1980 1981 1982 1983 1984 1985 1986
//
// TRUNCATE TABLE
//
// Truncate table statements remove all records from a table. The table must
// exist.
//
//  TruncateTableStmt = "TRUNCATE" "TABLE" TableName .
//
// For example
//
//	BEGIN TRANSACTION
// 		TRUNCATE TABLE department;
//	COMMIT;
//
// UPDATE
//
// Update statements change values of fields in rows of a table.
//
cznic's avatar
cznic committed
1987
//  UpdateStmt = "UPDATE" TableName [ "SET" ] AssignmentList [ WhereClause ] .
cznic's avatar
cznic committed
1988 1989 1990 1991 1992 1993 1994 1995 1996 1997 1998 1999 2000
//
//  AssignmentList = Assignment { "," Assignment } [ "," ] .
//  Assignment = ColumnName "=" Expression .
//
// For example
//
//	BEGIN TRANSACTION
// 		UPDATE department
//			DepartmentName = DepartmentName + " dpt.",
//			DepartmentID = 1000+DepartmentID,
//		WHERE DepartmentID < 1000;
//	COMMIT;
//
cznic's avatar
cznic committed
2001 2002
// Note: The SET clause is optional.
//
cznic's avatar
cznic committed
2003 2004 2005
// If any of the columns of the table were defined using the optional
// constraints clause or the optional defaults clause then those are processed
// on a per row basis. The details are discussed in the "Constraints and
cznic's avatar
cznic committed
2006
// defaults" chapter below the CREATE TABLE statement documentation.
cznic's avatar
cznic committed
2007
//
cznic's avatar
cznic committed
2008 2009
// System Tables
//
2010 2011
// To allow to query for DB meta data, there exist specially named tables, some
// of them being virtual.
2012
//
2013 2014
// Note: Virtual system tables may have fake table-wise unique but meaningless
// and unstable record IDs. Do not apply the built-in id() to any system table.
cznic's avatar
cznic committed
2015 2016 2017 2018 2019 2020 2021
//
// Tables Table
//
// The table __Table lists all tables in the DB. The schema is
//
//	CREATE TABLE __Table (Name string, Schema string);
//
2022 2023
// The Schema column returns the statement to (re)create table Name. This table
// is virtual.
cznic's avatar
cznic committed
2024 2025 2026 2027 2028 2029 2030
//
// Columns Table
//
// The table __Colum lists all columns of all tables in the DB. The schema is
//
//	CREATE TABLE __Column (TableName string, Ordinal int, Name string, Type string);
//
2031
// The Ordinal column defines the 1-based index of the column in the record.
2032
// This table is virtual.
cznic's avatar
cznic committed
2033
//
2034 2035 2036 2037 2038 2039 2040 2041 2042 2043 2044 2045 2046 2047 2048 2049 2050 2051 2052
// Columns2 Table
//
// The table __Colum2 lists all columns of all tables in the DB which have the
// constraint NOT NULL or which have a constraint expression defined or which
// have a default expression defined. The schema is
//
//	CREATE TABLE __Column2 (TableName string, Name string, NotNull bool, ConstraintExpr string, DefaultExpr string)
//
// It's possible to obtain a consolidated recordset for all properties of all
// DB columns using
//
//	SELECT
//		__Column.TableName, __Column.Ordinal, __Column.Name, __Column.Type,
//		__Column2.NotNull, __Column2.ConstraintExpr, __Column2.DefaultExpr,
//	FROM __Column
//	LEFT JOIN __Column2
//	ON __Column.TableName == __Column2.TableName && __Column.Name == __Column2.Name
//	ORDER BY __Column.TableName, __Column.Ordinal;
//
cznic's avatar
cznic committed
2053
// The Name column is the column name in TableName.
2054
//
cznic's avatar
cznic committed
2055 2056 2057 2058
// Indices table
//
// The table __Index lists all indices in the DB. The schema is
//
2059
//	CREATE TABLE __Index (TableName string, ColumnName string, Name string, IsUnique bool);
cznic's avatar
cznic committed
2060
//
2061
// The IsUnique columns reflects if the index was created using the optional
2062
// UNIQUE clause. This table is virtual.
cznic's avatar
cznic committed
2063
//
cznic's avatar
cznic committed
2064 2065 2066 2067
// Built-in functions
//
// Built-in functions are predeclared.
//
2068
// Average
cznic's avatar
cznic committed
2069
//
cznic's avatar
cznic committed
2070 2071
// The built-in aggregate function avg returns the average of values of an
// expression.  Avg ignores NULL values, but returns NULL if all values of a
2072
// column are NULL or if avg is applied to an empty record set.
cznic's avatar
cznic committed
2073
//
cznic's avatar
cznic committed
2074
// 	func avg(e numeric) typeof(e)
cznic's avatar
cznic committed
2075 2076 2077 2078 2079
//
// The column values must be of a numeric type.
//
//	SELECT salesperson, avg(sales) FROM salesforce GROUP BY salesperson;
//
2080 2081 2082 2083 2084 2085
// Contains
//
// The built-in function contains returns true if substr is within s.
//
//	func contains(s, substr string) bool
//
cznic's avatar
cznic committed
2086 2087
// If any argument to contains is NULL the result is NULL.
//
cznic's avatar
cznic committed
2088 2089
// Count
//
cznic's avatar
cznic committed
2090
// The built-in aggregate function count returns how many times an expression
2091 2092
// has a non NULL values or the number of rows in a record set. Note: count()
// returns 0 for an empty record set.
cznic's avatar
cznic committed
2093
//
cznic's avatar
cznic committed
2094
//	func count() int             // The number of rows in a record set.
cznic's avatar
cznic committed
2095
//	func count(*) int            // Equivalent to count().
cznic's avatar
cznic committed
2096
// 	func count(e expression) int // The number of cases where the expression value is not NULL.
cznic's avatar
cznic committed
2097 2098 2099 2100 2101
//
// For example
//
//	SELECT count() FROM department; // # of rows
//
cznic's avatar
cznic committed
2102 2103
//	SELECT count(*) FROM department; // # of rows
//
cznic's avatar
cznic committed
2104 2105 2106 2107 2108 2109
//	SELECT count(DepartmentID) FROM department; // # of records with non NULL field DepartmentID
//
//	SELECT count()-count(DepartmentID) FROM department; // # of records with NULL field DepartmentID
//
//	SELECT count(foo+bar*3) AS y FROM t; // # of cases where 'foo+bar*3' is non NULL
//
cznic's avatar
cznic committed
2110 2111 2112 2113 2114 2115 2116 2117 2118 2119 2120 2121 2122 2123 2124 2125 2126 2127 2128
// Date
//
// Date returns the time corresponding to
//
//	yyyy-mm-dd hh:mm:ss + nsec nanoseconds
//
// in the appropriate zone for that time in the given location.
//
// The month, day, hour, min, sec, and nsec values may be outside their usual
// ranges and will be normalized during the conversion. For example, October 32
// converts to November 1.
//
// A daylight savings time transition skips or repeats times. For example, in
// the United States, March 13, 2011 2:15am never occurred, while November 6,
// 2011 1:15am occurred twice. In such cases, the choice of time zone, and
// therefore the time, is not well-defined. Date returns a time that is correct
// in one of the two zones involved in the transition, but it does not
// guarantee which.
//
cznic's avatar
cznic committed
2129
// 	func date(year, month, day, hour, min, sec, nsec int, loc string) time
cznic's avatar
cznic committed
2130
//
cznic's avatar
cznic committed
2131 2132 2133 2134 2135
// A location maps time instants to the zone in use at that time. Typically,
// the location represents the collection of time offsets in use in a
// geographical area, such as "CEST" and "CET" for central Europe.  "local"
// represents the system's local time zone. "UTC" represents Universal
// Coordinated Time (UTC).
cznic's avatar
cznic committed
2136 2137 2138
//
// The month specifies a month of the year (January = 1, ...).
//
cznic's avatar
cznic committed
2139 2140
// If any argument to date is NULL the result is NULL.
//
cznic's avatar
cznic committed
2141 2142 2143 2144 2145 2146 2147 2148
// Day
//
// The built-in function day returns the day of the month specified by t.
//
// 	func day(t time) int
//
// If the argument to day is NULL the result is NULL.
//
cznic's avatar
cznic committed
2149 2150 2151 2152 2153 2154 2155 2156 2157 2158 2159 2160 2161 2162 2163 2164
// Format time
//
// The built-in function formatTime returns a textual representation of the
// time value formatted according to layout, which defines the format by
// showing how the reference time,
//
//	Mon Jan 2 15:04:05 -0700 MST 2006
//
// would be displayed if it were the value; it serves as an example of the
// desired output. The same display rules will then be applied to the time
// value.
//
// 	func formatTime(t time, layout string) string
//
// If any argument to formatTime is NULL the result is NULL.
//
cznic's avatar
cznic committed
2165 2166 2167 2168 2169 2170 2171 2172 2173 2174 2175 2176 2177 2178 2179 2180 2181 2182 2183
// NOTE: The string value of the time zone, like "CET" or "ACDT", is dependent
// on the time zone of the machine the function is run on. For example, if the
// t value is in "CET", but the machine is in "ACDT", instead of "CET" the
// result is "+0100". This is the same what Go (time.Time).String() returns and
// in fact formatTime directly calls t.String().
//
//	formatTime(date(2006, 1, 2, 15, 4, 5, 999999999, "CET"))
//
// returns
//
//	2006-01-02 15:04:05.999999999 +0100 CET
//
// on a machine in the CET time zone, but may return
//
//	2006-01-02 15:04:05.999999999 +0100 +0100
//
// on a machine in the ACDT zone. The time value is in both cases the same so
// its ordering and comparing is correct. Only the display value can differ.
//
2184 2185
// Format numbers
//
2186
// The built-in functions formatFloat and formatInt format numbers
2187 2188 2189 2190 2191 2192 2193 2194 2195 2196 2197 2198 2199 2200 2201 2202 2203
// to strings using go's number format functions in the `strconv` package. For
// all three functions, only the first argument is mandatory. The default values
// of the rest are shown in the examples. If the first argument is NULL, the
// result is NULL.
//
//	formatFloat(43.2[, 'g', -1, 64]) string
//
// returns
//
//	"43.2"
//
//	formatInt(-42[, 10]) string
//
// returns
//
//	"-42"
//
2204
//	formatInt(uint32(42)[, 10]) string
2205 2206 2207 2208 2209
//
// returns
//
//	"42"
//
2210 2211 2212
// Unlike the `strconv` equivalent, the formatInt function handles all integer
// types, both signed and unsigned.
//
2213 2214 2215 2216 2217 2218
// HasPrefix
//
// The built-in function hasPrefix tests whether the string s begins with prefix.
//
//	func hasPrefix(s, prefix string) bool
//
cznic's avatar
cznic committed
2219 2220
// If any argument to hasPrefix is NULL the result is NULL.
//
2221 2222 2223 2224 2225 2226
// HasSuffix
//
// The built-in function hasSuffix tests whether the string s ends with suffix.
//
//	func hasSuffix(s, suffix string) bool
//
cznic's avatar
cznic committed
2227 2228
// If any argument to hasSuffix is NULL the result is NULL.
//
cznic's avatar
cznic committed
2229 2230 2231 2232 2233 2234 2235 2236
// Hour
//
// The built-in function hour returns the hour within the day specified by t,
// in the range [0, 23].
//
// 	func hour(t time) int
//
// If the argument to hour is NULL the result is NULL.
cznic's avatar
cznic committed
2237
//
2238 2239 2240 2241 2242
// Hours
//
// The built-in function hours returns the duration as a floating point number
// of hours.
//
cznic's avatar
cznic committed
2243
// 	func hours(d duration) float