Query Queue（Beta）

创建查询队列

• 语法

  • 通用型实例

    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：必填，当前支持的条件属性：

    说明

    • 每次只能配置一个条件属性，若条件值大小写敏感，则需要带上双引号。

    • 若同一种条件属性需匹配多个条件值，则需进行多次设置。例如：若分类器对command_tag为SELECT和INSERT的请求均需匹配，则需执行两条SQL语句进行设置。

    • 分类器可以设置多个条件属性，条件属性之间为并的关系，而条件属性内部则为或的关系。例如：存在一个分类器，该分类器包含user_name和command_tag两个数据属性，这两个属性之间为并的关系；而在user_name内设置的各个用户则为或的关系。

    • user_name：当前账号的UID。

    • command_tag：请求类型。取值：INSERT、SELECT、UPDATE、DELETE。

      为了提高COPY操作的执行效率，Hologres是通过INSERT来实现COPY操作。因此，当INSERT操作的并发受到限制时，COPY操作的写入并发同样会受到影响。

    • db_name：数据库名称。

    • engine_type：请求使用的引擎。取值：HQE、PQE、SQE、HiveQE。

    • digest：SQL指纹。关于SQL指纹详情，请参见SQL指纹。

    • storage_mode：存储模式。取值：hot、cold。

• 示例

  • 通用型实例

    -- 在insert_queue查询队列的classifier_insert分类器中，设置command_tag为INSERT的匹配规则
    CALL hg_set_classifier_rule_condition_value ('insert_queue', 'classifier_insert', 'command_tag', 'INSERT');
    
    -- 在insert_queue查询队列的classifier_insert分类器中，设置user_name为p4_12345的匹配规则
    CALL hg_set_classifier_rule_condition_value ('insert_queue', 'classifier_insert', 'user_name', 'p4_12345');
    
    -- 在insert_queue查询队列的classifier_insert分类器中，设置db_name为prd_db的匹配规则
    CALL hg_set_classifier_rule_condition_value ('insert_queue', 'classifier_insert', 'db_name', 'prd_db');
    
    -- 在insert_queue查询队列的classifier_insert分类器中，设置engine_type为HQE的匹配规则
    CALL hg_set_classifier_rule_condition_value ('insert_queue', 'classifier_insert', 'engine_type', 'HQE');
    
    -- 在insert_queue查询队列的classifier_insert分类器中，设置digest为md5edb3161000a003799a5d3f2656b70b4c的匹配规则
    CALL hg_set_classifier_rule_condition_value ('insert_queue', 'classifier_insert', 'digest', 'md5edb3161000a003799a5d3f2656b70b4c');
    
    -- 在insert_queue查询队列的classifier_insert分类器中，设置storage_mode为hot的匹配规则
    CALL hg_set_classifier_rule_condition_value ('insert_queue', 'classifier_insert', 'storage_mode', 'hot');

  • 计算组型实例

    -- 在init_warehouse计算组的insert_queue查询队列的classifier_insert分类器中，设置command_tag为INSERT的匹配规则
    CALL hg_set_classifier_rule_condition_value ('init_warehouse','insert_queue', 'classifier_insert', 'command_tag', 'INSERT');
    
    -- 在init_warehouse计算组的insert_queue查询队列的classifier_insert分类器中，设置user_name为p4_12345的匹配规则
    CALL hg_set_classifier_rule_condition_value ('init_warehouse','insert_queue', 'classifier_insert', 'user_name', 'p4_12345');
    
    -- 在init_warehouse计算组的insert_queue查询队列的classifier_insert分类器中，设置db_name为prd_db的匹配规则
    CALL hg_set_classifier_rule_condition_value ('init_warehouse','insert_queue', 'classifier_insert', 'db_name', 'prd_db');
    
    -- 在init_warehouse计算组的insert_queue查询队列的classifier_insert分类器中，设置engine_type为HQE的匹配规则
    CALL hg_set_classifier_rule_condition_value ('init_warehouse','insert_queue', 'classifier_insert', 'engine_type', 'HQE');
    
    -- 在init_warehouse计算组的insert_queue查询队列的classifier_insert分类器中，设置digest为md5edb3161000a003799a5d3f2656b70b4c的匹配规则
    CALL hg_set_classifier_rule_condition_value ('init_warehouse','insert_queue', 'classifier_insert', 'digest', 'md5edb3161000a003799a5d3f2656b70b4c');
    
    -- 在init_warehouse计算组的insert_queue查询队列的classifier_insert分类器中，设置storage_mode为hot的匹配规则
    CALL hg_set_classifier_rule_condition_value ('init_warehouse','insert_queue', 'classifier_insert', 'storage_mode', 'hot');

更多操作

分类器管理

使用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');

• 创建数据库名称为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');