apache/beam · error · WontImplementError

nlargest(keep= ) is not supported because it is order…

Error message

nlargest(keep={keep!r}) is not supported because it is order sensitive. Only keep="all" is supported.

What it means

DeferredDataFrame/Series.nlargest() with keep='first' or 'last' breaks ties by row order, which is undefined in a distributed Beam pipeline. Therefore only keep='all' (keep every tied row) is supported; any other value raises WontImplementError with reason 'order-sensitive'.

Solutions

Pass keep='all' explicitly: nlargest(n, keep='all')
Avoid relying on tie-break order; deduplicate afterwards if you need fewer rows
Use keep='any' (Beam-specific) which lets Beam keep an arbitrary duplicate
Sort by the column and slice head(n) only if order-insensitivity of ties is acceptable

Example fix

// before
df.nlargest(5, 'score')  # pandas default keep='first'
// after
df.nlargest(5, 'score', keep='all')

Defensive patterns

Strategy: validation

Validate before calling

assert keep == 'all', "nlargest on Beam dataframes only supports keep='all' (or keep='any')"

Type guard

def beam_safe_keep(keep):
    return keep in ('all', 'any')

Try / catch

from apache_beam.dataframe import frame_base
try:
    top = df.nlargest(n, col, keep='all')
except frame_base.WontImplementError:
    top = df.nlargest(n, col, keep='all')

Prevention

Always pass keep explicitly to nlargest/nsmallest in Beam pipelines
Treat pandas defaults (keep='first') as unsafe in distributed code
Decide tie-handling policy (all vs any) before porting

When it happens

Trigger: Calling nlargest(n, keep='first'), keep='last', or keep='any' (note: keep='any' is silently converted to 'first', which then raises? No — 'any' is mapped to 'first'... actually 'any' is accepted and remapped, so the error fires for any keep value that is not 'any' or 'all', e.g. 'first', 'last', or a typo like 'all '.)

Common situations: Porting pandas nlargest(..., keep='first') defaults — pandas' default keep='first' will trigger this; typos in the keep value; code that relies on tie-breaking order.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

AI-assisted analysis of apache/beam@12126d8942 (2026-09-13). Data as JSON: /api/errors/4a04b19b542c0d35. Report an issue: GitHub.

Appendix: source

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

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

  @frame_base.with_docs_from(pd.Series)
  @frame_base.args_to_kwargs(pd.Series)
  @frame_base.populate_defaults(pd.Series)
  def nlargest(self, keep, **kwargs):
    """Only ``keep=False`` and ``keep="any"`` are supported. Other values of
    ``keep`` make this an order-sensitive operation. Note ``keep="any"`` is
    a Beam-specific option that guarantees only one duplicate will be kept, but
    unlike ``"first"`` and ``"last"`` it makes no guarantees about _which_
    duplicate element is kept."""
    # TODO(robertwb): Document 'any' option.
    # TODO(robertwb): Consider (conditionally) defaulting to 'any' if no
    # explicit keep parameter is requested.
    if keep == 'any':
      keep = 'first'
    elif keep != 'all':
      raise frame_base.WontImplementError(
          f"nlargest(keep={keep!r}) is not supported because it is "
          "order sensitive. Only keep=\"all\" is supported.",
          reason="order-sensitive")
    kwargs['keep'] = keep
    per_partition = expressions.ComputedExpression(
        'nlargest-per-partition', lambda df: df.nlargest(**kwargs),
        [self._expr],
        preserves_partition_by=partitionings.Arbitrary(),
        requires_partition_by=partitionings.Arbitrary())
    with expressions.allow_non_parallel_operations(True):
      return frame_base.DeferredFrame.wrap(
          expressions.ComputedExpression(
              'nlargest', lambda df: df.nlargest(**kwargs), [per_partition],
              preserves_partition_by=partitionings.Arbitrary(),
              requires_partition_by=partitionings.Singleton()))

  @frame_base.with_docs_from(pd.Series)
  @frame_base.args_to_kwargs(pd.Series)

View on GitHub (pinned to 12126d8942)