[SPARK-36468][SQL][DOCS] Update docs about ANSI interval literals

### What changes were proposed in this pull request?
In the PR, I propose to update the doc page https://spark.apache.org/docs/latest/sql-ref-literals.html#interval-literal, and describe formats of ANSI interval literals.

<img width="1032" alt="Screenshot 2021-08-11 at 10 31 36" src="https://user-images.githubusercontent.com/1580697/128988454-7a6ac435-409b-4961-9b79-ebecfb141d5e.png">
<img width="1030" alt="Screenshot 2021-08-10 at 20 58 04" src="https://user-images.githubusercontent.com/1580697/128912018-a4ea3ee5-f252-49c7-a90e-5beaf7ac868f.png">

### Why are the changes needed?
To improve UX with Spark SQL, and inform users about recently added ANSI interval literals.

### Does this PR introduce _any_ user-facing change?
No

### How was this patch tested?
Manually checked the generated docs:
```
$ SKIP_API=1 SKIP_RDOC=1 SKIP_PYTHONDOC=1 SKIP_SCALADOC=1 bundle exec jekyll build
```

Closes #33693 from MaxGekk/doc-ansi-interval-literals.

Authored-by: Max Gekk <max.gekk@gmail.com>
Signed-off-by: Max Gekk <max.gekk@gmail.com>
This commit is contained in:
Max Gekk 2021-08-11 13:38:39 +03:00
parent f7c85b855b
commit bbf988bd73

View file

@ -439,13 +439,78 @@ SELECT TIMESTAMP '1997-01' AS col;
An interval literal is used to specify a fixed period of time. An interval literal is used to specify a fixed period of time.
#### ANSI style
The ANSI SQL standard defines interval literals in the form:
```sql
INTERVAL [ <sign> ] <interval string> <interval qualifier>
```
where `<interval qualifier>` can be a single field or in the field-to-field form:
```sql
<interval qualifier> ::= <start field> TO <end field> | <single field>
```
The field name is case-insensitive, and can be one of `YEAR`, `MONTH`, `DAY`, `HOUR`, `MINUTE` and `SECOND`.
An interval literal can have either year-month or day-time interval type. The interval sub-type defines format of `<interval string>`:
```sql
<interval string> ::= <quote> [ <sign> ] { <year-month literal> | <day-time literal> } <quote>
<year-month literal> ::= <years value> [ <minus sign> <months value> ] | <months value>
<day-time literal> ::= <day-time interval> | <time interval>
<day-time interval> ::= <days value> [ <space> <hours value> [ <colon> <minutes value> [ <colon> <seconds value> ] ] ]
<time interval> ::= <hours value> [ <colon> <minutes value> [ <colon> <seconds value> ] ]
| <minutes value> [ <colon> <seconds value> ]
| <seconds value>
```
Supported year-month interval literals and theirs formats:
|`<interval qualifier>`|Interval string pattern|An instance of the literal|
|---------|-------|------------|
|YEAR|`[+|-]'[+|-]y'`|`INTERVAL -'2021' YEAR`|
|YEAR TO MONTH|`[+|-]'[+|-]y-m'`|`INTERVAL '-2021-07' YEAR TO MONTH`|
|MONTH|`[+|-]'[+|-]m'`|`interval '10' month`|
Formats of supported day-time interval literals:
|`<interval qualifier>`|Interval string pattern|An instance of the literal|
|---------|----|-------------------|
|DAY|`[+|-]'[+|-]d'`|`INTERVAL -'100' DAY`|
|DAY TO HOUR|`[+|-]'[+|-]d h'`|`INTERVAL '-100 10' DAY TO HOUR`|
|DAY TO MINUTE|`[+|-]'[+|-]d h:m'`|`INTERVAL '100 10:30' DAY TO MINUTE`|
|DAY TO SECOND|`[+|-]'[+|-]d h:m:s.n'`|`INTERVAL '100 10:30:40.999999' DAY TO SECOND`|
|HOUR|`[+|-]'[+|-]h'`|`INTERVAL '123' HOUR`|
|HOUR TO MINUTE|`[+|-]'[+|-]h:m'`|`INTERVAL -'-123:10' HOUR TO MINUTE`|
|HOUR TO SECOND|`[+|-]'[+|-]h:m:s.n'`|`INTERVAL '123:10:59' HOUR TO SECOND`|
|MINUTE|`[+|-]'[+|-]m'`|`interval '1000' minute`|
|MINUTE TO SECOND|`[+|-]'[+|-]m:s.n'`|`INTERVAL '1000:01.001' MINUTE TO SECOND`|
|SECOND|`[+|-]'[+|-]s.n'`|`INTERVAL '1000.000001' SECOND`|
##### Examples
```sql
SELECT INTERVAL '2-3' YEAR TO MONTH AS col;
+----------------------------+
|col |
+----------------------------+
|INTERVAL '2-3' YEAR TO MONTH|
+----------------------------+
SELECT INTERVAL -'20 15:40:32.99899999' DAY TO SECOND AS col;
+--------------------------------------------+
|col |
+--------------------------------------------+
|INTERVAL '-20 15:40:32.998999' DAY TO SECOND|
+--------------------------------------------+
```
#### Multi-units style
```sql ```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_value interval_unit [ interval_value interval_unit ... ]' |
INTERVAL interval_string_value interval_unit TO interval_unit
``` ```
#### Parameters ##### Parameters
* **interval_value** * **interval_value**
@ -453,10 +518,6 @@ INTERVAL interval_string_value interval_unit TO interval_unit
[ + | - ] number_value | '[ + | - ] number_value' [ + | - ] number_value | '[ + | - ] number_value'
* **interval_string_value**
year-month/day-time interval string.
* **interval_unit** * **interval_unit**
**Syntax:** **Syntax:**
@ -464,7 +525,9 @@ INTERVAL interval_string_value interval_unit TO interval_unit
YEAR[S] | MONTH[S] | WEEK[S] | DAY[S] | HOUR[S] | MINUTE[S] | SECOND[S] | YEAR[S] | MONTH[S] | WEEK[S] | DAY[S] | HOUR[S] | MINUTE[S] | SECOND[S] |
MILLISECOND[S] | MICROSECOND[S] MILLISECOND[S] | MICROSECOND[S]
#### Examples Mix of the YEAR[S] or MONTH[S] interval units with other units is not allowed.
##### Examples
```sql ```sql
SELECT INTERVAL 3 YEAR AS col; SELECT INTERVAL 3 YEAR AS col;
@ -495,18 +558,4 @@ SELECT INTERVAL 1 YEARS 2 MONTH 3 WEEK 4 DAYS 5 HOUR 6 MINUTES 7 SECOND 8
+-----------------------------------------------------------+ +-----------------------------------------------------------+
|1 years 2 months 25 days 5 hours 6 minutes 7.008009 seconds| |1 years 2 months 25 days 5 hours 6 minutes 7.008009 seconds|
+-----------------------------------------------------------+ +-----------------------------------------------------------+
SELECT INTERVAL '2-3' YEAR TO MONTH AS col;
+----------------+
| col|
+----------------+
|2 years 3 months|
+----------------+
SELECT INTERVAL '20 15:40:32.99899999' DAY TO SECOND AS col;
+---------------------------------------------+
| col|
+---------------------------------------------+
|20 days 15 hours 40 minutes 32.998999 seconds|
+---------------------------------------------+
``` ```