apache/beam · error · ValueError

Please provide either `query_fn` or the parameters…

Error message

Please provide either `query_fn` or the parameters `table_name`, `row_restriction_template` together.

What it means

_validate_bigquery_metadata() requires that, when no query_fn is given, both table_name and row_restriction_template are provided. If either is missing (None), this ValueError is raised from __init__.

Solutions

Provide both table_name and row_restriction_template
Or provide a query_fn instead of the table-based parameters

Example fix

// before
BigQueryEnrichmentHandler(table_name='proj.ds.tbl')
// after
BigQueryEnrichmentHandler(table_name='proj.ds.tbl', row_restriction_template='id = {id}')

Defensive patterns

Strategy: validation

Validate before calling

def check_table_config(cfg):
    if not cfg.get('query_fn'):
        missing = [k for k in ('table_name', 'row_restriction_template') if not cfg.get(k)]
        if missing:
            raise ValueError(f'Missing required enrichment params: {missing}')

Try / catch

try:
    handler = BigQueryEnrichmentHandler(**cfg)
except ValueError as e:
    logger.error('Incomplete BigQuery enrichment config: %s', e)
    raise

Prevention

Always set both table_name and row_restriction_template for table-based enrichment
Use keyword arguments with explicit names to avoid typo'd kwargs being ignored
Validate config at pipeline-construction time with a smoke instantiation

When it happens

Trigger: BigQueryEnrichmentHandler(table_name='t') without row_restriction_template, or with only fields/condition_value_fn and no table_name/template, and no query_fn.

Common situations: Forgot row_restriction_template (WHERE-clause template) when switching from query_fn to table-based enrichment; typo in kwarg name.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

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

Appendix: source

Thrown at sdks/python/apache_beam/transforms/enrichment_handlers/bigquery.py:49

QueryFn = Callable[[beam.Row], str]
ConditionValueFn = Callable[[beam.Row], list[Any]]

_LOGGER = logging.getLogger(__name__)


def _validate_bigquery_metadata(
    table_name, row_restriction_template, fields, condition_value_fn, query_fn):
  if query_fn:
    if bool(table_name or row_restriction_template or fields or
            condition_value_fn):
      raise ValueError(
          "Please provide either `query_fn` or the parameters `table_name`, "
          "`row_restriction_template`, and `fields/condition_value_fn` "
          "together.")
  else:
    if not (table_name and row_restriction_template):
      raise ValueError(
          "Please provide either `query_fn` or the parameters "
          "`table_name`, `row_restriction_template` together.")
    if ((fields and condition_value_fn) or
        (not fields and not condition_value_fn)):
      raise ValueError(
          "Please provide exactly one of `fields` or "
          "`condition_value_fn`")


class BigQueryEnrichmentHandler(EnrichmentSourceHandler[Union[Row, list[Row]],
                                                        Union[Row, list[Row]]]):
  """Enrichment handler for Google Cloud BigQuery.

  Use this handler with :class:`apache_beam.transforms.enrichment.Enrichment`
  transform.

  To use this handler you need either of the following combinations:
    * `table_name`, `row_restriction_template`, `fields`

View on GitHub (pinned to 12126d8942)