文档反馈官招募中，报名立赚积分兑换代金券！> HOT
文档中心>TDSQL Boundless>通用参考>SQL 参考>数据字典>INFORMATION_SCHEMA>PROXY_DECISION

PROXY_DECISION

最近更新时间：2026-06-29 09:44:33

我的收藏

本页目录：

功能

INFORMATION_SCHEMA.PROXY_DECISION 用于展示 当前会话内最近若干条 SQL 语句的代理路由决策追踪信息。当一条 SQL 进入计算节点后，系统会在派发预检、Prepare 之前、Prepare 之后三个阶段对该语句进行代理可行性判定，并最终决定是直接代理到远端节点执行，还是回退到本节点执行。视图按时序记录每一条语句的决策最终动作以及完整的判定路径，便于诊断 SQL 路由不符合预期、代理被拒绝、代理执行失败等问题。
该视图为会话级视图，每个会话独立保留各自的决策历史，不同会话之间的数据互不可见。视图的数据采集与保留行为受以下系统变量控制：
tdsql_enable_proxy_decision：是否开启决策追踪，默认 OFF。
tdsql_proxy_decision_history_size：单个会话最多保留的决策行数，默认 10。
tdsql_proxy_decision_max_mem_size：单条决策记录允许占用的最大字节数，默认 1048576（1 MB）。
说明：
会话级视图查询本身不会被记录为一条新的代理决策。仅当 tdsql_enable_proxy_decision 为 ON 时，新执行的 SQL 才会写入该视图；将该变量从 ON 切换为 OFF 会清空当前会话的历史记录。

字段说明

字段名
数据类型
说明
SEQ
bigint unsigned
当前会话内的决策序号，按 SQL 进入计算节点的时间顺序单调递增。结合 ORDER BY SEQ DESC 可获取最近一条记录。
QUERY
varchar(65535)
被追踪的 SQL 语句原文。语句长度受 tdsql_proxy_decision_max_mem_size 限制，超出时会被截断。
FINAL_ACTION
varchar(64)
该 SQL 的最终路由动作，取值如下：
proxy_remote：成功代理到远端节点执行。
exec_in_this_node：在当前节点本地执行。
fallback_to_local：原本判定为代理执行，但因故回退到本节点执行。
error_before_proxy：在进入代理前发生错误。
error：代理过程中发生错误。
TRACE
varchar(65535)
完整的代理决策路径，使用 JSON 文本格式表达。包含 phases 数组与 final 对象两部分：
phases：决策阶段数组，每个阶段对象由 phase 字段标识所处阶段（取值为 dispatch_precheck、before_prepare、post_prepare），steps 字段记录该阶段触发的判定步骤；每个步骤包含 stage（判定项名称）、outcome（判定结果，如 accept / reject / defer / choose / remote）、cause（判定原因）以及可选的 detail（补充信息）。
final：最终决策对象，包含 action（同 FINAL_ACTION 列）和 reason（最终动作产生的原因）。
当单条记录超过 tdsql_proxy_decision_max_mem_size 限制时，TRACE 内容会被安全截断，但仍保证返回的字符串是合法 JSON。
MISSING_BYTES_BEYOND_MAX_MEM_SIZE
int unsigned
因 tdsql_proxy_decision_max_mem_size 限制而被截断丢弃的字节数。值为 0 表示当前记录未发生截断；非 0 表示已发生截断，可适当调大 tdsql_proxy_decision_max_mem_size 以保留完整 TRACE。

示例

示例 1：开启决策追踪，并查询最近一条 SQL 的最终动作与决策路径。
SET SESSION tdsql_enable_proxy = ON;
SET SESSION tdsql_enable_proxy_decision = ON;
SELECT /*+ PROXY(1) */ SUM(v) FROM t1;
SELECT * FROM information_schema.PROXY_DECISION ORDER BY SEQ DESC LIMIT 1\\G
输出示例：
*************************** 1. row ***************************
                              SEQ: 12
                            QUERY: SELECT /*+ PROXY(1) */ SUM(v) FROM t1
                     FINAL_ACTION: proxy_remote
                            TRACE: {"phases": [{"phase": "dispatch_precheck", "steps": [{"stage": "can_proxy_in_dispatch", "outcome": "defer", "cause": "regular_dml_deferred_to_prepare"}]}, {"phase": "before_prepare", "steps": [{"stage": "can_proxy_sql_property", "outcome": "accept", "cause": "hint_node_id_forced"}]}, {"phase": "post_prepare", "steps": [{"stage": "proxy_if_possible", "outcome": "choose", "cause": "initiative_proxy"}, {"stage": "determine_executor_node", "outcome": "choose", "cause": "route_found", "detail": "node_id=1"}, {"stage": "prepare_proxy_transaction", "outcome": "choose", "cause": "proxy_transaction_prepared", "detail": "node_id=1"}, {"stage": "proxy_query", "outcome": "remote", "cause": "proxy_remote"}]}], "final": {"action": "proxy_remote", "reason": "proxy_remote"}}
MISSING_BYTES_BEYOND_MAX_MEM_SIZE: 0
示例 2：诊断未按预期代理的 SQL，定位被拒原因。
SET SESSION tdsql_enable_proxy = ON;
SET SESSION tdsql_enable_proxy_decision = ON;
/*## broadcast */ SELECT COUNT(*) FROM t1;
SELECT FINAL_ACTION, TRACE
  FROM information_schema.PROXY_DECISION
  ORDER BY SEQ DESC LIMIT 1\\G
输出示例：
*************************** 1. row ***************************
FINAL_ACTION: exec_in_this_node
       TRACE: {"phases": [{"phase": "dispatch_precheck", "steps": [{"stage": "can_proxy_in_dispatch", "outcome": "defer", "cause": "regular_dml_deferred_to_prepare"}]}, {"phase": "before_prepare", "steps": [{"stage": "can_proxy_sql_property", "outcome": "reject", "cause": "broadcast_all_nodes"}]}, {"phase": "post_prepare", "steps": []}], "final": {"action": "exec_in_this_node", "reason": "rejected_before_proxy"}}
通过 TRACE 中的 outcome=reject、cause=broadcast_all_nodes 可定位到：该 SQL 因被识别为需要广播到所有节点的查询，从而在 before_prepare 阶段被拒绝代理，最终在本节点执行。
示例 3：检查最近一段时间内 SQL 的代理动作分布，统计是否存在大量本地回退。
SELECT FINAL_ACTION, COUNT(*) AS cnt
  FROM information_schema.PROXY_DECISION
  GROUP BY FINAL_ACTION
  ORDER BY cnt DESC;
输出示例：
+-------------------+-----+
| FINAL_ACTION      | cnt |
+-------------------+-----+
| proxy_remote      |   7 |
| exec_in_this_node |   2 |
| fallback_to_local |   1 |
+-------------------+-----+
若 fallback_to_local 占比偏高，可结合对应行的 TRACE 列分析回退原因，进而判断是否需要调整路由配置或排查节点连通性。
示例 4：通过 MISSING_BYTES_BEYOND_MAX_MEM_SIZE 识别被截断的 TRACE，并调大配额以保留完整内容。
SELECT SEQ, MISSING_BYTES_BEYOND_MAX_MEM_SIZE
  FROM information_schema.PROXY_DECISION
  WHERE MISSING_BYTES_BEYOND_MAX_MEM_SIZE > 0;

SET SESSION tdsql_proxy_decision_max_mem_size = 4194304;
将 tdsql_proxy_decision_max_mem_size 调大后，新写入的决策记录将按更大的上限保留 TRACE 内容；已写入的历史记录不会自动重新填充。
中国站