Skip to content

SQLRec SQL 语法参考 ​

本文档介绍 SQLRec 支持的扩展 SQL 语法。普通 SELECT、INSERT 和建表操作可从编写推荐流程与接入数据源入手。

按任务查找:

你要做什么从这里开始
定义和管理 SQL 函数CREATE SQL FUNCTION、SHOW SQL FUNCTIONS
编写推荐流程DEFINE INPUT TABLE、CACHE TABLE、CALL、IF、ASSERT、RETURN
设置和读取执行变量SET、GET
发布和管理 APICREATE 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 函数。

语法:

sql
CREATE [OR REPLACE] SQL FUNCTION function_name

描述:

此语句开始一个函数定义块,后续需要输入函数体的 SQL 语句,直到函数编译完成。

参数:

参数描述
OR REPLACE可选。如果函数已存在,则替换现有定义
function_name函数名称

示例:

sql
CREATE SQL FUNCTION my_function;

CREATE OR REPLACE SQL FUNCTION my_function;

DROP SQL FUNCTION ​

删除一个已存在的 SQL 函数。对象不存在时,IF EXISTS 可避免报错。

sql
DROP SQL FUNCTION [IF EXISTS] function_name;

注意: 如果函数被 API 引用,则无法删除。

SHOW SQL FUNCTIONS ​

显示所有 SQL 函数列表。

sql
SHOW SQL FUNCTIONS;

DESCRIBE SQL FUNCTION ​

显示 SQL 函数的创建语句。

语法:

sql
{DESCRIBE | DESC} SQL FUNCTION function_name

参数:

参数描述
function_name函数名称

示例:

sql
DESCRIBE SQL FUNCTION my_function;

DESC SQL FUNCTION my_function;

推荐流程语句 ​

DEFINE INPUT TABLE ​

定义一个输入表的结构,用于在 SQL 函数中声明输入参数的表结构。

语法:

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 支持两种方式定义输入表结构:

  1. 显式定义:直接指定列名和列类型
  2. LIKE 子句:复制已有表的结构,包括所有列名和类型

示例:

sql
-- 显式定义列
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 ​

缓存查询结果或函数调用结果到指定表。

语法:

sql
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_statementSELECT 查询语句

缓存表名不区分大小写,创建时统一保存为小写;SQL 函数的输入表名使用相同规则,并按此规则检查重复声明。不同大小写的同名缓存写入会覆盖同一张表。表名引号内的空格属于名称的一部分,会保留。

示例:

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 的方法无需指定模式。

语法:

sql
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 时,实际输出必须满足声明的列数、列名、顺序、完整字段类型和可空性约束。静态调用在编译时检查,动态调用在解析目标函数后、执行前检查;不匹配会报错。

示例:

sql
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 ​

条件执行语句。

语法:

sql
IF [TIMEIN] (condition) THEN (statement) [ELSE (statement)]

参数:

参数描述
TIMEIN可选。指定为超时模式,条件返回超时时间(毫秒)
condition条件表达式。普通模式返回布尔值,超时模式返回数值(毫秒)
statement可执行语句:CACHE TABLE、SELECT/INSERT/UPDATE/DELETE、ASSERT、CALL、SET 或 RETURN
ELSE可选。普通模式下可选,超时模式下必需

描述:

IF 语句支持两种执行模式:

  1. 普通模式:评估条件表达式,如果返回 true 则执行 THEN 子句,否则执行 ELSE 子句(如果存在)
  2. 超时模式(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 语句,对应的缓存表会被注册为空表(若尚不存在),保证后续语句可正常引用

示例:

sql
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,则抛出异常中止执行。

语法:

sql
ASSERT select_statement

参数:

参数描述
select_statementSELECT 查询语句,返回的字段必须全部为布尔类型

描述:

ASSERT 语句执行指定的 SELECT 查询,并对返回结果进行断言校验:

  1. 查询返回的字段必须全部为布尔(BOOLEAN)类型,否则在编译期抛出异常
  2. 查询必须至少返回一行数据,否则抛出异常
  3. 每一行、每一列的值必须为 true,若存在 false 或 null 值则抛出异常

注意:

  • ASSERT 算子不支持并发执行
  • 断言失败时会抛出 RuntimeException,包含失败的具体行号、列名和列号信息

示例:

sql
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;

可以使用列别名标识断言。失败信息会包含对应列名和位置,便于定位:

sql
ASSERT SELECT COUNT(*) > 0 AS has_candidates FROM items;

RETURN ​

从 SQL 函数中返回结果并提前结束本次函数执行。RETURN 可以直接返回缓存表,也可以执行 SELECT 或同步 CALL 并返回其结果。

语法:

sql
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 不受支持,因为异步调用无法作为当前函数的同步返回值。

示例:

sql
-- 空返回
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 转发,详见执行边界。

语法:

sql
SET 'variable_name' = 'value'

示例:

sql
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 函数时,表参数仍须直接写缓存表名。

语法:

sql
GET('variable_name')
GET('variable_name', 'default_value')

参数:

参数描述
variable_name变量名称,必须是字符串字面量
default_value可选,变量不存在时使用,可以是字符串、数字或布尔字面量;其类型决定 Java 参数类型,省略时按 VARCHAR 处理

示例:

sql
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 函数。

语法:

sql
CREATE [OR REPLACE] API api_name WITH function_name

参数:

参数描述
OR REPLACE可选。如果 API 已存在,则替换现有定义
api_nameAPI 名称
function_name关联的 SQL 函数名称

示例:

sql
CREATE API my_api WITH my_function;

CREATE OR REPLACE API my_api WITH my_function;

DROP API ​

删除一个已存在的 API。对象不存在时,IF EXISTS 可避免报错。

sql
DROP API [IF EXISTS] api_name;

SHOW APIS ​

显示所有 API 列表。

sql
SHOW APIS;

DESCRIBE API ​

显示 API 的创建语句。

语法:

sql
{DESCRIBE | DESC} API api_name

参数:

参数描述
api_nameAPI 名称

示例:

sql
DESCRIBE API my_api;

DESC API my_api;

模型与 Checkpoint ​

CREATE MODEL ​

创建一个新的机器学习模型定义。

语法:

sql
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属性值

示例:

sql
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 可避免报错。

sql
DROP MODEL [IF EXISTS] model_name;

TRAIN MODEL ​

训练或下载模型并创建检查点。

训练型后端需要 ON 数据表;Hugging Face 后端用 TRAIN MODEL 下载模型,不需要 ON。后端差异见模型指南。

同名检查点采用幂等重试:运行中或已成功的任务直接返回已有检查点;失败任务会停止并清理旧 Kubernetes 资源,保留模型存储目录和检查点记录后重新提交。TZRec 从目录内已有的保存点续训;其他后端是否恢复训练进度由其训练入口决定。重试时应保持训练数据和配置一致。需要重新训练、修改参数或增加训练轮数时,使用新的检查点名称,可通过 FROM 指定已有模型。

语法:

sql
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可选。训练属性值

示例:

sql
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 指定导出过程读取的数据表,不是模型产物的写入目标。模型产物保存在配置的模型存储中,格式由模型后端决定。

语法:

sql
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可选。导出属性值

示例:

sql
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 ​

显示所有模型列表。

sql
SHOW MODELS;

DESCRIBE MODEL ​

显示模型的创建语句或检查点信息。

语法:

sql
{DESCRIBE | DESC} [FORMATTED] MODEL model_name [CHECKPOINT = 'checkpoint_name']

参数:

参数描述
FORMATTED可选。以格式化表格形式显示详细信息,包括模型信息、输入字段、输出字段和模型参数
model_name模型名称
checkpoint_name可选。检查点名称,如果指定则显示该检查点的详细信息

示例:

sql
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 ​

显示指定模型的所有检查点列表。

sql
SHOW CHECKPOINTS model_name;

ALTER MODEL DROP CHECKPOINT ​

删除模型的指定检查点。

语法:

sql
ALTER MODEL model_name DROP [IF EXISTS] CHECKPOINT = 'checkpoint_name'

参数:

参数描述
model_name模型名称
IF EXISTS可选。如果检查点不存在,则不报错
checkpoint_name要删除的检查点名称

示例:

sql
ALTER MODEL my_model DROP CHECKPOINT = 'v1.0';

ALTER MODEL my_model DROP IF EXISTS CHECKPOINT = 'v1.0';

模型服务管理 ​

CREATE SERVICE ​

创建一个模型服务。

语法:

sql
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可选。服务属性值

示例:

sql
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 可避免报错。

sql
DROP SERVICE [IF EXISTS] service_name;

SHOW SERVICES ​

显示所有服务列表。

sql
SHOW SERVICES;

DESCRIBE SERVICE ​

显示服务的创建语句。

语法:

sql
{DESCRIBE | DESC} [FORMATTED] SERVICE service_name

参数:

参数描述
FORMATTED可选。以格式化表格形式显示详细信息,包括服务信息、关联模型信息和模型字段
service_name服务名称

示例:

sql
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 ​

sql
FLUSH;

使当前进程的表、Java/SQL 函数、API、服务配置等定义缓存失效。后续访问重建 Connector 表对象,Filesystem 运行时写入会重置;会话 CACHE TABLE 及文件模式的内存 DDL 修改保留。

通常在外部修改元数据后使用。它不重新读取 SQL 文件,也不为已有会话增加数据库;新库不能用于本地查询时应重新连接。缓存范围见架构说明。