BigQuery联邦查询通过Airflow执行时提示Connection not found问题排查

问题场景 #

在BigQuery控制台执行以下联邦查询可正常返回结果：

SELECT * FROM EXTERNAL_QUERY("projects/project_XXX/locations/asia-southeast1/connections/connection_XXX", "SELECT * FROM postgres_table_name;")

但将该查询放入Airflow的BigQueryInsertJobOperator执行时，报错：

404 Not found: Connection {connection_name}

对应的Airflow代码片段：

execute_query_save = BigQueryInsertJobOperator(
    task_id="execute_query_insert",
    configuration={
        "query": {
            "query": open(f"{SQL_PATH}/file_sql.sql", "r").read(),
            "writeDisposition": "WRITE_TRUNCATE",
            "useLegacySql": False,
            "destinationTable": {
                'projectId': "project_xxx",
                'datasetId': "dataset_xxx",
                'tableId': "table_target",
            },
        }
    },
)

可能原因 #

• 执行身份权限不足：控制台用的是你的个人账号（已拥有联邦连接访问权限），但Airflow任务使用的服务账号没有访问该联邦连接的权限。
• 任务地域不匹配：联邦连接位于asia-southeast1，但Airflow提交BigQuery任务时未指定地域，导致BigQuery默认在其他地域查找连接，无法定位资源。
• 连接名称拼写错误：SQL文件中的连接字符串可能存在大小写、项目ID/地域/连接名的拼写错误，虽然控制台能正常执行，但Airflow读取的SQL文件存在笔误。

解决办法 #

1. 给Airflow服务账号添加权限

   • 找到Airflow任务使用的服务账号（比如Composer环境的默认服务账号，或自定义的服务账号）。
   • 在GCP控制台的IAM页面，为该服务账号添加BigQuery Connection User角色，确保其有权限访问目标联邦连接。
   • 验证：用该服务账号模拟执行查询，确认能正常访问联邦连接。

2. 指定BigQuery任务的地域

   • 在BigQueryInsertJobOperator中添加location参数，值设置为联邦连接所在的asia-southeast1，确保任务在对应地域执行：

     execute_query_save = BigQueryInsertJobOperator(
         task_id="execute_query_insert",
         location="asia-southeast1",  # 新增地域指定
         configuration={
             "query": {
                 "query": open(f"{SQL_PATH}/file_sql.sql", "r").read(),
                 "writeDisposition": "WRITE_TRUNCATE",
                 "useLegacySql": False,
                 "destinationTable": {
                     'projectId': "project_xxx",
                     'datasetId': "dataset_xxx",
                     'tableId': "table_target",
                 },
             }
         },
     )
     

3. 核对SQL文件中的连接字符串

   • 打开file_sql.sql文件，确认其中EXTERNAL_QUERY的第一个参数完全匹配控制台使用的连接字符串，包括项目ID、地域、连接名的大小写、拼写，无多余空格或符号。

内容的提问来源于stack exchange，提问作者user2506175