文档

SPL指令

更新时间:

本文介绍SPL指令的详细信息。

参数类型说明

SPL指令中的参数类型说明如下表所示。

参数类型

说明

Bool

布尔类型参数。使用SPL时,该参数为开关参数。

Char

ASCII字符类型参数,需使用单引号('')包裹,例如'a'表示字符a,'\t'表示制表符、'\11'表示序号为八进制数11对应的ASCII字符、'\x09'表示序号为十六进制数09对应的ASCII字符。

Integer

整数类型参数。

String

字符串类型参数,需使用单引号('')包裹,例如'this is a string'

RegExp

RE2正则表达式类型参数,需使用单引号('')包裹,例如'([\d.]+)'

语法定义,请参见Syntax

JSONPath

JSON路径类型参数,需使用单引号('')包裹,例如'$.body.values[0]'

语法定义,请参见JsonPath

Field

字段名类型参数,例如| project level, content

如果字段名中包含字母、数字、下划线以外的特殊字符,需使用双引号("")包裹,例如 | project "a:b:c"

说明

关于字段名称大小写敏感详情,请参见SPL在不同场景的功能定义

FieldPattern

字段名和通配符组合或者字段名类型参数。支持通配符号*,表示匹配0个或多个任意字符。需使用双引号("")包裹,例如| project "__tag__:*"

说明

关于字段名称大小写敏感详情,请参见SPL在不同场景的功能定义

SPLExp

SPL表达式类型参数。

SQLExp

SQL表达式类型参数。

字段操作指令

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

结构化数据SQL计算指令

extend

通过SQL表达式计算结果产生新字段。支持的SQL函数列表,请参见SPL支持的SQL函数列表

语法

| extend <output>=<sql-expr>, ...

参数说明

参数

类型

必填

说明

output

Field

添加的目标字段名称。不支持多个表达式结果输出至相同的目标字段。

重要

如果目标字段与输入数据中字段重名,则直接使用新的类型以及值将其覆盖。

sql-expr

SQLExpr

数据处理表达式。

重要

关于null值处理,请参见SQL表达式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值处理,请参见SQL表达式null值处理

示例

  • 示例1:根据字段内容过滤数据条目。

    * | where userId='123'
  • 示例2:使用匹配字段名的正则表达式过滤数据条目。

    * | where regexp_like(server_protocol, '\d+')
  • 示例3:转换数据类型后,匹配所有服务端错误数据。

    * | where cast(status as BIGINT) >= 500

弱结构化数据提取指令

parse-regexp

提取指定字段中的正则表达式分组匹配信息。

重要
  • 提取结果的数据类型为VARCHAR。如果结果字段与输入数据中字段重名,取值策略请参见新旧值保留与覆盖

  • 无法操作时间字段__time__和__time_ns_part__,请参见时间字段

语法

| parse-regexp <field>, <pattern> as <output>, ...

参数说明

参数

类型

必填

说明

field

Field

需要提取的原始字段名称。

要求输入数据包含该字段,类型须为VARCHAR,且其值为非null。否则,不执行提取操作。

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格式的信息。

重要
  • 提取结果的数据类型为VARCHAR。如果结果字段与输入数据中字段重名,取值策略请参见新旧值保留与覆盖

  • 无法操作时间字段__time__和__time_ns_part__,请参见时间字段

语法

| 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

当数据内容中值的数量与output中指定字段不一致时,是否开启严格配对。

  • False:非严格配对,按照最大化配对策略执行。

    • 值的数目多于字段时,多余值不输出。

    • 字段数多于值时,多余字段输出空字符串。

  • True:严格配对,不输出任何字段。

默认为关闭,需要开启时,请添加此参数。

field

Field

需要解析的原字段名称。

要求数据内容包含该字段,类型须为VARCHAR,且其值为非null。否则,不执行提取操作。

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信息。

重要
  • 提取结果的数据类型为VARCHAR。如果结果字段与输入数据中字段重名,取值策略请参见新旧值保留与覆盖

  • 无法操作时间字段__time__和__time_ns_part__,请参见时间字段

语法

| parse-json -mode=<mode> -path=<path> -prefix=<prefix> <field>

参数说明

参数

类型

必填

说明

mode

String

如果新字段与输入数据中字段重名,指定其结果取值模式。默认值为overwrite。

path

JSONPath

指定字段内容中的JSON路径,用于定位需要提取的内容位置。

默认值为空字符串,表示直接提取指定字段的完整内容。

prefix

String

否​

JSON结构展开的结果字段前缀,默认为空字符串。

field

Field

需要解析的原字段名称。

要求输入数据包含该字段,其值为非null,且满足以下条件之一。否则,则不执行提取操作。

  • 类型为JSON

  • 类型为VARCHAR,且值为合法JSON字符串

示例

  • 示例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'