From 3ed11fd82121261983703361b503eb6dfad9a5ef Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20Wa=C5=9B?= Date: Thu, 15 Jun 2023 13:25:20 +0200 Subject: [PATCH] Expand docs for lexical structure - Add details about decimal, hexadecimal, octal, and binary literals - Add docs for comments - Add info about identifiers - Add info about underscore usage in literals Co-authored by: Manfred Moser --- docs/src/main/sphinx/language/reserved.md | 36 ++++++++++++- docs/src/main/sphinx/language/types.md | 63 ++++++++++++++++++----- docs/src/main/sphinx/sql.md | 1 + docs/src/main/sphinx/sql/comment.md | 4 ++ docs/src/main/sphinx/sql/comments.md | 26 ++++++++++ 5 files changed, 117 insertions(+), 13 deletions(-) create mode 100644 docs/src/main/sphinx/sql/comments.md diff --git a/docs/src/main/sphinx/language/reserved.md b/docs/src/main/sphinx/language/reserved.md index 1018a9a91dd0..a33d122c8af9 100644 --- a/docs/src/main/sphinx/language/reserved.md +++ b/docs/src/main/sphinx/language/reserved.md @@ -1,4 +1,7 @@ -# Reserved keywords +# Keywords and identifiers + +(language-keywords)= +## Reserved keywords The following table lists all of the keywords that are reserved in Trino, along with their status in the SQL standard. These reserved keywords must @@ -89,3 +92,34 @@ be quoted (using double quotes) in order to be used as an identifier. | `WHERE` | reserved | reserved | | `WITH` | reserved | reserved | +(language-identifiers)= +## Identifiers + +Tokens that identify names of catalogs, schemas, tables, columns, functions, or +other objects, are identifiers. + +Identifiers must start with a letter, and subsequently include alphanumeric +characters and underscores. Identifiers with other characters must be delimited +with double quotes (`"`). When delimited with double quotes, identifiers can use +any character. Escape a `"` with another preceding double quote in a delimited +identifier. + +Identifiers are not treated as case sensitive. + +Following are some valid examples: + +```sql +tablename +SchemaName +example_catalog.a_schema."table$partitions" +"identifierWith""double""quotes" +``` + +The following identifiers are invalid in Trino and must be quoted when used: + +```text +table-name +123SchemaName +colum$name@field +``` + diff --git a/docs/src/main/sphinx/language/types.md b/docs/src/main/sphinx/language/types.md index 27557529a856..97bf46da3b19 100644 --- a/docs/src/main/sphinx/language/types.md +++ b/docs/src/main/sphinx/language/types.md @@ -41,31 +41,55 @@ This type captures boolean values `true` and `false`. ## Integer +Integer numbers can be expressed as numeric literals in the following formats: + +* Decimal integer. Examples are `-7`, `0`, or `3`. +* Hexadecimal integer composed of `0X` or `0x` and the value. Examples are + `0x0A` for decimal `10` or `0x11` for decimal `17`. +* Octal integer composed of `0O` or `0o` and the value. Examples are `0o40` for + decimal `32` or `0o11` for decimal `9`. +* Binary integer composed of `0B` or `0b` and the value. Examples are `0b1001` + for decimal `9` or `0b101010` for decimal `42``. + +Underscore characters are ignored within literal values, and can be used to +increase readability. For example, decimal integer `123_456.789_123` is +equivalent to `123456.789123`. Preceding and trailing underscores are not +permitted. + +Integers are supported by the following data types. + ### `TINYINT` A 8-bit signed two's complement integer with a minimum value of -`-2^7` and a maximum value of `2^7 - 1`. +`-2^7` or `-0x80` and a maximum value of `2^7 - 1` or `0x7F`. ### `SMALLINT` A 16-bit signed two's complement integer with a minimum value of -`-2^15` and a maximum value of `2^15 - 1`. +`-2^15` or `-0x8000` and a maximum value of `2^15 - 1` or `0x7FFF`. -### `INTEGER` +### `INTEGER` or `INT` -A 32-bit signed two's complement integer with a minimum value of -`-2^31` and a maximum value of `2^31 - 1`. The name `INT` is -also available for this type. +A 32-bit signed two's complement integer with a minimum value of `-2^31` or +`-0x80000000` and a maximum value of `2^31 - 1` or `0x7FFFFFFF`. The names +`INTEGER` and `INT` can both be used for this type. ### `BIGINT` -A 64-bit signed two's complement integer with a minimum value of -`-2^63` and a maximum value of `2^63 - 1`. +A 64-bit signed two's complement integer with a minimum value of `-2^63` or +`-0x8000000000000000` and a maximum value of `2^63 - 1` or `0x7FFFFFFFFFFFFFFF`. (floating-point-data-types)= ## Floating-point +Floating-point, fixed-precision numbers can be expressed as numeric literal +using scientific notation such as `1.03e1` and are cast as `DOUBLE` data type. +Underscore characters are ignored within literal values, and can be used to +increase readability. For example, value `123_456.789e4` is equivalent to +`123456.789e4`. Preceding underscores, trailing underscores, and underscores +beside the comma (`.`) are not permitted. + ### `REAL` A real is a 32-bit inexact, variable-precision implementing the @@ -84,9 +108,20 @@ Example literals: `DOUBLE '10.3'`, `DOUBLE '1.03e1'`, `10.3e0`, `1.03e1` ## Fixed-precision +Fixed-precision numbers can be expressed as numeric literals such as `1.1`, and +are supported by the `DECIMAL` data type. + +Underscore characters are ignored within literal values, and can be used to +increase readability. For example, decimal `123_456.789_123` is equivalent to +`123456.789123`. Preceding underscores, trailing underscores, and underscores +beside the comma (`.`) are not permitted. + +Leading zeros in literal values are permitted and ignored. For example, +`000123.456` is equivalent to `123.456`. + ### `DECIMAL` -A fixed precision decimal number. Precision up to 38 digits is supported +A fixed-precision decimal number. Precision up to 38 digits is supported but performance is best up to 18 digits. The decimal type takes two literal parameters: @@ -134,9 +169,13 @@ Example type definitions: `char`, `char(20)` Variable length binary data. -SQL statements support usage of binary data with the prefix `X`. The -binary data has to use hexadecimal format. For example, the binary form of -`eh?` is `X'65683F'`. +SQL statements support usage of binary literal data with the prefix `X` or `x`. +The binary data has to use hexadecimal format. For example, the binary form of +`eh?` is `X'65683F'` as you can confirm with the following statement: + +```sql +SELECT from_utf8(x'65683F'); +``` :::{note} Binary strings with length are not yet supported: `varbinary(n)` diff --git a/docs/src/main/sphinx/sql.md b/docs/src/main/sphinx/sql.md index 589144205f37..7109ed2f17b2 100644 --- a/docs/src/main/sphinx/sql.md +++ b/docs/src/main/sphinx/sql.md @@ -16,6 +16,7 @@ sql/alter-view sql/analyze sql/call sql/comment +sql/comments sql/commit sql/create-materialized-view sql/create-role diff --git a/docs/src/main/sphinx/sql/comment.md b/docs/src/main/sphinx/sql/comment.md index 99b675f2fb19..317fb0cb8859 100644 --- a/docs/src/main/sphinx/sql/comment.md +++ b/docs/src/main/sphinx/sql/comment.md @@ -29,3 +29,7 @@ Change the comment for the `users.name` column to be `full name`: ``` COMMENT ON COLUMN users.name IS 'full name'; ``` + +## See also + +[](./comments) diff --git a/docs/src/main/sphinx/sql/comments.md b/docs/src/main/sphinx/sql/comments.md new file mode 100644 index 000000000000..6cdb93f70129 --- /dev/null +++ b/docs/src/main/sphinx/sql/comments.md @@ -0,0 +1,26 @@ +# Comments + +## Synopsis + +Comments are part of a SQL statement or script that are ignored for processing. +Comments begin with double dashes and extend to the end of the line. Block +comments begin with `/*` and extend to the next occurrence of `*/`, possibly +spanning over multiple lines. + +## Examples + +The following example displays a comment line, a comment after a valid +statement, and a block comment: + +```sql +-- This is a comment. +SELECT * FROM table; -- This comment is ignored. + +/* This is a block comment + that spans multiple lines + until it is closed. */ +``` + +## See also + +[](./comment)