{"record":{"id":"a0ada91aeabb28f5","repo":"apache/beam","slug":"please-provide-exactly-one-of-fields-or-condition-value-fn","errorCode":null,"errorMessage":"Please provide exactly one of `fields` or `condition_value_fn`","messagePattern":"Please provide exactly one of `fields` or `condition_value_fn`","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/transforms/enrichment_handlers/bigquery.py","lineNumber":54,"sourceCode":"\n\ndef _validate_bigquery_metadata(\n    table_name, row_restriction_template, fields, condition_value_fn, query_fn):\n  if query_fn:\n    if bool(table_name or row_restriction_template or fields or\n            condition_value_fn):\n      raise ValueError(\n          \"Please provide either `query_fn` or the parameters `table_name`, \"\n          \"`row_restriction_template`, and `fields/condition_value_fn` \"\n          \"together.\")\n  else:\n    if not (table_name and row_restriction_template):\n      raise ValueError(\n          \"Please provide either `query_fn` or the parameters \"\n          \"`table_name`, `row_restriction_template` together.\")\n    if ((fields and condition_value_fn) or\n        (not fields and not condition_value_fn)):\n      raise ValueError(\n          \"Please provide exactly one of `fields` or \"\n          \"`condition_value_fn`\")\n\n\nclass BigQueryEnrichmentHandler(EnrichmentSourceHandler[Union[Row, list[Row]],\n                                                        Union[Row, list[Row]]]):\n  \"\"\"Enrichment handler for Google Cloud BigQuery.\n\n  Use this handler with :class:`apache_beam.transforms.enrichment.Enrichment`\n  transform.\n\n  To use this handler you need either of the following combinations:\n    * `table_name`, `row_restriction_template`, `fields`\n    * `table_name`, `row_restriction_template`, `condition_value_fn`\n    * `query_fn`\n\n  By default, the handler pulls all columns from the BigQuery table.\n  To override this, use the `column_name` parameter to specify a list of column","sourceCodeStart":36,"sourceCodeEnd":72,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/transforms/enrichment_handlers/bigquery.py#L36-L72","documentation":"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.","triggerScenarios":"BigQueryEnrichmentHandler(table_name=..., row_restriction_template=...) with both fields and condition_value_fn set, or with neither set.","commonSituations":"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.","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"],"exampleFix":"// before\nBigQueryEnrichmentHandler(table_name=t, row_restriction_template=tmpl, fields=['id'], condition_value_fn=fn)\n// after\nBigQueryEnrichmentHandler(table_name=t, row_restriction_template=tmpl, condition_value_fn=fn)","handlingStrategy":"validation","validationCode":"def check_key_config(fields=None, condition_value_fn=None):\n    if bool(fields) == bool(condition_value_fn):\n        raise ValueError('Provide exactly one of fields or condition_value_fn')","typeGuard":null,"tryCatchPattern":"try:\n    handler = BigQueryEnrichmentHandler(**cfg)\nexcept ValueError as e:\n    logger.error('Ambiguous key extraction config: %s', e)\n    raise","preventionTips":["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"],"tags":["apache-beam","bigquery","configuration"],"backgroundTag":"mutually-exclusive-options","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-20T03:17:13.778Z"}