finder_group_funnel

El análisis de embudo estándar trata a todos los usuarios como un solo grupo. Cuando necesita comparar tasas de conversión entre segmentos de usuarios (por ejemplo, por provincia, canal de adquisición o tipo de dispositivo), utilice finder_group_funnel para dividir los resultados del embudo según un campo de dimensión TEXT.

Cada usuario se asigna a exactamente un grupo según el valor de la dimensión presente en el evento de agrupación. Los usuarios que no alcanzan el evento de agrupación, o cuyo valor de dimensión no coincide con ningún grupo, se asignan al grupo integrado unreach.

La función devuelve un resultado codificado en BINARY por cada usuario y grupo. Para extraer datos utilizables, decodifique la salida mediante dos funciones complementarias:

finder_group_funnel_res — decodifica el progreso del embudo de cada usuario por paso
finder_group_funnel_text_group — decodifica la etiqueta del grupo (valor de dimensión o unreach)

Para agregar los resultados por usuario en conteos de conversión a nivel de grupo, pase la salida decodificada a funnel_rep.

Requisitos previos

Antes de empezar, asegúrese de contar con lo siguiente:

Hologres V2.2.32 o posterior
Acceso de superusuario a la base de datos destino

Instalación de la extensión

Ejecute la siguiente sentencia como superusuario para instalar la extensión flow_analysis:

CREATE extension flow_analysis; -- Install the extension.

La extensión se instala a nivel de base de datos. Instálela solo una vez por cada base de datos.

De forma predeterminada, la extensión se carga en el esquema public y no puede cargarse en otros esquemas. Para invocar funciones desde un esquema diferente, utilice el formato public.function_name; por ejemplo, public.windowFunnel.

Funcionamiento

finder_group_funnel procesa los eventos en tres etapas:

Asignación de intervalos — Para cada fila de evento, server_timestamp determina a qué intervalo de paso (día, hora u otro intervalo) pertenece el evento.
Ordenamiento — Dentro de cada intervalo, los eventos se ordenan por client_timestamp para establecer la secuencia.
Agrupación y seguimiento — A partir de group_event_index, los usuarios se asignan a un grupo según su valor de group_dimension. Posteriormente, la función rastrea el progreso de cada usuario a través de la lista ordenada de check_event dentro de la duración de window.

El resultado es un valor codificado en BINARY por cada usuario y grupo. Pase la salida por la tubería de finder_group_funnel_res y finder_group_funnel_text_group para leer el progreso del embudo y las etiquetas de grupo.

Agrupa eventos según la dimensión especificada y calcula los resultados del embudo por usuario.

Sintaxis

finder_group_funnel(
  window,
  start_timestamp,
  step_interval,
  step_numbers,
  num_events,
  attr_related,
  group_event_index,
  time_zone,
  is_relative_window,
  server_timestamp,
  client_timestamp,
  group_dimension,
  [prop1, prop2, ...],
  check_event1, check_event2, ...
)

Parámetros

Parámetro	Obligatorio	Tipo	Descripción
`window`	Sí	—	Tamaño de la ventana de análisis. Unidad: milisegundos.
`start_timestamp`	Sí	TIMESTAMP / TIMESTAMPTZ	Hora de inicio del análisis.
`step_interval`	Sí	—	Duración de un paso (la granularidad del análisis de conversión). Unidad: segundos. Por ejemplo, `86400` = un día.
`step_numbers`	Sí	—	Número de pasos a analizar. Por ejemplo, `step_interval=86400` y `step_numbers=7` significa que la función analiza datos diarios del embudo durante 7 días a partir de `start_timestamp`.
`num_events`	Sí	—	Número total de eventos a rastrear en el embudo.
`attr_related`	Sí	UINT8	Indica qué eventos tienen propiedades asociadas. En forma binaria, si el bit `i`-ésimo es 1, el evento `(i+1)`-ésimo tiene propiedades asociadas. El número de expresiones `prop` debe ser igual al número de bits en 1. Establezca este valor en `0` si ningún evento tiene propiedades asociadas.
`group_event_index`	Sí	—	El evento en el que comienza la agrupación. Si se establece en `1`, los usuarios se agrupan tan pronto como completan el primer evento. Si se establece en `2`, la agrupación comienza en el segundo evento; los usuarios que no alcancen el segundo evento se asignarán al grupo `unreach`.
`time_zone`	Sí	TEXT	Zona horaria de las marcas de tiempo de entrada, en formato estándar (por ejemplo, `Asia/Shanghai`). Este parámetro solo afecta la salida cuando `is_relative_window` es `true`.
`is_relative_window`	Sí	BOOLEAN	Indica si se deben usar límites de día calendario en lugar de una ventana de duración fija. Valor predeterminado: `false`. Cuando se establece en `true`: `window` debe ser un múltiplo entero de 86,400,000 y `step_interval` debe ser `86400`. Consulte la sección Ventana de día calendario a continuación para más detalles.
`server_timestamp`	Sí	TIMESTAMP / TIMESTAMPTZ	Hora del evento en el servidor. Se usa para determinar a qué intervalo de paso pertenece cada evento.
`client_timestamp`	Sí	TIMESTAMP / TIMESTAMPTZ	Hora del evento en el cliente. Debe coincidir con el tipo de datos de `start_timestamp`. Se usa para ordenar los eventos.
`group_dimension`	Sí	TEXT	El campo por el cual agrupar. Solo se admiten campos TEXT. Para agrupar por varios campos, combínelos con `concat_ws` o `concat`.
`prop`	No	—	Propiedades asociadas para eventos con bits de `attr_related` establecidos en 1. Todas las expresiones `prop` deben tener el mismo tipo de datos.
`check_event`	Sí	—	Lista ordenada de eventos de conversión. Los eventos que coinciden dentro de la duración de `window` cuentan como conversiones válidas. Ejemplo: `event = 'E0001', event = 'E0002', event = 'E0003'`.

Ventana de día calendario

Cuando is_relative_window=true, la ventana utiliza límites de día calendario en lugar de una duración transcurrida fija:

Un día calendario abarca de 00:00:00 a 23:59:59.
El primer día abarca desde la hora del evento hasta las 23:59:59 del mismo día.
Cada día subsiguiente es un día calendario completo.

Utilice ventanas de día calendario cuando los periodos de reporte del embudo deban alinearse a días hábiles (de medianoche a medianoche) en lugar de intervalos móviles de 24 horas contados a partir del primer evento.

Valor devuelto

Un resultado codificado de tipo BINARY. Decodifíquelo con finder_group_funnel_res y finder_group_funnel_text_group.

Ejemplo

El siguiente ejemplo agrupa los resultados del embudo por provincia en una ventana de 3 días. El usuario 1111 es de Beijing y el usuario 2222 es de Zhejiang.

Paso 1: Cree la tabla de prueba e inserte datos.

CREATE TABLE finder_group_funnel_test(
  id INT,
  event_time TIMESTAMP,
  event TEXT,
  province TEXT,
  city TEXT
);

INSERT INTO finder_group_funnel_test VALUES
(1111, '2024-01-02 00:00:00', 'registration', 'Beijing',  'Beijing'),
(1111, '2024-01-02 00:00:01', 'logon',        'Beijing',  'Beijing'),
(1111, '2024-01-02 00:00:02', 'payment',      'Beijing',  'Beijing'),
(1111, '2024-01-02 00:00:03', 'exit',         'Beijing',  'Beijing'),

(1111, '2024-01-03 00:00:00', 'registration', 'Beijing',  'Beijing'),
(1111, '2024-01-03 00:00:01', 'logon',        'Beijing',  'Beijing'),
(1111, '2024-01-03 00:00:02', 'payment',      'Beijing',  'Beijing'),

(1111, '2024-01-04 00:00:00', 'registration', 'Beijing',  'Beijing'),
(1111, '2024-01-04 00:00:01', 'logon',        'Beijing',  'Beijing'),

(2222, '2024-01-02 00:00:00', 'registration', 'Zhejiang', 'Hangzhou'),
(2222, '2024-01-02 00:00:00', 'logon',        'Zhejiang', 'Hangzhou'),
(2222, '2024-01-02 00:00:01', 'payment',      'Zhejiang', 'Hangzhou'),
(2222, '2024-01-02 00:00:03', 'payment',      'Zhejiang', 'Hangzhou');

Paso 2: Agrupe los resultados por provincia en una ventana de 3 días.

SELECT
    id,
    UNNEST(
        finder_group_funnel(
            86400000 * 3,                                              -- 3-day window
            EXTRACT(epoch FROM TIMESTAMP '2024-01-02 00:00:00')::BIGINT,
            86400,                                                     -- step_interval: 1 day
            3,                                                         -- step_numbers: 3 days
            4,                                                         -- num_events: 4 events
            0,                                                         -- attr_related: no associated properties
            1,                                                         -- group_event_index: group on first event
            'Asia/Shanghai',
            FALSE,
            event_time,
            event_time,
            province,                                                  -- group_dimension
            event = 'registration',
            event = 'logon',
            event = 'payment',
            event = 'exit'
        )
    ) AS result
FROM finder_group_funnel_test
GROUP BY id;

El resultado está codificado en BINARY. Cada fila muestra el ID del usuario y su etiqueta de grupo (valor de provincia o unreach):

  id  | result
------+---------
 2222 | Zhejiang
 2222 | unreach
 1111 | Beijing
 1111 | unreach
(4 rows)

Para decodificar el progreso detallado del embudo de cada grupo, utilice finder_group_funnel_res.

finder_group_funnel_res

Decodifica el resultado BINARY de finder_group_funnel en detalles del embudo por usuario para cada paso.

Sintaxis

finder_group_funnel_res(finder_group_funnel(...))

Parámetros

Parámetro	Descripción
`finder_group_funnel()`	El resultado BINARY de `finder_group_funnel`.

Valor devuelto

Un arreglo de enteros que muestra el evento más lejano alcanzado en la ventana general y en cada intervalo de paso.

Ejemplo

Con la tabla del finder_group_funnel example, decodifique el progreso diario del embudo de cada usuario:

SELECT
    id,
    finder_group_funnel_res(result) AS res
FROM (
    SELECT
        id,
        UNNEST(
            finder_group_funnel(
                86400000 * 3,
                EXTRACT(epoch FROM TIMESTAMP '2024-01-02 00:00:00')::BIGINT,
                86400, 3, 4, 0, 1, 'Asia/Shanghai', FALSE,
                event_time, event_time,
                province,
                event = 'register',
                event = 'logon',
                event = 'pay',
                event = 'exit'
            )
        ) AS result
    FROM finder_group_funnel_test
    GROUP BY id
) a;

Resultado:

  id  |    res
------+-----------
 1111 | {4,4,3,2}
 1111 | {0,0,0,0}
 2222 | {3,3,0,0}
 2222 | {0,0,0,0}

Lectura del arreglo de resultados: Cada arreglo tiene 1 + step_numbers elementos. El primer elemento es el evento más lejano alcanzado en toda la ventana; los elementos restantes son el evento más lejano alcanzado dentro de cada intervalo de paso (día, en este caso).

Para el usuario 1111 con resultado {4,4,3,2}:

Posición	Valor	Significado
General (ventana de 3 días)	4	Alcanzó el cuarto evento (`exit`) dentro de 3 días
Día 1	4	Alcanzó `exit` el día 1
Día 2	3	Alcanzó el tercer evento (`payment`) el día 2
Día 3	2	Alcanzó el segundo evento (`logon`) el día 3

finder_group_funnel_text_group

Decodifica la etiqueta del grupo (valor de dimensión o unreach) del resultado BINARY. Utilícela junto con finder_group_funnel_res para obtener tanto el nombre del grupo como los datos del embudo en una sola consulta.

Sintaxis

finder_group_funnel_text_group(finder_group_funnel(...))

Parámetros

Parámetro	Descripción
`finder_group_funnel()`	El resultado BINARY de `finder_group_funnel`.

Valor devuelto

La etiqueta del grupo decodificada como texto: el valor de la dimensión (por ejemplo, Beijing) o unreach.

Ejemplo

La siguiente consulta decodifica tanto la etiqueta del grupo como el progreso diario del embudo en una sola pasada:

SELECT
    id,
    finder_group_funnel_text_group(result) AS key,
    finder_group_funnel_res(result) AS res
FROM (
    SELECT
        id,
        UNNEST(
            finder_group_funnel(
                86400000 * 3,
                EXTRACT(epoch FROM TIMESTAMP '2024-01-02 00:00:00')::BIGINT,
                86400, 3, 4, 0, 1, 'Asia/Shanghai', FALSE,
                event_time, event_time,
                province,
                event = 'registration',
                event = 'logon',
                event = 'payment',
                event = 'exit'
            )
        ) AS result
    FROM finder_group_funnel_test
    GROUP BY id
) a;

Resultado:

  id  |   key    |    res
------+----------+-----------
 2222 | Zhejiang | {3,3,0,0}
 2222 | unreach  | {0,0,0,0}
 1111 | Beijing  | {4,4,3,2}
 1111 | unreach  | {0,0,0,0}
(4 rows)

funnel_rep

Agrega los resultados del embudo por usuario (de finder_group_funnel_res) en conteos de conversión a nivel de grupo para cada paso del embudo.

Sintaxis

funnel_rep(step_number, num_events, funnel_res)

Parámetros

Parámetro	Obligatorio	Tipo	Descripción
`step_number`	Sí	UINT	Número de intervalos de tiempo. Normalmente es el mismo valor que `step_numbers` en `finder_group_funnel`.
`num_events`	Sí	UINT	Total de eventos en el embudo. Normalmente coincide con el número de expresiones `check_event`.
`funnel_res`	Sí	—	Detalles de pasos de conversión por usuario generados por cada usuario, que corresponden a la salida de `finder_group_funnel` o `FINDER_FUNNEL`.

Valor devuelto

Un arreglo de cadenas con el formato {"overall","step1","step2",...}. Cada elemento es una lista separada por comas de conteos de usuarios que alcanzaron los eventos del 1 al N:

El primer elemento es el conteo general en toda la ventana.
Cada elemento subsiguiente es el conteo dentro de ese intervalo de paso.

Ejemplo

Con los datos del ejemplo de finder_group_funnel, calcule cuántos usuarios alcanzaron cada evento en una ventana de 3 días con un paso de 1 día:

-- 3-day window, 1-day step: count users reaching each event per day.
SELECT
    funnel_rep(3, 4, funnel_res)
FROM (
    SELECT
        id,
        FINDER_FUNNEL(
            86400000 * 3,
            EXTRACT(epoch FROM TIMESTAMP '2024-01-02 00:00:00')::BIGINT,
            86400, 3, 4, 0, 'Asia/Shanghai', FALSE,
            event_time, event_time,
            event = 'registration',
            event = 'logon',
            event = 'payment',
            event = 'exit'
        ) AS funnel_res
    FROM finder_group_funnel_test
    GROUP BY id
) a;

Resultado:

                funnel_rep
-------------------------------------------
 {"2,2,2,1","2,2,2,1","1,1,1,0","1,1,0,0"}
(1 row)

Al interpretar este resultado con step_numbers=3 y num_events=4:

Elemento	Valor	Significado
General	`2,2,2,1`	En 3 días: 2 usuarios alcanzaron el evento 1, 2 alcanzaron el evento 2, 2 alcanzaron el evento 3, 1 alcanzó el evento 4
Día 1	`2,2,2,1`	El día 1: mismo patrón
Día 2	`1,1,1,0`	El día 2: 1 usuario alcanzó los eventos 1–3, ninguno alcanzó el evento 4
Día 3	`1,1,0,0`	El día 3: 1 usuario alcanzó los eventos 1–2, ninguno alcanzó los eventos 3–4

Ejemplos completos

Escenario 1: Agrupar resultados del embudo por dimensión en una ventana de varios días

Objetivo: Un equipo de comercio electrónico desea comparar cómo convierten los usuarios de Beijing, Shanghái y Zhejiang a través de un flujo de 4 pasos (registro → inicio de sesión → pago → salida) dentro de una ventana móvil de 3 días, con desgloses diarios. El equipo espera que los usuarios de Beijing muestren la tasa de finalización más alta en todos los días.

Paso 1: Cree la tabla de prueba e inserte datos.

CREATE TABLE finder_group_funnel_test_1(
  id INT,
  event_time TIMESTAMP,
  event TEXT,
  province TEXT,
  city TEXT
);

INSERT INTO finder_group_funnel_test_1 VALUES
(1111, '2024-01-02 00:00:00', 'registration', 'Beijing',  'Beijing'),
(1111, '2024-01-02 00:00:01', 'logon',        'Beijing',  'Beijing'),
(1111, '2024-01-02 00:00:02', 'payment',      'Beijing',  'Beijing'),
(1111, '2024-01-02 00:00:03', 'exit',         'Beijing',  'Beijing'),

(1111, '2024-01-03 00:00:00', 'registration', 'Beijing',  'Beijing'),
(1111, '2024-01-03 00:00:01', 'logon',        'Beijing',  'Beijing'),
(1111, '2024-01-03 00:00:02', 'payment',      'Beijing',  'Beijing'),

(1111, '2024-01-04 00:00:00', 'registration', 'Beijing',  'Beijing'),
(1111, '2024-01-04 00:00:01', 'logon',        'Beijing',  'Beijing'),

(2222, '2024-01-02 00:00:00', 'registration', 'Zhejiang', 'Hangzhou'),
(2222, '2024-01-02 00:00:00', 'logon',        'Zhejiang', 'Hangzhou'),
(2222, '2024-01-02 00:00:01', 'payment',      'Zhejiang', 'Hangzhou'),
(2222, '2024-01-02 00:00:03', 'payment',      'Zhejiang', 'Hangzhou'),

(3333, '2024-01-02 00:00:00', 'registration', 'Shanghai', 'Shanghai'),
(3333, '2024-01-02 00:00:00', 'logon',        'Shanghai', 'Shanghai'),
(3333, '2024-01-02 00:00:01', 'payment',      'Shanghai', 'Shanghai'),
(3333, '2024-01-02 00:00:03', 'payment',      'Shanghai', 'Shanghai'),
(3333, '2024-01-02 00:00:04', 'exit',         'Shanghai', 'Shanghai');

Paso 2: Consulte los datos diarios del embudo agrupados por provincia.

SELECT
    key,
    funnel_rep(3, 4, res) AS ans
FROM (
    SELECT
        id,
        finder_group_funnel_text_group(result) AS key,
        finder_group_funnel_res(result) AS res
    FROM (
        SELECT
            id,
            UNNEST(
                finder_group_funnel(
                    86400000 * 3,
                    EXTRACT(epoch FROM TIMESTAMP '2024-01-02 00:00:00')::BIGINT,
                    86400, 3, 4, 0, 1, 'Asia/Shanghai', FALSE,
                    event_time, event_time,
                    province,
                    event = 'Register',
                    event = 'Log on',
                    event = 'Payment',
                    event = 'Exit'
                )
            ) AS result
        FROM finder_group_funnel_test_1
        GROUP BY id
    ) a
) b
GROUP BY key;

Resultado:

   key    |                    ans
----------+-------------------------------------------
 Beijing  | {"1,1,1,1","1,1,1,1","1,1,1,0","1,1,0,0"}
 unreach  | {"0,0,0,0","0,0,0,0","0,0,0,0","0,0,0,0"}
 Shanghai | {"1,1,1,1","1,1,1,1","0,0,0,0","0,0,0,0"}
 Zhejiang | {"1,1,1,0","1,1,1,0","0,0,0,0","0,0,0,0"}
(4 rows)

El usuario de Beijing completó los 4 eventos el día 1 y continuó convirtiendo los días 2 y 3. El usuario de Shanghái también completó los 4 eventos, pero solo el día 1 (sin actividad posterior). El usuario de Zhejiang alcanzó solo 3 de los 4 eventos.

Escenario 2: Agrupar resultados del embudo por día calendario

Objetivo: El mismo equipo desea observar datos del embudo alineados a límites de día calendario (de medianoche a medianoche) en lugar de una ventana móvil de tiempo transcurrido. Esto coincide con la definición típica de los periodos de reporte empresarial. Con una ventana móvil, el evento exit del 2024-01-05 podría caer todavía dentro de los 3 días posteriores al primer evento; con límites de día calendario, esto no ocurre.

Paso 1: Cree la tabla de prueba e inserte datos.

CREATE TABLE finder_group_funnel_test_2(
  id INT,
  event_time TIMESTAMP,
  event TEXT,
  province TEXT,
  city TEXT
);

INSERT INTO finder_group_funnel_test_2 VALUES
(1111, '2024-01-02 00:00:02', 'registration', 'Beijing',  'Beijing'),
(1111, '2024-01-02 00:00:03', 'logon',        'Beijing',  'Beijing'),

(1111, '2024-01-03 00:00:04', 'payment',      'Beijing',  'Beijing'),

(1111, '2024-01-05 00:00:01', 'exit',         'Beijing',  'Beijing'),

(2222, '2024-01-02 00:00:00', 'registration', 'Zhejiang', 'Hangzhou'),
(2222, '2024-01-02 00:00:00', 'logon',        'Zhejiang', 'Hangzhou'),
(2222, '2024-01-02 00:00:01', 'payment',      'Zhejiang', 'Hangzhou'),
(2222, '2024-01-02 00:00:03', 'payment',      'Zhejiang', 'Hangzhou');

Paso 2: Consulte con límites de día calendario (is_relative_window=TRUE).

SELECT
    key,
    funnel_rep(3, 4, res) AS ans
FROM (
    SELECT
        id,
        finder_group_funnel_text_group(result) AS key,
        finder_group_funnel_res(result) AS res
    FROM (
        SELECT
            id,
            UNNEST(
                finder_group_funnel(
                    86400000 * 3,
                    EXTRACT(epoch FROM TIMESTAMP '2024-01-02 00:00:00')::BIGINT,
                    86400, 3, 4, 0, 1, 'Asia/Shanghai', TRUE, -- calendar-day window
                    event_time, event_time,
                    province,
                    event = 'register',
                    event = 'logon',
                    event = 'pay',
                    event = 'exit'
                )
            ) AS result
        FROM finder_group_funnel_test_2
        GROUP BY id
    ) a
) b
GROUP BY key;

Resultado:

   key    |                    ans
----------+-------------------------------------------
 unreach  | {"0,0,0,0","0,0,0,0","0,0,0,0","0,0,0,0"}
 Zhejiang | {"1,1,1,0","1,1,1,0","0,0,0,0","0,0,0,0"}
 Beijing  | {"1,1,1,0","1,1,1,0","0,0,0,0","0,0,0,0"}
(3 rows)

Con límites de día calendario, el usuario 1111 (Beijing) completa solo 3 de 4 eventos dentro de la ventana de 3 días. Su evento exit ocurre el 2024-01-05, lo cual queda fuera de la ventana de día calendario que inicia el 2024-01-02 (y cubre el 2, 3 y 4 de enero). Bajo una ventana móvil, el mismo evento se capturaría porque cae dentro de los 3 × 86,400 segundos posteriores al primer evento.

Limitaciones

Limitación	Detalles
Requisito de versión	Solo Hologres V2.2.32 y versiones posteriores son compatibles con `finder_group_funnel`.
Tipo de campo de `group_dimension`	Solo se admiten campos TEXT. Para agrupar por varios campos, utilice `concat_ws` o `concat`.
Restricciones de ventana de día calendario	Cuando `is_relative_window=true`, `window` debe ser un múltiplo entero de 86,400,000 y `step_interval` debe ser `86400`.
Esquema de la extensión	La extensión `flow_analysis` se carga únicamente en el esquema `public` y no puede cargarse en otros esquemas.