apache/beam · error · ValueError

Please provide exactly one of `fields` or…

Error message

Please provide exactly one of `fields` or `condition_value_fn`

What it means

In the table-based (non-query_fn) configuration, exactly one of fields or condition_value_fn must be supplied — both or neither is invalid. _validate_bigquery_metadata raises this ValueError otherwise.

Solutions

Keep only fields (list of column names) OR only condition_value_fn, not both
If neither is needed, switch to a query_fn-based configuration

Example fix

// before
BigQueryEnrichmentHandler(table_name=t, row_restriction_template=tmpl, fields=['id'], condition_value_fn=fn)
// after
BigQueryEnrichmentHandler(table_name=t, row_restriction_template=tmpl, condition_value_fn=fn)

Defensive patterns

Strategy: validation

Validate before calling

def check_key_config(fields=None, condition_value_fn=None):
    if bool(fields) == bool(condition_value_fn):
        raise ValueError('Provide exactly one of fields or condition_value_fn')

Try / catch

try:
    handler = BigQueryEnrichmentHandler(**cfg)
except ValueError as e:
    logger.error('Ambiguous key extraction config: %s', e)
    raise

Prevention

Decide between fields and condition_value_fn once and document it
When adding condition_value_fn, delete the fields list
Cover handler construction in tests to fail fast

When it happens

Trigger: BigQueryEnrichmentHandler(table_name=..., row_restriction_template=...) with both fields and condition_value_fn set, or with neither set.

Common situations: Adding condition_value_fn for custom key extraction while forgetting to remove the fields list; or building the handler programmatically where both default to None.

Related errors

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

Appendix: source

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


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`
    * `table_name`, `row_restriction_template`, `condition_value_fn`
    * `query_fn`

  By default, the handler pulls all columns from the BigQuery table.
  To override this, use the `column_name` parameter to specify a list of column

View on GitHub (pinned to 12126d8942)