[SPARK-31383] Clean up the SQL documents in docs/sql-ref*

• Type: Sub-task
• Status: Resolved
• Priority: Minor
• Resolution: Fixed
• Affects Version/s: 3.0.0
• Fix Version/s: 3.0.0
• Component/s: Documentation, SQL
• Assignee: Takeshi Yamamuro
• Reporter: Takeshi Yamamuro
• Created: 08/Apr/20 07:58
• Updated: 13/Apr/20 04:41
• Resolved: 13/Apr/20 04:41

Description

This ticket intends to clean up the SQL documents in `doc/sql-ref*`.
Main changes are as follows;

• Fixes wrong syntaxes and capitalize sub-titles
• Adds some DDL queries in `Examples` so that users can run examples there
• Makes query output in `Examples` follows the `Dataset.showString` (right-aligned) format
• Adds/Removes spaces, Indents, or blank lines to follow the format below;

---
license...
---

### Description

Writes what's the syntax is.

### Syntax

{% highlight sql %}
SELECT...
 WHERE... // 4 indents after the second line
 ...
{% endhighlight %}

### Parameters

<dl>
 <!-- 2 indents in this section -->
 <dt><code><em>Param Name</em></code></dt>
 <dd>
 Param Description
 </dd>
 ...
</dl>

### Examples

{% highlight sql %}
-- It is better that users are able to execute example queries here.
-- So, we prepare test data in the first section if possible.
CREATE TABLE t (key STRING, value DOUBLE);
INSERT INTO t VALUES
 ('a', 1.0), ('a', 2.0), ('b', 3.0), ('c', 4.0);

-- query output has 2 indents and it follows the `Dataset.showString`
-- format (right-aligned).
SELECT * FROM t;
 +---+-----+
 |key|value|
 +---+-----+
 | a| 1.0|
 | a| 2.0|
 | b| 3.0|
 | c| 4.0|
 +---+-----+

-- Query statements after the second line have 4 indents.
SELECT key, SUM(value)
 FROM t
 GROUP BY key;
 +---+----------+ 
 |key|sum(value)|
 +---+----------+
 | c| 4.0|
 | b| 3.0|
 | a| 3.0|
 +---+----------+
...
{% endhighlight %}

### Related Statements

* [XXX](xxx.html)
 * ...

Issue Links

• links to: GitHub Pull Request #28151