[SPARK-31738][SQL][DOCS] Describe 'L' and 'M' month pattern letters #28558

MaxGekk · 2020-05-17T19:09:21Z

What changes were proposed in this pull request?

Describe standard 'M' and stand-alone 'L' text forms
Add examples for all supported number of month letters

Why are the changes needed?

To improve docs and show how to use month patterns.

Does this PR introduce any user-facing change?

No

How was this patch tested?

By building docs and checking by eyes.

MaxGekk · 2020-05-17T19:11:55Z

@cloud-fan @HyukjinKwon @xuanyuanking Please, review this PR.

SparkQA · 2020-05-17T19:27:13Z

Test build #122759 has finished for PR 28558 at commit eefc316.

This patch passes all tests.
This patch merges cleanly.
This patch adds no public classes.

cloud-fan · 2020-05-18T04:20:07Z

docs/sql-ref-datetime-pattern.md


 - Year: The count of letters determines the minimum field width below which padding is used. If the count of letters is two, then a reduced two digit form is used. For printing, this outputs the rightmost two digits. For parsing, this will parse using the base value of 2000, resulting in a year within the range 2000 to 2099 inclusive. If the count of letters is less than four (but not two), then the sign is only output for negative years. Otherwise, the sign is output if the pad width is exceeded when 'G' is not present.

+- Month: If the number of pattern letters is 3 or more, the month is interpreted as text; otherwise, it is interpreted as a number. The text form is depend on letters - 'M' denotes the 'standard' form, and 'L' is for 'stand-alone' form. The difference between the 'standard' and 'stand-alone' forms is trickier to describe as there is no difference in English. However, in other languages there is a difference in the word used when the text is used alone, as opposed to in a complete date. For example, the word used for a month when used alone in a date picker is different to the word used for month in association with a day and year in a date. Here are examples for all supported pattern letters:


we can give an example in Russia.

The PR contains examples in Russian already

It's better to give a quick example here, so that some users can stop reading the following detailed examples to save time.

cloud-fan · 2020-05-18T04:21:05Z

docs/sql-ref-datetime-pattern.md

+    spark-sql> select to_csv(named_struct('date', date '1970-01-01'), map('dateFormat', 'LLLL', 'locale', 'RU'));
+    январь
+    ```
+  - `'LLLLL'` or `'MMMMM'`: Narrow textual representation of standard or stand-alone forms. Typically it is a single letter.


how about 6 L/Ms?

I demonstrate only supported patterns

do we document somewhere that 6 or more L/Ms are invalid?

I wrote above that this is the list of all supported patterns or do you think it is not enough?

how about

Here are examples for all supported pattern letters (more than 5 letter is invalid):

xuanyuanking · 2020-05-18T04:46:05Z

docs/sql-ref-datetime-pattern.md


 - Year: The count of letters determines the minimum field width below which padding is used. If the count of letters is two, then a reduced two digit form is used. For printing, this outputs the rightmost two digits. For parsing, this will parse using the base value of 2000, resulting in a year within the range 2000 to 2099 inclusive. If the count of letters is less than four (but not two), then the sign is only output for negative years. Otherwise, the sign is output if the pad width is exceeded when 'G' is not present.

+- Month: If the number of pattern letters is 3 or more, the month is interpreted as text; otherwise, it is interpreted as a number. The text form is depend on letters - 'M' denotes the 'standard' form, and 'L' is for 'stand-alone' form. The difference between the 'standard' and 'stand-alone' forms is trickier to describe as there is no difference in English. However, in other languages there is a difference in the word used when the text is used alone, as opposed to in a complete date. For example, the word used for a month when used alone in a date picker is different to the word used for month in association with a day and year in a date. Here are examples for all supported pattern letters:


Do we also need to add an extra official description link for the 'standard' and 'standalone' mode?

This is the official doc, isn't it as we decided to not refer to Java doc anymore.

SparkQA · 2020-05-18T06:14:47Z

Test build #122790 has finished for PR 28558 at commit 8a43b8c.

This patch passes all tests.
This patch merges cleanly.
This patch adds no public classes.

cloud-fan · 2020-05-18T12:06:53Z

thanks, merging to master/3.0!

### What changes were proposed in this pull request? 1. Describe standard 'M' and stand-alone 'L' text forms 2. Add examples for all supported number of month letters <img width="1047" alt="Screenshot 2020-05-18 at 08 57 31" src="https://user-images.githubusercontent.com/1580697/82178856-b16f1000-98e5-11ea-87c0-456ef94dcd43.png"> ### Why are the changes needed? To improve docs and show how to use month patterns. ### Does this PR introduce _any_ user-facing change? No ### How was this patch tested? By building docs and checking by eyes. Closes #28558 from MaxGekk/describe-L-M-date-pattern. Authored-by: Max Gekk <max.gekk@gmail.com> Signed-off-by: Wenchen Fan <wenchen@databricks.com> (cherry picked from commit b3686a7) Signed-off-by: Wenchen Fan <wenchen@databricks.com>

HyukjinKwon · 2020-05-19T02:16:07Z

+1 seems good to me too

Month pattern descriptions

eefc316

probot-autolabeler bot added the DOCS label May 17, 2020

MaxGekk changed the title ~~[SPARK-31738][SQL][DOC] Describe 'L' and 'M' month pattern letters~~ [SPARK-31738][SQL][DOCS] Describe 'L' and 'M' month pattern letters May 17, 2020

cloud-fan reviewed May 18, 2020

View reviewed changes

xuanyuanking reviewed May 18, 2020

View reviewed changes

Address review comments

8a43b8c

cloud-fan closed this in b3686a7 May 18, 2020

MaxGekk deleted the describe-L-M-date-pattern branch June 5, 2020 19:49


		- Year: The count of letters determines the minimum field width below which padding is used. If the count of letters is two, then a reduced two digit form is used. For printing, this outputs the rightmost two digits. For parsing, this will parse using the base value of 2000, resulting in a year within the range 2000 to 2099 inclusive. If the count of letters is less than four (but not two), then the sign is only output for negative years. Otherwise, the sign is output if the pad width is exceeded when 'G' is not present.

		- Month: If the number of pattern letters is 3 or more, the month is interpreted as text; otherwise, it is interpreted as a number. The text form is depend on letters - 'M' denotes the 'standard' form, and 'L' is for 'stand-alone' form. The difference between the 'standard' and 'stand-alone' forms is trickier to describe as there is no difference in English. However, in other languages there is a difference in the word used when the text is used alone, as opposed to in a complete date. For example, the word used for a month when used alone in a date picker is different to the word used for month in association with a day and year in a date. Here are examples for all supported pattern letters:

[SPARK-31738][SQL][DOCS] Describe 'L' and 'M' month pattern letters #28558

[SPARK-31738][SQL][DOCS] Describe 'L' and 'M' month pattern letters #28558

Uh oh!

Conversation

MaxGekk commented May 17, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What changes were proposed in this pull request?

Why are the changes needed?

Does this PR introduce any user-facing change?

How was this patch tested?

Uh oh!

MaxGekk commented May 17, 2020

Uh oh!

SparkQA commented May 17, 2020

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cloud-fan May 18, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

MaxGekk May 18, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

SparkQA commented May 18, 2020

Uh oh!

cloud-fan commented May 18, 2020

Uh oh!

HyukjinKwon commented May 19, 2020

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

MaxGekk commented May 17, 2020 •

edited

Loading

cloud-fan May 18, 2020 •

edited

Loading

MaxGekk May 18, 2020 •

edited

Loading