PolarDB-X hints let you override the default query execution behavior by embedding directives directly in SQL statements. Use hints to route queries to specific database shards, target read-only instances, or set the workload type for a query.
Syntax
PolarDB-X supports two hint formats:
/*+TDDL: hint_command [hint_command ...]*/
/!+TDDL: hint_command [hint_command ...]*/A single SQL statement can contain one hint with one or more hint commands.
-c flag to your login command when running SQL statements that contain PolarDB-X hints. Without -c, the client strips the hint before sending the statement to the server—because the /*+TDDL:...*/ format looks like a MySQL comment—and the hint has no effect. See mysql client options for details.Available hint commands
| Hint command | Purpose | Example |
|---|---|---|
scan() | Queries the names of the physical tables in each database shard | /*+TDDL:scan()*/SHOW TABLES; |
node(n) | Routes the query to the specified shard | /*+TDDL:node(0)*/SELECT * FROM t1; |
slave() | Routes the query to a read-only ApsaraDB RDS instance | /*+TDDL:node(0) slave()*/SELECT * FROM t1; |
WORKLOAD=AP | Sets the workload type to analytical processing (AP) | /*+TDDL:WORKLOAD=AP*/SELECT * FROM t1; |
Examples
List physical tables across all shards
Use scan() to query the names of the physical tables in each database shard.
/*+TDDL:scan()*/SHOW TABLES;Route a query to a specific shard
Use node(n) to send a query to a specific database shard.
/*+TDDL:node(0)*/SELECT * FROM t1;Route a query to a read-only instance
Use slave() to route a query to a read-only ApsaraDB RDS instance. The following example routes the query to Database Shard 0000 of a read-only ApsaraDB RDS instance:
/*+TDDL:node(0) slave()*/SELECT * FROM t1;Combine multiple hint commands
Combine hint commands in a single hint to apply multiple directives at once. The following example routes the query to shard 0 of a read-only ApsaraDB RDS instance:
/*+TDDL:node(0) slave()*/SELECT * FROM t1;Alternatively, place the hint after the leading keyword:
SELECT /*+TDDL:node(0) slave()*/ * FROM t1;Set the workload type
Use WORKLOAD=AP to mark a query as an analytical processing workload.
/*+TDDL:WORKLOAD=AP*/SELECT * FROM t1;Limitations
One hint per statement. A single SQL statement cannot contain more than one hint comment block. The following is invalid:
-- Invalid: two separate hint blocks SELECT /*+TDDL:node(0)*/ /*+TDDL:slave()*/ * FROM t1;Instead, combine both commands in a single hint:
SELECT /*+TDDL:node(0) slave()*/ * FROM t1;No duplicate hint commands. A hint cannot repeat the same command. The following is invalid:
-- Invalid: node() appears twice SELECT /*+TDDL:node(0) node(1)*/ * FROM t1;