Tweak chart.rst

Signed-off-by: Yuanchun Shen <[email protected]>

Author: yuancu

docs/user/ppl/cmd/chart.rst

@@ -1,6 +1,6 @@
-=============
+=====
 chart
-=============
+=====
 
 .. rubric:: Table of contents
 
@@ -10,7 +10,7 @@ chart
 
 
 Description
-============
+===========
 
 The ``chart`` command transforms search results by applying a statistical aggregation function and optionally grouping the data by one or two fields. The results are suitable for visualization as a two-dimension chart when grouping by two fields, where unique values in the second group key can be pivoted to column names.
 
@@ -19,7 +19,7 @@ Version
 3.4.0
 
 Syntax
-============
+======
 
 .. code-block:: text
 
@@ -34,62 +34,59 @@ Syntax
 
   * Default: 10
   * Syntax: ``limit=(top|bottom) <number>`` or ``limit=<number>`` (defaults to top)
-  * When there are more distinct values than the limit, the additional values are grouped into an "OTHER" category if useother is not set to false.
+  * 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.
-  * Only applies when using column split (over...by clause).
+  * Only applies when column split presents (by 2 fields or over...by... coexists).
 
-* **useother**: optional. Controls whether to create an "OTHER" category for values beyond the limit.
+* **useother**: optional. Controls whether to create an "OTHER" category for distinct column values beyond the limit.
 
   * Default: true
-  * When set to false, only the top/bottom N values (based on limit) are shown without an "OTHER" category.
-  * When set to true, values beyond the limit are grouped into an "OTHER" category.
-  * Only applies when using column split and when there are more distinct values than the limit.
+  * When set to false, only the top/bottom N distinct 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.
 
 * **usenull**: optional. Controls whether to include null values as a separate 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.
 
-* **nullstr**: optional. Specifies the string to display for null values.
+* **nullstr**: optional. Specifies the category name for rows that do not contain the column split value.
 
   * Default: "NULL"
-  * Only applies when usenull is set to true.
+  * Only applies when ``usenull`` is set to true.
 
-* **otherstr**: optional. Specifies the string to display for the "OTHER" category.
+* **otherstr**: optional. Specifies the category name for the "OTHER" category.
 
   * Default: "OTHER"
-  * Only applies when useother is set to true and there are values beyond the limit.
+  * Only applies when ``useother`` is set to true and there are values beyond the limit.
 
 * **aggregation_function**: mandatory. The aggregation function to apply to the data.
 
   * Currently, only a single aggregation function is supported.
-  * Available functions: All aggregation functions supported by the :doc:`stats <stats>` command.
+  * Available functions: aggregation functions supported by the `stats <stats.rst>`_ command.
 
-* **by**: optional. Groups the results by the specified field as rows.
+* **by**: optional. Groups the results by either one field (row split) or two fields (row split and column split)
 
+  * ``limit``, ``useother``, and ``usenull`` apply to the column split
+  * Results are returned as individual rows for each combination.
   * If not specified, the aggregation is performed across all documents.
 
-* **over...by**: optional. Alternative syntax for grouping by multiple fields.
+* **over...by...**: optional. Alternative syntax for grouping by multiple fields.
 
   * ``over <row_split> by <column_split>`` groups the results by both fields.
-  * The row_split field becomes the primary grouping dimension.
-  * The column_split field becomes the secondary grouping dimension.
-  * Results are returned as individual rows for each combination.
+  * Using ``over`` alone on one field is equivalent to ``by <row-split>``
 
 Notes
 =====
 
-* The ``chart`` command transforms results into a table format suitable for visualization.
-* When using multiple grouping fields (over...by syntax), the output contains individual rows for each combination of the grouping fields.
-* The limit parameter determines how many columns to show when there are many distinct values.
-* Results are ordered by the aggregated values to determine top/bottom selections.
+* 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.
 
 Examples
 ========
 
 Example 1: Basic aggregation without grouping
-==============================================
+---------------------------------------------
 
 This example calculates the average balance across all accounts.
 
@@ -104,7 +101,7 @@ PPL query::
     +--------------+
 
 Example 2: Group by single field
-=================================
+--------------------------------
 
 This example calculates the count of accounts grouped by gender.
 
@@ -120,7 +117,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.
 
@@ -138,7 +135,7 @@ PPL query::
     +--------+-----+--------------+
 
 Example 4: Using basic limit functionality
-========================================
+------------------------------------------
 
 This example limits the results to show only the top 1 age group.
 
@@ -155,7 +152,7 @@ PPL query::
     +--------+-------+---------+
 
 Example 5: Using limit with other parameters
-=============================================
+--------------------------------------------
 
 This example shows using limit with useother and custom otherstr parameters.
 
@@ -173,7 +170,7 @@ PPL query::
     +-------+--------+--------------+
 
 Example 6: Using span with chart command
-=======================================
+----------------------------------------
 
 This example demonstrates using span for grouping age ranges.
 
@@ -189,6 +186,5 @@ PPL query::
     +--------------+-----+
 
 Limitations
-============
+-----------
 * Only a single aggregation function is supported per chart command.
-* When using both row and column splits, the column split field is converted to string type so that it can be used as column names.