Ppl help command

integ-test/src/integration/scala/org/opensearch/flint/spark/ppl/FlintSparkPPLHelpCommandITSuite.scala

@@ -0,0 +1,87 @@
+/*
+ * Copyright OpenSearch Contributors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package org.opensearch.flint.spark.ppl
+
+import org.opensearch.flint.spark.PrintLiteralCommandDescriptionLogicalPlan
+import org.opensearch.sql.ppl.parser.AstCommandDescriptionVisitor
+
+import org.apache.spark.sql.{QueryTest, Row}
+import org.apache.spark.sql.catalyst.TableIdentifier
+import org.apache.spark.sql.catalyst.analysis.{UnresolvedAttribute, UnresolvedRelation, UnresolvedStar}
+import org.apache.spark.sql.catalyst.expressions.{Ascending, Literal, SortOrder}
+import org.apache.spark.sql.catalyst.plans.logical._
+import org.apache.spark.sql.execution.command.DescribeTableCommand
+import org.apache.spark.sql.streaming.StreamTest
+
+class FlintSparkPPLHelpCommandITSuite
+    extends QueryTest
+    with LogicalPlanTestUtils
+    with FlintPPLSuite
+    with StreamTest {
+
+  override def beforeAll(): Unit = {
+    super.beforeAll()
+  }
+
+  protected override def afterEach(): Unit = {
+    super.afterEach()
+    // Stop all streaming jobs if any
+    spark.streams.active.foreach { job =>
+      job.stop()
+      job.awaitTermination()
+    }
+  }
+
+  ingore("search -help command") {
+    val helpText =
+      """
+        |SEARCH Command:
+        |
+        |Syntax:
+        |   (SEARCH)? fromClause
+        |   | (SEARCH)? fromClause logicalExpression
+        |   | (SEARCH)? logicalExpression fromClause
+        |
+        |Description:
+        |The SEARCH command is used to retrieve data from a specified source. It can be used with or without additional filters.
+        |- You can specify the data source using the FROM clause.
+        |- You can add filters using logical expressions.
+        |- The order of FROM clause and logical expression can be interchanged.
+""".stripMargin.trim
+
+    val pplParser = new PPLSyntaxParser()
+    val frame = sql(s"""
+           search -help
+           """.stripMargin)
+
+    // Retrieve the results
+    val results: Array[Row] = frame.collect()
+    // Define the expected results
+    val expectedResults: Array[Row] = Array(
+      Row(AstCommandDescriptionVisitor.describeCommand(helpText, pplParser.getParserVersion())))
+
+    // Extract values from rows, assuming single column
+    val actualValues = results.map(_.getAs[String](0))
+    val expectedValues = expectedResults.map(_.getAs[String](0))
+
+    assert(
+      actualValues.sameElements(expectedValues),
+      s"""
+         |Expected: ${expectedValues.mkString(", ")}
+         |Actual: ${actualValues.mkString(", ")}
+         |""".stripMargin)
+
+    // Retrieve the logical plan
+    val logicalPlan: LogicalPlan = frame.queryExecution.logical
+    // Expected plan should match the produced custom logical plan
+    val expectedPlan: LogicalPlan = PrintLiteralCommandDescriptionLogicalPlan(
+      AstCommandDescriptionVisitor.describeCommand(helpText, pplParser.getParserVersion()))
+
+    // Compare the plans
+    comparePlans(expectedPlan, logicalPlan, false)
+  }
+
+}

ppl-spark-integration/src/main/antlr4/OpenSearchPPLLexer.g4

@@ -6,6 +6,20 @@
 
 lexer grammar OpenSearchPPLLexer;
 
+@lexer::members {
+    public static final String GRAMMAR_VERSION = "1.0.0";
+    public static final String LAST_UPDATED = "2024-09-18";
+
+    public static String getGrammarVersion() {
+        return GRAMMAR_VERSION;
+    }
+
+    public static String getLastUpdated() {
+        return LAST_UPDATED;
+    }
+}
+
+
 channels { WHITESPACE, ERRORCHANNEL }
 
 
@@ -80,6 +94,9 @@ WITH:                               'WITH';
 // CLAUSE KEYWORDS
 SORTBY:                             'SORTBY';
 
+// HELP COMMAND
+HELP:                               'HELP';
+
 // FIELD KEYWORDS
 AUTO:                               'AUTO';
 STR:                                'STR';

ppl-spark-integration/src/main/antlr4/OpenSearchPPLParser.g4

@@ -5,6 +5,18 @@
 
 parser grammar OpenSearchPPLParser;
 
+@parser::members {
+    public static final String GRAMMAR_VERSION = "1.0.0";
+    public static final String LAST_UPDATED = "2024-09-18";
+
+    public static String getGrammarVersion() {
+        return GRAMMAR_VERSION;
+    }
+
+    public static String getLastUpdated() {
+        return LAST_UPDATED;
+    }
+}
 
 options { tokenVocab = OpenSearchPPLLexer; }
 root
@@ -32,6 +44,7 @@ subSearch
 pplCommands
    : searchCommand
    | describeCommand
+   | helpCommand
    ;
 
 commands
@@ -58,10 +71,16 @@ searchCommand
    : (SEARCH)? fromClause                       # searchFrom
    | (SEARCH)? fromClause logicalExpression     # searchFromFilter
    | (SEARCH)? logicalExpression fromClause     # searchFilterFrom
+   | (SEARCH)? HELP                             # searchHelp
    ;
 
 describeCommand
-   : DESCRIBE tableSourceClause
+   : DESCRIBE tableSourceClause                 # describeClause
+   | DESCRIBE HELP                              # describeHelp
+   ;
+
+helpCommand
+   : HELP commandNames                          # helpCommandName
    ;
 
 explainCommand
@@ -81,11 +100,13 @@ showDataSourcesCommand
     ;
 
 whereCommand
-    : WHERE logicalExpression
+    : WHERE logicalExpression                   # whereClause         
+    | WHERE HELP                                # whereHelp
     ;
 
 correlateCommand
-    : CORRELATE correlationType FIELDS LT_PRTHS fieldList RT_PRTHS (scopeClause)? mappingList
+    : CORRELATE correlationType FIELDS LT_PRTHS fieldList RT_PRTHS (scopeClause)? mappingList       # correlateClause
+    | CORRELATE HELP                                                                                # correlateHelp
     ;
 
 correlationType
@@ -107,51 +128,63 @@ mappingClause
     ;
 
 fieldsCommand
-   : FIELDS (PLUS | MINUS)? fieldList
+   : FIELDS (PLUS | MINUS)? fieldList           # fieldsClause
+   | FIELDS HELP                                # fieldsHelp
    ;
 
 renameCommand
-   : RENAME renameClasue (COMMA renameClasue)*
+   : RENAME renameClasue (COMMA renameClasue)*  # renameClause    
+   | RENAME HELP                                # renameHelp
    ;
 
 statsCommand
-   : STATS (PARTITIONS EQUAL partitions = integerLiteral)? (ALLNUM EQUAL allnum = booleanLiteral)? (DELIM EQUAL delim = stringLiteral)? statsAggTerm (COMMA statsAggTerm)* (statsByClause)? (DEDUP_SPLITVALUES EQUAL dedupsplit = booleanLiteral)?
+   : STATS (PARTITIONS EQUAL partitions = integerLiteral)? (ALLNUM EQUAL allnum = booleanLiteral)? (DELIM EQUAL delim = stringLiteral)? statsAggTerm (COMMA statsAggTerm)* (statsByClause)? (DEDUP_SPLITVALUES EQUAL dedupsplit = booleanLiteral)?  # statsClause
+   | STATS HELP                                                                                                                                                                                                                                     # statsHelp   
    ;
 
 dedupCommand
-   : DEDUP (number = integerLiteral)? fieldList (KEEPEMPTY EQUAL keepempty = booleanLiteral)? (CONSECUTIVE EQUAL consecutive = booleanLiteral)?
+   : DEDUP (number = integerLiteral)? fieldList (KEEPEMPTY EQUAL keepempty = booleanLiteral)? (CONSECUTIVE EQUAL consecutive = booleanLiteral)?    # dedupClause
+   | DEDUP HELP                                                                                                                                    # dedupHelp 
    ;
 
 sortCommand
-   : SORT sortbyClause
+   : SORT sortbyClause                                                                                                                             # sortClause
+   | SORT HELP                                                                                                                                     # sortHelp 
    ;
 
 evalCommand
-   : EVAL evalClause (COMMA evalClause)*
+   : EVAL evalClause (COMMA evalClause)*                                                                                                           # evalCommandClause 
+   | EVAL HELP                                                                                                                                     # evalHelp 
    ;
 
 headCommand
-   : HEAD (number = integerLiteral)? (FROM from = integerLiteral)?
+   : HEAD (number = integerLiteral)? (FROM from = integerLiteral)?                                                                                 # headClause 
+   | HEAD HELP                                                                                                                                     # headHelp 
    ;
 
-topCommand
-   : TOP (number = integerLiteral)? fieldList (byClause)?
+topCommand 
+   : TOP (number = integerLiteral)? fieldList (byClause)?                                                                                             # topClause                                                           
+   | TOP HELP                                                                                                                                      # topHelp                        
    ;
 
-rareCommand
-   : RARE fieldList (byClause)?
+rareCommand                                                                                                                                         
+   : RARE fieldList (byClause)?                                                                                                                    # rareClause
+   | RARE HELP                                                                                                                                     # rareHelp 
    ;
 
 grokCommand
-   : GROK (source_field = expression) (pattern = stringLiteral)
+   : GROK (source_field = expression) (pattern = stringLiteral)                                                                                    # grokClause 
+   | GROK HELP                                                                                                                                     # grokHelp                                                                                                                                   
    ;
 
 parseCommand
-   : PARSE (source_field = expression) (pattern = stringLiteral)
+   : PARSE (source_field = expression) (pattern = stringLiteral)                                                                                   # parseClause 
+   | PARSE HELP                                                                                                                                    # parseHelp     
    ;
 
 patternsCommand
-   : PATTERNS (patternsParameter)* (source_field = expression)
+   : PATTERNS (patternsParameter)* (source_field = expression)                                                                                     # patternsClause 
+   | PATTERNS HELP                                                                                                                                 # patternsHelp 
    ;
 
 patternsParameter
@@ -166,7 +199,8 @@ patternsMethod
 
 // lookup
 lookupCommand
-   : LOOKUP tableSource lookupMappingList ((APPEND | REPLACE) outputCandidateList)?
+   : LOOKUP tableSource lookupMappingList ((APPEND | REPLACE) outputCandidateList)?                                                                # lookupClause
+   | LOOKUP HELP                                                                                                                                   # lookupHelp 
    ;
 
 lookupMappingList
@@ -257,7 +291,8 @@ tableSourceClause
 
 // join
 joinCommand
-   : (joinType) JOIN sideAlias joinHintList? joinCriteria? right = tableSource
+   : (joinType) JOIN sideAlias joinHintList? joinCriteria? right = tableSource                                          # joinClause                           
+   | JOIN HELP                                                                                                          # joinHelp 
    ;
 
 joinType
@@ -306,7 +341,7 @@ bySpanClause
    ;
 
 spanClause
-   : SPAN LT_PRTHS fieldExpression COMMA value = literalValue (unit = timespanUnit)? RT_PRTHS
+   : SPAN LT_PRTHS fieldExpression COMMA value = literalValue (unit = timespanUnit)? RT_PRTHS                           
    ;
 
 sortbyClause
@@ -342,6 +377,7 @@ statsFunctionName
 
 takeAggFunction
    : TAKE LT_PRTHS fieldExpression (COMMA size = integerLiteral)? RT_PRTHS
+   | TAKE HELP                       
    ;
 
 percentileAggFunction
@@ -401,7 +437,7 @@ booleanExpression
    ;
 
  isEmptyExpression
-   : (ISEMPTY | ISBLANK) LT_PRTHS functionArg RT_PRTHS
+   : (ISEMPTY | ISBLANK)  LT_PRTHS functionArg RT_PRTHS
    ;
 
  caseFunction
@@ -943,8 +979,11 @@ keywordsCanBeId
    | textFunctionName
    | mathematicalFunctionName
    | positionFunctionName
-   // commands
-   | SEARCH
+   | commandNames 
+   ; 
+
+commandNames
+   : SEARCH // commands
    | DESCRIBE
    | SHOW
    | FROM

ppl-spark-integration/src/main/java/org/opensearch/sql/ast/tree/DescribeCommand.java

@@ -0,0 +1,24 @@
+/*
+ * Copyright OpenSearch Contributors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package org.opensearch.sql.ast.tree;
+
+import java.util.Collections;
+
+/**
+ * Extend Projection to describe the command itself
+ */
+public class DescribeCommand extends Project{
+    private String commandDescription;
+
+    public DescribeCommand(String commandDescription) {
+        super(Collections.emptyList());
+        this.commandDescription = commandDescription;
+    }
+
+    public String getDescription() {
+        return commandDescription;
+    }
+}

ppl-spark-integration/src/main/java/org/opensearch/sql/ast/tree/Help.java

@@ -0,0 +1,19 @@
+/*
+ * Copyright OpenSearch Contributors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package org.opensearch.sql.ast.tree;
+
+public interface Help {
+    /**
+     * command description (help)
+     * @return
+     */
+    String describe();
+
+    /**
+     *  command samples (help)
+     * @return
+     */
+    String sample();
+}