From e0b3337704d5a2f0cdc01d21cc3f6ef3521f6112 Mon Sep 17 00:00:00 2001 From: qiaominna Date: Mon, 29 Mar 2021 14:25:33 +0800 Subject: [PATCH] update zh docs update zh docs update zh docs --- hetu-docs/zh/admin/properties.md | 50 ++++++++++++++-- hetu-docs/zh/admin/reliable-execution.md | 63 ++++++++++++++++++++ hetu-docs/zh/develop/star-tree-cube.md | 70 +++++++++++++++++++++++ hetu-docs/zh/index.md | 4 +- hetu-docs/zh/sql/create-cube.md | 51 +++++++++++++++++ hetu-docs/zh/sql/drop-cube.md | 27 +++++++++ hetu-docs/zh/sql/insert-cube.md | 55 ++++++++++++++++++ hetu-docs/zh/sql/insert-overwrite-cube.md | 22 +++++++ hetu-docs/zh/sql/show-cubes.md | 29 ++++++++++ 9 files changed, 363 insertions(+), 8 deletions(-) create mode 100644 hetu-docs/zh/admin/reliable-execution.md create mode 100644 hetu-docs/zh/develop/star-tree-cube.md create mode 100644 hetu-docs/zh/sql/create-cube.md create mode 100644 hetu-docs/zh/sql/drop-cube.md create mode 100644 hetu-docs/zh/sql/insert-cube.md create mode 100644 hetu-docs/zh/sql/insert-overwrite-cube.md create mode 100644 hetu-docs/zh/sql/show-cubes.md diff --git a/hetu-docs/zh/admin/properties.md b/hetu-docs/zh/admin/properties.md index f18644181..552ad2128 100644 --- a/hetu-docs/zh/admin/properties.md +++ b/hetu-docs/zh/admin/properties.md @@ -543,12 +543,13 @@ ### `hetu.heuristicindex.indexstore.filesystem.profile` -> - **类型** `string` -> -> 此属性定义用于存储索引文件的文件系统属性描述文件名称，该名称对应的属性文件应该存在于`etc/filesystem/`中。 +> - 类型 `string` > -> - `LOCAL` 本地文件系统只应该被用于本地测试，或单节点部署情形。（否则索引文件将无法在机器之间共享） -> - `HDFS` 应用于生产环境来在集群中共享数据。 +> 此属性定义用于读取和写入索引的文件系统配置文件。对应的配置文件必须存在于`etc/filesystem`中。例如，如果将该属性设置为`hetu.heuristicindex.filter.indexstore.filesystem.profile=index-hdfs1`，则必须在`etc/filesystem`中创建描述该文件系统访问的配置文件`index-hdfs1.properties`，其中包含的必要信息包括身份验证类型、配置和密钥表（如适用）。 +> +> `LOCAL`文件系统类型仅应在测试期间或单节点群集中使用。 +> +> 应在生产中使用`HDFS`文件系统类型，以便集群中的所有节点都能访问索引。所有节点都应配置为使用相同的文件系统配置文件。 ## 执行计划缓存属性 @@ -640,4 +641,41 @@ > > 处理队列已满时，预取队列可以容纳的最大页数。预取队列用于急切读取数据，从而无需等待I/O执行查询。也可以使用 cte_max_prefetch_queue_size会话属性对每个查询指定。 > -> **说明：** 应在所有工作节点上配置该属性。 \ No newline at end of file +> **说明：** 应在所有工作节点上配置该属性。 + +## 分布式快照 + +### `snapshot_enabled` + +> - 类型：`boolean` +> - **默认值**：`false` +> +> 此会话属性用于启用或禁用分布式快照功能。 + +### `hetu.experimental.snapshot.profile` + +> - 类型：`string` +> +> 此属性定义用于存储快照的文件系统配置文件。对应的配置文件必须存在于`etc/filesystem`中。例如，如果将该属性设置为`hetu.experimental.snapshot.profile=snapshot-hdfs1`，则必须在`etc/filesystem`中创建描述此文件系统的配置文件`snapshot-hdfs1.properties`，其中包含的必要信息包括身份验证类型、配置和密钥表（如适用）。 +> +> 如在打开分布式快照的情况下执行任何查询时，需要配本属性。此属性必须包含在所有协调节点和工作节点的配置文件中。指定的文件系统必须可由所有工作节点访问，且这些工作节点必须能够读取和写入指定文件系统中的`/tmp/hetu/snapshot`文件夹。 +> +> 作为实验性属性，或可以将快照存储在非文件系统位置，如连接器。 + +### `hetu.snapshot.maxRetries` + +> - 类型：`int` +> - **默认值**：`10` +> +> 此属性定义查询的错误恢复尝试的最大次数。达到限制时，查询失败。 +> +> 也可以使用`snapshot_max_retries`会话属性在每个查询基础上指定。 + +### `hetu.snapshot.retryTimeout` + +> - 类型：`duration` +> - **默认值：**`10m`（10分钟） +> +> 此属性定义系统等待所有任务成功恢复的最大时长。如果在此超时时限内任何任务未就绪，则认为恢复失败，查询将尝试从较早快照恢复（如果可用）。 +> +> 也可以使用`snapshot_retry_timeout`会话属性在每个查询基础上指定。 \ No newline at end of file diff --git a/hetu-docs/zh/admin/reliable-execution.md b/hetu-docs/zh/admin/reliable-execution.md new file mode 100644 index 000000000..4e19ab567 --- /dev/null +++ b/hetu-docs/zh/admin/reliable-execution.md @@ -0,0 +1,63 @@ +# 可靠查询执行 + +## 概述 + +当集群中的节点因网络、硬件或软件问题发生故障时，在故障节点上运行任务的所有查询都将丢失。这可能会严重影响集群生产力并造成资源浪费，尤其对于长时间运行的查询。 + +解决这一问题的一种方法是自动重新运行受影响的查询。这减少了人工干预的需要，并提高了容错性，但同时会延长总执行时间。 + +为了保持执行可靠性同时实现更好的性能，openLooKeng中的分布式快照机制定期保存查询执行的完整状态的快照。发生错误时，查询可以从上一个成功的快照恢复执行。该实现基于标准[Chandy-Lamport算法](https://en.wikipedia.org/wiki/Chandy%E2%80%93Lamport_algorithm)。 + +自版本1.2.0起，openLooKeng支持恢复任务和工作节点故障。 + +## 启用分布式快照 + +分布式快照适用于长时间运行的查询任务。该功能默认为禁用状态，可以通过会话属性[`snapshot_enabled`](properties.md#snapshot_enabled)启用或禁用。建议仅在对可靠性要求高的复杂查询场景下启用该功能。 + +## 要求 + +要从之前保存的快照恢复执行，必须有足够数量的可用工作节点，以便恢复所有任务。要对查询启用分布式快照，有以下要求： + +- 至少2个工作节点 +- 至少之前80%的可用节点仍处于活动状态，以便恢复成功。如果没有足够的工作节点可用，则查询将从头重新运行。 + +## 限制 + +- **支持的语句**：仅支持`INSERT`和`CREATE TABLE AS SELECT`类型的语句 + - 不包括类似`INSERT INTO CUBE`的语句。 +- **源表**：只能从`Hive`、`TPCDS`和`TPCH`目录中的表读取。 +- **目标表**：只能写入`Hive`目录中的表，格式为`ORC`。 +- **与其他功能的交互**：分布式快照目前无法与以下功能一起使用： + - 重用交换，即`optimizer.reuse-table-scan` + - 重用公用表表达式（CTE），即`optimizer.cte-reuse-enabled` + - 溢出，即`experimental.spill-enabled` + +在启用分布式快照的情况下提交不满足上述要求的查询时，查询按未启用分布式快照功能的场景执行。 + +## 检测 + +协调节点与远程任务之间的通信长时间失败时，将触发错误恢复，由`query.remote-task.max-error-duration`配置控制。 + +另一个相关配置为`exchange.max-error-duration`，其影响任务间通信错误。建议将此属性配置为大于`query.remote-task.max-error-duration`的时长，以提高工作节点故障恢复的可能性。 + +## 存储注意事项 + +从保存的快照恢复查询执行时，任务可能会在与保存快照时不同的工作节点上调度。这意味着所有工作节点都必须能够访问保存的快照数据。 + +快照数据存储在使用`hetu.experimental.snapshot.profile`属性指定的文件系统中。 + +快照文件存储在文件系统的`/tmp/hetu/snapshot/`文件夹下。必须授权所有工作节点读取和写入此文件夹。 + +快照反映查询执行中的状态，可能会变得非常大，并且因查询而异。例如，需要缓冲大量数据的查询（通常涉及排序、窗口、连接、聚合等操作）可能会产生包含整个表数据的快照。执行前请确保共享文件系统有足够的可用空间来保存这些快照。 + +每次查询执行都可能生成多个快照。快照的内容可能会重叠。目前，快照以单独文件的形式存储。未来可能会引入“增量快照”功能，以节省存储空间。 + +## 性能开销 + +从错误和快照中恢复需要成本。捕获快照需要时间，时间长短取决于复杂性。因此，需要在性能和可靠性之间进行权衡。 + +建议仅在必要时启用分布式快照，如运行时间较长的查询任务。对于这些类型的工作负载，捕获快照的开销可以忽略不计。 + +## 配置 + +与分布式快照功能相关的配置可参见[属性参考](properties.md#distributed-snapshot)。 \ No newline at end of file diff --git a/hetu-docs/zh/develop/star-tree-cube.md b/hetu-docs/zh/develop/star-tree-cube.md new file mode 100644 index 000000000..1eb8083f1 --- /dev/null +++ b/hetu-docs/zh/develop/star-tree-cube.md @@ -0,0 +1,70 @@ +# Star-Tree + +Star-tree多维数据集是一种预聚合技术，用于实现低延迟冰山查询。冰山查询用于计算属性（或属性集）的聚合函数，以便查找高于指定阈值的聚合值。通过该技术，用户能够创建具有必要聚合和维度的多维数据集。然后，当执行聚合查询时，多维数据集用于执行查询而非原始表。实际性能提升是在TableScan操作期间实现的，因为多维数据集是预计算和预聚合的。 + +因此，当group by基数产生的行少于原始表时，多维数据集技术非常有效。 + +## 支持功能 + + COUNT, COUNT DISTINCT, MIN, MAX, SUM, AVG + +## 启用和禁用star-tree + +启用star-tree： + +```sql +SET SESSION enable_star_tree_index=true; +``` + +禁用star-tree： + +```sql +SET SESSION enable_star_tree_index=false; +``` + +## 配置属性 + +| 属性名称| 默认值| 是否必填| 说明| +|----------|----------|----------|----------| +| optimizer.enable-star-tree-index| false| 否| 启用star-tree索引| +| cube.metadata-cache-size| 5| 否| 在缓存清空前可以加载到缓存中的star-tree元数据的最大数量| +| cube.metadata-cache-ttl| 1h| 否| 在缓存清空前加载到缓存中的star-tree的最长保留时间| + +## 示例 + +创建star-tree多维数据集： + +```sql +CREATE CUBE nation_cube +ON nation +WITH (AGGREGATIONS=(count(*), count(distinct regionkey), avg(nationkey), max(regionkey)), +GROUP=(nationkey), +format='orc', partitioned_by=ARRAY['nationkey']); +``` + +向多维数据集添加数据： + +```sql +INSERT INTO CUBE nation_cube WHERE nationkey > 5; +``` + +要使用新多维数据集，只需使用多维数据集中包含的聚合来查询原始表： + +```sql +SELECT count(*) FROM nation WHERE nationkey > 5 GROUP BY nationkey; +SELECT nationkey, avg(nationkey), max(regionkey) WHERE nationkey > 5 GROUP BY nationkey; +``` + +## 优化器变更 + +Star-tree聚合规则为迭代优化器，通过将原始聚合子树和原始表扫描替换为预聚合表扫描来优化逻辑计划。 + +## 依赖 + +Star-tree索引依赖于Hetu元存储来存储多维数据集相关的元数据。有关更多信息，请查看[Hetu元存储](../admin/meta-store.md)。 + +## 限制 + +1. Star-tree多维数据集仅在group by基数远低于源表中的行数时有效。 +2. 维护大型数据集的多维数据集需要大量的用户人力。 +3. 仅支持增量插入多维数据集。无法从多维数据集删除特定行。 \ No newline at end of file diff --git a/hetu-docs/zh/index.md b/hetu-docs/zh/index.md index c01e94cd6..d11378314 100644 --- a/hetu-docs/zh/index.md +++ b/hetu-docs/zh/index.md @@ -44,7 +44,7 @@ headless: true - [状态存储]({{< relref "./docs/admin/state-store.md" >}}) - [元数据存储]({{< relref "./docs/admin/meta-store.md" >}}) - [审计日志]({{< relref "./docs/admin/audit-log.md" >}}) - + - [可靠查询执行]({{< relref "./docs/admin/reliable-execution.md" >}}) - [查询优化器]("#") - [表统计]({{< relref "./docs/optimizer/statistics.md" >}}) - [EXPLAIN成本]({{< relref "./docs/optimizer/cost-in-explain.md" >}}) @@ -198,7 +198,7 @@ headless: true - [启发式索引]({{< relref "./docs/develop/indexer.md" >}}) - [Hive ORC Cache]({{< relref "./docs/develop/hive-orc-cache.md" >}}) - [外部函数注册和下推]({{< relref "./docs/develop/externalfunction-registration-pushdown.md" >}}) - + - [Star-tree多维数据集]({{< relref "./docs/develop/star-tree-cube.md" >}}) - [openLooKeng REST接口说明]({{< relref "./docs/rest/_index.md" >}}) - [节点资源]({{< relref "./docs/rest/node.md" >}}) - [查询资源]({{< relref "./docs/rest/query.md" >}}) diff --git a/hetu-docs/zh/sql/create-cube.md b/hetu-docs/zh/sql/create-cube.md new file mode 100644 index 000000000..65d9ed37c --- /dev/null +++ b/hetu-docs/zh/sql/create-cube.md @@ -0,0 +1,51 @@ +# CREATE CUBE + +## 使用方式 + +```sql +CREATE CUBE [ IF NOT EXISTS ] +cube_name ON table_name WITH ( + AGGREGATIONS = ( expression [, ...] ), GROUP = ( column_name [, ...] ) + [, ( property_name = expression [, ...] ) ] +) +``` + +## 介绍 + +使用指定的组和聚合创建新的star-tree多维数据集。使用`insert-into-cube`插入数据。 + +如果表已存在，可选的`IF NOT EXISTS`子句将导致错误被隐藏。 + +可以使用可选的`property_name`标签来设置创建的多维数据集的属性。要列出所有可用的表属性，请运行以下查询： + + SELECT * FROM system.metadata.table_properties + +## 示例 + +在`orders`上创建新多维数据集`orders_cube`： + + CREATE CUBE orders_cube ON orders WITH ( + AGGREGATIONS = ( SUM(totalprice), AVG(totalprice) ), + GROUP = ( orderstatus, orderdate ), + format = 'ORC' + ) + +创建新的分区多维数据集`orders_cube`： + + CREATE CUBE orders_cube ON orders WITH ( + AGGREGATIONS = ( SUM(totalprice), AVG(totalprice) ), + GROUP = ( orderstatus, orderdate ), + format = 'ORC', + partitioned_by = ARRAY['orderdate'] + ) + +## 限制 + +- 支持的聚合函数：COUNT、COUNT DISTINCT、MIN、MAX、SUM、AVG +- 每个多维数据集仅支持一个组。 +- 不同的连接器可能支持不同的数据类型和不同的表/列属性。 +- 当前只能在Hive连接器中创建多维数据集，但可以从另一个连接器在表中创建多维数据集。 + +## 另请参见 + +[INSERT INTO CUBE](./insert-cube.md)、[SHOW CUBES](./show-cubes.md)、[DROP CUBE](./drop-cube.md) \ No newline at end of file diff --git a/hetu-docs/zh/sql/drop-cube.md b/hetu-docs/zh/sql/drop-cube.md new file mode 100644 index 000000000..af8d76544 --- /dev/null +++ b/hetu-docs/zh/sql/drop-cube.md @@ -0,0 +1,27 @@ +# DROP CUBE + +## 使用方式 + +```sql +DROP CUBE [ IF EXISTS ] cube_name +``` + +## 说明 + +删除已存在的多维数据集。 + +如果多维数据集不存在，可选子句`IF EXISTS`将导致错误被隐藏。 + +## 示例 + +删除多维数据集`orders_cube`： + + DROP CUBE orders_cube + +如果多维数据集`orders_cube`存在，则将其删除： + + DROP CUBE IF EXISTS orders_cube + +## 另请参见 + +[CREATE CUBE](./create-cube.md)、[SHOW CUBES](./show-cubes.md)、[INSERT INTO CUBE](./insert-cube.md) \ No newline at end of file diff --git a/hetu-docs/zh/sql/insert-cube.md b/hetu-docs/zh/sql/insert-cube.md new file mode 100644 index 000000000..e6c23d134 --- /dev/null +++ b/hetu-docs/zh/sql/insert-cube.md @@ -0,0 +1,55 @@ +# INSERT INTO CUBE + +## 使用方式 + +```sql +INSERT INTO CUBE cube_name [WHERE condition] +``` + +## 介绍 + +将数据插入star-tree多维数据集。谓词信息为可选项。如果提供了谓词，则仅从源表处理与给定谓词匹配的数据并将其插入多维数据集。否则，将处理源表中的全部数据并将其插入多维数据集。 + +## 示例 + +根据条件将数据插入`orders_cube`多维数据集中： + + INSERT INTO CUBE orders_cube WHERE orderdate > date '1999-01-01'; + INSERT INTO CUBE order_all_cube; + +## 另请参见 + +[INSERT OVERWRITE CUBE](./insert-overwrite-cube.md)、[CREATE CUBE](./create-cube.md)、[SHOW CUBES](./show-cubes.md)、[DROP CUBE](./drop-cube.md) + +## 限制 + +1. 如果在where子句谓词中使用两个不同的列，则insert语句将无法正常运行。 + +```sql + CREATE CUBE orders_cube ON orders WITH (AGGREGATIONS = (count(*)), GROUP = (orderdate)); + + INSERT INTO CUBE orders_cube WHERE orderdate BETWEEN date '1999-01-01' AND date '1999-01-05'; + + -- This statement would fail because its possible the Cube already contain rows matching the given predicate. + INSERT INTO CUBE orders_cube WHERE location = 'Canada'; +``` + +2. 范围谓词问题。 + +```sql + CREATE CUBE orders_cube ON orders WITH (AGGREGATIONS = (count(*)), GROUP = (orderdate)); + + INSERT INTO CUBE orders_cube WHERE orderdate BETWEEN date '1999-01-01' AND date '1999-01-05'; + INSERT INTO CUBE orders_cube WHERE orderdate BETWEEN date '1999-01-06' AND date '1999-01-10'; + + SET SESSION enable_star_tree_index=true; + + -- This statement uses orders_cube -- + SELECT count(*) FROM orders WHERE orderdate BETWEEN date '1999-01-03' AND date '1999-01-04'; + -- This statement uses orders_cube -- + SELECT count(*) FROM orders WHERE orderdate BETWEEN date '1999-01-07' AND date '1999-01-09'; + -- This statement does not user orders_cube because the two predicates used in the INSERT statement cannot be merged + -- and the TupleDomain evaluation to check cubePredicate.contains(statementPredicate) evaluates to false + + SELECT count(*) FROM orders WHERE orderdate BETWEEN date '1999-01-04' AND date '1999-01-07'; +``` \ No newline at end of file diff --git a/hetu-docs/zh/sql/insert-overwrite-cube.md b/hetu-docs/zh/sql/insert-overwrite-cube.md new file mode 100644 index 000000000..f3f60d1a2 --- /dev/null +++ b/hetu-docs/zh/sql/insert-overwrite-cube.md @@ -0,0 +1,22 @@ +# INSERT INTO CUBE + +## 使用方式 + +```sql +INSERT OVERWRITE CUBE cube_name [WHERE condition] +``` + +## 介绍 + +类似于INSERT INTO CUBE语句，但使用此语句将覆盖现有数据。谓词为可选项。 + +## 示例 + +根据条件将数据插入`orders_cube`多维数据集中： + + INSERT OVERWRITE CUBE orders_cube WHERE orderdate > date '1999-01-01'; + INSERT OVERWRITE CUBE orders_cube; + +## 另请参见 + +[INSERT INTO CUBE](./insert-cube.md)、[CREATE CUBE](./create-cube.md)、[SHOW CUBES](./show-cubes.md)、[DROP CUBE](./drop-cube.md) \ No newline at end of file diff --git a/hetu-docs/zh/sql/show-cubes.md b/hetu-docs/zh/sql/show-cubes.md new file mode 100644 index 000000000..f229186dc --- /dev/null +++ b/hetu-docs/zh/sql/show-cubes.md @@ -0,0 +1,29 @@ +# SHOW CUBES + +## 使用方式 + +```sql +SHOW CUBES [ FOR table_name ]; +``` + +## 说明 + +`SHOW CUBES`列举所有多维数据集。添加选项`table_name`仅列出该表的多维数据集。 + +## 示例 + +显示所有多维数据集： + +```sql + SHOW CUBES; +``` + +显示`orders`表的多维数据集： + +```sql + SHOW CUBES FOR orders; +``` + +## 另请参见 + +[CREATE CUBE](./create-cube.md)、[DROP CUBE](./drop-cube.md)、[INSERT INTO CUBE](./insert-cube.md) \ No newline at end of file