# SQL 客户端

## 前提

OushuDB SQL 客户端是为 OushuDB 量身打造的基于 BS 架构 SQL 客户端，您可以使用此客户端管理数据库的对象，包括表空间、库、Schema、表、视图、函数的增删改查，
也可以使用此客户端编写 SQL、执行 SQL、查看执行结果并对执行结果进行编辑、下载等操作。

使用 OushuDB SQL 客户端，请先确保您已经安装并运行了 OushuDB 基础服务，如果您尚未安装，请参考 [OushuDB 可视化安装](../../installation/zh/oushudb/oushudb-install-ui.md)。

## 限制及约束
前端 UI 对浏览器的版本有如下限制：

| 浏览器     | 建议版本  | 最低版本 |
|---------|-------|------|
| Chrome  | \>100 | 70   |
| Edge    | \>100 | 80   |
| Firefox | \>100 | 70   |
| Safari  | \>14  | 13   |
| Opera   | \>70  | 48   |
| IE      | 不支持   | 不支持  |

## 工作簿

工作簿（Worksheet）是 OushuDB 的可视化工作平台，提供了针对 OushuDB 的对象管理、SQL 查询、上传下载等功能，各个工作簿之间相互独立，同一个工作簿可以多人同时操作互不影响，并且可以查阅他人的操作内容，合作完成任务。

### 工作簿列表

进入云数据库菜单后，默认展示的为您最近访问的工作簿列表。

![](./_static/worksheet_zj_list.png)

您也可以切换标签页，查看所有您可见的工作簿。

![](./_static/worksheet_sy_list.png)

光标悬停在某条工作簿记录上，可以看到有修改名称、设置工作簿权限和删除工作簿三个操作按钮。

![](./_static/worksheet_list_rename.png)

![](./_static/worksheet_list_qx.png)

![](./_static/worksheet_list_sc.png)

### 新建文件夹

您可以使用文件夹将不同的工作簿分类管理，统一进行授权和删除操作。在`所有工作簿`标签页中点击`新建文件夹`输入文件夹名称，即可创建一个新的空白文件夹，文件夹同样有修改名称、权限和删除三种操作。

![](./_static/worksheet_folder_create.png)

![](./_static/worksheet_folder_list.png)

点击进入文件夹内部，会展示包含的工作簿列表，点击文件夹名称可以进行修改名称和删除操作。

![](./_static/worksheet_folder_inside.png)

![](./_static/worksheet_folder_cz.png)

### 新建工作簿

您可以点击`新建工作簿`按钮创建一个空白的工作簿，或是您已经拥有一个`.sql`结尾的脚本文件，可以选择点击`从SQL文件创建工作簿`，将会自动帮您将脚本内容写入工作簿。一个新建的空白工作簿如下图所示。

![](./_static/worksheet_inside.png)

### 工作簿使用

点击顶部工作簿标签左侧的按钮可以返回工作簿列表。

![](./_static/worksheet_return.png)

点击顶部工作簿标签名称可以打开多项操作，包括修改工作簿名称、查看工作簿 SQL 的版本历史、复制当前工作簿 SQL 到一个新的工作簿、移动工作簿、导入一个 SQL 脚本文件、把工作簿 SQL 文本导出、删除工作簿等。

![](./_static/worksheet_tab.png)

此处可以选择当前工作簿使用的 OushuDB 实例和虚拟计算集群。

![](./_static/worksheet_select_instance.png)

此处可以指定 SQL 执行时的资源队列。

![](./_static/worksheet_select_resource_queue.png)

此处按钮可以快捷改变下方展示区域的布局以及全屏显示。

![](./_static/worksheet_qp.png)

#### 对象管理

左侧分为资源和收藏两个功能标签，资源展示的是当前 OushuDB 实例的对象管理，收藏展示的客户标记收藏的表、视图和函数，可以进行一些快捷操作。

![](./_static/worksheet_zy.png)

![](./_static/worksheet_sc.png)

##### 库

资源的对象管理部分，第一行表示的是`数据库（database）`，我们可以在下拉列表内切换不同数据库，并在后面更多按钮中使用其他可视化快捷操作，例如新建、编辑、删除数据库以及数据库授权等操作。

![](./_static/worksheet_db.png)

##### 模式

资源的对象管理部分，第二行表示的是`模式（schema）`，我们可以在下拉列表内切换不同数模式，并在后面更多按钮中使用其他可视化快捷操作，例如新建、编辑、删除模式以及模式的授权等操作。

![](./_static/worksheet_schema.png)

##### 表

支持可视化的创建内表或外表。新建内表的时候可以选择分区、压缩方式等信息，创建外表的时候可以填写表位置和压缩方式等。

![](./_static/worksheet_table.png)

![](./_static/worksheet_table_create.png)

![](./_static/worksheet_table_create2.png)

光标悬浮到某个数据表时，可以看到收藏、复制名称、编辑表、删除表、新建列等操作按钮。

![](./_static/worksheet_table_list.png)

展开表信息，我们可以看表的全部列，并做编辑和删除操作。

![](./_static/worksheet_table_col.png)

##### 视图

支持可视化的创建视图，并对已有视图做收藏、复制名称、删除、查看信息、预览数据等操作。

![](./_static/worksheet_view.png)

![](./_static/worksheet_view_list.png)

##### 函数

支持可视化的创建函数，并对已有函数做收藏、编辑和删除等操作。

![](./_static/worksheet_func.png)

![](./_static/worksheet_func_list.png)

> 注意：当使用上述提到的对象的可视化创建功能时，所填写的对象名称是`大小写敏感`的，请根据需要正确填写对象名称的大小写。

#### SQL控制台

工作簿右上方的部分是 SQL 控制台，可以让我们编写 SQL 脚本并进行执行。SQL 脚本编写支持语法高亮、关键字自动补全（包括库、Schema、表、列名字）、
格式化、版本管理等功能。

SQL 执行的结果支持表格的方式与控制台的方式展现，以满足不同的需求。以表格方式展现查询结果时，可支持对查询结果数据的
修改。同时支持下载查询结果。

![](./_static/worksheet_sql.png)

上面一排按钮依次是：

执行（支持选中部分单独执行）

![](./_static/worksheet_sql_execute.png)

![](./_static/worksheet_execute_partially.png)

执行按钮右侧有一个下拉选项，可以在普通【执行】(返回数据表格)和【以控制台方式执行】模式之间切换

![](./_static/worksheet_execute_functional_enable.png)

当以控制台方式执行时，执行的结果将以逐行输出的命令行形式呈现。（示例 SQL：select * from user;）

这意味着每个执行步骤都会在屏幕上独立显示，以更清晰地展示每个命令的执行结果。

这种形式的输出使您能够逐步查看程序或脚本的运行过程，方便调试和定位潜在问题，有助于提高可视化和理解性，更容易分析和监控代码的执行流程。

![](./_static/worksheet_execute_functional_enable_execute.png)

设置最大查询数量

![](./_static/worksheet_sql_count.png)

设置查询的数据库和模式

![](./_static/worksheet_sql_searchpath.png)

格式化

![](./_static/worksheet_sql_format.png)

注释

![](./_static/worksheet_sql_annotation.png)

快捷键

![](./_static/worksheet_sql_key.png)

从 SQL 文件导入

![](./_static/worksheet_sql_import.png)

导出为 SQL 文件

![](./_static/worksheet_sql_export.png)

保存 SQL 脚本版本

![](./_static/worksheet_sql_save.png)

![](./_static/worksheet_sql_save2.png)

查看 SQL 脚本版本历史

![](./_static/worksheet_sql_history.png)

![](./_static/worksheet_sql_history2.png)

#### 结果可视化（可编辑列表）

工作簿右下方的部分是执行的查询历史和执行查询结果（多个）的标签页。
执行多条语句时，展示最后 20 条执行结果。

列表模式下，可以查询表的查询结果，同时当处在单表查询时，还可以对查询的结果进行增删改查。

##### 执行历史
可以对执行历史进行查看，点击 SQL 还能看到执行时的具体SQL，同时也可以对不需要的记录进行删除。
![](./_static/worksheet_result_overview.png)

##### 标签页管理
多个Select语句时，可以同时查看多个执行结果，也可以在执行结果标签上右键关闭不需要的执行结果。
![](./_static/worksheet_result_tab.png)

##### 执行中（可取消未执行语句）
当任务处在执行中时，会显示执行中的样式。
![](./_static/worksheet_executing.png)

##### 取消执行
当任务处在执行中时，可以点击取消按钮阻止执行，当阻止成功时，会显示如下内容：
![](./_static/worksheet_execution_cancelled.png)

##### 执行结果
以下是执行结果的示例图：
![](./_static/worksheet_result_list.png)

##### 执行结果列配置
执行结果表的列，通过点击右侧的列配置，可以自定义列的显示和顺序。
![](./_static/worksheet_result_list_column_settings.png)

##### 执行结果列表列头自定义宽度
执行结果表的列头可以直接拖拽边缘处进行修改宽度
![](./_static/worksheet_result_list_column_width_custom.png)

##### 执行结果列表搜索高亮
![](./_static/worksheet_result_list_search_highlight.png)

##### 执行结果列表编辑单元格（可双击或者右键单元格选择编辑）
![](./_static/worksheet_result_list_cell_editing.png)

##### 执行结果列表单元格右键菜单（根据不同场景显示有所不同）
![](./_static/worksheet_result_list_cell_right_menu.png)

##### 删除行（删除已有行时标记颜色，删除新增行直接抹除）
![](./_static/worksheet_result_list_delete_row.png)

##### 被删除的已有行标记颜色
![](./_static/worksheet_result_list_deleted_row.png)

##### 新增行
![](./_static/worksheet_result_list_new_row.png)

##### 还原修改
可还原修改过的单元格、删除的行、新增行。
![](./_static/worksheet_result_list_revert.png)

##### 预览修改
可选择本次改动的条件匹配列

![](./_static/worksheet_result_list_preview_match.png)
![](./_static/worksheet_result_list_preview.png)

##### 提交修改
![](./_static/worksheet_result_list_commit.png)

#### 结果可视化（图表）
执行结果也可以使用图表自定义展示。

![](./_static/worksheet_result_picture.png)


## 传输任务

传输任务分为表数据导入、表数据导出和执行结果导出三种。

![](./_static/worksheet_task_list.png)

点击任务名称可以查看任务的详细信息，并执行相应的操作。

![](./_static/worksheet_task_list2.png)

### 表数据导入

点击查看表结构，点击导入数据，按需填写上传即可创建表数据导入任务。

![](./_static/worksheet_table_insert1.png)

![](./_static/worksheet_table_insert2.png)

### 表数据导出

点击查看表结构，点击导出数据，按需填写即可创建表数据导出任务。

![](./_static/worksheet_table_output1.png)

![](./_static/worksheet_table_output2.png)

### 执行结果导出

在执行结果处点击导出执行结果按钮，按需填写即可创建执行结果导出任务，支持自定义任务名称，支持CSV、TEXT文件类型，支持是否携带表头。

![](./_static/worksheet_result_output1.png)

![](./_static/worksheet_result_output2.png)

## 快捷短语

通过快捷短语功能，可为 SQL 文本定义快捷短语名称。在工作簿中输入快捷短语名称，可调出对应的 SQL 文本，达到快速录入的目的。
### 快捷短语列表

快捷短语列表展示了当前用户有权限看到的快捷短语信息，并提供新建、编辑、删除、批量删除快捷短语的功能。

![](./_static/worksheet_shortcut_list.png)

### 新建快捷短语

点击`新建`按钮，打开新建快捷短语窗口，在此可完成快捷短语的定义。

![](./_static/worksheet_shortcut_new1.png)

* **快捷短语名称**：在工作簿中，通过输入快捷短语名称可实现对应 SQL 文本的快速录入。
* **权限**：公共 / 个人。公共：所有用户均可见。个人：只有创建本快捷短语的用户可见。
* **快捷短语 SQL**：快捷短语代表的 SQL 文本。

### 使用快捷短语

在工作簿中，输入快捷短语名称，可快速匹配到用户有权限使用的快捷短语，按回车键，可实现对应 SQL 文本的快速录入。

![](./_static/worksheet_shortcut_input1.png)

![](./_static/worksheet_shortcut_input2.png)

在工作簿中，可通过`新建快捷短语`功能按钮，快捷打开新建窗口添加快捷短语。
![](./_static/worksheet_shortcut_new2.png)

## 迁移工具

为支持用户业务系统从友商数仓平台方便快捷的迁移到 Skylab 云平台，Skylab 提供了自动化迁移工具，可帮助用户完成 DDL 脚本、 SQL 脚本、业务程序脚本、函数的转换。

### 迁移任务列表

迁移任务列表展示了当前系统中已定义的迁移任务。光标移动到某项任务，可通过浮现的功能按钮启动任务或删除任务。也可通过顶部功能栏的`新建任务`按钮打开新建任务窗口。

![](./_static/worksheet_convert_list.png)

### 新建和编辑迁移任务

在新建和编辑迁移任务窗口，可定义或修改迁移任务的各个参数，并通过`保存`按钮完成任务创建或修改。

![](./_static/worksheet_convert_edit.png)

* **任务名称**：新建任务可自动生成带时间戳的任务名称，可根据需要自行修改。
* **文件路径**：待转换的源脚本文件全路径，此文件要提前上传到 Lava Server 服务器中 oushu 用户有权访问的路径下。
* **文件处理开关**：实现了文本替换功能（暂不支持正则表达式），可根据需要开启此功能。文本处理开启后，可指定文件编码方式（UTF-8 或 GBK），并自定义文本替换规则。
* **转换开关**：实现了DDL 脚本、 SQL 脚本、业务程序脚本、函数的语法转换功能，可根据需要开启此功能。脚本类型分为：DDL 脚本和其他脚本。
    * **DDL 脚本**：当前支持 GBase、Mysql、Oracle、Vertica 语法向 Skylab 云平台语法的转换。
    * **其他脚本**：其他脚本包括：Perl 文件、SQL 文件、动态函数、静态函数。转换支持情况如下：

|数据源类型   |Perl 文件 |SQL 文件|动态函数|静态函数|
|  ----      | ----    | ----   | ----   | ----  |
| DB2        | -       |  -     | 支持   | -     |
| Greenplum  | -       |  -     | 支持   | 支持  |
| Hive       | -       |  -     | 支持   | -     |
| Netezza    | 支持    | 支持    | 支持   | -     |
| Oracle     | -       | 支持    | 支持   | -     |
| Teradata   | 支持     |  -     | 支持   | -     |
| Vertica    | 支持    |   -     |   -   | -      |

### 查看迁移任务详情

在迁移任务列表中点击某个迁移任务的名称，可查看该任务的详情和任务历史执行记录。

迁移任务详情：

![](./_static/worksheet_convert_detail.png)

迁移任务历史执行记录：

![](./_static/worksheet_convert_history.png)

在任务执行历史清单中，光标移动到某项执行记录，可通过浮现的功能查看文件对比、查看执行日志、导出转换后的脚本文件、删除此项执行记录。

在文件对比功能中，左侧展示源脚本文件，右侧展示转换后的脚本文件。画面中对比展示了转换前后的脚本文件差异。在右侧窗口中，可直接编辑转换后的脚本文件，并通过`保存`按钮保存编辑结果。

![](./_static/worksheet_convert_compare.png)

在日志任务功能中，展示了服务器侧执行脚本转换任务的日志。

![](./_static/worksheet_convert_tasklog.png)

## 表空间管理

选择对应的 DB 集群，展示 DB 表空间列表，提供创建表空间的功能
### 表空间列表

展示选中DB集群的表空间列表，展示字段包含表空间名称、表空间拥有者，表空间选项、表空间路径。

![](./_static/worksheet_tablespace_list.jpg)

### 新建表空间

点击`新建表空间`按钮，打开新建表空间窗口，在此可完成表空间的创建。

![](./_static/worksheet_tablespace_add.jpg)

* **表空间名称**：DB 表空间名称，同一 DB 集群不可重复。
* **表空间路径**：表空间对应的远程 hdfs 地址。
* **表空间桶数量**：提供默认值。
* **表空间选项**：可选择填写自定义表空间选项。