tencent cloud

TDSQL Boundless

Distribution Policy

Download
Mode fokus
Ukuran font
Terakhir diperbarui: 2026-08-10 11:31:16
Diterjemahkan oleh AI
Distribution Policy (DP) is the rule system governing data object distribution in TDSQL Boundless. By explicitly setting rules for data objects, the Metadata Service (MC) can perform corresponding scheduling. Through configuring different scheduling rules, users gain granular control over data object distribution, including number of replicas, replica location distribution, and Replication Group Leader placement.

Rules Introduction

Distribution Policy typically consists of multiple specific rules. The Metadata Service validates user-specified rules to ensure their correctness and prevent conflicts between multiple rules. Specific validation rules can be referenced in the Precautions section. The design of individual DP rules draws inspiration from Kubernetes' LabelConstraint, usually structured as JSON containing key, op, and values fields, as shown below:
{"key": "key1", "op": "op1", "values": ["value1","value2"]}
Currently, the rules supported by TDSQL Boundless are as follows:
key
op
values
region
"in", "notIn", "exists", "notExists"
region list, such as ["guangzhou"]
zone
"in", "notIn", "exists", "notExists"
AZ list, such as ["guangzhou-1"]
rack
"in", "notIn", "exists", "notExists"
rack list, such as ["rack-1","rack-2"]
host
"in", "notIn", "exists", "notExists"
host list, such as ["host-1","host-2","host-3"]
node
"in", "notIn"
node list, such as ["node-tdsql3-xxx-001"]
replica-count
"="
number of replicas, such as ["3"]
follower-count
"="
number of RG followers, such as ["2"]
learner-count
"="
number of RG learners, such as ["1"]
witness-count
"="
number of RG witnesses, such as ["1"]
leader-preferences
"="
RG leader preference. For usage, refer to note 2
fault-tolerance-level
"="
disaster recovery level, such as ["zone"]
tdsql-storage-type
"in", "notIn", "exists", "notExists"
disk type list, such as ["CLOUD_TCS","CLOUD_BSSD"]
Note:
1. Operator meaning:
in: the value corresponding to the given key is contained in the given values list.
notIn: the value corresponding to the given key is not contained in the given values list.
exists: contains the given key.
notExists: does not contain the given key.
2. The values for leader-preferences are composed of nested structures, for example: ["{\\"key\\": \\"zone\\", \\"op\\": \\"in\\", \\"values\\": [\\"guangzhou-1\\"]}", "{\\"key\\": \\"zone\\", \\"op\\": \\"in\\", \\"values\\": [\\"guangzhou-2\\"]}"]. For the corresponding SQL syntax of leader-preferences, see Create Distribution Policy.
Note:
1. RG replica rule description: RG leader quantity + RG follower quantity = replica-count - learner-count - witness-count.
When learner-count or witness-count is not specified, the default quantities for both learner and witness are 0.
For example, when replica-count = 4 is specified, it indicates that the RG leader quantity is 1 and the follower quantity is 3.
2. Rule description for using node as key:
2.1 The nodes in values must actually exist in the instance.
2.2 If the number of replicas is specified, the number of nodes in values must be greater than or equal to the number of replicas; otherwise, DP cannot be scheduled.
3. Rule description for using leader-preferences: The location of the RG leader must always be a subset of the replica location constraints. For example, when replica locations are specified in AZs ["zone1", "zone2", "zone3"], the RG leader location must also be specified within these AZs.
Warning:
The metadata service will refuse to schedule when it discovers unreasonable DP settings, but it will not affect the availability of other features or the correctness of data.

Using Distribution Policy

Starting from TDSQL Boundless V21.2.3, you can directly use SQL statements to create, modify, delete, and query Distribution Policy. The keywords in the SQL syntax correspond to the key and op fields in the preceding rule table as follows:
Rule Field
Corresponding SQL Keyword
region
REGION
zone
ZONE
rack
RACK
host
HOST
node
NODE
replica-count
REPLICA_COUNT
follower-count
FOLLOWER_COUNT
learner-count
LEARNER_COUNT
witness-count
WITNESS_COUNT
leader-preferences
LEADER_PREFERENCES
fault-tolerance-level
FAULT_TOLERANCE_LEVEL
tdsql-storage-type
STORAGE_TYPE
in / notIn / exists / notExists
IN / NOT IN / EXISTS / NOT EXISTS
Note:
If the instance kernel version is earlier than v21.2.3, managing Distribution Policy via SQL statements is not currently supported. Please contact Tencent Cloud technical support for assistance.

Enable and Disable Distribution Policy

distribution-policy-enabled is enabled by default starting from v18.0.0 and generally does not require manual configuration. If you need to disable this feature, please contact Tencent Cloud technical support for assistance.

Create Distribution Policy

Use the CREATE DISTRIBUTION POLICY statement to create a DP. A DP can contain multiple rules, which are connected using AND:
CREATE DISTRIBUTION POLICY "$policy_name" SET $key1 $op1 ($value1, $value2, ...) AND $key2 $op2 (...) ...;
Note:
To create a DP, you must specify a policy_name and configure one or more DP rules using the SET clause. For the SQL keywords corresponding to each rule, see the keyword mapping table above.

Modify Distribution Policy

Use the ALTER DISTRIBUTION POLICY statement to modify DP rules, and use the RENAME DISTRIBUTION POLICY statement to modify the DP name:
# Modify the DP rule named policy_1.
ALTER DISTRIBUTION POLICY "policy_1" SET $key $op (...);

# Rename the DP old_dp_name to new_dp_name.
RENAME DISTRIBUTION POLICY "old_dp_name" TO "new_dp_name";
Note:
Only DP rules that are not bound to data objects can be modified. To modify a DP that is already bound to data objects, you must first unbind the data objects from the DP.

Delete Distribution Policy

Use the DROP DISTRIBUTION POLICY statement to delete a DP:
DROP DISTRIBUTION POLICY "$policy_name";
Note:
Only DP rules that are not bound to data objects can be deleted. To delete a DP that is already bound to data objects, you must first unbind the data objects from the DP.

View Distribution Policy

Query created DPs through the system view information_schema.META_CLUSTER_DPS:
# List all created DPs
SELECT * FROM information_schema.META_CLUSTER_DPS;
# View a specific DP by name
SELECT * FROM information_schema.META_CLUSTER_DPS WHERE distribution_policy_name = '$policy_name';

Data Object Binding DP

After a DP is created, you can bind data objects to the DP to achieve the corresponding scheduling effect.

Database DP Binding

CREATE DATABASE db1 USING distribution policy ${policy_name};

Single Table Binding DP

CREATE TABLE t1(a INT) USING distribution policy ${policy_name};

Bind Partitioned Table to DP

CREATE TABLE t1(a INT) PARTITION BY HASH(a) PARTITIONS 4 USING distribution policy ${policy_name};
Note:
DP inheritance rules apply to data objects. For example, in the scenario described above, when database db1 is created and bound to a DP, all single tables and partitioned tables created within this database will inherit the same DP. However, if a different DP is explicitly bound to a specific table within this database, that binding takes precedence over the inheritance rule.

Typical DP Examples

Scenario 1: Create a 5-replica Distribution Policy.
CREATE DISTRIBUTION POLICY "policy_1" SET REPLICA_COUNT = 5;
Scenario 2: Create a 4-replica Distribution Policy that includes one learner.
CREATE DISTRIBUTION POLICY "policy_2" SET REPLICA_COUNT = 4 AND LEARNER_COUNT = 1;
Scenario 3: Create a DP with replicas on node-001, node-002, and node-003, and the RG Leader on node-001.
CREATE DISTRIBUTION POLICY "policy_3" SET NODE IN ("node-001", "node-002", "node-003") AND
LEADER_PREFERENCES = (NODE IN ("node-001"));
Scenario 4: Create a Distribution Policy with replicas placed on SSD disks.
CREATE DISTRIBUTION POLICY "policy_4" SET STORAGE_TYPE IN ("SSD");

Advanced Features

V21.2.3 introduces an advanced DP feature. Partition tables using RANGE or RANGE COLUMNS with a time-type partition key can be bound to this advanced DP. This allows specific partitions within the table to be scheduled after a designated time. A typical use case is automatically cooling down partitions. The details are as follows:
Create the following DP using SQL.
CREATE DISTRIBUTION POLICY "policy_x" SET PARTITION_METHOD = "RANGE" AND
PARTITION_KEY_TO_TIME_TYPE = "predefined:TO_DAYS" AND
EXPIRE = "1 YEAR" AND
START_TIME = "2024-06-11 00:11:22" AND
END_TIME = "2025-06-11 00:11:22" AND
STORAGE_TYPE IN ("HDD");
The keywords in this DP are explained as follows:
PARTITION_METHOD: indicates the partitioning method supported by partitioned tables associated with the DP. Currently, only RANGE and RANGE COLUMNS are supported.
PARTITION_KEY_TO_TIME_TYPE: This key is required only for RANGE partitioning and is used to convert partition boundary values into time types. The values corresponding to this key are conversion functions. The system provides three predefined conversion functions: TO_DAYS, UNIX_TIMESTAMP, and YEAR. Users can also define custom conversion functions. A custom function must provide a calculation formula for year, month, day, hour, minute, and second, following the format: year/month/day/hour/minute/second:(a mathematical formula containing the identifier v), where v is the identifier representing the integer value of the partition boundary. For example, if values are set to ["year:v/100", "month:v%100"], the omitted day/hour/minute/second are treated as zero for their respective time units.
EXPIRE: Partition expiration time, in the format of a positive integer + unit, such as 1 YEAR. Available units include: YEAR, MONTH, DAY, HOUR.
START_TIME: Optional, defaults to the start of the partition. If START_TIME is specified, the DP rule is applied after this time.
END_TIME: Optional, defaults to the end of the partition. If END_TIME is specified, the DP rule will be rejected from being applied after this time.
Note:
1. Only supports related features for first-level RANGE and RANGE COLUMNS partitioning, and its partition key must also be of time type.
2. RANGE COLUMNS partitioning supports only one partition column.

Case Description

Case 1: Automatic Cold Data Archiving Based on UNIX_TIMESTAMP

# Create policy_x1 using the predefined function UNIX_TIMESTAMP
CREATE DISTRIBUTION POLICY "policy_x1" SET PARTITION_METHOD = "RANGE" AND
PARTITION_KEY_TO_TIME_TYPE = ("predefined:UNIX_TIMESTAMP") AND
EXPIRE = "1 MONTH" AND
STORAGE_TYPE IN ("HDD");

# Create a RANGE partitioned table and bind to policy_x1
CREATE TABLE t_order_1(
id bigint NOT NULL,
gmt_modified timestamp NOT NULL)
PARTITION BY RANGE(unix_timestamp(gmt_modified))(
PARTITION p1 VALUES LESS THAN(unix_timestamp('2025-11-11')),
PARTITION p2 VALUES LESS THAN(unix_timestamp('2025-12-11'))
) USING DISTRIBUTION POLICY policy_x1;
Scheduling Behavior Description
p1 Partition Scheduling:
Partition boundary time: 2025-11-11
Expiration time offset: 1 month
Scheduling trigger time: 2025-11-11 + 1 month = 2025-12-11
Scheduling action: Migrate data replicas of the p1 partition to HDD.
p2 Partition Scheduling:
Partition boundary time: 2025-12-11
Expiration time offset: 1 month
Scheduling trigger time: 2025-12-11 + 1 month = 2026-01-11.
Scheduling action: Migrate data replicas of the p2 partition to HDD storage.

Case 2: Custom Time Conversion Function for Precise Scheduling Control

# Create policy_x2 using a custom function
CREATE DISTRIBUTION POLICY "policy_x2" SET PARTITION_METHOD = "RANGE" AND
PARTITION_KEY_TO_TIME_TYPE = ("year:v/100", "month:v%100") AND
EXPIRE = "1 MONTH" AND
LEADER_PREFERENCES = (ZONE in ("zone1")) AND
START_TIME = "2025-12-10 00:00:00";

# Create a RANGE partition table and bind it to policy_x2
CREATE TABLE t_order_2(
id bigint NOT NULL,
gmt_modified datetime NOT NULL)
PARTITION BY RANGE(YEAR(gmt_modified) * 100 + MONTH(gmt_modified))(
PARTITION p1 VALUES LESS THAN(202511),
PARTITION p2 VALUES LESS THAN(202512),
PARTITION p3 VALUES LESS THAN(202601)
) USING DISTRIBUTION POLICY policy_x2;
Conversion Function Parsing
Custom function: year:v/100, month:v%100

The partition boundary value v = YEAR(gmt_modified) * 100 + MONTH(gmt_modified)

Example calculation:
- p1: v=202511 → year=202511/100=2025, month=202511%100=11
- p2: v=202512 → year=202512/100=2025, month=202512%100=12
- p3: v=202601 → year=202601/100=2026, month=202601%100=1
Partition Time Boundary Calculation
Partitioning Operations
Boundary Value
Converted Time
Scheduling Trigger Time
Whether Constrained
p1
202511
2025-11-01 00:00:00
2025-12-01 00:00:00
Unconstrained
p2
202512
2025-12-01 00:00:00
2026-01-01 00:00:00
Unconstrained
p3
202601
2026-01-01 00:00:00
2026-02-01 00:00:00
Constrained
START_TIME Impact Analysis
START_TIME = "2025-12-10 00:00:00"
Only partitions with a partition boundary time ≥ START_TIME will apply the DP constraint.
p1(2025-11-01) and p2(2025-12-01) < START_TIME(2025-12-10) → unconstrained
p3(2026-01-01) > START_TIME(2025-12-10) → constrained.

Case 3: Time Window Scheduling for RANGE COLUMNS Partitioning

# Create policy_x3
CREATE DISTRIBUTION POLICY "policy_x3" SET PARTITION_METHOD = "RANGE COLUMNS" AND
EXPIRE = "1 YEAR" AND
NODE NOT IN ("node-tdsql3-x-001") AND
START_TIME = "2025-12-10 00:00:00" AND
END_TIME = "2026-12-10 00:00:00";

# Create a RANGE COLUMNS partition table and bind to policy_x3
CREATE TABLE t_order_3(
id bigint NOT NULL,
gmt_modified datetime NOT NULL)
PARTITION BY RANGE COLUMNS(gmt_modified)(
PARTITION p1 VALUES LESS THAN("2024-12-10 00:00:00"),
PARTITION p2 VALUES LESS THAN("2025-12-10 00:00:00"),
PARTITION p3 VALUES LESS THAN("2026-12-10 00:00:00"),
PARTITION p4 VALUES LESS THAN("2027-12-10 00:00:00")
) USING DISTRIBUTION POLICY policy_x3;
Since it is a DP bound to RANGE COLUMNS time partitions, there is no need to use the PARTITION_KEY_TO_TIME_TYPE field to provide a conversion function, as the partition boundaries are already time-type values. Simultaneously, because START_TIME and END_TIME are specified, only partitions p2 and p3 will initiate scheduling one year after the partition boundary time is reached (EXPIRE = "1 YEAR").
Partitioning Operations
Boundary Time
Scheduling Trigger Time
Whether Within the Time Window
p1
2024-12-10
2025-12-10
Earlier than START_TIME
p2
2025-12-10
2026-12-10
Within [START_TIME, END_TIME]
p3
2026-12-10
2027-12-10
Within [START_TIME, END_TIME]
p4
2027-12-10
2028-12-10
Later than END_TIME

Bantuan dan Dukungan

Apakah halaman ini membantu?

masukan