Update chart doc

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

Author: yuancu

docs/user/ppl/cmd/chart.rst

@@ -32,24 +32,26 @@ Syntax
 
 * **limit**: optional. Specifies the number of distinct values to display when using column split.
 
-  * Default: 10
-  * Syntax: ``limit=(top|bottom) <number>`` or ``limit=<number>`` (defaults to top)
-  * When there are more distinct column split values than the limit, the additional values are grouped into an "OTHER" category if ``useother`` is not set to false.
-  * Set to 0 to show all distinct values without any limit.
+  * Default: top10
+  * Syntax: ``limit=(top|bottom)<number>`` or ``limit=<number>`` (defaults to top)
+  * When ``limit=K`` is set, the top or bottom K distinct column split values are retained; the additional values are grouped into an "OTHER" category if ``useother`` is not set to false.
+  * Set limit to 0 to show all distinct values without any limit.
+  * Use ``limit=topK`` or ``limit=bottomK`` to specify whether to retain the top or bottom K column categories. The ranking is based on the aggregated values for each distinct column-split value.  For example, ``chart limit=top3 count() by a b`` retains the 3 most common b categories; ``chart limit=top5 min(value) by a b`` selects the 5 b categories that contains smallest aggregated values. If not specified, top is used by default.
   * Only applies when column split presents (by 2 fields or over...by... coexists).
 
-* **useother**: optional. Controls whether to create an "OTHER" category for distinct column values beyond the limit.
+* **useother**: optional. Controls whether to create an "OTHER" category for distinct column-split values beyond the limit.
 
   * Default: true
-  * When set to false, only the top/bottom N distinct values (based on limit) are shown without an "OTHER" category.
+  * When set to false, only the top/bottom N distinct column-split values (based on limit) are shown without an "OTHER" category.
   * When set to true, distinct values beyond the limit are grouped into an "OTHER" category.
-  * Only applies when using column split and when there are more distinct column values than the limit.
+  * Only applies when using column split and when there are more distinct column-split values than the limit.
 
-* **usenull**: optional. Controls whether to include null values as a separate category.
+* **usenull**: optional. Controls whether to group events without a column split (i.e. whose column split is null) into a separate "NULL" category.
 
   * Default: true
-  * When set to false, events with null values in the split-by field are excluded from results.
-  * When set to true, null values appear as a separate category.
+  * When ``usenull=false``, events with a null column split are excluded from results.
+  * When ``usenull=true``, events with a null column split are grouped into a separate "NULL" category.
+  * ``usenull`` only applies to column split. Null values in the row split are handled in the same way as normal aggregations.
 
 * **nullstr**: optional. Specifies the category name for rows that do not contain the column split value.
 
@@ -80,7 +82,8 @@ Syntax
 Notes
 =====
 
-* The column split field in the result will become strings so that they are compatible with ``nullstr`` and ``otherstr`` and can be used as column names once pivoted.
+* The fields generated by column splitting are converted to strings so that they are compatible with ``nullstr`` and ``otherstr`` and can be used as column names once pivoted.
+* The aggregation metric appears as the last column in the result. Result columns are ordered as: [row-split] [column-split] [aggregation-metrics]
 
 Examples
 ========
@@ -119,7 +122,7 @@ PPL query::
 Example 3: Using over and by for multiple field grouping
 --------------------------------------------------------
 
-This example shows average balance grouped by both gender and age fields.
+This example shows average balance grouped by both gender and age fields. Note that the age column in the result is converted to string type.
 
 PPL query::
 
@@ -137,7 +140,7 @@ PPL query::
 Example 4: Using basic limit functionality
 ------------------------------------------
 
-This example limits the results to show only the top 1 age group.
+This example limits the results to show only the top 1 age group. Note that the age column in the result is converted to string type.
 
 PPL query::
 
@@ -158,7 +161,7 @@ This example shows using limit with useother and custom otherstr parameters.
 
 PPL query::
 
-    os> source=accounts | chart limit=top 1 useother=true otherstr='minor_gender' count() over state by gender
+    os> source=accounts | chart limit=top1 useother=true otherstr='minor_gender' count() over state by gender
     fetched rows / total rows = 4/4
     +-------+--------------+---------+
     | state | gender       | count() |