UDF使用介绍

UDF 使用介绍

内置UDF列表

数学函数

函数名	功能简介	版本
rand		未发布
%(mod)		未发布

字符串函数

函数名	功能简介	版本
concat		未发布
split_part		未发布
substr		未发布
length		未发布

复杂类型函数

函数名	功能简介	版本
contain	判断字段值在给定集合内，支持单值和多值	ALL
notcontain	判断字段值不在给定集合内，支持单值和多值	ALL
MATCHINDEX	使用给定的条件查询指定字段的倒排索引	ALL
QUERY	使用给定的条件查询倒排索引, 原HA3 query语法	ALL
sp_query_match	根据sp语法描述的条件查询倒排索引	>=3.7.5
hashcombine	将多个int64的值合并成1个int64的值	>=3.7.5
rangevalue	按范围将字段值做映射	>=3.7.5
sphere_distance	计算经纬度距离	>=3.7.5
ha_in	判断字段值在给定集合内	>=3.7.5
not_ha_in	判断字段值不在给定集合内	未发布
range	判断字段值在给定区间内	>=3.9.0
normalizescore	对字段值作规整	>=3.9.0
aitheta	用于aitheta向量召回检索	>=3.9.0
index	对多值字段按给定下标取值	ALL, 需要配置
array_slice	对多值字段按给起始下标和长度，取子集	未发布

使用示例

检索示例

检索全表内容

SELECT nid, price, brand, size FROM phone ORDER BY nid LIMIT 1000

USE_TIME: 0.881, ROW_COUNT: 10

------------------------------- TABLE INFO ---------------------------
                 nid |               price |               brand |                size |
                   1 |                3599 |              Huawei |                 5.9 |
                   2 |                4388 |              Huawei |                 5.5 |
                   3 |                 899 |              Xiaomi |                   5 |
                   4 |                2999 |                OPPO |                 5.5 |
                   5 |                1299 |               Meizu |                 5.5 |
                   6 |                 169 |               Nokia |                 1.4 |
                   7 |                3599 |               Apple |                 4.7 |
                   8 |                5998 |               Apple |                 5.5 |
                   9 |                4298 |               Apple |                 4.7 |
                  10 |                5688 |             Samsung |                 5.6 |

contain

原型

boolean contain(int32 a, const string b)
boolean contain(int64 a, const string b)
boolean contain(string a, const string b)
boolean contain(ARRAY<int32> a, const string b)
boolean contain(ARRAY<int64> a, const string b)
boolean contain(ARRAY<string> a, const string b)

说明

判断单值或多值a中是否包含b中描述的内容

参数

参数a：输入为单值多值的int32/int64/string 类型
参数b：输入为常量string表达式，用 | 分隔，表示满足任意一项即可

返回值

boolean类型返回，表示参数a是否包含参数b中描述的集合

示例

使用 contain ，检索nid字段值在[1,2,3]的所有记录

SELECT nid, price, brand, size FROM phone WHERE contain(nid, '1|2|3') ORDER BY nid LIMIT 100

USE_TIME: 0.059, ROW_COUNT: 3

------------------------------- TABLE INFO ---------------------------
                 nid |               price |               brand |                size |
                   1 |                3599 |              Huawei |                 5.9 |
                   2 |                4388 |              Huawei |                 5.5 |
                   3 |                 899 |              Xiaomi |                   5 |

notcontain

原型

boolean notcontain(int32 a, const string b)
boolean notcontain(int64 a, const string b)
boolean notcontain(string a, const string b)
boolean notcontain(ARRAY<int32> a, const string b)
boolean notcontain(ARRAY<int64> a, const string b)
boolean notcontain(ARRAY<string> a, const string b)

说明

判断单值或多值a中是否不在b中描述的内容

参数

参数a：输入为单值多值的int32/int64/string 类型
参数b：输入为常量string表达式，用 | 分隔，表示不能满足任意一项

返回值

boolean类型返回，表示参数a是否不在参数b中描述的集合

示例

使用 notcontain ，检索nid字段值不在[1,2,3]范围内的所有记录

SELECT nid, price, brand, size FROM phone WHERE notcontain(nid, '1|2|3') ORDER BY nid LIMIT 100

USE_TIME: 0.092, ROW_COUNT: 7

------------------------------- TABLE INFO ---------------------------
                 nid |               price |               brand |                size |
                   4 |                2999 |                OPPO |                 5.5 |
                   5 |                1299 |               Meizu |                 5.5 |
                   6 |                 169 |               Nokia |                 1.4 |
                   7 |                3599 |               Apple |                 4.7 |
                   8 |                5998 |               Apple |                 5.5 |
                   9 |                4298 |               Apple |                 4.7 |
                  10 |                5688 |             Samsung |                 5.6 |

MATCHINDEX

原型

boolean MATCHINDEX(const string a, const string b)
boolean MATCHINDEX(const string a, const string b, const string c)

说明

判断字段a中是否包含b中描述的内容，单字段索引的召回
仅限索引表召回阶段倒排加速优化使用，用于where条件中

参数

参数a：输入为常量string 类型，对应建立倒排优化字段
参数b：输入为常量string 类型，内容为字符串描述内容，
参数b可作为一个string整体查询，可用于空间向量索引
参数c：可选项，可描述内容包含分词器，停用词等，用于b中内容的分词：
主要通过下以关键词设置：
使用: , 分隔每一项

  - global_analyzer
  - specific_index_analyzer
  - no_token_indexes
  - tokenize_query
  - remove_stopwords
  - default_op

返回值

boolean类型返回，表示字段a中是否含有参数b中描述的内容

示例

使用 MATCHINDEX ，检索倒排字段 title 中含有"镜头"关键字的记录

SELECT nid, brand FROM phone WHERE MATCHINDEX('title', '镜头')

------------------------------- TABLE INFO ---------------------------
                 nid |               brand |
                   1 |              Huawei |

QUERY

原型

boolean QUERY(const string a, const string b)
boolean QUERY(const string a, const string b, const string c)

说明

判断字段a中是否包含b中描述的内容，提供自动分词并检索能力，
用于支持在SQL模式下使用HA3引擎原生的查询语法ha3 query语法，
仅限索引表召回阶段倒排加速优化使用，用于where条件中

参数

参数a：输入为常量string 类型，会作为默认索引字段，default_index
参数b：输入为常量string 类型，内容为字符串描述内容
会拼到query解析中，可用于range索引
参数c：可选项，可描述内容包含分词器，停用词等，用于b中内容的分词：
使用: , 分隔每一项
主要通过下以关键词设置：

  - global_analyzer
  - specific_index_analyzer
  - no_token_indexes
  - tokenize_query
  - remove_stopwords
  - default_op

返回值

boolean类型返回，表示字段a中是否含有参数b中描述的内容

示例
- 使用 QUERY ，查询 title 中含有"Huawei手机"的条目。

SELECT nid, price, brand, size FROM phone WHERE QUERY(title, 'Huawei手机')

USE_TIME: 0.034, ROW_COUNT: 1

------------------------------- TABLE INFO ---------------------------
                 nid |               price |               brand |                size |
                   2 |                4388 |              Huawei |                 5.5 |

使用组合条件，检索title中含有 "Huawei手机" 或者 "OPPO手机" 条目

SELECT nid, price, brand, size FROM phone 
   WHERE QUERY(title, 'Huawei手机 OR OPPO手机')

USE_TIME: 0.03, ROW_COUNT: 2

------------------------------- TABLE INFO ---------------------------
                 nid |               price |               brand |                size |
                   2 |                4388 |              Huawei |                 5.5 |
                   4 |                2999 |                OPPO |                 5.5 |

指定default_op等用法，使用: , 分隔

SELECT nid, price, brand, size FROM phone 
   WHERE QUERY(title, 'Huawei手机 OPPO手机', 'default_op:OR,remove_stopwords:true')

备注

QUERY udf的参数2是通过HA3 query语法解析器解析的，HA3 query语法可以参考 [query子句] 一节。当参数2填入的是常量字符串，代入HA3 query需要注意将前后单引号去掉，如QUERY(title, 'Huawei手机 OPPO手机')等价于HA3查询query=Huawei手机 OPPO手机。如果需要在query描述内部加引号，如形为query='Huawei手机' AND 'OPPO手机' 的HA3查询串，QUERY udf中的等价形式为 QUERY(title, '''Huawei手机'' AND ''OPPO手机''')。

典型错误 | 错误类型 | 错误形式 | 正确形式 | | --- | --- | --- | | 语法报错，查询无结果 | QUERY('pidvid','123:456') | QUERY('pidvid','"123:456"') |

sp_query_match

原型

boolean sp_query_match(string a)

说明

使用sp的查询语法检索倒排索引

参数

参数a：sp格式的查询串

返回值
示例

使用sp_query_match，检索brand是Apple且nid等于6或7或8的记录

SELECT * FROM phone WHERE sp_query_match('brand:Apple+(nid:6|nid:7|nid:8'))

hashcombine

原型

int64 hashcombine(int64 k1, int64 k2, ...)

说明

将多个int64整数通过内置hash函数合并成1个int64

参数

多个int64的整数列

返回值

hash后的值

示例

使用hashcombine，将cate_id和user_id合并成一个值

SELECT hashcombine(cate_id,user_id) FROM phone;

rangevalue

原型

float rangevalue(float v, string desc)

说明

将连续值映射成离散值

参数

参数v：连续值的列
参数desc：映射规则

返回值

映射后的离散值

示例

使用rangevalue，对price的值做映射：小于等于1000映射为1.0，大于1000小于等于5000映射为2.0，其他保留原始价格值

SELECT rangevalue(price,'(,1000]:1.0;(1000,5000]:2.0') FROM phone;

sphere_distance

原型

double sphere_distance(LOCATION point, double longitude, double latitude)

说明

计算输入的经纬度和检索文档的距离

参数

参数point：LOCATION类型单值的列
参数longitude：经度
参数latitude：纬度

返回值

地球球面距离，单位为千米

示例

使用sphere_distance。geo必须是LOCATION类型单值字段且创建了正排

SELECT sphere_distance(geo,127.0,30.0) FROM phone

ha_in

原型

boolean ha_in(int32 v, const string desc, [const string sep])
boolean ha_in(ARRAY<int32> v, const string desc, [const string sep])
boolean ha_in(int64 v, const string desc, [const string sep])
boolean ha_in(ARRAY<int64> v, const string desc, [const string sep])
boolean ha_in(string v, const string desc, [const string sep])
boolean ha_in(ARRAY<string> v, const string desc, [const string sep])

说明

类似contain的用法，判断描述内容是否存在于v字段中，可以用于summary/kv/kkv表查询

参数

参数v：字段，支持单值多值类型
参数desc：常量描述，可表述多个项，v满足其中一项即可
参数sep：可选项，分隔符，拆个参数desc内容成多项，默认|

返回值

判断v是否满足desc描述

示例

使用ha_in，检索nid字段值在描述里的所有记录

select nid from mainse_excellent_search where ha_in(nid, '641999912989|577150359640|123456')

USE_TIME: 32.141ms, ROW_COUNT: 2

------------------------------- TABLE INFO ---------------------------
                  nid(int64) |
                641999912989 |
                577150359640 |

not_ha_in

原型

boolean not_ha_in(int32 v, const string desc, [const string sep])
boolean not_ha_in(ARRAY<int32> v, const string desc, [const string sep])
boolean not_ha_in(int64 v, const string desc, [const string sep])
boolean not_ha_in(ARRAY<int64> v, const string desc, [const string sep])
boolean not_ha_in(string v, const string desc, [const string sep])
boolean not_ha_in(ARRAY<string> v, const string desc, [const string sep])

说明

类似notcontain的用法，判断描述内容是否不存在于v字段中

参数

参数v：字段，支持单值多值类型
参数desc：常量描述，可表述多个项，v满足其中一项即可过滤
参数sep：可选项，分隔符，拆个参数desc内容成多项，默认|

返回值

判断v是否不满足desc描述

示例

使用not_ha_in，检索nid字段值在[1,2,3]的所有记录

range

原型

boolean range(int8 v, const string rangeDesc)
boolean range(uint8 v, const string rangeDesc)
boolean range(int16 v, const string rangeDesc)
boolean range(uint16 v, const string rangeDesc)
boolean range(int32 v, const string rangeDesc)
boolean range(uint32 v, const string rangeDesc)
boolean range(int64 v, const string rangeDesc)
boolean range(uint64 v, const string rangeDesc)
boolean range(float v, const string rangeDesc)
boolean range(double v, const string rangeDesc)

说明

判断正排字段值是否在某一个区间

参数

参数v：字段，支持单值数值类型
参数rangeDesc：常量，描述数值范围区间，支持开、闭与半开半闭区间

返回值

判断v是否在rangeDesc描述范围内，下表为支持的写法及返回值

调用写法示例	返回值
range(v, "[0, 100]")	0<=v<=100
range(v, "(0, 100)")	0<v<100
range(v, "[0, 100)")	0<=v<100
range(v, "(0, 100]")	0<v<=100
range(v, "(0,)") range(v, "(0,]")	0<v
range(v, "[0,)") range(v, "[0,]")	0<=v
range(v, "(,100)") range(v, "[,100)")	v<100
range(v, "(,100]") range(v, "[,100]")	v<=100
range(v, "(,)") range(v, "[,]") range(v, "[,)") range(v, "(,]")	true

此外，rangeDesc还支持用"!"符号写于行首，表示对意向区间取反

示例

使用range

SELECT nid FROM phone where range(price,"(127.0,30.0)")
SELECT nid FROM phone where range(price,"!(127.0,30.0)")

normalizescore

原型

double normalizescore(int8 v, const string defaultScore)
double normalizescore(uint8 v, const string defaultScore)
double normalizescore(int16 v, const string defaultScore)
double normalizescore(uint16 v, const string defaultScore)
double normalizescore(int32 v, const string defaultScore)
double normalizescore(uint32 v, const string defaultScore)
double normalizescore(int64 v, const string defaultScore)
double normalizescore(uint64 v, const string defaultScore)
double normalizescore(float v, const string defaultScore)
double normalizescore(double v, const string defaultScore)

说明

对入参字段v作规整化处理，转换为double类型，已初始化返回原值，未初始化返回defaultScore

参数

参数v：字段，支持单值数值类型
参数defaultScore：常量描述，必须为能转换为合法double类型的字符串

返回值

v若已初始化返回原值，未初始化返回defaultScore

示例

对于拥有字段price的3个doc，原始内容如下:
doc1: price=1.0
doc2: price= (未初始化)
doc3: price=2.0

执行
select normalizescore(price, "1000.0") as normalized_score from phone

USE_TIME: 32.141ms, ROW_COUNT: 2

------------------------------- TABLE INFO ---------------------------
          normalized_score(double) |
                            1.0    |
                            1000.0 |
                            2.0.   |

aitheta

原型

boolean aitheta(const string biz_name, const string kvpair_desc)

说明

用于aitheta向量召回检索，具体使用方法看深度模型在 HA3/SQL 中的使用

参数

参数biz_name：常量string描述，对应的模型名
参数kvpair_desc：常量string描述，kapair形式，内容包含 topk，category，qinfo等信息

返回值

判断item侧向量是否属于与user向量最接近的topk个

示例

具体使用查看深度模型在 HA3/SQL 中的使用

index

原型

int8 index(ARRAY<int8> mv, const int64 idx, [const int8 def])
uint8 index(ARRAY<uint8> mv, const int64 idx, [const uint8 def])
int16 index(ARRAY<int16> mv, const int64 idx, [const int16 def])
uint16 index(ARRAY<uint16> mv, const int64 idx, [const uint16 def])
int32 index(ARRAY<int32> mv, const int64 idx, [const int32 def])
uint32 index(ARRAY<uint32> mv, const int64 idx, [const uint32 def])
int64 index(ARRAY<int64> mv, const int64 idx, [const int64 def])
uint64 index(ARRAY<uint64> mv, const int64 idx, [const uint64 def])
float index(ARRAY<float> mv, const int64 idx, [const float def])
string index(ARRAY<string> mv, const int64 idx, [const string def])

说明

从多值字段中按给定下标返回对应单值，可指定下标超出范围时返回的默认值

参数

参数mv: 字段名，多值数值或多值string类型
参数idx: 常量int64，指定返回的下标
参数def: 可选项，常量，类型需与mv的单值类型一致，指定下标溢出时的返回值。若无此项，对于数值类型默认为0，string类型默认为空字符串

返回值

下标合法时返回mv[idx]，溢出时返回def

示例

对于拥有字段prices的3个doc，原始内容如下:
doc1: prices=1.0 2.0 3.0
doc2: prices=100.0
doc3: prices=1000.0 2000.0

不指定默认值，执行

select index(prices, 2) as price_2 from phone

USE_TIME: 32.141ms, ROW_COUNT: 2

------------------------------- TABLE INFO ---------------------------
                  price_2(double) |
                         2.0      |
                         0.0      |
                         2000.0   |
                

指定默认值，执行

select index(prices, 2， -1.0) as price_2 from phone

USE_TIME: 32.141ms, ROW_COUNT: 2

------------------------------- TABLE INFO ---------------------------
                  price_2(double) |
                         2.0      |
                        -1.0      |
                         2000.0   |

array_slice

原型

ARRAY<int8> index(ARRAY<int8> mv, const int64 begin, const int64 length)
ARRAY<uint8> index(ARRAY<uint8> mv, const int64 begin, const int64 length)
ARRAY<int16> index(ARRAY<int16> mv, const int64 begin, const int64 length)
ARRAY<uint16> index(ARRAY<uint16> mv, const int64 begin, const int64 length)
ARRAY<int32> index(ARRAY<int32> mv, const int64 begin, const int64 length)
ARRAY<uint32> index(ARRAY<uint32> mv, const int64 begin, const int64 length)
ARRAY<int64> index(ARRAY<int64> mv, const int64 begin, const int64 length)
ARRAY<uint64> index(ARRAY<uint64> mv, const int64 begin, const int64 length)
ARRAY<float> index(ARRAY<float> mv, const int64 begin, const int64 length)
ARRAY<double> index(ARRAY<double> mv, const int64 begin, const int64 length)
ARRAY<string> index(ARRAY<string> mv, const int64 begin, const int64 length)

说明

从多值字段中按给定下标的起点及个数返回其子集

参数

参数mv: 字段名，多值数值或多值string类型
参数begin: 常量int64，指定返回的下标起点
参数length: 常量int64，指定从begin起取值的个数

返回值

返回mv从begin到begin+length-1的值，会根据mv的实际情况作截断

示例

对于拥有字段prices的3个doc，原始内容如下:
doc1: prices=1.0 2.0 3.0
doc2: prices=100.0
doc3: prices=1000.0 2000.0


select array_slice(prices, 1, 2) as price_2 from phone

USE_TIME: 32.141ms, ROW_COUNT: 2

------------------------------- TABLE INFO ---------------------------
            price_2(multi_double) |
                     2.0 3.0      |
                                  |
                     2000.0       |

附录：

分词器描述：

用于MATCHINDEX，QUERY等使用的参数说明

global_analyzer：

查询中指定全局的分词器，该分词器会覆盖schema的分词器，指定的值必须在analyzer.json里有配置

specific_index_analyzer

查询中指定index使用另外的分词器，该分词器会覆盖global_analyzer和schema的分词器

no_token_indexes

支持查询中指定的index不分词（除分词以外的其他流程如归一化、去停用词会正常执行），
多个index之间用;分割

tokenize_query

true or false 表示是否需要对query进行分词，QUERY UDF带了分词器该参数不生效
默认true

remove_stopwords

true or false 表示是否需要删除stop words，stop words在分词器中配置
默认true

default_op

指定在该次查询中使用的默认query 分词后的连接操作符，AND or OR, 默认行为在biz中配置

第三方UDF列表

复杂类型函数

函数名	功能简介	版本
type cast	cast类型	ALL

用户手册
技术文档
- havenask介绍

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

UDF使用介绍

内置UDF列表

数学函数

字符串函数

复杂类型函数

使用示例

检索示例

contain

notcontain

MATCHINDEX

QUERY

sp_query_match

hashcombine

rangevalue

sphere_distance

ha_in

not_ha_in

range

normalizescore

aitheta

index

array_slice

附录：

分词器描述：

第三方UDF列表

复杂类型函数

Clone this wiki locally