[improvement][project] supersonic 0.7.0 version backend update (#20)

Co-authored-by: kanedai <kanedai@tencent.com>

docs/userguides/chat_config_cn.md

@@ -0,0 +1,67 @@
+English | [中文](chat_config_cn.md)
+# 问答设置
+
+问答设置旨在进一步降低用户通过自然语言方式获取数据的门槛。在超音数平台首页, 单击顶部菜单栏的**问答设置**, 然后选择特定的**主题域**, 便可对特定主题域进行问答设置, 当前支持对指标场景和明细场景分别进行设置。
+
+<img src="../images/chat_config.png" height="70%" width="70%" align="center"/>
+
+## 1. 指标场景
+
+指标场景指基于特定的维度, 进行指标的分析, 这会涉及到 group by 的聚合计算, 比如"按活跃区域查询播放量", 会基于维度**活跃区域**, 查看指标**播放量**在不同活跃区域的聚合数据。
+
+### 1.1 问答可见
+
+* 如果希望在指标场景中设置特定维度/指标的可见性, 通过以下3步即可实现：
+
+1. 在左侧列表中选择需要可见的维度和指标;
+2. 点击中间的 **>** 标志, 可将其状态由不可见转变为可见;
+3. 点击底部**完成**按钮。
+
+<img src="../images/visibility_item.png" height="70%" width="70%" align="center"/>
+
+* 如果还希望实现**维度值的联想**, 通过以下步骤即可实现:
+
+1. 对特定的维度, 勾选**维度值可见**选项;
+2. 如果有高级设置的需要, 可点击**可见维度值设置**[可选的], 高级设置可对该维度的维度值设置黑名单、白名单、sql规则等 ;
+3. 点击底部**完成**按钮。
+
+<img src="../images/visibility_dim_value.png" height="70%" width="70%" align="center"/>
+
+设置后, 系统会启动后台任务, 计算对应维度的维度值, 并写入到问答知识库中, 当用户输入不完整的歌手名时, 系统会根据知识库中的数据进行维度值联想。
+
+<img src="../images/visibility_dim_value_show.png" height="70%" width="70%" align="center"/>
+
+### 1.2 默认设置
+
+指标场景的默认设置分为指标和时间范围两个选项：
+
+<img src="../images/metric_default.png" height="70%" width="70%" align="center"/>
+
+- **指标:**  在指标场景时, 如果用户查询中没有指定指标, 系统会用此处设置的指标进行查询;
+- **时间范围:**  在指标场景时, 如果用户查询中没有指定时间范围, 如"查询流行歌手的播放量", 系统会用此处设置的时间选项进行查询, 最终查询为"查询流行歌手的最近7天的播放量"。
+
+## 2. 明细场景
+
+指标场景指仅仅查询原始明细数据, 不会涉及到聚合计算, 比如"周杰伦的代表作"。
+
+### 2.1 实体
+
+实体是指数据表中的唯一标识, 类似于主键。 一般而言，一个主题域中只有一个实体。如维度歌手名可以作为艺人库实体的唯一标识。
+
+实体只在明细场景中存在，指标场景不存在实体。当系统识别出当前查询是针对实体展开的，那么就可确定当前是一个明细查询的场景。实体设置主要分为实体别名和唯一标识两部分：
+
+- **实体别名:** 可用别名来简化实体查询, 使查询更简单;
+- **唯一标识:** 一个实体的唯一标识, 一般是维度。
+
+<img src="../images/detail_entity.png" height="70%" width="70%" align="center"/>
+
+### 2.2 问答可见
+
+具体配置含义可参考 *1.1 指标场景问答可见*
+
+### 2.3 默认设置
+
+- **维度/指标:** 在明细场景时, 如果用户查询中没有指定维度/指标, 系统会用此处设置的维度/指标进行查询, 如输入"周杰伦", 系统会将周杰伦作为维度歌手名的筛选条件, 然后查询出设置的维度/指标数据;
+- **时间范围:** 用户可根据数据特定的时效性, 设置时间点, 如果用户明细查询中不涉及时间信息, 则会用此处配置的时间进行查询。
+
+<img src="../images/detail_default.png" height="70%" width="70%" align="center"/>

docs/userguides/semantic_user_guide_cn.md

@@ -0,0 +1,108 @@
+# 语义建模
+
+### **简介**
+
+语义建模是使用超音数的第一步。在这个模块中，它可以连接上你的数据库引擎，并通过简单方便的方式来帮助你将物理数据建模为数据源、维度和指标等逻辑概念。建模完成后，你就可以在问答中通过自然语言的方式来和你的物理数据交互啦~
+
+### **问题示例**
+为了帮助你更好地理解建模的过程，我们通过一个问题示例来进行介绍: 超音数本身作为一个产品，那么如何用语义建模来统计它的埋点访问数据呢？比如超音数在一段时间内的访问用户数是多少？这些用户的访问次数和停留时长是怎样的？这些用户来自哪些部门？这些用户看了哪些页面？分别看了多少次？等我们建模完成，这些问题的答案也就浮出水面了。
+
+
+### **1. 创建一个主题域**
+
+在超音数中，主题域是一个非常重要的概念，它存在并作用于系统的每一个地方。简单来说，超音数引导用户把数据划分为一个个主题域，用户在创建主题域之后，可以在这个主题域中进行数据源，维度，指标等建模。如图1-1所示，为了统计超音数的埋点访问情况，我们创建了一个叫"超音数"的主题域作为示例:
+
+<div align="center" >
+    <img src=../images/domain.png width="70%"/>
+    <p>图1-1 主题域示例</p>
+</div>
+
+### **2. 创建一个数据库连接**
+
+创建一个数据库连接主要分为三个步骤，
+1. 填写连接信息
+2. 点击测试连接，若连接测试通过，则可点击保存。否则，返回步骤1
+3. 点击保存。
+
+如图2-1所示，由于超音数的埋点访问数据被存放在H2数据库中，因此我们创建了一个H2数据库实例作为例子。除了H2数据库以外，我们还支持MySQL，ClickHouse等多种常见数据库。
+
+<div align="center" >
+    <img src=../images/database.png/>
+    <p>图2-1 数据库连接示例</p>
+</div>
+
+### **3. 创建数据源** 
+连接上数据库之后，我们首先需要把物理数据抽象为一个个数据源。在超音数中，数据源是对数据库中数据的一种逻辑层面上的抽象，它既可以直接指代一张物理表，也可以由一段SQL逻辑表示而成。数据源中涉及的字段可被指定为维度或者度量，而这些维度和度量又可以衍生出更复杂的维度和指标。如图3-1，超音数提供了两种创建数据源方式。
+<div align="center" >
+    <img src=../images/datasource_create.png/>
+    <p>图3-1 数据源创建方式</p>
+</div>
+
+其中，**快速创建** 可以直接指定一张物理表来把它创建为数据源，而**SQL脚本** 则提供了更为灵活的数据源创建方式，我们可以通过写一条逻辑SQL来把它指定为数据源
+
+如图3-2为通过**SQL脚本**的方式创建数据源，首先我们写一条SQL来表达我们的数据源逻辑，然后点击运行，就可以看到这条SQL查询出来的数据，校验数据无误之后，我们可以点击生成数据源
+<div align="center" >
+    <img src=../images/datasource_sql.png/>
+    <p>图3-2 SQL脚本</p>
+</div>
+
+如图3-3所示，点击生成数据源之后，需要我们填写一些基本信息，如数据源名称和描述，填写完成之后，点击下一步
+<div align="center" >
+    <img src=../images/datasource_base_info.png/>
+    <p>图3-3 数据源基本信息</p>
+</div>
+
+如图3-4所示，填写完基本信息之后，需要填写一些字段信息，把数据源的字段指定为维度或者度量，其中日期和主键/外键为特殊的维度。
+**维度**主要用于筛选和分组
+**度量**主要标识数值类型字段，用来进行聚合计算
+**日期字段**主要用于标识，方便问答进行数据查询。
+**主键/外键**则用于不同数据源之间的连接字段，若多个不同数据源存在相同的主键外键，则可以进行多数据源连接
+
+<div align="center" >
+    <img src=../images/datasource_extend_info.png/>
+    <p>图3-4 数据源字段信息</p>
+</div>
+
+把字段指定为维度/度量之后，还可选择是否勾选**快速创建**单选框。若**勾选**，则会直接把选中的维度/度量批量创建到维度/指标列表。若**不勾选**，但字段已被选定为维度/度量，该字段虽然不会直接被创建到维度/指标列表，但是后续在创建衍生维度/指标的时候也可作为表达式中的字段被用上。如图3-5所示，为我们创建的3个数据源示例，分别为超音数用户停留时长统计，访问次数和访问人数统计，用户部门统计。
+
+<div align="center" >
+    <img src=../images/datasource_list.png/>
+    <p>图3-5 数据源列表</p>
+</div>
+
+
+### **4. 创建维度**
+如图4-1，为刚刚创建数据源时，通过勾选**快速创建**按钮创建出来的维度。分别为用户名，用户所在的部门，用户浏览过的超音数页面。
+<div align="center" >
+    <img src=../images/dimension_list.png/>
+    <p>图4-1 维度列表</p>
+</div>
+
+若我们需要更复杂的维度，如我们需要根据页面来划分模块，那我们可以点击创建按钮来创建一个更复杂的维度。如图4-2所示
+<div align="center" >
+    <img src=../images/dimension_create.png/>
+    <p>图4-2 维度创建</p>
+</div>
+
+### **5. 创建指标**
+和维度类似，如图5-1为通过**快速创建**按钮创建出来的指标，分别为访问超音数的次数，人数和停留时长。这几个指标都可以在用户、部门 、页面等分组粒度上进行计算。
+<div align="center" >
+    <img src=../images/metric_list.png/>
+    <p>图5-1 指标列表</p>
+</div>
+
+若我们需要统计口径更复杂的指标，如用户的平均停留时长，可以通过点击**创建指标**按钮来进行创建，如图5-2和5-3所示:
+
+<div align="center" >
+    <img src=../images/metric_base_info.png/>
+    <p>图5-2 指标基本信息</p>
+</div>
+
+如图5-3， 展示了人均停留时长这个指标依赖的度量信息，分别依赖了访问人数和停留时长这两个度量(分别来自于停留时长统计和PVUV统计两个数据源，均在度量名称前加上数据源名称作为前缀加以区分)，并通过在表达中将它们相除，计算出人均停留时长。
+<div align="center" >
+    <img src=../images/metric_sql_info.png/>
+    <p>图5-3 指标表达式信息</p>
+</div>
+
+### **总结**
+到此为止，我们就成功把超音数的访问统计数据建模成了相关的数据源、维度和指标。通过在问答中直接对这些维度和指标进行提问，就可以回答我们在介绍开头提到的那些问题啦！