Todos os produtos
Search

Este produto

    Hologres:Funções compatíveis com atualização incremental

    Central de documentação

    Hologres:Funções compatíveis com atualização incremental

    Última atualização: Jun 28, 2026

    A atualização incremental de Dynamic Table é compatível com funções de agregação básicas — COUNT, SUM, MIN/MAX e COUNT DISTINCT — além das funções estendidas listadas neste tópico.

    Lista de funções compatíveis

    Função

    Descrição

    Versão compatível

    ROW_NUMBER / RANK

    Window functions para processamento de TopN. Classificam linhas dentro de uma partição e filtram os N principais registros. Apenas ROW_NUMBER e RANK são compatíveis. Defina refresh_mode como auto para ative a atualização incremental automática.

    V4.2 e posterior

    COUNT, SUM, MIN/MAX, COUNT DISTINCT

    Funções de agregação básicas

    Todas as versões

    hg_id_encoding_int32 / hg_id_encoding_int64

    Mapeiam um UID do tipo text para int32 ou int64 e gravam automaticamente o mapeamento em uma tabela de mapeamento de usuário. Uso comum no cálculo de visitantes únicos (UV) em longos períodos com RoaringBitmap.

    V4.1 e posterior

    min_by / max_by

    Retornam o valor de uma coluna da linha que possui o valor mínimo ou máximo em outra coluna.

    V4.0 e posterior

    RB_BUILD_AGG

    Constroem um RoaringBitmap a partir de uma coluna int32 ou int64.

    V3.1 e posterior

    string_agg

    Concatenam valores de coluna em uma string usando um delimitador. A sintaxe string_agg([distinct]) exige a versão V3.1.10 ou posterior.

    V3.1 e posterior

    array_agg

    Agregam valores de coluna em um array. A sintaxe array_agg([distinct]) exige a versão V3.1.10 ou posterior.

    V3.1 e posterior

    any_value

    Em uma consulta GROUP BY, retornam um valor não determinístico de cada grupo. Compatível apenas com os tipos int e binary.

    V3.1.5 e posterior

    ROW_NUMBER / RANK

    O Hologres V4.2 e versões posteriores são compatíveis com as window functions ROW_NUMBER() e RANK() na atualização incremental de Dynamic Table. Use essas funções para particionar e classificar linhas e filtrar os N principais registros de cada partição. Esse é um padrão comum para materialização de TopN em tempo real.

    Sintaxe

    SELECT [column_list]
FROM (
   SELECT [column_list],
     ROW_NUMBER() OVER ([PARTITION BY partition_column[, ...]]
       ORDER BY order_column [ASC|DESC][, ...]) AS rownum
   FROM table_name)
WHERE rownum <= N [AND conditions]

    Argumentos:

    • PARTITION BY partition_column: Opcional. Agrupa as linhas em partições antes da classificação.

    • ORDER BY order_column [ASC|DESC]: Obrigatório. Define a ordem de classificação dentro de cada partição.

    • rownum <= N: Obrigatório. Mantém apenas as N principais linhas de cada partição.

    Notas de uso

    • Disponível no Hologres V4.2 e versões posteriores.

    • Somente ROW_NUMBER() e RANK() são compatíveis. Outras window functions, como DENSE_RANK, LAG e LEAD, não têm suporte.

    • Defina refresh_mode como auto para permitir que o Hologres derive automaticamente o modo incremental para a Dynamic Table.

    Exemplo

    O exemplo abaixo crie uma Dynamic Table que mantém os 3 pedidos de maior valor por produto, com atualização incremental a cada 5 minutos.

    -- Create the source table
CREATE TABLE orders (
  order_id   bigint,
  product_id bigint,
  amount     bigint
);

INSERT INTO orders
SELECT i, i % 100, (random() * 1000000)::bigint
FROM generate_series(1, 10000) i;

-- Create the Dynamic Table for TopN
CREATE DYNAMIC TABLE top3_orders
WITH (
  freshness = '5 minutes',
  auto_refresh_mode = 'incremental'
) AS
SELECT order_id, product_id, amount
FROM (
   SELECT order_id, product_id, amount,
     ROW_NUMBER() OVER (PARTITION BY product_id ORDER BY amount DESC) AS rownum
   FROM orders)
WHERE rownum <= 3;

-- Query results for a specific product
SELECT * FROM top3_orders WHERE product_id = 1;

    hg_id_encoding_int32 / hg_id_encoding_int64

    As funções hg_id_encoding_int32 e hg_id_encoding_int64 mapeiam uma coluna UID do tipo text para int32 ou int64 e gravam automaticamente o mapeamento em uma tabela de mapeamento de usuário. Combine essas funções com a atualização incremental de Dynamic Table e RoaringBitmap para calcular UVs em longos períodos.

    Para um exemplo completo de ponta a ponta, consulte Cálculo de UV em períodos arbitrariamente longos usando Dynamic Tables do Hologres.

    Sintaxe

    hg_id_encoding_int4(<user_id>, '<mapping_tablename>')
hg_id_encoding_int8(<user_id>, '<mapping_tablename>')

    Argumentos

    Argumento

    Tipo

    Descrição

    user_id

    text

    Coluna UID a ser mapeada. Valores NULL não são aceitos; a função retorna erro se receber NULL.

    mapping_tablename

    text

    Nome da tabela de mapeamento de usuário. Crie esta tabela antes de chamar a função.

    Comportamento

    Grava novos mapeamentos de UID para inteiro na tabela de mapeamento de usuário. Caso o UID já exista na tabela, o mapeamento atual é preservado e nenhuma duplicata é inserida.

    Notas de uso

    • Compatível com Hologres V4.1 e versões posteriores.

    • A tabela de mapeamento de usuário deve ter uma chave primária e exatamente um campo Serial (além da chave primária).

    • Apenas chaves primárias de coluna única do tipo text são aceitas.

    Exemplo

    -- Create the source table
CREATE TABLE base_table(user_id text);
INSERT INTO base_table VALUES('a');

-- Create the user mapping table
CREATE TABLE uid_mapping(user_id text PRIMARY KEY, id serial);

-- Map UIDs to integers and write mappings to uid_mapping
SELECT user_id, hg_id_encoding_int4(user_id, 'uid_mapping') AS res
FROM base_table;

-- Query the mapping table to verify
-- user_id | id
-- --------+----
--   a     |  1

    min_by / max_by

    As funções min_by e max_by retornam o valor de uma coluna correspondente à linha que contém o valor mínimo ou máximo em outra coluna.

    Sintaxe

    min_by(expr1, expr2)
max_by(expr1, expr2)

    Argumentos

    Argumento

    Descrição

    expr2

    Coluna usada para comparação (onde se busca o valor mínimo ou máximo).

    expr1

    Coluna cujo valor será retornado da linha correspondente.

    Retorno

    Retorna o valor de expr1 da linha onde expr2 atinge seu valor mínimo (min_by) ou máximo (max_by).

    Notas de uso

    Recurso disponível no Hologres V4.0 e versões posteriores.

    Exemplo

    Este exemplo demonstra a criação de uma Dynamic Table que rastreia o primeiro e o último evento de cada usuário, com base nos timestamps dos eventos.

    -- Create the source table
DROP TABLE IF EXISTS detail;
CREATE TABLE detail (
  userid       text,
  event_id     text,
  create_time  timestamptz
);

INSERT INTO detail(userid, event_id, create_time) VALUES
  ('user_1', 'e1', '2024-12-20 10:00:00+08'),
  ('user_1', 'e2', '2024-12-20 11:30:00+08'),
  ('user_1', 'e3', '2024-12-21 09:15:00+08'),
  ('user_2', 'e4', '2024-12-20 08:05:00+08'),
  ('user_2', 'e5', '2024-12-22 14:20:00+08'),
  ('user_3', 'e6', '2024-12-21 16:45:00+08');

-- Create the Dynamic Table
DROP TABLE IF EXISTS detail_user_first_last_event;

CREATE DYNAMIC TABLE detail_user_first_last_event
WITH (
  auto_refresh_mode = 'incremental',
  computing_resource = 'local',
  freshness = '3 minutes'
)
AS
SELECT
  userid,
  min_by(event_id, create_time) AS first_event_id,
  max_by(event_id, create_time) AS last_event_id,
  date_trunc('day', max(create_time))::date AS dt
FROM detail
GROUP BY userid;

    string_agg

    A função string_agg concatena valores não nulos de uma coluna em uma única string, separados por um delimitador constante.

    Sintaxe

    string_agg([distinct] column_expr, const_expr)

    Argumentos

    Argumento

    Tipo

    Descrição

    column_expr

    text, char ou varchar

    Coluna a ser agregada.

    const_expr

    constante text

    Delimitador inserido entre os valores concatenados.

    Notas de uso

    • A cláusula ORDER BY não é compatível.

    • A sintaxe string_agg([distinct]) requer Hologres V3.1.10 ou superior.

    • A função básica string_agg está disponível a partir do Hologres V3.1.

    Exemplo

    CREATE DYNAMIC TABLE string_agg_test_dt
  WITH (
    freshness = '3 minutes',
    refresh_mode = 'incremental')
  AS
  SELECT day,
         string_agg(gameversion, ',') AS gameversion_list
    FROM base_table GROUP BY day;

    array_agg

    A função array_agg coleta valores não nulos de uma coluna e os organiza em um array.

    Sintaxe

    array_agg([distinct] expr)

    Argumentos

    Argumento

    Tipo

    Descrição

    expr

    boolean, qualquer tipo numérico, text ou bytea

    Coluna a ser agregada em um array.

    Notas de uso

    • A cláusula ORDER BY não é compatível.

    • A sintaxe array_agg([distinct]) requer Hologres V3.1.10 ou posterior.

    • A versão básica de array_agg está disponível no Hologres V3.1 e versões posteriores.

    Exemplo

    CREATE DYNAMIC TABLE array_agg_test_dt
  WITH (
    freshness = '3 minutes',
    refresh_mode = 'incremental')
  AS
  SELECT day,
         array_agg(gameversion) AS gameversion_list
    FROM base_table GROUP BY day;

    any_value

    Em consultas com GROUP BY, a função any_value retorna um valor não determinístico de cada grupo de agregação.

    Sintaxe

    any_value(expr)

    Argumentos

    Argumento

    Tipo

    Descrição

    expr

    int ou binary

    Coluna da qual um valor será retornado.

    Notas de uso

    • Compatível com Hologres V3.1.5 e versões posteriores.

    • O parâmetro expr aceita exclusivamente os tipos int e binary.

    • O valor retornado é não determinístico.

    Exemplo

    CREATE DYNAMIC TABLE dt_t0
WITH (
  freshness = '1 minutes',
  auto_refresh_mode = 'auto'
)
AS
SELECT a, any_value(c), sum(b) FROM t0 GROUP BY a;

    Próximos passos