[DOC]Revise and edit PPL in-product documentation (#1233) (#1368)

(cherry picked from commit 31b0a94) Signed-off-by: Melissa Vagi <[email protected]> Signed-off-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com> Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com> Co-authored-by: Nathan Bower <[email protected]>
opensearch-project · Jan 18, 2024 · 65f8eaa · 65f8eaa
1 parent 67a5952
commit 65f8eaa
Show file tree

Hide file tree

Showing 21 changed files with 756 additions and 1,326 deletions.
diff --git a/public/components/common/helpers/ppl_docs/commands/dedup.ts b/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\] &lt;field-list&gt; \[keepempty=&lt;bool&gt;\]
 \[consecutive=&lt;bool&gt;\]
 
--   int: optional. The \'dedup\' command retains multiple events for each
-    combination when you specify &lt;int&gt;. The number for &lt;int&gt;
-    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 is \`false\`.
+-   \`int\`: Optional. The \'dedup\' command retains multiple events for each combination when you specify \`&lt;int&gt;\`. The number for \`&lt;int&gt;\` 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\`, keeps 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 example PPL query 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 example PPL query 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 example PPL query 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               | [email protected]   |
     +------------------+-----------------------+
 
-The example show dedup the document by ignore the empty value field.
-
-PPL query:
+The following example PPL query 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               | [email protected]   |
     +------------------+-----------------------+
 
-#### Example 4: Dedup in consecutive document
-
-The example show dedup the consecutive document.
+#### Example 4: Remove duplicate consecutive documents
 
-PPL query:
+The following example PPL query shows how to use \`dedup\` to remove duplicate consecutive documents:
 
     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 domain-specific language (DSL)](https://opensearch.org/docs/latest/query-dsl/index/). It is only run on the coordinating node.
+`;
diff --git a/public/components/common/helpers/ppl_docs/commands/eval.ts b/public/components/common/helpers/ppl_docs/commands/eval.ts
@@ -8,26 +8,21 @@ 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 &lt;field&gt;=&lt;expression&gt; \[","
 &lt;field&gt;=&lt;expression&gt; \]...
 
--   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 value 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.
+The following example PPL query shows how to use \`eval\` to create a new field for each document. In this example, the new field is \`doubleAge\`.
 
-PPL query:
-
-    os> source=accounts | eval doubleAge = age * 2 | fields age, doubleAge ;
+    os> source=accounts | eval doubleAge = age * 2 | fields age, doubleAge;
     fetched rows / total rows = 4/4
     +-------+-------------+
     | age   | doubleAge   |
@@ -38,13 +33,11 @@ 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 example PPL query 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 ;
+    os> source=accounts | eval age = age + 1 | fields age;
     fetched rows / total rows = 4/4
     +-------+
     | age   |
@@ -55,15 +48,11 @@ 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 example PPL query shows how to use \`eval\` to create a new field based on the fields defined in the \`eval\` expression. In this example, the new field \`ddAge\` is the evaluation result of the \`doubleAge\` field multiplied by 2. \`doubleAge\` is defined in the \`eval\` command.
 
-    os> source=accounts | eval doubleAge = age * 2, ddAge = doubleAge * 2 | fields age, doubleAge, ddAge ;
+    os> source=accounts | eval doubleAge = age * 2, ddAge = doubleAge * 2 | fields age, doubleAge, ddAge;
     fetched rows / total rows = 4/4
     +-------+-------------+---------+
     | age   | doubleAge   | ddAge   |
@@ -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 domain-specific language (DSL)](https://opensearch.org/docs/latest/query-dsl/index/). It is only run on the coordinating node.
+`;
diff --git a/public/components/common/helpers/ppl_docs/commands/fields.ts b/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 in or excluded from the search results.
 
 ### Syntax
 
 fields \[+\|-\] &lt;field-list&gt;
 
--   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 is \`+\`.
 
-### 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 example PPL query 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,13 +31,11 @@ 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 example PPL query shows how to remove the \`account\_number\` field from the search results:
 
-    os> source=accounts | fields account_number, firstname, lastname | fields - account_number ;
+    os> source=accounts | fields account_number, firstname, lastname | fields - account_number;
     fetched rows / total rows = 4/4
     +-------------+------------+
     | firstname   | lastname   |
@@ -52,4 +45,4 @@ PPL query:
     | Nanette     | Bates      |
     | Dale        | Adams      |
     +-------------+------------+
-`;
+`;
diff --git a/public/components/common/helpers/ppl_docs/commands/head.ts b/public/components/common/helpers/ppl_docs/commands/head.ts
@@ -8,20 +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 return. Default is 10.
 
-### Example 1: Get first 10 results
+#### Example 1: Get the first 10 results
 
-The example show first 10 results from accounts index.
-
-PPL query:
+The following example PPL query shows how to use \`head\` to return the first 10 search results:
 
     os> source=accounts | fields firstname, age | head;
     fetched rows / total rows = 10/10
@@ -40,11 +37,9 @@ PPL query:
     | Fulton        | 23        |
     +---------------+-----------+
 
-### Example 2: Get first N results
-
-The example show first N results from accounts index.
+#### Example 2: Get the first N results
 
-PPL query:
+The following example PPL query shows how to use \`head\` to get a specified number of search results. In this example, N is equal to 3: 
 
     os> source=accounts | fields firstname, age | head 3;
     fetched rows / total rows = 3/3
@@ -57,5 +52,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 domain-specific language (DSL)](https://opensearch.org/docs/latest/query-dsl/index/). It is only run on the coordinating node.
+`;