腾讯云数据仓库 TCHouse-X ML Functions 语

TCHouse-X ML Functions 语法介绍
本文档介绍 TCHouse-X 支持的机器学习能力，通过 SQL 接口实现模型训练、推理、评估及管理的全生命周期覆盖。
核心能力矩阵
TCHouse-X ML 能力围绕 3 类核心 SQL 接口展开：
接口类型
语法示例
描述
训练 (DDL)
`CREATE MODEL ... AS SELECT ...`
触发模型训练并自动在元数据中注册。
推理 (Scalar)
`ML_PREDICT(model, f0, ...)`
标量函数，支持嵌套在 `SELECT`、`WHERE` 等任意合法位置。
评估 (Agg)
`ML_EVALUATE(model, label, f0, ...)`
聚合函数，返回包含多个评估指标的 JSON 结果。
此外，提供 SHOW MODELS, DESCRIBE MODEL, DROP MODEL 等模型管理语句。
模型训练
CREATE MODEL — 创建/训练模型
语法：
CREATE MODEL <model_name>
MODEL_OPTIONS(
    label_column = '<label_col_name>',   -- 监督学习必填，无监督学习不可指定
    model_type = <model_type>,           -- 必填，模型类型
    [option1 = value1, ...]              -- 可选，模型超参数
)
AS <training_query>;
参数
是否必填
说明
model_name
必填
模型名称，唯一标识符。必填，在当前数据库中唯一，支持大小写字母、数字、下划线，长度 ≤ 1024。
model_type
必填
模型类型，见支持的模型类型。
label_column
监督学习必填
标签列名称，必须存在于训练查询的输出列中。
超参数
可选
模型特定的超参数，如max_iter、l1_ratio、n_clusters 等。
AS 
必填
训练集定义，支持所有 DQL 语句。
注意：目前仅支持数值类型列参与训练与推理。
支持的模型类型
模型类型
学习方式
Label 类型要求
说明
ml_linear_regression
监督学习
DOUBLE
线性回归，用于连续值预测
ml_gbdt
监督学习
INT
梯度提升决策树，用于分类任务
ml_gbrt
监督学习
DOUBLE
梯度提升回归树，用于回归任务
ml_kmeans
无监督学习
训练时不可指定 label_column，评估时 label_column 类型需是 INT
K-Means 聚类，需指定 n_clusters 参数
数据类型约束
Feature 列：支持浮点/整型。不支持 STRING、DECIMAL 等类型。
Label 列：类型必须与模型类型要求严格匹配（见上表）。例如 ml_linear_regression 要求 label 为 DOUBLE，传入 INT 会报错。
训练数据量：对于 KMeans 模型，训练数据行数必须 ≥ n_clusters，否则训练会失败。
示例
以下示例基于如下测试表：
-- 基础测试表
CREATE TABLE test (
    id INT,
    int_feature INT,
    double_feature DOUBLE,
    string_feature STRING,
    int_label INT,
    double_label DOUBLE
);
﻿
﻿
INSERT INTO test VALUES
(1, 10, 1.5, 'apple', 0, 0.1),
(2, 20, 2.5, 'banana', 1, 0.5),
(3, 30, 3.5, 'cherry', 0, 0.9),
(4, 40, 4.5, 'date', 1, 1.2);
﻿
-- 多类型测试表
CREATE TABLE test_data (
    id INT,
    int_feature INT,
    int_feature2 INT,
    double_feature DOUBLE,
    float_feature FLOAT,
    int_label INT,
    double_label DOUBLE
);
﻿
﻿
INSERT INTO test_data VALUES
(1, 100, 200, 1.1, 2.2, 0, 0.5),
(2, 150, 250, 3.3, 4.4, 1, 1.5),
(3, 200, 300, 5.5, 6.6, 0, 2.5),
(4, 250, 350, 7.7, 8.8, 1, 3.5);
线性回归模型（监督学习）：
-- 创建线性回归模型，label 列为 double_label（DOUBLE 类型）
CREATE MODEL test_model
MODEL_OPTIONS(label_column='double_label', model_type=ml_linear_regression)
AS SELECT double_label, double_feature, id, int_feature FROM test WHERE int_label < 10;
GBDT 分类模型（监督学习）：
-- 创建 GBDT 分类模型，label 列为 int_label（INT 类型）
CREATE MODEL gbdt_model
MODEL_OPTIONS(label_column='int_label', model_type=ml_gbdt)
AS SELECT int_label, int_feature, int_feature2, double_feature, float_feature
FROM test_data;
GBRT 回归模型（监督学习）：
-- 创建 GBRT 回归模型，label 列为 double_label（DOUBLE 类型）
CREATE MODEL gbrt_model
MODEL_OPTIONS(label_column='double_label', model_type=ml_gbrt)
AS SELECT double_label, int_feature, int_feature2, double_feature, float_feature
FROM test_data;
KMeans 聚类模型（无监督学习）：
-- 创建 KMeans 聚类模型，无需指定 label_column，必须指定 n_clusters
CREATE MODEL kmeans_model
MODEL_OPTIONS(model_type=ml_kmeans, n_clusters=3)
AS SELECT int_feature, int_feature2, double_feature, float_feature
FROM test_data;
训练查询支持表达式作为列：
-- label 列可以是表达式，通过 AS 指定别名
CREATE MODEL test_model2
MODEL_OPTIONS(label_column='tmp', model_type=ml_linear_regression)
AS SELECT double_feature, id, int_feature, (double_label + CAST(1.0 AS DOUBLE)) AS tmp FROM test;
CREATE OR REPLACE MODEL — 重新训练模型
使用 CREATE OR REPLACE MODEL 可以对已有模型进行重新训练，生成新版本。
语法：
CREATE OR REPLACE MODEL <model_name>
MODEL_OPTIONS(
    label_column = '<label_col_name>',
    model_type = <model_type>,
    [option1 = value1, ...]
)
AS <training_query>;
示例：
-- 重新训练模型，修改超参数（如 max_iter、l1_ratio）
CREATE OR REPLACE MODEL test_model
MODEL_OPTIONS(label_column='double_label', model_type=ml_linear_regression, max_iter=2000, l1_ratio=0.1)
AS SELECT double_label, double_feature, id, int_feature FROM test;
兼容性校验规则： CREATE OR REPLACE 时，系统会对新模型与已有模型进行兼容性校验，以下情况会报错：
1. model_type 不一致：新旧模型类型必须相同。例如不能将 ml_linear_regression 替换为 ml_gbrt。
2. Input Schema 列数不一致：新旧模型的 feature 列数量必须相同。
3. Input Schema 列类型不一致：新旧模型对应位置的 feature 列类型必须相同。
4. Label 类型约束：label 列类型仍需满足模型类型的要求（如 ml_linear_regression 要求 DOUBLE）。
注意：
超参数（如 max_iter、l1_ratio、n_clusters 等）的变化是允许的，不会触发兼容性校验错误。
模型管理
查看列表与定义
查看所有模型: SHOW MODELS
示例：
-- 查看当前数据库中所有模型
SHOW MODELS;
输出示例（每行一个模型名称）：
test_model
模型检查
使用 DESCRIBE 获取模型架构与元数据。
简要信息: DESCRIBE MODEL model_name; (展示名称、版本、Schema 等)
扩展信息: DESCRIBE MODEL EXTENDED model_name; (展示存储 URI、超参详情等)
示例：
-- 查看模型简要信息
DESCRIBE MODEL test_model;
输出示例（逗号分隔：模型名称, 模型类型, 最新版本号, Label 类型, Input Schema）：
test_model,ml_linear_regression,3,DOUBLE,[{"name":"f0","type":"DOUBLE"},{"name":"f1","type":"INT"},{"name":"f2","type":"INT"}]
-- 查看模型扩展信息（包含每个版本的存储 URI 和超参数详情）
DESCRIBE MODEL EXTENDED test_model;
输出示例（每行一个版本，逗号分隔：模型名称, 模型类型, 版本号, Label 类型, Input Schema, 模型 URI, 超参数 JSON）：
test_model,ml_linear_regression,1,DOUBLE,[{"name":"f0","type":"DOUBLE"},{"name":"f1","type":"INT"},{"name":"f2","type":"INT"}],runs:/xxx/model,{"penalty":"l2","l1_ratio":0.15,"max_iter":1000,...}
test_model,ml_linear_regression,2,DOUBLE,[{"name":"f0","type":"DOUBLE"},{"name":"f1","type":"INT"},{"name":"f2","type":"INT"}],runs:/xxx/model,{"penalty":"l2","l1_ratio":0.1,"max_iter":1000,...}
test_model,ml_linear_regression,3,DOUBLE,[{"name":"f0","type":"DOUBLE"},{"name":"f1","type":"INT"},{"name":"f2","type":"INT"}],runs:/xxx/model,{"penalty":"l2","l1_ratio":0.1,"max_iter":2000,...}
删除模型
DROP MODEL [IF EXISTS] model_name;
示例：
-- 删除模型（模型不存在时报错）
DROP MODEL test_model;
﻿
-- 删除模型（模型不存在时不报错）
DROP MODEL IF EXISTS test_model;
模型推理
ML_PREDICT 属于标量函数（Scalar Function），支持嵌入任何允许标量表达式的 SQL 子句中（如 SELECT、WHERE 或 ORDER BY）。其输入参数支持任意合法的 SQL 表达式，输出结果为模型生成的预测值。
语法：
-- 不指定版本（使用最新版本）
ML_PREDICT("<model_name>", feature_expr0, feature_expr1, ...)
﻿
-- 指定版本（第二个参数为正整数字面量）
ML_PREDICT("<model_name>", <version>, feature_expr0, feature_expr1, ...)
参数
是否必填
说明
model_name
必填
模型名称，STRING 类型（不能是表达式），需用双引号包裹
version
可选
模型版本号，必须为正整数字面量（如 1, 2, 3）。不支持 0、负数、浮点数、字符串。不指定时使用最新版本。
feature_expr
必填
特征列表达式，数量和类型必须与模型训练时的 feature 列一一对应
示例：
-- 使用最新版本进行预测
SELECT ML_PREDICT("test_model", double_feature, id, int_feature) FROM test;
﻿
-- 指定版本 1 进行预测
SELECT ML_PREDICT("test_model", 1, double_feature, id, int_feature) FROM test;
﻿
-- feature 参数支持表达式
SELECT ML_PREDICT("test_model", CAST(0.1 AS DOUBLE), id, int_feature) FROM test;
﻿
-- KMeans 模型预测（返回聚类标签）
SELECT ML_PREDICT("kmeans_model", int_feature, int_feature2, double_feature, float_feature) FROM test_data;
注意：
禁止分组：不允许配合 GROUP BY 使用。
禁止混合聚合：不允许与其他聚合函数（如 COUNT()）出现在同一层级。
不支持命名参数：version=1 这种写法不合法，version 只能作为位置参数传入。
Feature 列数量和类型必须与训练时严格匹配，否则会报错。
模型评估
ML_EVALUATE 属于聚合函数（Aggregate Function），对整个数据集计算评估指标，返回包含多个指标的 JSON 结果。
语法：
-- 不指定版本（使用最新版本）
ML_EVALUATE("<model_name>", label_expr, feature_expr0, feature_expr1, ...)
﻿
-- 指定版本（第二个参数为正整数字面量）
ML_EVALUATE("<model_name>", <version>, label_expr, feature_expr0, feature_expr1, ...)
参数
是否必填
说明
model_name
必填
模型名称，STRING 类型（不能是表达式），需用双引号包裹
version
可选
模型版本号，必须为正整数字面量（如 1, 2, 3）。不支持 0、负数、浮点数、字符串。不指定时使用最新版本。
label_expr
必填
标签列表达式，类型必须与模型训练时的 label 类型匹配。对于无监督模型（如 KMeans），评估阶段可以指定 label 列用于外部评估。
feature_expr
必填
特征列表达式，数量和类型必须与模型训练时的 feature 列一一对应
示例：
-- 使用最新版本评估监督学习模型
SELECT ML_EVALUATE("test_model", double_label, double_feature, id, int_feature) FROM test;
﻿
-- 指定版本 1 评估
SELECT ML_EVALUATE("test_model", 1, double_label, double_feature, id, int_feature) FROM test;
﻿
-- 评估 KMeans 模型（评估阶段可指定 label 列）
SELECT ML_EVALUATE("kmeans_model", int_label, int_feature, int_feature2, double_feature,
    float_feature) FROM test_data;
注意：
Label 列类型必须与模型要求匹配：ml_linear_regression / ml_gbrt 要求 DOUBLE，ml_gbdt 要求 INT。
对于无监督模型（如 KMeans），训练时不可指定 label_column，但评估阶段可以传入 label 列用于外部评估指标计算。
Feature 列数量和类型必须与训练时严格匹配。
特征工程函数
TCHouse-X 提供内建函数以简化数据预处理。部分函数支持窗口函数形态：
函数
类型
说明
`MAX_ABS_SCALER(v) OVER()`
Window
最大绝对值归一化，将数据缩放到 `[-1, 1]`。
`MIN_MAX_SCALER(v) OVER()`
Window
离差标准化，将数据缩放到 `[0, 1]`。
`STANDARD_SCALER(v) OVER()`
Window
Z-Score 标准化（均值为 0，标准差为 1）。
`NORMALIZER(ARRAY[v1, v2])`
Scalar
向量 L2 归一化。
常见错误参考
错误场景
错误信息示例
模型已存在（未使用 OR REPLACE）
Model already exists: test_model
未指定 model_type
Model option 'model_type' is required but not specified.
model_type 不合法
Model option 'model_type' not supported, model type name: ml_unknown.
监督学习未指定 label_column
Model option 'label_column' is required but not specified.
label_column 在查询输出中不存在
Label column 'xxx' not found in the training query output in Supervised ML
Label 列类型不匹配
Label column 'xxx' type mismatch: expected 'DOUBLE', got 'INT'
Feature 列类型不合法（如 STRING、DECIMAL）
Feature column 'xxx' type mismatch: expected integer or floating type, but got 'STRING'
无监督模型指定了 label_column
Unsupervised model type 'ml_kmeans' does not support specifying 'label_column' during training.
超参数名称不存在
parser Model param(n_clusters) failed, no such param
CREATE OR REPLACE 时 model_type 不一致
Model type mismatch for model 'xxx': existing model type is 'ml_linear_regression', but new model type is 'ml_gbrt'.
CREATE OR REPLACE 时 input schema 不一致
Input schema mismatch for model 'xxx': existing input schema are '[INT, INT, DOUBLE]', but new input schema are '[INT, INT]'.
ML_PREDICT/ML_EVALUATE feature 列数量不匹配
Validation Error: Expected 6 operands (without version) or 7 operands (with version), got 3
ML_PREDICT/ML_EVALUATE feature 列类型不匹配
Cannot assign to target field 'feature column 0' of type INT from source field 'operand 1' of type DOUBLE
ML_PREDICT/ML_EVALUATE label 列类型不匹配
Cannot assign to target field 'label column' of type DOUBLE from source field 'operand 1' of type INTEGER
version 参数不合法（0、负数、浮点数、字符串）
Second argument (model_version) must be a positive integer literal.
指定的 version 不存在
Model 'test_model' version 999 not found or has no URI.
训练数据量不足（KMeans）
n_samples=3 should be >= n_clusters=8

接口类型	语法示例	描述
训练 (DDL)	`CREATE MODEL ... AS SELECT ...`	触发模型训练并自动在元数据中注册。
推理 (Scalar)	`ML_PREDICT(model, f0, ...)`	标量函数，支持嵌套在 `SELECT`、`WHERE` 等任意合法位置。
评估 (Agg)	`ML_EVALUATE(model, label, f0, ...)`	聚合函数，返回包含多个评估指标的 JSON 结果。

参数	是否必填	说明
model_name	必填	模型名称，唯一标识符。必填，在当前数据库中唯一，支持大小写字母、数字、下划线，长度 ≤ 1024。
model_type	必填	模型类型，见支持的模型类型。
label_column	监督学习必填	标签列名称，必须存在于训练查询的输出列中。
超参数	可选	模型特定的超参数，如max_iter、l1_ratio、n_clusters 等。
AS	必填	训练集定义，支持所有 DQL 语句。注意：目前仅支持数值类型列参与训练与推理。

模型类型	学习方式	Label 类型要求	说明
ml_linear_regression	监督学习	DOUBLE	线性回归，用于连续值预测
ml_gbdt	监督学习	INT	梯度提升决策树，用于分类任务
ml_gbrt	监督学习	DOUBLE	梯度提升回归树，用于回归任务
ml_kmeans	无监督学习	训练时不可指定 label_column，评估时 label_column 类型需是 INT	K-Means 聚类，需指定 n_clusters 参数

函数	类型	说明
`MAX_ABS_SCALER(v) OVER()`	Window	最大绝对值归一化，将数据缩放到 `[-1, 1]`。
`MIN_MAX_SCALER(v) OVER()`	Window	离差标准化，将数据缩放到 `[0, 1]`。
`STANDARD_SCALER(v) OVER()`	Window	Z-Score 标准化（均值为 0，标准差为 1）。
`NORMALIZER(ARRAY[v1, v2])`	Scalar	向量 L2 归一化。

错误场景	错误信息示例
模型已存在（未使用 OR REPLACE）	Model already exists: test_model
未指定 model_type	Model option 'model_type' is required but not specified.
model_type 不合法	Model option 'model_type' not supported, model type name: ml_unknown.
监督学习未指定 label_column	Model option 'label_column' is required but not specified.
label_column 在查询输出中不存在	Label column 'xxx' not found in the training query output in Supervised ML
Label 列类型不匹配	Label column 'xxx' type mismatch: expected 'DOUBLE', got 'INT'
Feature 列类型不合法（如 STRING、DECIMAL）	Feature column 'xxx' type mismatch: expected integer or floating type, but got 'STRING'
无监督模型指定了 label_column	Unsupervised model type 'ml_kmeans' does not support specifying 'label_column' during training.
超参数名称不存在	parser Model param(n_clusters) failed, no such param
CREATE OR REPLACE 时 model_type 不一致	Model type mismatch for model 'xxx': existing model type is 'ml_linear_regression', but new model type is 'ml_gbrt'.
CREATE OR REPLACE 时 input schema 不一致	Input schema mismatch for model 'xxx': existing input schema are '[INT, INT, DOUBLE]', but new input schema are '[INT, INT]'.
ML_PREDICT/ML_EVALUATE feature 列数量不匹配	Validation Error: Expected 6 operands (without version) or 7 operands (with version), got 3
ML_PREDICT/ML_EVALUATE feature 列类型不匹配	Cannot assign to target field 'feature column 0' of type INT from source field 'operand 1' of type DOUBLE
ML_PREDICT/ML_EVALUATE label 列类型不匹配	Cannot assign to target field 'label column' of type DOUBLE from source field 'operand 1' of type INTEGER
version 参数不合法（0、负数、浮点数、字符串）	Second argument (model_version) must be a positive integer literal.
指定的 version 不存在	Model 'test_model' version 999 not found or has no URI.
训练数据量不足（KMeans）	n_samples=3 should be >= n_clusters=8

ML Functions 语法介绍

本页目录：

TCHouse-X ML Functions 语法介绍

核心能力矩阵

模型训练

CREATE MODEL — 创建/训练模型

支持的模型类型

数据类型约束

示例

CREATE OR REPLACE MODEL — 重新训练模型

模型管理

查看列表与定义

模型检查

删除模型

模型推理

模型评估

特征工程函数

常见错误参考