算法执行的方式有以下四种,每次只能以其中一种方式执行:
执行方式 | 执行参数 | 描述 |
与其他 UQL 语句组装 |
---|---|---|---|
任务回写 | write() |
以任务的方式运行算法,任务 ID 会返回给客户端(SDK/API/Manager);算法结果可回写至文件(RPC 接口)或点/边属性,算法统计值回写至任务信息 | 不支持 |
直接返回 | / | 直接将算法结果和统计值返回给客户端,需要为算法语句定义别名并与 return 子句组合使用 |
有限的支持,例如子句 limit 、skip 和 order by |
流式返回 | stream() |
将算法结果实时返回 | 支持 |
实时统计 | stats() |
将算法统计值实时返回 | 不支持 |
针对任务的操作,详见 UQL 手册《任务》一章。
任务回写
使用 write()
参数可将算法结果和统计值回写到指定位置,包含文件回写(file)、属性回写(db)和统计值回写(stats)。不能同时回写到文件和属性;在进行文件或属性回写时,统计值(如有)会自动回写至算法任务中。
1. 文件回写
将算法结果回写到一个或多个文件,需提供文件名;回写的文件无表头,每行数据以英文逗号作为分隔符。同时,自动将算法统计值(如有)回写至算法任务中。
语法:write()
参数里包裹 file 对象
algo(<>).params(<>).write({
file:{
filename: "<filename>"
}
})
algo(<>).params(<>).write({
file:{
filename_<result1>: "<filename1>",
filename_<result2>: "<filename2>",
...
}
})
文件名建议使用 .csv 或 .txt 后缀,也可以不使用后缀。
示例:在图上运行三角形计算算法并将结果回写至文件,文件名为 count
algo(triangle_counting).params().write({
file:{
filename: "count.csv"
}
})
在 Ultipa Manager 中显示结果:查看(文件下载链接和算法统计值都显示在任务信息的 Result 列)
示例:在图上运行全图 K 邻算法并将两种结果回写至两个文件,文件名分别为 khop_ids 和 khop_num
algo(khop_all).params().write({
file:{
filename_ids: "khop_ids.csv",
filename_num: "khop_num.csv"
}
})
在 Ultipa Manager 中显示结果:查看(文件下载链接显示在任务信息的 Result 列,全图 K 邻算法没有统计值)
2. 属性回写
将算法结果回写至一个或多个属性,需提供属性名。根据算法的计算内容,回写的属性可能是点属性,也可能是边属性。同时,自动将算法统计值(如有)回写至算法任务中。
属性回写是全量操作,即回写至当前图集的所有点或所有边,因此提供属性名称时不需要指定 schema;对于任意一个 schema,如果提供的回写属性不存在,则自动创建属性;如果属性名已存在但数据类型和待回写的属性类型不一致,则该 schema 的属性回写失败。有计算结果的点或边,其算法结果将写入其属性中,没有结果的点或边(比如非全量计算时),则根据算法结果的数据类型写入 0、空字符串等。
语法:write()
参数里包裹 db 对象
algo(<>).params(<>).write({
db:{
property: "<property>"
}
})
示例:在图上运行接近中心性算法,将结果回写至点的 centrality 属性
algo(closeness_centrality).params().write({
db:{
property: "centrality"
}
})
在 Ultipa Manager 中显示结果:查看(算法结果回写到点的 centrality 属性中,接近中心性算法没有统计值,任务信息 Result 列为空)
示例:在图上运行标签传播算法,最多为每个节点保留两个标签,将结果回写至点的 label_1、probability_1、label_2、probability_2 属性
algo(lpa).params({k:2}).write({
db:{
property: "label"
}
})
在 Ultipa Manager 中显示结果:查看(算法结果回写到点的 label_1、probability_1、label_2、probability_2 属性中,算法统计值都显示在任务信息的 Result 列)
有些算法执行后,每个点(或边)对应多种结果,此时只需指定一个属性名
<property>
,系统将根据该名称自动将全部结果写入不同的属性中。
上例的标签传播算法,指定“标签”的属性名为 label,标签“占比”的属性名 probability 是系统默认且不可修改的,回写时系统自动为 label 和 probability 加上序号。
3. 统计回写
如果算法有统计值,将算法统计值记录在任务信息中。执行文件回写或属性回写时,会自动记录统计值;执行统计回写时,仅记录统计值。
语法:直接使用 write()
参数
algo(<>).params(<>).write()
示例:在图上运行节点度算法并将算法统计值 total_degree
和 average_degree
回写至算法任务
algo(degree).params().write()
在 Ultipa Manager 中显示结果:查看(算法统计值写在任务信息的 Result 列)
直接返回
语法:定义别名并与 return
子句组装
// 实时返回算法结果和统计值
algo(<>).params(<>) as <alias0>, <alias1>
return <alias0>, <alias1>
// 实时返回算法结果
algo(<>).params(<>) as <alias>
return <alias>
定义算法语句别名时,写在前面的是算法结果别名,写在后面的是算法统计值别名,该顺序不可修改。如果算法没有统计值,算法语句只能定义一个算法结果别名。
在
return
子句中,也可调用算法结果或统计值的某一列。关于别名的定义和调用方法,详见 UQL 文档的《查询》章节。
示例:在图上运行节点度算法并直接返回算法结果(定义为别名 a1)和统计值(定义为别名 a2)
algo(degree).params() as a1, a2
return a1, a2
示例:修改上例,将算法结果和统计值都分列返回
algo(degree).params() as a1, a2
return a1._uuid, a1.degree, a2.total_degree, a2.average_degree
在 Ultipa Manager 中显示结果:a1._uuid,a1.degree,a2.total_degree,a2.average_degree
流式返回
语法:直接使用 stream()
参数
// 执行算法并将算法结果定义为别名 <alias>,算法结果可返回或作为后续 UQL 语句的输入
algo(<>).params(<>).stream() as <alias>
...
示例:在图上运行接近中心性算法并以实时数据流(定义为别名 cc)的方式返回结果
algo(closeness_centrality).params().stream() as cc
return cc
在 Ultipa Manager 中显示结果:cc
示例:修改上例,返回图上接近中心性大于 0.5 的点的 UUID
algo(closeness_centrality).params().stream() as cc
where cc.centrality > 0.5
return cc._uuid
在 Ultipa Manager 中显示结果:cc._uuid
通过算法语句获得的数据流可在后续查询类型的 UQL 语句中使用,但不支持插入、修改或删除元数据。
实时统计
语法:直接使用 stats()
参数
// 执行算法并将算法统计值定义为别名 <alias>,算法统计值可返回或作为后续 UQL 语句的输入
algo(<>).params(<>).stats() as <alias>
...
示例:在图上运行节点度算法并实时分列返回统计值(定义为别名 sta)
algo(degree).params().stats() as sta
return sta
在 Ultipa Manager 中显示结果:sta
示例:修改上例,将统计值分列返回
algo(degree).params().stats() as sta
return sta.total_degree, sta.average_degree
在 Ultipa Manager 中显示结果:sta.total_degree,sta.average_degree