You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
2720 lines
94 KiB
2720 lines
94 KiB
// Copyright 2014 The ql Authors. All rights reserved.
|
|
// Use of this source code is governed by a BSD-style
|
|
// license that can be found in the LICENSE file.
|
|
|
|
//MAYBE set operations
|
|
//MAYBE +=, -=, ...
|
|
|
|
//TODO verify there's a graceful failure for a 2G+ blob on a 32 bit machine.
|
|
|
|
// Package ql implements a pure Go embedded SQL database engine.
|
|
//
|
|
// Builders
|
|
//
|
|
// Builder results available at
|
|
//
|
|
// https://modern-c.appspot.com/-/builder/?importpath=modernc.org%2fql
|
|
//
|
|
// 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).
|
|
//
|
|
// Change list
|
|
//
|
|
// 2020-12-10: sql/database driver now supports url parameter removeemptywal=N
|
|
// which has the same semantics as passing RemoveEmptyWAL = N != 0 to OpenFile
|
|
// options.
|
|
//
|
|
// 2020-11-09: Add IF NOT EXISTS support for the INSERT INTO statement. Add
|
|
// IsDuplicateUniqueIndexError function.
|
|
//
|
|
// 2018-11-04: Back end file format V2 is now released. To use the new format
|
|
// for newly created databases set the FileFormat field in *Options passed to
|
|
// OpenFile to value 2 or use the driver named "ql2" instead of "ql".
|
|
//
|
|
// - Both the old and new driver will properly open and use, read and write the
|
|
// old (V1) or new file (V2) format of an existing database.
|
|
//
|
|
// - V1 format has a record size limit of ~64 kB. V2 format record size limit
|
|
// is math.MaxInt32.
|
|
//
|
|
// - V1 format uncommitted transaction size is limited by memory resources. V2
|
|
// format uncommitted transaction is limited by free disk space.
|
|
//
|
|
// - A direct consequence of the previous is that small transactions perform
|
|
// better using V1 format and big transactions perform better using V2 format.
|
|
//
|
|
// - V2 format uses substantially less memory.
|
|
//
|
|
// 2018-08-02: Release v1.2.0 adds initial support for Go modules.
|
|
//
|
|
// 2017-01-10: Release v1.1.0 fixes some bugs and adds a configurable WAL
|
|
// headroom.
|
|
//
|
|
// https://gitlab.com/cznic/ql/issues/140
|
|
//
|
|
// 2016-07-29: Release v1.0.6 enables alternatively using = instead of == for
|
|
// equality operation.
|
|
//
|
|
// https://gitlab.com/cznic/ql/issues/131
|
|
//
|
|
// 2016-07-11: Release v1.0.5 undoes vendoring of lldb. QL now uses stable lldb
|
|
// (modernc.org/lldb).
|
|
//
|
|
// https://gitlab.com/cznic/ql/issues/128
|
|
//
|
|
// 2016-07-06: Release v1.0.4 fixes a panic when closing the WAL file.
|
|
//
|
|
// https://gitlab.com/cznic/ql/pull/127
|
|
//
|
|
// 2016-04-03: Release v1.0.3 fixes a data race.
|
|
//
|
|
// https://gitlab.com/cznic/ql/issues/126
|
|
//
|
|
// 2016-03-23: Release v1.0.2 vendors gitlab.com/cznic/exp/lldb and
|
|
// github.com/camlistore/go4/lock.
|
|
//
|
|
// 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.
|
|
//
|
|
// 2015-06-15: To improve compatibility with other SQL implementations, the
|
|
// count built-in aggregate function now accepts * as its argument.
|
|
//
|
|
// 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
|
|
// 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.
|
|
//
|
|
// 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>'`.
|
|
//
|
|
// 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.
|
|
//
|
|
// 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.
|
|
//
|
|
// 2015-04-20: Added support for {LEFT,RIGHT,FULL} [OUTER] JOIN.
|
|
//
|
|
// 2015-04-18: Column definitions can now have constraints and defaults.
|
|
// Details are discussed in the "Constraints and defaults" chapter below the
|
|
// CREATE TABLE statement documentation.
|
|
//
|
|
// 2015-03-06: New built-in functions formatFloat and formatInt. Thanks
|
|
// urandom! (https://github.com/urandom)
|
|
//
|
|
// 2015-02-16: IN predicate now accepts a SELECT statement. See the updated
|
|
// "Predicates" section.
|
|
//
|
|
// 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".
|
|
//
|
|
// 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
|
|
// (uncommitted) transaction in progress means losing the transaction data.
|
|
// 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.
|
|
//
|
|
// 2014-09-21: id() now optionally accepts a single argument - a table name.
|
|
//
|
|
// 2014-09-01: Added the DB.Flush() method and the LIKE pattern matching
|
|
// predicate.
|
|
//
|
|
// 2014-08-08: The built in functions max and min now accept also time values.
|
|
// Thanks opennota! (https://github.com/opennota)
|
|
//
|
|
// 2014-06-05: RecordSet interface extended by new methods FirstRow and Rows.
|
|
//
|
|
// 2014-06-02: Indices on id() are now used by SELECT statements.
|
|
//
|
|
// 2014-05-07: Introduction of Marshal, Schema, Unmarshal.
|
|
//
|
|
// 2014-04-15:
|
|
//
|
|
// Added optional IF NOT EXISTS clause to CREATE INDEX and optional IF EXISTS
|
|
// clause to DROP INDEX.
|
|
//
|
|
// 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.
|
|
//
|
|
// 2014-04-11: Introduction of LIMIT, OFFSET.
|
|
//
|
|
// 2014-04-10: Introduction of query rewriting.
|
|
//
|
|
// 2014-04-07: Introduction of indices.
|
|
//
|
|
// 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 modernc.org/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/modernc.org/zappy/*.go
|
|
// $ go install -tags purego modernc.org/zappy
|
|
// $ go install modernc.org/ql
|
|
//
|
|
// 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" .
|
|
// unicode_letter = . // Unicode category L.
|
|
// unicode_digit = . // Unocode category D.
|
|
//
|
|
// Letters and digits
|
|
//
|
|
// The underscore character _ (U+005F) is considered a letter.
|
|
//
|
|
// letter = ascii_letter | unicode_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.
|
|
// There are two kinds of identifiers, normal idententifiers and quoted
|
|
// identifiers.
|
|
//
|
|
// indentifier = normal_identifier | quoted_identifier.
|
|
//
|
|
// An normal identifier is a sequence of one or more letters and digits.
|
|
// The first character in an identifier must be a letter.
|
|
//
|
|
// normal_identifier = letter { letter | decimal_digit | unicode_digit } .
|
|
//
|
|
// For example
|
|
//
|
|
// price
|
|
// _tmp42
|
|
// Sales
|
|
//
|
|
// A quoted identifier is a string of any charaters between guillmets «».
|
|
// Quoted identifiers allow QL key words or phrases with spaces to be used
|
|
// as identifiers. The guillemets were chosen because QL already uses
|
|
// double quotes, single quotes, and backticks for other quoting purposes.
|
|
//
|
|
// quoted_identifier = "«" { unicode_char | newline } "»".
|
|
//
|
|
// For example
|
|
//
|
|
// «TRANSACTION»
|
|
// «duration»
|
|
// «lovely stories»
|
|
//
|
|
//
|
|
// No identifiers are predeclared, however note that no keyword can be used as
|
|
// a normal 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
|
|
// __Column2
|
|
// __Index
|
|
// __Table
|
|
//
|
|
// Keywords
|
|
//
|
|
// The following keywords are reserved and may not be used as identifiers.
|
|
//
|
|
// ADD complex128 FROM LEFT string
|
|
// ALTER complex64 FULL LIKE TABLE
|
|
// AND CREATE GROUP LIMIT time
|
|
// AS DEFAULT IF NOT TRANSACTION
|
|
// ASC DELETE IN NULL true
|
|
// BEGIN DESC INDEX OFFSET TRUNCATE
|
|
// BETWEEN DISTINCT INSERT ON uint
|
|
// bigint DROP int OR uint16
|
|
// bigrat duration int16 ORDER uint32
|
|
// blob EXISTS int32 OUTER uint64
|
|
// bool EXPLAIN int64 RIGHT uint8
|
|
// BY false int8 ROLLBACK UNIQUE
|
|
// byte float INTO rune UPDATE
|
|
// COLUMN float32 IS SELECT VALUES
|
|
// COMMIT float64 JOIN SET WHERE
|
|
//
|
|
// 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 = "<=" .
|
|
// eq = "==" | "=" .
|
|
// 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.
|
|
//
|
|
// ql_parameter = ( "?" | "$" ) "1" … "9" { "0" … "9" } .
|
|
//
|
|
// 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.
|
|
//
|
|
// 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" .
|
|
//
|
|
// Named instances of the boolean, numeric, and string types are keywords. The
|
|
// names are not case sensitive.
|
|
//
|
|
// 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.
|
|
//
|
|
// 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.
|
|
//
|
|
// 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.
|
|
//
|
|
// 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)
|
|
// duration the set of all signed 64-bit integers (-9223372036854775808 to 9223372036854775807)
|
|
// bigint the set of all integers
|
|
//
|
|
// bigrat the set of all rational numbers
|
|
//
|
|
// 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
|
|
// expression or assignment.
|
|
//
|
|
// 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.
|
|
//
|
|
// 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.
|
|
//
|
|
// Predeclared functions
|
|
//
|
|
// The following functions are implicitly declared
|
|
//
|
|
// avg complex contains count date
|
|
// day formatTime formatFloat formatInt
|
|
// 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
|
|
//
|
|
// 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 .
|
|
//
|
|
// Call = "(" [ "*" | ExpressionList ] ")" . // * only in count(*).
|
|
// 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]
|
|
//
|
|
// denotes the element of a string indexed by x. Its type is byte. The value x
|
|
// is called the index. The following rules apply
|
|
//
|
|
// - 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.
|
|
//
|
|
// - 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.
|
|
//
|
|
// Integer values of type bigint or duration cannot be used as indices.
|
|
//
|
|
// 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.
|
|
//
|
|
// Expression = Term { ( oror | "OR" ) Term } .
|
|
//
|
|
// ExpressionList = Expression { "," Expression } [ "," ].
|
|
// Factor = PrimaryFactor { ( ge | ">" | le | "<" | neq | eq | "LIKE" ) PrimaryFactor } [ Predicate ] .
|
|
// PrimaryFactor = PrimaryTerm { ( "^" | "|" | "-" | "+" ) PrimaryTerm } .
|
|
// PrimaryTerm = UnaryExpr { ( andnot | "&" | lsh | rsh | "%" | "/" | "*" ) UnaryExpr } .
|
|
// Term = Factor { ( andand | "AND" ) Factor } .
|
|
// 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.
|
|
//
|
|
// Pattern matching
|
|
//
|
|
// Expressions of the form
|
|
//
|
|
// expr1 LIKE expr2
|
|
//
|
|
// yield a boolean value true if expr2, a regular expression, matches expr1
|
|
// (see also [6]). Both expression must be of type string. If any one of the
|
|
// expressions is NULL the result is NULL.
|
|
//
|
|
// Predicates
|
|
//
|
|
// Predicates are special form expressions having a boolean result type.
|
|
//
|
|
// 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".
|
|
//
|
|
// 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
|
|
//
|
|
// 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 ")"
|
|
// | "IN" "(" SelectStmt [ ";" ] ")"
|
|
// | "BETWEEN" PrimaryFactor "AND" PrimaryFactor
|
|
// )
|
|
// | "IS" [ "NOT" ] "NULL"
|
|
// ).
|
|
//
|
|
// Expressions of the form
|
|
//
|
|
// expr IS NULL // case A
|
|
//
|
|
// expr IS NOT NULL // case B
|
|
//
|
|
// yield a boolean value true if expr does not have a specific type (case A) or
|
|
// 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 (+, -, *,
|
|
// /) 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.
|
|
//
|
|
// + sum integers, rationals, floats, complex values, strings
|
|
// - difference integers, rationals, floats, complex values, times
|
|
// * product integers, rationals, floats, complex values
|
|
// / quotient integers, rationals, floats, complex values
|
|
// % 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.
|
|
//
|
|
// A value of type duration can be added to or subtracted from a value of type time.
|
|
//
|
|
// now() + duration("1h") // time after 1 hour from now
|
|
// duration("1h") + now() // time after 1 hour from now
|
|
// now() - duration("1h") // time before 1 hour from now
|
|
// duration("1h") - now() // illegal, negative times do not exist
|
|
//
|
|
// Times can subtracted from each other producing a value of type duration.
|
|
//
|
|
// now() - t0 // elapsed time since t0
|
|
// now() + now() // illegal, operator + not defined for times
|
|
//
|
|
// 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''.
|
|
//
|
|
// 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.
|
|
//
|
|
// Integers of type bigint and rationals do not overflow but their handling is
|
|
// limited by the memory resources available to the program.
|
|
//
|
|
// 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.
|
|
//
|
|
// - Complex values are comparable. Two complex values u and v are equal if
|
|
// both real(u) == real(v) and imag(u) == imag(v).
|
|
//
|
|
// - Integer values are comparable and ordered, in the usual way. Note that
|
|
// durations are integers.
|
|
//
|
|
// - Floating point values are comparable and ordered, as defined by the
|
|
// IEEE-754 standard.
|
|
//
|
|
// - Rational values are comparable and ordered, in the usual way.
|
|
//
|
|
// - String and Blob values are comparable and ordered, lexically byte-wise.
|
|
//
|
|
// - Time values are comparable and ordered.
|
|
//
|
|
// 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.
|
|
//
|
|
// - x is an integer, except bigint or duration, and T is a string type.
|
|
//
|
|
// 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.
|
|
//
|
|
// Conversions to and from a string type
|
|
//
|
|
// 1. Converting a signed or unsigned integer value to a string type yields a
|
|
// 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"
|
|
//
|
|
// 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{}
|
|
//
|
|
// 4. Converting a value of a bigint type to a string yields a string
|
|
// containing the decimal decimal representation of the integer.
|
|
//
|
|
// 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”
|
|
// 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.
|
|
//
|
|
// bigint("2305843009213693951") // M9
|
|
// bigint("0x1ffffffffffffffffffffff") // M10 == 2^89-1
|
|
//
|
|
// 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")
|
|
//
|
|
// 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
|
|
//
|
|
// 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"
|
|
//
|
|
// 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
|
|
// | CreateIndexStmt | CreateTableStmt | DeleteFromStmt | DropIndexStmt
|
|
// | DropTableStmt | InsertIntoStmt | RollbackStmt | SelectStmt
|
|
// | TruncateTableStmt | UpdateStmt | ExplainStmt.
|
|
//
|
|
// 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
|
|
// 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.
|
|
//
|
|
// 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;
|
|
//
|
|
// 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.
|
|
//
|
|
// 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;
|
|
//
|
|
// 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
|
|
//
|
|
// 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;
|
|
//
|
|
// 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
|
|
// 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
|
|
// column name of the table the index is on.
|
|
//
|
|
// CreateIndexStmt = "CREATE" [ "UNIQUE" ] "INDEX" [ "IF" "NOT" "EXISTS" ]
|
|
// IndexName "ON" TableName "(" ExpressionList ")" .
|
|
//
|
|
// 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.
|
|
//
|
|
// The UNIQUE modifier requires the indexed values tuple to be index-wise
|
|
// unique or have all values NULL.
|
|
//
|
|
// The optional IF NOT EXISTS clause makes the statement a no operation if the
|
|
// index already exists.
|
|
//
|
|
// 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.
|
|
//
|
|
// CREATE TABLE
|
|
//
|
|
// Create table statements create new tables. A column definition declares the
|
|
// 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.
|
|
//
|
|
// CreateTableStmt = "CREATE" "TABLE" [ "IF" "NOT" "EXISTS" ] TableName
|
|
// "(" ColumnDef { "," ColumnDef } [ "," ] ")" .
|
|
//
|
|
// ColumnDef = ColumnName Type [ "NOT" "NULL" | Expression ] [ "DEFAULT" Expression ] .
|
|
// ColumnName = identifier .
|
|
// TableName = identifier .
|
|
//
|
|
// For example
|
|
//
|
|
// BEGIN TRANSACTION;
|
|
// CREATE TABLE department (
|
|
// DepartmentID int,
|
|
// DepartmentName string,
|
|
// );
|
|
// CREATE TABLE employee (
|
|
// LastName string,
|
|
// DepartmentID int,
|
|
// );
|
|
// COMMIT;
|
|
//
|
|
// The optional IF NOT EXISTS clause makes the statement a no operation if the
|
|
// table already exists.
|
|
//
|
|
// 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
|
|
// validate the column. If the value of the expression is true then the
|
|
// validation succeeded. If the value of the expression is false or NULL then
|
|
// the validation fails. If the value of the expression is not of type bool an
|
|
// error occurs.
|
|
//
|
|
// BEGIN TRANSACTION;
|
|
// CREATE TABLE department (
|
|
// DepartmentID int,
|
|
// DepartmentName string DepartmentName IN ("HQ", "R/D", "Lab", "HR"),
|
|
// );
|
|
// COMMIT;
|
|
//
|
|
// 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,
|
|
// DepartmentName string DepartmentName IN ("HQ", "R/D", "Lab", "HR") DEFAULT "HQ",
|
|
// );
|
|
// COMMIT;
|
|
//
|
|
// 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;
|
|
//
|
|
//
|
|
// Constraints and defaults
|
|
//
|
|
// 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.
|
|
//
|
|
// 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
|
|
// WHERE DepartmentName == "Ponies";
|
|
// COMMIT;
|
|
//
|
|
// If the WHERE clause is not present then all rows are removed and the
|
|
// statement is equivalent to the TRUNCATE TABLE statement.
|
|
//
|
|
// DROP INDEX
|
|
//
|
|
// Drop index statements remove indices from the DB. The index must exist.
|
|
//
|
|
// DropIndexStmt = "DROP" "INDEX" [ "IF" "EXISTS" ] IndexName .
|
|
// IndexName = identifier .
|
|
//
|
|
// For example
|
|
//
|
|
// BEGIN TRANSACTION;
|
|
// DROP INDEX ItemsOrderID;
|
|
// COMMIT;
|
|
//
|
|
// The optional IF EXISTS clause makes the statement a no operation if the
|
|
// index does not exist.
|
|
//
|
|
// DROP TABLE
|
|
//
|
|
// Drop table statements remove tables from the DB. The table must exist.
|
|
//
|
|
// DropTableStmt = "DROP" "TABLE" [ "IF" "EXISTS" ] TableName .
|
|
//
|
|
// For example
|
|
//
|
|
// BEGIN TRANSACTION;
|
|
// DROP TABLE Inventory;
|
|
// COMMIT;
|
|
//
|
|
// The optional IF EXISTS clause makes the statement a no operation if the
|
|
// table does not exist.
|
|
//
|
|
// 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.
|
|
//
|
|
// If there exists an unique index that would make the insert statement fail,
|
|
// the optional IF NOT EXISTS turns the insert statement in such case into a
|
|
// no-op.
|
|
//
|
|
// InsertIntoStmt = "INSERT" "INTO" TableName [ "IF" "NOT" "EXISTS" ]
|
|
// [ "(" 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;
|
|
//
|
|
// 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
|
|
// defaults" chapter below the CREATE TABLE statement documentation.
|
|
//
|
|
// 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'
|
|
// ┌Iterate all rows of table "t" using index "xt_i" where i > 12 && i <= 20
|
|
// └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"]
|
|
// $
|
|
//
|
|
// 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
|
|
// then the effects on the DB are as if the transaction never happened.
|
|
//
|
|
// 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.
|
|
//
|
|
// SelectStmt = "SELECT" [ "DISTINCT" ] ( "*" | FieldList ) [ "FROM" RecordSetList ]
|
|
// [ JoinClause ] [ WhereClause ] [ GroupByClause ] [ OrderBy ] [ Limit ] [ Offset ].
|
|
//
|
|
// JoinClause = ( "LEFT" | "RIGHT" | "FULL" ) [ "OUTER" ] "JOIN" RecordSet "ON" Expression .
|
|
//
|
|
// RecordSet = ( TableName | "(" SelectStmt [ ";" ] ")" ) [ "AS" identifier ] .
|
|
// 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"
|
|
//
|
|
// 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
|
|
// respective rows which would be otherwise provided by the separate executions
|
|
// of the LEFT JOIN and RIGHT JOIN variants. For more thorough OUTER JOIN
|
|
// discussion please see the Wikipedia article at [10].
|
|
//
|
|
// 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.
|
|
//
|
|
// Another form of the WHERE clause is an existence predicate of a
|
|
// parenthesized select statement. The EXISTS form evaluates to true if the
|
|
// parenthesized SELECT statement produces a non empty record set. The NOT
|
|
// EXISTS form evaluates to true if the parenthesized SELECT statement produces
|
|
// an empty record set. The parenthesized SELECT statement is evaluated only
|
|
// once (TODO issue #159).
|
|
//
|
|
// WhereClause = "WHERE" Expression
|
|
// | "WHERE" "EXISTS" "(" SelectStmt ")"
|
|
// | "WHERE" "NOT" "EXISTS" "(" SelectStmt ")" .
|
|
//
|
|
// 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 .
|
|
//
|
|
// 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
|
|
// #5: Return 2/5
|
|
// #6: Return 3/5
|
|
// #7: Return 4/5
|
|
// #8: Return 5/5
|
|
//
|
|
// After returning record #8, no more result rows/records are computed.
|
|
//
|
|
// Select statement evaluation order
|
|
//
|
|
// 1. The FROM clause is evaluated, producing a Cartesian product of its source
|
|
// record sets (tables or nested SELECT statements).
|
|
//
|
|
// 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
|
|
// previous evaluation.
|
|
//
|
|
// 4. If present, the GROUP BY clause is evaluated on the result set of the
|
|
// previous evaluation(s).
|
|
//
|
|
// 5. The SELECT field expressions are evaluated on the result set of the
|
|
// previous evaluation(s).
|
|
//
|
|
// 6. If present, the DISTINCT modifier is evaluated on the result set of the
|
|
// previous evaluation(s).
|
|
//
|
|
// 7. If present, the ORDER BY clause is evaluated on the result set of the
|
|
// previous evaluation(s).
|
|
//
|
|
// 8. If present, the OFFSET clause is evaluated on the result set of the
|
|
// previous evaluation(s). The offset expression is evaluated once for the
|
|
// first record produced by the previous evaluations.
|
|
//
|
|
// 9. If present, the LIMIT clause is evaluated on the result set of the
|
|
// previous evaluation(s). The limit expression is evaluated once for the first
|
|
// record produced by the previous evaluations.
|
|
//
|
|
//
|
|
// 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.
|
|
//
|
|
// UpdateStmt = "UPDATE" TableName [ "SET" ] AssignmentList [ WhereClause ] .
|
|
//
|
|
// AssignmentList = Assignment { "," Assignment } [ "," ] .
|
|
// Assignment = ColumnName "=" Expression .
|
|
//
|
|
// For example
|
|
//
|
|
// BEGIN TRANSACTION
|
|
// UPDATE department
|
|
// DepartmentName = DepartmentName + " dpt.",
|
|
// DepartmentID = 1000+DepartmentID,
|
|
// WHERE DepartmentID < 1000;
|
|
// COMMIT;
|
|
//
|
|
// Note: The SET clause is optional.
|
|
//
|
|
// 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
|
|
// defaults" chapter below the CREATE TABLE statement documentation.
|
|
//
|
|
// System Tables
|
|
//
|
|
// To allow to query for DB meta data, there exist specially named tables, some
|
|
// of them being virtual.
|
|
//
|
|
// 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.
|
|
//
|
|
// Tables Table
|
|
//
|
|
// The table __Table lists all tables in the DB. The schema is
|
|
//
|
|
// CREATE TABLE __Table (Name string, Schema string);
|
|
//
|
|
// The Schema column returns the statement to (re)create table Name. This table
|
|
// is virtual.
|
|
//
|
|
// 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);
|
|
//
|
|
// The Ordinal column defines the 1-based index of the column in the record.
|
|
// This table is virtual.
|
|
//
|
|
// 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;
|
|
//
|
|
// The Name column is the column name in TableName.
|
|
//
|
|
// Indices table
|
|
//
|
|
// The table __Index lists all indices in the DB. The schema is
|
|
//
|
|
// CREATE TABLE __Index (TableName string, ColumnName string, Name string, IsUnique bool);
|
|
//
|
|
// The IsUnique columns reflects if the index was created using the optional
|
|
// UNIQUE clause. This table is virtual.
|
|
//
|
|
// Built-in functions
|
|
//
|
|
// Built-in functions are predeclared.
|
|
//
|
|
// Average
|
|
//
|
|
// 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
|
|
// column are NULL or if avg is applied to an empty record set.
|
|
//
|
|
// func avg(e numeric) typeof(e)
|
|
//
|
|
// The column values must be of a numeric type.
|
|
//
|
|
// SELECT salesperson, avg(sales) FROM salesforce GROUP BY salesperson;
|
|
//
|
|
// Coalesce
|
|
//
|
|
// The built-in function coalesce takes at least one argument and returns
|
|
// the first of its arguments which is not NULL. If all arguments are NULL,
|
|
// this function returns NULL. This is useful for providing defaults
|
|
// for NULL values in a select query.
|
|
//
|
|
// func coalesce(args ...interface{}) interface{}
|
|
//
|
|
// Contains
|
|
//
|
|
// The built-in function contains returns true if substr is within s.
|
|
//
|
|
// func contains(s, substr string) bool
|
|
//
|
|
// If any argument to contains is NULL the result is NULL.
|
|
//
|
|
// Count
|
|
//
|
|
// The built-in aggregate function count returns how many times an expression
|
|
// has a non NULL values or the number of rows in a record set. Note: count()
|
|
// returns 0 for an empty record set.
|
|
//
|
|
// func count() int // The number of rows in a record set.
|
|
// func count(*) int // Equivalent to count().
|
|
// func count(e expression) int // The number of cases where the expression value is not NULL.
|
|
//
|
|
// For example
|
|
//
|
|
// SELECT count() FROM department; // # of rows
|
|
//
|
|
// SELECT count(*) FROM department; // # of rows
|
|
//
|
|
// 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
|
|
//
|
|
// 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.
|
|
//
|
|
// func date(year, month, day, hour, min, sec, nsec int, loc string) time
|
|
//
|
|
// 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).
|
|
//
|
|
// The month specifies a month of the year (January = 1, ...).
|
|
//
|
|
// If any argument to date is NULL the result is NULL.
|
|
//
|
|
// 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.
|
|
//
|
|
// 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.
|
|
//
|
|
// 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.
|
|
//
|
|
// Format numbers
|
|
//
|
|
// The built-in functions formatFloat and formatInt format numbers
|
|
// 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"
|
|
//
|
|
// formatInt(uint32(42)[, 10]) string
|
|
//
|
|
// returns
|
|
//
|
|
// "42"
|
|
//
|
|
// Unlike the `strconv` equivalent, the formatInt function handles all integer
|
|
// types, both signed and unsigned.
|
|
//
|
|
// HasPrefix
|
|
//
|
|
// The built-in function hasPrefix tests whether the string s begins with prefix.
|
|
//
|
|
// func hasPrefix(s, prefix string) bool
|
|
//
|
|
// If any argument to hasPrefix is NULL the result is NULL.
|
|
//
|
|
// HasSuffix
|
|
//
|
|
// The built-in function hasSuffix tests whether the string s ends with suffix.
|
|
//
|
|
// func hasSuffix(s, suffix string) bool
|
|
//
|
|
// If any argument to hasSuffix is NULL the result is NULL.
|
|
//
|
|
// 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.
|
|
//
|
|
// Hours
|
|
//
|
|
// The built-in function hours returns the duration as a floating point number
|
|
// of hours.
|
|
//
|
|
// func hours(d duration) float
|
|
//
|
|
// If the argument to hours is NULL the result is NULL.
|
|
//
|
|
// Record id
|
|
//
|
|
// The built-in function id takes zero or one arguments. If no argument is
|
|
// provided, id() returns a table-unique automatically assigned numeric
|
|
// identifier of type int. Ids of deleted records are not reused unless the DB
|
|
// becomes completely empty (has no tables).
|
|
//
|
|
// func id() int
|
|
//
|
|
// For example
|
|
//
|
|
// SELECT id(), LastName
|
|
// FROM employee;
|
|
//
|
|
// If id() without arguments is called for a row which is not a table record
|
|
// then the result value is NULL.
|
|
//
|
|
// For example
|
|
//
|
|
// SELECT id(), e.LastName, e.DepartmentID, d.DepartmentID
|
|
// FROM
|
|
// employee AS e,
|
|
// department AS d,
|
|
// WHERE e.DepartmentID == d.DepartmentID;
|
|
// // Will always return NULL in first field.
|
|
//
|
|
// SELECT e.ID, e.LastName, e.DepartmentID, d.DepartmentID
|
|
// FROM
|
|
// (SELECT id() AS ID, LastName, DepartmentID FROM employee) AS e,
|
|
// department as d,
|
|
// WHERE e.DepartmentID == d.DepartmentID;
|
|
// // Will work.
|
|
//
|
|
// If id() has one argument it must be a table name of a table in a cross join.
|
|
//
|
|
// For example
|
|
//
|
|
// SELECT *
|
|
// FROM foo, bar
|
|
// WHERE bar.fooID == id(foo)
|
|
// ORDER BY id(foo);
|
|
//
|
|
// Length
|
|
//
|
|
// The built-in function len takes a string argument and returns the lentgh of
|
|
// the string in bytes.
|
|
//
|
|
// func len(s string) int
|
|
//
|
|
// The expression len(s) is constant if s is a string constant.
|
|
//
|
|
// If the argument to len is NULL the result is NULL.
|
|
//
|
|
// Maximum
|
|
//
|
|
// The built-in aggregate function max returns the largest value of an
|
|
// expression in a record set. Max ignores NULL values, but returns NULL if
|
|
// all values of a column are NULL or if max is applied to an empty record set.
|
|
//
|
|
// func max(e expression) typeof(e) // The largest value of the expression.
|
|
//
|
|
// The expression values must be of an ordered type.
|
|
//
|
|
// For example
|
|
//
|
|
// SELECT department, max(sales) FROM t GROUP BY department;
|
|
//
|
|
// Minimum
|
|
//
|
|
// The built-in aggregate function min returns the smallest value of an
|
|
// expression in a record set. Min ignores NULL values, but returns NULL if
|
|
// all values of a column are NULL or if min is applied to an empty record set.
|
|
//
|
|
// func min(e expression) typeof(e) // The smallest value of the expression.
|
|
//
|
|
// For example
|
|
//
|
|
// SELECT a, min(b) FROM t GROUP BY a;
|
|
//
|
|
// The column values must be of an ordered type.
|
|
//
|
|
// Minute
|
|
//
|
|
// The built-in function minute returns the minute offset within the hour
|
|
// specified by t, in the range [0, 59].
|
|
//
|
|
// func minute(t time) int
|
|
//
|
|
// If the argument to minute is NULL the result is NULL.
|
|
//
|
|
// Minutes
|
|
//
|
|
// The built-in function minutes returns the duration as a floating point
|
|
// number of minutes.
|
|
//
|
|
// func minutes(d duration) float
|
|
//
|
|
// If the argument to minutes is NULL the result is NULL.
|
|
//
|
|
// Month
|
|
//
|
|
// The built-in function month returns the month of the year specified by t
|
|
// (January = 1, ...).
|
|
//
|
|
// func month(t time) int
|
|
//
|
|
// If the argument to month is NULL the result is NULL.
|
|
//
|
|
// Nanosecond
|
|
//
|
|
// The built-in function nanosecond returns the nanosecond offset within the
|
|
// second specified by t, in the range [0, 999999999].
|
|
//
|
|
// func nanosecond(t time) int
|
|
//
|
|
// If the argument to nanosecond is NULL the result is NULL.
|
|
//
|
|
// Nanoseconds
|
|
//
|
|
// The built-in function nanoseconds returns the duration as an integer
|
|
// nanosecond count.
|
|
//
|
|
// func nanoseconds(d duration) float
|
|
//
|
|
// If the argument to nanoseconds is NULL the result is NULL.
|
|
//
|
|
// Now
|
|
//
|
|
// The built-in function now returns the current local time.
|
|
//
|
|
// func now() time
|
|
//
|
|
// Parse time
|
|
//
|
|
// The built-in function parseTime parses a formatted string and returns the
|
|
// time value it represents. The layout defines the format by showing how the
|
|
// reference time,
|
|
//
|
|
// Mon Jan 2 15:04:05 -0700 MST 2006
|
|
//
|
|
// would be interpreted if it were the value; it serves as an example of the
|
|
// input format. The same interpretation will then be made to the input string.
|
|
//
|
|
// Elements omitted from the value are assumed to be zero or, when zero is
|
|
// impossible, one, so parsing "3:04pm" returns the time corresponding to Jan
|
|
// 1, year 0, 15:04:00 UTC (note that because the year is 0, this time is
|
|
// before the zero Time). Years must be in the range 0000..9999. The day of the
|
|
// week is checked for syntax but it is otherwise ignored.
|
|
//
|
|
// In the absence of a time zone indicator, parseTime returns a time in UTC.
|
|
//
|
|
// When parsing a time with a zone offset like -0700, if the offset corresponds
|
|
// to a time zone used by the current location, then parseTime uses that
|
|
// location and zone in the returned time. Otherwise it records the time as
|
|
// being in a fabricated location with time fixed at the given zone offset.
|
|
//
|
|
// When parsing a time with a zone abbreviation like MST, if the zone
|
|
// abbreviation has a defined offset in the current location, then that offset
|
|
// is used. The zone abbreviation "UTC" is recognized as UTC regardless of
|
|
// location. If the zone abbreviation is unknown, Parse records the time as
|
|
// being in a fabricated location with the given zone abbreviation and a zero
|
|
// offset. This choice means that such a time can be parses and reformatted
|
|
// with the same layout losslessly, but the exact instant used in the
|
|
// representation will differ by the actual zone offset. To avoid such
|
|
// problems, prefer time layouts that use a numeric zone offset.
|
|
//
|
|
// func parseTime(layout, value string) time
|
|
//
|
|
// If any argument to parseTime is NULL the result is NULL.
|
|
//
|
|
// Second
|
|
//
|
|
// The built-in function second returns the second offset within the minute
|
|
// specified by t, in the range [0, 59].
|
|
//
|
|
// func second(t time) int
|
|
//
|
|
// If the argument to second is NULL the result is NULL.
|
|
//
|
|
// Seconds
|
|
//
|
|
// The built-in function seconds returns the duration as a floating point
|
|
// number of seconds.
|
|
//
|
|
// func seconds(d duration) float
|
|
//
|
|
// If the argument to seconds is NULL the result is NULL.
|
|
//
|
|
// Since
|
|
//
|
|
// The built-in function since returns the time elapsed since t. It is
|
|
// shorthand for now()-t.
|
|
//
|
|
// func since(t time) duration
|
|
//
|
|
// If the argument to since is NULL the result is NULL.
|
|
//
|
|
// Sum
|
|
//
|
|
// The built-in aggregate function sum returns the sum of values of an
|
|
// expression for all rows of a record set. Sum ignores NULL values, but
|
|
// returns NULL if all values of a column are NULL or if sum is applied to an
|
|
// empty record set.
|
|
//
|
|
// func sum(e expression) typeof(e) // The sum of the values of the expression.
|
|
//
|
|
// The column values must be of a numeric type.
|
|
//
|
|
// SELECT salesperson, sum(sales) FROM salesforce GROUP BY salesperson;
|
|
//
|
|
// Time in a specific zone
|
|
//
|
|
// The built-in function timeIn returns t with the location information set to
|
|
// loc. For discussion of the loc argument please see date().
|
|
//
|
|
// func timeIn(t time, loc string) time
|
|
//
|
|
// If any argument to timeIn is NULL the result is NULL.
|
|
//
|
|
// Weekday
|
|
//
|
|
// The built-in function weekday returns the day of the week specified by t.
|
|
// Sunday == 0, Monday == 1, ...
|
|
//
|
|
// func weekday(t time) int
|
|
//
|
|
// If the argument to weekday is NULL the result is NULL.
|
|
//
|
|
// Year
|
|
//
|
|
// The built-in function year returns the year in which t occurs.
|
|
//
|
|
// func year(t time) int
|
|
//
|
|
// If the argument to year is NULL the result is NULL.
|
|
//
|
|
// Year day
|
|
//
|
|
// The built-in function yearDay returns the day of the year specified by t, in
|
|
// the range [1,365] for non-leap years, and [1,366] in leap years.
|
|
//
|
|
// func yearDay(t time) int
|
|
//
|
|
// If the argument to yearDay is NULL the result is NULL.
|
|
//
|
|
// Manipulating complex numbers
|
|
//
|
|
// Three functions assemble and disassemble complex numbers. The built-in
|
|
// function complex constructs a complex value from a floating-point real and
|
|
// imaginary part, while real and imag extract the real and imaginary parts of
|
|
// a complex value.
|
|
//
|
|
// complex(realPart, imaginaryPart floatT) complexT
|
|
// real(complexT) floatT
|
|
// imag(complexT) floatT
|
|
//
|
|
// The type of the arguments and return value correspond. For complex, the two
|
|
// arguments must be of the same floating-point type and the return type is the
|
|
// complex type with the corresponding floating-point constituents: complex64
|
|
// for float32, complex128 for float64. The real and imag functions together
|
|
// form the inverse, so for a complex value z, z == complex(real(z), imag(z)).
|
|
//
|
|
// If the operands of these functions are all constants, the return value is a
|
|
// constant.
|
|
//
|
|
// complex(2, -2) // complex128
|
|
// complex(1.0, -1.4) // complex128
|
|
// float32(math.Cos(math.Pi/2)) // float32
|
|
// complex(5, float32(-x)) // complex64
|
|
// imag(b) // float64
|
|
// real(complex(5, float32(-x))) // float32
|
|
//
|
|
// If any argument to any of complex, real, imag functions is NULL the result
|
|
// is NULL.
|
|
//
|
|
// Size guarantees
|
|
//
|
|
// For the numeric types, the following sizes are guaranteed
|
|
//
|
|
// type size in bytes
|
|
//
|
|
// byte, uint8, int8 1
|
|
// uint16, int16 2
|
|
// uint32, int32, float32 4
|
|
// uint, uint64, int, int64, float64, complex64 8
|
|
// complex128 16
|
|
//
|
|
// License
|
|
//
|
|
// Portions of this specification page are modifications based on work[2]
|
|
// created and shared by Google[3] and used according to terms described in the
|
|
// Creative Commons 3.0 Attribution License[4].
|
|
//
|
|
// This specification is licensed under the Creative Commons Attribution 3.0
|
|
// License, and code is licensed under a BSD license[5].
|
|
//
|
|
// References
|
|
//
|
|
// Links from the above documentation
|
|
//
|
|
// [1]: http://golang.org/ref/spec#Notation
|
|
// [2]: http://golang.org/ref/spec
|
|
// [3]: http://code.google.com/policies.html
|
|
// [4]: http://creativecommons.org/licenses/by/3.0/
|
|
// [5]: http://golang.org/LICENSE
|
|
// [6]: http://golang.org/pkg/regexp/#Regexp.MatchString
|
|
// [7]: http://developer.mimer.com/validator/sql-reserved-words.tml
|
|
// [8]: http://godoc.org/modernc.org/zappy
|
|
// [9]: http://www.w3schools.com/sql/sql_default.asp
|
|
// [10]: http://en.wikipedia.org/wiki/Join_(SQL)#Outer_join
|
|
//
|
|
// Implementation details
|
|
//
|
|
// This section is not part of the specification.
|
|
//
|
|
// Indices
|
|
//
|
|
// WARNING: The implementation of indices is new and it surely needs more time
|
|
// to become mature.
|
|
//
|
|
// Indices are used currently used only by the WHERE clause. The following
|
|
// expression patterns of 'WHERE expression' are recognized and trigger index
|
|
// use.
|
|
//
|
|
// - WHERE c // For bool typed indexed column c
|
|
// - WHERE !c // For bool typed indexed column c
|
|
// - WHERE c relOp constExpr // For indexed column c
|
|
// - WHERE c relOp parameter // For indexed column c
|
|
// - WHERE parameter relOp c // For indexed column c
|
|
// - WHERE constExpr relOp c // For indexed column c
|
|
//
|
|
// The relOp is one of the relation operators <, <=, ==, >=, >. For the
|
|
// equality operator both operands must be of comparable types. For all other
|
|
// operators both operands must be of ordered types. The constant expression is
|
|
// a compile time constant expression. Some constant folding is still a TODO.
|
|
// Parameter is a QL parameter ($1 etc.).
|
|
//
|
|
// Query rewriting
|
|
//
|
|
// Consider tables t and u, both with an indexed field f. The WHERE expression
|
|
// doesn't comply with the above simple detected cases.
|
|
//
|
|
// SELECT * FROM t, u WHERE t.f < x && u.f < y;
|
|
//
|
|
// However, such query is now automatically rewritten to
|
|
//
|
|
// SELECT * FROM
|
|
// (SELECT * FROM t WHERE f < x),
|
|
// (SELECT * FROM u WHERE f < y);
|
|
//
|
|
// which will use both of the indices. The impact of using the indices can be
|
|
// substantial (cf. BenchmarkCrossJoin*) if the resulting rows have low
|
|
// "selectivity", ie. only few rows from both tables are selected by the
|
|
// respective WHERE filtering.
|
|
//
|
|
// Note: Existing QL DBs can be used and indices can be added to them. However,
|
|
// once any indices are present in the DB, the old QL versions cannot work with
|
|
// such DB anymore.
|
|
//
|
|
// Benchmarks
|
|
//
|
|
// Running a benchmark with -v (-test.v) outputs information about the scale
|
|
// used to report records/s and a brief description of the benchmark. For
|
|
// example
|
|
//
|
|
// $ go test -run NONE -bench 'SelectMem.*1e[23]' -v
|
|
// PASS
|
|
// BenchmarkSelectMem1kBx1e2 50000 67680 ns/op 1477537.05 MB/s
|
|
// --- BENCH: BenchmarkSelectMem1kBx1e2
|
|
// all_test.go:310:
|
|
// =============================================================
|
|
// NOTE: All benchmarks report records/s as 1000000 bytes/s.
|
|
// =============================================================
|
|
// all_test.go:321: Having a table of 100 records, each of size 1kB, measure the performance of
|
|
// SELECT * FROM t;
|
|
//
|
|
// BenchmarkSelectMem1kBx1e3 5000 634819 ns/op 1575251.01 MB/s
|
|
// --- BENCH: BenchmarkSelectMem1kBx1e3
|
|
// all_test.go:321: Having a table of 1000 records, each of size 1kB, measure the performance of
|
|
// SELECT * FROM t;
|
|
//
|
|
// ok modernc.org/ql 7.496s
|
|
// $
|
|
//
|
|
// Running the full suite of benchmarks takes a lot of time. Use the -timeout
|
|
// flag to avoid them being killed after the default time limit (10 minutes).
|
|
package ql // import "modernc.org/ql"
|