Adds PError.EXPERIMENTAL, and adds to window parsing/planning

johnedquinn · johnedquinn · commit 17a387f6629b · 2025-08-18T11:45:47.000-07:00
Adds deprecation notices to APIs
diff --git a/partiql-ast/src/main/java/org/partiql/ast/WindowClause.java b/partiql-ast/src/main/java/org/partiql/ast/WindowClause.java
@@ -11,9 +11,11 @@
  * Represents a PartiQL WINDOW clause.
  * @see WindowDefinition
  * @see org.partiql.ast.expr.ExprWindowFunction
+ * @deprecated This feature is experimental and is subject to change.
  */
 @Builder(builderClassName = "Builder")
 @EqualsAndHashCode(callSuper = false)
+@Deprecated
 public final class WindowClause extends AstNode {
 
     @NotNull
diff --git a/partiql-ast/src/main/java/org/partiql/ast/WindowFunctionNullTreatment.java b/partiql-ast/src/main/java/org/partiql/ast/WindowFunctionNullTreatment.java
@@ -9,8 +9,10 @@
 /**
  * The null treatment for window functions.
  * @see WindowFunctionType.LeadOrLag#getNullTreatment()
+ * @deprecated This feature is experimental and is subject to change.
  */
 @EqualsAndHashCode(callSuper = false)
+@Deprecated
 public final class WindowFunctionNullTreatment extends AstEnum {
     /**
      * The RESPECT NULLS variant of the null treatment.
diff --git a/partiql-ast/src/main/java/org/partiql/ast/WindowFunctionType.java b/partiql-ast/src/main/java/org/partiql/ast/WindowFunctionType.java
@@ -12,16 +12,20 @@
 
 /**
  * Represents a window function type.
- * @see ExprWindowFunction#getFunctionType() 
+ * @see ExprWindowFunction#getFunctionType()
+ * @deprecated This feature is experimental and is subject to change.
  */
+@Deprecated
 public abstract class WindowFunctionType extends AstNode {
 
     /**
      * The RANK window function.
      * @see ExprWindowFunction#getFunctionType()
+     * @deprecated This feature is experimental and is subject to change.
      */
     @Builder(builderClassName = "Builder")
     @EqualsAndHashCode(callSuper = false)
+    @Deprecated
     public static final class Rank extends WindowFunctionType {
         private int _type;
 
@@ -71,9 +75,11 @@ public <R, C> R accept(@NotNull AstVisitor<R, C> visitor, C ctx) {
     /**
      * The CUME_DIST window function.
      * @see ExprWindowFunction#getFunctionType()
+     * @deprecated This feature is experimental and is subject to change.
      */
     @Builder(builderClassName = "Builder")
     @EqualsAndHashCode(callSuper = false)
+    @Deprecated
     public static final class CumeDist extends WindowFunctionType {
         /**
          * Constructs a CUME_DIST window function.
@@ -95,9 +101,11 @@ public <R, C> R accept(@NotNull AstVisitor<R, C> visitor, C ctx) {
     /**
      * The ROW_NUMBER window function.
      * @see ExprWindowFunction#getFunctionType()
+     * @deprecated This feature is experimental and is subject to change.
      */
     @Builder(builderClassName = "Builder")
     @EqualsAndHashCode(callSuper = false)
+    @Deprecated
     public static final class RowNumber extends WindowFunctionType {
 
         /**
@@ -122,7 +130,9 @@ public <R, C> R accept(@NotNull AstVisitor<R, C> visitor, C ctx) {
      * @see ExprWindowFunction#getFunctionType()
      * @see Lead
      * @see Lag
+     * @deprecated This feature is experimental and is subject to change.
      */
+    @Deprecated
     public interface LeadOrLag {
         /**
          * Returns the extent of the window function.
@@ -156,9 +166,11 @@ public interface LeadOrLag {
     /**
      * Represents the LEAD window function.
      * @see ExprWindowFunction#getFunctionType()
+     * @deprecated This feature is experimental and is subject to change.
      */
     @Builder(builderClassName = "Builder")
     @EqualsAndHashCode(callSuper = false)
+    @Deprecated
     public static final class Lead extends WindowFunctionType implements LeadOrLag {
         private final Expr extent;
         private final Long offset;
@@ -226,9 +238,11 @@ public <R, C> R accept(@NotNull AstVisitor<R, C> visitor, C ctx) {
     /**
      * Represents the LAG window function.
      * @see ExprWindowFunction#getFunctionType()
+     * @deprecated This feature is experimental and is subject to change.
      */
     @Builder(builderClassName = "Builder")
     @EqualsAndHashCode(callSuper = false)
+    @Deprecated
     public static final class Lag extends WindowFunctionType implements LeadOrLag {
         private final Expr extent;
         private final Long offset;
diff --git a/partiql-ast/src/main/java/org/partiql/ast/WindowPartition.java b/partiql-ast/src/main/java/org/partiql/ast/WindowPartition.java
@@ -11,14 +11,18 @@
  * Represents a partition specified by a window specification.
  * @see Name
  * @see WindowSpecification#getPartitionClause()
+ * @deprecated This feature is experimental and is subject to change.
  */
+@Deprecated
 public abstract class WindowPartition extends AstNode {
     /**
      * Represents a partition specified by a name.
      * @see WindowSpecification#getPartitionClause()
+     * @deprecated This feature is experimental and is subject to change.
      */
     @Builder(builderClassName = "Builder")
     @EqualsAndHashCode(callSuper = false)
+    @Deprecated
     public static final class Name extends WindowPartition {
         private final Identifier columnReference;
 
diff --git a/partiql-ast/src/main/java/org/partiql/ast/WindowSpecification.java b/partiql-ast/src/main/java/org/partiql/ast/WindowSpecification.java
@@ -11,9 +11,11 @@
 /**
  * Represents a window specification or a window reference.
  * @see WindowClause.WindowDefinition#getSpecification()
+ * @deprecated This feature is experimental and is subject to change.
  */
 @Builder(builderClassName = "Builder")
 @EqualsAndHashCode(callSuper = false)
+@Deprecated
 public final class WindowSpecification extends AstNode {
     // TODO: In the future: @Nullable private final WindowFrameClause frameClause;
 
diff --git a/partiql-cli/src/main/kotlin/org/partiql/cli/ErrorCodeString.kt b/partiql-cli/src/main/kotlin/org/partiql/cli/ErrorCodeString.kt
@@ -28,5 +28,6 @@ enum class ErrorCodeString(val code: Int) {
     NUMERIC_VALUE_OUT_OF_RANGE(PError.NUMERIC_VALUE_OUT_OF_RANGE),
     INVALID_CHAR_VALUE_FOR_CAST(PError.INVALID_CHAR_VALUE_FOR_CAST),
     DIVISION_BY_ZERO(PError.DIVISION_BY_ZERO),
-    DEGREE_VIOLATION_SCALAR_SUBQUERY(PError.DEGREE_VIOLATION_SCALAR_SUBQUERY)
+    DEGREE_VIOLATION_SCALAR_SUBQUERY(PError.DEGREE_VIOLATION_SCALAR_SUBQUERY),
+    EXPERIMENTAL(PError.EXPERIMENTAL),
 }
diff --git a/partiql-cli/src/main/kotlin/org/partiql/cli/pipeline/ErrorMessageFormatter.kt b/partiql-cli/src/main/kotlin/org/partiql/cli/pipeline/ErrorMessageFormatter.kt
@@ -35,6 +35,7 @@ object ErrorMessageFormatter {
             ErrorCodeString.DIVISION_BY_ZERO -> divisionByZero(error)
             ErrorCodeString.TYPE_UNEXPECTED -> typeUnexpected(error)
             ErrorCodeString.DEGREE_VIOLATION_SCALAR_SUBQUERY -> degreeViolationScalarSubquery(error)
+            ErrorCodeString.EXPERIMENTAL -> experimental(error)
             ErrorCodeString.ALL -> "INTERNAL ERROR: This should never have occurred."
             null -> "Unrecognized error code received: ${error.code()}"
         }
@@ -139,6 +140,15 @@ object ErrorMessageFormatter {
         return "Degree of scalar subquery must be 1 (one).$actualTypeStr"
     }
 
+    /**
+     * @see PError.EXPERIMENTAL
+     */
+    private fun experimental(error: PError): String {
+        val actualType = error.getOrNull("FEATURE", String::class.java)
+        val actualTypeStr = prepare(actualType.toString(), " (", ")")
+        return "Feature$actualTypeStr is experimental and is subject to change."
+    }
+
     /**
      * @see PError.TYPE_UNEXPECTED
      */
diff --git a/partiql-parser/src/main/kotlin/org/partiql/parser/internal/PErrors.kt b/partiql-parser/src/main/kotlin/org/partiql/parser/internal/PErrors.kt
@@ -1,5 +1,6 @@
 package org.partiql.parser.internal
 
+import org.antlr.v4.runtime.ParserRuleContext
 import org.partiql.spi.SourceLocation
 import org.partiql.spi.errors.PError
 import org.partiql.spi.errors.PErrorKind
@@ -51,4 +52,33 @@ internal object PErrors {
             )
         )
     }
+
+    /**
+     * @return an error representing [PError.EXPERIMENTAL]
+     */
+    internal fun experimental(
+        feature: String,
+        ctx: ParserRuleContext,
+    ): PError {
+        val location = ctxToLocation(ctx)
+        return PError(
+            PError.EXPERIMENTAL,
+            Severity.WARNING(),
+            PErrorKind.SYNTAX(),
+            location,
+            mapOf(
+                "FEATURE" to feature
+            )
+        )
+    }
+
+    private fun ctxToLocation(ctx: ParserRuleContext): SourceLocation? {
+        val start = ctx.start
+        val stop = ctx.stop
+        if (start == null || stop == null) {
+            return null
+        }
+        val length = ctx.sourceInterval.length()
+        return SourceLocation(start.line.toLong(), start.charPositionInLine + 1L, length.toLong())
+    }
 }
diff --git a/partiql-parser/src/main/kotlin/org/partiql/parser/internal/PartiQLParserDefault.kt b/partiql-parser/src/main/kotlin/org/partiql/parser/internal/PartiQLParserDefault.kt
@@ -286,7 +286,7 @@ internal class PartiQLParserDefault : PartiQLParser {
             else -> throw IllegalArgumentException("Unsupported parser mode: $mode")
         }
         val tree = parser.statements()
-        return Visitor.translate(tokens, tree)
+        return Visitor.translate(tokens, tree, listener)
     }
 
     private fun createTokenStream(source: String, listener: PErrorListener): CountingTokenStream {
@@ -390,6 +390,7 @@ internal class PartiQLParserDefault : PartiQLParser {
         private val tokens: CommonTokenStream,
         private val locations: MutableMap<Int, SourceLocation>,
         private val parameters: Map<Int, Int> = mapOf(),
+        private val listener: PErrorListener
     ) : PartiQLParserBaseVisitor<AstNode>() {
         // Counter to store unique AstNode tags
         private var counter = 0
@@ -414,9 +415,10 @@ internal class PartiQLParserDefault : PartiQLParser {
             fun translate(
                 tokens: CountingTokenStream,
                 tree: GeneratedParser.StatementsContext,
+                listener: PErrorListener
             ): PartiQLParser.Result {
                 val locations = mutableMapOf<Int, SourceLocation>()
-                val visitor = Visitor(tokens, locations, tokens.parameterIndexes)
+                val visitor = Visitor(tokens, locations, tokens.parameterIndexes, listener)
                 val statements = tree.statement().map { statementCtx ->
                     visitor.visit(statementCtx) as Statement
                 }
@@ -1079,6 +1081,7 @@ internal class PartiQLParserDefault : PartiQLParser {
          */
 
         override fun visitWindowClause(ctx: GeneratedParser.WindowClauseContext) = translate(ctx) {
+            listener.report(PErrors.experimental("Window Clause", ctx))
             val definitions = visitOrEmpty<WindowClause.WindowDefinition>(ctx.windowDefinition())
             WindowClause(definitions)
         }
@@ -1993,6 +1996,7 @@ internal class PartiQLParserDefault : PartiQLParser {
          * Window Functions
          */
         override fun visitWindowFunction(ctx: GeneratedParser.WindowFunctionContext) = translate(ctx) {
+            listener.report(PErrors.experimental("Window Function", ctx))
             val type = visitAs<WindowFunctionType>(ctx.windowFunctionType())
             val ref = visit(ctx.windowNameOrSpecification()) as WindowSpecification
             ExprWindowFunction(type, ref)
diff --git a/partiql-plan/src/main/java/org/partiql/plan/WindowFunctionNode.java b/partiql-plan/src/main/java/org/partiql/plan/WindowFunctionNode.java
@@ -8,7 +8,9 @@
 /**
  * Represents a window function node.
  * @see WindowFunctionSignature
+ * @deprecated This feature is experimental and is subject to change.
  */
+@Deprecated
 public final class WindowFunctionNode {
 
     private final WindowFunctionSignature signature;
diff --git a/partiql-plan/src/main/java/org/partiql/plan/WindowFunctionSignature.java b/partiql-plan/src/main/java/org/partiql/plan/WindowFunctionSignature.java
@@ -8,7 +8,9 @@
 /**
  * Represents the signature of a window function.
  * @see WindowFunctionNode
+ * @deprecated This feature is experimental and is subject to change.
  */
+@Deprecated
 public final class WindowFunctionSignature {
 
     private final String name;
diff --git a/partiql-plan/src/main/java/org/partiql/plan/rel/RelWindow.java b/partiql-plan/src/main/java/org/partiql/plan/rel/RelWindow.java
@@ -23,7 +23,9 @@
  *     <li>the window functions' outputs</li>
  * </ul>
  * </p>
+ * @deprecated This feature is experimental and is subject to change.
  */
+@Deprecated
 public abstract class RelWindow extends RelBase {
 
     /**
diff --git a/partiql-planner/src/main/kotlin/org/partiql/planner/internal/PErrors.kt b/partiql-planner/src/main/kotlin/org/partiql/planner/internal/PErrors.kt
@@ -229,6 +229,16 @@ internal object PErrors {
         )
     }
 
+    internal fun experimental(feature: String, location: SourceLocation? = null): PError {
+        return PError(
+            PError.EXPERIMENTAL,
+            Severity.WARNING(),
+            PErrorKind.SEMANTIC(),
+            location,
+            mapOf("FEATURE" to feature),
+        )
+    }
+
     internal fun degreeViolationScalarSubquery(actual: Int, location: SourceLocation? = null): PError {
         return PError(
             PError.DEGREE_VIOLATION_SCALAR_SUBQUERY,
diff --git a/partiql-planner/src/main/kotlin/org/partiql/planner/internal/typer/PlanTyper.kt b/partiql-planner/src/main/kotlin/org/partiql/planner/internal/typer/PlanTyper.kt
@@ -228,6 +228,7 @@ internal class PlanTyper(private val env: Env, config: Context, private val flag
         }
 
         override fun visitRelOpWindow(node: Rel.Op.Window, ctx: Rel.Type?): Rel {
+            env.listener.report(PErrors.experimental("Window Clause"))
             val input = visitRel(node.input, ctx)
             val functions = node.functions.map { visitRelOpWindowWindowFunction(it, input.type) }
             val partitions = node.partitions.map { it.type(input.type.schema, outer) }
diff --git a/partiql-spi/api/partiql-spi.api b/partiql-spi/api/partiql-spi.api
@@ -303,6 +303,7 @@ public final class org/partiql/spi/errors/PError : org/partiql/spi/Enum {
 	public static final field CARDINALITY_VIOLATION I
 	public static final field DEGREE_VIOLATION_SCALAR_SUBQUERY I
 	public static final field DIVISION_BY_ZERO I
+	public static final field EXPERIMENTAL I
 	public static final field FEATURE_NOT_SUPPORTED I
 	public static final field FUNCTION_NOT_FOUND I
 	public static final field FUNCTION_TYPE_MISMATCH I
diff --git a/partiql-spi/src/main/java/org/partiql/spi/errors/PError.java b/partiql-spi/src/main/java/org/partiql/spi/errors/PError.java
@@ -563,4 +563,21 @@ public static PError INTERNAL_ERROR(@NotNull PErrorKind kind, @Nullable SourceLo
      * </p>
      */
     public static final int DEGREE_VIOLATION_SCALAR_SUBQUERY = 20;
+
+    /**
+     * <p>
+     * This is a runtime/compilation/planning warning indicating that the particular feature is experimental, and the
+     * result/api is subject to change.
+     * </p>
+     * <p>
+     * Potentially  available properties:
+     * <ul>
+     * <li><b>FEATURE</b> ({@link String}): The name of the feature that is experimental.</li>
+     * </ul>
+     * </p>
+     * <p>
+     * Example error message: <code>[location]: Feature ([feature]) is experimental and is subject to change.</code>
+     * </p>
+     */
+    public static final int EXPERIMENTAL = 21;
 }
diff --git a/partiql-spi/src/test/kotlin/org/partiql/spi/errors/PErrorCodeTests.kt b/partiql-spi/src/test/kotlin/org/partiql/spi/errors/PErrorCodeTests.kt
@@ -35,7 +35,8 @@ class PErrorCodeTests {
             "NUMERIC_VALUE_OUT_OF_RANGE" to 17,
             "INVALID_CHAR_VALUE_FOR_CAST" to 18,
             "DIVISION_BY_ZERO" to 19,
-            "DEGREE_VIOLATION_SCALAR_SUBQUERY" to 20
+            "DEGREE_VIOLATION_SCALAR_SUBQUERY" to 20,
+            "EXPERIMENTAL" to 21,
         )
 
         // Preparation

Original file line number	Diff line number	Diff line change
`@@ -28,5 +28,6 @@ enum class ErrorCodeString(val code: Int) {`
`28`	`28`	`NUMERIC_VALUE_OUT_OF_RANGE(PError.NUMERIC_VALUE_OUT_OF_RANGE),`
`29`	`29`	`INVALID_CHAR_VALUE_FOR_CAST(PError.INVALID_CHAR_VALUE_FOR_CAST),`
`30`	`30`	`DIVISION_BY_ZERO(PError.DIVISION_BY_ZERO),`
`31`		`- DEGREE_VIOLATION_SCALAR_SUBQUERY(PError.DEGREE_VIOLATION_SCALAR_SUBQUERY)`
	`31`	`+ DEGREE_VIOLATION_SCALAR_SUBQUERY(PError.DEGREE_VIOLATION_SCALAR_SUBQUERY),`
	`32`	`+ EXPERIMENTAL(PError.EXPERIMENTAL),`
`32`	`33`	`}`