本文介绍SPL指令的详细信息。
参数类型说明
SPL指令中的参数类型说明如下表所示。
参数类型 | 说明 |
Bool | 布尔类型参数。使用SPL时,该参数为开关参数。 |
Char | ASCII字符类型参数,需使用单引号('')包裹,例如 |
Integer | 整数类型参数。 |
String | 字符串类型参数,需使用单引号('')包裹,例如 |
RegExp | RE2正则表达式类型参数,需使用单引号('')包裹,例如 语法定义,请参见Syntax。 |
JSONPath | JSON路径类型参数,需使用单引号('')包裹,例如 语法定义,请参见JsonPath。 |
Field | 字段名类型参数,例如 如果字段名中包含字母、数字、下划线以外的特殊字符,需使用双引号("")包裹,例如 说明 关于字段名称大小写敏感详情,请参见SPL在不同场景的功能定义。 |
FieldPattern | 字段名和通配符组合或者字段名类型参数。支持通配符号*,表示匹配0个或多个任意字符。需使用双引号("")包裹,例如 说明 关于字段名称大小写敏感详情,请参见SPL在不同场景的功能定义。 |
SPLExp | SPL表达式类型参数。 |
SQLExp | SQL表达式类型参数。 |
SPL指令列表
指令类别 | 指令名称 | 说明 |
字段操作指令 | 保留与给定模式相匹配的字段、同时可重命名指定字段。指令执行过程中,先完成所有字段保留表达式的执行,再执行重命名表达式。 | |
移除与给定模式相匹配的字段,原样保留其他所有字段。 | ||
重命名指定字段,并保留其他所有字段原样。 | ||
展开指定字段的第一层JSON对象,生成多条结果。 | ||
结构化数据SQL计算指令 | 通过SQL表达式计算结果产生新字段。支持的SQL函数列表,请参见SPL支持的SQL函数列表。 | |
根据SQL表达式过滤数据,保留满足SQL表达式的数据条目。where指令支持的SQL函数列表,请参见SPL支持的SQL函数列表。 | ||
弱结构化数据提取指令 | 提取指定字段中的正则表达式分组匹配信息。 | |
提取指定字段中的CSV格式的信息。 | ||
提取指定字段中的第一层JSON信息。 | ||
提取指定字段中的键值对信息。 |
字段操作指令
project
保留与给定模式相匹配的字段、同时可重命名指定字段。指令执行过程中,先执行完成所有字段保留表达式,再执行重命名表达式。
默认保留时间字段__time__和__time_ns_part__,并且不可重命名与覆盖,更多信息,请参见时间字段。
语法
| project -wildcard <field-pattern>, <output>=<field>, ...
参数说明
参数 | 类型 | 必填 | 说明 |
wildcard | Bool | 否 | 是否开启通配模式。默认为字段精确匹配。您需要开启通配模式时,需添加该参数。 |
field-pattern | FieldPattern | 是 | 需要保留的字段名称或字段和通配符组合(处理匹配到的所有字段)。 |
output | Field | 是 | 需要重命名的新字段名称,不支持多次重命名至相同的目标字段。 重要 如果新字段与输入数据中字段重名,其结果取值策略,请参见新旧值保留与覆盖。 |
field | Field | 是 | 需要重命名的原字段名称。
|
示例
示例1:保留特定字段。
* | project level, err_msg
示例2:重命名字段。
* | project log_level=level, err_msg
示例3:保留精确匹配的字段
__tag__:*
。* | project "__tag__:*"
project-away
移除与给定模式相匹配的字段,原样保留其他所有字段。
该指令将默认保留时间字段__time__和__time_ns_part__,更多详情,请参见时间字段。
语法
| project-away -wildcard <field-pattern>, ...
参数说明
参数 | 类型 | 必填 | 说明 |
wildcard | Bool | 否 | 是否开启通配模式。默认为字段精确匹配。您需要开启通配模式时,需添加该参数。 |
field-pattern | FieldPattern | 是 | 需要移除的字段名称或者字段和通配符组合(处理匹配到的所有字段)。 |
project-rename
重命名指定字段,并保留其他所有字段原样。
默认保留时间字段__time__和__time_ns_part__,并且不可重命名与覆盖,更多详情,请参见时间字段。
语法
| project-rename <output>=<field>, ...
参数说明
参数 | 类型 | 必填 | 说明 |
output | Field | 是 | 重命名后的字段名称。不支持多次重命名至相同的目标字段。 重要 如果新字段与输入数据中字段重名,其结果取值策略,请参见新旧值保留与覆盖。 |
field | Field | 是 | 待重命名的原字段名称。
|
示例
重命名指定字段。
* | project-rename log_level=level, log_err_msg=err_msg
expand-values
展开指定字段的第一层JSON对象,生成多条结果。
展开结果的数据类型为VARCHAR。如果结果字段与输入数据中字段重名,取值策略请参见新旧值保留与覆盖。
无法操作时间字段
__time__
和__time_ns_part__
,请参见时间字段。支持场景:数据加工(新版)。不同SPL使用场景请参见SPL在不同场景的功能定义。
语法
| expand-values -path=<path> -limit=<limit> -keep <field> as <output>
参数说明
参数 | 类型 | 必填 | 说明 |
path | JSONPath | 否 | 指定字段内容中的JSON路径,用于定位需要提取的内容位置。 默认值为空,表示直接提取指定字段的完整内容。 |
limit | Integer | 否 | 每条原始数据可展开的最大条目数,值为1至10之间的整数。默认值为10。 |
keep | Bool | 否 | 展开后是否保留原字段。默认不保留,需要保留时,打开此开关。 |
field | Field | 是 | 需要展开的原字段名称,支持类型为 |
output | Filed | 否 | 展开的目标字段名称。如果不指定,则默认输出结果至输入字段。 针对原始内容的展开逻辑为: JSON数组:根据数组的元素逐个展开。 JSON字典:根据字典键值对逐个展开。 其他JSON类型:返回原值。 非法JSON:返回 |
示例
示例1:展开数组,输出多条结果数据。
SPL语句
* | expand-values y
输入数据
x: 'abc' y: '[0,1,2]'
输出数据,展开为3条数据
# 条目1 x: 'abc' y: '0' # 条目2 x: 'abc' y: '1' # 条目3 x: 'abc' y: '2'
示例2:展开字典,输出多条结果数据。
SPL语句
* | expand-values y
输入数据
x: 'abc' y: '{"a": 1, "b": 2}'
输出数据,展开为2条数据
# 条目1 x: 'abc' y: '{"a": 1}' # 条目2 x: 'abc' y: '{"b": 2}'
示例3:展开指定JSON Path下的内容,并输出至新字段。
SPL语句
* | expand-values -keep content -path='$.body' as body
输入数据
content: '{"body": [0, {"a": 1, "b": 2}]}'
输出数据,展开为2条数据
# 条目1 content: '{"body": [1, 2]}' body: '0' # 条目2 content: '{"body": [1, 2]}' body: '{"a": 1, "b": 2}'
结构化数据SQL计算指令
extend
通过SQL表达式计算结果产生新字段。支持的SQL函数列表,请参见SPL支持的SQL函数列表。
语法
| extend <output>=<sql-expr>, ...
参数说明
参数 | 类型 | 必填 | 说明 |
output | Field | 是 | 添加的目标字段名称。不支持多个表达式结果输出至相同的目标字段。 重要 如果目标字段与输入数据中字段重名,则直接使用新的类型以及值将其覆盖。 |
sql-expr | SQLExpr | 是 | 数据处理表达式。 重要 关于null值处理,请参见SPL表达式null值处理。 |
示例
示例1:使用计算表达式。
* | extend Duration = EndTime - StartTime
示例2:使用正则表达式。
* | extend server_protocol_version=regexp_extract(server_protocol, '\d+')
示例3:提取JSON路径内容,并转换部分字段的数据类型。
SPL语句
* | extend a=json_extract(content, '$.body.a'), b=json_extract(content, '$.body.b') | extend b=cast(b as BIGINT)
输入数据
content: '{"body": {"a": 1, "b": 2}}'
输出结果
content: '{"body": {"a": 1, "b": 2}}' a: '1' b: 2
where
根据SQL表达式过滤数据,保留满足SQL表达式的数据条目。where指令支持的SQL函数列表,请参见SPL支持的SQL函数列表。
语法
| where <sql-expr>
参数说明
参数 | 类型 | 必填 | 说明 |
sql-expr | SQLExp | 是 | SQL表达式,保留满足此表达式的数据条目。 重要 SQL表达式中null值处理,请参见SPL表达式null值处理。 |
示例
示例1:根据字段内容过滤数据条目。
* | where userId='123'
示例2:使用匹配字段名的正则表达式过滤数据条目。
* | where regexp_like(server_protocol, '\d+')
示例3:转换数据类型后,匹配所有服务端错误数据。
* | where cast(status as BIGINT) >= 500
弱结构化数据提取指令
parse-regexp
提取指定字段中的正则表达式分组匹配信息。
语法
| parse-regexp <field>, <pattern> as <output>, ...
参数说明
参数 | 类型 | 必填 | 说明 |
field | Field | 是 | 需要提取的原始字段名称。 要求输入数据包含该字段,类型须为 |
pattern | Regexp | 是 | 正则表达式,支持RE2正则语法。 |
output | Field | 否 | 用于存储正则提取结果的字段名称。 |
示例
示例1:探索式逐个进行匹配。
SPL语句
* | parse-regexp content, '(\S+)' as ip -- 生成字段ip: 10.0.0.0。 | parse-regexp content, '\S+\s+(\w+)' as method -- 生成字段method: GET。
输入数据
content: '10.0.0.0 GET /index.html 15824 0.043'
输出结果
content: '10.0.0.0 GET /index.html 15824 0.043' ip: '10.0.0.0' method: 'GET'
示例2:完整模式匹配,使用非命名正则捕获。
SPL语句
* | parse-regexp content, '(\S+)\s+(\w+)' as ip, method
输入数据
content: '10.0.0.0 GET /index.html 15824 0.043'
输出结果
content: '10.0.0.0 GET /index.html 15824 0.043' ip: '10.0.0.0' method: 'GET'
parse-csv
提取指定字段中的CSV格式的信息。
语法
| parse-csv -delim=<delim> -quote=<quote> -strict <field> as <output>, ...
参数说明
参数 | 类型 | 必填 | 说明 |
delim | String | 否 | 数据内容的分隔字符为1至3个有效ASCII字符。 可使用转义符表示特殊字符,比如\t表示制表符、\11表示序号为八进制数11对应的ASCII字符、\x09表示序号为十六进制数09对应的ASCII字符。 也可使用多个字符组合作为分隔符,比如 默认值为英文逗号(,)。 |
quote | Char | 否 | 数据内容引用符是单个有效ASCII字符,在数据内容中包含分隔符时使用。 比如双引号(")、单引号(')以及不可见字符(0x01)。 默认不使用引用符。 重要 该参数仅在delim参数为单个字符时生效,且取值不能与delim相同。 |
strict | Bool | 否 | 当数据内容中值的数量与
默认为关闭,需要开启时,请添加此参数。 |
field | Field | 是 | 需要解析的原字段名称。 要求数据内容包含该字段,类型须为 |
output | Field | 是 | 用于存储数据内容解析结果的字段名称。 |
示例
示例1:简单数据匹配。
SPL语句
* | parse-csv content as x, y, z
输入数据
content: 'a,b,c'
输出结果
content: 'a,b,c' x: 'a' y: 'b' z: 'c'
示例2:默认使用双引号作为引用符,匹配包含特殊字符的内容。
SPL语句
* | parse-csv content as ip, time, host
输入数据
content: '192.168.0.100,"10/Jun/2019:11:32:16,127 +0800",example.aliyundoc.com'
输出结果
content: '192.168.0.100,"10/Jun/2019:11:32:16,127 +0800",example.aliyundoc.com' ip: '192.168.0.100' time: '10/Jun/2019:11:32:16,127 +0800' host: 'example.aliyundoc.com'
示例3:使用多字符组合作为分隔符。
SPL语句
* | parse-csv -delim='||' content as time, ip, req
输入数据
content: '05/May/2022:13:30:28||127.0.0.1||POST /put?a=1&b=2'
输出结果
content: '05/May/2022:13:30:28||127.0.0.1||POST /put?a=1&b=2' time: '05/May/2022:13:30:28' ip: '127.0.0.1' req: 'POST /put?a=1&b=2'
parse-json
提取指定字段中的第一层JSON信息。
语法
| parse-json -mode=<mode> -path=<path> -prefix=<prefix> <field>
参数说明
参数 | 类型 | 必填 | 说明 |
mode | String | 否 | 如果新字段与输入数据中字段重名,指定其结果取值模式。默认值为overwrite。 |
path | JSONPath | 否 | 指定字段内容中的JSON路径,用于定位需要提取的内容位置。 默认值为空字符串,表示直接提取指定字段的完整内容。 |
prefix | String | 否 | JSON结构展开的结果字段前缀,默认为空字符串。 |
field | Field | 是 | 需要解析的原字段名称。 要求输入数据包含该字段,其值为非null,且满足以下条件之一。否则,不执行提取操作。
|
示例
示例1:提取y字段中的所有键值。
SPL语句
* | parse-json y
输入数据
x: '0' y: '{"a": 1, "b": 2}'
输出结果
x: '0' y: '{"a": 1, "b": 2}' a: '1' b: '2'
示例2:提取content字段中的body键对应的内容,并将其所有键值提取为字段。
SPL语句
* | parse-json -path='$.body' content
输入数据
content: '{"body": {"a": 1, "b": 2}}'
输出结果
content: '{"body": {"a": 1, "b": 2}}' a: '1' b: '2'
示例3:指定字段值输出模式为preserve,对于已有字段,保留原始值。
SPL语句
* | parse-json -mode='preserve' y
输入数据
a: 'xyz' x: '0' y: '{"a": 1, "b": 2}'
输出结果
x: '0' y: '{"a": 1, "b": 2}' a: 'xyz' b: '2'
parse-kv
提取指定字段中的键值对信息。
语法
| parse-kv -mode=<mode> -prefix=<prefix> -regexp <field>, <pattern>
参数
参数 | 类型 | 必填 | 说明 |
mode | String | 否 | 如果相应的目标字段已存在于输入数据中,可选择数据覆盖模式。 默认值为overwrite。具体参考字段值覆盖模式。 |
prefix | String | 否 | 提取结果输出字段名前缀,默认为空字符串。 |
regexp | Bool | 是 | 开启正则提取模式。 |
field | Field | 是 | 需要提取的原始字段名称。 要求输入数据包含该字段,类型须为 |
pattern | RegExpr | 是 | 包含2个正则捕获组的正则表达式,第1个捕获组提取字段名,第2个捕获组提取字段值,支持RE2正则语法。 |
示例
示例1:正则提取模式,处理复杂的键值对之间的定界符、以及键与值之间的分隔符。
SPL语句
* | parse-kv -regexp content, '([^&?]+)(?:=|:)([^&?]+)'
输入数据
content: 'k1=v1&k2=v2?k3:v3' k1: 'xyz'
输出数据
content: 'k1=v1&k2=v2?k3:v3' k1: 'v1' k2: 'v2' k3: 'v3'
示例2:正则提取模式,并指定字段值输出模式为preserve,对于已有字段,保留原始值。
SPL语句
* | parse-kv -regexp -mode='preserve' content, '([^&?]+)(?:=|:)([^&?]+)'
输入数据
content: 'k1=v1&k2=v2?k3:v3' k1: 'xyz'
输出结果
content: 'k1=v1&k2=v2?k3:v3' k1: 'xyz' k2: 'v2' k3: 'v3'
示例3:正则提取模式,提取复杂非结构数据,值格式为数字或者双引号包裹的字符串。
SPL语句
* | parse-kv -regexp content, '([^&?]+)(?:=|:)([^&?]+)'
输入数据
content: 'verb="GET" URI="/healthz" latency="45.911µs" userAgent="kube-probe/1.30+" audit-ID="" srcIP="192.168.123.45:40092" contentType="text/plain; charset=utf-8" resp=200'
输出结果
content: 'verb="GET" URI="/healthz" latency="45.911µs" userAgent="kube-probe/1.30+" audit-ID="" srcIP="192.168.123.45:40092" contentType="text/plain; charset=utf-8" resp=200' verb: 'GET' URI: '/healthz' latency: '45.911µs' userAgent: 'kube-probe/1.30+' audit-ID: '' srcIP: '192.168.123.45:40092' contentType: 'text/plain; charset=utf-8' resp: '200'