SPL指令 - Simple Log Service

本文介紹SPL指令的詳細資料。

參數類型說明

SPL指令中的參數類型說明如下表所示。

參數類型	說明
Bool	布爾型別參數。使用SPL時，該參數為切換參數。
Char	ASCII字元型別參數，需使用單引號（''）包裹，例如`'a'`表示字元a，`'\t'`表示定位字元、`'\11'`表示序號為八位元11對應的ASCII字元、`'\x09'`表示序號為十六進位數09對應的ASCII字元。
Integer	整數型別參數。
String	字串型別參數，需使用單引號（''）包裹，例如`'this is a string'`。
RegExp	RE2Regex型別參數，需使用單引號（''）包裹，例如`'([\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運算式型別參數。

SPL指令列表

指令類別	指令名稱	說明
欄位操作指令	project	保留與給定模式相匹配的欄位、同時可重新命名指定欄位。指令執行過程中，先完成所有欄位保留運算式的執行，再執行重新命名運算式。
	project-away	移除與給定模式相匹配的欄位，原樣保留其他所有欄位。
	project-rename	重新命名指定欄位，並保留其他所有欄位原樣。
	expand-values	展開指定欄位的第一層JSON對象，產生多條結果。
結構化資料SQL計算指令	extend	通過SQL運算式計算結果產生新欄位。支援的SQL函數列表，請參見SPL支援的SQL函數列表。
結構化資料SQL計算指令	where	根據SQL運算式過濾資料，保留滿足SQL運算式的資料條目。where指令支援的SQL函數列表，請參見SPL支援的SQL函數列表。
弱結構化資料提取指令	parse-regexp	提取指定欄位中的Regex分組匹配資訊。
	parse-csv	提取指定欄位中的CSV格式的資訊。
	parse-json	提取指定欄位中的第一層JSON資訊。
	parse-kv	提取指定欄位中的索引值對資訊。

欄位操作指令

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	是	需要展開的原欄位名稱，支援類型為`VARCHAR`。如果指定欄位不存在，則不執行展開操作。
output	Filed	否	展開的目標欄位名稱。如果不指定，則預設輸出結果至輸入欄位。針對原始內容的展開邏輯為： JSON數組：根據數組的元素逐個展開。 JSON字典：根據字典索引值對逐個展開。其他JSON類型：返回原值。非法JSON：返回`null`。

樣本

樣本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：使用Regex。

* | 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：使用匹配欄位名的Regex過濾資料條目。
```
* | where regexp_like(server_protocol, '\d+')
```
樣本3：轉換資料類型後，匹配所有服務端錯誤資料。
```
* | where cast(status as BIGINT) >= 500
```

弱結構化資料提取指令

parse-regexp

提取指定欄位中的Regex分組匹配資訊。

重要

提取結果的資料類型為VARCHAR。如果結果欄位與輸入資料中欄位重名，取值策略請參見新舊值保留與覆蓋。
無法操作時間欄位__time__和__time_ns_part__，請參見時間欄位。

文法

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

參數說明

參數	類型	必填	說明
field	Field	是	需要提取的原始欄位名稱。要求輸入資料包含該欄位，類型須為`VARCHAR`，且其值為非`null`。否則，不執行提取操作。
pattern	Regexp	是	Regex，支援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：非嚴格配對，按照最大化配對策略執行。值的數目多於欄位時，多餘值不輸出。欄位數多於值時，多餘欄位輸出Null 字元串。 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'
```

parse-kv

提取指定欄位中的索引值對資訊。

重要

提取結果的資料類型為VARCHAR。如果結果欄位與輸入資料中欄位重名，取值策略請參見新舊值保留與覆蓋。
無法操作時間欄位__time__和__time_ns_part__，請參見時間欄位。

文法

| parse-kv -mode=<mode> -prefix=<prefix> -regexp <field>, <pattern>

參數

參數	類型	必填	說明
mode	String	否	如果相應的目標欄位已存在於輸入資料中，可選擇資料覆蓋模式。預設值為overwrite。具體參考欄位值覆蓋模式。
prefix	String	否	提取結果輸出欄位名首碼，預設為空白字串。
regexp	Bool	是	開啟正則提模數式。
field	Field	是	需要提取的原始欄位名稱。要求輸入資料包含該欄位，類型須為`VARCHAR`，且其值為非`null`。否則，則不執行提取操作。
pattern	RegExpr	是	包含2個正則擷取的群組的Regex，第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'