BigQuery Python 客户端 - 超时参数的含义，以及如何设置查询结果超时

Question

这个问题是关于BigQuery Python客户端中QueryJob对象的result方法中的timeout参数。

看起来timeout的含义相对于版本 1.24.0 已经发生了变化。

例如， 版本 1.24.0 中 QueryJob result的文档指出超时是：

在使用重试之前等待底层 HTTP 传输的秒数。 如果在后台发出多个请求，超时被解释为所有请求的大致总时间。

据我了解，这可以用作限制result方法调用等待result的总时间的一种方式。

例如，考虑以下脚本：

import logging

from google.cloud import bigquery

# Set logging level to DEBUG in order to see the HTTP requests
# being made by urllib3
logging.basicConfig(level=logging.DEBUG)

PROJECT_ID = "project_id" # replace by actual project ID

client = bigquery.Client(project=PROJECT_ID)

QUERY = ('SELECT name FROM `bigquery-public-data.usa_names.usa_1910_2013` '
        'WHERE state = "TX" '
        'LIMIT 100')
TIMEOUT = 30  # in seconds
query_job = client.query(QUERY)  # API request - starts the query
assert query_job.state == 'RUNNING'

# Waits for the query to finish
iterator = query_job.result(timeout=TIMEOUT)
rows = list(iterator)

assert query_job.state == 'DONE'

据我了解，如果所有涉及获取结果的 API 调用加起来超过 30 秒，那么对result的调用就会放弃。 因此，这里的timeout用于限制result方法调用的总执行时间。

但是，后来的版本引入了更改。 例如， 1.27.2 中result的文档指出超时是：

在使用重试之前等待底层 HTTP 传输的秒数。 如果在后台发出多个请求，则超时适用于每个单独的请求。

如果我正确理解这一点，上面的示例完全改变了含义，并且对result的调用可能需要超过 30 秒。

我的疑问是：

1. 如果我使用新版本的result与旧版本运行它，上面的脚本到底有什么区别？
2. 当前推荐的timeout时值传递给result用例是什么？
3. 在等待查询结果时，当前推荐的在给定总时间后超时的方法是什么？

谢谢你。

Answer 1

正如您在此修复程序中看到的：

传输层超时独立于查询超时，即等待查询完成的最长时间。

查询超时由阻塞轮询使用，以便后端在轮询作业完成时不会阻塞太长时间，但传输可以有不同的超时要求，我们不希望它有时会引发不必要的超时错误。

• 对每个底层请求应用超时

由于作业方法不再在方法可能发出的所有请求之间拆分超时，因此客户端方法以相同的方式进行调整。

所以基本的区别是，在以前的版本中，如果在下面的层中发出许多请求，它们将共享 30 秒超时。 换句话说，如果第一个请求需要 20 秒，第二个请求将在 10 秒后超时。 在新版本中，每个请求都有 30 秒。

关于用例，基本上取决于您的应用程序。 如果您不能为可能丢失的请求等待很长时间，则可以减少超时。