AI_MASK

AI_MASK

[MASKED]

云器将 AI 计算下沉至存储层与执行引擎，数据在平台内部即可完成智能处理，无需流转至外部环境，在保障数据安全的同时大幅降低任务延迟。

语法

AI_MASK

-- 使用工作区默认模型（推荐） AI_MASK(<content>, <labels> [, json '{}']) -- 手动指定连接和模型 AI_MASK('<connection>:<model>', <content>, <labels> [, json '{}'])

参数说明

model（可选）

指定要调用的语言模型。从 2026 年 9 月起，该参数可以省略——模型通过工作区默认模型自动路由，无需在每次调用时显式传入。

省略 model 参数时调用方式最简洁：

SELECT AI_MASK('手机1381234', ARRAY('phone'));

工作区默认模型可通过以下方式配置：

方式一：创建新工作区时开启开关（推荐）

2026 年 9 月起新建的工作区，在创建时打开 "启用 AI Function" 开关，系统将自动配置默认模型，调用时无需传入 model 参数。对于此之前创建的工作区，需通过下方方式手动配置。

方式二：工作区级别 ALTER WORKSPACE 配置

通过

ALTER WORKSPACE

ALTER WORKSPACE <workspace_name> SET PROPERTIES ( 'cz.sql.ai.mask.default.model' = '<connection>:<model>' ); SELECT AI_MASK('手机1381234', ARRAY('phone'));

方式三：会话级 SET 覆盖

在当前会话中临时指定默认模型，优先级高于工作区属性，仅当前 session 生效：

SET cz.sql.ai.mask.default.model=conn_bailian:qwen/qwen3.6-flash; SELECT AI_MASK('手机1381234', ARRAY('phone'));

方式四：API Connection 连接对象

通过

CREATE API CONNECTION

CREATE API CONNECTION conn_bailian TYPE ai_function PROVIDER = 'bailian' BASE_URL = 'https://dashscope.aliyuncs.com/api/v1' API_KEY = 'sk-xxxxxxxxxxxxxxxxxxxxxxxx'; SELECT AI_MASK('conn_bailian:qwen3.5-plus', '用户王小明，手机号：13800138000', ARRAY('姓名', '手机号'));

CREATE API CONNECTION

TYPE

ai_function

PROVIDER

'bailian'

'openai'

'anthropic'

BASE_URL

API_KEY

content（必需）

包含待脱敏敏感信息的输入文本，类型为 STRING（CHAR/VARCHAR/STRING 均可）。支持中文、英文、日文等多种语言，无需手动指定语言，模型自动识别。

labels（必需）

需要脱敏的标签数组，类型为 ARRAY(STRING)。标签由用户自定义，模型根据标签的语义含义在文本中识别对应信息。数组中的标签数量须在 1~20 之间。

ARRAY('姓名', '手机号', '邮箱') ARRAY('person', 'email', 'SSN')

options（可选）

使用

json '{}'

输出格式控制

output.behavior

formatted_json

formatted_json

raw_string

fail_on_error

三种输出模式对比：

formatted_json

{"value":"模型输出"}

{"value":"","error_message":"..."}

raw_string

fail_on_error

-- formatted_json（默认） SELECT AI_MASK('手机1381234', ARRAY('phone'), json '{"output.behavior":"formatted_json"}'); -- 结果: {"value":"[MASKED]"} -- raw_string SELECT AI_MASK('手机1381234', ARRAY('phone'), json '{"output.behavior":"raw_string"}'); -- 结果: [MASKED] -- fail_on_error SELECT AI_MASK('手机1381234', ARRAY('phone'), json '{"output.behavior":"fail_on_error"}'); -- 结果（成功时同 raw_string）: [MASKED]

output.behavior

_

.

-

formatted_json

formatted.json

json

raw_string

raw.string

raw

fail_on_error

fail.on.error

fail-on-error

fail

返回值

返回 STRING 类型，具体格式取决于

output.behavior

• formatted_json

  formatted_json
  （默认）：返回

  {"value":"脱敏后文本"}

  {"value":"脱敏后文本"}
  格式的 JSON 字符串

• raw_string

  raw_string
  /

  fail_on_error

  fail_on_error
  ：返回脱敏后的原始字符串
• 若文本中不包含指定标签对应的信息，返回原文不变

异常情况：

• content 为

  NULL

  NULL
  时返回

  NULL

  NULL
  ，不报错
• content 为空字符串

  ''

  ''
  时返回

  ''

  ''
  ，不报错
• labels 数组为空（

  ARRAY()

  ARRAY()
  ）时，报错

  labels must contain at least 1 label

  labels must contain at least 1 label
• 默认情况下，若函数无法处理输入，返回

  NULL

  NULL
  ，不报错。在多行查询中，出错的行返回

  NULL

  NULL
  ，不影响其他行的正常执行
• model 不存在时，报错

  CZLH-67000: No available endpoints found

  CZLH-67000: No available endpoints found
• model 格式错误（无正确的前缀）时，报错

  CZLH-65000: Invalid model coordinates

  CZLH-65000: Invalid model coordinates

使用示例

基础用法（省略 model 参数）

SELECT AI_MASK('手机1381234', ARRAY('phone')); -- 返回：[MASKED]

指定连接和模型

-- 中文 PII 脱敏 SELECT AI_MASK( 'conn_bailian:qwen3.5-plus', '用户王小明，手机号：13800138000，邮箱：wang@example.com', ARRAY('姓名', '手机号', '邮箱') ) AS masked; -- 返回：用户[MASKED]，手机号：[MASKED]，邮箱：[MASKED] -- 英文 PII 脱敏 SELECT AI_MASK( 'conn_bailian:qwen3.5-plus', 'John Doe, email: john.doe@example.com', ARRAY('person', 'email') ) AS masked; -- 返回：[MASKED], email: [MASKED]

多类型同时脱敏

SELECT AI_MASK( 'conn_bailian:qwen3.5-plus', '张三，男，28岁，电话13800138000，邮箱zhangsan@qq.com，住址北京市朝阳区建国路88号。', ARRAY('姓名', '电话', '邮箱', '住址') ) AS masked; -- 返回：[MASKED]，男，28岁，电话[MASKED]，邮箱[MASKED]，住址[MASKED]。

日文 PII 脱敏

SELECT AI_MASK( 'conn_bailian:qwen3.5-plus', '田中太郎、電話番号：090-1234-5678、メール：tanaka@example.jp', ARRAY('名前', '電話番号', 'メール') ) AS masked; -- 返回：[MASKED]、電話番号：[MASKED]、メール：[MASKED]

批量脱敏表数据

SELECT id, AI_MASK( 'conn_bailian:qwen3.5-plus', customer_info, ARRAY('姓名', '身份证', '手机号', '地址') ) AS masked_info FROM customer_records WHERE customer_info IS NOT NULL;

使用 output.behavior 控制输出格式

SELECT AI_MASK( 'conn_bailian:qwen3.5-plus', '手机1381234', ARRAY('phone'), json '{"output.behavior":"formatted_json"}' ) AS masked;

脱敏后做情感分析

SELECT id, AI_MASK('conn_bailian:qwen3.5-plus', content, ARRAY('姓名', '电话', '邮箱') ) AS masked_content, AI_SENTIMENT('conn_bailian:qwen3.5-plus', content) AS sentiment FROM customer_feedback WHERE content IS NOT NULL;

合规数据导出

CREATE TABLE masked_feedback AS SELECT id, AI_MASK('conn_bailian:qwen3.5-plus', content, ARRAY('姓名', '电话', '邮箱', '地址') ) AS masked_content FROM customer_feedback;

注意事项

• model 参数可省略：通过工作区开关（新工作区）、

  ALTER WORKSPACE

  ALTER WORKSPACE
  或会话级

  SET

  SET
  配置

  cz.sql.ai.mask.default.model

  cz.sql.ai.mask.default.model
  后，调用时无需传 model 参数，系统自动路由至默认模型。
• content 为 NULL 返回 NULL：content 为

  NULL

  NULL
  时，函数返回

  NULL

  NULL
  ，不报错。
• content 为空字符串返回空字符串：content 为

  ''

  ''
  时，函数返回

  ''

  ''
  ，不报错。
• 无匹配时返回原文：文本中不包含

  labels

  labels
  指定类型的信息时，返回原文不变，不报错。
• labels 不能为空数组：

  ARRAY()

  ARRAY()
  会触发报错，至少需要提供 1 个标签，上限为 20 个。
• 标签越具体越精准：使用"身份证号"比"证件"更精确，使用"手机号"比"号码"更准确。
• 标签语言与文本语言匹配效果更佳：中文文本配中文标签（如"姓名"、"手机号"），英文文本配英文标签（如"person"、"phone"）。
• 占位符统一为

  [MASKED]

  [MASKED]
  ：所有被脱敏的信息均替换为相同占位符，不区分脱敏类型。
• 不支持仅检测模式：函数直接返回脱敏后文本，不支持仅返回敏感信息位置或类型的检测模式。
• 先过滤再脱敏：对大表使用时，先用

  WHERE content IS NOT NULL

  WHERE content IS NOT NULL
  过滤空值，减少不必要的模型调用。
• 结果不保证 100% 覆盖：AI 脱敏基于 LLM，可能存在漏脱或误脱，合规场景建议人工抽检。
• 结果具有非确定性：基于 LLM 的脱敏结果可能因模型版本或调用时机略有差异。
• 输入长度受模型限制：输入文本长度受底层模型 context window 限制。