docs(windowFunnel):The new description of windowFunnel function was edited.

2024-09-20 16:50:48 +00:00 · 2019-12-25 23:55:07 +03:00 · 2019-12-25 23:55:07 +03:00 · d5a597d4fc
commit d5a597d4fc
parent 3ccd33eeb8
2 changed files with 109 additions and 45 deletions
--- a/docs/en/query_language/agg_functions/parametric_functions.md
+++ b/docs/en/query_language/agg_functions/parametric_functions.md
@ -219,43 +219,70 @@ SELECT sequenceCount('(?1).*(?2)')(time, number = 1, number = 2) FROM t
 - [sequenceMatch](#function-sequencematch)


-## windowFunnel(window, [mode])(timestamp, cond1, cond2, cond3, ...)
+## windowFunnel {#windowfunnel}

 Searches for event chains in a sliding time window and calculates the maximum number of events that occurred from the chain.

-```
-windowFunnel(window, [mode])(timestamp, cond1, cond2, cond3, ...)
-```
-
-**Parameters:**
-
- `window` — Length of the sliding window in seconds.
- `mode` - It is an optional argument.
-  * `'strict'` - When the `'strict'` is set, the windowFunnel() applies conditions only for the unique values.
- `timestamp` — Name of the column containing the timestamp. Data types supported: `Date`, `DateTime`, and other unsigned integer types (note that even though timestamp supports the `UInt64` type, it's value can't exceed the Int64 maximum, which is 2^63 - 1).
- `cond1`, `cond2`... — Conditions or data describing the chain of events. Data type: `UInt8`. Values can be 0 or 1.
-
-**Algorithm**
+The function works according to the algorithm:

 - The function searches for data that triggers the first condition in the chain and sets the event counter to 1. This is the moment when the sliding window starts.
+
 - If events from the chain occur sequentially within the window, the counter is incremented. If the sequence of events is disrupted, the counter isn't incremented.
+
 - If the data has multiple event chains at varying points of completion, the function will only output the size of the longest chain.

+**Syntax** 
+
+```sql
+windowFunnel(window, [mode])(timestamp, cond1, cond2, ..., condN)
+```
+
+**Parameters**
+
+- `window` — Length of the sliding window in seconds.[UInt](../../data_types/int_uint.md).
+- `mode` - It is an optional argument. 
+  - `'strict'` - When the `'strict'` is set, the windowFunnel() applies conditions only for the unique values.
+- `timestamp` — Name of the column containing the timestamp. Data types supported: [Date](../../data_types/date.md), [DateTime](../../data_types/datetime.md#data_type-datetime)  and other unsigned integer types (note that even though timestamp supports the `UInt64` type, it's value can't exceed the Int64 maximum, which is 2^63 - 1).
+- `cond` — Conditions or data describing the chain of events. [UInt8](../../data_types/int_uint.md).
+
 **Returned value**

- Integer. The maximum number of consecutive triggered conditions from the chain within the sliding time window. All the chains in the selection are analyzed.
+The maximum number of consecutive triggered conditions from the chain within the sliding time window.
+All the chains in the selection are analyzed.
+
+Type: `Integer`.

 **Example**

-Determine if one hour is enough for the user to select a phone and purchase it in the online store.
+Determine if a set period of time is enough for the user to select a phone and purchase it twice in the online store.

 Set the following chain of events:

-1. The user logged in to their account on the store (`eventID=1001`).
-2. The user searches for a phone (`eventID = 1003, product = 'phone'`).
+1. The user logged in to their account on the store (`eventID = 1003`).
+2. The user searches for a phone (`eventID = 1007, product = 'phone'`).
 3. The user placed an order (`eventID = 1009`).
+4. The user made the order again (`eventID = 1010`).

-To find out how far the user `user_id` could get through the chain in an hour in January of 2017, make the query:
+Input table:
+
+```text
+┌─event_date─┬─user_id─┬───────────timestamp─┬─eventID─┬─product─┐
+│ 2019-01-28 │       1 │ 2019-01-29 10:00:00 │    1003 │ phone   │
+└────────────┴─────────┴─────────────────────┴─────────┴─────────┘
+┌─event_date─┬─user_id─┬───────────timestamp─┬─eventID─┬─product─┐
+│ 2019-01-31 │       1 │ 2019-01-31 09:00:00 │    1007 │ phone   │
+└────────────┴─────────┴─────────────────────┴─────────┴─────────┘
+┌─event_date─┬─user_id─┬───────────timestamp─┬─eventID─┬─product─┐
+│ 2019-01-30 │       1 │ 2019-01-30 08:00:00 │    1009 │ phone   │
+└────────────┴─────────┴─────────────────────┴─────────┴─────────┘
+┌─event_date─┬─user_id─┬───────────timestamp─┬─eventID─┬─product─┐
+│ 2019-02-01 │       1 │ 2019-02-01 08:00:00 │    1010 │ phone   │
+└────────────┴─────────┴─────────────────────┴─────────┴─────────┘
+```
+
+Find out how far the user `user_id` could get through the chain in a period in January-February of 2019.
+
+Query:

 ```sql
 SELECT
@ -265,16 +292,22 @@ FROM
 (
    SELECT
        user_id,
-        windowFunnel(3600)(timestamp, eventID = 1001, eventID = 1003 AND product = 'phone', eventID = 1009) AS level
-    FROM trend_event
-    WHERE (event_date >= '2017-01-01') AND (event_date <= '2017-01-31')
+        windowFunnel(6048000000000000)(timestamp, eventID = 1003, eventID = 1009, eventID = 1007, eventID = 1010) AS level
+    FROM trend
+    WHERE (event_date >= '2019-01-01') AND (event_date <= '2019-02-02')
    GROUP BY user_id
 )
 GROUP BY level
-ORDER BY level
+ORDER BY level ASC
 ```

-Simply, the level value could only be 0, 1, 2, 3, it means the maxium event action stage that one user could reach.
+Result:
+
+```text
+┌─level─┬─c─┐
+│     4 │ 1 │
+└───────┴───┘
+```

 ## retention(cond1, cond2, ...)

--- a/docs/ru/query_language/agg_functions/parametric_functions.md
+++ b/docs/ru/query_language/agg_functions/parametric_functions.md
@ -214,42 +214,68 @@ SELECT sequenceCount('(?1).*(?2)')(time, number = 1, number = 2) FROM t

 - [sequenceMatch](#function-sequencematch)

-## windowFunnel(window)(timestamp, cond1, cond2, cond3, ...)
+## windowFunnel {#windowfunnel}

 Отыскивает цепочки событий в скользящем окне по времени и вычисляет максимальное количество произошедших событий из цепочки.

+Функция работает по алгоритму:
+
+- Функция отыскивает данные, на которых срабатывает первое условие из цепочки, и присваивает счетчику событий значение 1. С этого же момента начинается отсчет времени скользящего окна.
+
+- Если в пределах окна последовательно попадаются события из цепочки, то счетчик увеличивается. Если последовательность событий нарушается, то счетчик не растет.
+
+- Если в данных оказалось несколько цепочек разной степени завершенности, то функция выдаст только размер самой длинной цепочки.
+
+**Синтаксис**

 ```sql
-windowFunnel(window)(timestamp, cond1, cond2, cond3, ...)
+windowFunnel(window, [mode])(timestamp, cond1, cond2, ..., condN)
 ```

 **Параметры**

- `window` — ширина скользящего окна по времени в секундах.
- `timestamp` — имя столбца, содержащего отметки времени. Тип данных [Date](../../data_types/date.md), [DateTime](../../data_types/datetime.md#data_type-datetime) или [UInt*](../../data_types/int_uint.md). Заметьте, что в случает хранения меток времени в столбцах с типом `UInt64`, максимально допустимое значение соответствует ограничению для типа `Int64`, т.е. равно `2^63-1`.
- `cond1`, `cond2`... — условия или данные, описывающие цепочку событий. Тип данных — `UInt8`. Значения могут быть 0 или 1.
-
-**Алгоритм**
-
- Функция отыскивает данные, на которых срабатывает первое условие из цепочки, и присваивает счетчику событий значение 1. С этого же момента начинается отсчет времени скользящего окна.
- Если в пределах окна последовательно попадаются события из цепочки, то счетчик увеличивается. Если последовательность событий нарушается, то счетчик не растёт.
- Если в данных оказалось несколько цепочек разной степени завершенности, то функция выдаст только размер самой длинной цепочки.
+- `window` — ширина скользящего окна по времени в секундах. [UInt](../../data_types/int_uint.md).
+- `mode` - необязательный параметр. Если установлено значение `'strict'`, то функция `windowFunnel()` применяет условия только для уникальных значений.
+- `timestamp` — имя столбца, содержащего временные отметки. [Date](../../data_types/date.md), [DateTime](../../data_types/datetime.md#data_type-datetime)  и другие параметры с типом `Integer`. В случае хранения меток времени в столбцах с типом `UInt64`, максимально допустимое значение соответствует ограничению для типа `Int64`, т.е. равно `2^63-1`.
+- `cond` — условия или данные, описывающие цепочку событий. [UInt8](../../data_types/int_uint.md). 

 **Возвращаемое значение**

- Целое число. Максимальное количество последовательно сработавших условий из цепочки в пределах скользящего окна по времени. Исследуются все цепочки в выборке.
+Максимальное количество последовательно сработавших условий из цепочки в пределах скользящего окна по времени. Исследуются все цепочки в выборке.
+
+Тип: `Integer`.

 **Пример**

-Определим, успевает ли пользователь за час выбрать телефон в интернет-магазине и купить его.
+Определим, успевает ли пользователь за установленный период выбрать телефон в интернет-магазине, купить его и сделать повторный заказ.

 Зададим следующую цепочку событий:

-1. Пользователь вошел в личный кабинет магазина (`eventID=1001`).
+1. Пользователь вошел в личный кабинет (`eventID = 1001`).
 2. Пользователь ищет телефон (`eventID = 1003, product = 'phone'`).
-3. Пользователь сделал заказ (`eventID = 1009`).
+3. Пользователь сделал заказ (`eventID = 1009`)
+4. Пользователь сделал повторный заказ (`eventID = 1010`).

-Чтобы узнать, как далеко пользователь `user_id` смог пройти по цепочке за час в январе 2017-го года, составим запрос:
+Входная таблица:
+
+```text
+┌─event_date─┬─user_id─┬───────────timestamp─┬─eventID─┬─product─┐
+│ 2019-01-28 │       1 │ 2019-01-29 10:00:00 │    1003 │ phone   │
+└────────────┴─────────┴─────────────────────┴─────────┴─────────┘
+┌─event_date─┬─user_id─┬───────────timestamp─┬─eventID─┬─product─┐
+│ 2019-01-31 │       1 │ 2019-01-31 09:00:00 │    1007 │ phone   │
+└────────────┴─────────┴─────────────────────┴─────────┴─────────┘
+┌─event_date─┬─user_id─┬───────────timestamp─┬─eventID─┬─product─┐
+│ 2019-01-30 │       1 │ 2019-01-30 08:00:00 │    1009 │ phone   │
+└────────────┴─────────┴─────────────────────┴─────────┴─────────┘
+┌─event_date─┬─user_id─┬───────────timestamp─┬─eventID─┬─product─┐
+│ 2019-02-01 │       1 │ 2019-02-01 08:00:00 │    1010 │ phone   │
+└────────────┴─────────┴─────────────────────┴─────────┴─────────┘
+```
+
+Сделаем запрос и узнаем, как далеко пользователь `user_id` смог пройти по цепочке за период в январе-феврале 2019-го года.
+
+Запрос:

 ```sql
 SELECT
@ -259,17 +285,22 @@ FROM
 (
    SELECT
        user_id,
-        windowFunnel(3600)(timestamp, eventID = 1001, eventID = 1003 AND product = 'phone', eventID = 1009) AS level
-    FROM trend_event
-    WHERE (event_date >= '2017-01-01') AND (event_date <= '2017-01-31')
+        windowFunnel(6048000000000000)(timestamp, eventID = 1003, eventID = 1009, eventID = 1007, eventID = 1010) AS level
+    FROM trend
+    WHERE (event_date >= '2019-01-01') AND (event_date <= '2019-02-02')
    GROUP BY user_id
 )
 GROUP BY level
-ORDER BY level
+ORDER BY level ASC
 ```

-В результате мы можем получить 0, 1, 2 или 3 в зависимости от действий пользователя.
+Ответ:

+```text
+┌─level─┬─c─┐
+│     4 │ 1 │
+└───────┴───┘
+```

 ## uniqUpTo(N)(x)