You need to enable JavaScript to run this app.
最新活动
产品
解决方案
定价
生态与合作
支持与服务
开发者
了解我们
导航

脚本式Query

最近更新时间2022.09.07 11:50:09

首次发布时间2022.07.26 11:41:17

根据实际业务场景,您可以通过自定义SQL的脚本模式,自行编写API的查询SQL,实现更复杂的查询需求。本文为您介绍如何通过脚本模式生成API。

1 使用前提

  • 已完成相关数据集的创建,操作详见:创建数据集

2 新建Query

  1. 登录 DataLeap租户控制台

  2. 概览 界面顶部服务窗口,点击 数据服务 ,可快速进入到 数据服务 功能界面。

  3. 在上方导航栏中,点击 Query 进入界面。
    alt

  4. 左侧导航栏中,点击 新建Query,在弹窗中填写以下参数完成新建:

参数说明
类型表查询类型,可选择向导式、脚本式、原生Query,此处选择脚本式创建。
Query名称输入Query名称,只允许英文,数字和下划线。
Query存放目录选择Query存放的目录,下拉选择已创建的Query目录,目录创建方式详见:Query目录
网络协议仅支持HTTPS协议。
返回类型仅支持JSON返回类型。
负责人下拉选择Query负责人。
最大QPS设置每秒向服务发送的请求数量峰值,需正整数。
用途描述输入该Query使用场景,方便后续管理。
初始Query版本输入Query版本,三段式个位数,如1.0.0。
版本描述输入版本描述,方便后续多版本管理。

更多配置(可选)

  1. SLA:设置服务等级保障。
  2. PCT99:响应时间指标,99%的请求可以在设定的时间内得到响应。
  3. 超时:一次调用时间超过设定的时间后会失败。
  1. 参数填写完整后,点击 确认 按钮,完成新建Query。

  2. 点击Query名称右侧的 更多 按钮,您可以进行以下操作:

    • 详情:查看当前Query的详情,查看通用信息、版本信息、接口信息等。

    • 编辑:进入当前Query编辑界面,配置Query的请求参数、返回参数等。

    • 移动:移动当前Query到其他Query目录文件夹下。

    • 删除:删除当前Query。

3 配置Query

3.1 选择数据集

  1. 点击Query名称,进入编辑界面,选择数据集信息。

  2. 下拉选择,或输入关键字搜索 数据集 中创建的 数据集目录文件夹 名称。

  3. 下拉选择,或输入关键字搜索目录文件夹下已导入的数据集名称。

数据集相关操作详见:创建数据集

3.2 参数设置

3.2.1 编辑器选择

脚本式API需要您在编辑器自行编写Query,脚本编辑目前支持 SQL编辑器XML编辑器, 您可以在下方入口进行切换:
alt

3.2.2 编辑器工具栏

说明

  • 请求参数推断 功能添加的请求参数外,您也可以自行新增一些请求参数,而不必在SQL中使用它,请求参数推断 功能不会覆盖掉您自己新增的请求参数。同理 推断返回参数 也不会覆盖您已经指定的返回参数。

  • 手动新增参数详见:向导式Query---参数设置

功能说明

编辑框

您可以在此输入代码逻辑,语法规则详见:SQL语法详情

示例代码:
select
    runoob_id,
    runoob_title,
    runoob_author,
    submission_date
from
    @dataset
where
    runoob_id = #{runoob_id};  --runoob_id 自动为请求参数,可自动进行 请求参数推断。

请求参数推断

  • 请求参数推断会自动填充您写在SQL中的请求参数名称,但不会推断数据类型,即struct类型只会自动填写struct名称,而不会推断成员。
      所以 请求参数推断 生成的请求参数,需再手动下拉添加参数类型,如:int、string、date等。
  • 返回参数也不用您填写,在测试Query页面,勾选 推断返回参数 ,测试结果出来后会自动填充返回参数的 名称类型 到返回参数页面。同样,你可以自己指定返回参数,返回参数推断同样不会覆盖你已经指定的返回参数。
格式化格式化您书写的代码,使其可读性、结构上更清晰明了。
清空一键清空编辑器中您书写的代码。

编辑器语法说明:

语法说明
#{}根据数据类型自动生成 SQL 片段,应当尽量使用 #{} 符号,这可以有效避免 SQL 注入问题。
${}直接将对应的数据插入到 SQL 中。

@dataset

作为数据集占位符,如select p_date from @dataset。
多个数据集join时,也可使用 `数据集目录名`.`数据集名称` 表示。

注释支持块级注释 /*comment*/,行级:--comment,不支持 <!---->
XML编辑器动态SQL的格式是XML,最外层(根节点)必须要以<select></select>元素包裹。
XML转义在XML格式的动态sql中如果包含 > 或 < 等符号, 有些情况会导致XML解析失败,此时需要对xml元素包裹的sql使用转义字符,常用的转义字符见下方表格。

常用转义字符

操作符转义字符说明
&nbsp;空格
<&lt;小于号
>&gt;大于号
&&amp;
"&quot;双引号
'&apos;单引号

3.3 高级配置

  • 数据缓存时间:用于设定服务查询对结果集的缓存时间。
    • 系统策略:默认600s 缓存时间。

    • 手动设置缓存时间,单位:秒。

    • 关闭缓存时间。

3.4 保存Query

数据集、参数等信息配置完成后,您可以点击右上角 保存 按钮,保存该Query:
alt
保存 按钮,直接保存当前版本。
若当前线上有已发布的版本,直接修改会影响调用,您可以选择以下保存方式:

  1. 另存为新的版本:将当前的修改另存为新版本保存,在弹窗中填写 新版本号 即可完成保存。

  2. 另存为新的Query:将当前的修改另存为新Query保存,在弹窗中填写 Query基本信息 完成新建。

  3. 或者在右侧 版本信息 内可将当前版本Query下线之后,再进行修改保存。

4 Query基本信息

点击界面右侧导航栏中的 基本信息,即可实现基本信息的修改,支持修改Query名称、负责人、QPS限流、SLA、PCT99、超时等Query基本信息,修改完成后,点击 保存基本信息 按钮,即可完成修改。

5 版本信息

点击界面右侧导航栏中的 版本信息,记录历史各Query版本:

  • 版本:
    • 您可以点击历史版本号,编辑界面将会切换到历史版本。

    • 您也可以在Query编辑界面上方的导航栏中,选择历史版本号,点击进入编辑。

alt

  • 版本对比:您可以勾选两个版本号,点击右上角 对比 按钮,进行基本信息、参数等对比。

  • 提交日期:您可以点击说明栏的 排序 按钮,根据日期先后进行排序。

  • 操作栏:

    • 下线-线上:将线上已有的版本下线操作。

    • 发布-线上:将未发布的版本操作上线,会覆盖之前已发布的版本。

    • 详情:点击后跳转到详情界面,查看Query的通用信息、版本信息、HTTPS接口信息等详情。

    • 删除:允许删除未发布的版本。


6 SQL语法详情

点击界面右侧导航栏中的 SQL语法详情,详细了解语法详情。

6.1 SQL通用规则

  1. 仅支持一条 SQL 语句,不支持多条 SQL 语句。

  2. 仅支持 SELECT 语句,不支持非 SELECT 语句,如 UPDATE, DESCRIBE 等。

  3. 数据集使用字符串 @dataset 进行占位。如select p_date from @dataset。或者使用数据集目录名和数据集名字占位。比如 select p_date from `dir_name`.`dataset_name`。

  4. 不支持 SELECT * 语句,必须明确指出需要查询的列。

6.2 定义参数

  1. SELECT 语句的返回结果字段必须和 API 定义的返回参数名字、类型、个数保持一致。如果返回字段是聚合函数或其他表达式,请对其重命名。

  2. SQL 语法是 dynamic unified sql(暂不支持直接使用底层引擎SQL语法)。 使用 #{} 符号来引用请求参数。比如需要引用参数 date 则写作#{date}, #{} 符号会根据参数类型将参数拼接到查询的最终SQL中。

  3. 也可以使用 ${} 符号引用参数, ${} 符号不会根据数据类型将参数拼接到最终的SQL中,而是将${}内的参数的值作为字符串直接拼接到SQL中。比如参数 app (类型是string, 值是video), 对于表达式 app_name=#{app} 生成的查询语句是 app_name='video', 对于表达式 app_name=${app} 生成的查询语句是 app_name=video。

6.3 函数列表

支持多种函数,例如日期函数date、adddate、datediff等,您可以在搜索框中输入函数关键字进行搜索。
更多函数列表,详见界面右侧导航栏 SQL语法详情