AI_FILTER 是 Hologres 提供的 AI Function，用于在 SQL 中直接对文本或文件进行「真/假」的语义判断，返回 BOOLEAN 结果。本文为您介绍 AI_FILTER 的使用限制、语法和使用示例。
功能介绍
AI_FILTER 将大语言模型的语义理解能力封装成一个标准的布尔函数，可以用在 SELECT 列表、WHERE 过滤条件、JOIN ON 关联条件等任意需要布尔值的位置，无需额外的 UDF 或外部服务集成。
典型使用场景如下：
评论、反馈的情感或意图筛选，例如判断「客户是否满意」。
内容合规、垃圾信息、敏感内容判断。
在没有外键关系时，基于语义做关联 JOIN。
图片内容识别，例如判断「图片中是否包含猫」。
使用限制
版本要求：仅 Hologres V4.2.12 及以上版本支持。
需先部署托管模型：使用前需在 Hologres 控制台部署托管模型。具体操作，请参见托管模型。
return_error_details 参数：只接受省略或
TRUE。省略时，出错的行返回NULL；取值为TRUE时，返回 OBJECT 类型的{"value": ..., "error": ...}；取值为FALSE时不被接受，会直接报错并提示改用不带该参数的重载。行级容错：批量处理多行时，出错的行返回
NULL，不会中断整个查询。结果非确定性：布尔结果由模型的语义判断决定，同一输入在不同模型或不同模型版本下可能存在差异，不保证结果完全一致。
语法
-- 语法一：对输入文本做布尔判断
AI_FILTER( <model_name>, <input> [, <return_error_details> ] )
-- 语法二：对单个文件（如图片）做布尔判断
AI_FILTER( <model_name>, <predicate>, <file> [, <return_error_details> ] )
-- 语法三：使用 PROMPT 模板拼装多列、混合文本与文件的输入
AI_FILTER( <model_name>, PROMPT('<template_string>', <col_1>, ... ) [, <return_error_details> ] )参数说明
参数名 | 参数含义 | 是否必填 |
| 模型名，TEXT 类型。 | 是 |
| 待判断的文本陈述，TEXT 类型。函数会在陈述前自动拼接一段「判断以下陈述为 TRUE 还是 FALSE」的提示词，由模型返回布尔结果。 | 是 |
| 判断指令，TEXT 类型，描述如何对 | 是 |
| 待判断的文件列，FILE 类型。可以使用 IMAGE FILE 作为输入，通过 | 是 |
| 对于复杂提示词，尤其是多列或混合文本与文件的场景，使用 | 是 |
| 布尔标志，BOOLEAN 类型，指示出错时是否返回错误详情。省略时，出错返回 | 否 |
错误行为
默认情况下，如果 AI_FILTER 无法处理某一行输入，该行返回 NULL，查询继续执行，不会中断。返回值取决于 return_error_details 参数。
return_error_details 取值 | 返回值 | 说明 |
省略或 TRUE（执行成功） | BOOLEAN 类型的 | 正常结果。 |
省略（执行失败） |
| 行级错误，查询继续执行。 |
TRUE（执行失败） |
| 错误详情作为 OBJECT 返回。 |
FALSE | 报错 | 不支持该取值，报错并引导改用不带该参数的重载。 |
传入 FALSE 时的报错信息如下：
ERROR: ai_filter: return_error_details must be TRUE when specified;
use ai_filter(model_name, input) for BOOLEAN output
HINT: Call ai_filter(model_name, input) to get a BOOLEAN result on error (NULL).使用示例
以下示例均使用 Hologres 托管模型 qwen3.8-max 执行。
示例一：对输入文本应用 AI_FILTER
SELECT ai_filter('qwen3.8-max', '天空是蓝色的');返回结果：
+------+
| ? |
+------+
| t |
+------+示例二：在 WHERE 子句中做语义过滤
筛选出表达正面评价的订单评论。
SELECT order_id, order_comments
FROM (VALUES
(1, '质量很好，物流也快，非常满意'),
(2, '包装破损，客服态度差'),
(3, '一般般，凑合用')
) AS orders(order_id, order_comments)
WHERE ai_filter('qwen3.8-max', '客户是否喜欢这个商品:' || order_comments);返回结果：
+----------+----------------------------------------+
| order_id | order_comments |
+----------+----------------------------------------+
| 1 | 质量很好，物流也快，非常满意 |
+----------+----------------------------------------+示例三：使用 PROMPT 函数拼装输入
SELECT ai_filter(
'qwen3.8-max',
prompt('{0} 是否被描述为 {1}？', '无线鼠标', '一款黑色的人体工学鼠标')
) AS consistent;返回结果：
consistent
---------
f示例四：在 JOIN 条件中做语义关联
投诉表中没有部门 ID，无法使用传统外键 JOIN。此时可以用 AI_FILTER 判断某条投诉是否应由某个部门处理，并将其作为 JOIN 条件。
SELECT t.ticket_id, t.issue_text, d.department_name
FROM (VALUES
(201, '手机屏幕碎了，想申请保修维修'),
(202, '扣款成功了但订单状态一直没更新'),
(203, '登录时收不到短信验证码')
) AS t(ticket_id, issue_text)
JOIN (VALUES
('售后服务'),
('订单运营'),
('账号支持')
) AS d(department_name)
ON ai_filter(
'qwen3.8-max',
prompt('下面这条用户问题是否应该由"{0}"负责处理？只根据语义判断。用户问题：{1}',
d.department_name, t.issue_text)
);返回结果：
ticket_id | issue_text | department_name
----------|--------------------------------|----------------
201 | 手机屏幕碎了，想申请保修维修 | 售后服务
202 | 扣款成功了但订单状态一直没更新 | 售后服务
202 | 扣款成功了但订单状态一直没更新 | 订单运营
203 | 登录时收不到短信验证码 | 账号支持示例五：对图片文件应用 AI_FILTER
SELECT id,
ai_filter(
'qwen3.8-max',
'图片中是否包含猫？',
to_file(img_path, 'oss-cn-hangzhou-internal.aliyuncs.com', 'acs:ram::<ACCOUNT_ID>:role/<ROLE_NAME>')
) AS has_cat
FROM (VALUES
(1, 'oss://my-bucket/cat.png'),
(2, 'oss://my-bucket/dog.png')
) AS images(id, img_path);返回结果：
+----+---------+
| id | has_cat |
+----+---------+
| 1 | t |
| 2 | f |
+----+---------+示例六：返回错误详情
将 return_error_details 设置为 TRUE，返回 OBJECT 类型的结果。
SELECT ai_filter('qwen3.8-max', '水在100摄氏度沸腾', TRUE) AS result;返回结果：
+----------------------------------+
| result |
+----------------------------------+
| {"value": true, "error": null} |
+----------------------------------+如需 BOOLEAN 类型的输出，请省略 return_error_details 参数。传入 FALSE 会直接报错。