{"record":{"id":"e25d5f84f25009ed","repo":"apache/beam","slug":"converting-bigquery-type-field-type-to-python-beam-type-is","errorCode":null,"errorMessage":"Converting BigQuery type [{field_type}] to Python Beam type is not supported.","messagePattern":"Converting BigQuery type \\[(.+?)\\] to Python Beam type is not supported\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/io/gcp/bigquery_tools.py","lineNumber":1822,"sourceCode":"  Returns:\n    List[Tuple[str, Any]]: A list of type hints that describe the input schema.\n    Nested and repeated fields are supported.\n  \"\"\"\n  effective_types = {**BIGQUERY_TYPE_TO_PYTHON_TYPE, **(type_overrides or {})}\n  if not isinstance(schema, (bigquery.TableSchema, bigquery.TableFieldSchema)):\n    schema = get_bq_tableschema(schema)\n  typehints = []\n  for field in schema.fields:\n    name, field_type, mode = field.name, field.type.upper(), field.mode.upper()\n\n    if field_type in [\"STRUCT\", \"RECORD\"]:\n      # Structs can be represented as Beam Rows.\n      typehint = RowTypeConstraint.from_fields(\n          get_beam_typehints_from_tableschema(field, type_overrides))\n    elif field_type in effective_types:\n      typehint = effective_types[field_type]\n    else:\n      raise ValueError(\n          f\"Converting BigQuery type [{field_type}] to \"\n          \"Python Beam type is not supported.\")\n\n    if mode == \"REPEATED\":\n      typehint = Sequence[typehint]\n    elif mode != \"REQUIRED\":\n      typehint = Optional[typehint]\n\n    typehints.append((name, typehint))\n  return typehints\n\n\nclass BigQueryJobTypes:\n  EXPORT = 'EXPORT'\n  COPY = 'COPY'\n  LOAD = 'LOAD'\n  QUERY = 'QUERY'\n","sourceCodeStart":1804,"sourceCodeEnd":1840,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/io/gcp/bigquery_tools.py#L1804-L1840","documentation":"get_beam_typehints_from_tableschema() maps BigQuery field types to Beam Python type hints and raises ValueError when a field's type has no mapping in effective_types (after applying type_overrides). Unsupported or unrecognized BigQuery/legacy type names cannot be converted to Beam Rows type hints.","triggerScenarios":"A table schema containing a BigQuery type not in the supported map (e.g. GEOGRAPHY, JSON, or a typo like 'STRING ' with whitespace or 'INTERVAL'); custom type_overrides that fail to cover an otherwise unsupported type; recursive struct fields containing an unsupported nested type.","commonSituations":"Reading modern BigQuery tables (GEOGRAPHY/JSON columns) into Beam Rows; schemas autogenerated from newer BigQuery features; hand-written schema strings with typos; older Beam versions lacking newer type mappings.","solutions":["Remove or exclude the unsupported column from the schema before reading/writing.","Supply type_overrides mapping the unsupported BigQuery type to a supported one (e.g. {'GEOGRAPHY': 'STRING'}).","Cast the column in SQL (e.g. CAST(geog AS STRING)) in the query used to export data.","Upgrade apache-beam to a version that maps the newer BigQuery types."],"exampleFix":"// before\nWriteToBigQuery(schema=table_schema)  # schema has GEOGRAPHY field\n\n// after\nWriteToBigQuery(\n    schema=table_schema,\n    type_overrides={\"GEOGRAPHY\": \"STRING\"})","handlingStrategy":"validation","validationCode":"SUPPORTED = {'STRING','BYTES','INTEGER','INT64','FLOAT','FLOAT64','NUMERIC','BOOLEAN','BOOL','TIMESTAMP','DATE','TIME','DATETIME','RECORD','STRUCT'}\nunsupported = [f['type'] for f in schema['fields'] if f['type'].strip().upper() not in SUPPORTED and f['type'] not in (type_overrides or {})]\nif unsupported:\n    raise ValueError(f'Unsupported BigQuery types: {unsupported}')","typeGuard":"def is_convertible_field(field, overrides=None):\n    t = field.get('type', '').strip().upper()\n    return t in overrides or t in {'STRING','INTEGER','FLOAT','BOOLEAN','TIMESTAMP','RECORD','BYTES','NUMERIC','DATE','TIME','DATETIME'}","tryCatchPattern":"try:\n    hints = get_beam_typehints_from_tableschema(schema)\nexcept ValueError as e:\n    if 'not supported' in str(e):\n        hints = get_beam_typehints_from_tableschema(schema, type_overrides={'GEOGRAPHY': 'STRING', 'JSON': 'STRING'})\n    else:\n        raise","preventionTips":["Audit table schemas for GEOGRAPHY/JSON/other exotic types before using Rows-based reads.","Set type_overrides proactively for unsupported types.","Strip whitespace and normalize case in schema type names.","Keep apache-beam updated for newer BigQuery type mappings."],"tags":["python","apache-beam","bigquery","schema","type-mapping"],"backgroundTag":"unsupported-enum-value","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}