Hologres:クエリキュー

クエリキューの作成

• 構文

  • General-purpose

    CALL hg_create_query_queue (query_queue_name, max_concurrency, max_queue_size);

  • Virtual Warehouse

    CALL hg_create_query_queue (warehouse_name, query_queue_name, max_concurrency, max_queue_size);

• パラメーター

  • warehouse_name: 省略可能。仮想ウェアハウスの名前。このパラメーターを省略した場合、デフォルトで現在の接続の仮想ウェアハウスにクエリキューが作成されます。

    説明

    このパラメーターは、Virtual Warehouse のみで必須です。

  • query_queue_name: 必須。クエリキューの名前。この名前は、現在のインスタンスまたは仮想ウェアハウス内で一意である必要があります。

  • max_concurrency: 省略可能。最大同時実行数。デフォルト値は -1（制限なし）です。値の範囲は [-1, 2147483647) です。

  • max_queue_size: 省略可能。キューに入れられる SQL クエリの最大数。デフォルト値は -1（無制限）です。値の範囲は [-1, 2147483647) です。

  説明

  クエリキューを作成する際には、max_concurrency および max_queue_size のみを設定できます。その他のプロパティの設定方法については、「クエリキューのプロパティ設定」をご参照ください。

• 例

  • General-purpose

    -- insert_queue という名前のクエリキューを作成し、最大同時実行数を 10 に設定します。concurrency パラメーターにはシングルクォーテーションは不要です。
    CALL hg_create_query_queue ('insert_queue', 10);

  • Virtual Warehouse

    -- init_warehouse 仮想ウェアハウス内に insert_queue という名前のクエリキューを作成し、最大同時実行数を 10 に設定します。
    CALL hg_create_query_queue ('init_warehouse', 'insert_queue', 10);

分類器の作成

• 構文

  • General-purpose

    CALL hg_create_classifier (query_queue_name, classifier_name, priority);

  • Virtual Warehouse

    CALL hg_create_classifier (warehouse_name, query_queue_name, classifier_name, priority);

• パラメーター

  • warehouse_name: 省略可能。仮想ウェアハウスの名前。このパラメーターを省略した場合、デフォルトで現在の接続の仮想ウェアハウスが使用されます。

    説明

    このパラメーターは、Virtual Warehouse のみで必須です。

  • query_queue_name: 必須。分類器が所属するクエリキューの名前。

  • classifier_name: 必須。分類器の名前。この名前は、現在のインスタンスまたは仮想ウェアハウス内で一意である必要があります。

  • priority: 省略可能。分類器のマッチング優先度。値が大きいほど優先度が高くなります。デフォルト値は 50 です。値の範囲は [1, 100] です。作成時に指定しなかった場合、後から「分類器のプロパティ設定」の手順に従って設定できます。

    説明

    • 優先度が高い分類器が先にマッチします。

    • 複数の分類器が同じ優先度を持つ場合、クエリキュー名および分類器名の辞書式順序に基づいてマッチが行われます。辞書式順序でより前に位置する名前が先にマッチします。たとえば、queue_a(classifier_1) は queue_b(classifier_1) よりも高い優先度を持ちます。

• 例

  • General-purpose

    -- insert_queue クエリキュー内に、マッチング優先度が 20 の classifier_insert という名前の分類器を作成します。priority パラメーターにはシングルクォーテーションは不要です。
    CALL hg_create_classifier ('insert_queue', 'classifier_insert', 20);

  • Virtual Warehouse

    -- init_warehouse 仮想ウェアハウスの insert_queue クエリキュー内に、マッチング優先度が 20 の classifier_insert という名前の分類器を作成します。
    CALL hg_create_classifier ('init_warehouse', 'insert_queue', 'classifier_insert', 20);

分類器のマッチングルール設定

分類器に対してマッチングルールを設定することで、SQL クエリを特定のクエリキューにルーティングできます。

• 構文

  • General-purpose

    CALL hg_set_classifier_rule_condition_value (query_queue_name, classifier_name, condition_name, condition_value);

  • Virtual Warehouse

    CALL hg_set_classifier_rule_condition_value (warehouse_name, query_queue_name, classifier_name, condition_name, condition_value);

• パラメーター

  パラメーター	説明
  warehouse_name	省略可能。仮想ウェアハウスの名前。このパラメーターを省略した場合、デフォルトで現在の接続の仮想ウェアハウスが使用されます。 説明 このパラメーターは、Virtual Warehouse のみで必須です。
  query_queue_name	必須。クエリキューの名前。
  classifier_name	必須。設定対象の分類器の名前。
  condition_name および condition_value	必須。条件のプロパティ。以下のプロパティがサポートされています： user_name: 現在のアカウントの UID。 command_tag: リクエストの種別。有効な値： INSERT、SELECT、UPDATE、DELETE。 実行効率のため、Hologres は COPY 操作を INSERT 操作として実装しています。したがって、INSERT の同時実行数を制限すると、COPY の書き込み同時実行数も制限されます。 db_name: データベース名。 engine_type: リクエストで使用されるエンジン。有効な値： HQE、PQE、SQE、HiveQE。Hologres V3.1.18 以降では、このプロパティの使用を推奨します。 digest: SQL 指紋。詳細については、「SQL 指紋」をご参照ください。 application_name: クエリを開始したアプリケーション。Hologres V3.0.9 以降でサポートされます。 storage_mode: ストレージモード。有効な値： hot、cold。Hologres V3.1.18 または V3.1.8 以降では、このプロパティの使用を推奨します。 write_table: クエリがデータを書き込むテーブル。形式は <db_name>.<schema_name>.<table_name>。Hologres V3.1 以降でサポートされます。 read_table: クエリがデータを読み取るテーブル。Hologres V3.1 以降でサポートされます。

  1 つの分類器内に複数のプロパティを設定でき、各プロパティには複数のマッチングルールを設定できます。Hologres V3.1.18 以降では、プロパティおよびルール間の論理関係は以下のとおりです：

  • 分類器が複数のプロパティのマッチングルールを持つ場合：

    • 異なるプロパティ間には AND 論理が適用されます。たとえば、user_name および command_tag の両方のプロパティにルールがある場合、クエリは両方のルールに一致する必要があります。

    • プロパティ間に OR 関係を作成するには、同一のクエリキューに割り当てられた複数の分類器を使用します。いずれかの分類器のルールに一致すれば、クエリはマッチします。

  • 単一の分類器内で、同一プロパティに設定されたルールには以下の 3 種類のマッチングロジックがあります：

    • user_name、command_tag、db_name、digest、および application_name の場合：

      • プロパティのマッチングルールで設定された値の集合を set_a とします。

      • クエリ内の対応するプロパティ値は単一要素の集合 set_b です。

      • クエリがルールに一致するのは、set_b が set_a の部分集合である場合です（set_b ⊆ set_a）。

    • storage_mode の場合：

      • storage_mode プロパティのマッチングルールで設定された値の集合を set_a とします。

      • クエリ内の対応するプロパティ値は集合 set_b であり、{hot}、{cold}、または {hot, cold} のいずれかになります。

      • クエリがルールに一致するのは、set_a が set_b と完全に等しい場合のみです（set_a == set_b）。

    • engine_type、write_table、および read_table の場合：

      • プロパティのマッチングルールで設定された値の集合を set_a とします。

      • クエリ内の対応するプロパティ値は集合 set_b であり、要素数に制限はありません。

      • クエリがルールに一致するのは、set_a と set_b の共通部分が空でない場合です（(set_a ∩ set_b) != ∅）。

  説明

  • 1 回の呼び出しで 1 つの条件プロパティのみを設定してください。条件値が大文字小文字を区別する場合は、二重引用符（""）で囲んでください。

  • 同一条件に対して複数の値をマッチさせるには、関数を複数回呼び出します。たとえば、SELECT および INSERT の両方のリクエストをマッチさせるには、2 つの独立した SQL ステートメントを実行する必要があります。

• 例

  以下の例では仮想ウェアハウスインスタンスを使用します。汎用インスタンスの場合は、最初のパラメーター warehouse_name を省略してください。まず、デフォルトの仮想ウェアハウス init_warehouse に対して test_queue という名前のクエリキューを作成します：

  CALL hg_create_query_queue ('init_warehouse', 'test_queue');

  • 例 1: ユーザー p4_123 または p4_456 が送信したクエリ、または SQL 指紋が xxx または yyy のクエリを test_queue クエリキューにルーティングします。

    -- `user_name` および `digest` プロパティ間の OR 関係を実現するには、2 つの分類器が必要です。
    
    -- classifier_user という名前の分類器を作成し、test_queue クエリキューに追加します。
    CALL hg_create_classifier ('init_warehouse', 'test_queue', 'classifier_user');
    -- user_name プロパティに基づくマッチングルールを設定します。ユーザー "p4_123" または "p4_456" が送信したクエリがこの分類器に一致します。
    CALL hg_set_classifier_rule_condition_value ('init_warehouse','test_queue', 'classifier_user', 'user_name', 'p4_123');
    CALL hg_set_classifier_rule_condition_value ('init_warehouse','test_queue', 'classifier_user', 'user_name', 'p4_456');
    
    -- classifier_digest という名前の分類器を作成し、test_queue クエリキューに追加します。
    CALL hg_create_classifier ('init_warehouse', 'test_queue', 'classifier_digest');
    -- SQL 指紋プロパティに基づくマッチングルールを設定します。SQL 指紋が "xxx" または "yyy" のクエリがこの分類器に一致します。
    CALL hg_set_classifier_rule_condition_value ('init_warehouse','test_queue', 'classifier_digest', 'digest', 'xxx');
    CALL hg_set_classifier_rule_condition_value ('init_warehouse','test_queue', 'classifier_digest', 'digest', 'yyy');

  • 例 2: xx_bi アプリケーションから開始され、かつホットストレージとコールドストレージの両方にアクセスするクエリを test_queue クエリキューにルーティングします。

    -- `application_name` および `storage_mode` プロパティ間の AND 関係は、同一分類器内で両方のプロパティを定義することで実現できます。
    
    -- classifier_3 という名前の分類器を作成し、test_queue クエリキューに追加します。
    CALL hg_create_classifier ('init_warehouse', 'test_queue', 'classifier_3');
    -- application プロパティに基づくマッチングルールを設定します。
    CALL hg_set_classifier_rule_condition_value ('init_warehouse','test_queue', 'classifier_3', 'application_name', 'xx_bi');
    -- ストレージモードプロパティに基づくマッチングルールを設定します。「hot」と「cold」の両方を設定することで、クエリがホットストレージとコールドストレージの両方にアクセスする場合のみこのルールに一致するようにします。
    CALL hg_set_classifier_rule_condition_value ('init_warehouse','test_queue', 'classifier_3', 'storage_mode', 'hot');
    CALL hg_set_classifier_rule_condition_value ('init_warehouse','test_queue', 'classifier_3', 'storage_mode', 'cold');

  • 例 3: コールドストレージにアクセスするすべてのクエリを test_queue クエリキューにルーティングします。

    -- `storage_mode` プロパティは完全に一致する必要があるため、コールドストレージにアクセスするすべてのクエリをルーティングするには 2 つの分類器を使用する必要があります。いずれかの分類器に一致すれば、クエリはルーティングされます。
    
    -- classifier_cold_1 という名前の分類器を作成し、test_queue クエリキューに追加します。
    CALL hg_create_classifier ('init_warehouse', 'test_queue', 'classifier_cold_1');
    -- storage_mode が 'cold' のみであるクエリがこのキューに入ります。
    CALL hg_set_classifier_rule_condition_value ('init_warehouse','test_queue', 'classifier_cold_1', 'storage_mode', 'cold');
    
    -- classifier_cold_2 という名前の分類器を作成し、test_queue クエリキューに追加します。
    CALL hg_create_classifier ('init_warehouse', 'test_queue', 'classifier_cold_2');
    -- storage_mode が 'hot' および 'cold' の両方を含むクエリがこのキューに入ります。
    CALL hg_set_classifier_rule_condition_value ('init_warehouse','test_queue', 'classifier_cold_2', 'storage_mode', 'hot');
    CALL hg_set_classifier_rule_condition_value ('init_warehouse','test_queue', 'classifier_cold_2', 'storage_mode', 'cold');

  • 例 4: テーブル a から読み取り、かつテーブル b に書き込むすべてのクエリを test_queue クエリキューにルーティングします。

    -- `read_table` および `write_table` プロパティ間の AND 関係は、同一分類器内で両方のプロパティのルールを定義することで実現できます。
    
    -- classifier_table という名前の分類器を作成し、test_queue クエリキューに追加します。
    CALL hg_create_classifier ('init_warehouse', 'test_queue', 'classifier_table');
    -- read_table プロパティのマッチングルールを設定します。クエリがテーブル 'a' から読み取る場合（他のテーブルからも読み取る場合を含む）、このルールに一致します。
    CALL hg_set_classifier_rule_condition_value ('init_warehouse','test_queue', 'classifier_table', 'read_table', 'db_name.schema_name.a');
    -- write_table プロパティのマッチングルールを設定します。クエリがテーブル 'b' に書き込む場合、このルールに一致します。
    CALL hg_set_classifier_rule_condition_value ('init_warehouse','test_queue', 'classifier_table', 'write_table', 'db_name.schema_name.b');

その他の操作

サーバーレスコンピューティングを使用したクエリ実行

Hologres V3.0.10 以降では、クエリキュー内のすべてのクエリをサーバーレスコンピューティングリソースで実行するよう指定できます。設定後、キュー内のクエリはリクエストの順序および設定済みの優先度に基づいてサーバーレスリソースで実行されます。クエリキューの同時実行数設定およびキューイング機構の影響は受けなくなります。詳細については、「サーバーレスコンピューティングユーザーガイド」をご参照ください。

• 汎用インスタンスの場合

  • 構文

    -- 対象キュー内のすべてのクエリをサーバーレスリソースで実行するよう指定します。
    CALL hg_set_query_queue_property('<query_queue_name>', 'computing_resource', 'serverless');
    
    -- （任意）対象キュー内のクエリがサーバーレスリソースを使用する場合の優先度を設定します。有効な値は 1～5 です。デフォルト値は 3 です。
    CALL hg_set_query_queue_property('<query_queue_name>', 'query_priority_when_using_serverless_computing', '<priority>');

  • パラメーター

    • query_queue_name: 必須。クエリキューの名前。

    • priority: 優先度。値の範囲は [1, 5] であり、デフォルトは 3 です。

  • 例

    -- 対象キュー内のすべてのクエリをサーバーレスリソースで実行するよう指定します。
    CALL hg_set_query_queue_property('insert_queue', 'computing_resource', 'serverless');
    
    -- 対象キュー内のクエリがサーバーレスリソースを使用する場合の優先度を 2 に設定します。
    CALL hg_set_query_queue_property('insert_queue', 'query_priority_when_using_serverless_computing', '2');

• 仮想ウェアハウスインスタンスの場合

  • 構文

    -- 対象キュー内のすべてのクエリをサーバーレスリソースで実行するよう指定します。
    CALL hg_set_query_queue_property('<warehouse_name>', '<query_queue_name>', 'computing_resource', 'serverless');
    
    -- （任意）対象キュー内のクエリがサーバーレスリソースを使用する場合の優先度を設定します。有効な値は 1～5 です。デフォルト値は 3 です。
    CALL hg_set_query_queue_property('<warehouse_name>', '<query_queue_name>', 'query_priority_when_using_serverless_computing', '<priority>');

  • パラメーター

    • warehouse_name: 必須。仮想ウェアハウスの名前。

    • query_queue_name: 必須。クエリキューの名前。

    • priority: 必須。優先度。値の範囲は [1, 5] であり、デフォルトは 3 です。

  • 例

    -- 対象キュー内のすべてのクエリをサーバーレスリソースで実行するよう指定します。
    CALL hg_set_query_queue_property('init_warehouse', 'insert_queue', 'computing_resource', 'serverless');
    
    -- 対象キュー内のクエリがサーバーレスリソースを使用する場合の優先度を 2 に設定します。
    CALL hg_set_query_queue_property('init_warehouse', 'insert_queue', 'query_priority_when_using_serverless_computing', '2');

特定の SQL のクエリキューを表示

特定の SQL クエリがどのクエリキューにルーティングされるかを確認するには、EXPLAIN ステートメントを実行します。Query Queue フィールドの出力に、割り当てられたキューおよび分類器が表示されます。例：

-- 同時実行数 10、最大キュー長 20 のクエリキューを作成します。
CALL hg_create_query_queue ('select_queue', 10, 20);
-- 分類器を作成し、command_tag プロパティのルールを追加します。
CALL hg_create_classifier ('select_queue', 'classifier_1');
CALL hg_set_classifier_rule_condition_value ('select_queue', 'classifier_1', 'command_tag', 'select');

-- EXPLAIN ANALYZE を使用して、マッチする分類器およびクエリキューを表示します。
EXPLAIN ANALYZE SELECT * FROM hg_stat_activity;

出力例：

QUERY PLAN
Gather  (cost=0.00..14.96 rows=1000 width=408)
[4:1 id=100003 dop=1 time=16/16/16ms rows=142(142/142/142) mem=43/43/43KB open=0/0/0ms get_next=16/16/16ms]
  ->  Forward  (cost=0.00..12.19 rows=1000 width=408)
      [0:4 id=100002 dop=4 time=16/8/5ms rows=142(39/35/33) mem=6/6/6KB open=16/8/5ms get_next=0/0/0ms scan_rows=142(39/35/33)]
        ->  ExecuteExternalSQL on PQE  (cost=0.00..10.04 rows=0 width=408)
"              External SQL: SELECT "datid" AS c_d2adb610_0, "datname" AS c_d2adb760_1, "pid" AS c_d2adb8a0_2, "usesysid" AS c_d2adba10_3, "usename" AS c_d2adbb60_4, "application_name" AS c_d2adbd10_5, "client_addr" AS c_d2adbe80_6, "client_hostname" AS c_d2df1020_7, "client_port" AS c_d2df1190_8, "backend_start" AS c_d2df1300_9, "xact_start" AS c_d2df1470_10, "query_start" AS c_d2df15e0_11, "state_change" AS c_d2df1750_12, "wait_event_type" AS c_d2df18c0_13, "wait_event" AS c_d2df1a30_14, "state" AS c_d2df1b80_15, "backend_xid" AS c_d2df1cf0_16, "backend_xmin" AS c_d2df1e60_17, "query" AS c_d2df1fb0_18, "backend_type" AS c_d2df2120_19, "query_id" AS c_d2df2290_20, "transaction_id" AS c_d2df2400_21, "extend_info" AS c_d2df2570_22, "running_info" AS c_d2df26e0_23 FROM pg_catalog."hg_stat_activity""
Query id:[1001002491453065719]
Query Queue: init_warehouse.select_queue.classifier_1

アクティブなクエリのクエリキューを表示

アクティブなクエリの詳細（割り当てられたクエリキュー名、現在のステータス、キュー待ち時間など）を表示するには、以下の SQL ステートメントを実行します。

SELECT
    running_info::json -> 'current_stage' ->> 'stage_name' AS stage_name,
    running_info::json -> 'current_stage' ->> 'queue_time_ms' AS queue_time_ms,
    running_info::json ->> 'query_queue' AS query_queue,
    *
FROM
    hg_stat_activity;

クエリログからクエリキューを表示

クエリログから履歴クエリのクエリキュー、ステータス、キュー待ち時間を表示するには、以下の SQL ステートメントを実行します。query_detail フィールドには使用されたクエリキューが記録されます。hologres.hg_query_log システムテーブルの詳細については、「hg_query_log テーブル」をご参照ください。

SELECT * FROM hologres.hg_query_log WHERE query_detail like '%query_queue = <warehouse_name>.<queue_name>%';-- warehouse_name パラメーターは、仮想ウェアハウスベースのインスタンスでのみ必須です。

異なるマッチングルールを持つクエリキューの作成

• 例 1: INSERT などの特定のリクエスト種別向けのクエリキューを作成します。

  このキューを作成した後、classifier_1 分類器がすべての INSERT リクエストをマッチし、insert_queue クエリキューにルーティングします。

  -- 同時実行数 10、最大キュー長 20 のクエリキューを作成します。
  CALL hg_create_query_queue ('insert_queue', 10, 20);
  
  -- 分類器を作成し、command_tag プロパティのルールを追加します。
  CALL hg_create_classifier ('insert_queue', 'classifier_1');
  CALL hg_set_classifier_rule_condition_value ('insert_queue', 'classifier_1', 'command_tag', 'INSERT');

• 例 2: p4_123 および p4_345 などの特定のユーザー向けのクエリキューを作成します。

  このキューを作成した後、classifier_2 分類器がユーザー p4_123 および p4_345 からの SQL リクエストを user_queue クエリキューにルーティングします。

  -- 同時実行数 3、最大キュー長無制限のクエリキューを作成します。
  CALL hg_create_query_queue ('user_queue', 3);
  CALL hg_set_query_queue_property('user_queue','max_queue_size', -1);
  -- 分類器を作成し、user_name のマッチングルールを設定します。
  CALL hg_create_classifier ('user_queue', 'classifier_2');
  CALL hg_set_classifier_rule_condition_value ('user_queue', 'classifier_2', 'user_name', 'p4_123');
  CALL hg_set_classifier_rule_condition_value ('user_queue', 'classifier_2', 'user_name', 'p4_345');

  説明

  カスタムユーザーアカウントを指定する場合、その名前を二重引用符（""）で囲んでください。たとえば、CALL hg_set_classifier_rule_condition_value ('user_queue', 'classifier_2', 'user_name', '"BASIC$xxx"'); のようにします。

• 例 3: test および postgres などの特定のデータベース向けのクエリキューを作成します。

  このキューを作成した後、classifier_3 分類器が test および postgres データベースに対する SQL リクエストを db_queue クエリキューにルーティングします。

  -- 同時実行数 5 のクエリキューを作成します。
  CALL hg_create_query_queue ('db_queue', 5);
  
  -- 最大キュー待ち時間を 600,000 ms に設定します。クエリがこの時間を超えて待機した場合、エラーが報告されます。
  CALL hg_set_query_queue_property ('db_queue', 'queue_timeout_ms', '600000');
  
  -- 分類器を作成し、db_name プロパティのルールを追加します。
  CALL hg_create_classifier ('db_queue', 'classifier_3');
  CALL hg_set_classifier_rule_condition_value ('db_queue', 'classifier_3', 'db_name', 'test');
  CALL hg_set_classifier_rule_condition_value ('db_queue', 'classifier_3', 'db_name', 'postgres');

• 例 4: HQE などの特定のエンジン種別向けのクエリキューを作成します。

  このキューを作成した後、classifier_4 分類器が HQE エンジンに関連する SQL リクエストを hqe_queue クエリキューにルーティングします。

  -- 同時実行数 10 のクエリキューを作成します。
  CALL hg_create_query_queue ('hqe_queue', 10);
  
  -- 分類器を作成し、engine_type プロパティのルールを追加します。
  CALL hg_create_classifier ('hqe_queue', 'classifier_4');
  CALL hg_set_classifier_rule_condition_value ('hqe_queue', 'classifier_4', 'engine_type', 'HQE');

キュー内のすべてのリクエストをブロック

キュー内のすべてのリクエストをブロックするには、その同時実行数および最大キュー長を 0 に設定します。例：

CALL hg_set_query_queue_property ('insert_queue', 'max_concurrency', '0');
CALL hg_set_query_queue_property ('insert_queue', 'max_queue_size', '0');