基于数据集，通过编写SQL语句灵活创建API，支持多表关联查询、参数化查询、向量查询等功能。本文为您介绍如何使用SQL模式生成API。
前提条件
需购买非结构化数据功能和数据服务功能才能使用数据集API。
需在研发 > 数据研发 > 数据集中创建并提交数据集，详情请参见数据集。
使用限制
使用API分页查询时，需要设置字段排序以确保返回结果的顺序稳定，避免导致分页查询的部分结果重复及丢失；仅当使用API分页查询时，在API调试或测试页面展示分页参数（PageStart及PageSize）信息。
在API调用时，分页查询是否开启，均可使用PageStart及PageSize设置分页。
仅支持表数据集和混合数据集创建数据集-SQL模式。
基于数据集的SQL模式API仅支持同步调用及单表查询，不支持多表关联查询（Join），且不会校验字段是否在数据集中。
权限说明
数据服务的项目管理员和开发用户支持生成API。
步骤一：选择生成API的方式
在Dataphin首页的顶部菜单栏，选择服务 > API开发。
在左上角选择项目，单击左侧导航栏API服务，在API页面，单击+新建API。
在新建API对话框，选择数据集API-SQL模式（数据集）。
步骤二：配置API参数信息
在新建API页面，配置API基本信息和SQL参数配置。
API基本信息配置
参数
描述
API名称
填写API的名称。命名规则如下：
只能包含中文、字母、数字或下划线（_）。
长度为4~100个字符。
以字母开头。
全局唯一。
操作方式
API操作类型包括GET和LIST：
GET：请求服务器获取指定的某个资源。
LIST：请求服务器获取某一部分的资源。
数据更新频率
定义API返回数据的更新频率，便于调用方了解数据的时效性，支持的更新频率为每天、每小时、每分钟以及自定义，若选择自定义，支持输入不超过128个字符。
API分组
选择当前项目下配置的API分组，如需创建，请参见创建服务分组。
描述
填写对API的简单描述。不超过128个字符。
协议
数据生成API的接口协议，支持HTTP协议。
HTTP：即超文本传输协议HTTP（HyperText Transfer Protocol），是应用最为广泛的网络协议。
调用模式
用于客户端和服务器之间的通信，以获取或处理数据。支持选择同步调用。
同步调用：客户端发送请求后，必须等服务器返回结果后才能继续执行其他请求，针对复杂查询语句，响应时间较长且在等待过程中会占用服务器连接数，造成服务器压力。适用于实时性要求高、处理时间短的场景。
超时时间
用于监控API调用的最大时长。默认为3秒，支持设置的时间范围为3到60秒的正整数。
调用API过程中如果超过了设定的超时时间，则调用API时会报错，便于您及时发现并处理调用API的异常情况。异常情况查看，详情请参见管理运维监控API。
最大返回条数
当操作类型为LIST时支持该配置项。API最大的返回条数为10000条。支持输入1~10000之间的正整数。
缓存设置
支持开启或关闭。开启后需配置缓存时长。默认300秒，支持设置60秒~1000000秒（约277.78小时）之间的正整数。
版本号
请填写API的版本号，每份配置信息会有所属版本号，以便于和上个版本信息对比。该API下版本号唯一。命名规则如下：
不超过64个字符。
支持输入大小写英文字母、数字、下划线（_）、半角句号（.）、短划线（-）。
返回类型
默认JSON。
返回SQL
控制API响应中是否包含实际执行的SQL语句。
选择是（启用）：API响应中将返回数据库实际执行的物理SQL语句。
选择否（禁用）：API响应中将展示原始SQL脚本。
选择数据集并编写SQL
在参数配置区域，先选择数据集，再编写SQL语句定义API的查询逻辑。
选择数据集：配置模式、项目、数据集及版本。
参数
描述
模式
支持Basic模式和SQL模式。Basic模式下开发、提交均读取生产库；SQL模式下通过编写SQL语句灵活定义API查询逻辑。
SQL模式
支持选择基础SQL和高级SQL两种模式。
项目
选择对应模式下的项目。
数据集
选择对应项目下已发布的数据集及版本。
结果分页
当操作类型为List时，支持设置结果分页。开启后，请务必指定排序字段，确保返回查询结果的稳定，避免导致分页查询的部分结果重复及丢失；关闭后，API调试或测试页面不展示分页参数（PageStart及PageSize），您可以取消选中隐藏参数，展示分页参数。
排序优先级
开启结果分页后，需要设置排序优先级。
当SQL模式选择基础SQL时，可以选择排序的优先级顺序，支持选择SQL脚本或OrderByList请求参数。
SQL脚本：若SQL脚本指定了排序，则公共请求参数中的OrderByList不生效。
OrderByList请求参数：在测试或调试API时，SQL脚本中定义的排序与OrderByList公共请求参数同时生效，OrderByList公共请求参数的优先级高于API中定义的排序设置。
当SQL模式选择高级SQL时，在测试或调试API时，SQL脚本中定义的排序与OrderByList公共请求参数同时生效，OrderByList公共请求参数的优先级高于API中定义的排序设置。
编写SQL语句：在SQL编辑器中编写查询语句。SQL编辑器支持以下功能：
API SQL脚本编辑：API SQL脚本帮助您在编辑脚本时需遵循的SQL编辑规范，详情请参见API SQL脚本编辑说明。
语法高亮：SQL关键字、表名、字段名等以不同颜色高亮展示，便于阅读和编写。
格式化：单击工具栏的格式化按钮，可对SQL语句进行自动格式化排版。
参数化查询：使用
${参数名}语法定义请求参数，系统会自动解析SQL中的参数占位符并生成对应的请求参数列表。参数名命名规则：以字母开头，仅包含字母、数字或下划线（_），长度为1~64个字符。
参考示例
Get/List基础SQL示例： -- 示例一：根据条件查询单条记录；id非必填且未传参时，自动忽略该条件 SELECT id,name FROM tablename WHERE id = ${id} -- 示例二：In条件批量查询，id_list参数按","分隔 SELECT id,name FROM tablename WHERE id in (${id_list}) -- 示例三：使用Like模糊匹配，聚合函数使用语义化别名 SELECT MAX(a) AS max_a, SUM(a) AS sum_a, MIN(a) AS min_a, COUNT(*) AS count_all FROM tableName WHERE name LIKE ${name_pattern} -- 示例四：带标别名的查询 SELECT t.name as name FROM tablename t WHERE id=${id_card} -- 示例五：表达式计算+多条件查询 SELECT (a+b) as sum_ab, (b+c) as sum_bc FROM tablename WHERE id=${id_card} and b>=${num} and c<=${num1} -- 示例六：分组 + CASE统计 SELECT category, SUM(CASE WHEN name LIKE ${name_pattern} THEN 1 ELSE 0 END) AS proj_score FROM table WHERE id=${id} GROUP BY category Get/List高级SQL示例： -- 目前支持的Mybatis标签类型包括：if、choose、when、otherwise、trim、foreach和where。 -- 标签内的SQL参数支持$或者#符号标识，具体示例如下 -- 示例1：使用 <where> + <if> 实现条件过滤 SELECT id, name, age FROM tableName <where> <if test="name != null and name != ''"> AND age > #{age} </if> <if test="name == null"> AND age < #{age} </if> </where> -- 示例2：使用 <choose> 实现互斥条件 SELECT id, name, age FROM tableName <where> <choose> <when test="name != null and name != ''"> AND age > #{age} </when> <when test="age != null"> AND age < #{maxAge} </when> <otherwise> AND status = 'active' </otherwise> </choose> </where> -- 示例3：使用 <foreach> 实现 IN 查询 SELECT id, name FROM tableName <where> id IN <foreach item="item" index="index" collection="idList" open="(" separator="," close=")"> #{item} </foreach> </where> -- 示例4：使用 <trim> 自定义前缀（替代 <where>） SELECT id, name, age FROM ${tableName} <trim prefix="WHERE" prefixOverrides="AND | OR "> <if test="name != null"> AND name LIKE #{namePattern} </if> <if test="minAge != null"> AND age >= #{minAge} </if> <if test="status != null"> AND status = #{status} </if> </trim> -- 示例5：动态字段查询（var_cols） SELECT category,${var_cols_metrics} FROM tableName WHERE id = ${id} GROUP BY category说明SQL语句中的表名需使用数据集中定义的表名。
SQL语法需与数据集关联表的引擎保持一致。您可在右侧字段参考面板查看引擎类型，并编写与引擎兼容的SQL语句。
涉及向量距离运算的SQL语句中，特殊运算符需使用CDATA语法包裹。例如vector的余弦相似度排序需写为
ORDER BY embedding <![CDATA[<=>]]> '[1,2,3]'。
字段参考
选择数据集后，单击右侧字段参考，为您展示数据集对应字段，包含以下内容：
表名：数据集中包含的表名称，可快速复制表名至SQL编辑器。
引擎类型：数据集对应的引擎类型。
字段列表：展示每个表下的所有字段名称及字段类型。单击字段名称可快速插入至SQL编辑器。URL字段以链接图标标识，向量字段以向量图标标识。
请求参数
编写SQL语句后，单击解析参数按钮，系统自动解析SQL中的
${参数名}，生成请求参数列表。若SQL模式选择高级SQL，支持勾选保留手动配置，当修改SQL脚本需再次解析参数时，系统将保留已填写的参数信息；如需删除无用参数信息，请手动删除。适用于复杂的SQL语句参数无法解析，需手动填写参数信息的场景。说明若SQL模式为高级SQL，以var_cols开头的参数为动态参数，支持通过传参的方式动态指定SQL语句查询返回的字段，可将所有支持的字段添加到返回参数中。调用API时，在动态参数中传入需要查询的字段，若未传入，则字段在返回参数中为Null值。
若SQL模式为基础SQL，当参数为非必填且无输入参数时，系统将自动改写SQL，忽略对应的筛选条件；若参数值类型为between，则该参数值为必填。
高级SQL语句较为复杂，SQL编译解析的参数不一定完整且正确。因此，您可根据SQL语句对解析结果进行删除参数、新增请求参数和新增返回参数操作。
参数
描述
请求参数
参数名称
由SQL中的
${参数名}自动解析生成。支持手动修改参数名称，命名规则如下：参数名称唯一。
包含字母、数字或下划线（_）。
以字母开头。
长度为1~64个字符。
参数类型
为您展示数据集对应字段类型。
参数类型包括double、float、string、Date(yyyy-MM-dd HH:mm:ss)、Boolean、int、long、short、byte、BigDecimal和binary。
参数值类型
必填，选择参数值的类型，支持单值、多值。
单值：根据参数类型传入，传入参数将被解析为单一值。
多值：传入参数将被解析为多个值，多个值之间使用半角逗号（,）分隔，适用的操作符为in。
参数处理
当SQL模式为基础SQL且向量字段为string类型、单值参数值类型时需配置。支持选择平台转向量、不处理。
平台转向量：系统将自动调用向量字段配置的Embedding模型，把输入的文本转换为向量数值。
不处理：系统将原样保存提交的数据，不进行任何向量转换、语义分析等。
示例
填写请求参数值的示例，便于开发者理解。支持输入不超过1000个字符。
描述
填写对请求参数的简单描述。支持输入不超过1000个字符。
是否必填
选择请求参数是否为调用API时的必填参数。
选择否：调用API的语句中没有该参数也可以执行调用API的SQL语句。
选择是：调用API的语句中没有该参数，将无法执行调用API的SQL语句。
例如，请求参数为id，请求参数为必填参数，返回参数为name；则执行以下语句会有不同的返回：
返回对应的name字段及数据：select name from tableA where id=5;。
SQL语句执行报错：select name from tableA;。
默认值
若参数值未指定，则使用默认值（未设置时为NULL），支持输入不超过1000个字符。
返回参数
参数名称
必填，显示对外开放的参数名，系统从SQL中解析，不支持修改。
参数类型
调用API时的数据格式。参数类型包括double、float、string、Date(yyyy-MM-dd HH:mm:ss)、Boolean、int、long、short、byte、BigDecimal、binary和vector。
示例
填写返回参数值的示例，便于开发者理解。支持输入不超过1000个字符。
描述
填写对返回参数的简单描述。支持输入不超过1000个字符。
SQL试运行
单击SQL试运行，在请求参数输入对话框中，选择参数类型、参数值类型、参数处理和试运行输入值，然后单击确认。
运行日志：支持查看SQL试运行时实际执行的SQL语句。
试运行输入值：需要配置绑定字段的字段值，可以在数据预览面板查看绑定字段的字段值。
批量操作：支持批量修改请求参数的参数类型、参数值类型、参数处理（仅基础SQL模式且向量字段为string类型、单值参数值类型时支持操作）及批量删除参数（仅高级SQL模式支持操作）。
填充参数示例值
单击填充参数示例值，系统会将最近一次试运行成功的示例值填充至请求参数和返回参数。如果示例有值，则不进行覆盖，支持修改。
仅当SQL模式为高级SQL且已有试运行结果记录时，支持单击填充返回参数/从试运行结果导入，在填充参数对话框中，配置参数的添加方式及同名参数处理方式。
添加方式：导入参数时的添加策略，支持追加新参数和全量替换已有参数。
追加新参数：保留返回参数列表中已有参数并追加本次试运行结果中的解析的参数，根据参数名称唯一性，添加列表中不同名参数。
全量替换已有参数：将返回参数列表中已有参数全部替换为试运行结果中解析的参数。
同名参数处理：当添加方式为追加新参数时支持配置。针对添加的参数名称重复时处理策略，支持保持不变或替换。
保持不变：保留原有参数信息不变更。
替换：若试运行结果的参数名称和列表中的参数名称重复，以本次试运行结果中解析的参数类型和示例值为准更新列表中的信息；若试运行结果的值为空，则不进行替换。
若选中同步填充请求参数的示例值，将根据填充参数的配置同步替换请求参数列表中的示例值。
Download URL字段配置
当数据源为OSS且SQL中SELECT的返回字段包含URL字段时，系统会在执行SQL后自动生成临时下载链接并返回至结果中。您可以配置域名替换和过期时间。
域名替换：开启后，输入需替换的域名；关闭则使用文件存储默认域名。
过期时间：链接的过期时间，默认3600秒，支持配置的时间范围为60~86400秒（24小时）。
单击提交，完成API的生成。