PolarDB:ヒントワードの紹介

SQL ヒントの仕組み

SQL ヒントは SQL コメント内に埋め込まれ、実行前に PolarDB-X 1.0 によって処理されます。ヒントとは、/* および */（または /! および */）で囲まれた文字列であり、先頭に +TDDL: を含み、その後に 1 つ以上のヒントコマンドが続きます。

/*+TDDL: ヒントコマンド [ヒントコマンド ...]*/
/!+TDDL: ヒントコマンド [ヒントコマンド ...]*/

各 ヒントコマンド は、特定の動作（例：データベースシャードへのルーティング、読み書き分離の有効化、タイムアウトの設定など）を対象としています。複数のヒントコマンドを指定する場合は、半角スペースで区切ります。

例

-- 各データベースシャード内の物理テーブル名をクエリします。
/*+TDDL:scan()*/SHOW TABLES;

-- 読み取り専用 ApsaraDB RDS インスタンスのデータベースシャード 0000 にクエリをルーティングします。
/*+TDDL:node(0) slave()*/SELECT * FROM t1;

上記の例では、/*+TDDL:scan()*/ および /*+TDDL:node(0) slave()*/ がカスタムヒントです。これら 2 つのヒントはいずれも +TDDL: で始まります。scan()、node(0)、slave() はヒントコマンドであり、半角スペースで区切られています。

構文フォーマット

PolarDB-X 1.0 では、以下の 2 種類の構文フォーマットがサポートされています。

-c オプションの重要性

/*...*/ 形式は標準的な MySQL コメントとして扱われます。デフォルトでは、MySQL コマンドラインクライアントが SQL ステートメントをサーバーに送信する前にコメントを削除するため、ヒントが無視されることがあります。ヒントを保持するには、ログインコマンドに -c オプションを追加してください。

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

詳細については、「MySQL のコメント」および「mysql クライアントのオプション」をご参照ください。

SQL ステートメント内でのヒントの配置位置

PolarDB-X 1.0 では、データ操作言語 (DML)、データ定義言語 (DDL)、データアクセス言語 (DAL) ステートメントにおけるヒントの使用がサポートされています。

ヒントは、ステートメントの直前、または最初のキーワードの直後に配置できます。

-- ステートメントの直前
/*+TDDL: ... */ SELECT ...
/*+TDDL: ... */ INSERT ...
/*+TDDL: ... */ REPLACE ...
/*+TDDL: ... */ UPDATE ...
/*+TDDL: ... */ DELETE ...
/*+TDDL: ... */ CREATE TABLE ...
/*+TDDL: ... */ ALTER TABLE ...
/*+TDDL: ... */ DROP TABLE ...
/*+TDDL: ... */ SHOW ...

-- 最初のキーワードの直後
SELECT /*+TDDL: ... */ ...
INSERT /*+TDDL: ... */ ...
REPLACE /*+TDDL: ... */ ...
UPDATE /*+TDDL: ... */ ...
DELETE /*+TDDL: ... */ ...

ヒントの種類によって対応するステートメントが異なります。各ヒントコマンドのトピックを確認し、対応するステートメントを確認してください。

複数ヒントの使用制限

複数のヒントコマンドは、単一のヒント内にまとめて指定してください。同一のステートメント内で複数の別々のヒントを使用しないでください。

-- 正しい例：1 つのヒント内に 2 つのコマンドを指定
SELECT /*+TDDL:node(0) slave()*/ * FROM orders;

-- 不適切な例：1 つのステートメント内で 2 つの別々のヒントを指定
SELECT /*+TDDL:node(0)*/ /*+TDDL:slave()*/ * FROM orders;

-- 不適切な例：1 つのヒント内で重複するコマンドを指定
SELECT /*+TDDL:node(0) node(1)*/ * FROM orders;

利用可能なヒントカテゴリ

PolarDB-X 1.0 のカスタム SQL ヒントは、以下の 4 つのカテゴリに分類されます。各カテゴリは、クエリ実行時の異なる制御ポイントに対応しています。

• 読み書き分離 — 読み取りクエリを読み取り専用ノードにルーティングします。

• SQL ステートメントに対するカスタムタイムアウトの指定 — デフォルトの実行タイムアウトを上書きします。

• 実行対象のデータベースシャードの指定 — ステートメントを 1 つ以上の特定のデータベースシャードにルーティングします。

• データベースシャード間でのテーブルシャードのスキャン — 全てまたは選択されたテーブルシャードおよびデータベースシャードに対してクエリを実行します。

トラブルシューティング

ヒントが無視される

最も一般的な原因は、MySQL コマンドラインクライアントが /*...*/ コメントを削除してしまうことです。この問題を回避するには、/!+TDDL:...*/ 形式に切り替えるか、-c オプションを指定して再接続してください。

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

次のステップ

• 読み書き分離

• SQL ステートメントに対するカスタムタイムアウトの指定

• 実行対象のデータベースシャードの指定

• データベースシャード間でのテーブルシャードのスキャン