Document flatten command

Signed-off-by: Yuanchun Shen <yuanchu@amazon.com>

Author: yuancu

docs/user/ppl/cmd/appendcol.rst

@@ -11,9 +11,10 @@ appendcol
 
 Description
 ============
-| (Experimental)
-| (From 3.1.0)
-| Using ``appendcol`` command to append the result of a sub-search and attach it alongside with the input search results (The main search).
+    (Experimental)
+    (From 3.1.0)
+
+Use ``appendcol`` command to append the result of a sub-search and attach it alongside with the input search results (The main search).
 
 Version
 =======

docs/user/ppl/cmd/eventstats.rst

@@ -11,9 +11,10 @@ evenstats
 
 Description
 ============
-| (Experimental)
-| (From 3.1.0)
-| Using ``evenstats`` command to enriches your event data with calculated summary statistics. It operates by analyzing specified fields within your events, computing various statistical measures, and then appending these results as new fields to each original event.
+    (Experimental)
+    (From 3.1.0)
+
+Use ``evenstats`` command to enriches your event data with calculated summary statistics. It operates by analyzing specified fields within your events, computing various statistical measures, and then appending these results as new fields to each original event.
 
 | Key aspects of `eventstats`:
 

docs/user/ppl/cmd/flatten.rst

@@ -12,11 +12,89 @@ Description
 ===========
     From 3.1.0
 
-Use ``flatten`` command to flatten a nested struct field into separate fields in a document.
+Use ``flatten`` command to flatten a nested struct / object field into separate
+fields in a document.
 
+The flattened fields will be ordered **lexicographically** by their original
+key names in the struct. I.e. if the struct has keys ``b``, ``c`` and ``Z``,
+the flattened fields will be ordered as ``Z``, ``b``, ``c``.
+
+Note that ``flatten`` does not work on arrays. Please use ``expand`` command
+to expand an array field into multiple rows instead. If the field is an nested
+array of structs, only the first element of the array will be flattened.
 
 Syntax
 ======
 
-flatten <field-list> [as <alias-list>]
+flatten <field> [as (<alias-list>)]
+
+* field: The field to be flatten. Currently only nested struct is supported.
+* alias-list: (Optional) The names to use instead of the original key names.
+  Names are separated by commas. It is advised to put the alias-list in
+  parentheses if there is more than one alias. E.g. both
+  ``country, state, city`` and ``(country, state, city)`` are supported,
+  but the latter is advised. Its length must match the number of keys in the
+  struct field.  Please note that the provided alias names **must** follow
+  the alphabetical order of the corresponding original keys in the struct.
+
+Example: flatten a struct field with aliases
+============================================
+
+Given the following index ``nested``
+
+.. code-block::
+
+    {"message":{"info":"a","author":"e","dayOfWeek":1},"myNum":1}
+    {"message":{"info":"b","author":"f","dayOfWeek":2},"myNum":2}
+
+with the following mapping:
+
+.. code-block:: json
+
+    {
+      "mappings": {
+        "properties": {
+          "message": {
+            "type": "nested",
+            "properties": {
+              "info": {
+                "type": "keyword",
+                "index": "true"
+              },
+              "author": {
+                "type": "keyword",
+                "fields": {
+                  "keyword": {
+                    "type": "keyword",
+                    "ignore_above": 256
+                  }
+                },
+                "index": "true"
+              },
+              "dayOfWeek": {
+                "type": "long"
+              }
+            }
+          },
+          "myNum": {
+            "type": "long"
+          }
+        }
+      }
+    }
+
+
+The following query flattens the ``message`` field and renames the keys to
+``creator, dow, info``:
+
+PPL query::
+
+    PPL> source=nested | flatten message as (creator, dow, info);
+    fetched rows / total rows = 2/2
+    +-----------------------------------------+--------+---------+-----+------+
+    | message                                 | myNum  | creator | dow | info |
+    |-----------------------------------------|--------|---------|-----|------|
+    | {"info":"a","author":"e","dayOfWeek":1} | 1      | e       | 1   | a    |
+    | {"info":"b","author":"f","dayOfWeek":2} | 2      | f       | 2   | b    |
+    +-----------------------------------------+--------+---------+-----+------+
 

integ-test/src/test/java/org/opensearch/sql/calcite/remote/CalciteFlattenCommandIT.java

@@ -71,7 +71,7 @@ public void testFlattenWithAliases() throws Exception {
   }
 
   @Test
-  public void testFlattenWithMismatchedNumberOfAliasesShouldThrow() throws Exception {
+  public void testFlattenWithMismatchedNumberOfAliasesShouldThrow() {
     Throwable t =
         expectThrows(
             Exception.class,