What causes "Unknown DateTime type ${logicalId}" in apache/beam?

Use standard Beam DATE/TIME logical types instead of a custom logical type for the column

apache/beam · error · java.lang.UnsupportedOperationException

Unknown DateTime type ${logicalId}

Error message

Unknown DateTime type ${logicalId}

What it means

fieldToAvatica converts Beam Row field values into Avatica (Calcite JDBC) typed values. In the DATE branch, if the field's logical type is neither the recognized DATE logical type nor a PassThroughLogicalType, the converter cannot map it and throws UnsupportedOperationException("Unknown DateTime type " + logicalId). It is a schema/type-support limitation, not a data error.

Source

Thrown at sdks/java/extensions/sql/src/main/java/org/apache/beam/sdk/extensions/sql/impl/rel/BeamEnumerableConverter.java:340

        LogicalType<?, ?> logicalType = type.getLogicalType();
        assert logicalType != null;
        String logicalId = logicalType.getIdentifier();
        if (SqlTypes.TIME.getIdentifier().equals(logicalId)) {
          if (beamValue instanceof Long) { // base type
            return (Long) beamValue;
          } else { // input type
            return ((LocalTime) beamValue).toNanoOfDay();
          }
        } else if (SqlTypes.DATE.getIdentifier().equals(logicalId)) {
          if (beamValue instanceof Long) { // base type
            return ((Long) beamValue).intValue();
          } else { // input type
            return (int) ((LocalDate) beamValue).toEpochDay();
          }
        } else if (logicalType instanceof PassThroughLogicalType) {
          return beamValue;
        } else {
          throw new UnsupportedOperationException("Unknown DateTime type " + logicalId);
        }
      case DATETIME:
        return ((ReadableInstant) beamValue).getMillis();
      case BYTE:
      case INT16:
      case INT32:
      case INT64:
      case DECIMAL:
      case FLOAT:
      case DOUBLE:
      case STRING:
      case BOOLEAN:
      case BYTES:
        return beamValue;
      case ARRAY:
        return ((List<?>) beamValue)
            .stream()
                .map(elem -> fieldToAvatica(type.getCollectionElementType(), elem))

View on GitHub (pinned to 12126d8942)

Solutions

Use standard Beam DATE/TIME logical types instead of a custom logical type for the column
Make the logical type implement PassThroughLogicalType so the value is returned as-is
Convert the column to a primitive DATE (FieldType of TypeName.DATETIME) before querying
Patch BeamEnumerableConverter.fieldToAvatica to handle the logicalId
Check Beam version — upgrade if the logical type support was added later

Example fix

// before
FieldType dateField = FieldType.logicalType(new MyDateLogicalType());
// after: use a supported logical type or pass-through
FieldType dateField = FieldType.logicalType(new MyDateLogicalType() implements PassThroughLogicalType);

Defensive patterns

Strategy: validation

Validate before calling

FieldType ft = schema.getField(i).getType();
if (ft.getTypeName() == TypeName.DATETIME && ft.getLogicalType() != null
    && !(ft.getLogicalType() instanceof Dates.LogicalDate)
    && !(ft.getLogicalType() instanceof PassThroughLogicalType)) {
  throw new IllegalArgumentException("Unsupported logical type: " + ft.getLogicalType().getIdentifier());
}

Type guard

boolean isSupportedDateField(FieldType ft) {
  return ft.getTypeName() != TypeName.DATETIME || ft.getLogicalType() == null
      || ft.getLogicalType() instanceof PassThroughLogicalType;
}

Try / catch

try {
  Object v = fieldToAvatica(fieldType, value);
} catch (UnsupportedOperationException e) {
  if (e.getMessage().startsWith("Unknown DateTime type")) {
    // fall back to raw value or coerce to java.sql.Date
  } else throw e;
}

Prevention

Use standard Beam logical types for DATE/TIME columns queried via Beam SQL
Implement PassThroughLogicalType for custom logical types
Normalize schemas to primitive types before exposing them to Beam SQL
Test SELECT round-trips on all schema columns in CI
Check Beam release notes for newly supported logical types

When it happens

Trigger: Executing a Beam SQL SELECT whose schema contains a DATE/timestamp logical type column with a custom or unrecognized LogicalType identifier (logicalId) that BeamEnumerableConverter does not know how to convert to Avatica's java.sql.Date representation.

Common situations: Using custom logical types registered in the schema (e.g. via Schema.builder().addLogicalType or custom FieldType with logical type), or Beam version mismatches where a new built-in logical type isn't yet handled by the Avatica converter.

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/beam@12126d8942 (2026-09-13). Data as JSON: /api/errors/fa8e4c60f482a26d. Report an issue: GitHub.