Hologres:クエリキュー

クエリキューの作成

• 構文

  • 汎用 インスタンス

    CALL hg_create_query_queue (query_queue_name, max_concurrency, max_queue_size);

  • コンピューティンググループ インスタンス

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

• パラメーターの説明

  • warehouse_name：このパラメーターはオプションです。計算グループの名前を指定します。このパラメーターを指定しない場合、クエリキューは現在の接続の計算グループに作成されます。

    説明

    このパラメーターは、[計算グループ] インスタンス専用です。

  • query_queue_name：このパラメーターは必須です。クエリキューの名前を指定します。名前は現在のインスタンスまたは計算グループ内で一意である必要があります。

  • max_concurrency：このパラメーターはオプションです。最大同時実行リクエスト数を指定します。デフォルト値は -1 で、同時実行数に制限がないことを示します。値は [-1, 2147483647) の範囲内である必要があります。

  • max_queue_size：このパラメーターはオプションです。キューに入れられるリクエストの最大数を指定します。このパラメーターは、キューに入れることができる SQL 文の最大数を指定します。デフォルト値は -1 で、キューサイズが無制限であることを示します。値は [-1, 2147483647) の範囲内である必要があります。

  説明

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

• 例

  • 汎用 インスタンス

    -- insert_queue という名前のクエリキューを作成し、最大同時実行数を 10 に設定します。同時実行数パラメーターには単一引用符は不要です。
    CALL hg_create_query_queue ('insert_queue', 10);

  • コンピュートグループのインスタンス

    -- init_warehouse 計算グループに、insert_queue という名前のクエリキューを作成し、最大同時実行数を 10 に設定します。
    CALL hg_create_query_queue ('init_warehouse', 'insert_queue', 10);

分類子の作成

• 構文

  • 汎用 インスタンス

    CALL hg_create_classifier (query_queue_name, classifier_name, priority);

  • コンピュートグループ インスタンス

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

• パラメーターの説明

  • warehouse_name：このパラメーターはオプションです。計算グループの名前を指定します。このパラメーターを指定しない場合、現在の接続の計算グループが使用されます。

    説明

    このパラメーターは、[計算グループ] インスタンスにのみ適用されます。

  • query_queue_name：このパラメーターは必須です。分類子を作成するクエリキューの名前を指定します。

  • classifier_name：このパラメーターは必須です。分類子の名前を指定します。名前は現在のインスタンスまたは計算グループ内で一意である必要があります。

  • priority：このパラメーターはオプションです。分類子のマッチング優先度を指定します。値が大きいほど優先度が高くなります。デフォルト値は 50 です。値は [1, 100] の範囲内である必要があります。分類子の作成時にこのパラメーターを指定しない場合、後で設定できます。詳細については、「分類子プロパティの設定」をご参照ください。

    説明

    • 優先度の高い分類子が最初に照合されます。

    • 複数の分類子が同じ優先度を持つ場合、それらはクエリキューと分類子名の辞書順に基づいて照合されます。辞書順で先に来る名前が最初に照合されます。たとえば、queue_a(classifier_1) は queue_b(classifier_1) よりも優先度が高くなります。

• 例

  • 汎用 インスタンス

    -- insert_queue クエリキューに、classifier_insert という名前の分類子をマッチング優先度 20 で作成します。priority パラメーターには単一引用符は不要です。
    CALL hg_create_classifier ('insert_queue', 'classifier_insert', 20);

  • インスタンスとしての コンピュートグループタイプ

    -- init_warehouse 計算グループの insert_queue クエリキューに、classifier_insert という名前の分類子をマッチング優先度 20 で作成します。
    CALL hg_create_classifier ('init_warehouse', 'insert_queue', 'classifier_insert', 20);

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

分類子のマッチングルールを設定して、特定の SQL 文を照合できます。このプロセスにより、どの SQL 文が対応するクエリキューに入るかが決まります。

• 構文

  • 汎用インスタンス

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

  • [コンピュートグループ] インスタンス

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

• パラメーターの説明

  名前	説明
  warehouse_name	オプション。計算グループの名前。このパラメーターを設定しない場合、現在の接続の計算グループが使用されます。 説明 このパラメーターは、[計算グループ] インスタンスの場合にのみ設定します。
  query_queue_name	必須。クエリキューの名前。
  classifier_name	必須。マッチングルールを追加する分類子の名前。
  condition_name と condition_value	必須。サポートされている条件プロパティは次のとおりです： user_name：現在のアカウントの UID。 command_tag：リクエストタイプ。有効な値：INSERT、SELECT、UPDATE、DELETE。 COPY 操作の実行効率を向上させるため、Hologres は INSERT 操作を使用して COPY 操作を実装します。したがって、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 以降でのみサポートされています。

  分類子に複数のプロパティを設定でき、各プロパティには複数のマッチングルールを設定できます。Hologres V3.1.18 以降では、プロパティとルールの関係は次のとおりです：

  • 分類子で複数のプロパティのマッチングルールを設定する場合：

    • 異なるプロパティ間の関係は AND です。たとえば、分類子に `user_name` と `command_tag` の両方のマッチングルールが含まれている場合、クエリはこの分類子に割り当てられるために両方のルールを満たす必要があります。

    • プロパティ間に OR 関係を定義するには、複数の分類子を作成し、それらを同じクエリキューに割り当てる必要があります。

  • 単一の分類子内で、単一のプロパティのマッチングルールには、次の 3 つの関係のいずれかがあります：

    • `user_name`、`command_tag`、`db_name`、`digest`、`application_name` などのプロパティの場合：

      • set_a をマッチングルールに設定されたプロパティ値のセットとします。たとえば、プロパティは user_name です。

      • set_b プロパティセットはクエリに対応し、1 つの値のみを含みます。

      • 集合演算 set_b ⊆ set_a が満たされる場合、クエリはルールに一致します。

    • storage_mode：

      • set_a は、マッチングルールに設定されたプロパティ値のセットを表します。

      • set_b パラメーターは、クエリのプロパティセットを指定します。可能な値は "hot"、"cold"、または "hot, cold" です。

      • 集合演算 set_a == set_b が true と評価された場合にのみ、クエリはルールに一致します。

    • `engine_type`、`write_table`、`read_table` などのプロパティの場合：

      • set_a を、read_table などのマッチングルールに設定されたプロパティ値のセットとします。

      • set_b はクエリのプロパティセットであり、無制限の数の値を含むことができます。たとえば、クエリは複数のテーブルから読み取ることができます。

      • 集合演算が条件 (set_a ∩ set_b) != ∅ を満たす場合、クエリはルールに一致します。

  説明

  • 一度に設定できる条件プロパティは 1 つだけです。条件値で大文字と小文字が区別される場合は、二重引用符 ("") で囲む必要があります。

  • プロパティが複数の値に一致する必要がある場合は、値ごとに個別の SQL 文を実行する必要があります。たとえば、`command_tag` が `SELECT` または `INSERT` のいずれかであるリクエストに一致させるには、2 つの SQL 文を実行してルールを設定する必要があります。

• 例

  以下の例では、計算グループインスタンスを使用します。汎用インスタンスの場合は、最初の入力パラメーターを削除できます。この例では、デフォルトの計算グループ `init_warehouse` のために `test_queue` という名前のクエリキューを作成します：

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

  • 例 1：ユーザー `p4_123` または `p4_456` によって送信された場合、または SQL 指紋が `xxx` または `yyy` である場合、クエリは `test_queue` クエリキューに割り当てられます。

    -- ユーザーと SQL 指紋プロパティの間には OR 関係が必要なため、2 つの分類子を設定する必要があります。
    
    -- classifier_user という名前の分類子を作成し、test_queue クエリキューにアタッチします。
    CALL hg_create_classifier ('init_warehouse', 'test_queue', 'classifier_user');
    -- ユーザープロパティに基づいてマッチングルールを設定します。ユーザー "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` クエリキューに割り当てられます。

    -- アプリケーションとストレージモードプロパティの間には AND 関係が必要なため、両方のプロパティを同じ分類子内で定義します。
    
    -- classifier_3 という名前の分類子を作成し、test_queue クエリキューにアタッチします。
    CALL hg_create_classifier ('init_warehouse', 'test_queue', 'classifier_3');
    -- アプリケーションプロパティに基づいてマッチングルールを設定します。
    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` クエリキューに割り当てられます。

    -- ストレージモードの値は完全に一致する必要があるため、「コールドストレージデータにアクセスする」リクエストは、次の 2 つの分類子に分割する必要があります。リクエストは、いずれか 1 つの分類子に入るだけで十分です。
    
    -- 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` クエリキューに割り当てられます。

    -- 読み取りテーブルと書き込みテーブルのプロパティの間には AND 関係が必要なため、両方のプロパティを同じ分類子内で定義します。
    
    -- classifier_table という名前の分類子を作成し、test_queue クエリキューにアタッチします。
    CALL hg_create_classifier ('init_warehouse', 'test_queue', 'classifier_table');
    -- 読み取りテーブルに基づいてマッチングルールを設定します。リクエストは、他のテーブルから読み取るかどうかに関係なく、テーブル a からデータを読み取る場合にこのルールに一致します。
    CALL hg_set_classifier_rule_condition_value ('init_warehouse','test_queue', 'classifier_table', 'read_table', 'db_name.schema_name.a');
    -- 書き込みテーブルに基づいてマッチングルールを設定します。テーブル 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：優先度。デフォルト値は 3 です。値は [1, 5] の範囲内である必要があります。

  • 例

    -- ターゲットキュー内のすべてのクエリをサーバーレスリソースで実行するように設定します。
    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：このパラメーターは必須です。優先度を指定します。デフォルト値は 3 です。値は [1, 5] の範囲内である必要があります。

  • 例

    -- ターゲットキュー内のすべてのクエリをサーバーレスリソースで実行するように設定します。
    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 文で使用されるクエリキューの表示

EXPLAIN を実行して、特定の SQL 文で使用されるクエリキューを表示できます。結果の `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 文が使用するクエリキューの表示

次の SQL 文を実行して、アクティブなクエリ内の 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 文が使用するクエリキューの表示

次の SQL 文を実行して、クエリログ内の SQL 文のクエリキュー、現在のステータス、およびキュー時間を表示できます。`query_detail` フィールドには、SQL 文が使用したクエリキューが記録されます。`hologres.hg_query_log` システムテーブルの詳細については、「query_log テーブルの表示」をご参照ください。

SELECT * FROM hologres.hg_query_log WHERE query_detail like '%query_queue = <warehouse_name>.<queue_name>%';--計算グループインスタンスの場合のみ warehouse_name パラメーターを設定します。

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

• 例 1：`INSERT` リクエストのマッチングルールを持つクエリキューを作成します。次のコードは例です。

  クエリキューが作成されると、すべての `INSERT` リクエストは `classifier_1` 分類子に一致し、`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');

• ユーザー `p4_123` と `p4_345` のマッチングルールを持つクエリキューを作成します。次のコードは例です。

  クエリキューが作成されると、ユーザー `p4_123` と `p4_345` によって送信された SQL リクエストは `classifier_2` 分類子に一致し、`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"');。

• `test` および `postgres` データベースのマッチングルールを持つクエリキューを作成します。次のコードは例です。

  クエリキューが作成されると、`test` および `postgres` データベースに関連する SQL リクエストは `classifier_3` 分類子に一致し、`db_queue` クエリキューに割り当てられます。

  -- 同時実行数 5 のクエリキューを作成します。
  CALL hg_create_query_queue ('db_queue', 5);
  
  -- 最大キュー時間を 600000 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');

• `HQE` エンジンタイプのマッチングルールを持つクエリキューを作成します。次のコードは例です。

  クエリキューが作成されると、`HQE` エンジンに関連する SQL リクエストは `classifier_4` 分類子に一致し、`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');

すべてのタスクのブロック (極端なシナリオ)

`insert_queue` クエリキューの同時実行数とキューサイズを 0 に設定できます。次のコードは例です。

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