SQLRec SQL 语法参考
本文档介绍 SQLRec 支持的扩展 SQL 语法。普通 SELECT、INSERT 和建表操作可从编写推荐流程与接入数据源入手。
按任务查找:
| 你要做什么 | 从这里开始 |
|---|---|
| 定义和管理 SQL 函数 | CREATE SQL FUNCTION、SHOW SQL FUNCTIONS |
| 编写推荐流程 | DEFINE INPUT TABLE、CACHE TABLE、CALL、IF、ASSERT、RETURN |
| 设置和读取执行变量 | SET、GET |
| 发布和管理 API | CREATE API、SHOW APIS |
| 定义、训练和导出模型 | CREATE MODEL、TRAIN MODEL、EXPORT MODEL、SHOW CHECKPOINTS |
| 部署和管理模型服务 | CREATE SERVICE、SHOW SERVICES |
| 了解表、库和 UDF 的 DDL 支持范围 | 元数据 DDL |
| 查看数据库、表结构和 UDF | 元数据查询 |
| 刷新进程内定义缓存 | FLUSH |
SQL 函数管理
CREATE SQL FUNCTION
创建一个自定义 SQL 函数。
语法:
CREATE [OR REPLACE] SQL FUNCTION function_name描述:
此语句开始一个函数定义块,后续需要输入函数体的 SQL 语句,直到函数编译完成。
参数:
| 参数 | 描述 |
|---|---|
OR REPLACE | 可选。如果函数已存在,则替换现有定义 |
function_name | 函数名称 |
示例:
CREATE SQL FUNCTION my_function;
CREATE OR REPLACE SQL FUNCTION my_function;DROP SQL FUNCTION
删除一个已存在的 SQL 函数。对象不存在时,IF EXISTS 可避免报错。
DROP SQL FUNCTION [IF EXISTS] function_name;注意: 如果函数被 API 引用,则无法删除。
SHOW SQL FUNCTIONS
显示所有 SQL 函数列表。
SHOW SQL FUNCTIONS;DESCRIBE SQL FUNCTION
显示 SQL 函数的创建语句。
语法:
{DESCRIBE | DESC} SQL FUNCTION function_name参数:
| 参数 | 描述 |
|---|---|
function_name | 函数名称 |
示例:
DESCRIBE SQL FUNCTION my_function;
DESC SQL FUNCTION my_function;推荐流程语句
DEFINE INPUT TABLE
定义一个输入表的结构,用于在 SQL 函数中声明输入参数的表结构。
语法:
DEFINE INPUT TABLE table_name (
column_name1 column_type1,
column_name2 column_type2,
...
)
-- 或者使用 LIKE 子句复制已有表的结构
DEFINE INPUT TABLE table_name LIKE existing_table参数:
| 参数 | 描述 |
|---|---|
table_name | 输入表名称 |
column_name | 列名 |
column_type | 列数据类型 |
existing_table | 已存在的表名,用于复制其表结构 |
描述:
DEFINE INPUT TABLE 支持两种方式定义输入表结构:
- 显式定义:直接指定列名和列类型
- LIKE 子句:复制已有表的结构,包括所有列名和类型
示例:
-- 显式定义列
DEFINE INPUT TABLE input_data (
id INT,
name VARCHAR(100),
score DOUBLE,
created_at TIMESTAMP
);
-- 使用 LIKE 子句复制表结构
DEFINE INPUT TABLE input_data LIKE source_table;CACHE TABLE
缓存查询结果或函数调用结果到指定表。
语法:
CACHE TABLE table_name AS
{CALL function_name([arg1, arg2, ...]) [LIKE {like_table | FUNCTION 'function_name'}] [PARTITION BY table_name SIZE partition_size]
| select_statement}参数:
| 参数 | 描述 |
|---|---|
table_name | 缓存表名称 |
function_name | 要调用的函数名称,可以是标识符或 GET() 表达式 |
arg1, arg2, ... | 函数参数,可以是标识符、GET() 表达式或字符串、数字、布尔字面量 |
like_table | 可选。指定结果表的模板表 |
FUNCTION 'function_name' | 可选。指定结果表的模式与某个函数的输出模式相同 |
PARTITION BY table_name SIZE partition_size | 可选。按指定输入表进行分区并发执行,table_name 必须是函数的输入表之一,partition_size 可为整数字面量或 get(),表示每个分区的最大行数 |
select_statement | SELECT 查询语句 |
缓存表名不区分大小写,创建时统一保存为小写;SQL 函数的输入表名使用相同规则,并按此规则检查重复声明。不同大小写的同名缓存写入会覆盖同一张表。表名引号内的空格属于名称的一部分,会保留。
示例:
CACHE TABLE cached_result AS
SELECT * FROM source_table WHERE status = 'active';
CACHE TABLE cached_result AS
CALL my_function('param1', 'param2');
CACHE TABLE cached_result AS
CALL my_function(GET('var1'), 'param2') LIKE template_table;
CACHE TABLE cached_result AS
CALL my_function(GET('var1'), 'param2') LIKE FUNCTION 'template_function';
CACHE TABLE cached_result AS
CALL my_function(t1) PARTITION BY t1 SIZE 100;
CACHE TABLE cached_result AS
CALL my_function(t1) LIKE t1 PARTITION BY t1 SIZE 100;注意
CACHE TABLE ... AS CALL 只支持同步调用。如需异步执行,请使用独立的 CALL ... ASYNC 语句。
CALL
调用 SQL 函数或已注册的 Java UDF。表函数的显式表参数必须是当前执行器中的 CacheTable;标量参数可直接传入字符串、数字或布尔字面量,或通过 GET() 获取。返回表结果时,若编译期无法推断模式,需要使用 LIKE table 或 LIKE FUNCTION。
Java 标量参数支持 String、Integer、Long、Double、Boolean 及对应基本类型。重载优先选择精确类型,整数可以向 BIGINT、DOUBLE 扩展。通过 GET 传入数字或布尔参数时,需要提供对应类型的默认值;这些位置暂不支持任意表达式。
未通过 LIKE 指定返回模式时,默认在编译期调用返回 CacheTable 的 Java 方法来推断模式。启动服务前设置环境变量 ENABLE_JAVA_FUNCTION_SCHEMA_INFERENCE=false 可关闭此调用;SQL SET 和请求 params 不能覆盖该配置。关闭后,调用返回 CacheTable 的 Java 方法必须通过 LIKE table 或 LIKE FUNCTION 显式指定模式,否则编译时直接报错,不调用方法。返回 void 的方法无需指定模式。
语法:
CALL function_name([arg1, arg2, ...]) [LIKE {like_table | FUNCTION 'function_name'}] [PARTITION BY table_name SIZE partition_size] [ASYNC]参数:
| 参数 | 描述 |
|---|---|
function_name | 函数名称,可以是标识符或 GET() 表达式 |
arg1, arg2, ... | 函数参数,可以是标识符、GET() 表达式或字符串、数字、布尔字面量 |
like_table | 可选。指定结果表的模板表 |
FUNCTION 'function_name' | 可选。指定结果表的模式与某个函数的输出模式相同 |
PARTITION BY table_name SIZE partition_size | 可选。按指定输入表进行分区并发执行,table_name 必须是函数的输入表之一,partition_size 可为整数字面量或 get(),表示每个分区的最大行数 |
ASYNC | 可选。异步执行 |
ASYNC 仅提交后台任务并立即返回,不提供可同步消费的结果,因此不能放在 CACHE TABLE ... AS CALL 或 RETURN CALL 中。PARTITION BY 会按输入缓存表分区并发调用,通常应配合 LIKE 显式声明合并结果的模式;ASYNC 必须放在语句末尾。
SQL 函数调用指定 LIKE 时,实际输出必须满足声明的列数、列名、顺序、完整字段类型和可空性约束。静态调用在编译时检查,动态调用在解析目标函数后、执行前检查;不匹配会报错。
示例:
CALL my_function('param1', 'param2');
CALL my_function(GET('var1'), 'param2') LIKE template_table;
CALL my_function(GET('var1'), 'param2') LIKE FUNCTION 'template_function';
CALL my_function('param1') ASYNC;
CALL GET('fun1')(GET('id'), t1, '10') LIKE t1;
CALL my_function(t1) PARTITION BY t1 SIZE 100;
CALL my_function(t1) LIKE t1 PARTITION BY t1 SIZE 100 ASYNC;IF
条件执行语句。
语法:
IF [TIMEIN] (condition) THEN (statement) [ELSE (statement)]参数:
| 参数 | 描述 |
|---|---|
TIMEIN | 可选。指定为超时模式,条件返回超时时间(毫秒) |
condition | 条件表达式。普通模式返回布尔值,超时模式返回数值(毫秒) |
statement | 可执行语句:CACHE TABLE、SELECT/INSERT/UPDATE/DELETE、ASSERT、CALL、SET 或 RETURN |
ELSE | 可选。普通模式下可选,超时模式下必需 |
描述:
IF 语句支持两种执行模式:
- 普通模式:评估条件表达式,如果返回 true 则执行 THEN 子句,否则执行 ELSE 子句(如果存在)
- 超时模式(TIMEIN):条件表达式必须返回数值类型的 THEN 执行时间预算(毫秒)
- 如果超时时间 > 0,执行 THEN 子句并设置超时;如果超时则回退到 ELSE 子句
- 如果时间预算 <= 0,跳过 THEN,直接执行 ELSE
- THEN 超时或执行失败时使用 ELSE 的结果,不返回失败分支的中间结果
注意:
- 条件查询必须恰好返回一行一列。普通模式下该值必须是 BOOLEAN(NULL 按 false 处理);TIMEIN 模式下必须是数值。
- THEN 和 ELSE 子句必须同为 CACHE 语句,或同为非 CACHE 语句,不允许混用
- 两分支均为 CACHE 语句时:必须写入相同的表名,且表结构必须兼容
- IF 的结果结构合并所有可能分支的可空性和类型长度;无 ELSE 且可能保留已有缓存时,也合并已有缓存的结构。函数的多处 RETURN 使用同样的合并规则。
- 两分支均为非 CACHE 语句时:两个分支的返回字段结构必须兼容
- IF 包含
RETURN时,仅支持两种结构:THEN 返回且没有 ELSE;或者 THEN 和 ELSE 都返回。不能只在 ELSE 返回,也不能将返回分支与非返回 ELSE 混用 - 两个分支都返回时,返回模式必须兼容;该 IF 后必须立即以一条空
RETURN;结束函数定义,不能再写其他语句。函数结果模式由两个分支推导,不受末尾空 RETURN 影响 - THEN 返回且没有 ELSE 时,如果条件为 false,函数继续执行 IF 后面的语句
- TIMEIN 模式必须提供 ELSE;两个分支必须同为 CACHE,或同为 RETURN
- TIMEIN 超时或失败后,THEN 的迟到结果不会覆盖 ELSE。
- 请求已取消时终止执行,不再降级到 ELSE;请求仍有效时,THEN 的异常、Error 和中断均可触发 ELSE。
- TIMEIN 的非正数预算表示直接降级;
NODE_EXEC_TIMEOUT <= 0仍表示不设置节点超时,两者含义不同 - 当前不支持在 THEN 或 ELSE 中直接嵌套另一个 IF
- 无 ELSE 子句且条件为 false 时:若 THEN 子句为 CACHE 语句,对应的缓存表会被注册为空表(若尚不存在),保证后续语句可正常引用
示例:
IF (SELECT COUNT(*) > 100 FROM source_table) THEN (
CACHE TABLE result_table AS SELECT * FROM source_table
) ELSE (
CACHE TABLE result_table AS SELECT * FROM backup_table
);
IF TIMEIN (SELECT timeout_ms FROM config_table) THEN (
CACHE TABLE result_table AS CALL slow_function('param')
) ELSE (
CACHE TABLE result_table AS SELECT * FROM default_table
);
-- 分支为任意可执行语句
IF (SELECT COUNT(*) > 0 FROM source_table) THEN (
SELECT * FROM source_table
) ELSE (
SELECT * FROM backup_table
);
IF (SELECT COUNT(*) > 0 FROM source_table) THEN (
ASSERT SELECT COUNT(*) > 0 FROM source_table
);
-- SQL 函数中提前返回:无 ELSE 时,条件为 false 会继续执行
IF (SELECT COUNT(*) = 0 FROM source_table) THEN (
RETURN SELECT CAST(NULL AS BIGINT) AS id LIMIT 0
);
RETURN SELECT id FROM source_table;
-- 两个分支都返回,且返回模式一致
IF (SELECT use_primary FROM config_table) THEN (
RETURN SELECT id, score FROM primary_result
) ELSE (
RETURN SELECT id, score FROM fallback_result
);
-- 两个分支已覆盖全部路径;紧随其后的空 RETURN 只结束函数定义
RETURN;
-- TIMEIN 同样支持 RETURN;超时或异常时执行 ELSE
IF TIMEIN (SELECT 1000) THEN (
RETURN SELECT id, score FROM slow_result
) ELSE (
RETURN SELECT id, score FROM fallback_result
);
RETURN;ASSERT
执行 SELECT 查询并断言结果为真。如果查询结果的任何字段不为 true,则抛出异常中止执行。
语法:
ASSERT select_statement参数:
| 参数 | 描述 |
|---|---|
select_statement | SELECT 查询语句,返回的字段必须全部为布尔类型 |
描述:
ASSERT 语句执行指定的 SELECT 查询,并对返回结果进行断言校验:
- 查询返回的字段必须全部为布尔(BOOLEAN)类型,否则在编译期抛出异常
- 查询必须至少返回一行数据,否则抛出异常
- 每一行、每一列的值必须为
true,若存在false或null值则抛出异常
注意:
- ASSERT 算子不支持并发执行
- 断言失败时会抛出
RuntimeException,包含失败的具体行号、列名和列号信息
示例:
ASSERT SELECT COUNT(*) > 0 FROM source_table;
ASSERT SELECT COUNT(*) > 100 FROM source_table WHERE status = 'active';
ASSERT SELECT COUNT(*) > 0, COUNT(*) >= 10 FROM source_table;可以使用列别名标识断言。失败信息会包含对应列名和位置,便于定位:
ASSERT SELECT COUNT(*) > 0 AS has_candidates FROM items;RETURN
从 SQL 函数中返回结果并提前结束本次函数执行。RETURN 可以直接返回缓存表,也可以执行 SELECT 或同步 CALL 并返回其结果。
语法:
RETURN
RETURN table_name
RETURN select_statement
RETURN CALL function_name([arg1, arg2, ...]) [LIKE {like_table | FUNCTION 'function_name'}] [PARTITION BY table_name SIZE partition_size]参数:
| 参数 | 描述 |
|---|---|
table_name | 要返回的缓存表(CacheTable)名称,不能是普通外部表 |
select_statement | 作为函数结果返回的 SELECT 查询 |
CALL ... | 调用 SQL/Java 函数并返回其结果;动态调用仍需通过 LIKE 指定返回模式 |
规则:
RETURN;表示函数正常结束但不返回数据。- 顶层
RETURN是 SQL 函数定义的结束标志;即使函数体中的IF已包含提前返回,函数定义仍需以顶层RETURN结束。顶层RETURN之后不能再定义其他函数体语句。 IF分支内的RETURN只在运行时提前结束函数,不会在编译时结束函数定义。- 如果 IF 只有 THEN 分支返回,条件为 false 时仍会继续执行;末尾顶层
RETURN是该路径的实际返回点,必须与 THEN 的返回模式兼容。 - 如果 IF 的 THEN 和 ELSE 都是
RETURN,IF 已覆盖所有运行路径。该 IF 后必须立即且只能写一条不携带数据的RETURN;作为函数定义结束标志;不能插入其他语句,也不能改写为RETURN table_name、RETURN SELECT ...或RETURN CALL ...。这条空 RETURN 不参与返回模式推导。 - 函数内所有可能执行的返回点必须具有一致的返回模式:要么全部为空返回,要么全部返回列数、列名和列类型一致的数据。上述双分支场景中的末尾空 RETURN 只是编译结束标志,不属于运行时返回点。
RETURN CALL ... ASYNC不受支持,因为异步调用无法作为当前函数的同步返回值。
示例:
-- 空返回
RETURN;
-- 返回已有缓存表
RETURN result_table;
-- 直接返回查询结果,无需先创建匿名缓存表
RETURN SELECT id, score FROM candidates ORDER BY score DESC;
-- 返回函数调用结果
RETURN CALL rerank(candidates);
-- IF 中提前返回;最后一条顶层 RETURN 仍是函数定义结束标志,
-- 并在条件为 false 时作为后备返回
IF (SELECT COUNT(*) = 0 FROM candidates) THEN (
RETURN SELECT CAST(NULL AS BIGINT) AS id LIMIT 0
);
RETURN SELECT id FROM candidates;执行变量
SET
设置当前执行上下文中的字符串变量。SQL 函数可以通过 `get` 读取变量。
在 Thrift 会话中,顶层 SET 'key' = 'value' 还会保存会话设置,无需连接 Gateway;设置在下一次远程 SQL 执行前同步到 Gateway,本地保存成功不代表远程验证成功。无赋值的 SET(如 SET;)查询 Flink 配置,仍需 Gateway。RESET 或 RESET 'key' 经 Gateway 确认成功后才清除本地保存的全部或指定会话设置;转发禁用或远程执行失败时,原设置保持不变。REST/CLI 不提供透明 Gateway 转发,详见执行边界。
语法:
SET 'variable_name' = 'value'示例:
SET 'rank_fun' = 'rank_fun_simple';
SET 'limit_count' = '10';
SELECT `get`('rank_fun');
SELECT CAST(`get`('limit_count', '50') AS INT);API 请求体中 params 对象的键值也会作为执行变量。变量值为字符串;用作数字或布尔值时,可在标量函数 get 中提供相应类型的默认值,或显式转换。
读取不存在的执行变量时,默认回退到同名环境变量;显式空字符串不回退。通过服务环境变量 ENABLE_VARIABLE_ENV_FALLBACK=false 可关闭该行为。环境变量值不会写入执行变量集合。
GET
在 CALL 的动态函数名、Java 表函数的标量参数或 PARTITION BY ... SIZE 中读取执行变量。GET 是这些位置可用的语法,不是独立的 SQL 语句;调用 SQL 函数时,表参数仍须直接写缓存表名。
语法:
GET('variable_name')
GET('variable_name', 'default_value')参数:
| 参数 | 描述 |
|---|---|
variable_name | 变量名称,必须是字符串字面量 |
default_value | 可选,变量不存在时使用,可以是字符串、数字或布尔字面量;其类型决定 Java 参数类型,省略时按 VARCHAR 处理 |
示例:
SET 'rank_fun' = 'default_rank';
CALL GET('rank_fun')(input_table) LIKE FUNCTION 'default_rank';
CALL GET('rank_fun', 'default_rank')(input_table)
LIKE FUNCTION 'default_rank';在 SELECT 等普通 SQL 表达式中,使用标量函数 `get`('variable_name') 或 `get`('variable_name', 'default_value');写法和适用位置见标量函数。
API 管理
CREATE API
创建一个 API 接口,关联到指定的 SQL 函数。
语法:
CREATE [OR REPLACE] API api_name WITH function_name参数:
| 参数 | 描述 |
|---|---|
OR REPLACE | 可选。如果 API 已存在,则替换现有定义 |
api_name | API 名称 |
function_name | 关联的 SQL 函数名称 |
示例:
CREATE API my_api WITH my_function;
CREATE OR REPLACE API my_api WITH my_function;DROP API
删除一个已存在的 API。对象不存在时,IF EXISTS 可避免报错。
DROP API [IF EXISTS] api_name;SHOW APIS
显示所有 API 列表。
SHOW APIS;DESCRIBE API
显示 API 的创建语句。
语法:
{DESCRIBE | DESC} API api_name参数:
| 参数 | 描述 |
|---|---|
api_name | API 名称 |
示例:
DESCRIBE API my_api;
DESC API my_api;模型与 Checkpoint
CREATE MODEL
创建一个新的机器学习模型定义。
语法:
CREATE MODEL [IF NOT EXISTS] model_name
[(column_name column_type [, ...])]
[WITH ('property_name' = 'property_value' [, ...])]参数:
| 参数 | 描述 |
|---|---|
IF NOT EXISTS | 可选。如果模型已存在,则不创建新模型,也不报错 |
model_name | 模型名称,必须是有效的标识符 |
column_name | 列名 |
column_type | 列数据类型 |
property_name | 属性名 |
property_value | 属性值 |
示例:
CREATE MODEL rank_model (
user_id BIGINT,
item_id BIGINT,
price DOUBLE,
is_click INT
) WITH (
'model' = 'tzrec.wide_and_deep',
'label_columns' = 'is_click'
);
CREATE MODEL IF NOT EXISTS external_rank_model WITH (
'model' = 'external',
'output_columns' = 'score:FLOAT'
);DROP MODEL
删除一个已存在的模型。对象不存在时,IF EXISTS 可避免报错。
DROP MODEL [IF EXISTS] model_name;TRAIN MODEL
训练或下载模型并创建检查点。
训练型后端需要 ON 数据表;Hugging Face 后端用 TRAIN MODEL 下载模型,不需要 ON。后端差异见模型指南。
同名检查点采用幂等重试:运行中或已成功的任务直接返回已有检查点;失败任务会停止并清理旧 Kubernetes 资源,保留模型存储目录和检查点记录后重新提交。TZRec 从目录内已有的保存点续训;其他后端是否恢复训练进度由其训练入口决定。重试时应保持训练数据和配置一致。需要重新训练、修改参数或增加训练轮数时,使用新的检查点名称,可通过 FROM 指定已有模型。
语法:
TRAIN MODEL model_name CHECKPOINT = 'checkpoint_name'
[ON data_source]
[WHERE condition]
[FROM 'existing_checkpoint']
[WITH ('property_name' = 'property_value' [, ...])]参数:
| 参数 | 描述 |
|---|---|
model_name | 要训练的模型名称 |
checkpoint_name | 检查点名称,用于标识训练结果 |
data_source | 训练数据表;训练型后端必填,Hugging Face 下载模型时不需要 |
condition | 可选。WHERE 条件,用于过滤训练数据 |
existing_checkpoint | 可选。基于已有检查点继续训练 |
property_name | 可选。训练属性名 |
property_value | 可选。训练属性值 |
示例:
TRAIN MODEL my_model CHECKPOINT = 'v1.0'
ON training_data
WHERE status = 'active';
TRAIN MODEL my_model CHECKPOINT = 'v2.0'
ON training_data
FROM 'v1.0'
WITH ('num_epochs' = '10', 'sparse_lr' = '0.01');EXPORT MODEL
导出模型的训练结果。
ON 指定导出过程读取的数据表,不是模型产物的写入目标。模型产物保存在配置的模型存储中,格式由模型后端决定。
语法:
EXPORT MODEL model_name CHECKPOINT = 'checkpoint_name'
[ON data_source]
[WHERE condition]
[WITH ('property_name' = 'property_value' [, ...])]参数:
| 参数 | 描述 |
|---|---|
model_name | 要导出的模型名称 |
checkpoint_name | 检查点名称 |
data_source | 可选。导出过程读取的数据表,是否需要由模型后端决定 |
condition | 可选。WHERE 条件 |
property_name | 可选。导出属性名 |
property_value | 可选。导出属性值 |
示例:
EXPORT MODEL my_model CHECKPOINT = 'v1.0'
ON export_table;
EXPORT MODEL my_model CHECKPOINT = 'v1.0'
ON export_table
WHERE status = 'valid';SHOW MODELS
显示所有模型列表。
SHOW MODELS;DESCRIBE MODEL
显示模型的创建语句或检查点信息。
语法:
{DESCRIBE | DESC} [FORMATTED] MODEL model_name [CHECKPOINT = 'checkpoint_name']参数:
| 参数 | 描述 |
|---|---|
FORMATTED | 可选。以格式化表格形式显示详细信息,包括模型信息、输入字段、输出字段和模型参数 |
model_name | 模型名称 |
checkpoint_name | 可选。检查点名称,如果指定则显示该检查点的详细信息 |
示例:
DESCRIBE MODEL my_model;
DESC MODEL my_model CHECKPOINT = 'v1.0';
DESCRIBE FORMATTED MODEL my_model;
DESCRIBE FORMATTED MODEL my_model CHECKPOINT = 'v1.0';SHOW CHECKPOINTS
显示指定模型的所有检查点列表。
SHOW CHECKPOINTS model_name;ALTER MODEL DROP CHECKPOINT
删除模型的指定检查点。
语法:
ALTER MODEL model_name DROP [IF EXISTS] CHECKPOINT = 'checkpoint_name'参数:
| 参数 | 描述 |
|---|---|
model_name | 模型名称 |
IF EXISTS | 可选。如果检查点不存在,则不报错 |
checkpoint_name | 要删除的检查点名称 |
示例:
ALTER MODEL my_model DROP CHECKPOINT = 'v1.0';
ALTER MODEL my_model DROP IF EXISTS CHECKPOINT = 'v1.0';模型服务管理
CREATE SERVICE
创建一个模型服务。
语法:
CREATE SERVICE [IF NOT EXISTS] service_name
ON MODEL model_name
[CHECKPOINT = 'checkpoint_name']
[WITH ('property_name' = 'property_value' [, ...])]参数:
| 参数 | 描述 |
|---|---|
IF NOT EXISTS | 可选。名称须先通过校验;如果服务已存在,则不创建新服务,也不报错 |
service_name | 与 Kubernetes Service 的 DNS(RFC 1035)命名规则一致:仅允许小写字母、数字和连字符 -;长度为 1~63,以小写字母开头,以小写字母或数字结尾 |
model_name | 关联的模型名称 |
checkpoint_name | 可选。使用的检查点名称 |
property_name | 可选。服务属性名 |
property_value | 可选。服务属性值 |
示例:
CREATE SERVICE `rank-service`
ON MODEL rank_model
CHECKPOINT = 'v1.0_export';
CREATE SERVICE IF NOT EXISTS `external-rank-service`
ON MODEL external_rank_model
WITH ('url' = 'http://rank-service:8080/predict');名称限制遵循 Kubernetes Service 的 DNS 命名规则。大写字母、下划线、点号、空格等均会报错,不自动转换大小写;IF NOT EXISTS 也必须通过名称校验。含连字符的名称须用反引号包裹。自托管服务直接使用服务名作为 Kubernetes Service 和 Deployment 名称,不追加哈希后缀;URL 为 http://<service-name>.<namespace>.svc.cluster.local:80/predict。非法名称直接报错,不自动替换或截断。此名称校验也适用于 external 服务。
服务定义在 Kubernetes 提交成功后保存,提交失败不会覆盖已有定义。提交成功不代表工作负载已就绪,调用前仍需检查状态。更新或重试已有定义时不带 IF NOT EXISTS;该选项会跳过已有记录。
DROP SERVICE
删除一个已存在的服务。对象不存在时,IF EXISTS 可避免报错。
DROP SERVICE [IF EXISTS] service_name;SHOW SERVICES
显示所有服务列表。
SHOW SERVICES;DESCRIBE SERVICE
显示服务的创建语句。
语法:
{DESCRIBE | DESC} [FORMATTED] SERVICE service_name参数:
| 参数 | 描述 |
|---|---|
FORMATTED | 可选。以格式化表格形式显示详细信息,包括服务信息、关联模型信息和模型字段 |
service_name | 服务名称 |
示例:
DESCRIBE SERVICE `my-service`;
DESC SERVICE `my-service`;
DESCRIBE FORMATTED SERVICE `my-service`;元数据 DDL
| 模式 | 定义存放位置 | 运行时 DDL |
|---|---|---|
| 远程元数据 | 库、表、Java UDF 在 HMS;SQLRec 资源在 PostgreSQL | 通过 Beeline/JDBC 执行持久化 DDL |
| SQL 文件 | 启动时加载 SQL_SCHEMA_DIR 下的文件 | 默认关闭;SQL_SCHEMA_DDL_ENABLED=true 开启支持的内存 DDL |
文件模式的 DDL 在同一进程的会话间共享,不回写文件,重启后恢复文件定义,不跨实例同步。Demo 镜像已开启该选项;需在启动前配置,SQL SET 不能改变它。
文件模式支持库的 CREATE/ALTER SET/DROP、表的 CREATE/CREATE LIKE/ALTER/DROP,以及持久 Java UDF、SQL 函数和 API 的创建、删除;语法支持时可替换。模型、Service、Checkpoint、训练和导出命令仍不能在运行时执行。
库、表及 UDF 定义使用 Flink 1.19 default 方言。表支持普通列、metadata 列、主键及分区键声明。文件模式不支持计算列、WATERMARK、临时表、CTAS/RTAS、视图、分区实例修改和跨库重命名。库删除支持 RESTRICT/CASCADE,不能删除当前库和默认库。数据库 DDL 变更后,其他已有会话查询新库前可能需要重新连接。
远程模式的持久元数据 DDL 不需要 Gateway;临时函数、视图及持久表 CTAS/RTAS 通过 Thrift 远程转发。不支持 USE CATALOG 和临时表。USE database 不立即校验库是否存在,后续操作按实际元数据执行,见执行边界。
保存表或 UDF 定义不代表本地引擎支持对应能力。Connector/UDF JAR 需另行部署,SQLRec 不自动下载 UDF 资源。
元数据查询
两种模式均支持 SHOW DATABASES、SHOW TABLES、SHOW CREATE TABLE、DESCRIBE、SHOW FUNCTIONS、SHOW USER FUNCTIONS,无需 Gateway。文件模式查看定义不依赖 HMS,也不要求对应 Connector/UDF 类可用。
- 表名支持
table、database.table、hive.database.table;未限定数据库时优先匹配会话CACHE TABLE。 SHOW TABLES包含当前库的会话缓存表,可用LIKE、NOT LIKE筛选名称。SHOW USER FUNCTIONS列出已声明的 Java UDF;SHOW FUNCTIONS还含 Flink 内置函数,支持 LIKE/ILIKE 及其 NOT 形式。被列出的函数不一定能本地执行;SQL 函数使用SHOW SQL FUNCTIONS。SHOW CREATE TABLE返回规范化 DDL,主键列包含 NOT NULL;列注释不保证在往返转换中保留。- 持久表
DESCRIBE返回name、type、null、key、extras、watermark,存在注释时追加comment;缓存表返回name、type。
SQL 文件按路径排序加载,CREATE TABLE ... LIKE 的源表须先定义。修改文件需要重启,FLUSH 不重新读取文件。
元数据刷新
DDL 保留未变化表的内存数据。ALTER、RENAME 可能重置目标表的运行时数据;DROP 后重建同名表会创建新对象。
FLUSH
FLUSH;使当前进程的表、Java/SQL 函数、API、服务配置等定义缓存失效。后续访问重建 Connector 表对象,Filesystem 运行时写入会重置;会话 CACHE TABLE 及文件模式的内存 DDL 修改保留。
通常在外部修改元数据后使用。它不重新读取 SQL 文件,也不为已有会话增加数据库;新库不能用于本地查询时应重新连接。缓存范围见架构说明。