Hologres:Fila de Consultas

Criar uma fila de consultas

• Sintaxe

  • Instância de uso geral

    CALL hg_create_query_queue (query_queue_name, max_concurrency, max_queue_size);

  • Instância de virtual warehouse

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

• Descrição dos parâmetros

  • warehouse_name: Opcional. O nome da virtual warehouse. Se você não especificar este parâmetro, a fila de consultas é criada na virtual warehouse da conexão atual por padrão.

    Nota

    Este parâmetro é obrigatório apenas para instâncias de virtual warehouse.

  • query_queue_name: Obrigatório. O nome da fila de consultas. O nome deve ser único dentro da instância ou virtual warehouse atual.

  • max_concurrency: Opcional. A simultaneidade máxima. O valor padrão é -1, o que indica que não há limite de simultaneidade. O valor deve estar no intervalo de [-1, 2147483647).

  • max_queue_size: Opcional. O tamanho máximo da fila. Este parâmetro especifica o número máximo de instruções SQL que podem ser enfileiradas. O valor padrão é -1, o que indica que o tamanho da fila é ilimitado. O valor deve estar no intervalo de [-1, 2147483647).

  Nota

  Ao criar uma fila de consultas, você pode configurar as propriedades acima. Para obter informações sobre como definir outras propriedades, consulte Definir propriedades da fila de consultas.

• Exemplos

  • Instância de uso geral

    -- Create a query queue named insert_queue and set the maximum concurrency to 10. The concurrency parameter does not require single quotation marks.
    CALL hg_create_query_queue ('insert_queue', 10);

  • Instância de virtual warehouse

    -- In the init_warehouse virtual warehouse, create a query queue named insert_queue and set the maximum concurrency to 10.
    CALL hg_create_query_queue ('init_warehouse', 'insert_queue', 10);

Criar um classificador

• Sintaxe

  • Instância de uso geral

    CALL hg_create_classifier (query_queue_name, classifier_name, priority);

  • Instância de virtual warehouse

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

• Descrição dos parâmetros

  • warehouse_name: Opcional. O nome da virtual warehouse. Se você não especificar este parâmetro, a virtual warehouse da conexão atual é usada por padrão.

    Nota

    Este parâmetro se aplica apenas a instâncias de virtual warehouse.

  • query_queue_name: Obrigatório. O nome da fila de consultas para a qual você deseja criar um classificador.

  • classifier_name: Obrigatório. O nome do classificador. O nome deve ser único dentro da instância ou virtual warehouse atual.

  • priority: Opcional. A prioridade de correspondência do classificador. Um valor maior indica uma prioridade mais alta. O valor padrão é 50. O valor deve estar no intervalo de [1, 100]. Se você não especificar este parâmetro ao criar o classificador, poderá configurá-lo posteriormente. Para obter mais informações, consulte Definir propriedades do classificador.

    Nota

    • Classificadores com prioridade mais alta são correspondidos primeiro.

    • Se vários classificadores tiverem a mesma prioridade, eles serão correspondidos com base na ordem lexicográfica de suas filas de consultas e nomes de classificadores. O classificador com o nome que vem primeiro na ordem lexicográfica é correspondido primeiro. Por exemplo, queue_a(classifier_1) tem prioridade mais alta que queue_b(classifier_1).

• Exemplos

  • Instância de uso geral

    -- In the insert_queue query queue, create a classifier named classifier_insert with a matching priority of 20. Note that the priority parameter does not require single quotation marks.
    CALL hg_create_classifier ('insert_queue', 'classifier_insert', 20);

  • Instância de virtual warehouse

    -- In the insert_queue query queue of the init_warehouse virtual warehouse, create a classifier named classifier_insert with a matching priority of 20.
    CALL hg_create_classifier ('init_warehouse', 'insert_queue', 'classifier_insert', 20);

Configurar condições do classificador

Ao configurar condições do classificador, você pode rotear instruções SQL específicas para filas de consultas específicas. Se uma consulta satisfizer a condição de um classificador, ela será colocada na fila de consultas daquele classificador.

• Sintaxe

  • Instância de uso geral

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

  • Instância de virtual warehouse

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

• Descrição dos parâmetros

  Nome	Descrição
  warehouse_name	Opcional. O nome da virtual warehouse. Se você não configurar este parâmetro, a virtual warehouse da conexão atual é usada por padrão. Nota Você deve configurar este parâmetro apenas para instâncias de virtual warehouse.
  query_queue_name	Obrigatório. O nome da fila de consultas.
  classifier_name	Obrigatório. O nome do classificador para o qual você deseja adicionar uma regra de correspondência.
  condition_name and condition_value	Obrigatório. As condições suportadas são: user_name: O UID da conta atual. command_tag: O tipo de solicitação. Valores válidos: INSERT, SELECT, UPDATE e DELETE. Para melhorar a eficiência de execução de operações COPY, o Hologres implementa operações COPY usando INSERT. Portanto, quando a simultaneidade de operações INSERT é limitada, a simultaneidade de gravação de operações COPY também é afetada. db_name: O nome do banco de dados. engine_type: O mecanismo usado pela solicitação. Valores válidos: HQE, PQE, SQE e HiveQE. Recomendamos que você use esta propriedade a partir do Hologres V3.1.18. digest: A impressão digital SQL. Para obter mais informações sobre impressões digitais SQL, consulte Impressões digitais SQL. application_name: O aplicativo que iniciou a consulta. Esta propriedade é suportada apenas no Hologres V3.0.9 e posterior. storage_mode: O modo de armazenamento. Valores válidos: hot e cold. Recomendamos que você use esta propriedade a partir do Hologres V3.1.18 ou V3.1.8. write_table: A tabela de destino da consulta. O formato é <db_name>.<schema_name>.<table_name>. Esta propriedade é suportada apenas no Hologres V3.1 e posterior. read_table: A tabela de origem da consulta. Esta propriedade é suportada apenas no Hologres V3.1 e posterior.

  Os classificadores suportam várias condições, e cada condição pode aceitar um conjunto de valores. A partir do Hologres V3.1.18, regras avançadas de classificador são suportadas. Observe o seguinte:

  • Relação entre condições:

    • Lógica AND: Quando um classificador tem várias condições (por exemplo, user_name AND command_tag), uma consulta deve satisfazer todas elas para entrar na fila daquele classificador.

    • Lógica OR: Para obter uma relação "OR" (onde uma consulta corresponde se atender a qualquer um dos vários critérios), crie vários classificadores separados, cada um com uma condição.

  • Corresponder vários valores dentro de uma condição

    • Correspondência de subconjunto (⊆): Para condições como user_name, command_tag, db_name, digest, application_name. Os valores da consulta devem ser um subconjunto dos valores aceitáveis.

    • Correspondência exata (==): Para storage_mode. Os valores da consulta devem corresponder exatamente aos valores aceitáveis.

    • Correspondência por interseção (∩): Para engine_type, write_table, read_table. A consulta deve compartilhar pelo menos um valor com os valores aceitáveis.

  Nota

  • Configure as condições de filtro uma a uma. Se o valor da condição diferenciar maiúsculas de minúsculas, coloque-o entre aspas duplas ("").

  • Se uma condição aceitar um conjunto de valores, defina-o várias vezes. Por exemplo, se um classificador precisar corresponder a solicitações onde command_tag seja SELECT ou INSERT, execute duas instruções SQL para definir as regras.

• Exemplos

  Os exemplos a seguir usam uma instância de virtual warehouse. Para uma instância de uso geral, ignore o primeiro parâmetro de entrada. Crie uma fila de consultas chamada test_queue para a virtual warehouse padrão init_warehouse:

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

  • Exemplo 1: Roteie uma consulta para a fila de consultas test_queue se a consulta for enviada pelo usuário p4_123 ou p4_456, ou se sua impressão digital SQL for xxx ou yyy.

    -- Because an OR relationship is required between the user and SQL fingerprint properties, you must configure two classifiers.
    
    -- Create a classifier named classifier_user and attach it to the test_queue query queue.
    CALL hg_create_classifier ('init_warehouse', 'test_queue', 'classifier_user');
    -- Set matching rules based on the user property. Queries from user "p4_123" or "p4_456" will hit this classifier.
    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');
    
    -- Create a classifier named classifier_digest and attach it to the test_queue query queue.
    CALL hg_create_classifier ('init_warehouse', 'test_queue', 'classifier_digest');
    -- Set matching rules based on the SQL fingerprint property. Queries with SQL fingerprint "xxx" or "yyy" will hit this classifier.
    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');

  • Exemplo 2: Roteie uma consulta para a fila de consultas test_queue se a consulta for iniciada pelo aplicativo xx_bi e acessar armazenamento cold e hot.

    -- Because an AND relationship is required between the application and storage class properties, define both properties within the same classifier.
    
    -- Create a classifier named classifier_3 and attach it to the test_queue query queue.
    CALL hg_create_classifier ('init_warehouse', 'test_queue', 'classifier_3');
    -- Set a condition based on the application property.
    CALL hg_set_classifier_rule_condition_value ('init_warehouse','test_queue', 'classifier_3', 'application_name', 'xx_bi');
    -- Set a condition based on the storage class. Set both "hot" and "cold" rules. A query must access both cold and hot storage to match.
    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');

  • Exemplo 3: Roteie todas as solicitações que acessam dados de armazenamento cold para a fila de consultas test_queue.

    -- Because the storage class value requires an exact match, requests that "access any cold storage data" must be split into the following two classifiers. The request only needs to match one of them.
    
    -- Create a classifier named classifier_cold_1 and attach it to the test_queue query queue.
    CALL hg_create_classifier ('init_warehouse', 'test_queue', 'classifier_cold_1');
    -- Queries where storage_mode is only 'cold' enter this queue.
    CALL hg_set_classifier_rule_condition_value ('init_warehouse','test_queue', 'classifier_cold_1', 'storage_mode', 'cold');
    
    -- Create a classifier named classifier_cold_2 and attach it to the test_queue query queue.
    CALL hg_create_classifier ('init_warehouse', 'test_queue', 'classifier_cold_2');
    -- Queries where storage_mode includes both 'hot' and 'cold' enter this queue.
    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');

  • Exemplo 4: Roteie todas as solicitações que leem da tabela a e gravam na tabela b para a fila de consultas test_queue.

    -- Because an AND relationship is required between the read table and write table properties, define both properties within the same classifier.
    
    -- Create a classifier named classifier_table and attach it to the test_queue query queue.
    CALL hg_create_classifier ('init_warehouse', 'test_queue', 'classifier_table');
    -- Set a matching rule based on the read table. A request matches this rule if it reads data from table a, regardless of whether it reads from other tables.
    CALL hg_set_classifier_rule_condition_value ('init_warehouse','test_queue', 'classifier_3', 'read_table', 'db_name.schema_name.a');
    -- Set a matching rule based on the write table. A request that writes to table b matches this rule.
    CALL hg_set_classifier_rule_condition_value ('init_warehouse','test_queue', 'classifier_3', 'write_table', 'db_name.schema_name.b');

Recursos avançados

Rotear consultas em uma fila para recursos do Serverless Computing

A partir do Hologres V3.0.10, você pode especificar que todas as consultas em uma fila de consultas específica sejam executadas por recursos do Serverless Computing. Após essa configuração, as consultas na fila solicitam recursos Serverless para execução com base na ordem de solicitação e prioridade configurada. Elas não são mais afetadas pela configuração de simultaneidade ou mecanismo de enfileiramento da fila de consultas. Para obter mais informações, consulte Guia do Usuário do Serverless Computing.

• Instância de uso geral

  • Sintaxe

    -- Set all queries in the target queue to run on Serverless resources.
    CALL hg_set_query_queue_property('<query_queue_name>', 'computing_resource', 'serverless');
    
    -- (Optional) Set the priority for queries in the target queue when using Serverless resources. Supported values are 1-5. The default is 3.
    CALL hg_set_query_queue_property('<query_queue_name>', 'query_priority_when_using_serverless_computing', '<priority>');

  • Descrição dos parâmetros

    • query_queue_name: Obrigatório. O nome da fila de consultas.

    • priority: A prioridade. O valor padrão é 3. O valor deve estar no intervalo de [1, 5].

  • Exemplo

    -- Set all queries in the target queue to run on Serverless resources.
    CALL hg_set_query_queue_property('insert_queue', 'computing_resource', 'serverless');
    
    -- Set the priority to 2 for queries in the target queue when using Serverless resources.
    CALL hg_set_query_queue_property('insert_queue', 'query_priority_when_using_serverless_computing', '2');

• Instância de virtual warehouse

  • Sintaxe

    -- Set all queries in the target queue to run on Serverless resources.
    CALL hg_set_query_queue_property('<warehouse_name>', '<query_queue_name>', 'computing_resource', 'serverless');
    
    -- (Optional) Set the priority for queries in the target queue when using Serverless resources. Supported values are 1-5. The default is 3.
    CALL hg_set_query_queue_property('<warehouse_name>', '<query_queue_name>', 'query_priority_when_using_serverless_computing', '<priority>');

  • Descrição dos parâmetros

    • warehouse_name: Obrigatório. O nome da virtual warehouse.

    • query_queue_name: Obrigatório. O nome da fila de consultas.

    • priority: Obrigatório. A prioridade. O valor padrão é 3. O valor deve estar no intervalo de [1, 5].

  • Exemplo

    -- Set all queries in the target queue to run on Serverless resources.
    CALL hg_set_query_queue_property('init_warehouse', 'insert_queue', 'computing_resource', 'serverless');
    
    -- Set the priority to 2 for queries in the target queue when using Serverless resources.
    CALL hg_set_query_queue_property('init_warehouse', 'insert_queue', 'query_priority_when_using_serverless_computing', '2');

View the query queue for a SQL query

Run EXPLAIN to view the query queue used by a specific SQL statement. The Query Queue field shows the query queue used. The following code provides an example.

-- Create a query queue with a concurrency of 10 and a maximum queue size of 20.
CALL hg_create_query_queue ('select_queue', 10, 20);
-- Create a classifier and set the command_tag property.
CALL hg_create_classifier ('select_queue', 'classifier_1');
CALL hg_set_classifier_rule_condition_value ('select_queue', 'classifier_1', 'command_tag', 'select');

-- Use Explain Analyze to view the classifier and query queue matched by the query.
EXPLAIN ANALYZE SELECT * FROM hg_stat_activity;

O seguinte resultado é retornado.

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

View the query queues for active queries

Execute the following SQL statement to view information, such as the query queue name, current status, and queue time, for SQL statements in active queries.

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;

View the query queues for SQL statements in the Query Log

Você pode executar a seguinte instrução SQL para visualizar a fila de consultas, o status atual e o tempo de enfileiramento das instruções SQL no Query Log. O campo query_detail registra a fila de consultas usada pela instrução SQL. Para obter mais informações sobre a tabela de sistema hologres.hg_query_log, consulte A tabela hg_query_log.

SELECT * FROM hologres.hg_query_log WHERE query_detail like '%query_queue = <warehouse_name>.<queue_name>%';-- You must configure the warehouse_name parameter only for virtual warehouse-based instances.

Criar filas de consultas para tipos específicos de consulta

• Exemplo 1: Criar uma fila de consultas que aceita tipos específicos de solicitações, como INSERT.

  After the query queue is created, all INSERT requests are matched by the classifier_1 classifier and routed to the insert_queue query queue.

  -- Create a query queue with a concurrency of 10 and a maximum queue size of 20.
  CALL hg_create_query_queue ('insert_queue', 10, 20);
  
  -- Create a classifier and attach the command_tag property.
  CALL hg_create_classifier ('insert_queue', 'classifier_1');
  CALL hg_set_classifier_rule_condition_value ('insert_queue', 'classifier_1', 'command_tag', 'INSERT');

• Example 2: Create a query queue that accepts requests from specific users, like users p4_123 and p4_345.

  After creation, SQL requests submitted by users p4_123 and p4_345 are matched by classifier_2 and routed to the user_queue query queue.

  -- Create a query queue with a concurrency of 3 and an unlimited maximum queue size.
  CALL hg_create_query_queue ('user_queue', 3);
  CALL hg_set_query_queue_property('user_queue','max_queue_size', -1);
  -- Create a classifier and set a user_name matching rule.
  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');

  Nota

  If you specify a custom user account, you must enclose its name in double quotation marks (""). For example, CALL hg_set_classifier_rule_condition_value ('user_queue', 'classifier_2', 'user_name', '"BASIC$xxx"');.

• Create a query queue that accepts queries related to the test and postgres databases.

  After the query queue is created, SQL requests related to the test and postgres databases are matched by classifier_3 and assigned to the db_queue query queue.

  -- Create a query queue with a concurrency of 5.
  CALL hg_create_query_queue ('db_queue', 5);
  
  -- Set the maximum queue time to 600000 ms. If a query waits longer than this time, an error is reported.
  CALL hg_set_query_queue_property ('db_queue', 'queue_timeout_ms', '600000');
  
  -- Create a classifier and attach the db_name property.
  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');

• Create a query queue that accepts requests related to the HQE engine.

  After the query queue is created, SQL requests related to the HQE engine are matched by classifier_4 and routed to the hqe_queue query queue.

  -- Create a query queue with a concurrency of 10.
  CALL hg_create_query_queue ('hqe_queue', 10);
  
  -- Create a classifier and attach the engine_type property.
  CALL hg_create_classifier ('hqe_queue', 'classifier_4');
  CALL hg_set_classifier_rule_condition_value ('hqe_queue', 'classifier_4', 'engine_type', 'HQE');

Bloquear todas as solicitações

Set the concurrency and queue size of insert_queue to 0 to block queries from entering a query queue.

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