@clickzetta/cz-cli-darwin-x64 0.3.1

package/bin/skills/lakehouse-doc/references/CREATE_EXTERNATL_FUNCTION.md

@@ -0,0 +1,219 @@
+# CREATE EXTERNAL FUNCTION
+
+外部函数（EXTERNAL FUNCTION）是云器 Lakehouse 提供的强大功能，允许您通过 Python 和 Java 语言创建自定义函数（UDF），并通过远程云服务执行。这种灵活性使您能够扩展 Lakehouse 的计算能力，处理复杂的业务逻辑。支持以下云服务平台执行外部函数：
+
+* 阿里云函数计算（FC）
+* 腾讯云云函数服务
+* AWS Lambda 服务
+
+支持开发语言：
+
+* Python 3.10
+* Java 8
+
+对于以下三种不同类型的自定义函数：
+
+* UDF（用户自定义函数）：处理输入行中的一个或多个列，并为每一行返回单个结果值。
+* UDAF（用户自定义聚合函数）：对多行数据进行聚合计算，返回单个结果值。
+* UDTF（用户自定义表函数）：接收一个或多个输入参数，返回多行多列的结果集。
+
+Python 函数支持 UDF，Java 函数支持 UDF、UDAF 和 UDTF
+
+## EXTERNAL FUNCTION 创建主要流程
+
+* 用户开通云上的函数计算服务（如阿里云的函数计算FC）和对象存储服务
+
+* 将 EXTERNAL FUNCTION 执行代码、可执行文件、依赖的库、模型和数据文件，打包上传至对象存储
+
+* 授予云器 Lakehouse 操作上述服务和访问函数文件的权限
+
+* 用户执行连接和 EXTERNAL FUNCTION DDL 创建函数
+
+* 用户在云器 Lakehouse SQL 语句中使用函数
+
+* 云器 Lakehouse 根据提供的服务地址和认证信息发送 HTTP 请求调用运行函数
+
+* 云器 Lakehouse 获取响应信息返回结果
+
+## EXTERNAL FUNCTION 优势
+
+* 可以使用 EXTERNAL FUNCTION 调用外部丰富的数据处理能力，对传统 SQL 计算模型做补充。如可调用大语言模型（LLM）、图像、音视频等，补充 SQL 的非结构化数据处理能力
+* 可以直接访问外部网络，不受云器 Lakehouse 网络约束
+
+## 语法
+
+```SQL
+CREATE EXTERNAL FUNCTION [ IF NOT EXISTS ] [<database_name>.]<schema_name>.<function_name>
+  AS <class_name>
+  USING { FILE | JAR | ARCHIVE } = '<resource_uri>'[, ...]
+  CONNECTION = <api_connection_name>
+  WITH PROPERTIES ( '<property_name>' = '<property_value>'[, ...] )
+  [ COMMENT  '<comment_string>' ]
+```
+
+## 参数说明
+
+### 必选参数
+
+* `function_name`: 指定函数的名称。
+
+* `class_name`：对于 JAVA 函数，指 JAVA 函数的主类名；对于 Python 函数，为主类名和模块名的组合，例如，主程序文件为 `video_contents.py`，主类名为 `image_to_text`，AS 后的参数为 `'video_contents.image_to_text'`。
+
+* `api_connection_name`：指定连接函数计算的认证信息，具体请参考[创建连接](CREATECONNECTION.md)。
+
+* `resource_uri`：资源连接，指 EXTERNAL FUNCTION 运行所需的资源文件。需指定对应的文件地址，要求认证信息（API CONNECTION 或者内部 VOLUME）具有该文件的读取权限。您也可以指定内部 VOLUME 如 USER VOLUME 和 TABLE VOLUME 存放代码包，这样您无需再去开通云对象存储服务。虽然您可以使用内部 volume 存放函数程序包，但是您在创建 API CONNECTION 中的 code bucket 参数必须填写外部对象存储的 BUCKET 名称。
+  * **External** **Volume 格式地址**：`volume://[{workspace}.][{schema}.]{volume_name}/upper.jar`
+    * `workspace` 和 `schema` 是可选项，如果省略，将使用当前上下文默认值。
+  * **User Volume 格式地址**：`volume:user://~/upper.jar`
+    * `user` 表示使用 User Volume 协议。
+    * `~` 表示当前用户，为固定值。
+    * `upper.jar` 表示目标文件名。
+  * **Table Volume 格式地址**：`volume:table://[{workspace}.][{schema}.]{table_name}/upper.jar`
+    * `workspace` 和 `schema` 是可选项，如果省略，将使用当前上下文默认值。
+    * `table` 表示使用 Table Volume 协议。
+    * `table_name` 表示表名，需根据实际情况填写。
+    * `upper.jar` 表示目标文件名。
+
+* `WITH PROPERTIES`：指定函数的参数信息。
+  1. `remote.udf.api` - 指定运行时编译环境，支持两种选项：
+
+     * `python3.mc.v0`：当使用 Python UDF 时需要指定此选项
+     * `java8.hive2.v0`：当使用 JAVA Hive 风格 UDF 时需要指定此选项
+  2. `remote.udf.protocol` - 指定访问协议，默认值为`http.arrow.v0`，代表访问云函数的协议
+
+### 可选参数
+
+* `IF NOT EXISTS`：如果指定的函数已存在，则命令不会进行任何更改并返回一条指示函数存在的信息。如果不指定，函数存在时会直接返回错误信息。
+* `COMMENT`：指定注释信息。
+
+## 注意事项
+
+* 创建外部函数过程需要读取函数代码或可执行文件，可能需要较长时间。
+* 该命令无需启动 VC，因此不消耗 CRU。
+* 目前只支持 Java 和 Python 编程语言，支持的运行环境：Java 8 和 Python 3.10 版本
+
+# 开发指南
+
+* [创建 API CONNECTION](create-api-connection.md)
+* [Java 语言开发 External Function 指南](ExternalFunctionDevGuideJava.md)
+* [Python 语言开发 External Function指南](RemoteFunctionDevGuidePython3.md)
+
+# 使用示例
+
+## 阿里云创建 EXTERNAL FUNCTION
+
+**环境依赖**：系统已经创建 API CONNECTION，请参考 [API CONNECTION](create-api-connection.md)
+
+**步骤 1**：JAVA 语言编写 EXTERNAL FUNCTION，以下是实现大小写转换的示例代码：
+
+```java
+package com.example;
+
+import org.apache.hadoop.hive.ql.exec.UDFArgumentException;
+import org.apache.hadoop.hive.ql.metadata.HiveException;
+import org.apache.hadoop.hive.ql.udf.generic.GenericUDF;
+import org.apache.hadoop.hive.serde2.objectinspector.ObjectInspector;
+import org.apache.hadoop.hive.serde2.objectinspector.PrimitiveObjectInspector;
+import org.apache.hadoop.hive.serde2.objectinspector.PrimitiveObjectInspector.PrimitiveCategory;
+import org.apache.hadoop.hive.serde2.objectinspector.primitive.PrimitiveObjectInspectorFactory;
+
+import java.util.Locale;
+
+public class GenericUdfUpper extends GenericUDF {
+  @Override
+  public ObjectInspector initialize(ObjectInspector[] arguments) throws UDFArgumentException {
+    checkArgsSize(arguments, 1, 1);
+    checkArgPrimitive(arguments, 0);
+    if (((PrimitiveObjectInspector) arguments[0]).getPrimitiveCategory() != PrimitiveCategory.STRING) {
+      throw new UDFArgumentException("argument 0 requires to be string rather than " + arguments[0].getTypeName());
+    }
+    return PrimitiveObjectInspectorFactory.javaStringObjectInspector;
+  }
+
+  @Override
+  public Object evaluate(DeferredObject[] arguments) throws HiveException {
+    Object arg = arguments[0].get();
+    if (arg == null) {
+      return null;
+    }
+    return ((String) arg).toUpperCase(Locale.ROOT);
+  }
+
+  @Override
+  public String getDisplayString(String[] children) {
+    return "upper";
+  }
+}
+```
+
+编译代码生成 **Jar 包和其他依赖文件**，打包成 zip 压缩包
+
+**步骤 2**：上传函数程序包到指定路径
+如： `oss://hz-oss-lakehouse/functions/sentiment/UDF_code/my_upper.zip`
+函数主类：`com.clickzetta.my_upper`
+有两种方法上传文件到指定路径：
+
+* 通过 OSS 客户端直接上传
+* 在 Lakehouse JDBC 客户端（不支持 Lakehouse Web UI 使用 PUT 命令上传）通过 [PUT 命令](PUT.md) 将程序包上传至 [Volume 对象](datalake_volume.md)，并在创建函数 DDL 中引用 VOLUME 路径和上面创建的 API CONNECTION。例如：
+
+```SQL
+-- 上传文件到命名为 fc_volume 的 Volume对象：
+PUT './my_upper.zip' to volume fc_volume file '/udfs/my_upper.zip';
+
+-- 在创建函数时引用该 Volume 路径：
+create external function public.my_upper
+    AS 'com.clickzetta.my_upper' 
+    USING ARCHIVE 'volume://fc_volume/udfs/my_upper.zip' 
+    CONNECTION my_function_connection
+    WITH
+    PROPERTIES (
+        'remote.udf.api' = 'java8.hive2.v0'
+);
+```
+
+**步骤 3**：使用函数
+
+```SQL
+SELECT public.my_upper('a');
+```
+
+**说明**：
+
+如果您使用 USER VOLUME 替换**步骤 2** 中的 OSS 路径，USER VOLUME 为云器 Lakehouse 默认提供的个人文件存储空间（类似于操作系统的用户 HOME 目录）
+
+```SQL
+-- 查看 USER VOLUME
+SHOW USER VOLUME DIRECTORY;
+
+-- 上传文件至 USER VOLUME
+-- !!! 注意：
+-- 1. 需使用 Lakehouse JDBC 客户端工具执行 PUT 命令，文件路径为本地路径。
+-- 2. 必须使用包含依赖的 JAR 包
+PUT '/Users/nero/Downloads/udf/expudf-1.0-SNAPSHOT-jar-with-dependencies.jar' TO USER VOLUME;
+
+-- 删除已存在的函数定义（如有）
+DROP FUNCTION IF EXISTS public.eval_exp_internal_volume;
+
+-- 创建外部函数
+CREATE EXTERNAL FUNCTION public.eval_exp_internal_volume
+AS 'com.clickzetta.hive.udf.EvalExpUdf' 
+USING FILE 'volume:user://~/expudf-1.0-SNAPSHOT-jar-with-dependencies.jar' 
+CONNECTION udf_api_conn
+WITH PROPERTIES (
+    'remote.udf.api' = 'java8.hive2.v0'
+);
+
+-- 测试函数：返回字符串结果
+SELECT public.eval_exp_internal_volume(
+    named_struct('a', 1d, 'b', 4.3d, 'c', 3d), 
+    '(a+b)/c'
+).string_result;
+
+-- 测试函数：返回浮点数结果
+SELECT public.eval_exp_internal_volume(
+    named_struct('a', 1d, 'b', 4.3d, 'c', 3d), 
+    '(a+b)/c'
+).double_result;
+```
+
+^

package/bin/skills/lakehouse-doc/references/CTERevenueCohort.md

@@ -0,0 +1,275 @@
+# 用CTE方式对客户进行同类群组分析
+
+## CTE
+
+[CTE(Common Table Expression) ](WITH.md)，公用表表达式，它是在单个语句的执行范围内定义的临时结果集，只在查询期间有效。它可以自引用，也可在同一查询中多次引用，实现了代码段的重复利用。
+
+## 同类群组（Revenue Cohort）
+
+同类群组（Revenue Cohort）分析是对几个不同同类群组（即客户群）的分析，以更好地了解行为、模式和趋势。
+最常见的同类群组分析类型之一着眼于基于时间的同类群组，这些群组按特定时间范围对用户/客户进行分组。例如，一家公司可能希望了解其在 1 月份开始使用该产品或开始付款的客户与 2 月份的客户相比如何。
+基于细分的群组代表使用或购买特定产品或服务的客户群。例如，您可以根据用户每周登录您的应用的时间来细分用户。
+另一种类型的群组是基于规模的群组，它按货币价值对客户进行细分。这是游戏行业（免费用户与鲸鱼用户）或 SaaS 世界中的常见做法，通过他们的 LTV 或计划对客户进行细分。
+对于本文的其余部分，我们将只关注实施基于时间的收入群组分析。
+队列分析所需的数据，在开始队列分析之前，需要以下数据：
+\*     与购买数据相关联的收入数据
+\*     用户的唯一标识符，例如客户 ID 或帐户 ID
+\*     每个用户的初始开始日期，无论是注册日期还是第一次付款。
+
+## 数据说明
+
+本文所使用的数据来自云器Lakehouse的共享样例数据，可以直接按照如下方式直接使用:
+
+```
+select * from clickzetta_sample_data.ecommerce_events_history.ecommerce_events_multicategorystore limit 10;
+```
+
+![](.topwrite/assets/image_1718761578596.png)
+
+## 分析步骤
+
+1. 临时结果集user\_cohorts：首先，我们想将用户分到群组中——在这种情况下，我们想按他们的Order Week 。
+2. 临时结果集order\_Week：接下来我们要创建一个order\_month变量。例如，客户在首次付款后一个月进行的付款的值为order\_month2。创建一个order\_Week变量。例如，客户在首次付款后一周进行的付款的order\_Week值为 2。
+3. 临时结果集cohort\_size：进一步，我们现在可以汇总cohortMonth第一步中创造的收入。这将使我们能够创建我们的rentention\_table.汇总cohortMonth第一步中创造的收入。这将使我们能够创建我们的rentention\_table.
+   构建分析模型如下：
+
+```
+WITH 
+eCommerce_LifeCycle_Order_Sequence AS (
+SELECT event_date,
+       user_id,
+       ROW_NUMBER() OVER (PARTITION BY user_id ORDER BY event_date ASC) AS customer_order_sequence,
+       LAG(event_date) OVER (PARTITION BY user_id ORDER BY user_id ASC) AS previous_order_date,
+       MIN(event_date) AS first_order_date,
+       MAX(event_date) AS last_order_date
+FROM clickzetta_sample_data.ecommerce_events_history.ecommerce_events_multicategorystore
+WHERE event_type = 'purchase'
+GROUP BY event_date,
+         user_id)
+,
+eCommerce_LifeCycle_Time_Between_Orders AS (
+SELECT event_date,
+       user_id,
+       customer_order_sequence,
+       CASE
+         WHEN previous_order_date IS NULL THEN event_date
+         ELSE previous_order_date
+       END AS previous_order_date,
+       DATEDIFF(event_date,previous_order_date) AS days_between_orders,
+       first_order_date,
+       last_order_date
+FROM eCommerce_LifeCycle_Order_Sequence)
+,
+eCommerce_LifeCycle AS(
+SELECT event_date,
+       user_id,
+       CASE
+         WHEN customer_order_sequence = 1 THEN '新客户'
+         WHEN days_between_orders > 0 AND days_between_orders < 30 THEN '活跃客户'
+         WHEN days_between_orders > 30 THEN '沉睡客户'
+         ELSE '未知'
+       END AS customer_life_cycle,
+       customer_order_sequence,
+       previous_order_date,
+       CASE
+         WHEN days_between_orders IS NULL THEN 0
+         ELSE days_between_orders
+       END AS days_between_orders,
+       first_order_date,
+       last_order_date
+FROM eCommerce_LifeCycle_Time_Between_Orders)
+select * from eCommerce_LifeCycle;
+```
+
+运行上述SQL代码，结果如下：
+![](.topwrite/assets/image_1718761957078.png)
+
+也可以通过以下方式，可以将结果直接写入到目标表中：
+
+```
+DROP TABLE if exists eCommerce_User_Cohort;
+
+CREATE TABLE if not exists eCommerce_User_Cohort
+
+AS
+
+--将用户分到群组中。在本例中，我们想按他们的Order Date
+
+with user_cohorts as (
+
+SELECT user_id
+
+, MIN(weekofyear(event_date)) as cohortWeek
+
+FROM clickzetta_sample_data.ecommerce_events_history.ecommerce_events_multicategorystore
+
+WHERE CAST(event_type as string) = 'purchase'
+
+GROUP BY 1
+
+--LIMIT 100
+
+),
+
+--创建一个order_Week变量。例如，客户在首次付款后一周进行的付款的order_Week值为 2。
+
+order_Week as (
+
+SELECT eed.user_id
+
+, (weekofyear(event_date)-cohortWeek+1) as Week_number
+
+, SUM(price) as revenue
+
+FROM clickzetta_sample_data.ecommerce_events_history.ecommerce_events_multicategorystore eed
+
+LEFT JOIN user_cohorts u on eed.user_id=u.user_id --USING(user_id)
+
+WHERE CAST(event_type as string) = 'purchase'
+
+GROUP BY 1, 2
+
+--LIMIT 100
+
+),
+
+--汇总cohortMonth第一步中创造的收入。这将使我们能够创建我们的rentention_table.
+
+cohort_size as (
+
+SELECT sum(price) as revenue
+
+, cohortWeek
+
+FROM clickzetta_sample_data.ecommerce_events_history.ecommerce_events_multicategorystore eed
+
+LEFT JOIN user_cohorts u on eed.user_id=u.user_id --USING (user_id)
+
+WHERE CAST(event_type as string) = 'purchase'
+
+GROUP BY 2
+
+ORDER BY 2
+
+--LIMIT 100
+
+),
+
+retention_table as (
+
+SELECT c.cohortWeek
+
+, o.Week_number
+
+, sum(revenue) as revenue
+
+FROM order_Week o
+
+LEFT JOIN user_cohorts c on c.user_id=o.user_id 
+
+GROUP BY 1, 2
+
+)
+
+SELECT r.cohortWeek
+
+, s.revenue as totalRevenue
+
+, r.Week_number
+
+, r.revenue / s.revenue as percentage
+
+FROM retention_table r
+
+LEFT JOIN cohort_size s on r.cohortWeek=s.cohortWeek 
+
+WHERE r.cohortWeek IS NOT NULL
+
+ORDER BY 1, 3;
+
+```
+
+## 回顾：物理表的方式
+
+不使用CTE，而是将每一个子查询的结果都落成物理表，则整个处理过程如下：
+
+1. 根据每个客户的升序订单日期创建特定于每个客户 ID 的订单序列列。这就是ROW\_NUMBER 分析函数在下面的查询中所做的。
+2. 创建一个新列，为客户 ID 插入先前的订单日期，以便在以后的代码块中用于计算订单之间的时间段。这就是LAG 分析函数在以下查询中所做的。
+   –请注意语句末尾的“Group By”order\_date 和 customer\_id 列。这很重要，因为客户可以在同一天拥有多个具有不同订单 ID 的订单。
+
+```
+DROP TABLE if exists eCommerce_LifeCycle_Order_Sequence;
+CREATE TABLE eCommerce_LifeCycle_Order_Sequence 
+AS
+SELECT event_date,
+       user_id,
+       ROW_NUMBER() OVER (PARTITION BY user_id ORDER BY event_date ASC) AS customer_order_sequence,
+       LAG(event_date) OVER (PARTITION BY user_id ORDER BY user_id ASC) AS previous_order_date,
+       MIN(event_date) AS first_order_date,
+       MAX(event_date) AS last_order_date
+FROM clickzetta_sample_data.ecommerce_events_history.ecommerce_events_multicategorystore
+WHERE event_type = 'purchase'
+GROUP BY event_date,
+         user_id;
+```
+
+针对上表运行子查询以计算 order\_date 和 previous\_order\_date 列之间的天数，您将看到创建新列 days\_between\_orders 的 DATE\_DIFF 函数会发生这种情况。
+
+```
+DROP TABLE if exists eCommerce_LifeCycle_Time_Between_Orders;
+CREATE TABLE eCommerce_LifeCycle_Time_Between_Orders 
+AS
+SELECT event_date,
+       user_id,
+       customer_order_sequence,
+       CASE
+         WHEN previous_order_date IS NULL THEN event_date
+         ELSE previous_order_date
+       END AS previous_order_date,
+       DATEDIFF(event_date,previous_order_date) AS days_between_orders,
+       first_order_date,
+       last_order_date
+FROM eCommerce_LifeCycle_Order_Sequence;
+```
+
+下一个查询使用CASE 语句创建一个附加的 customer\_life\_cycle 列，以根据 days\_between\_orders 列指示订单是来自新客户、活跃客户还是已失效客户。在此示例中，如果订单发生在距上一个订单 1 到 365 天之间的任何时间，则客户被视为活跃客户；如果先前订单超过 365 天，则客户被视为已失效。这具有高度的业务特定性，因此您的可能会有所不同。
+
+```
+DROP TABLE if exists eCommerce_LifeCycle;
+CREATE TABLE eCommerce_LifeCycle 
+AS
+SELECT event_date,
+       user_id,
+       CASE
+         WHEN customer_order_sequence = 1 THEN '新客户'
+         WHEN days_between_orders > 0 AND days_between_orders < 30 THEN '活跃客户'
+         WHEN days_between_orders > 30 THEN '沉睡客户'
+         ELSE '未知'
+       END AS customer_life_cycle,
+       customer_order_sequence,
+       previous_order_date,
+       CASE
+         WHEN days_between_orders IS NULL THEN 0
+         ELSE days_between_orders
+       END AS days_between_orders,
+       first_order_date,
+       last_order_date
+FROM eCommerce_LifeCycle_Time_Between_Orders;
+```
+
+```
+select * from eCommerce_LifeCycle limit 100;
+```
+
+## Congratulations, it's done.
+
+Please enojoy and learn more!
+
+## 附录
+
+### 下载Zeppelin Notebook源文件
+
+本文代码也提供运行在[Zeppelin](eco_integration/Zeppelin.md)的版本，你如果想直接运行本文代码，请按照文档说明安装[Zeppelin](eco_integration/Zeppelin.md)。
+
+[03.CTE(Common Table Expression)..ipynb](https://github.com/yunqiqiliang/clickzetta_quickstart/blob/main/zeppelin_notebook/03.CTE\(Common%20Table%20Expression\)..ipynb)
+[03.CTE(Common Table Expression)\_2JHUJ5BP8.zpln](https://github.com/yunqiqiliang/clickzetta_quickstart/blob/main/zeppelin_notebook/03.CTE\(Common%20Table%20Expression\)_2JHUJ5BP8.zpln)

package/bin/skills/lakehouse-doc/references/ComputeResourceDDL.md

@@ -0,0 +1 @@
+^

package/bin/skills/lakehouse-doc/references/Concepts.md

@@ -0,0 +1 @@
+^