tencent cloud

TDSQL Boundless

DocumentationTDSQL BoundlessGeneral ReferenceSQL ReferenceData DictionaryINFORMATION_SCHEMAPROXY_DECISION

PROXY_DECISION

Download
Focus Mode
Font Size
Last updated: 2026-07-13 17:17:19

Function

INFORMATION_SCHEMA.PROXY_DECISION displays the proxy routing decision trace information for the most recent SQL statements within the current session. After an SQL statement enters a compute node, the system determines its proxy feasibility at three stages: dispatch pre-check, before Prepare, and after Prepare. It then decides whether to directly proxy the statement to a remote node for execution or fall back to the local node. The view records the final decision action and the complete decision path for each statement in chronological order, facilitating the diagnosis of issues such as unexpected SQL routing, proxy rejection, or proxy execution failure.
This view is a session-level view. Each session independently retains its own decision history, and data between different sessions is not visible to each other. The data collection and retention behavior of the view is controlled by the following system variables:
tdsql_enable_proxy_decision: Whether to enable decision tracing. The default value is OFF.
tdsql_proxy_decision_history_size: The maximum number of decision rows retained per session. The default value is 10.
tdsql_proxy_decision_max_mem_size: The maximum number of bytes that a single decision record is allowed to occupy. The default value is 1048576 (1 MB).
Note:
Querying the session-level view itself is not recorded as a new proxy decision. Newly executed SQL statements are written to this view only when tdsql_enable_proxy_decision is ON. Switching this variable from ON to OFF clears the historical records of the current session.

Field Description

Field Name
Data Type
Description
SEQ
bigint unsigned
The decision sequence number within the current session monotonically increases in the order of SQL entering the compute node. You can obtain the most recent record by combining it with ORDER BY SEQ DESC.
QUERY
varchar(65535)
The original text of the traced SQL statement. The statement length is limited by tdsql_proxy_decision_max_mem_size and will be truncated if it exceeds the limit.
FINAL_ACTION
varchar(64)
The final routing action of the SQL. The value is as follows:
proxy_remote: Successfully proxied to a remote node for execution.
exec_in_this_node: Execute locally on the current node.
fallback_to_local: Originally determined to be executed via proxy, but falls back to the local node for execution due to certain reasons.
error_before_proxy: An error occurs before the proxy is entered.
error: An error occurs during the proxy process.
TRACE
varchar(65535)
The complete proxy decision path is expressed in JSON text format. It contains two parts: the phases array and the final object.
phases: An array of decision phases. Each phase object is identified by the phase field, which indicates the phase (with possible values of dispatch_precheck, before_prepare, and post_prepare). The steps field records the decision steps triggered in that phase. Each step contains the stage (name of the decision item), outcome (decision result, such as accept / reject / defer / choose / remote), cause (reason for the decision), and the optional detail (supplementary information).
final: The final decision object, which contains action (same as the FINAL_ACTION column) and reason (the cause of the final action).
When a single record exceeds the tdsql_proxy_decision_max_mem_size limit, the TRACE content is safely truncated, but the returned string is still guaranteed to be valid JSON.
MISSING_BYTES_BEYOND_MAX_MEM_SIZE
int unsigned
The number of bytes truncated and discarded due to the tdsql_proxy_decision_max_mem_size limit. A value of 0 indicates that the current record is not truncated. A non-0 value indicates that truncation has occurred, and you can appropriately increase tdsql_proxy_decision_max_mem_size to retain the complete TRACE.

Examples

Example 1: Enable decision tracing and query the final action and decision path of the most recent SQL statement.
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
Output example:
*************************** 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
Example 2: Diagnose SQL statements that are not proxied as expected and locate the reasons for their rejection.
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
Output example:
*************************** 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"}}
By checking outcome=reject and cause=broadcast_all_nodes in the TRACE, you can determine that this SQL statement was identified as a query that needs to be broadcast to all nodes. Consequently, it was rejected for proxy during the before_prepare phase and was ultimately executed on the local node.
Example 3: Check the distribution of SQL proxy actions over a recent period and determine whether a large number of local fallbacks exist.
SELECT FINAL_ACTION, COUNT(*) AS cnt
  FROM information_schema.PROXY_DECISION
  GROUP BY FINAL_ACTION
  ORDER BY cnt DESC;
Output example:
+-------------------+-----+
| FINAL_ACTION      | cnt |
+-------------------+-----+
| proxy_remote      |   7 |
| exec_in_this_node |   2 |
| fallback_to_local |   1 |
+-------------------+-----+
If the proportion of fallback_to_local is high, you can analyze the fallback reason by referring to the TRACE column of the corresponding row. Then, determine whether you need to adjust the routing configuration or troubleshoot node connectivity.
Example 4: Identify truncated TRACE entries by using MISSING_BYTES_BEYOND_MAX_MEM_SIZE and increase the quota to retain complete content.
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;
After you increase tdsql_proxy_decision_max_mem_size, newly written decision records retain TRACE content according to the higher limit. However, previously written historical records are not automatically refilled.
Previous Topic: PROCESSLISTNext Topic: QUERY_AUDIT_LOG

Help and Support

Was this page helpful?

Help us improve! Rate your documentation experience in 5 mins.

Feedback