All Products
Search

This Product

    PolarDB:Hints

    Document Center

    PolarDB:Hints

    Last Updated:Aug 27, 2026

    This topic describes the purpose and basic syntax of custom hints.

    This topic applies to PolarDB-X 1.0 5.3 and later.

    Introduction

    A hint is a directive that supplements standard SQL syntax. In a relational database, hints let you influence a statement's execution and apply specific optimizations.

    PolarDB-X 1.0 also provides a special hint syntax. For example, if you know that your target data resides in specific table shards within certain database shards, you can use a custom hint in PolarDB-X 1.0 to route the SQL statement directly to those database shards.

    PolarDB-X 1.0 custom hint syntax

    Syntax

     /*+TDDL: hint_command [hint_command ...]*/
 /!+TDDL: hint_command [hint_command ...]*/

    Notes

    • Custom hints in PolarDB-X 1.0 support two formats: /*+TDDL:hint_command*/ and /!+TDDL:hint_command*/.
    • A hint must be enclosed in either /* and */ or /! and */, and start with +TDDL:. The hint_command specifies a custom hint operation in PolarDB-X 1.0. If you use multiple hint_commands, separate them with spaces.
    • If you use the /*+TDDL:hint_command*/ format, add the -c parameter to your logon command when you use the MySQL command-line client to execute SQL statements with custom PolarDB-X 1.0 hints. Custom hints in PolarDB-X 1.0 are implemented as MySQL comments. Without the -c parameter, the client strips these comments before sending the SQL statement to the server, causing the custom PolarDB-X 1.0 hint to be ignored. For more information, see mysql Client Options.

    Example

    # Query the physical table name in each database shard.
/*+TDDL:scan()*/SHOW TABLES;

# Route the query to database shard 0000 of a read-only ApsaraDB RDS instance.
/*+TDDL:node(0) slave()*/SELECT * FROM t1;

    In the examples, /*+TDDL:scan()*/ and /*+TDDL:node(0) slave()*/ are custom hints for PolarDB-X 1.0 and start with +TDDL:. The commands scan(), node(0), and slave() are custom hint commands in PolarDB-X 1.0. Multiple hint commands are separated by spaces.

    Using hints in SQL statements

    PolarDB-X 1.0 supports hints in DML, DDL, and DAL statements. The syntax is as follows:

    • For all supported statements, you can add a hint before the statement. Example:
      /*+TDDL: ... */ SELECT ...
/*+TDDL: ... */ INSERT ...
/*+TDDL: ... */ REPLACE ...
/*+TDDL: ... */ UPDATE ...
/*+TDDL: ... */ DELETE ...
/*+TDDL: ... */ CREATE TABLE ...
/*+TDDL: ... */ ALTER TABLE ...
/*+TDDL: ... */ DROP TABLE ...
/*+TDDL: ... */ SHOW ...
...
    • For DML statements, you can add a hint after the first keyword. Example:
      SELECT /*+TDDL: ... */  ...
INSERT /*+TDDL: ... */  ...
REPLACE /*+TDDL: ... */  ...
UPDATE /*+TDDL: ... */  ...
DELETE /*+TDDL: ... */  ...
...
      Note The supported statements vary by hint. For details, see the documentation for each hint command.

    Using multiple hint commands

    PolarDB-X 1.0 allows you to use multiple hint commands within a single hint block. Example:

    SELECT /*+TDDL:node(0) slave()*/ ...;

    PolarDB-X 1.0 does not support using hints in the following ways:

    # Multiple hint blocks are not supported in a single SQL statement.
SELECT /*+TDDL:node(0)*/ /*+TDDL:slave()*/ ...;

# Duplicate hint commands are not supported within a single hint block.
SELECT /*+TDDL:node(0) node(1)*/ ...;

    PolarDB-X 1.0 custom hint categories