Ignoring '{}' as such values are constant within a partition

Error message

Ignoring '{}' as such values are constant within a partition

What it means

Spark Z-Order rewrite runner skips columns whose values are constant within each partition, because sorting by such columns gives no benefit inside a partition's files. This is a LOG.warn (not an exception) emitted while building the valid Z-Order column list; the rewrite continues with the remaining columns.

Source

Thrown at spark/v3.5/spark/src/main/java/org/apache/iceberg/spark/actions/SparkZOrderFileRewriteRunner.java:199

            ? schema.findField(Z_COLUMN) == null
            : schema.caseInsensitiveFindField(Z_COLUMN) == null,
        "Cannot zorder because the table has a column named '%s', which conflicts with Iceberg's internal Z-order column name",
        Z_COLUMN);

    List<String> validZOrderColNames = Lists.newArrayList();

    for (String colName : inputZOrderColNames) {
      Types.NestedField field =
          caseSensitive ? schema.findField(colName) : schema.caseInsensitiveFindField(colName);
      Preconditions.checkArgument(
          field != null,
          "Cannot find column '%s' in table schema (case sensitive = %s): %s",
          colName,
          caseSensitive,
          schema.asStruct());

      if (identityPartitionFieldIds.contains(field.fieldId())) {
        LOG.warn("Ignoring '{}' as such values are constant within a partition", colName);
      } else {
        validZOrderColNames.add(colName);
      }
    }

    Preconditions.checkArgument(
        !validZOrderColNames.isEmpty(),
        "Cannot ZOrder, all columns provided were identity partition columns and cannot be used");

    return validZOrderColNames;
  }
}

View on GitHub (pinned to 86d9c8fc54)

Solutions

Remove identity partition columns from the Z_ORDER BY option
Keep only non-partition columns in z_order_by to get actual intra-partition clustering
If ordering across the whole table is desired, change partitioning so the column is not an identity partition field

Example fix

-- before
CALL iceberg.system.rewrite_data_files(table => 'db.t', options => map('strategy','sort'), where => 'true', strategy => 'zorder', z_order_by => 'date, id')
-- after
CALL iceberg.system.rewrite_data_files(table => 'db.t', strategy => 'zorder', z_order_by => 'id')

Defensive patterns

Strategy: validation

Validate before calling

Set<PartitionField> identity = table.spec().identitySourceIds().isEmpty() ? Set.of() : table.spec().fields().stream().filter(f -> f.transform().isIdentity()).collect(Collectors.toSet()); List<String> valid = zOrderCols.stream().filter(c -> !identity.contains(table.schema().findField(c))).collect(Collectors.toList());

Prevention

Exclude identity partition columns from z_order_by
Check table.spec() partition transforms before choosing sort columns

When it happens

Trigger: Calling rewrite_data_files with a Z_ORDER BY option containing a column that is an identity partition field.

Common situations: Users z-order by a partition key column (e.g. date or region) assuming it will cluster data, when it is already fully clustered per partition.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

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