apache/iceberg · error · UnsupportedOperationException

Z-ORDER Rewrite Strategy not implemented for this framework

Error message

Z-ORDER Rewrite Strategy not implemented for this framework

What it means

RewriteDataFiles.zOrder(String...) selects the Z-ORDER rewrite strategy over the given columns. The interface default throws UnsupportedOperationException; invoking the stub means the framework binding has not implemented Z-ORDER space-filling-curvature rewriting.

Solutions

Use an implementation that supports Z-ORDER (e.g. SparkActions' RewriteDataFiles)
Switch to binpack() or sort() if supported by the current implementation
Upgrade or replace the engine integration where Z-ORDER is implemented
Implement the zOrder override in a custom action binding if Z-ORDER is required

Example fix

// before
RewriteDataFiles.Result r = actions.rewriteDataFiles(table)
    .zOrder("colA", "colB")
    .execute();
// after
RewriteDataFiles.Result r = SparkActions.get()
    .rewriteDataFiles(table)
    .zOrder("colA", "colB")
    .execute();

Defensive patterns

Strategy: fallback

Try / catch

try {
  rewrite.zOrder(columns);
} catch (UnsupportedOperationException e) {
  rewrite.binpack();
}

Prevention

Treat Z-ORDER as a Spark-only capability unless verified otherwise
Document which strategies each engine binding supports
Add integration tests for strategy selection on every target engine
Fall back to SORT/BINPACK when multi-dimensional clustering is unavailable

When it happens

Trigger: Calling rewriteDataFiles().zOrder("colA", "colB") on an implementation that has not overridden the default zOrder method.

Common situations: Users copying Spark multi-dimensional clustering jobs to another engine, or custom RewriteDataFiles implementations that only implement BINPACK/SORT, hit the stub during strategy configuration.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

AI-assisted analysis of apache/iceberg@86d9c8fc54 (2026-09-12). Data as JSON: /api/errors/3917c7383961e5b2. Report an issue: GitHub.

Appendix: source

Thrown at api/src/main/java/org/apache/iceberg/actions/RewriteDataFiles.java:187

  /**
   * Choose SORT as a strategy for this rewrite operation and manually specify the sortOrder to use
   *
   * @param sortOrder user defined sortOrder
   * @return this for method chaining
   */
  default RewriteDataFiles sort(SortOrder sortOrder) {
    throw new UnsupportedOperationException(
        "SORT Rewrite Strategy not implemented for this framework");
  }

  /**
   * Choose Z-ORDER as a strategy for this rewrite operation with a specified list of columns to use
   *
   * @param columns Columns to be used to generate Z-Values
   * @return this for method chaining
   */
  default RewriteDataFiles zOrder(String... columns) {
    throw new UnsupportedOperationException(
        "Z-ORDER Rewrite Strategy not implemented for this framework");
  }

  /**
   * Choose HILBERT as a strategy for this rewrite operation with a specified list of columns to use
   *
   * @param columns Columns to be used to generate Hilbert values
   * @return this for method chaining
   */
  default RewriteDataFiles hilbert(String... columns) {
    throw new UnsupportedOperationException(
        "HILBERT Rewrite Strategy not implemented for this framework");
  }

  /**
   * A user provided filter for determining which files will be considered by the rewrite strategy.
   * This will be used in addition to whatever rules the rewrite strategy generates. For example
   * this would be used for providing a restriction to only run rewrite on a specific partition.

View on GitHub (pinned to 86d9c8fc54)