发布和调用 API
完成 SQL 函数后,可以把它发布为 HTTP API。调用方只需按函数声明传入数据,无需了解函数内部的召回、排序等步骤。
发布函数
假设已经定义了名为 recommend 的 SQL 函数,API 定义为:
CREATE OR REPLACE API recommend WITH recommend;第一个 recommend 是 API 名称,WITH 后的 recommend 是 SQL 函数名称。发布后通过以下地址调用:
POST /api/v1/recommend如需覆盖同名 API,使用 OR REPLACE。SQL 函数的编写方法见编写推荐流程。
API 定义与 SQL 函数采用相同的加载方式。使用 SQL 文件时,将上述语句保存为 api/recommend.sql 并重启服务,步骤见管理本地 SQL 定义。使用远程元数据时,通过 Beeline 或 JDBC 执行该语句。
发起请求
请求体中的 data 按“输入表名 → 行数组”组织。每个由 DEFINE INPUT TABLE 声明的输入表都必须提供,并且字段应与声明的结构一致。
例如,函数声明如下:
DEFINE INPUT TABLE user_info (
user_id BIGINT
);调用请求为:
curl -X POST http://localhost:30001/api/v1/recommend \
-H 'Content-Type: application/json' \
-d '{
"data": {
"user_info": [
{"user_id": 1000001}
]
}
}'服务开启 AUTH_ENABLED 后,在 curl 中增加 --user sqlrec,按提示输入密码;使用 AUTH_USERNAME 中的一个账号及其对应密码,不发送逗号列表。缺少或错误凭证返回 HTTP 401。配置和 JDBC 接入见入口认证。
函数有多个输入表时,把它们分别放入 data:
{
"data": {
"user_info": [{"user_id": 1000001}],
"context": [{"page": "home"}]
}
}传递执行参数
params 适合传递返回数量、实验分组、动态函数名等请求级配置。值必须是字符串,可在 SQL 中通过 `get` 读取:
{
"data": {
"user_info": [{"user_id": 1000001}]
},
"params": {
"limit_count": "10",
"experiment": "rank_v2"
}
}SELECT CAST(`get`('limit_count', '50') AS INT);读取响应
调用成功时,data 是函数 RETURN 的结果行,默认包含的 params 是执行结束时的显式变量。设置服务环境变量 EXECUTE_RESULT_INCLUDE_PARAMS=false 并重启后,SQL 和函数 API 的 JSON 响应均省略 params:
{
"data": [
{"item_id": 2001, "score": 0.96},
{"item_id": 2002, "score": 0.91}
],
"params": {
"limit_count": "10"
}
}正常执行返回 HTTP 200。结果行为空时 data 是空数组;函数正常结束但没有返回表时,msg 给出说明。请求格式错误返回 HTTP 400,函数执行失败返回 HTTP 500,错误原因在 msg 中。
调用方应先检查 HTTP 状态码,再读取结果或错误说明。路径不匹配返回 404,方法不支持返回 405。
需要按场景或实验分组查看指标时,可在 params 中传入 scene、experiment 等变量,再由运维配置 METRICS_TAG_KEYS。配置方法见可观测性。
常见问题
提示输入表不存在
检查 data 中的键是否与 DEFINE INPUT TABLE 的表名完全一致。所有声明的输入表都必须出现;没有数据时也应传入空数组。
字段转换失败
检查字段名和 JSON 值是否符合函数声明的数据类型,尤其是数值、数组和时间字段。
API 找不到
确认请求路径中的名称与 API 定义一致:/api/v1/{api_name},并检查定义是否已按发布函数中的说明加载。
/sql/v1 和 /api/v1 有什么区别
/api/v1/{api_name} 调用已发布的业务函数,是业务接入的推荐方式。/sql/v1 用于直接提交 SQL,是否开放由服务配置决定,不应作为普通业务 API 使用。
API 的完整定义语法见 SQL 语法参考。