Tencent Cloud Docs JP

テーマ

元ドキュメント: Distribution Policy

Distribution Policy ​

Distribution Policy（DP）は、TDSQL Boundless におけるデータオブジェクトの分散を管理するルールシステムです。データオブジェクトに対して明示的にルールを設定することで、メタデータサービス（MC）が対応するスケジューリングを実行できます。異なるスケジューリングルールを設定することで、以下のようなデータオブジェクトの分散をきめ細かく制御できます。

  • レプリカ数
  • レプリカの配置場所
  • Replication Group の Leader 配置

ルールの概要 ​

Distribution Policy は通常、複数の具体的なルールで構成されます。メタデータサービスは、ユーザーが指定した複数のルールを検証し、ルール自体の正確性および複数のルール間で矛盾が発生しないことを確認します。具体的な検証ルールについては「注意事項」を参照してください。DP の個々のルールは Kubernetes の LabelConstraint の設計を参考にしており、通常 key、op、values フィールドを含む JSON で構成されます。

json
{"key": "key1", "op": "op1", "values": ["value1","value2"]}

TDSQL Boundless で現在サポートされているルールは以下のとおりです。

keyopvalues
regionin、notIn、exists、notExistsリージョンリスト（例: ["guangzhou"]）
zonein、notIn、exists、notExistsアベイラビリティゾーンリスト（例: ["guangzhou-1"]）
rackin、notIn、exists、notExistsラックリスト（例: ["rack-1","rack-2"]）
hostin、notIn、exists、notExistsホストリスト（例: ["host-1","host-2","host-3"]）
nodein、notInノードリスト（例: ["node-tdsql3-xxx-001"]）
replica-count=レプリカ数（例: ["3"]）
follower-count=RG Follower 数（例: ["2"]）
learner-count=RG Learner 数（例: ["1"]）
witness-count=RG Witness 数（例: ["1"]）
leader-preferences=RG Leader の優先配置。使用方法は説明2を参照
fault-tolerance-level=ディザスタリカバリレベル（例: ["zone"]）
tdsql-storage-typein、notIn、exists、notExistsディスクタイプリスト（例: ["CLOUD_TCS","CLOUD_BSSD"]）

説明:

  1. オペレータの意味:

    • in: 指定された key に対応する value が、指定された values リストに含まれる
    • notIn: 指定された key に対応する value が、指定された values リストに含まれない
    • exists: 指定された key を含む
    • notExists: 指定された key を含まない

  2. leader-preferences の values はネスト構造で構成されます。例: ["{\"key\": \"zone\", \"op\": \"in\", \"values\": [\"guangzhou-1\"]}", "{\"key\": \"zone\", \"op\": \"in\", \"values\": [\"guangzhou-2\"]}"]。利便性のため、SQL を使用して Distribution Policy を作成することを推奨します。

注意:

  1. RG レプリカ関連のルール: RG Leader 数 + RG Follower 数 = replica-count - learner-count - witness-count。learner-count または witness-count を指定しない場合、Learner と Witness のデフォルト数は 0 です。例えば、replica-count = 4 を指定した場合、RG Leader 数は 1、Follower 数は 3 となります。

  2. node を key として使用する場合:

    • 2.1 values 内のノードがインスタンスに実在することを保証する必要があります。
    • 2.2 レプリカ数を指定する場合、values 内のノード数はレプリカ数以上である必要があります。そうでない場合、DP のスケジューリングが実行できません。

  3. leader-preferences を使用する場合: RG Leader の配置場所は、常にレプリカ配置制約のサブセットである必要があります。例えば、レプリカの配置をアベイラビリティゾーン ["zone1", "zone2", "zone3"] に指定した場合、RG Leader の配置も上記のアベイラビリティゾーン内に指定する必要があります。

警告: メタデータサービスは、不合理な DP 設定を検出した場合、スケジューリングの実行を拒否しますが、他の機能の可用性やデータの正確性には影響しません。

Distribution Policy の使用 ​

このセクションでは、ツール mc-ctl を例に説明します。対応する HTTP API を使用しても同様の結果が得られます。

Distribution Policy の有効化と無効化 ​

distribution-policy-enabled は v18.0.0 でデフォルト有効化されています。

Distribution Policy を有効化:

bash
./mc-ctl schedule set --config_key distribution-policy-enabled --config_value 1

Distribution Policy を無効化:

bash
./mc-ctl schedule set --config_key distribution-policy-enabled --config_value 0

Distribution Policy の作成 ​

bash
./mc-ctl dp create --data 
'{
    "policy_name":"$name",
    "constraints":[
      {"key": "key1", "op": "op1", "values": ["value1","value2"]},
      ...
    ]
}'

説明: DP 作成時の JSON 文字列には policy_name と constraints を指定する必要があります。constraints には前述の DP ルールを複数含めることができます。

Distribution Policy の変更 ​

bash
./mc-ctl dp modify --data 
'{
    "policy_id": $id, 
    "policy_name":"$name",
    "constraints":[
      {"key": "key1", "op": "op1", "values": ["value1","value2"]},
      ...
    ]
}'

注意: DP 変更時の JSON 文字列には policy_id を指定し、変更対象の policy_name または constraints を指定する必要があります。データオブジェクトにバインドされていない DP のみ変更可能です。バインド済みの DP を変更する場合は、まずデータオブジェクトと DP のバインドを解除してください。

Distribution Policy の削除 ​

bash
# ID で削除
./mc-ctl dp delete --distribution_policy_id ${id}
# distribution policy name で削除
./mc-ctl dp delete --distribution_policy_name ${policy_name}

注意: DP は distribution_policy_id または distribution_policy_name で削除できます。データオブジェクトにバインドされていない DP のみ削除可能です。バインド済みの DP を削除する場合は、まずデータオブジェクトと DP のバインドを解除してください。

Distribution Policy の確認 ​

bash
# 作成済みのすべての DP を表示
./mc-ctl dp info all 
# distribution policy name で単一の DP を表示
./mc-ctl dp info single --distribution_policy_name ${policy_name}

データオブジェクトへの DP バインド ​

DP の作成完了後、データオブジェクトと DP をバインドして、対応するスケジューリング効果を得ることができます。

データベースへの DP バインド ​

sql
CREATE DATABASE db1 USING distribution policy ${policy_name};

単一テーブルへの DP バインド ​

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

パーティションテーブルへの DP バインド ​

sql
CREATE TABLE t1(a INT) PARTITION BY HASH(a) PARTITIONS 4 USING distribution policy ${policy_name};

説明: DP はデータオブジェクトにおいて継承ルールに従います。例えば上記の例では、データベース db1 を作成し DP をバインドすると、そのデータベース内に作成されるすべての単一テーブルとパーティションテーブルはデータベースと同じ DP を使用します。ただし、特定のテーブルに直接別の DP をバインドした場合、そのバインドは継承ルールよりも優先されます。

代表的な DP の例 ​

シナリオ 1: 5 レプリカの DP を作成。

bash
./mc-ctl dp create --data '{"policy_name": "policy_1", "constraints": [{"key": "replica-count", "op": "=", "values": ["5"]}]}'

シナリオ 2: 4 レプリカで 1 つの Learner を含む DP を作成。

bash
./mc-ctl dp create --data '{"policy_name": "policy_2", "constraints": [{"key": "replica-count", "op": "=", "values": ["4"]}, {"key": "learner-count", "op": "=", "values": ["1"]}]}'

シナリオ 3: レプリカを node-001、node-002、node-003 ノードに配置し、RG Leader を node-001 ノードに配置する DP を作成。

bash
./mc-ctl dp create --data '{"policy_name": "policy_3", "constraints": [
{"key": "node", "op": "in", "values": ["node-001", "node-002", "node-003"]}, 
{
	"key": "leader-preferences", "op": "=", "values": [
		"{\"key\": \"node\", \"op\": \"in\", \"values\": [\"node-001\"]}"
	]
}]}'

シナリオ 4: レプリカをディスクタイプ SSD に配置する DP を作成。

bash
./mc-ctl dp create --data '{"policy_name": "policy_4", "constraints": [{"key": "tdsql-storage-type", "op": "in", "values": ["SSD"]}]}'

SQL による Distribution Policy の作成 ​

v21.2.3 で Distribution Policy を作成するための SQL 構文が提供されました。SQL による DP 作成の構文設計は mc-ctl の使用法に沿っており、学習コストを最小限に抑えています。具体的な使用法は以下のとおりです。

SQL in DP でルールの key に関連するキーワード:

REGION、ZONE、RACK、HOST、NODE、REPLICA_COUNT、FOLLOWER_COUNT、LEARNER_COUNT、WITNESS_COUNT、STORAGE_TYPE、FAULT_TOLERANCE_LEVEL、LEADER_PREFERENCES

op に関連するキーワード:

IN、NOT IN、EXISTS、NOT EXISTS

SQL による Distribution Policy の作成 ​

sql
# レプリカを zone1 と zone2 のアベイラビリティゾーンに配置し、レプリカ数 2 の DP を作成
CREATE DISTRIBUTION POLICY "policy_1" SET ZONE IN ("zone1", "zone2") AND REPLICA_COUNT = 2;

SQL による Distribution Policy の変更 ​

sql
# "policy_1" の制約を変更: レプリカをディスクタイプ "SSD" に配置
ALTER DISTRIBUTION POLICY "policy_1" SET STORAGE_TYPE IN ("SSD");

# DP "old_dp_name" の名前を "new_dp_name" に変更
RENAME DISTRIBUTION POLICY "old_dp_name" TO "new_dp_name";

SQL による Distribution Policy の削除 ​

sql
# "policy_1" を削除
DROP DISTRIBUTION POLICY "policy_1";

SQL による Distribution Policy のクエリ ​

information_schema に新しいビュー META_CLUSTER_DPS が追加されました。このビューを使用して、既存の DP をリアルタイムで確認できます。

高度な機能 ​

v21.2.3 では高度な DP 機能が提供されています。RANGE および RANGE COLUMNS パーティション方式で、時間型をパーティションキーとするパーティションテーブルにこの高度な DP をバインドできます。指定した時間経過後にパーティションのスケジューリングを実行でき、代表的なシナリオとしてパーティションの自動コールドデータアーカイブがあります。

SQL による高度な DP の作成 ​

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");

この DP の各キーワードの説明は以下のとおりです。

  • PARTITION_METHOD: DP がサポートするパーティションテーブルのパーティション方式を示します。現在、RANGE と RANGE COLUMNS のみサポートされています。
  • PARTITION_KEY_TO_TIME_TYPE: RANGE パーティション方式の場合のみ指定が必要で、パーティション境界値を時間型に変換するために使用します。対応する values は変換関数です。システムは3つの定義済み変換関数（TO_DAYS、UNIX_TIMESTAMP、YEAR）を提供しています。ユーザーはカスタム変換関数を定義することもできます。カスタム関数は年月日時分秒の計算式を提供する必要があり、形式は year/month/day/hour/minute/second:(識別子 v を含む数学式) です。ここで v はパーティション境界の整数値を表す識別子です。例えば values を ["year:v/100", "month:v%100"] と設定すると、省略された day/hour/minute/second は対応する時間単位のゼロ値として処理されます。
  • EXPIRE: パーティションの有効期限。正の整数 + 単位の形式（例: 1 YEAR）。使用可能な単位: YEAR、MONTH、DAY、HOUR。
  • START_TIME: 任意項目。デフォルトはパーティションの開始時刻。指定した場合、この時刻以降から DP ルールが適用されます。
  • END_TIME: 任意項目。デフォルトはパーティションの終了時刻。指定した場合、この時刻以降は DP ルールの適用が拒否されます。

注意:

  1. 一次レベルの RANGE および RANGE COLUMNS パーティションのみが関連機能をサポートし、パーティションキーは時間型である必要があります。
  2. RANGE COLUMNS パーティションは1つのパーティション列のみサポートします。

ケーススタディ ​

ケース1: UNIX_TIMESTAMP に基づく自動コールドデータアーカイブ ​

sql
# 定義済み関数 UNIX_TIMESTAMP を使用して policy_x1 を作成
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");

# RANGE パーティションテーブルを作成し 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;

スケジューリング動作の説明:

  • p1 パーティションのスケジューリング:

    • パーティション境界時刻: 2025-11-11
    • 有効期限オフセット: 1か月
    • スケジューリングトリガー時刻: 2025-11-11 + 1か月 = 2025-12-11
    • スケジューリングアクション: p1 パーティションのデータレプリカを HDD ストレージに移行

  • p2 パーティションのスケジューリング:

    • パーティション境界時刻: 2025-12-11
    • 有効期限オフセット: 1か月
    • スケジューリングトリガー時刻: 2025-12-11 + 1か月 = 2026-01-11
    • スケジューリングアクション: p2 パーティションのデータレプリカを HDD ストレージに移行

ケース2: カスタム時間変換関数による精密なスケジューリング制御 ​

sql
# カスタム関数を使用して policy_x2 を作成
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";

# RANGE パーティションテーブルを作成し 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;

変換関数の解析:

  • カスタム関数: year:v/100、month:v%100
  • パーティション境界値 v = YEAR(gmt_modified) * 100 + MONTH(gmt_modified)
  • 計算例:
    • 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

パーティション時間境界の計算:

パーティション境界値変換後の時刻スケジューリングトリガー時刻制約対象
p12025112025-11-01 00:00:002025-12-01 00:00:00制約なし
p22025122025-12-01 00:00:002026-01-01 00:00:00制約なし
p32026012026-01-01 00:00:002026-02-01 00:00:00制約あり

START_TIME の影響分析:

  • START_TIME = "2025-12-10 00:00:00"
  • パーティション境界時刻 ≥ START_TIME のパーティションのみに DP 制約が適用されます。
  • p1(2025-11-01) と p2(2025-12-01) < START_TIME(2025-12-10) → 制約なし
  • p3(2026-01-01) > START_TIME(2025-12-10) → 制約あり

ケース3: RANGE COLUMNS パーティションのタイムウィンドウスケジューリング ​

sql
# 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";

# RANGE COLUMNS パーティションテーブルを作成し 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;

RANGE COLUMNS 時間パーティションにバインドされた DP のため、PARTITION_KEY_TO_TIME_TYPE フィールドによる変換関数の指定は不要です。パーティション境界がすでに時間型の値であるためです。また、START_TIME と END_TIME が指定されているため、p2 と p3 パーティションのみがパーティション境界時刻から1年（EXPIRE = "1 YEAR"）後にスケジューリングが開始されます。

パーティション境界時刻スケジューリングトリガー時刻タイムウィンドウ内かどうか
p12024-12-102025-12-10START_TIME より前
p22025-12-102026-12-10[START_TIME, END_TIME] 内
p32026-12-102027-12-10[START_TIME, END_TIME] 内
p42027-12-102028-12-10END_TIME より後

Tencent Cloud プロダクトドキュメント

Maintained by Jaden Li · © 2026 Tencent Cloud