v0.14 to v1 Evaluation Migration

If there are inaccuracies discovered with this documentation, please submit a GitHub issue.

This guide is intended to cover the differences between the evaluation interfaces used in partiql-lang-kotlin v0.14 and partiql-lang-kotlin v1.

Background on ExprValue and v0.14 Evaluation

ExprValue was introduced in partiql-lang-kotlin v0.1 as the primary value representation for the evaluator. The evaluation system evolved to support various use cases, but by v0.14.9 several fundamental issues had emerged with the evaluation architecture.

1. Modeling issues with backwards compatibility and Java/Kotlin coupling

The ExprValue hierarchy relied heavily on Kotlin’s sealed classes and data classes, which constrained API evolution. Similar to StaticType, adding new value types or extending existing ones often broke compatibility for downstream consumers. This rigid class structure also bound the evaluation model tightly to JVM semantics, requiring frequent type casting and making runtime value operations unnecessarily complex.

2. Complex value access patterns

ExprValue had multiple ways to access the same data (scalar, bindings, ordinalBindings) with no unified access pattern. This led to confusion about which method to use and inconsistent null/missing handling across the codebase.

3. Complex session-based evaluation context

v0.14 used EvaluationSession with parameter lists for managing evaluation context. This approach required building sessions with parameters and accessing them by index, making variable management cumbersome and error-prone.

4. Limited compiler extensibility

The evaluation system was difficult to extend with custom operators and strategies. The compiler interface was monolithic and did not support pluggable compilation strategies for different evaluation patterns.

Background on Datum and v1 Evaluation

Datum was introduced in PLK v1 to address the prior pain points of ExprValue. It provides a unified interface for runtime values with proper support for gradual typing and lazy materialization. The v1 evaluation system was redesigned to provide better extensibility, cleaner environment management, and explicit error handling modes.

To use the Datum and v1 evaluation system, we’ve provided more examples within the partiql-lang-kotlin library’s migration guide

Included in the code examples are how to

  1. Safely access Datum values with proper type checking

  2. Perform orderly materialization of semi-structured data

  3. Work with the new Environment and Row classes

  4. Build custom compiler strategies

  5. Use evaluation modes (STRICT vs PERMISSIVE)

Other Differences

  • v1 Datum is pulled in from partiql-spi. v0.14 ExprValue is pulled in from partiql-lang. We made this change since the SPI package already heavily relies on Datum and provides a cleaner separation of concerns.

  • v1 defines explicit evaluation modes (Mode.STRICT() and Mode.PERMISSIVE()) for better error handling control. PERMISSIVE mode returns missing for type mismatches, while STRICT mode throws exceptions.

  • v1 introduces orderly materialization requirements for semi-structured data to support lazy evaluation. This ensures predictable iteration order for stateful processes through explicit materialization functions.

  • v1 separates the evaluation module (partiql-eval) from the main language module, providing better modularity and allowing for independent evolution of the evaluation system.

  • v1 uses a simplified stack-based Environment and Row system. v0.14 used complex nested bindings approach. Environment operations like push() return new immutable environments.

  • v1 requires explicit Field.of() construction for struct and row fields. v0.14 used implicit field creation patterns.

  • v1 Row class provides concat() operations and array-based value access. v0.14 used binding-based variable access patterns.

  • v1 supports pluggable compilation strategies through the Strategy pattern. v0.14 had a monolithic compiler design. Custom strategies can be added via PartiQLCompiler.builder().addStrategy().

  • v1 uses PError for structured error handling with better error codes and property extraction. See error handling for details on the improved evaluation error reporting.