使用Python批量将BigQuery数据写入Firestore时遇504超时错误

一、更优的错误处理方式 #

针对批量写入超时问题，结合重试机制、细粒度批次拆分和精准异常捕获可大幅提升稳定性：

1. 针对超时异常的指数退避重试
   捕获Firestore特定的超时/服务不可用异常，用指数退避策略重试，避免短时间重复请求加剧服务压力。可借助tenacity库实现：

from tenacity import retry, stop_after_attempt, wait_exponential, retry_if_exception_type
from google.api_core.exceptions import DeadlineExceeded, ServiceUnavailable

max_batch_size = 200
for i in range(0, len(records), max_batch_size):
    batch_number += 1
    batch = firestore_client.batch()
    batch_records = records[i:i+max_batch_size]
    
    for data in batch_records:
        doc_ref = collection_ref.document()
        batch.set(doc_ref, data)
    
    # 带重试的提交逻辑
    @retry(
        stop=stop_after_attempt(3),  # 最多重试3次
        wait=wait_exponential(multiplier=1, min=2, max=10),  # 等待时间按2s→4s→8s递增
        retry=retry_if_exception_type((DeadlineExceeded, ServiceUnavailable))
    )
    def commit_with_retry():
        batch.commit()
    
    try:
        commit_with_retry()
    except (DeadlineExceeded, ServiceUnavailable):
        print(f"Batch {batch_number} 多次重试后仍失败，建议后续手动处理该批次数据")
        # 可选：将失败批次数据写入GCS存储，便于后续排查修复
    except Exception as e:
        print(f"Batch {batch_number} 发生非超时错误: {str(e)}")

2. 细粒度批次拆分+失败数据隔离
   将批量大小降至100-200，单个批次数据量越小，单次提交的超时概率越低。同时单独记录失败批次，避免少数异常数据拖累整个任务。

3. 数据合法性预检查
   提前验证每条数据的大小（Firestore单文档最大1MB）和字段格式，排除超大文档或非法字段——这类数据往往会导致写入耗时激增甚至超时。

4. 详细日志记录
   记录每个批次的编号、数据范围、执行耗时和错误详情，方便快速定位是特定批次数据异常，还是全局服务限流问题。

二、调整batch.commit()超时时间的方法与建议 #

调整方式 #

Firestore Python客户端支持两种设置超时的方式：

1. 全局设置客户端超时
   初始化客户端时统一配置所有操作的超时时间：

from google.cloud import firestore
from google.api_core.client_options import ClientOptions

# 设置全局超时为120秒
client_options = ClientOptions(timeout=120)
firestore_client = firestore.Client(client_options=client_options)

2. 单次提交单独设置超时
   仅针对当前batch的提交操作设置超时，不影响其他Firestore操作：

batch.commit(timeout=120)  # 单位：秒

注意：需同步调整Cloud Function的函数超时时间（在Cloud Console的函数设置中修改），确保函数本身的超时阈值大于batch提交的超时，避免函数先被系统终止。

是否推荐？ #

不推荐将调整超时作为核心解决方案。超时本质是写入效率或服务压力问题，单纯延长超时只是缓解症状，无法解决根本问题：

• 若因数据量过大导致超时，更推荐使用BigQuery直接导出到Firestore（通过Dataflow或Firestore官方导入工具），无需自行编写批量写入逻辑，效率更高且稳定性更强；
• 若Cloud Function运行时间过长，可将写入任务拆分到Cloud Tasks异步执行，避免在函数中长时间阻塞。

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