From 71353a02e979f71c6bb5dd3733a5d293a48e1731 Mon Sep 17 00:00:00 2001 From: Huaxin Gao Date: Thu, 16 Apr 2020 20:56:05 -0700 Subject: [PATCH 01/12] [SPARK-31465][SQL][DOCS] Document Literal in SQL Reference --- docs/_data/menu-sql.yaml | 2 + docs/sql-ref-literals.md | 155 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 157 insertions(+) create mode 100644 docs/sql-ref-literals.md diff --git a/docs/_data/menu-sql.yaml b/docs/_data/menu-sql.yaml index 7827a0fe7d90..cf9d34684ed3 100644 --- a/docs/_data/menu-sql.yaml +++ b/docs/_data/menu-sql.yaml @@ -78,6 +78,8 @@ subitems: - text: Data Types url: sql-ref-datatypes.html + - text: Literals + url: sql-ref-literals.html - text: Null Semantics url: sql-ref-null-semantics.html - text: NaN Semantics diff --git a/docs/sql-ref-literals.md b/docs/sql-ref-literals.md new file mode 100644 index 000000000000..072658bd5496 --- /dev/null +++ b/docs/sql-ref-literals.md @@ -0,0 +1,155 @@ +--- +layout: global +title: Literals +displayTitle: Literals +license: | + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +--- + +A literal (aka constant) represents a fixed data value. Spark SQL supports the following literals: + + * String Literals + * Boolean Literals + * Numeric Literals + * Datetime Literals + * Interval Literals + +### String Literals + +A string literal is used to specify a character string value. +
+
Format:
+
+ 'c [ ... ]'
+ c: one character of user's character set. +
+
+
+
Examples:
+
+ 'Hello, World!', 'Spark SQL', 'dbname.schema' +
+
+ +### Boolean Literals + +A boolean literal is used to specify a boolean value. +
+
Format:
+
+ TRUE | FALSE +
+
+ +### Numeric Literals + +A numeric literal is used to specify a fixed or floating-point number. + +#### Integer Literals + +
+
Format:
+
+ [ + | - ] digit [ ... ] [ l | L ]
+ digit: one of 0, 1, 2, 3, 4, 5, 6, 7, 8 or 9
+ l or L: indicates LongType. +
+
+
+
Examples:
+
+ 6, +188, -54, 1000L +
+
+ +#### Floating Point and Decimal Literals + +
+
Format:
+
+ + [ + | - ] { digit [ ... ] [ . ] [ digit [ ... ] ] | . digit [ ... ] }
+ [ { e | E } [ + | - ] digit [ ... ] ] [ d | D ] +
+ digit: one of 0, 1, 2, 3, 4, 5, 6, 7, 8 or 9.
+ e or E: indicates that the number is in scientific notation format.
+ d or D: indicates DoubleType +
+
+
+
Examples:
+
+ 5E2, 3.e6, 2.3E-2, +3.e+3, -4D, 0.25 +
+
+ +### Datetime Literals + +A Datetime literal is used to specify a datetime data type value. + +#### Date Literals + +
+
Format:
+
+ + DATE 'YYYY-MM-DD' + +
+
+
+
Examples:
+
+ DATE '2011-11-11' +
+
+ +#### Timestamp Literals + +
+
Format:
+
+ + TIMESTAMP yyyy-MM-dd HH:mm[:ss.SSSSSSzzz] + +
+
+
+
Examples:
+
+ TIMESTAMP '1997-01-31 09:26:56.123'
+ TIMESTAMP '1997-01-31 09:26:56.66666666CST' +
+
+ +### Interval Literals + +An inerval literal is used to specify a fixed period of time. +
+
Format:
+
+ + INTERVAL value { YEAR | MONTH | DAY | HOUR | MINUTE | SECOND | MILLISECOND | MICROSECOND } + +
+
+
+
Examples:
+
+ INTERVAL 3 YEAR
+ INTERVAL 3 YEAR 3 HOUR +
+
\ No newline at end of file From 7628fb8f59ce01041685e0501ce980169ea85e6a Mon Sep 17 00:00:00 2001 From: Huaxin Gao Date: Fri, 17 Apr 2020 16:14:45 -0700 Subject: [PATCH 02/12] address comments --- docs/sql-ref-literals.md | 441 ++++++++++++++++++++++++++++----------- 1 file changed, 317 insertions(+), 124 deletions(-) diff --git a/docs/sql-ref-literals.md b/docs/sql-ref-literals.md index 072658bd5496..11c1feb4333b 100644 --- a/docs/sql-ref-literals.md +++ b/docs/sql-ref-literals.md @@ -19,137 +19,330 @@ license: | limitations under the License. --- -A literal (aka constant) represents a fixed data value. Spark SQL supports the following literals: +A literal (also known as a constant) represents a fixed data value. Spark SQL supports the following literals: - * String Literals - * Boolean Literals - * Numeric Literals - * Datetime Literals - * Interval Literals + * [String Literal](#string-literal) + * [Null Literal](#null-literal) + * [Boolean Literal](#boolean-literal) + * [Numeric Literal](#numeric-literal) + * [Datetime Literal](#datetime-literal) + * [Interval Literal](#interval-literal) -### String Literals +### String Literal A string literal is used to specify a character string value. -
-
Format:
-
- 'c [ ... ]'
- c: one character of user's character set. -
-
-
-
Examples:
-
- 'Hello, World!', 'Spark SQL', 'dbname.schema' -
-
- -### Boolean Literals - -A boolean literal is used to specify a boolean value. -
-
Format:
-
- TRUE | FALSE -
-
- -### Numeric Literals + +#### Syntax + +{% highlight sql %} +'c [ ... ]' | "c [ ... ]" +{% endhighlight %} +c: one character of the user's character set. + +#### Examples + +{% highlight sql %} +SELECT 'Hello, World!' AS col; + +-------------+ + |col | + +-------------+ + |Hello, World!| + +-------------+ + +SELECT "SPARK SQL" AS col; + +---------+ + |col | + +---------+ + |Spark SQL| + +---------+ +{% endhighlight %} + +### Null Literal + +A null literal is used to specify a null value. + +#### Syntax + +{% highlight sql %} +NULL +{% endhighlight %} + +#### Examples + +{% highlight sql %} +SELECT NULL AS col; + +----+ + |col | + +----+ + |NULL| + +----+ +{% endhighlight %} + +### Boolean Literal + +#### Syntax + +{% highlight sql %} +TRUE | FALSE +{% endhighlight %} + +#### Examples + +{% highlight sql %} +SELECT TRUE AS col; + +----+ + |col | + +----+ + |true| + +----+ +{% endhighlight %} + +### Numeric Literal A numeric literal is used to specify a fixed or floating-point number. -#### Integer Literals - -
-
Format:
-
- [ + | - ] digit [ ... ] [ l | L ]
- digit: one of 0, 1, 2, 3, 4, 5, 6, 7, 8 or 9
- l or L: indicates LongType. -
-
-
-
Examples:
-
- 6, +188, -54, 1000L -
-
- -#### Floating Point and Decimal Literals - -
-
Format:
-
- - [ + | - ] { digit [ ... ] [ . ] [ digit [ ... ] ] | . digit [ ... ] }
- [ { e | E } [ + | - ] digit [ ... ] ] [ d | D ] -
- digit: one of 0, 1, 2, 3, 4, 5, 6, 7, 8 or 9.
- e or E: indicates that the number is in scientific notation format.
- d or D: indicates DoubleType -
-
-
-
Examples:
-
- 5E2, 3.e6, 2.3E-2, +3.e+3, -4D, 0.25 -
-
- -### Datetime Literals +#### Integer Literal + +#### Syntax + +{% highlight sql %} +[ + | - ] digit [ ... ] [ L | S | Y ] +{% endhighlight %} +digit: one of 0, 1, 2, 3, 4, 5, 6, 7, 8 or 9.
+default (no postfix): indicates a 4-byte signed integer number.
+L: case insensitive, indicates BIGINT, which is a 8-byte signed integer number.
+S: case insensitive, indicates SMALLINT, which is a 2-byte signed integer number.
+Y: case insensitive, indicates TINYINT, which is a 1-byte signed integer number.
+#### Examples + +{% highlight sql %} +SELECT -2147483648 AS col; + +-----------+ + |col | + +-----------+ + |-2147483648| + +-----------+ + +SELECT 9223372036854775807l AS col; + +-------------------+ + |col | + +-------------------+ + |9223372036854775807| + +-------------------+ + +SELECT -32Y AS col; + +---+ + |col| + +---+ + |-32| + +---+ + +SELECT 482S AS col; + +---+ + |col| + +---+ + |482| + +---+ +{% endhighlight %} + +#### Decimal Literal + +#### Syntax + +{% highlight sql %} + [ + | - ] { digit [ ... ] . [ digit [ ... ] ] | . digit [ ... ] } +{% endhighlight %} + +#### Examples + +{% highlight sql %} +SELECT 12.578 AS col; + +------+ + |col | + +------+ + |12.578| + +------+ + +SELECT -0.1234567 AS col; + +----------+ + |col | + +----------+ + |-0.1234567| + +----------+ + +SELECT -.1234567 AS col; + +----------+ + |col | + +----------+ + |-0.1234567| + +----------+ +{% endhighlight %} + +#### Floating Point and BigDecimal Literals + +#### Syntax + +{% highlight sql %} + [ + | - ] { digit [ ... ] [ E [ + | - ] digit [ ... ] ] [ D | BD ] + | digit [ ... ] . [ digit [ ... ] ] [ E [ + | - ] digit [ ... ] ] [ D | BD ] + | . digit [ ... ] [ E [ + | - ] digit [ ... ] ] [ D | BD ] } +{% endhighlight %} +digit: one of 0, 1, 2, 3, 4, 5, 6, 7, 8 or 9.
+default (no postfix): indicate a 4-byte single-precision floating point number.
+D: case insensitive, indicates DOUBLE, which is a 8-byte double-precision floating point number.
+BD: case insensitive, indicates BIGDECIMAL, is an arbitrary-precision signed decimal number.
+#### Examples + +{% highlight sql %} +SELECT 5E2 AS col; + +-----+ + |col | + +-----+ + |500.0| + +-----+ + +SELECT 5D AS col; + +---+ + |col| + +---+ + |5.0| + +---+ + +SELECT -5BD AS col; + +---+ + |col| + +---+ + |-5 | + +---+ + +SELECT 12.578e-2d AS col; + +-------+ + |col | + +-------+ + |0.12578| + +-------+ + +SELECT -.1234567E+2BD AS col; + +---------+ + |col | + +---------+ + |-12.34567| + +---------+ + +SELECT +3.e+3 AS col; + +------+ + |col | + +------+ + |3000.0| + +------+ + +SELECT -3.E-3D AS col; + +------+ + |col | + +------+ + |-0.003| + +------+ +{% endhighlight %} + +### Datetime Literal A Datetime literal is used to specify a datetime data type value. -#### Date Literals - -
-
Format:
-
- - DATE 'YYYY-MM-DD' - -
-
-
-
Examples:
-
- DATE '2011-11-11' -
-
- -#### Timestamp Literals - -
-
Format:
-
- - TIMESTAMP yyyy-MM-dd HH:mm[:ss.SSSSSSzzz] - -
-
-
-
Examples:
-
- TIMESTAMP '1997-01-31 09:26:56.123'
- TIMESTAMP '1997-01-31 09:26:56.66666666CST' -
-
- -### Interval Literals - -An inerval literal is used to specify a fixed period of time. -
-
Format:
-
- - INTERVAL value { YEAR | MONTH | DAY | HOUR | MINUTE | SECOND | MILLISECOND | MICROSECOND } - -
-
-
-
Examples:
-
- INTERVAL 3 YEAR
- INTERVAL 3 YEAR 3 HOUR -
-
\ No newline at end of file +#### Date Literal + +#### Syntax + +{% highlight sql %} +DATE 'yyyy-MM-dd' +{% endhighlight %} + +#### Examples + +{% highlight sql %} +SELECT DATE '2011-11-11' AS col; + +----------+ + |col | + +----------+ + |2011-11-11| + +----------+ +{% endhighlight %} + +#### Timestamp Literal + +#### Syntax + +{% highlight sql %} +TIMESTAMP 'yyyy-MM-dd [ HH:mm:ss.SSSSSSzzz ]' +{% endhighlight %} + +#### Examples + +{% highlight sql %} +SELECT TIMESTAMP '1997-01-31 09:26:56.123' AS col; + +-----------------------+ + |col | + +-----------------------+ + |1997-01-31 09:26:56.123| + +-----------------------+ + +SELECT TIMESTAMP '1997-01-31 09:26:56.66666666CST' AS col; + +--------------------------+ + |col | + +--------------------------+ + |1997-01-31 07:26:56.666666| + +--------------------------+ +{% endhighlight %} + +### Interval Literal + +An interval literal is used to specify a fixed period of time. + +#### Syntax +{% highlight sql %} +{ INTERVAL interval_value interval_unit [ interval_value interval_unit ... ] + | INTERVAL interval_value interval_unit TO interval_unit } +{% endhighlight %} + +interval_value: +{% highlight sql %} +{ [ + | - ] number_value | string_value } +{% endhighlight %} +Note: string_value needs to be used for INTERNAL ... TO ... format. + +interval_unit: +{% highlight sql %} +YEAR | MONTH | DAY | HOUR | MINUTE | SECOND | MILLISECOND | MICROSECOND +{% endhighlight %} + +#### Examples + +{% highlight sql %} +SELECT INTERVAL 3 YEAR AS col; + +-------+ + | col| + +-------+ + |3 years| + +-------+ + +SELECT INTERVAL -2 HOUR 3 MINUTE AS col; + +--------------------+ + | col| + +--------------------+ + |-1 hours -57 minutes| + +--------------------+ + +SELECT INTERVAL 1 YEAR 2 MONTH 3 WEEK 4 DAY 5 HOUR 6 MINUTE 7 SECOND 8 + MILLISECOND 9 MICROSECOND AS col; + +-----------------------------------------------------------+ + |col | + +-----------------------------------------------------------+ + |1 years 2 months 25 days 5 hours 6 minutes 7.008009 seconds| + +-----------------------------------------------------------+ + +SELECT INTERVAL '20 15:40:32.99899999' DAY TO SECOND AS col; + +---------------------------------------------+ + |col | + +---------------------------------------------+ + |20 days 15 hours 40 minutes 32.998999 seconds| + +---------------------------------------------+ +{% endhighlight %} From c8c768f2e61f687c4d654abca369dc172bfbb875 Mon Sep 17 00:00:00 2001 From: Huaxin Gao Date: Fri, 17 Apr 2020 16:43:33 -0700 Subject: [PATCH 03/12] fix --- docs/sql-ref-literals.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/sql-ref-literals.md b/docs/sql-ref-literals.md index 11c1feb4333b..da6550eb2bfd 100644 --- a/docs/sql-ref-literals.md +++ b/docs/sql-ref-literals.md @@ -80,6 +80,8 @@ SELECT NULL AS col; ### Boolean Literal +A boolean literal is used to specify a boolean value. + #### Syntax {% highlight sql %} @@ -190,7 +192,7 @@ SELECT -.1234567 AS col; digit: one of 0, 1, 2, 3, 4, 5, 6, 7, 8 or 9.
default (no postfix): indicate a 4-byte single-precision floating point number.
D: case insensitive, indicates DOUBLE, which is a 8-byte double-precision floating point number.
-BD: case insensitive, indicates BIGDECIMAL, is an arbitrary-precision signed decimal number.
+BD: case insensitive, indicates BIGDECIMAL, which is an arbitrary-precision signed decimal number.
#### Examples {% highlight sql %} @@ -246,7 +248,7 @@ SELECT -3.E-3D AS col; ### Datetime Literal -A Datetime literal is used to specify a datetime data type value. +A Datetime literal is used to specify a datetime value. #### Date Literal From 2059414001fd4e95febe09aea18bcce809d50d22 Mon Sep 17 00:00:00 2001 From: Huaxin Gao Date: Fri, 17 Apr 2020 17:16:47 -0700 Subject: [PATCH 04/12] fix DATE and TIMESTAMP syntax --- docs/sql-ref-literals.md | 32 ++++++++++++++++++++++++++++++-- 1 file changed, 30 insertions(+), 2 deletions(-) diff --git a/docs/sql-ref-literals.md b/docs/sql-ref-literals.md index da6550eb2bfd..017bc1ae2af4 100644 --- a/docs/sql-ref-literals.md +++ b/docs/sql-ref-literals.md @@ -255,12 +255,26 @@ A Datetime literal is used to specify a datetime value. #### Syntax {% highlight sql %} -DATE 'yyyy-MM-dd' +DATE 'yyyy [ -MM-dd ]' {% endhighlight %} #### Examples {% highlight sql %} +SELECT DATE '1997' AS col; + +----------+ + |col | + +----------+ + |1997-01-01| + +----------+ + +SELECT TIMESTAMP '1997-01' AS col; + +----------+ + |col | + +----------+ + |1997-01-01| + +----------+ + SELECT DATE '2011-11-11' AS col; +----------+ |col | @@ -274,7 +288,7 @@ SELECT DATE '2011-11-11' AS col; #### Syntax {% highlight sql %} -TIMESTAMP 'yyyy-MM-dd [ HH:mm:ss.SSSSSSzzz ]' +TIMESTAMP { 'yyyy [ -MM-dd HH:mm:ss.SSSSSSzzz ]' | '[ yyyy-MM-dd ] HH:mm [ :ss.SSSSSSzzz ]' } {% endhighlight %} #### Examples @@ -293,6 +307,20 @@ SELECT TIMESTAMP '1997-01-31 09:26:56.66666666CST' AS col; +--------------------------+ |1997-01-31 07:26:56.666666| +--------------------------+ + +SELECT TIMESTAMP '1997-01' AS col; + +-------------------+ + |col | + +-------------------+ + |1997-01-01 00:00:00| + +-------------------+ + +SELECT TIMESTAMP '09:26' AS col; + +-------------------+ + |col | + +-------------------+ + |2020-04-17 09:26:00| + +-------------------+ {% endhighlight %} ### Interval Literal From 39862aed22e5cf5f8d207526683c94efc50076ee Mon Sep 17 00:00:00 2001 From: Huaxin Gao Date: Fri, 17 Apr 2020 18:31:51 -0700 Subject: [PATCH 05/12] address comments --- docs/sql-ref-literals.md | 57 ++++++++++++++++++++++------------------ 1 file changed, 32 insertions(+), 25 deletions(-) diff --git a/docs/sql-ref-literals.md b/docs/sql-ref-literals.md index 017bc1ae2af4..c5ff487f5518 100644 --- a/docs/sql-ref-literals.md +++ b/docs/sql-ref-literals.md @@ -35,26 +35,33 @@ A string literal is used to specify a character string value. #### Syntax {% highlight sql %} -'c [ ... ]' | "c [ ... ]" +'...' | "..." {% endhighlight %} -c: one character of the user's character set. +...: indicates any string. #### Examples {% highlight sql %} SELECT 'Hello, World!' AS col; +-------------+ - |col | + | col| +-------------+ |Hello, World!| +-------------+ SELECT "SPARK SQL" AS col; +---------+ - |col | + | col| +---------+ |Spark SQL| +---------+ + +SELECT SELECT 'it\'s $10.' AS col; + +---------+ + | col| + +---------+ + |It's $10.| + +----------+ {% endhighlight %} ### Null Literal @@ -72,7 +79,7 @@ NULL {% highlight sql %} SELECT NULL AS col; +----+ - |col | + | col| +----+ |NULL| +----+ @@ -93,7 +100,7 @@ TRUE | FALSE {% highlight sql %} SELECT TRUE AS col; +----+ - |col | + | col| +----+ |true| +----+ @@ -120,14 +127,14 @@ Y: case insensitive, indicates TINYINT, which is a 1-byte signed in {% highlight sql %} SELECT -2147483648 AS col; +-----------+ - |col | + | col| +-----------+ |-2147483648| +-----------+ SELECT 9223372036854775807l AS col; +-------------------+ - |col | + | col| +-------------------+ |9223372036854775807| +-------------------+ @@ -160,21 +167,21 @@ SELECT 482S AS col; {% highlight sql %} SELECT 12.578 AS col; +------+ - |col | + | col| +------+ |12.578| +------+ SELECT -0.1234567 AS col; +----------+ - |col | + | col| +----------+ |-0.1234567| +----------+ SELECT -.1234567 AS col; +----------+ - |col | + | col| +----------+ |-0.1234567| +----------+ @@ -198,7 +205,7 @@ BD: case insensitive, indicates BIGDECIMAL, which is an arbitrary-p {% highlight sql %} SELECT 5E2 AS col; +-----+ - |col | + | col| +-----+ |500.0| +-----+ @@ -219,28 +226,28 @@ SELECT -5BD AS col; SELECT 12.578e-2d AS col; +-------+ - |col | + | col| +-------+ |0.12578| +-------+ SELECT -.1234567E+2BD AS col; +---------+ - |col | + | col| +---------+ |-12.34567| +---------+ SELECT +3.e+3 AS col; +------+ - |col | + | col| +------+ |3000.0| +------+ SELECT -3.E-3D AS col; +------+ - |col | + | col| +------+ |-0.003| +------+ @@ -263,21 +270,21 @@ DATE 'yyyy [ -MM-dd ]' {% highlight sql %} SELECT DATE '1997' AS col; +----------+ - |col | + | col| +----------+ |1997-01-01| +----------+ SELECT TIMESTAMP '1997-01' AS col; +----------+ - |col | + | col| +----------+ |1997-01-01| +----------+ SELECT DATE '2011-11-11' AS col; +----------+ - |col | + | col| +----------+ |2011-11-11| +----------+ @@ -296,28 +303,28 @@ TIMESTAMP { 'yyyy [ -MM-dd HH:mm:ss.SSSSSSzzz ]' | '[ yyyy-MM-dd ] HH:mm [ :ss.S {% highlight sql %} SELECT TIMESTAMP '1997-01-31 09:26:56.123' AS col; +-----------------------+ - |col | + | col| +-----------------------+ |1997-01-31 09:26:56.123| +-----------------------+ SELECT TIMESTAMP '1997-01-31 09:26:56.66666666CST' AS col; +--------------------------+ - |col | + | col | +--------------------------+ |1997-01-31 07:26:56.666666| +--------------------------+ SELECT TIMESTAMP '1997-01' AS col; +-------------------+ - |col | + | col| +-------------------+ |1997-01-01 00:00:00| +-------------------+ SELECT TIMESTAMP '09:26' AS col; +-------------------+ - |col | + | col| +-------------------+ |2020-04-17 09:26:00| +-------------------+ @@ -364,14 +371,14 @@ SELECT INTERVAL -2 HOUR 3 MINUTE AS col; SELECT INTERVAL 1 YEAR 2 MONTH 3 WEEK 4 DAY 5 HOUR 6 MINUTE 7 SECOND 8 MILLISECOND 9 MICROSECOND AS col; +-----------------------------------------------------------+ - |col | + | col| +-----------------------------------------------------------+ |1 years 2 months 25 days 5 hours 6 minutes 7.008009 seconds| +-----------------------------------------------------------+ SELECT INTERVAL '20 15:40:32.99899999' DAY TO SECOND AS col; +---------------------------------------------+ - |col | + | col| +---------------------------------------------+ |20 days 15 hours 40 minutes 32.998999 seconds| +---------------------------------------------+ From 0121faf90018a7b15bcc303298576d442412ef1a Mon Sep 17 00:00:00 2001 From: Huaxin Gao Date: Sat, 18 Apr 2020 21:03:51 -0700 Subject: [PATCH 06/12] address comments --- docs/sql-ref-literals.md | 218 ++++++++++++++++++++++++++++++--------- 1 file changed, 169 insertions(+), 49 deletions(-) diff --git a/docs/sql-ref-literals.md b/docs/sql-ref-literals.md index c5ff487f5518..30e5b0707c45 100644 --- a/docs/sql-ref-literals.md +++ b/docs/sql-ref-literals.md @@ -32,12 +32,20 @@ A literal (also known as a constant) represents a fixed data value. Spark SQL su A string literal is used to specify a character string value. -#### Syntax +#### Syntax {% highlight sql %} -'...' | "..." +'c [ ... ]' | "c [ ... ]" {% endhighlight %} -...: indicates any string. + +#### Parameters + +
+
c
+
+ One character from the character set. Use \ to escape special characters. +
+
#### Examples @@ -61,20 +69,20 @@ SELECT SELECT 'it\'s $10.' AS col; | col| +---------+ |It's $10.| - +----------+ + +---------+ {% endhighlight %} ### Null Literal A null literal is used to specify a null value. -#### Syntax +#### Syntax {% highlight sql %} NULL {% endhighlight %} -#### Examples +#### Examples {% highlight sql %} SELECT NULL AS col; @@ -89,13 +97,13 @@ SELECT NULL AS col; A boolean literal is used to specify a boolean value. -#### Syntax +#### Syntax {% highlight sql %} TRUE | FALSE {% endhighlight %} -#### Examples +#### Examples {% highlight sql %} SELECT TRUE AS col; @@ -112,17 +120,45 @@ A numeric literal is used to specify a fixed or floating-point number. #### Integer Literal -#### Syntax +#### Syntax {% highlight sql %} [ + | - ] digit [ ... ] [ L | S | Y ] {% endhighlight %} -digit: one of 0, 1, 2, 3, 4, 5, 6, 7, 8 or 9.
-default (no postfix): indicates a 4-byte signed integer number.
-L: case insensitive, indicates BIGINT, which is a 8-byte signed integer number.
-S: case insensitive, indicates SMALLINT, which is a 2-byte signed integer number.
-Y: case insensitive, indicates TINYINT, which is a 1-byte signed integer number.
-#### Examples + +#### Parameters + +
+
digit
+
+ Any numeral from 0 to 9. +
+
+
+
L
+
+ Case insensitive, indicates BIGINT, which is a 8-byte signed integer number. +
+
+
+
S
+
+ Case insensitive, indicates SMALLINT, which is a 2-byte signed integer number. +
+
+
+
Y
+
+ Case insensitive, indicates TINYINT, which is a 1-byte signed integer number. +
+
+
+
default (no postfix)
+
+ Indicates a 4-byte signed integer number. +
+
+#### Examples {% highlight sql %} SELECT -2147483648 AS col; @@ -156,13 +192,22 @@ SELECT 482S AS col; #### Decimal Literal -#### Syntax +#### Syntax {% highlight sql %} [ + | - ] { digit [ ... ] . [ digit [ ... ] ] | . digit [ ... ] } {% endhighlight %} -#### Examples +#### Parameters + +
+
digit
+
+ Any numeral from 0 to 9. +
+
+ +#### Examples {% highlight sql %} SELECT 12.578 AS col; @@ -189,18 +234,42 @@ SELECT -.1234567 AS col; #### Floating Point and BigDecimal Literals -#### Syntax +#### Syntax {% highlight sql %} - [ + | - ] { digit [ ... ] [ E [ + | - ] digit [ ... ] ] [ D | BD ] - | digit [ ... ] . [ digit [ ... ] ] [ E [ + | - ] digit [ ... ] ] [ D | BD ] - | . digit [ ... ] [ E [ + | - ] digit [ ... ] ] [ D | BD ] } + [ + | - ] { digit [ ... ] [ E [ + | - ] digit [ ... ] ] [ D | BD ] | + digit [ ... ] . [ digit [ ... ] ] [ E [ + | - ] digit [ ... ] ] [ D | BD ] | + . digit [ ... ] [ E [ + | - ] digit [ ... ] ] [ D | BD ] } {% endhighlight %} -digit: one of 0, 1, 2, 3, 4, 5, 6, 7, 8 or 9.
-default (no postfix): indicate a 4-byte single-precision floating point number.
-D: case insensitive, indicates DOUBLE, which is a 8-byte double-precision floating point number.
-BD: case insensitive, indicates BIGDECIMAL, which is an arbitrary-precision signed decimal number.
-#### Examples + +#### Parameters + +
+
digit
+
+ Any numeral from 0 to 9. +
+
+
+
D
+
+ Case insensitive, indicates DOUBLE, which is a 8-byte double-precision floating point number. +
+
+
+
BD
+
+ Case insensitive, indicates BIGDECIMAL, which is an arbitrary-precision signed decimal number. +
+
+
+
default (no postfix)
+
+ Indicate a 4-byte single-precision floating point number. +
+
+ +#### Examples {% highlight sql %} SELECT 5E2 AS col; @@ -221,7 +290,7 @@ SELECT -5BD AS col; +---+ |col| +---+ - |-5 | + | -5| +---+ SELECT 12.578e-2d AS col; @@ -259,13 +328,26 @@ A Datetime literal is used to specify a datetime value. #### Date Literal -#### Syntax +#### Syntax {% highlight sql %} -DATE 'yyyy [ -MM-dd ]' +DATE { 'yyyy' | + 'yyyy-[m]m' | + 'yyyy-[m]m-[d]d' | + 'yyyy-[m]m-[d]d ' | + 'yyyy-[m]m-[d]d[T]c[...]' } {% endhighlight %} -#### Examples +#### Parameters + +
+
c
+
+ One character from the character set. +
+
+ +#### Examples {% highlight sql %} SELECT DATE '1997' AS col; @@ -292,13 +374,40 @@ SELECT DATE '2011-11-11' AS col; #### Timestamp Literal -#### Syntax +#### Syntax {% highlight sql %} -TIMESTAMP { 'yyyy [ -MM-dd HH:mm:ss.SSSSSSzzz ]' | '[ yyyy-MM-dd ] HH:mm [ :ss.SSSSSSzzz ]' } +TIMESTAMP { 'yyyy' | + 'yyyy-[m]m' | + 'yyyy-[m]m-[d]d' | + 'yyyy-[m]m-[d]d ' | + 'yyyy-[m]m-[d]d[T][h]h[:]' | + 'yyyy-[m]m-[d]d[T][h]h:[m]m[:]' | + 'yyyy-[m]m-[d]d[T][h]h:[m]m:[s]s[.]' | + 'yyyy-[m]m-[d]d[T][h]h:[m]m:[s]s.[ms][ms][ms][us][us][us][zone_id]' | + '[T][h]h:' | + '[T][h]h:[m]m[:]' | + '[T][h]h:[m]m:[s]s[.]' | + 'T[h]h' | + '[T][h]h:[m]m:[s]s.[ms][ms][ms][us][us][us][zone_id]' } {% endhighlight %} - -#### Examples +`zone_id` should have one of the forms: +
    +
  • Z - Zulu time zone UTC+0
    • +
  • +|-[h]h:[m]m
    • +
  • A short id, see SHORT_IDS
    • +
  • An id with one of the prefixes UTC+, UTC-, GMT+, GMT-, UT+ or UT-, and a suffix in the formats: +
      +
    • +|-h[h]
      • +
    • +|-hh[:]mm
      • +
    • +|-hh:mm:ss
      • +
    • +|-hhmmss
      • +
    +
    • +
  • Region-based zone IDs in the form area/city, such as Europe/Paris
    • +
+ +#### Examples {% highlight sql %} SELECT TIMESTAMP '1997-01-31 09:26:56.123' AS col; @@ -334,24 +443,35 @@ SELECT TIMESTAMP '09:26' AS col; An interval literal is used to specify a fixed period of time. -#### Syntax -{% highlight sql %} -{ INTERVAL interval_value interval_unit [ interval_value interval_unit ... ] - | INTERVAL interval_value interval_unit TO interval_unit } -{% endhighlight %} - -interval_value: -{% highlight sql %} -{ [ + | - ] number_value | string_value } -{% endhighlight %} -Note: string_value needs to be used for INTERNAL ... TO ... format. - -interval_unit: +#### Syntax {% highlight sql %} -YEAR | MONTH | DAY | HOUR | MINUTE | SECOND | MILLISECOND | MICROSECOND +{ INTERVAL interval_value interval_unit [ interval_value interval_unit ... ] | + INTERVAL interval_value interval_unit TO interval_unit } {% endhighlight %} -#### Examples +#### Parameters + +
+
interval_value
+
+ Syntax: + + { [ + | - ] number_value | string_value } +
+ Note: string_value needs to be used for INTERNAL ... TO ... format. +
+
+
+
interval_unit
+
+ Syntax: + + YEAR | MONTH | DAY | HOUR | MINUTE | SECOND | MILLISECOND | MICROSECOND + +
+
+ +#### Examples {% highlight sql %} SELECT INTERVAL 3 YEAR AS col; From 37f5baa6e2eaba6538edbc0a6da5bb305caf011a Mon Sep 17 00:00:00 2001 From: Huaxin Gao Date: Sun, 19 Apr 2020 12:54:56 -0700 Subject: [PATCH 07/12] remove extra space --- docs/sql-ref-literals.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/sql-ref-literals.md b/docs/sql-ref-literals.md index 30e5b0707c45..f5eb7c1e58db 100644 --- a/docs/sql-ref-literals.md +++ b/docs/sql-ref-literals.md @@ -195,7 +195,7 @@ SELECT 482S AS col; #### Syntax {% highlight sql %} - [ + | - ] { digit [ ... ] . [ digit [ ... ] ] | . digit [ ... ] } +[ + | - ] { digit [ ... ] . [ digit [ ... ] ] | . digit [ ... ] } {% endhighlight %} #### Parameters @@ -237,9 +237,9 @@ SELECT -.1234567 AS col; #### Syntax {% highlight sql %} - [ + | - ] { digit [ ... ] [ E [ + | - ] digit [ ... ] ] [ D | BD ] | - digit [ ... ] . [ digit [ ... ] ] [ E [ + | - ] digit [ ... ] ] [ D | BD ] | - . digit [ ... ] [ E [ + | - ] digit [ ... ] ] [ D | BD ] } +[ + | - ] { digit [ ... ] [ E [ + | - ] digit [ ... ] ] [ D | BD ] | + digit [ ... ] . [ digit [ ... ] ] [ E [ + | - ] digit [ ... ] ] [ D | BD ] | + . digit [ ... ] [ E [ + | - ] digit [ ... ] ] [ D | BD ] } {% endhighlight %} #### Parameters From 35cb2862b338ecc5d24deef2e0f7ad216cae1534 Mon Sep 17 00:00:00 2001 From: Huaxin Gao Date: Sun, 19 Apr 2020 21:17:35 -0700 Subject: [PATCH 08/12] address comments --- docs/sql-ref-literals.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/sql-ref-literals.md b/docs/sql-ref-literals.md index f5eb7c1e58db..d9e6a29fc926 100644 --- a/docs/sql-ref-literals.md +++ b/docs/sql-ref-literals.md @@ -43,7 +43,7 @@ A string literal is used to specify a character string value.
c
- One character from the character set. Use \ to escape special characters. + One character from the character set. Use \ to escape special characters (e.g., ' or \).
@@ -158,6 +158,7 @@ A numeric literal is used to specify a fixed or floating-point number. Indicates a 4-byte signed integer number. + #### Examples {% highlight sql %} From 0809b1ebe28f270092efc2a034749dcaff77ee17 Mon Sep 17 00:00:00 2001 From: Huaxin Gao Date: Mon, 20 Apr 2020 15:11:45 -0700 Subject: [PATCH 09/12] address comments --- docs/sql-ref-literals.md | 146 ++++++++++++++++++++++++++------------- 1 file changed, 97 insertions(+), 49 deletions(-) diff --git a/docs/sql-ref-literals.md b/docs/sql-ref-literals.md index d9e6a29fc926..efcd658a2c08 100644 --- a/docs/sql-ref-literals.md +++ b/docs/sql-ref-literals.md @@ -191,14 +191,30 @@ SELECT 482S AS col; +---+ {% endhighlight %} -#### Decimal Literal +#### Non-integer Literals #### Syntax +decimal literals: +{% highlight sql %} +{ decimal_digits { [ BD ] | [ exponent BD ] } | digit [ ... ] [ exponent ] BD } +{% endhighlight %} + +double literals: +{% highlight sql %} +{ decimal_digits { D | exponent [ D ] } | digit [ ... ] { exponent [ D ] | [ exponent ] D } +{% endhighlight %} + +While decimal_digits is defined as {% highlight sql %} [ + | - ] { digit [ ... ] . [ digit [ ... ] ] | . digit [ ... ] } {% endhighlight %} +and exponent is defined as +{% highlight sql %} +E [ + | - ] digit [ ... ] +{% endhighlight %} + #### Parameters
@@ -207,6 +223,18 @@ SELECT 482S AS col; Any numeral from 0 to 9.
+
+
D
+
+ Case insensitive, indicates DOUBLE, which is a 8-byte double-precision floating point number. +
+
+
+
BD
+
+ Case insensitive, indicates BIGDECIMAL, which is an arbitrary-precision signed decimal number. +
+
#### Examples @@ -231,48 +259,21 @@ SELECT -.1234567 AS col; +----------+ |-0.1234567| +----------+ -{% endhighlight %} - -#### Floating Point and BigDecimal Literals -#### Syntax - -{% highlight sql %} -[ + | - ] { digit [ ... ] [ E [ + | - ] digit [ ... ] ] [ D | BD ] | - digit [ ... ] . [ digit [ ... ] ] [ E [ + | - ] digit [ ... ] ] [ D | BD ] | - . digit [ ... ] [ E [ + | - ] digit [ ... ] ] [ D | BD ] } -{% endhighlight %} - -#### Parameters - -
-
digit
-
- Any numeral from 0 to 9. -
-
-
-
D
-
- Case insensitive, indicates DOUBLE, which is a 8-byte double-precision floating point number. -
-
-
-
BD
-
- Case insensitive, indicates BIGDECIMAL, which is an arbitrary-precision signed decimal number. -
-
-
-
default (no postfix)
-
- Indicate a 4-byte single-precision floating point number. -
-
+SELECT 123. AS col; + +---+ + |col| + +---+ + |123| + +---+ -#### Examples +SELECT 123.BD AS col; + +---+ + |col| + +---+ + |123| + +---+ -{% highlight sql %} SELECT 5E2 AS col; +-----+ | col| @@ -347,6 +348,7 @@ DATE { 'yyyy' | One character from the character set. +Note: defaults to 01 if month or day is not specified. #### Examples @@ -396,7 +398,38 @@ TIMESTAMP { 'yyyy' |
  • Z - Zulu time zone UTC+0
  • +|-[h]h:[m]m
    • -
  • A short id, see SHORT_IDS
    • +
  • A short id: +
      +
    • EST - -05:00
      • +
    • HST - -10:00
      • +
    • MST - -07:00
      • +
    • ACT - Australia/Darwin
      • +
    • AET - Australia/Sydney
      • +
    • AGT - America/Argentina/Buenos_Aires
      • +
    • ART - Africa/Cairo
      • +
    • AST - America/Anchorage
      • +
    • BET - America/Sao_Paulo
      • +
    • BST - Asia/Dhaka
      • +
    • CAT - Africa/Harare
      • +
    • CNT - America/St_Johns
      • +
    • CST - America/Chicago
      • +
    • CTT - Asia/Shanghai
      • +
    • EAT - Africa/Addis_Ababa
      • +
    • ECT - Europe/Paris
      • +
    • IET - America/Indiana/Indianapolis
      • +
    • IST - Asia/Kolkata
      • +
    • JST - Asia/Tokyo
      • +
    • MIT - Pacific/Apia
      • +
    • NET - Asia/Yerevan
      • +
    • NST - Pacific/Auckland
      • +
    • PLT - Asia/Karachi
      • +
    • PNT - America/Phoenix
      • +
    • PRT - America/Puerto_Rico
      • +
    • PST - America/Los_Angeles
      • +
    • SST - Pacific/Guadalcanal
      • +
    • VST - Asia/Ho_Chi_Minh
      • +
    +
  • An id with one of the prefixes UTC+, UTC-, GMT+, GMT-, UT+ or UT-, and a suffix in the formats:
    • +|-h[h]
      • @@ -407,6 +440,7 @@ TIMESTAMP { 'yyyy' |
    • Region-based zone IDs in the form area/city, such as Europe/Paris
    +Note: defaults to system time-zone if zone_id is not specified. #### Examples @@ -447,7 +481,8 @@ An interval literal is used to specify a fixed period of time. #### Syntax {% highlight sql %} { INTERVAL interval_value interval_unit [ interval_value interval_unit ... ] | - INTERVAL interval_value interval_unit TO interval_unit } + INTERVAL ' [ INTERVAL ] interval_value interval_unit [ interval_value interval_unit ... ] ' | + INTERVAL interval_string_value interval_unit TO interval_unit } {% endhighlight %} #### Parameters @@ -457,17 +492,23 @@ An interval literal is used to specify a fixed period of time.
    Syntax: - { [ + | - ] number_value | string_value } + [ + | - ] number_value | ' [ + | - ] number_value '
    - Note: string_value needs to be used for INTERNAL ... TO ... format.
    +
    +
    interval_string_value
    +
    + SQL standard year-month/date-time string. +
    +
    interval_unit
    - Syntax: + Syntax:
    - YEAR | MONTH | DAY | HOUR | MINUTE | SECOND | MILLISECOND | MICROSECOND + YEAR[S] | MONTH[S] | WEEK[S] | DAY[S] | HOUR[S] | MINUTE[S] | SECOND[S] |
    + MILLISECOND[S] | MICROSECOND[S]
    @@ -482,15 +523,22 @@ SELECT INTERVAL 3 YEAR AS col; |3 years| +-------+ -SELECT INTERVAL -2 HOUR 3 MINUTE AS col; +SELECT INTERVAL -2 HOUR '3' MINUTE AS col; +--------------------+ | col| +--------------------+ |-1 hours -57 minutes| +--------------------+ -SELECT INTERVAL 1 YEAR 2 MONTH 3 WEEK 4 DAY 5 HOUR 6 MINUTE 7 SECOND 8 - MILLISECOND 9 MICROSECOND AS col; +SELECT INTERVAL 'INTERVAL 1 YEAR 2 DAYS 3 HOURS'; + +----------------------+ + | col| + +----------------------+ + |1 years 2 days 3 hours| + +----------------------+ + +SELECT INTERVAL 1 YEARS 2 MONTH 3 WEEK 4 DAYS 5 HOUR 6 MINUTES 7 SECOND 8 + MILLISECOND 9 MICROSECONDS AS col; +-----------------------------------------------------------+ | col| +-----------------------------------------------------------+ From 6162a8f6af469caf0690da2f250c6f93dc6640ac Mon Sep 17 00:00:00 2001 From: Huaxin Gao Date: Tue, 21 Apr 2020 20:10:34 -0700 Subject: [PATCH 10/12] add binary string literal --- docs/sql-ref-literals.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/docs/sql-ref-literals.md b/docs/sql-ref-literals.md index efcd658a2c08..2fee50dc09f4 100644 --- a/docs/sql-ref-literals.md +++ b/docs/sql-ref-literals.md @@ -35,7 +35,7 @@ A string literal is used to specify a character string value. #### Syntax {% highlight sql %} -'c [ ... ]' | "c [ ... ]" +[ X ] { 'c [ ... ]' | "c [ ... ]" } {% endhighlight %} #### Parameters @@ -46,6 +46,12 @@ A string literal is used to specify a character string value. One character from the character set. Use \ to escape special characters (e.g., ' or \). +
    +
    X
    +
    + Indicates the string literal is in binary format. +
    +
    #### Examples From 59cef7d783aa84b29961cd21fb966373a834908d Mon Sep 17 00:00:00 2001 From: Huaxin Gao Date: Wed, 22 Apr 2020 13:24:35 -0700 Subject: [PATCH 11/12] address comments --- docs/sql-ref-literals.md | 438 ++++++++++++++++++--------------------- 1 file changed, 205 insertions(+), 233 deletions(-) diff --git a/docs/sql-ref-literals.md b/docs/sql-ref-literals.md index 2fee50dc09f4..672f5196bff2 100644 --- a/docs/sql-ref-literals.md +++ b/docs/sql-ref-literals.md @@ -22,6 +22,7 @@ license: | A literal (also known as a constant) represents a fixed data value. Spark SQL supports the following literals: * [String Literal](#string-literal) + * [Binary Literal](#binary-literal) * [Null Literal](#null-literal) * [Boolean Literal](#boolean-literal) * [Numeric Literal](#numeric-literal) @@ -35,7 +36,7 @@ A string literal is used to specify a character string value. #### Syntax {% highlight sql %} -[ X ] { 'c [ ... ]' | "c [ ... ]" } +'c [ ... ]' | "c [ ... ]" {% endhighlight %} #### Parameters @@ -46,36 +47,60 @@ A string literal is used to specify a character string value. One character from the character set. Use \ to escape special characters (e.g., ' or \). -
    -
    X
    -
    - Indicates the string literal is in binary format. -
    -
    #### Examples {% highlight sql %} SELECT 'Hello, World!' AS col; - +-------------+ - | col| - +-------------+ - |Hello, World!| - +-------------+ ++-------------+ +| col| ++-------------+ +|Hello, World!| ++-------------+ SELECT "SPARK SQL" AS col; - +---------+ - | col| - +---------+ - |Spark SQL| - +---------+ ++---------+ +| col| ++---------+ +|Spark SQL| ++---------+ SELECT SELECT 'it\'s $10.' AS col; - +---------+ - | col| - +---------+ - |It's $10.| - +---------+ ++---------+ +| col| ++---------+ +|It's $10.| ++---------+ +{% endhighlight %} + +### Binary Literal + +A binary literal is used to specify a byte sequence value. + +#### Syntax + +{% highlight sql %} +X { 'c [ ... ]' | "c [ ... ]" } +{% endhighlight %} + +#### Parameters + +
    +
    c
    +
    + One character from the character set. +
    +
    + +#### Examples + +{% highlight sql %} +SELECT X'123456' AS col; ++----------+ +| col| ++----------+ +|[12 34 56]| ++----------+ {% endhighlight %} ### Null Literal @@ -92,11 +117,11 @@ NULL {% highlight sql %} SELECT NULL AS col; - +----+ - | col| - +----+ - |NULL| - +----+ ++----+ +| col| ++----+ +|NULL| ++----+ {% endhighlight %} ### Boolean Literal @@ -113,18 +138,18 @@ TRUE | FALSE {% highlight sql %} SELECT TRUE AS col; - +----+ - | col| - +----+ - |true| - +----+ ++----+ +| col| ++----+ +|true| ++----+ {% endhighlight %} ### Numeric Literal A numeric literal is used to specify a fixed or floating-point number. -#### Integer Literal +#### Integral Literal #### Syntax @@ -169,46 +194,46 @@ A numeric literal is used to specify a fixed or floating-point number. {% highlight sql %} SELECT -2147483648 AS col; - +-----------+ - | col| - +-----------+ - |-2147483648| - +-----------+ ++-----------+ +| col| ++-----------+ +|-2147483648| ++-----------+ SELECT 9223372036854775807l AS col; - +-------------------+ - | col| - +-------------------+ - |9223372036854775807| - +-------------------+ ++-------------------+ +| col| ++-------------------+ +|9223372036854775807| ++-------------------+ SELECT -32Y AS col; - +---+ - |col| - +---+ - |-32| - +---+ ++---+ +|col| ++---+ +|-32| ++---+ SELECT 482S AS col; - +---+ - |col| - +---+ - |482| - +---+ ++---+ +|col| ++---+ +|482| ++---+ {% endhighlight %} -#### Non-integer Literals +#### Fractional Literals #### Syntax decimal literals: {% highlight sql %} -{ decimal_digits { [ BD ] | [ exponent BD ] } | digit [ ... ] [ exponent ] BD } +decimal_digits { [ BD ] | [ exponent BD ] } | digit [ ... ] [ exponent ] BD {% endhighlight %} double literals: {% highlight sql %} -{ decimal_digits { D | exponent [ D ] } | digit [ ... ] { exponent [ D ] | [ exponent ] D } +decimal_digits { D | exponent [ D ] } | digit [ ... ] { exponent [ D ] | [ exponent ] D } {% endhighlight %} While decimal_digits is defined as @@ -238,7 +263,7 @@ E [ + | - ] digit [ ... ]
    BD
    - Case insensitive, indicates BIGDECIMAL, which is an arbitrary-precision signed decimal number. + Case insensitive, indicates DECIMAL, with the total number of digits as precision and the number of digits to right of decimal point as scale.
    @@ -246,88 +271,88 @@ E [ + | - ] digit [ ... ] {% highlight sql %} SELECT 12.578 AS col; - +------+ - | col| - +------+ - |12.578| - +------+ ++------+ +| col| ++------+ +|12.578| ++------+ SELECT -0.1234567 AS col; - +----------+ - | col| - +----------+ - |-0.1234567| - +----------+ ++----------+ +| col| ++----------+ +|-0.1234567| ++----------+ SELECT -.1234567 AS col; - +----------+ - | col| - +----------+ - |-0.1234567| - +----------+ ++----------+ +| col| ++----------+ +|-0.1234567| ++----------+ SELECT 123. AS col; - +---+ - |col| - +---+ - |123| - +---+ ++---+ +|col| ++---+ +|123| ++---+ SELECT 123.BD AS col; - +---+ - |col| - +---+ - |123| - +---+ ++---+ +|col| ++---+ +|123| ++---+ SELECT 5E2 AS col; - +-----+ - | col| - +-----+ - |500.0| - +-----+ ++-----+ +| col| ++-----+ +|500.0| ++-----+ SELECT 5D AS col; - +---+ - |col| - +---+ - |5.0| - +---+ ++---+ +|col| ++---+ +|5.0| ++---+ SELECT -5BD AS col; - +---+ - |col| - +---+ - | -5| - +---+ ++---+ +|col| ++---+ +| -5| ++---+ SELECT 12.578e-2d AS col; - +-------+ - | col| - +-------+ - |0.12578| - +-------+ ++-------+ +| col| ++-------+ +|0.12578| ++-------+ SELECT -.1234567E+2BD AS col; - +---------+ - | col| - +---------+ - |-12.34567| - +---------+ ++---------+ +| col| ++---------+ +|-12.34567| ++---------+ SELECT +3.e+3 AS col; - +------+ - | col| - +------+ - |3000.0| - +------+ ++------+ +| col| ++------+ +|3000.0| ++------+ SELECT -3.E-3D AS col; - +------+ - | col| - +------+ - |-0.003| - +------+ ++------+ +| col| ++------+ +|-0.003| ++------+ {% endhighlight %} ### Datetime Literal @@ -342,43 +367,33 @@ A Datetime literal is used to specify a datetime value. DATE { 'yyyy' | 'yyyy-[m]m' | 'yyyy-[m]m-[d]d' | - 'yyyy-[m]m-[d]d ' | - 'yyyy-[m]m-[d]d[T]c[...]' } + 'yyyy-[m]m-[d]d ' } {% endhighlight %} - -#### Parameters - -
    -
    c
    -
    - One character from the character set. -
    -
    Note: defaults to 01 if month or day is not specified. #### Examples {% highlight sql %} SELECT DATE '1997' AS col; - +----------+ - | col| - +----------+ - |1997-01-01| - +----------+ - -SELECT TIMESTAMP '1997-01' AS col; - +----------+ - | col| - +----------+ - |1997-01-01| - +----------+ ++----------+ +| col| ++----------+ +|1997-01-01| ++----------+ + +SELECT DATE '1997-01' AS col; ++----------+ +| col| ++----------+ +|1997-01-01| ++----------+ SELECT DATE '2011-11-11' AS col; - +----------+ - | col| - +----------+ - |2011-11-11| - +----------+ ++----------+ +| col| ++----------+ +|2011-11-11| ++----------+ {% endhighlight %} #### Timestamp Literal @@ -393,49 +408,13 @@ TIMESTAMP { 'yyyy' | 'yyyy-[m]m-[d]d[T][h]h[:]' | 'yyyy-[m]m-[d]d[T][h]h:[m]m[:]' | 'yyyy-[m]m-[d]d[T][h]h:[m]m:[s]s[.]' | - 'yyyy-[m]m-[d]d[T][h]h:[m]m:[s]s.[ms][ms][ms][us][us][us][zone_id]' | - '[T][h]h:' | - '[T][h]h:[m]m[:]' | - '[T][h]h:[m]m:[s]s[.]' | - 'T[h]h' | - '[T][h]h:[m]m:[s]s.[ms][ms][ms][us][us][us][zone_id]' } + 'yyyy-[m]m-[d]d[T][h]h:[m]m:[s]s.[ms][ms][ms][us][us][us][zone_id]'} {% endhighlight %} +Note: defaults to 00 if hour, minute or second is not specified.

    `zone_id` should have one of the forms:
    • Z - Zulu time zone UTC+0
    • +|-[h]h:[m]m
      • -
    • A short id: -
        -
      • EST - -05:00
        • -
      • HST - -10:00
        • -
      • MST - -07:00
        • -
      • ACT - Australia/Darwin
        • -
      • AET - Australia/Sydney
        • -
      • AGT - America/Argentina/Buenos_Aires
        • -
      • ART - Africa/Cairo
        • -
      • AST - America/Anchorage
        • -
      • BET - America/Sao_Paulo
        • -
      • BST - Asia/Dhaka
        • -
      • CAT - Africa/Harare
        • -
      • CNT - America/St_Johns
        • -
      • CST - America/Chicago
        • -
      • CTT - Asia/Shanghai
        • -
      • EAT - Africa/Addis_Ababa
        • -
      • ECT - Europe/Paris
        • -
      • IET - America/Indiana/Indianapolis
        • -
      • IST - Asia/Kolkata
        • -
      • JST - Asia/Tokyo
        • -
      • MIT - Pacific/Apia
        • -
      • NET - Asia/Yerevan
        • -
      • NST - Pacific/Auckland
        • -
      • PLT - Asia/Karachi
        • -
      • PNT - America/Phoenix
        • -
      • PRT - America/Puerto_Rico
        • -
      • PST - America/Los_Angeles
        • -
      • SST - Pacific/Guadalcanal
        • -
      • VST - Asia/Ho_Chi_Minh
        • -
      -
    • An id with one of the prefixes UTC+, UTC-, GMT+, GMT-, UT+ or UT-, and a suffix in the formats:
      • +|-h[h]
        • @@ -446,38 +425,31 @@ TIMESTAMP { 'yyyy' |
      • Region-based zone IDs in the form area/city, such as Europe/Paris
      -Note: defaults to system time-zone if zone_id is not specified. +Note: defaults to the session local timezone (set via spark.sql.session.timeZone) if zone_id is not specified. #### Examples {% highlight sql %} SELECT TIMESTAMP '1997-01-31 09:26:56.123' AS col; - +-----------------------+ - | col| - +-----------------------+ - |1997-01-31 09:26:56.123| - +-----------------------+ ++-----------------------+ +| col| ++-----------------------+ +|1997-01-31 09:26:56.123| ++-----------------------+ SELECT TIMESTAMP '1997-01-31 09:26:56.66666666CST' AS col; - +--------------------------+ - | col | - +--------------------------+ - |1997-01-31 07:26:56.666666| - +--------------------------+ ++--------------------------+ +| col | ++--------------------------+ +|1997-01-31 07:26:56.666666| ++--------------------------+ SELECT TIMESTAMP '1997-01' AS col; - +-------------------+ - | col| - +-------------------+ - |1997-01-01 00:00:00| - +-------------------+ - -SELECT TIMESTAMP '09:26' AS col; - +-------------------+ - | col| - +-------------------+ - |2020-04-17 09:26:00| - +-------------------+ ++-------------------+ +| col| ++-------------------+ +|1997-01-01 00:00:00| ++-------------------+ {% endhighlight %} ### Interval Literal @@ -487,7 +459,7 @@ An interval literal is used to specify a fixed period of time. #### Syntax {% highlight sql %} { INTERVAL interval_value interval_unit [ interval_value interval_unit ... ] | - INTERVAL ' [ INTERVAL ] interval_value interval_unit [ interval_value interval_unit ... ] ' | + INTERVAL ' interval_value interval_unit [ interval_value interval_unit ... ] ' | INTERVAL interval_string_value interval_unit TO interval_unit } {% endhighlight %} @@ -505,7 +477,7 @@ An interval literal is used to specify a fixed period of time.
      interval_string_value
      - SQL standard year-month/date-time string. + year-month/day-time interval string.
      @@ -523,38 +495,38 @@ An interval literal is used to specify a fixed period of time. {% highlight sql %} SELECT INTERVAL 3 YEAR AS col; - +-------+ - | col| - +-------+ - |3 years| - +-------+ ++-------+ +| col| ++-------+ +|3 years| ++-------+ SELECT INTERVAL -2 HOUR '3' MINUTE AS col; - +--------------------+ - | col| - +--------------------+ - |-1 hours -57 minutes| - +--------------------+ ++--------------------+ +| col| ++--------------------+ +|-1 hours -57 minutes| ++--------------------+ SELECT INTERVAL 'INTERVAL 1 YEAR 2 DAYS 3 HOURS'; - +----------------------+ - | col| - +----------------------+ - |1 years 2 days 3 hours| - +----------------------+ ++----------------------+ +| col| ++----------------------+ +|1 years 2 days 3 hours| ++----------------------+ SELECT INTERVAL 1 YEARS 2 MONTH 3 WEEK 4 DAYS 5 HOUR 6 MINUTES 7 SECOND 8 MILLISECOND 9 MICROSECONDS AS col; - +-----------------------------------------------------------+ - | col| - +-----------------------------------------------------------+ - |1 years 2 months 25 days 5 hours 6 minutes 7.008009 seconds| - +-----------------------------------------------------------+ ++-----------------------------------------------------------+ +| col| ++-----------------------------------------------------------+ +|1 years 2 months 25 days 5 hours 6 minutes 7.008009 seconds| ++-----------------------------------------------------------+ SELECT INTERVAL '20 15:40:32.99899999' DAY TO SECOND AS col; - +---------------------------------------------+ - | col| - +---------------------------------------------+ - |20 days 15 hours 40 minutes 32.998999 seconds| - +---------------------------------------------+ ++---------------------------------------------+ +| col| ++---------------------------------------------+ +|20 days 15 hours 40 minutes 32.998999 seconds| ++---------------------------------------------+ {% endhighlight %} From 968338ead21cc32d559a2b6cb191db422526ff7c Mon Sep 17 00:00:00 2001 From: Huaxin Gao Date: Wed, 22 Apr 2020 15:15:29 -0700 Subject: [PATCH 12/12] nit --- docs/sql-ref-literals.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/sql-ref-literals.md b/docs/sql-ref-literals.md index 672f5196bff2..7cf078c1e2c1 100644 --- a/docs/sql-ref-literals.md +++ b/docs/sql-ref-literals.md @@ -65,7 +65,7 @@ SELECT "SPARK SQL" AS col; |Spark SQL| +---------+ -SELECT SELECT 'it\'s $10.' AS col; +SELECT 'it\'s $10.' AS col; +---------+ | col| +---------+ @@ -367,7 +367,7 @@ A Datetime literal is used to specify a datetime value. DATE { 'yyyy' | 'yyyy-[m]m' | 'yyyy-[m]m-[d]d' | - 'yyyy-[m]m-[d]d ' } + 'yyyy-[m]m-[d]d[T]' } {% endhighlight %} Note: defaults to 01 if month or day is not specified. @@ -459,7 +459,7 @@ An interval literal is used to specify a fixed period of time. #### Syntax {% highlight sql %} { INTERVAL interval_value interval_unit [ interval_value interval_unit ... ] | - INTERVAL ' interval_value interval_unit [ interval_value interval_unit ... ] ' | + INTERVAL 'interval_value interval_unit [ interval_value interval_unit ... ]' | INTERVAL interval_string_value interval_unit TO interval_unit } {% endhighlight %} @@ -470,7 +470,7 @@ An interval literal is used to specify a fixed period of time.
      Syntax: - [ + | - ] number_value | ' [ + | - ] number_value ' + [ + | - ] number_value | '[ + | - ] number_value'