Hologres：查詢隊列Query Queue

建立查詢隊列

• 文法

  • 通用型執行個體

    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：可選，計算群組名稱。如果未配置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：可選，計算群組名稱。如果未配置warehouse_name參數，則預設使用當前串連的計算群組。

    說明

    僅計算群組型執行個體需配置此參數。

  • query_queue_name：必填，待建立分類器的查詢隊列名稱。

  • classifier_name：必填，分類器名稱，在當前執行個體或計算群組中保持唯一，不可重複。

  • priority：可選，分類器匹配優先順序，數值越大優先順序越高。預設值：50，取值範圍：[ 1 , 100 ]。若您建立時未配置該參數，後續可通過配置分類器屬性方式進行配置。

    說明

    • 分類器的優先順序越高，則匹配的順序越靠前。

    • 當多個分類器具有相同的優先順序時，將依據查詢隊列和分類器名稱的字典序進行匹配，優先匹配字典序較小的項。例如，queue_a(classifier_1) 的優先順序高於 queue_b(classifier_1)。

• 樣本

  • 通用型執行個體

    -- 在insert_queue的查詢隊列中，建立名為classifier_insert的分類器，匹配優先順序為20，注意此處的優先順序參數無需添加單引號。
    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	可選，計算群組名稱。如果未配置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指紋詳情，請參見SQL指紋。 application_name：發起Query的應用。僅V3.0.9及以上版本支援該屬性。 storage_mode：儲存模式。取值：hot、cold。建議自Hologres V3.1.18版本或V3.1.8開始使用。 write_table：Query寫入的表。格式為<db_name>.<schema_name>.<table_name>。僅V3.1版本及以上版本支援該屬性。 read_table：Query讀取的表。僅V3.1版本及以上版本支援該屬性。

  分類器內可以設定多個屬性，每個屬性可以設定多條匹配規則，自Hologres V3.1.18版本起，屬性和規則對應關係如下：

  • 如果一個分類器內設定了多個屬性的匹配規則：

    • 不同屬性之間是“且”的關係。例如：一個分類器包含user_name和command_tag兩個屬性的匹配規則，則二者需同時滿足，才可歸屬到該分類器。

    • 如果需要多個屬性之前定義為“或”的關係（滿足某個屬性要求即可），則需建立多個分類器，並將這些分類器歸屬於同一查詢隊列。

  • 在一個分類器內對同一個屬性設定的匹配規則，有三種關係，分類如下：

    • user_name/command_tag/db_name/digest/application_name：

      • 對同一個屬性（例如：user_name），匹配規則配置的屬性值集合為set_a。

      • Query的對應屬性集合為set_b（該集合內有且僅有一個值）。

      • 只要滿足集合運算set_b ⊆ set_a，Query就可匹配該規則。

    • storage_mode：

      • 對同一個屬性（目前僅有storage_mode），匹配規則配置的屬性值集合為set_a。

      • Query的對應屬性集合為set_b（可能有“hot”、“cold”或“hot, cold”三種取值）。

      • 需要滿足集合運算 set_a == set_b，Query才可匹配該規則。

    • engine_type/write_table/read_table：

      • 對同一個屬性（例如：read_table），匹配規則配置的屬性值集合為set_a。

      • Query的對應屬性集合為set_b（數量沒有限制，可能有很多張表）。

      • 只要滿足集合運算 (set_a ∩ set_b) != ∅，Query就可匹配該規則。

  說明

  • 每次只能配置一個條件屬性，若條件值大小寫敏感，則需要帶上雙引號。

  • 若同一種條件屬性需匹配多個條件值，則需進行多次設定。例如：若分類器對command_tag為SELECT和INSERT的請求均需匹配，則需執行兩條SQL語句進行設定。

• 樣本

  以計算群組型執行個體為例（通用型執行個體僅需刪去第一個入參）。為預設計算群組init_warehouse建立查詢隊列test_queue：

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

  • 樣本一：使用者p4_123、p4_456，或SQL指紋xxx、yyy，滿足任意一個條件即歸屬查詢隊列test_queue。

    -- 由於需要對使用者和SQL指紋這兩種屬性設定“或”的關係，因此，需要設定兩個分類器實現
    
    -- 建立分類器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_user', 'digest', 'xxx');
    CALL hg_set_classifier_rule_condition_value ('init_warehouse','test_queue', 'classifier_user', 'digest', 'yyy');

  • 樣本二：由應用xx_bi發起，且同時訪問了冷存和熱存，所有條件需同時滿足，才歸屬查詢隊列test_queue。

    -- 由於需要對應用和儲存類型這兩種屬性設定“且”的關係，因此，在同一個分類器內定義兩種屬性
    
    -- 建立分類器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”兩條，則需Query同時訪問冷存和熱存，才滿足該匹配規格
    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');

  • 樣本三：所有訪問了冷存資料的請求，均歸屬查詢隊列test_queue。

    -- 由於儲存類型的值需要完全符合，“所有訪問了冷存資料”的請求需拆分成如下兩個分類器，僅需進入一個分類器即可
    
    -- 建立分類器classifier_cold_1並綁定查詢隊列test_queue
    CALL hg_create_classifier ('init_warehouse', 'test_queue', 'classifier_cold_1');
    -- storage_mode僅為cold的Query進入該隊列
    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的Query進入該隊列
    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');

  • 樣本四：所有讀取了表a且寫入表b的請求，歸屬查詢隊列test_queue。

    -- 由於需要對讀表和寫表類型這兩種屬性設定“且”的關係，因此，在同一個分類器內定義兩種屬性
    
    -- 建立分類器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_3', 'read_table', 'db_name.schema_name.a');
    -- 設定按寫表的匹配規則，寫入b表的請求，滿足該匹配規則
    CALL hg_set_classifier_rule_condition_value ('init_warehouse','test_queue', 'classifier_3', 'write_table', 'db_name.schema_name.b');

更多操作

使用Serverless Computing資源執行查詢隊列的查詢

Hologres從V3.0.10版本起，支援指定某個查詢隊列中的查詢全部由Serverless Computing資源執行。設定後，隊列中的查詢將按請求順序和配置的優先順序申請Serverless資源執行，不再受查詢隊列的並發配置、排隊機制等因素影響。詳情請參見Serverless Computing使用指南。

• 通用型執行個體

  • 文法

    -- 設定目標Queue中的查詢全部通過Serverless資源運行
    CALL hg_set_query_queue_property('<query_queue_name>', 'computing_resource', 'serverless');
    
    -- （可選）設定目標Queue中的查詢使用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]。

  • 樣本

    -- 設定目標Queue中的查詢全部通過Serverless資源運行
    CALL hg_set_query_queue_property('insert_queue', 'computing_resource', 'serverless');
    
    -- 設定目標Queue中的查詢使用Serverless資源時的優先順序為2
    CALL hg_set_query_queue_property('insert_queue', 'query_priority_when_using_serverless_computing', '2');

• 計算群組型執行個體

  • 文法

    -- 設定目標Queue中的查詢全部通過Serverless資源運行
    CALL hg_set_query_queue_property('<warehouse_name>', '<query_queue_name>', 'computing_resource', 'serverless');
    
    -- （可選）設定目標Queue中的查詢使用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]。

  • 樣本

    -- 設定目標Queue中的查詢全部通過Serverless資源運行
    CALL hg_set_query_queue_property('init_warehouse', 'insert_queue', 'computing_resource', 'serverless');
    
    -- 設定目標Queue中的查詢使用Serverless資源時的優先順序為2
    CALL hg_set_query_queue_property('init_warehouse', 'insert_queue', 'query_priority_when_using_serverless_computing', '2');

查看指定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 查看 Query 所匹配的 Classifier 和 Query queue
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

查看活躍Query中SQL使用的查詢隊列

可以通過如下SQL查看活躍Query中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;

查看Query Log中SQL使用的查詢隊列

可以使用如下SQL查看Query Log中的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類型的SQL請求將被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 DB匹配規則的查詢隊列。樣本如下。

  建立完成後，test和postgres DB資料庫相關的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');