腾讯云数据仓库 TCHouse-X AI & ML Function

一、核心能力矩阵

TCHouse-X ML 能力围绕 3 类核心 SQL 接口展开：

此外，提供 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>;

三、支持的模型类型

四、数据类型约束

·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_modelMODEL_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_modelMODEL_OPTIONS(label_column='int_label', model_type=ml_gbdt)AS SELECT int_label, int_feature, int_feature2, double_feature, float_featureFROM test_data;

GBRT 回归模型（监督学习）：

— 创建 GBRT 回归模型，label 列为 double_label（DOUBLE 类型）CREATE MODEL gbrt_modelMODEL_OPTIONS(label_column='double_label', model_type=ml_gbrt)AS SELECT double_label, int_feature, int_feature2, double_feature, float_featureFROM test_data;

KMeans 聚类模型（无监督学习）：

— 创建 KMeans 聚类模型，无需指定 label_column，必须指定 n_clustersCREATE MODEL kmeans_modelMODEL_OPTIONS(model_type=ml_kmeans, n_clusters=3)AS SELECT int_feature, int_feature2, double_feature, float_featureFROM test_data;

训练查询支持表达式作为列：

— label 列可以是表达式，通过 AS 指定别名CREATE MODEL test_model2MODEL_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_modelMODEL_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, …)

示例：

— 使用最新版本进行预测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;

十一、模型评估

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, …)

示例：

— 使用最新版本评估监督学习模型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;

十二、特征工程函数

TCHouse-X 提供内建函数以简化数据预处理。部分函数支持窗口函数形态：

十三、常见错误参考