copilot 机翻文档

GreptimeTeam · Sep 5, 2024 · 8af2067 · 8af2067
1 parent a542db8
commit 8af2067
Show file tree

Hide file tree

Showing 3 changed files with 130 additions and 93 deletions.
diff --git a/...aurus-plugin-content-docs/current/user-guide/continuous-aggregation/overview.md b/...aurus-plugin-content-docs/current/user-guide/continuous-aggregation/overview.md
@@ -67,7 +67,7 @@ SELECT
     min(size) as min_size,
     max(size) as max_size,
     avg(size) as avg_size,
-    sum(case when `size` > 550::double then 1::double else 0::double end) as high_size_count,
+    sum(case when `size` > 550 then 1 else 0 end) as high_size_count,
     date_bin(INTERVAL '1 minutes', access_time) as time_window,
 FROM ngx_access_log
 GROUP BY
@@ -141,6 +141,8 @@ SELECT * FROM ngx_statistics;
 恭喜你已经初步了解了持续聚合功能。
 请参考以下章节了解更多：
 
+
+- [用例](./usecase-example.md) 提供了更多关于如何在实时分析、监控和仪表板中使用持续聚合的示例。
 - [管理 Flow](./manage-flow.md) 描述了如何创建、更新和删除 flow。你的每个持续聚合查询都是一个 flow。
 - [编写查询语句](./query.md) 描述了如何编写持续聚合查询。
 - [定义时间窗口](./define-time-window.md) 描述了如何为持续聚合定义时间窗口。时间窗口是持续聚合查询的一个重要属性，它定义了聚合的时间间隔。

diff --git a/...cusaurus-plugin-content-docs/current/user-guide/continuous-aggregation/query.md b/...cusaurus-plugin-content-docs/current/user-guide/continuous-aggregation/query.md
@@ -16,98 +16,12 @@ SELECT AGGR_FUNCTION(column1, column2,..) FROM <source_table> GROUP BY TIME_WIND
 
 查询应该有一个 `FROM` 子句来标识 source 表。由于不支持 join 子句，目前只能从单个表中聚合列。
 
-`GROUP BY` 子句与普通查询中的工作方式相同。
-它根据指定的列对数据进行分组。
-`GROUP BY` 子句中使用的时间窗口函数 `hop()` 和 `tumble()` 在 [定义时间窗口](./define-time-window.md) 部分中有描述。
-它们用于在聚合中定义时间窗口。
-`GROUP BY` 中的其他表达式可以是 literal、列名或 scalar 表达式。
-
-持续聚合查询不支持 `ORDER BY`、`LIMIT`、`OFFSET` 等其他操作。
-
-
-## 将现有查询重写为持续聚合查询
-
-一些简单的现有聚合查询可以直接用作持续聚合查询。例如，[概述](./overview.md) 部分中的示例可以用于标准 SQL 查询和持续聚合查询，因为它也是一个有效的 SQL 查询，没有任何特定于流的语法或函数：
-
-```sql
-SELECT
-    status,
-    count(client) AS total_logs,
-    min(size) as min_size,
-    max(size) as max_size,
-    avg(size) as avg_size,
-    sum(case when `size` > 550::double then 1::double else 0::double end) as high_size_count,
-    date_bin(INTERVAL '1 minutes', access_time) as time_window,
-FROM ngx_access_log
-GROUP BY
-    status,
-    time_window;
-```
-
-然而，还有其他类型的查询不能直接用作持续聚合查询。
-例如，需要计算百分位数的查询不应该在每次新数据到达时重复计算每个时间窗口的百分位数。
-在这种情况下，您可以将数据预聚合到所需大小的桶中，然后在需要时使用标准 SQL 在 sink 表中计算百分位数。原始 SQL 可能是：
-
-```sql
-SELECT
-    status,
-    percentile_approx(size, 0.5) as median_size,
-    date_bin(INTERVAL '1 minutes', access_time) as time_window,
-FROM ngx_access_log
-GROUP BY
-    status,
-    time_window;
-```
-上述查询可以重写为首先将数据聚合到大小为 10 的桶中，然后在 sink 表中计算百分位数。
-流查询将是：
+`WHERE` 和 `HAVING` 子句在持续聚合查询中是支持的。它们的工作方式与普通查询中的相同。`WHERE` 子句在聚合之前过滤数据，而 `HAVING` 子句在聚合之后过滤数据。
 
-```sql
-CREATE FLOW calc_ngx_distribution
-SINK TO ngx_distribution
-AS
-SELECT
-    status,
-    trunc(size, -1) as bucket,
-    count(client) AS total_logs,
-    date_bin(INTERVAL '1 minutes', access_time) as time_window,
-FROM ngx_access_log
-GROUP BY
-    status,
-    time_window,
-    bucket;
-```
-接下来，您可以使用标准 SQL 在 sink 表中计算百分位数：
-```sql
-SELECT
-    outer.status,
-    outer.time_window,
-    outer.bucket,
-    SUM(case when in1.bucket <= outer.bucket then in1.total_logs else 0 end) * 100 / SUM(in1.total_logs) AS percentile
-FROM ngx_distribution AS outer
-JOIN ngx_distribution AS in1
-ON in1.status = outer.status 
-AND in1.time_window = outer.time_window
-GROUP BY
-    status,
-    time_window,
-    bucket
-ORDER BY status, time_window, bucket;
-```
+`DISTINCT` 目前只能使用 `SELECT DISTINCT column1 ..` 语法。它用于从结果集中删除重复行。目前还不支持 `SELECT count(DISTINCT column1) ...`，但将来会添加支持。
 
-上述 SQL 查询按 status、time_window 和 bucket 对数据进行分组。percentile 列通过计算小于或等于当前 bucket 的所有 bucket 的总和，并将其除以所有日志的总数来计算每个组内的百分比。结果可能如下所示：
-
-```sql
- status |        time_window         | bucket | percentile 
---------+----------------------------+--------+------------
-    404 | 1970-01-01 00:00:00.000000 |      0 |         22
-    404 | 1970-01-01 00:00:00.000000 |      1 |         55
-    404 | 1970-01-01 00:00:00.000000 |      2 |         66
-    404 | 1970-01-01 00:00:00.000000 |      3 |        100
-(4 rows)
-```
+`GROUP BY` 子句与普通查询中的工作方式相同。它根据指定的列对数据进行分组。`GROUP BY` 子句中使用的时间窗口函数 `hop()` 和 `tumble()` 在 [定义时间窗口](./define-time-window.md) 部分中有描述。
+它们用于在聚合中定义时间窗口。
+`GROUP BY` 中的其他表达式可以是 literal、列名或 scalar 表达式。
 
-<!-- 
-TODO(discord9): add example for percentile query
-TODO(discord9): add example for tumble and hop once we support window table function
-Another example that require rewrite is for query that needs overlapping timewindow, hence `hop()` function is needed. 
--->
+持续聚合查询不支持 `ORDER BY`、`LIMIT`、`OFFSET` 等其他操作。
diff --git a/...lugin-content-docs/current/user-guide/continuous-aggregation/usecase-example.md b/...lugin-content-docs/current/user-guide/continuous-aggregation/usecase-example.md
@@ -0,0 +1,121 @@
+# 用例
+持续聚合的三个主要用例示例如下：
+
+1. **实时分析**：一个实时分析平台，不断聚合来自事件流的数据，提供即时洞察，同时可选择将数据降采样到较低分辨率。例如，此系统可以编译来自高频日志事件流（例如，每毫秒发生一次）的数据，以提供每分钟的请求数、平均响应时间和每分钟的错误率等最新洞察。
+
+2. **实时监控**：一个实时监控系统，不断聚合来自事件流的数据，根据聚合数据提供实时警报。例如，此系统可以处理来自传感器事件流的数据，以提供当温度超过某个阈值时的实时警报。
+
+3. **实时仪表盘**：一个实时仪表盘，显示每分钟的请求数、平均响应时间和每分钟的错误数。此仪表板可用于监控系统的健康状况，并检测系统中的任何异常。
+
+在所有这些用例中，持续聚合系统不断聚合来自事件流的数据，并根据聚合数据提供实时洞察和警报。系统还可以将数据降采样到较低分辨率，以减少存储和处理的数据量。这使得系统能够提供实时洞察和警报，同时保持数据存储和处理成本低廉。
+
+## 实时分析示例
+
+请参阅[概述](overview.md)中的实时分析示例。该示例用于计算日志的总数、包大小的最小、最大和平均值，以及大小大于 550 的数据包数量按照每个状态码在 1 分钟固定窗口中的实时分析。
+
+另外，您还可以使用持续聚合来计算其他类型的实时分析。例如，要从 `ngx_access_log` 表中获取所有不同的国家。持续聚合的查询如下：
+
+```sql
+-- input table
+CREATE TABLE ngx_access_log (
+    client STRING,
+    country STRING,
+    access_time TIMESTAMP TIME INDEX
+);
+-- create flow task to calculate the distinct country
+CREATE FLOW calc_ngx_country
+SINK TO ngx_country
+AS
+SELECT
+    DISTINCT country,
+FROM ngx_access_log;
+```
+
+或者，如果您想要按时间窗口对数据进行分组，可以使用以下查询：
+
+```sql
+CREATE FLOW calc_ngx_country
+SINK TO ngx_country
+AS
+SELECT
+    DISTINCT country,
+    date_bin(INTERVAL '1 hour', access_time) as time_window,
+FROM ngx_access_log
+GROUP BY
+    country,
+    time_window;
+```
+
+上述的查询将 `ngx_access_log` 表中的数据放入 `ngx_country` 表中。它计算每个时间窗口的不同国家。`date_bin` 函数用于将数据分组为一小时的间隔。`ngx_country` 表将不断更新聚合数据，提供实时洞察，显示正在访问系统的不同国家。
+
+请注意，目前没有持久存储用于 flow 的内部状态（但是表数据有持久存储），因此建议使用适当的时间窗口来最小化数据丢失，因为如果内部状态丢失，相关时间窗口数据也将丢失。
+
+## 实时监控示例
+
+考虑一个使用情况，您有一个来自温度传感器网络的传感器事件流，您希望实时监控。传感器事件包含传感器 ID、温度读数、读数的时间戳和传感器的位置等信息。您希望不断聚合这些数据，以在温度超过某个阈值时提供实时警报。那么持续聚合的查询将是：
+
+```sql
+CREATE TABLE temp_sensor_data (
+    sensor_id INT,
+    loc STRING,
+    temperature DOUBLE,
+    ts TIMESTAMP TIME INDEX
+);
+
+CREATE FLOW temp_monitoring
+SINK TO temp_alerts
+AS
+SELECT
+    sensor_id,
+    loc,
+    max(temperature) as max_temp,
+FROM temp_sensor_data
+GROUP BY
+    sensor_id,
+    loc
+HAVING max_temp > 100;
+```
+
+上述的查询将从 `temp_sensor_data` 表中不断聚合数据到 `temp_alerts` 表中。它计算每个传感器和位置的最高温度读数，并过滤出最高温度超过 100 度的数据。`temp_alerts` 表将不断更新聚合数据，并且当温度超过阈值时提供实时警报（即 `temp_alerts` 表中的新行）。
+
+## 实时仪表盘示例
+
+考虑一个使用情况，您需要一个柱状图，显示每个状态码的数据包大小分布，以监控系统的健康状况。持续聚合的查询将是：
+
+```sql
+-- create input table
+CREATE TABLE ngx_access_log (
+    client STRING,
+    stat INT,
+    size INT,
+    access_time TIMESTAMP TIME INDEX
+);
+-- create output table
+CREATE TABLE ngx_distribution (
+    stat INT,
+    bucket_size INT,
+    total_logs BIGINT,
+    time_window TIMESTAMP TIME INDEX,
+    update_at TIMESTAMP, -- auto generated column to store the last update time
+    PRIMARY KEY(stat, bucket_size)
+);
+-- create flow task to calculate the distribution of packet sizes for each status code
+CREATE FLOW calc_ngx_distribution SINK TO ngx_distribution AS
+SELECT
+    stat,
+    trunc(size, -1)::INT as bucket_size,
+    count(client) AS total_logs,
+    date_bin(INTERVAL '1 minutes', access_time) as time_window,
+FROM
+    ngx_access_log
+GROUP BY
+    stat,
+    time_window,
+    bucket_size;
+```
+
+上述查询将从 `ngx_access_log` 表中的数据放入 `ngx_distribution` 表中。它计算每个状态码的数据包大小分布，并将数据分组到每个时间窗口中。`ngx_distribution` 表将不断更新聚合数据，提供实时洞察，显示每个状态码的数据包大小分布。
+
+## 结论
+
+持续聚合是实时分析、监控和仪表盘的强大工具。它允许您不断聚合来自事件流的数据，并根据聚合数据提供实时洞察和警报。通过将数据降采样到较低分辨率，您可以减少存储和处理的数据量，从而更容易提供实时洞察和警报，同时保持数据存储和处理成本低廉。持续聚合是任何实时数据处理系统的关键组件，可以在各种用例中使用，以提供基于流数据的实时洞察和警报。