文档 插件 Infinity 数据源 查询 UQL Parser

UQL Parser

UQL（非结构化查询语言）是 Infinity 数据源中的一种高级查询格式，它可以整合 JSON、CSV、XML、GraphQL 格式。UQL 还提供了定制结果的能力。

UQL 是一种专门为内存操作设计的查询语言。UQL 查询可以通过一系列用 | 连接的命令构成，每行一个。大多数情况下，字段使用双引号引用，字符串值使用单引号引用。UQL 的灵感来源于 kusto 查询语言，并遵循类似的语法。

如果您的数据看起来像这样

json 复制

[
  {
    "id": 1,
    "name": { "firstName": "john", "lastName": "doe" },
    "dob": "1985-01-01",
    "city": "chennai"
  },
  {
    "id": 2,
    "name": { "firstName": "alice", "lastName": "bob" },
    "dob": "1990-12-31",
    "city": "london"
  }
]

那么以下 UQL 查询

sql 复制

parse-json
| extend "full name"=strcat("name.firstName",' ',"name.lastName"), "dob"=todatetime("dob")
| project-away "name"
| order by "full name" asc

将生成一个包含四列的表格 (id, dob, city, full name)。

基本 UQL 命令

除非另有说明，所有版本都提供这些命令。

project

project 命令用于选择要在结果中包含的列。如果您想选择嵌套对象内的属性，可以使用点记法。您还可以选择为字段设置别名。

sql 复制

parse-json
| project "id", "name.firstName", "date of birth"="dob"

project-away

project-away 命令与 project 命令完全相反。它只是从数据中删除特定的列。它不支持别名或点记法选择器。

sql 复制

parse-json
| project-away "id", "city"

order by

order by 命令根据任何列对输入进行排序。排序方向应为 asc 或 desc

sql 复制

parse-json
| order by "full name" asc

extend

extend 命令类似于 project。但它不是选择列，而是向现有数据添加/替换列。extends 需要一个别名和一个函数。

sql 复制

parse-json
| extend "dob"=todatetime("dob"), "city"=toupper("city")

以下是一些可用函数

例如，数据 [ { "a": 12, "b" : 20 }, { "a" : 6, "b": 32} ] 和以下 uql 查询

sql 复制

parse-json
| project "a", "triple"=sum("a","a","a"),"thrice"=mul("a",3), sum("a","b"),  diff("a","b"), mul("a","b")

将生成以下输出

要对字段应用多个转换，请使用相同的字段名重复它们。例如，uql 查询 extend "name"=tolower("name"), "name"=trim("name") 将对 name 字段先应用 tolower 函数，然后应用 trim 函数。

还有一些其他的 extend/project 方法可用于处理数组

pack

pack 方法将键值对数组转换为 map。例如 extend "foo"=pack('key1',"value1",'key1',"value2") 将生成对象 {key1:value1,key2:value2}

array_from_entries

array_from_entries 方法从条目构建对象数组。例如 extend "foo"=array_from_entries('timestamp',[2010,2020,2030]) 将生成数组 [{timestamp:2010},{timestamp:2020},{timestamp:2030}]

array_to_map

array_to_map 将条目数组转换为 map。可以选择为键提供别名而不是索引。例如 extend "foo"=array_to_map(['chennai','india'],'city','country') 将生成 { 'city': 'chennai', 'country':'india'}

summarize

summarize 命令按字符串列聚合数据。summarize 命令需要别名、summarize 字段和 summarize 函数。以下是有效的 summarize 函数。

例如，以下数据

json 复制

[
  { "city": "tokyo", "country": "japan", "population": 200 },
  { "city": "newyork", "country": "usa", "population": 60 },
  { "city": "oslo", "country": "usa", "population": 40 },
  { "city": "new delhi", "country": "india", "population": 180 },
  { "city": "mumbai", "country": "india", "population": 150 }
]

以及以下 uql 查询

sql 复制

parse-json
| summarize "number of cities"=count(), "total population"=sum("population") by "country"
| extend "country"=toupper("country")
| order by "total population" desc

将生成如下输出表

pivot

pivot 是用于对数据执行透视操作的命令。pivot 命令接受 3 个参数。

• 第一个参数是摘要。示例：count("id) 或 sum("salary")
• 第二个参数是行字段名。示例："country"
• 第三个参数是列字段名。示例："occupation"

Pivot 示例 1

csv 复制

name,age,country,occupation,salary
Leanne Graham,38,USA,Devops Engineer,3000
Ervin Howell,27,USA,Software Engineer,2300
Clementine Bauch,17,Canada,Student,
Patricia Lebsack,42,UK,Software Engineer,2800
Leanne Bell,38,USA,Senior Software Engineer,4000
Chelsey Dietrich,32,USA,Software Engineer,3500

以及以下查询

sql 复制

parse-csv
| extend "salary"=tonumber("salary")
| pivot sum("salary"), "country", "occupation"

将生成

而以下 summarize 查询

sql 复制

parse-csv
| extend "salary"=tonumber("salary")
| summarize "salary"=sum("salary") by "country", "occupation"

将生成

因此，根据您的需要选择 summarize 或 pivot

parse-json

parse-json 命令用于指示 UQL 将响应解析为 JSON

parse-csv

parse-csv 命令用于指示 UQL 将响应解析为 CSV

parse-xml

parse-xml 命令用于指示 UQL 将响应解析为 XML

parse-yaml

parse-yaml 用于指定结果为 YAML 格式

count

count

sql 复制

parse-json
| count

count 提供结果的数量。

limit

sql 复制

parse-json
| limit 10

limit 命令限制返回结果的数量。例如，以下查询只返回 10 个结果

scope

scope 命令设置输出数据的上下文。当结果位于嵌套的 json 对象内部时很有用。

json 复制

{
  "meta": { "last-updated": "2021-08-09" },
  "count": 2,
  "users": [{ "name": "foo" }, { "name": "bar" }]
}

示例

sql 复制

parse-json
| scope "users"

以下 uql 查询仅返回“users”并忽略其他根级别属性。

mv-expand

json 复制

[
  { "group": "A", "users": ["user a1", "user a2"] },
  { "group": "B", "users": ["user b1"] }
]

mv-expand 将多值属性扩展为独立的记录。例如，对以下数据使用命令 mv-expand "user"="users"

json 复制

[
  { "group": "A", "user": "user a1" },
  { "group": "A", "user": "user a2" },
  { "group": "B", "user": "user b1" }
]

将生成如下结果

mv-expand 也应适用于非字符串数组。

project kv()

project kv() 命令用于将给定的对象转换为键值对。

{"name":"c1"}

此命令也可与参数一起使用

示例：对于数据 { "data": { "a": {"name":"a1"}, "b": {"name":"b1"}, "c": {"name":"c1"} } } 和查询 parse-json | project kv("data") 将生成相同的结果

project kv() 命令仅在插件 0.8.7 及以上版本中可用

JSONata

sql 复制

parse-json
| scope "library"
| jsonata "library.loans@$L.books@$B[$L.isbn=$B.isbn].customers[$L.customer=id].{ 'customer': name, 'book': $B.title, 'due': $L.return}"
| count

jsonata 命令接受一个 JSONata 查询并应用于先前的输入

像任何其他命令一样，jsonata 命令可以与多个命令组合/通过管道连接。您也可以使用 JSONata 进行数据过滤。

从 0.8.8 版本开始支持 JSONata

注释