{"record":{"id":"302752a49cf76962","repo":"apache/iceberg","slug":"vectorized-reads-are-not-supported-yet-for-struct","errorCode":null,"errorMessage":"Vectorized reads are not supported yet for struct fields","messagePattern":"Vectorized reads are not supported yet for struct fields","errorType":"exception","errorClass":"UnsupportedOperationException","httpStatus":null,"severity":"error","filePath":"arrow/src/main/java/org/apache/iceberg/arrow/vectorized/VectorizedReaderBuilder.java","lineNumber":152,"sourceCode":"      return VectorizedArrowReader.nulls();\n    }\n\n    throw new IllegalArgumentException(String.format(\"Missing required field: %s\", field.name()));\n  }\n\n  private <T> ConstantVectorReader<T> constantReader(Types.NestedField field, T constant) {\n    return new ConstantVectorReader<>(field, constant);\n  }\n\n  protected VectorizedReader<?> vectorizedReader(List<VectorizedReader<?>> reorderedFields) {\n    return readerFactory.apply(reorderedFields);\n  }\n\n  @Override\n  public VectorizedReader<?> struct(\n      Types.StructType expected, GroupType groupType, List<VectorizedReader<?>> fieldReaders) {\n    if (expected != null) {\n      throw new UnsupportedOperationException(\n          \"Vectorized reads are not supported yet for struct fields\");\n    }\n    return null;\n  }\n\n  @Override\n  public ParquetVariantVisitor<VectorizedReader<?>> variantVisitor() {\n    return new VectorizedVariantVisitor(\n        currentPath(), parquetSchema, icebergSchema, rootAllocator, setArrowValidityVector);\n  }\n\n  @Override\n  public VectorizedReader<?> variant(\n      Types.VariantType iVariant, GroupType variant, VectorizedReader<?> result) {\n    return result;\n  }\n\n  @Override","sourceCodeStart":134,"sourceCodeEnd":170,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/arrow/src/main/java/org/apache/iceberg/arrow/vectorized/VectorizedReaderBuilder.java#L134-L170","documentation":"VectorizedReaderBuilder.struct rejects vectorized reading of nested struct fields whenever an expected StructType is present. Vectorization is only implemented for top-level primitive columns, so a nested struct column with a known expected type is unsupported and the builder throws UnsupportedOperationException (returns null only for unexpected/group-only structs).","triggerScenarios":"Enabling vectorized reads on a table whose projection includes a struct-typed column — IcebergParquetReaders.buildReader hits the struct visit with a non-null expected StructType.","commonSituations":"Queries selecting nested struct columns with vectorization enabled (default on); upgrading tables to include complex types while relying on the vectorized path.","solutions":["Disable vectorized reads for the table (spark.read.option vectorized-reader-enabled=false or table property) so generic readers handle structs","Project only primitive columns in vectorized queries","Upgrade Iceberg — newer versions may add nested-type vectorization"],"exampleFix":"// before\nspark.read.option(\"vectorized-reader-enabled\", \"true\").load(\"table\") // selects struct col\n// after\nspark.read.option(\"vectorized-reader-enabled\", \"false\").load(\"table\")","handlingStrategy":"fallback","validationCode":"boolean hasStruct = expectedSchema.columns().stream()\n    .anyMatch(f -> f.type().typeId() == Type.TypeID.STRUCT);\nif (hasStruct) {\n  // disable vectorization: spark.read.option(\"vectorized-reader-enabled\", \"false\")\n}","typeGuard":"boolean vectorizable(Schema s) {\n  return s.columns().stream().noneMatch(f -> f.type().typeId() == Type.TypeID.STRUCT);\n}","tryCatchPattern":"try {\n  reader = vectorizedBuilder.build();\n} catch (UnsupportedOperationException e) {\n  if (e.getMessage().contains(\"struct fields\")) { reader = genericBuilder.build(); }\n  else throw e;\n}","preventionTips":["Disable vectorization when projecting struct columns","Select only primitive columns for vectorized scans","Check Iceberg release notes for nested-type vectorization support"],"tags":["vectorized-reads","struct","nested-types"],"backgroundTag":"operation-not-supported","analyzedSha":"86d9c8fc543e7c56c9f624eb725f76c9baff9570","analyzedAt":"2026-09-12T00:46:39.097Z","contentChangedAt":"2026-09-12T00:46:39.097Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}