Address the PR comments

Signed-off-by: Srikanth Padakanti <[email protected]>

Author: Srikanth Padakanti

core/src/main/java/org/opensearch/sql/calcite/CalciteRelNodeVisitor.java

@@ -1556,11 +1556,16 @@ public RelNode visitMvExpand(MvExpand node, CalcitePlanContext context) {
     Field arrayField = node.getField();
     RexInputRef arrayFieldRex = (RexInputRef) rexVisitor.analyze(arrayField, context);
 
-    buildMvExpandRelNode(arrayFieldRex, arrayField.getField().toString(), null, context);
+    // buildMvExpandRelNode(arrayFieldRex, arrayField.getField().toString(), null, context);
 
-    if (node.getLimit() != null) {
-      context.relBuilder.limit(0, node.getLimit());
-    }
+    // pass the per-document limit into the builder so it can be applied inside the UNNEST inner
+    // query
+    buildMvExpandRelNode(
+        arrayFieldRex, arrayField.getField().toString(), null, node.getLimit(), context);
+
+    //    if (node.getLimit() != null) {
+    //      context.relBuilder.limit(0, node.getLimit());
+    //    }
     return context.relBuilder.peek();
   }
 
@@ -3083,16 +3088,17 @@ private void buildUnnestForLeft(
       String alias,
       Holder<RexCorrelVariable> correlVariable,
       RexNode correlArrayFieldAccess,
+      Integer mvExpandLimit,
       CalcitePlanContext context) {
 
-    // Build right node: one-row -> project(correlated access) -> uncollect
-    RelNode rightNode =
-        context
-            .relBuilder
-            .push(LogicalValues.createOneRow(context.relBuilder.getCluster()))
-            .project(List.of(correlArrayFieldAccess), List.of(arrayFieldName))
-            .uncollect(List.of(), false)
-            .build();
+    RelBuilder rb = context.relBuilder;
+    rb.push(LogicalValues.createOneRow(rb.getCluster()))
+        .project(List.of(correlArrayFieldAccess), List.of(arrayFieldName));
+    // apply per-document limit into the inner SELECT if provided
+    if (mvExpandLimit != null && mvExpandLimit > 0) {
+      rb.limit(0, mvExpandLimit);
+    }
+    RelNode rightNode = rb.uncollect(List.of(), false).build();
 
     // Compute required column ref against leftBuilt's row type (robust)
     RexNode requiredColumnRef =
@@ -3155,11 +3161,16 @@ private void buildExpandRelNode(
         alias,
         correlVariable,
         correlArrayFieldAccess,
+        null,
         context);
   }
 
   private void buildMvExpandRelNode(
-      RexInputRef arrayFieldRex, String arrayFieldName, String alias, CalcitePlanContext context) {
+      RexInputRef arrayFieldRex,
+      String arrayFieldName,
+      String alias,
+      Integer mvExpandLimit,
+      CalcitePlanContext context) {
 
     // Capture left node and its schema BEFORE calling build()
     RelNode leftNode = context.relBuilder.peek();
@@ -3192,6 +3203,7 @@ private void buildMvExpandRelNode(
         alias,
         correlVariable,
         correlArrayFieldAccess,
+        mvExpandLimit,
         context);
   }
 

docs/user/ppl/cmd/mvexpand.rst

@@ -20,10 +20,6 @@ Description
 - Handles empty, null, and non-array fields gracefully.
 - Works as a streaming/distributable command for performance and scalability.
 
-Version
-=======
-3.3.0
-
 Syntax
 ======
 mvexpand <field> [limit=<int>]
@@ -48,6 +44,10 @@ Limitations
 - For empty or null arrays, no rows are returned.
 - Large arrays may be subject to resource/memory limits; exceeding them results in an error or warning.
 
+Output ordering and default limit
+--------------------------------
+If no `limit` is specified, mvexpand expands all elements in the array (there is no implicit per-document cap). Elements are emitted in the same order they appear in the array (array iteration order). If the underlying field does not provide a defined order, the output order is undefined. Use `limit` to bound the number of expanded rows per document and to avoid resource issues on very large arrays.
+
 Examples and Edge Cases
 =======================
 
@@ -156,18 +156,18 @@ Output (example)::
 
 Example 5: Large Arrays and Memory Limits
 ----------------------------------------
-If an array exceeds configured memory/resource limits, mvexpand returns an error.
+If an array is very large it can trigger engine/cluster resource limits (memory, circuit-breakers, or query execution limits). Note: this behavior is enforced by the underlying engine and cluster settings, not by a mvexpand-specific configuration.
 
-Input document::
-
-    { "ids": [1, 2, ..., 100000] }
+To avoid failures when expanding large arrays:
+- Use the `limit` parameter to restrict the number of expanded values per document (for example: `mvexpand field limit=1000`).
+- Filter or narrow the input before expanding (use `where` and `fields` to reduce rows and columns).
+- Tune cluster and SQL/PPL execution settings (circuit breakers, query size/timeouts, memory limits) appropriate for your deployment.
 
 PPL query::
 
     source=docs | mvexpand ids
 
 Output (example)::
-
     Error: Memory/resource limit exceeded while expanding field 'ids'. Please reduce the array size or specify a limit.
 
 Example 6: Multiple Fields (Limitation)

ppl/src/main/antlr/OpenSearchPPLParser.g4

@@ -491,7 +491,7 @@ expandCommand
     ;
 
 mvexpandCommand
-    : MVEXPAND fieldExpression (LIMIT '=' INTEGER_LITERAL)?
+    : MVEXPAND fieldExpression (LIMIT EQUAL INTEGER_LITERAL)?
     ;
 
 flattenCommand