apache/beam · error · NotImplementedError

Accessing locals with @ is not yet supported…

Error message

Accessing locals with @ is not yet supported (https://github.com/apache/beam/issues/20626)

What it means

The Beam DataFrame API's query/eval support (_eval_or_query) rejects pandas' local-variable interpolation: when kwargs contain local_dict, global_dict, level, target, or resolvers (the '@' reference mechanism), this NotImplementedError fires because locals access is not yet supported (Beam issue 20626). Use literal expressions or precompute values instead.

Solutions

Format the variable value directly into the expression string with an f-string
Use string concatenation for the constant value
Materialize with to_pandas() and run the @-based query in pandas

Example fix

// before
result = df.beam.query('a > @limit')
// after
result = df.beam.query(f'a > {limit!r}')

Defensive patterns

Strategy: validation

Validate before calling

import re
if re.search(r'\@[^\d\W]\w*', expr):
    raise ValueError('@-references are unsupported in Beam query/eval; inline the value')

Try / catch

try:
    out = dframe.query(f'a > {limit!r}')
except NotImplementedError:
    out = dframe.to_pandas().query('a > @limit')

Prevention

Search expression strings for '@' before calling query/eval on Beam frames
Use f-strings to embed constants
Add a unit test that runs all query expressions against a Beam frame

When it happens

Trigger: Calling df.query('a > @limit') or df.eval('b + @offset') on a Beam deferred DataFrame where the expression contains '@<identifier>'

Common situations: Porting pandas code that interpolates local variables into query/eval strings; migrating pipelines from pandas to Beam DataFrames

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/785c08c6749c8f69. Report an issue: GitHub.

Appendix: source

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

      ))
    else:
      requires_partition_by = partitionings.Arbitrary()
    return frame_base.DeferredFrame.wrap(
        expressions.ComputedExpression(
            'dropna',
            lambda df: df.dropna(axis=axis, **kwargs),
            [self._expr],
            preserves_partition_by=partitionings.Arbitrary(),
            requires_partition_by=requires_partition_by))

  def _eval_or_query(self, name, expr, inplace, **kwargs):
    for key in ('local_dict', 'global_dict', 'level', 'target', 'resolvers'):
      if key in kwargs:
        raise NotImplementedError(f"Setting '{key}' is not yet supported")

    # look for '@<py identifier>'
    if re.search(r'\@[^\d\W]\w*', expr, re.UNICODE):
      raise NotImplementedError("Accessing locals with @ is not yet supported "
                                "(https://github.com/apache/beam/issues/20626)"
                                )

    result_expr = expressions.ComputedExpression(
        name,
        lambda df: getattr(df, name)(expr, **kwargs),
        [self._expr],
        requires_partition_by=partitionings.Arbitrary(),
        preserves_partition_by=partitionings.Arbitrary())

    if inplace:
      self._expr = result_expr
    else:
      return frame_base.DeferredFrame.wrap(result_expr)


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

View on GitHub (pinned to 12126d8942)