apache/beam · error · WontImplementError

unique() is not supported by default because it produces a…

Error message

unique() is not supported by default because it produces a non-deferred result: a numpy array. You can use the Beam-specific argument unique(as_series=True) to get the result as a DeferredSeries

What it means

DeferredSeries.unique() in pandas returns a plain numpy array — a non-deferred, eagerly-materialized value — which the Beam dataframe API cannot produce. By default it raises WontImplementError (reason 'non-deferred-result'); a Beam-specific as_series=True option returns the distinct values as a DeferredSeries instead.

Solutions

Call unique(as_series=True) and use the returned DeferredSeries
Use .drop_duplicates() on the series to keep a deferred pipeline
Convert to a distinct PCollection (e.g. via the Beam dataframe expression or a Distinct transform) if a PCollection is acceptable

Example fix

// before
values = s.unique()
// after
values = s.unique(as_series=True)  # DeferredSeries

Defensive patterns

Strategy: validation

Validate before calling

values = s.unique(as_series=True)  # never call s.unique() bare on a DeferredSeries

Type guard

from apache_beam.dataframe.frames import DeferredSeries
def is_deferred_series(x):
    return isinstance(x, DeferredSeries)

Try / catch

from apache_beam.dataframe import frame_base
try:
    values = s.unique(as_series=True)
except frame_base.WontImplementError:
    values = s.drop_duplicates()

Prevention

Search ported code for .unique() calls and add as_series=True
Prefer drop_duplicates() for deferred distinct values
Remember deferred APIs return frames/series, never numpy arrays

When it happens

Trigger: Calling series.unique() without arguments (as_series defaults to False) on any DeferredSeries.

Common situations: Porting pandas code that does s.unique() for distinct values; using the result in set operations or len(); getting distinct categories for feature engineering.

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/6034f84f8f5157b1. Report an issue: GitHub.

Appendix: source

Thrown at sdks/python/apache_beam/dataframe/frames.py:2300

  round = frame_base._elementwise_method('round', base=pd.Series)

  take = frame_base.wont_implement_method(
      pd.Series, 'take', reason='deprecated')

  to_dict = frame_base.wont_implement_method(
      pd.Series, 'to_dict', reason="non-deferred-result")

  to_frame = frame_base._elementwise_method('to_frame', base=pd.Series)

  @frame_base.with_docs_from(pd.Series)
  def unique(self, as_series=False):
    """unique is not supported by default because it produces a
    non-deferred result: an :class:`~numpy.ndarray`. You can use the
    Beam-specific argument ``unique(as_series=True)`` to get the result as
    a :class:`DeferredSeries`"""

    if not as_series:
      raise frame_base.WontImplementError(
          "unique() is not supported by default because it produces a "
          "non-deferred result: a numpy array. You can use the Beam-specific "
          "argument unique(as_series=True) to get the result as a "
          "DeferredSeries",
          reason="non-deferred-result")
    return frame_base.DeferredFrame.wrap(
        expressions.ComputedExpression(
            'unique', lambda df: pd.Series(df.unique()), [self._expr],
            preserves_partition_by=partitionings.Singleton(),
            requires_partition_by=partitionings.Singleton(
                reason="unique() cannot currently be parallelized.")))

  @frame_base.with_docs_from(pd.Series)
  def update(self, other):
    self._expr = expressions.ComputedExpression(
        'update', lambda df, other: df.update(other) or df,
        [self._expr, other._expr],
        preserves_partition_by=partitionings.Arbitrary(),

View on GitHub (pinned to 12126d8942)