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`, and `fields/condition_value_fn` together.

What it means

BigQueryEnrichmentHandler._validate_bigquery_metadata() rejects a configuration where query_fn is provided AND at least one of table_name, row_restriction_template, fields, or condition_value_fn is also given. The two configuration styles are mutually exclusive.

Solutions

Remove table_name, row_restriction_template, fields, and condition_value_fn when using query_fn
Or remove query_fn and configure the table-based path with table_name + row_restriction_template + (fields or condition_value_fn)

Example fix

// before
BigQueryEnrichmentHandler(query_fn=my_fn, table_name='proj.ds.tbl')
// after
BigQueryEnrichmentHandler(query_fn=my_fn)

Defensive patterns

Strategy: validation

Validate before calling

def check_bq_config(query_fn=None, table_name=None, row_restriction_template=None, fields=None, condition_value_fn=None):
    if query_fn and (table_name or row_restriction_template or fields or condition_value_fn):
        raise ValueError('query_fn is mutually exclusive with table-based params')

Try / catch

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

Prevention

Pick one config style (query_fn OR table-based) per handler
Remove legacy kwargs when migrating to query_fn
Add a unit test constructing the handler with your exact kwargs

When it happens

Trigger: Calling BigQueryEnrichmentHandler(query_fn=..., table_name='t') or query_fn plus row_restriction_template/fields/condition_value_fn.

Common situations: Migrating an existing handler from static-table config to a query_fn and leaving the old kwargs in place.

Related errors

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

Appendix: source

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

from google.api_core.exceptions import BadRequest
from google.cloud import bigquery

import apache_beam as beam
from apache_beam.pvalue import Row
from apache_beam.transforms.enrichment import EnrichmentSourceHandler

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.

View on GitHub (pinned to 12126d8942)