Query: Adds FIRST and LAST Scalar Expressions (#3629)

* Add FIRST and LAST objects and update visitors

* add FIRST LAST evaluation and update offline engine visitors

* Add FIRST and LAST to parser

* update another visitor

* Fix typo

* fix typo

* added new tests and baselines

* cleaning

* cleaning

---------

Co-authored-by: neildsh <35383880+neildsh@users.noreply.github.com>
Co-authored-by: Matias Quaranta <ealsur@users.noreply.github.com>

Microsoft.Azure.Cosmos/src/Query/Core/Parser/CstToAstVisitor.cs

@@ -568,6 +568,16 @@ public override SqlObject VisitExistsScalarExpression([NotNull] sqlParser.Exists
             return SqlExistsScalarExpression.Create(subquery);
         }
 
+        public override SqlObject VisitFirstScalarExpression([NotNull] sqlParser.FirstScalarExpressionContext context)
+        {
+            Contract.Requires(context != null);
+            // K_FIRST '(' sql_query ')'
+            Contract.Requires(context.ChildCount == 4);
+
+            SqlQuery subquery = (SqlQuery)this.Visit(context.children[2]);
+            return SqlFirstScalarExpression.Create(subquery);
+        }
+
         public override SqlObject VisitFunctionCallScalarExpression([NotNull] sqlParser.FunctionCallScalarExpressionContext context)
         {
             Contract.Requires(context != null);
@@ -627,6 +637,16 @@ public override SqlObject VisitIn_scalar_expression([NotNull] sqlParser.In_scala
             return SqlInScalarExpression.Create(needle, not, searchList.ToImmutableArray());
         }
 
+        public override SqlObject VisitLastScalarExpression([NotNull] sqlParser.LastScalarExpressionContext context)
+        {
+            Contract.Requires(context != null);
+            // K_LAST '(' sql_query ')'
+            Contract.Requires(context.ChildCount == 4);
+
+            SqlQuery subquery = (SqlQuery)this.Visit(context.children[2]);
+            return SqlLastScalarExpression.Create(subquery);
+        }
+
         public override SqlObject VisitLike_scalar_expression([NotNull] sqlParser.Like_scalar_expressionContext context)
         {
             Contract.Requires(context != null);

Microsoft.Azure.Cosmos/src/Query/Core/Parser/IsqlListener.cs

@@ -562,6 +562,18 @@ internal interface IsqlListener : IParseTreeListener {
 	/// <param name="context">The parse tree.</param>
 	void ExitObjectCreateScalarExpression([NotNull] sqlParser.ObjectCreateScalarExpressionContext context);
 	/// <summary>
+	/// Enter a parse tree produced by the <c>FirstScalarExpression</c>
+	/// labeled alternative in <see cref="sqlParser.primary_expression"/>.
+	/// </summary>
+	/// <param name="context">The parse tree.</param>
+	void EnterFirstScalarExpression([NotNull] sqlParser.FirstScalarExpressionContext context);
+	/// <summary>
+	/// Exit a parse tree produced by the <c>FirstScalarExpression</c>
+	/// labeled alternative in <see cref="sqlParser.primary_expression"/>.
+	/// </summary>
+	/// <param name="context">The parse tree.</param>
+	void ExitFirstScalarExpression([NotNull] sqlParser.FirstScalarExpressionContext context);
+	/// <summary>
 	/// Enter a parse tree produced by the <c>ArrayCreateScalarExpression</c>
 	/// labeled alternative in <see cref="sqlParser.primary_expression"/>.
 	/// </summary>
@@ -670,6 +682,18 @@ internal interface IsqlListener : IParseTreeListener {
 	/// <param name="context">The parse tree.</param>
 	void ExitArrayScalarExpression([NotNull] sqlParser.ArrayScalarExpressionContext context);
 	/// <summary>
+	/// Enter a parse tree produced by the <c>LastScalarExpression</c>
+	/// labeled alternative in <see cref="sqlParser.primary_expression"/>.
+	/// </summary>
+	/// <param name="context">The parse tree.</param>
+	void EnterLastScalarExpression([NotNull] sqlParser.LastScalarExpressionContext context);
+	/// <summary>
+	/// Exit a parse tree produced by the <c>LastScalarExpression</c>
+	/// labeled alternative in <see cref="sqlParser.primary_expression"/>.
+	/// </summary>
+	/// <param name="context">The parse tree.</param>
+	void ExitLastScalarExpression([NotNull] sqlParser.LastScalarExpressionContext context);
+	/// <summary>
 	/// Enter a parse tree produced by the <c>PropertyRefScalarExpressionRecursive</c>
 	/// labeled alternative in <see cref="sqlParser.primary_expression"/>.
 	/// </summary>

Microsoft.Azure.Cosmos/src/Query/Core/Parser/IsqlVisitor.cs

@@ -347,6 +347,13 @@ internal interface IsqlVisitor<Result> : IParseTreeVisitor<Result> {
 	/// <return>The visitor result.</return>
 	Result VisitObjectCreateScalarExpression([NotNull] sqlParser.ObjectCreateScalarExpressionContext context);
 	/// <summary>
+	/// Visit a parse tree produced by the <c>FirstScalarExpression</c>
+	/// labeled alternative in <see cref="sqlParser.primary_expression"/>.
+	/// </summary>
+	/// <param name="context">The parse tree.</param>
+	/// <return>The visitor result.</return>
+	Result VisitFirstScalarExpression([NotNull] sqlParser.FirstScalarExpressionContext context);
+	/// <summary>
 	/// Visit a parse tree produced by the <c>ArrayCreateScalarExpression</c>
 	/// labeled alternative in <see cref="sqlParser.primary_expression"/>.
 	/// </summary>
@@ -410,6 +417,13 @@ internal interface IsqlVisitor<Result> : IParseTreeVisitor<Result> {
 	/// <return>The visitor result.</return>
 	Result VisitArrayScalarExpression([NotNull] sqlParser.ArrayScalarExpressionContext context);
 	/// <summary>
+	/// Visit a parse tree produced by the <c>LastScalarExpression</c>
+	/// labeled alternative in <see cref="sqlParser.primary_expression"/>.
+	/// </summary>
+	/// <param name="context">The parse tree.</param>
+	/// <return>The visitor result.</return>
+	Result VisitLastScalarExpression([NotNull] sqlParser.LastScalarExpressionContext context);
+	/// <summary>
 	/// Visit a parse tree produced by the <c>PropertyRefScalarExpressionRecursive</c>
 	/// labeled alternative in <see cref="sqlParser.primary_expression"/>.
 	/// </summary>

Microsoft.Azure.Cosmos/src/Query/Core/Parser/sql.g4

@@ -173,6 +173,8 @@ primary_expression
     | K_EXISTS '(' sql_query ')' #ExistsScalarExpression
     | K_ARRAY '(' sql_query ')' #ArrayScalarExpression
     | K_ALL '(' sql_query ')' #AllScalarExpression
+    | K_FIRST '(' sql_query ')' #FirstScalarExpression
+    | K_LAST '(' sql_query ')' #LastScalarExpression
     | function_call_scalar_expression #FunctionCallScalarExpression
     ;
 
@@ -191,6 +193,8 @@ object_property : STRING_LITERAL ':' scalar_expression ;
 identifier
     : LEX_IDENTIFIER
     | K_ALL
+    | K_FIRST
+    | K_LAST
     ;
 /*--------------------------------------------------------------------------------*/
 
@@ -208,11 +212,13 @@ K_DESC : D E S C;
 K_DISTINCT : D I S T I N C T;
 K_ESCAPE: E S C A P E;
 K_EXISTS : E X I S T S;
+K_FIRST : F I R S T;
 K_FALSE : 'false';
 K_FROM : F R O M;
 K_GROUP : G R O U P;
 K_IN : I N ;
 K_JOIN : J O I N;
+K_LAST : L A S T;
 K_LEFT : L E F T;
 K_LIKE : L I K E;
 K_LIMIT : L I M I T;

Microsoft.Azure.Cosmos/src/Query/Core/Parser/sqlBaseListener.cs

@@ -666,6 +666,20 @@ public virtual void EnterObjectCreateScalarExpression([NotNull] sqlParser.Object
 	/// <param name="context">The parse tree.</param>
 	public virtual void ExitObjectCreateScalarExpression([NotNull] sqlParser.ObjectCreateScalarExpressionContext context) { }
 	/// <summary>
+	/// Enter a parse tree produced by the <c>FirstScalarExpression</c>
+	/// labeled alternative in <see cref="sqlParser.primary_expression"/>.
+	/// <para>The default implementation does nothing.</para>
+	/// </summary>
+	/// <param name="context">The parse tree.</param>
+	public virtual void EnterFirstScalarExpression([NotNull] sqlParser.FirstScalarExpressionContext context) { }
+	/// <summary>
+	/// Exit a parse tree produced by the <c>FirstScalarExpression</c>
+	/// labeled alternative in <see cref="sqlParser.primary_expression"/>.
+	/// <para>The default implementation does nothing.</para>
+	/// </summary>
+	/// <param name="context">The parse tree.</param>
+	public virtual void ExitFirstScalarExpression([NotNull] sqlParser.FirstScalarExpressionContext context) { }
+	/// <summary>
 	/// Enter a parse tree produced by the <c>ArrayCreateScalarExpression</c>
 	/// labeled alternative in <see cref="sqlParser.primary_expression"/>.
 	/// <para>The default implementation does nothing.</para>
@@ -792,6 +806,20 @@ public virtual void EnterArrayScalarExpression([NotNull] sqlParser.ArrayScalarEx
 	/// <param name="context">The parse tree.</param>
 	public virtual void ExitArrayScalarExpression([NotNull] sqlParser.ArrayScalarExpressionContext context) { }
 	/// <summary>
+	/// Enter a parse tree produced by the <c>LastScalarExpression</c>
+	/// labeled alternative in <see cref="sqlParser.primary_expression"/>.
+	/// <para>The default implementation does nothing.</para>
+	/// </summary>
+	/// <param name="context">The parse tree.</param>
+	public virtual void EnterLastScalarExpression([NotNull] sqlParser.LastScalarExpressionContext context) { }
+	/// <summary>
+	/// Exit a parse tree produced by the <c>LastScalarExpression</c>
+	/// labeled alternative in <see cref="sqlParser.primary_expression"/>.
+	/// <para>The default implementation does nothing.</para>
+	/// </summary>
+	/// <param name="context">The parse tree.</param>
+	public virtual void ExitLastScalarExpression([NotNull] sqlParser.LastScalarExpressionContext context) { }
+	/// <summary>
 	/// Enter a parse tree produced by the <c>PropertyRefScalarExpressionRecursive</c>
 	/// labeled alternative in <see cref="sqlParser.primary_expression"/>.
 	/// <para>The default implementation does nothing.</para>

Microsoft.Azure.Cosmos/src/Query/Core/Parser/sqlBaseVisitor.cs

@@ -549,6 +549,17 @@ internal partial class sqlBaseVisitor<Result> : AbstractParseTreeVisitor<Result>
 	/// <return>The visitor result.</return>
 	public virtual Result VisitObjectCreateScalarExpression([NotNull] sqlParser.ObjectCreateScalarExpressionContext context) { return VisitChildren(context); }
 	/// <summary>
+	/// Visit a parse tree produced by the <c>FirstScalarExpression</c>
+	/// labeled alternative in <see cref="sqlParser.primary_expression"/>.
+	/// <para>
+	/// The default implementation returns the result of calling <see cref="AbstractParseTreeVisitor{Result}.VisitChildren(IRuleNode)"/>
+	/// on <paramref name="context"/>.
+	/// </para>
+	/// </summary>
+	/// <param name="context">The parse tree.</param>
+	/// <return>The visitor result.</return>
+	public virtual Result VisitFirstScalarExpression([NotNull] sqlParser.FirstScalarExpressionContext context) { return VisitChildren(context); }
+	/// <summary>
 	/// Visit a parse tree produced by the <c>ArrayCreateScalarExpression</c>
 	/// labeled alternative in <see cref="sqlParser.primary_expression"/>.
 	/// <para>
@@ -648,6 +659,17 @@ internal partial class sqlBaseVisitor<Result> : AbstractParseTreeVisitor<Result>
 	/// <return>The visitor result.</return>
 	public virtual Result VisitArrayScalarExpression([NotNull] sqlParser.ArrayScalarExpressionContext context) { return VisitChildren(context); }
 	/// <summary>
+	/// Visit a parse tree produced by the <c>LastScalarExpression</c>
+	/// labeled alternative in <see cref="sqlParser.primary_expression"/>.
+	/// <para>
+	/// The default implementation returns the result of calling <see cref="AbstractParseTreeVisitor{Result}.VisitChildren(IRuleNode)"/>
+	/// on <paramref name="context"/>.
+	/// </para>
+	/// </summary>
+	/// <param name="context">The parse tree.</param>
+	/// <return>The visitor result.</return>
+	public virtual Result VisitLastScalarExpression([NotNull] sqlParser.LastScalarExpressionContext context) { return VisitChildren(context); }
+	/// <summary>
 	/// Visit a parse tree produced by the <c>PropertyRefScalarExpressionRecursive</c>
 	/// labeled alternative in <see cref="sqlParser.primary_expression"/>.
 	/// <para>