{"record":{"id":"0634602333253c1a","repo":"apache/iceberg","slug":"cannot-mix-zorder-and-hilbert-sort-expressions-063460","errorCode":null,"errorMessage":"Cannot mix Zorder and Hilbert sort expressions: ${sortOrderString}","messagePattern":"Cannot mix Zorder and Hilbert sort expressions: (.+?)","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"spark/v4.2/spark/src/main/java/org/apache/iceberg/spark/procedures/RewriteDataFilesProcedure.java","lineNumber":205,"sourceCode":"  private void parseSortOrder(\n      String sortOrderString,\n      List<Zorder> zOrderTerms,\n      List<Hilbert> hilbertTerms,\n      List<ExtendedParser.RawOrderField> sortOrderFields) {\n    ExtendedParser.parseSortOrder(spark(), sortOrderString)\n        .forEach(\n            field -> {\n              if (field.term() instanceof Zorder) {\n                zOrderTerms.add((Zorder) field.term());\n              } else if (field.term() instanceof Hilbert) {\n                hilbertTerms.add((Hilbert) field.term());\n              } else {\n                sortOrderFields.add(field);\n              }\n            });\n\n    if (!zOrderTerms.isEmpty() && !hilbertTerms.isEmpty()) {\n      throw new IllegalArgumentException(\n          \"Cannot mix Zorder and Hilbert sort expressions: \" + sortOrderString);\n    }\n\n    if ((!zOrderTerms.isEmpty() || !hilbertTerms.isEmpty()) && !sortOrderFields.isEmpty()) {\n      throw new IllegalArgumentException(\n          \"Cannot mix identity sort columns and a Zorder or Hilbert sort expression: \"\n              + sortOrderString);\n    }\n  }\n\n  private RewriteDataFilesSparkAction applySortStrategy(\n      RewriteDataFilesSparkAction action,\n      List<Zorder> zOrderTerms,\n      List<Hilbert> hilbertTerms,\n      List<ExtendedParser.RawOrderField> sortOrderFields,\n      Schema schema) {\n    if (!zOrderTerms.isEmpty()) {\n      String[] columnNames =","sourceCodeStart":187,"sourceCodeEnd":223,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/spark/v4.2/spark/src/main/java/org/apache/iceberg/spark/procedures/RewriteDataFilesProcedure.java#L187-L223","documentation":"RewriteDataFilesProcedure's sort_order option accepts either Z-order terms, Hilbert terms, or plain identity columns — not a mix of Z-order and Hilbert in the same expression. parseSortOrder throws this IllegalArgumentException when both zorder(...) and hilbert(...) appear in the sort_order string.","triggerScenarios":"Calling rewrite_data_files with sort_order => 'zorder(a, b), hilbert(c, d)' or an expression combining both functions.","commonSituations":"Combining sort expressions from different examples; evolving configs where one term was switched to hilbert but the other zorder term was left in place.","solutions":["Choose one spatial ordering scheme: use only zorder(...) terms or only hilbert(...) terms.","Remove the unwanted zorder/hilbert term from the sort_order option.","If both orderings are needed, run rewrite_data_files twice in separate passes."],"exampleFix":"// before\ncall rewrite_data_files(table => 'db.t', sort_order => 'zorder(a,b) hilbert(c,d)')\n// after\ncall rewrite_data_files(table => 'db.t', sort_order => 'hilbert(a,b,c,d)')","handlingStrategy":"validation","validationCode":"val hasZ = sortOrder.contains(\"zorder(\")\nval hasH = sortOrder.contains(\"hilbert(\")\nrequire(!(hasZ && hasH), \"cannot mix zorder and hilbert\")","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Pick one spatial scheme per table config","Templatize sort_order strings; don't hand-concatenate from examples","Review config migrations that switched zorder<->hilbert"],"tags":["spark","compaction","sort-order"],"backgroundTag":"mutually-exclusive-options","analyzedSha":"86d9c8fc543e7c56c9f624eb725f76c9baff9570","analyzedAt":"2026-09-12T00:46:39.097Z","contentChangedAt":"2026-09-12T00:46:39.097Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}