如何通过Python SDK查看及配置Couchbase集群超时时间

咱们先理清楚一个很容易踩的坑：客户端级超时和集群级查询超时是完全独立的两个设置——你之前用ClusterTimeoutOptions没效果，大概率是因为你要改的是集群侧的全局查询超时，而这个类管的是你的Python客户端自身等待响应的超时时间。下面分步骤解决你的问题：

一、查看当前集群的查询超时值 #

要获取集群层面的查询超时（就是你用couchbase-cli修改的那个值），可以通过Python SDK的Cluster对象调用query_settings()方法，直接读取集群的查询配置：

from couchbase.cluster import Cluster
from couchbase.auth import PasswordAuthenticator

# 连接集群
cluster = Cluster.connect(
    "couchbase://your-cluster-host",
    PasswordAuthenticator("your-username", "your-password")
)

# 获取集群查询设置
query_config = cluster.query_settings()
# 返回的timeout值是毫秒数，-1表示禁用超时
print(f"当前集群查询超时: {query_config.timeout} 毫秒")

二、配置集群级的查询超时 #

如果要修改集群侧的查询超时（和couchbase-cli setting-query --set --timeout -1效果完全一致），不能用ClusterTimeoutOptions，而是要用update_query_settings()方法：

# 设置集群查询超时为-1（禁用超时）
cluster.update_query_settings(timeout=-1)

# 验证设置是否生效
updated_config = cluster.query_settings()
print(f"更新后集群查询超时: {updated_config.timeout} 毫秒")

如果需要设置具体的超时时长（比如5秒），直接把timeout参数改成对应的毫秒数即可：

# 设置为5000毫秒（5秒）
cluster.update_query_settings(timeout=5000)

三、关于ClusterTimeoutOptions的正确用法 #

如果你其实是想设置Python客户端自身的超时（比如你的程序最多等5秒就放弃等待查询结果，不管集群那边有没有执行完），那ClusterTimeoutOptions才是正确的工具，用法如下：

from couchbase.cluster import Cluster, ClusterOptions
from couchbase.cluster import ClusterTimeoutOptions
from couchbase.auth import PasswordAuthenticator

# 创建客户端超时配置：设置查询超时为5000毫秒（5秒）
client_timeout_opts = ClusterTimeoutOptions(query_timeout=5000)
cluster_opts = ClusterOptions(
    PasswordAuthenticator("your-username", "your-password"),
    timeout_options=client_timeout_opts
)

# 用带超时配置的选项连接集群
cluster = Cluster.connect("couchbase://your-cluster-host", cluster_opts)

# 后续执行查询时，客户端会在5秒内没收到结果就抛出超时异常
result = cluster.query("SELECT * FROM `your-bucket` LIMIT 10")

关键提醒 #

• 确保你使用的是Couchbase Python SDK 3.x及以上版本，2.x的API和上述方法差异很大，不兼容。
• 集群级超时是全局生效的，所有客户端的查询都会受这个设置限制；而客户端级超时只对你的Python程序生效，和其他客户端无关。

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