[DOC]Revise and edit PPL in-product documentation

public/components/common/helpers/ppl_docs/commands/dedup.ts

@@ -8,33 +8,21 @@ export const dedupCmd = `## dedup
 
 ### Description
 
-Using \'dedup\' command to remove identical document defined by field from
-the search result.
+Use the \'dedup\' command to remove identical documents from the search results, based on the specified field.
 
 ### Syntax
 
 dedup \[int\] <field-list> \[keepempty=<bool>\]
 \[consecutive=<bool>\]
 
--   int: optional. The \'dedup\' command retains multiple events for each
-    combination when you specify <int>. The number for <int>
-    must be greater than 0. If you do not specify a number, only the
-    first occurring event is kept. All other duplicates are removed from
-    the results. **Default:** 1
--   keepempty: optional. if true, keep the document if the any field in
-    the field-list has NULL value or field is MISSING. **Default:**
-    false.
--   consecutive: optional. If set to true, removes only events with
-    duplicate combinations of values that are consecutive. **Default:**
-    false.
--   field-list: mandatory. The comma-delimited field list. At least one
-    field is required.
+-   \`field-list\`: Required. The comma-delimited field list. At least one field is required.
+-   \`consecutive\`: Optional. If set to \`true\`, removes duplicate events, where the duplicate events have consecutive timestamps. **Default:** \`false\`
+-   \`int\`: Optional. The \'dedup\' command retains multiple events for each combination when you specify \`<int>\`. The number for \`<int>\` must be greater than 0. If you do not specify a number, only the first occurring event is kept. All other duplicates are removed from the results. Default is \`1\`.
+-   \`keepempty\`: Optional. If set to \`true\`, keep the document if any field in the \`field-list\` is null or missing. Default is \`false\`.
 
-### Example 1: Dedup by one field
+#### Example 1: Dedup by one field
 
-The example show dedup the document with gender field.
-
-PPL query:
+The following PPL query example shows how to use \`dedup\` to remove duplicate documents based on the \`gender\` field.
 
     os> source=accounts | dedup gender | fields account_number, gender;
     fetched rows / total rows = 2/2
@@ -45,12 +33,9 @@ PPL query:
     | 13               | F        |
     +------------------+----------+
 
-### Example 2: Keep 2 duplicates documents
-
-The example show dedup the document with gender field keep 2
-duplication.
+#### Example 2: Keep two duplicate documents
 
-PPL query:
+The following PPL query example shows how to use \`dedup\` to remove duplicate documents based on the \`gender\` field while keeping two duplicates.
 
     os> source=accounts | dedup 2 gender | fields account_number, gender;
     fetched rows / total rows = 3/3
@@ -62,11 +47,9 @@ PPL query:
     | 13               | F        |
     +------------------+----------+
 
-### Example 3: Keep or Ignore the empty field by default
-
-The example show dedup the document by keep null value field.
+#### Example 3: Keep or ignore empty fields by default
 
-PPL query:
+The following PPL query example shows how to use \`dedup\` to remove duplicate documents while keeping documents with null values in the specified field.
 
     os> source=accounts | dedup email keepempty=true | fields account_number, email;
     fetched rows / total rows = 4/4
@@ -79,9 +62,7 @@ PPL query:
     | 18               | daleadams@boink.com   |
     +------------------+-----------------------+
 
-The example show dedup the document by ignore the empty value field.
-
-PPL query:
+The following PPL query example shows how to use \`dedup\` to remove duplicate documents while ignoring documents with empty values in the specified field.
 
     os> source=accounts | dedup email | fields account_number, email;
     fetched rows / total rows = 3/3
@@ -93,11 +74,9 @@ PPL query:
     | 18               | daleadams@boink.com   |
     +------------------+-----------------------+
 
-#### Example 4: Dedup in consecutive document
-
-The example show dedup the consecutive document.
+#### Example 4: Remove duplicate consecutive documents
 
-PPL query:
+The following PPL query example shows how to use \`dedup\` to remove duplicate documents while removing the duplicate consecutive document.
 
     os> source=accounts | dedup gender consecutive=true | fields account_number, gender;
     fetched rows / total rows = 3/3
@@ -109,6 +88,6 @@ PPL query:
     | 18               | M        |
     +------------------+----------+
 
-#### Limitation
-The \`dedup\` command is not rewritten to OpenSearch DSL, it is only executed on the coordination node.
+### Limitation
+The \`dedup\` command is not rewritten to Query DSL. It's only run on the coordinating node.
 `;

public/components/common/helpers/ppl_docs/commands/eval.ts

@@ -8,24 +8,19 @@ export const evalCmd = `## eval
 
 ### Description
 
-The \'eval\' command evaluate the expression and append the result to the
-search result.
+Use the \'eval\' command to evaluate the expression and append the result to the search result.
 
 ### Syntax
 
 eval <field>=<expression> \[","
 <field>=<expression> \]...
 
--   field: mandatory. If the field name not exist, a new field is added.
-    If the field name already exists, it will be overrided.
--   expression: mandatory. Any expression support by the system.
+-   \`field\`: Required. If the field name does not exist, a new field is created. If the field name exists, the vlaue of the existing field is replaced.
+-   \`expression\`: Required. Any expression that is supported by the system.
 
-### Example 1: Create the new field
+#### Example 1: Create new fields
 
-The example show to create new field doubleAge for each document. The
-new doubleAge is the evaluation result of age multiply by 2.
-
-PPL query:
+The following PPL example shows how to use \`eval\` to create a new field for each document. In this example, the new field is \`doubleAge\`.
 
     os> source=accounts | eval doubleAge = age * 2 | fields age, doubleAge ;
     fetched rows / total rows = 4/4
@@ -38,11 +33,9 @@ PPL query:
     | 33    | 66          |
     +-------+-------------+
 
-### Example 2: Override the existing field
-
-The example show to override the exist age field with age plus 1.
+#### Example 2: Override existing fields
 
-PPL query:
+The following PPL example shows how to use \`eval\` to override an existing field. In this example, the existing field \`age\` is overridden by the \`age\` field plus 1.
 
     os> source=accounts | eval age = age + 1 | fields age ;
     fetched rows / total rows = 4/4
@@ -55,13 +48,9 @@ PPL query:
     | 34    |
     +-------+
 
-### Example 3: Create the new field with field defined in eval
-
-The example show to create a new field ddAge with field defined in eval
-command. The new field ddAge is the evaluation result of doubleAge
-multiply by 2, the doubleAge is defined in the eval command.
+#### Example 3: Create new fields based on the fields defined in the \`eval\` expression
 
-PPL query:
+The following PPL example shows how to use \`eval\` to create a new field based on the fields defined in the \`eval\` esperession. In this example, the new field \`ddAge\` is the evaluation result of the \`doubleAge\` field multiplied by 2. The doubleAge is defined in the eval command.
 
     os> source=accounts | eval doubleAge = age * 2, ddAge = doubleAge * 2 | fields age, doubleAge, ddAge ;
     fetched rows / total rows = 4/4
@@ -74,6 +63,6 @@ PPL query:
     | 33    | 66          | 132     |
     +-------+-------------+---------+
 
-#### Limitation
-The \`eval\` command is not rewritten to OpenSearch DSL, it is only executed on the coordination node.
+### Limitation
+The \`eval\` command is not rewritten to Query DSL. It's only run on the coordinating node.
 `;

public/components/common/helpers/ppl_docs/commands/fields.ts

@@ -7,23 +7,18 @@ export const fieldsCmd = `## fields
 ---
 ### Description
 
-Using \`fields\` command to keep or remove fields from the search result.
+Use the \`fields\` command to specify the fields that should be included or excluded in the search results.
 
 ### Syntax
 
 fields \[+\|-\] <field-list>
 
--   index: optional. if the plus (+) is used, only the fields specified
-    in the field list will be keep. if the minus (-) is used, all the
-    fields specified in the field list will be removed. **Default** +
--   field list: mandatory. comma-delimited keep or remove fields.
+-   \`field-list\`: Required. Comma-separated list of fields to keep or remove.
+-   \`index\`: Optional. If the plus sign \`+\` is used, only the fields specified in the field list will be included. If the minus \`-\` is used, all the fields specified in the field list will be excluded. **Default** \`+\`
 
-### Example 1: Select specified fields from result
+#### Example 1: Select specified fields from the search result
 
-The example show fetch account\_number, firstname and lastname fields
-from search results.
-
-PPL query:
+The following PPL query example shows how to retrieve the \`account\_number\`,\`firstname\`, and \`lastname\` fields\` from the search results.
 
     os> source=accounts | fields account_number, firstname, lastname;
     fetched rows / total rows = 4/4
@@ -36,11 +31,9 @@ PPL query:
     | 18               | Dale        | Adams      |
     +------------------+-------------+------------+
 
-### Example 2: Remove specified fields from result
-
-The example show fetch remove account\_number field from search results.
+#### Example 2: Remove specified fields from the search results
 
-PPL query:
+The following PPL query example shows how to remove the \`account\_number\` field from the search results.
 
     os> source=accounts | fields account_number, firstname, lastname | fields - account_number ;
     fetched rows / total rows = 4/4

public/components/common/helpers/ppl_docs/commands/head.ts

@@ -8,21 +8,17 @@ export const headCmd = `## head
 
 ### Description
 
-The \`head\` command returns the first N number of specified results in
-search order.
+Use the \`head\` command to return the first N number of lines from a search result.
 
 ### Syntax
 
 head \[N\]
 
--   N: optional. number of results to return. **Default:** 10
+-   \`N\`: Optional. The number of results you want to see. Default is 10.
 
-### Example 1: Get first 10 results
-
-The example show first 10 results from accounts index.
-
-PPL query:
+#### Example 1: Get first 10 results
 
+The following PPL query example shows how to use \`head\` to see the first 10 search results. 
     os> source=accounts | fields firstname, age | head;
     fetched rows / total rows = 10/10
     +---------------+-----------+
@@ -40,11 +36,9 @@ PPL query:
     | Fulton        | 23        |
     +---------------+-----------+
 
-### Example 2: Get first N results
-
-The example show first N results from accounts index.
+#### Example 2: Get first N results
 
-PPL query:
+The following PPL query example shows how to use \`head\` to get a speficied number of search results. In this example, N is 3. 
 
     os> source=accounts | fields firstname, age | head 3;
     fetched rows / total rows = 3/3
@@ -57,5 +51,5 @@ PPL query:
     +---------------+-----------+
 
 #### Limitation
-The \`head\` command is not rewritten to OpenSearch DSL, it is only executed on the coordination node.
+The \`head\` command is not rewritten to Query DSL. It's only run on the coordinating node.
 `;

public/components/common/helpers/ppl_docs/commands/parse.ts

@@ -7,31 +7,22 @@ export const parseCmd = `## parse
 ---
 ### Description
 
-The \`parse\` command parses a text field using a regular expression and append
-the result to the search result.
+Use the \`parse\` command to extract information from a text field using a regular expression and add it to the search result.
 
 ### Syntax
 
 parse <field> <regular-expression>
 
-- field: mandatory. The field must be a text field.
-- regular-expression: mandatory. The regular expression used to extract new
-fields from given text field. If a new field name already exists, it will
-replace the original field.
+- \`field\`: Required. Must be a text field.
+- \`regular-expression\`: Required. The regular expression to extract new fields from a text field. It replaces the original field if a new field name exists.
 
-### Regular Expression
+### Regular expression
 
-The regular expression is used to match the whole text field of each document
-with Java regex engine. Each named capture group in the expression will become
-a new \`STRING\` field.
+Use the Java regular expression engine to match the entire text field of each document. Each named capture group in the expression will be converted to a new \`string\` field.
 
-### Example 1: Create the new field
+#### Example 1: Create a new field
 
-The example shows how to create new field \`host\` for each document. \`host\`
-will be the host name after \`@\` in \`email\` field. Parsing a null field will
-return an empty string.
-
-PPL query:
+The following PPL query example shows how to create new field \`host\` for each document. \`host\` becomes the host name after the at symbol (\`@\`) in the \`email\` field. Parsing a null field returns an empty string.
 
     os> source=accounts | parse email '.+@(?<host>.+)' | fields email, host ;
     fetched rows / total rows = 4/4
@@ -44,12 +35,9 @@ PPL query:
     | daleadams@boink.com   | boink.com  |
     +-----------------------+------------+
 
-### Example 2: Override the existing field
-
-The example shows how to override the existing \`address\` field with street
-number removed.
+#### Example 2: Override an existing field
 
-PPL query:
+The following PPL query example shows how to override the existing \`address\` field while excluding the street number.
 
     os> source=accounts | parse address '\\d+ (?<address>.+)' | fields address ;
     fetched rows / total rows = 4/4
@@ -62,12 +50,9 @@ PPL query:
     | Hutchinson Court |
     +------------------+
 
-### Example 3: Filter and sort by casted parsed field
+#### Example 3: Filter and sort by casted-parsed field
 
-The example shows how to sort street numbers that are higher than 500 in
-\`address\` field.
-
-PPL query:
+The following PPL query example shows how to sort street numbers that are greater than 500 in the \`address\` field.
 
     os> source=accounts | parse address '(?<streetNumber>\d+) (?<street>.+)' | where cast(streetNumber as int) > 500 | sort num(streetNumber) | fields streetNumber, street ;
     fetched rows / total rows = 3/3
@@ -81,30 +66,21 @@ PPL query:
 
 ### Limitation
 
-There are a few limitations with parse command:
-
-- Fields defined by parse cannot be parsed again.
+The following limitations apply:
 
-  The following command will not work:
+- Parsed fields cannpt be parsed again. For example, the following command isn't valid:
 
       source=accounts | parse address '\\d+ (?<street>.+)' | parse street '\\w+ (?<road>\\w+)' ;
 
-- Fields defined by parse cannot be overridden with other commands.
-
-  \`where\` will not match any documents since \`street\` cannot be overridden:
+- Other commands cannot overwrite fields created by parsing. For example, in the following query, \`where\` doesn't match any documents because \`street\` cannot be overridden:
 
       source=accounts | parse address '\\d+ (?<street>.+)' | eval street='1' | where street='1' ;
 
-- The text field used by parse cannot be overridden.
-
-  \`street\` will not be successfully parsed since \`address\` is overridden:
+- The text field that is parsed cannot be overridden. For example, in the following query, \`street\` is not successfully parsed because \`address\` is overridden:
 
       source=accounts | parse address '\\d+ (?<street>.+)' | eval address='1' ;
 
-- Fields defined by parse cannot be filtered/sorted after using them in
-\`stats\` command.
-
-  \`where\` in the following command will not work:
+- Fields created by parsing cannot be filtered or sorted after using them in the \`stats\` command. For example, in the following query, \`where\` isn't valid:
 
       source=accounts | parse email '.+@(?<host>.+)' | stats avg(age) by host | where host=pyrami.com ;
-`;
+`;