All Products
Search

This Product

    PolarDB:Execute SQL statements on specified database shards

    Document Center

    PolarDB:Execute SQL statements on specified database shards

    Last Updated:Mar 30, 2026

    NODE HINT routes an SQL statement to one or more specified database shards in PolarDB-X 1.0, bypassing the default routing logic. This is supported in PolarDB-X 1.0 V5.3 and later.

    This topic applies to PolarDB-X 1.0 V5.3 and later.

    Use cases

    • Unsupported SQL statements: When PolarDB-X 1.0 does not support a particular SQL statement, use NODE HINT to send it directly to the underlying database shard for execution.

    • Shard-specific queries: When you need to query data in a specific database shard or a specific table shard within a database shard, use NODE HINT to target that shard directly.

    How it works

    All examples in this document follow the same pattern:

    1. Run SHOW NODE to list the database shards and get their names.

    2. Copy the shard name you want to target.

    3. Embed the shard name in the node() hint and prefix it to your SQL statement.

    4. Run the SQL statement on the MySQL command-line client. If you use the standard /*+TDDL:*/ hint format, add the -c flag; otherwise the client strips comments before sending the statement to the server.

    Syntax

    NODE HINT uses shard names as routing targets. A shard name is the unique identifier of a database shard in a PolarDB-X 1.0 database. Run SHOW NODE to get the shard names.

    PolarDB-X 1.0 supports two hint formats:

    Format Syntax Notes
    Standard /*+TDDL:hint_command*/ Requires the -c flag on the MySQL command-line client; otherwise the client strips comments before sending the statement to the server. See Troubleshooting.
    Alternative /!+TDDL:hint_command*/ Works without the -c flag.

    Route to a single shard:

    /*+TDDL:node('node_name')*/

    Route to multiple shards:

    /*+TDDL:node('node_name'[,'node_name1','node_name2'])*/

    Separate multiple shard names with commas.

    Important

    When you run an SQL statement with a NODE HINT, the table names in the statement must exist in the specified shards. If a NODE HINT is inside an INSERT statement that contains a sequence definition for the target table, the sequence does not take effect. For more information, see Limits.

    NODE HINT works with DML, DDL, and Data Access Language (DAL) statements.

    Examples

    The following examples use a PolarDB-X 1.0 database named drds_test.

    Get shard names

    Run SHOW NODE to list the shards and their names:

    mysql> SHOW NODE\G

    Sample output:

    *************************** 1. row ******************
                 ID: 0
               NAME: DRDS_TEST_1473471355140LRPRDRDS_TEST_VTLA_0000_RDS
  MASTER_READ_COUNT: 212
   SLAVE_READ_COUNT: 0
MASTER_READ_PERCENT: 100%
 SLAVE_READ_PERCENT: 0%
*************************** 2. row ******************
                 ID: 1
               NAME: DRDS_TEST_1473471355140LRPRDRDS_TEST_VTLA_0001_RDS
  MASTER_READ_COUNT: 29
   SLAVE_READ_COUNT: 0
MASTER_READ_PERCENT: 100%
 SLAVE_READ_PERCENT: 0%
...
8 rows in set (0.02 sec)

    The NAME field is the unique identifier for each shard. For example, DRDS_TEST_1473471355140LRPRDRDS_TEST_VTLA_0003_RDS corresponds to the physical database shard drds_test_vtla_0003.

    Route to a single shard

    Execute a SELECT statement on shard 0:

    SELECT /*TDDL:node('DRDS_TEST_1473471355140LRPRDRDS_TEST_VTLA_0000_RDS')*/ * FROM table_name;

    Route to multiple shards

    Execute a SELECT statement on shards 0 and 6:

    SELECT /*TDDL:node('DRDS_TEST_1473471355140LRPRDRDS_TEST_VTLA_0000_RDS','DRDS_TEST_1473471355140LRPRDRDS_TEST_VTLA_0006_RDS')*/ * FROM table_name;

    The statement runs on both the DRDS_TEST_1473471355140LRPRDRDS_TEST_VTLA_0000_RDS shard and the DRDS_TEST_1473471355140LRPRDRDS_TEST_VTLA_0006_RDS shard.

    View the physical execution plan on a shard

    /*TDDL:node('DRDS_TEST_1473471355140LRPRDRDS_TEST_VTLA_0000_RDS')*/ EXPLAIN SELECT * FROM table_name;

    Physical table names

    • Random suffixes (DRDS V5.4.1 and later): PolarDB-X 1.0 appends a four-character random string to the names of physical tables for table shards. Run SHOW TOPOLOGY to get the topological relationships between logical tables and their physical tables.

    • Disable random suffixes (DRDS V5.4.4 and later): PolarDB-X 1.0 provides the ENABLE_RANDOM_PHY_TABLE_NAME switch to control whether physical table names include a random string. The switch is enabled by default.

      • To disable it for all tables in an instance: log in to the DRDS console, click the instance ID, go to Parameter Settings in the left-side navigation pane, click the Database tab, and set ENABLE_RANDOM_PHY_TABLE_NAME to false.

      • To disable it for specific tables in a single statement, use the following hint: /*+TDDL:cmd_extra(ENABLE_RANDOM_PHY_TABLE_NAME=FALSE)*/

    Troubleshooting

    NODE HINT has no effect on the MySQL command-line client

    Cause: When you use the standard hint format (/*+TDDL:hint_command*/), the MySQL command-line client strips comments before sending the statement to the server. As a result, PolarDB-X 1.0 never receives the hint.

    Solution: Add the -c flag when logging in to the MySQL command-line client:

    mysql -h <host> -P <port> -u <username> -p -c

    The -c flag tells the client to preserve comments. For more information, see mysql client options.

    Alternatively, use the /!+TDDL:hint_command*/ format, which does not require the -c flag.

    What's next

    • Limits — Limits on sequences and how to troubleshoot primary key conflicts

    • MySQL comments — MySQL comment syntax reference