Uploaded image for project: 'Spark'
  1. Spark
  2. SPARK-28588 Build a SQL reference doc
  3. SPARK-31383

Clean up the SQL documents in docs/sql-ref*

    XMLWordPrintableJSON

    Details

    • 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
    • Labels:
      None

      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)
       * ...
      

        Attachments

          Issue Links

            Activity

              People

              • Assignee:
                maropu Takeshi Yamamuro
                Reporter:
                maropu Takeshi Yamamuro
              • Votes:
                0 Vote for this issue
                Watchers:
                1 Start watching this issue

                Dates

                • Created:
                  Updated:
                  Resolved: