正則式函數文法及樣本 - Simple Log Service

正則式函數概覽

Log Service支援如下正則式函數（Regex採用RE2文法）。

重要在Log Service分析語句中，表示字串的字元必須使用單引號（''）包裹，無符號包裹或被雙引號（""）包裹的字元表示欄位名或列名。例如：'status'表示字串status，status或"status"表示日誌欄位status。

函數名稱	文法	說明	支援SQL	支援SPL
regexp_extract_all函數	regexp_extract_all(x, regular expression)	提取目標字串中符合Regex的子串，並返回所有子串的集合。	√	×
regexp_extract_all函數	regexp_extract_all(x, regular expression, n)	提取目標字串中符合Regex的子串，然後返回與目標擷取的群組匹配的子串集合。	√	×
regexp_extract函數	regexp_extract(x, regular expression)	提取並返回目標字串中符合Regex的第一個子串。	√	√
regexp_extract函數	regexp_extract(x, regular expression, n)	提取目標字串中符合Regex的子串，然後返回與目標擷取的群組匹配的第n個子串。	√	√
regexp_extract_bool函數	regexp_extract_bool(x, regular expression)	提取並返回目標字串中符合Regex的子串，並轉換為boolean類型，轉換失敗返回`null`。	√	×
regexp_extract_bool函數	regexp_extract_bool(x, regular expression, n)	提取目標字串中符合Regex的子串，然後返回與目標擷取的群組匹配的子串，並轉換為boolean類型，轉換失敗返回`null`。	√	×
regexp_extract_long函數	regexp_extract_long(x, regular expression)	提取並返回目標字串中符合Regex的子串，並轉換為bigint類型，轉換失敗返回`null`。	√	×
regexp_extract_long函數	regexp_extract_long(x, regular expression, n)	提取目標字串中符合Regex的子串，然後返回與目標擷取的群組匹配的子串，並轉換為bigint類型，轉換失敗返回`null`。	√	×
regexp_extract_double函數	regexp_extract_double(x, regular expression)	提取並返回目標字串中符合Regex的第一個子串，並轉換為double類型，轉換失敗返回`null`。	√	×
regexp_extract_double函數	regexp_extract_double(x, regular expression, n)	提取目標字串中符合Regex的子串，然後返回與目標擷取的群組匹配的子串，並轉換為double類型，轉換失敗返回`null`。	√	×
regexp_extract_map函數	regexp_extract_map(x, regular expression, keys)	指定鍵資訊，擷取的群組匹配子串作為值。	√	×
regexp_extract_map函數	regexp_extract_map(x, regular expression)	正則包含2個擷取的群組，分別匹配鍵和值。	√	×
regexp_like函數	regexp_like(x, regular expression)	判斷目標字串是否符合Regex。	√	√
regexp_replace函數	regexp_replace(x, regular expression)	刪除目標字串中符合Regex的子串，返回未被刪除的子串。	√	√
regexp_replace函數	regexp_replace(x, regular expression, replace string)	替換目標字串中符合Regex的子串，返回被替換後的字串。	√	√
regexp_split函數	regexp_split(x, regular expression)	使用Regex分割目標字串，返回被分割後的子串集合。	√	×

regexp_extract_all函數

regexp_extract_all函數用於提取目標字串中符合Regex的子串。

文法

提取目標字串中符合Regex的子串，並返回所有子串的集合。
```
regexp_extract_all(x, regular expression)
```
提取目標字串中符合Regex的子串，然後返回與目標擷取的群組匹配的子串集合。
```
regexp_extract_all(x, regular expression, n)
```

參數說明

參數	說明
x	參數值為varchar類型。
regular expression	包含擷取的群組的Regex。例如`(\d)(\d)(\d)`表示三個擷取的群組。
n	第n個擷取的群組。n為從1開始的整數。

傳回值類型

array類型。

樣本

樣本1：提取server_protocol欄位值中所有的數字。
- 欄位範例
```
server_protocol:HTTP/2.0
```
- 查詢和分析語句（調試）
```
*| SELECT regexp_extract_all(server_protocol, '\d+')
```
- 查詢和分析結果：查詢結果返回 _col0 列值為 ["2","0"]，即從 HTTP/2.0 中提取出的所有數字子串。
樣本2：提取http_user_agent欄位值中的Chrome部分，然後統計由Chrome瀏覽器發起的請求數量。
- 欄位範例
```
http_user_agent:Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/535.1 (KHTML, like Gecko) Chrome/14.0.803.0 Safari/535.1
```
- 查詢和分析語句（調試）
```
*| SELECT regexp_extract_all(http_user_agent, '(Chrome)',1) AS Chrome, count(*) AS count GROUP BY Chrome
```
- 查詢和分析結果：Chrome 列值為 ["Chrome"]，count 列值為 103440。

regexp_extract函數

regexp_extract函數用於提取目標字串中符合Regex的子串。

文法

提取並返回目標字串中符合Regex的第一個子串。
```
regexp_extract(x, regular expression)
```
提取目標字串中符合Regex的子串，然後返回與目標擷取的群組匹配的第n個子串。
```
regexp_extract(x, regular expression, n)
```

參數說明

參數	說明
x	參數值為varchar類型。
regular expression	包含擷取的群組的Regex。例如`(\d)(\d)(\d)`表示三個擷取的群組。
n	第n個擷取的群組。n為從1開始的整數。

傳回值類型

varchar類型。

樣本

SQL

樣本1：提取server_protocol欄位值中的第一個數字。
- 欄位範例
```
server_protocol:HTTP/2.0
```
- 查詢和分析語句（調試）
```
*|SELECT regexp_extract(server_protocol, '\d+')
```
- 查詢和分析結果返回一列 _col0，值為 2。
樣本2：提取request_uri欄位值中的檔案部分，然後統計各個檔案的訪問次數。
- 欄位範例
```
request_uri:/request/path-3/file-5
```
- 查詢和分析語句（調試）
```
* | SELECT regexp_extract(request_uri, '.*\/(file.*)', 1) AS file, count(*) AS count GROUP BY file
```
- 查詢和分析結果樣本：file 列為 file-5，count 列為 17127。
樣本3：提取message欄位值中的單引號（'）和數字部分。
- 欄位範例
```
message:error'1232
```
- 查詢和分析語句
```
* | SELECT regexp_extract(message, '''\d+') 
```
  說明
  使用正則式函數提取字串中的單引號（'）時，需要在Regex中再添加一個單引號（'）。
- 查詢和分析結果為'1232。

SPL

樣本1：提取server_protocol欄位值中的第一個數字。
- 欄位範例

server_protocol:HTTP/2.0

查詢和分析語句

* | extend a = regexp_extract(server_protocol, '\d+')

查詢和分析結果

a:  2

樣本2：提取request_uri欄位值中的檔案部分。
- 欄位範例

request_uri:/request/path-3/file-5

查詢和分析語句

* | extend a = regexp_extract(request_uri, '.*\/(file.*)',1)

查詢和分析結果

提取結果為 a: file-5。

樣本3：提取message欄位值中的單引號（'）和數字部分。
- 欄位範例

message:error'1232

查詢和分析語句

* | extend a = regexp_extract(message, '''\d+')

說明

使用Regex函數提取字串中的單引號（'）時，需要在Regex中再添加一個單引號（'）。

查詢和分析結果

1  12-19 10:39:33
   a: '1232

regexp_extract_bool函數

regexp_extract_bool函數用於提取目標字串中符合Regex的子串，並轉換成boolean類型，轉換失敗返回null。當該子串為"true"或"false"（不區分大小寫）時才轉換成功。

文法

提取並返回目標字串中符合Regex的子串，並轉換為boolean類型，轉換失敗返回null。
```
regexp_extract_bool(x, regular expression)
```
提取目標字串中符合Regex的子串，然後返回與指定擷取的群組匹配的子串，並轉換為boolean類型，轉換失敗返回null。
```
regexp_extract_bool(x, regular expression, n)
```

參數說明

參數	說明
x	參數值為varchar類型。
regular expression	包含擷取的群組的Regex。例如`(\d)(\d)(\d)`表示三個擷取的群組。
n	第n個擷取的群組。n為從1開始的整數。

傳回值類型

boolean類型。

樣本

提取欄位值中的boolean值。
- 欄位範例
```
false 
```
- 查詢和分析語句（調試）
```
*| select regexp_extract_bool('false', '[a-zA-Z]+')
```
- 查詢和分析結果
  
  返回一列 _col0，包含兩行資料，值均為 false。

regexp_extract_long函數

regexp_extract_long函數用於提取目標字串中符合Regex的子串，並轉換成bigint類型，轉換失敗返回null。

文法

提取並返回目標字串中符合Regex的子串，並轉換成bigint類型，轉換失敗返回null。
```
regexp_extract_long(x, regular expression)
```
提取目標字串中符合Regex的子串，然後返回與目標擷取的群組匹配的子串，並轉換成bigint類型，轉換失敗返回null。
```
regexp_extract_long(x, regular expression, n)
```

參數說明

參數	說明
x	參數值為varchar類型。
regular expression	包含擷取的群組的Regex。例如`(\d)(\d)(\d)`表示三個擷取的群組。
n	第n個擷取的群組。n為從1開始的整數。

傳回值類型

bigint類型。

樣本

提取time欄位中的數字。
- 欄位範例
```
time:19/Dec/2024:06:16:06
```
- 查詢和分析語句（調試）
```
*|SELECT regexp_extract_long(time, '(\d{2})/', 1) 
```
- 查詢和分析結果
  
  返回一列 _col0，共兩行，值均為 19。

regexp_extract_double函數

regexp_extract_double函數用於提取目標字串中符合Regex的子串，並轉換成double類型，轉換失敗返回null。

文法

提取並返回目標字串中符合Regex的子串，並轉換成double類型，轉換失敗返回null。
```
regexp_extract_double(x, regular expression)
```
提取目標字串中符合Regex的子串，返回與目標擷取的群組匹配的子串，並轉換成double類型，轉換失敗返回null。
```
regexp_extract_double(x, regular expression, n)
```

參數說明

參數	說明
x	參數值為varchar類型。
regular expression	包含擷取的群組的Regex。例如`(\d)(\d)(\d)`表示三個擷取的群組。
n	第n個擷取的群組。n為從1開始的整數。

傳回值類型

double類型。

樣本

提取server_protocol欄位中的數字。
- 欄位範例
```
server_protocol:HTTP/1.1
```
- 查詢和分析語句（調試）
```
*|SELECT regexp_extract_double(server_protocol, '\d+') 
```
- 查詢和分析結果
  
  查詢和分析結果返回一列 _col0，包含兩行資料，值均為浮點數 1.0。

regexp_extract_map函數

regexp_extract_map函數用於提取目標字串中符合Regex中所有擷取的群組的子串。

文法

指定鍵資訊，擷取的群組匹配子串作為值

regexp_extract_map(x, regular expression, keys)

正則包含2個擷取的群組，分別匹配鍵和值

regexp_extract_map(x, regular expression)

參數說明

參數	說明
x	參數值為varchar類型。
regular expression	包含擷取的群組的Regex。例如`(\d)(\d)(\d)`表示三個擷取的群組。
keys	捕獲子串輸出的key名稱。參數值為array(varchar)類型，元素數目與regular expression參數的擷取的群組數目保持一致。

傳回值類型

map(varchar, varchar)類型。

樣本

樣本1：提取server_protocol欄位中的協議名稱和版本。
- 欄位範例
```
server_protocol: 'HTTP/2.0'
```
- 查詢和分析語句
```
select regexp_extract_map(server_protocol, '(\w+)/([\d\.]+)', array['name', 'version']) as protocol
```
- 查詢和分析結果
  
  返回一條記錄，protocol 列的值為 {"name":"HTTP","version":"2.0"}。

樣本2：提取content欄位中的所有索引值對資訊。

欄位範例

content: 'verb="GET" URI="/healthz" latency="45.911µs" userAgent="kube-probe/1.30+"'

查詢和分析語句

select regexp_extract_map(content, '(\w+)="([^"]*)"') as args

輸出資料

{"latency":"45.911µs","verb":"GET","userAgent":"kube-probe/1.30+","URI":"/healthz"}

regexp_like函數

regexp_like函數用於判斷目標字串是否符合Regex。

文法

regexp_like(x, regular expression)

參數說明

參數	說明
x	參數值為varchar類型。
regular expression	Regex。

傳回值類型

boolean類型。

樣本

SQL

判斷server_protocol欄位值中是否包含數字。

欄位範例
```
server_protocol:HTTP/2.0
```

查詢和分析語句（調試）

*| select regexp_like(server_protocol, '\d+')

查詢和分析結果返回兩行資料，值均為 true，表示 server_protocol 欄位值匹配Regex \d+（包含數字）。

SPL

判斷server_protocol欄位值中是否包含數字

欄位範例

server_protocol:HTTP/2.0

查詢和分析語句

* |extend a = regexp_like(server_protocol, '\d+')

查詢和分析結果

1  12-18 19:34:20  1.2.3.4
        a: true

regexp_replace函數

刪除或替換目標字串中符合Regex的子串。

文法

刪除目標字串中符合Regex的子串，返回未被刪除的子串。
```
regexp_replace(x, regular expression)
```
替換目標字串中符合Regex的子串，返回被替換後的字串。
```
regexp_replace(x, regular expression, replace string)
```

參數說明

參數	說明
x	參數值為varchar類型。
regular expression	Regex。
replace string	用於替換的子串。

傳回值類型

varchar類型。

樣本

SQL

樣本1：將region欄位值中以cn開頭的地區名都替換為中國，然後統計來自中國的請求數量。
- 欄位範例
```
region:cn-shanghai
```
- 查詢和分析語句（調試）
```
* | select regexp_replace(region, 'cn.*','中國') AS region, count(*) AS count GROUP BY region
```
- 查詢和分析結果：查詢結果返回一行資料：region 列值為 中國，count 列值為 168871。
樣本2：刪除server_protocol欄位值中的版本號碼部分，然後統計不同通訊協定對應的請求數量。
- 欄位範例
```
server_protocol:HTTP/2.0
```
- 查詢和分析語句（調試）
```
*| select regexp_replace(server_protocol, '.\d+') AS server_protocol, count(*) AS count GROUP BY server_protocol
```
- 查詢和分析結果返回一行資料：server_protocol 為 HTTP，count 為 168871。

SPL

樣本1：將region欄位值中以cn開頭的地區名都替換為中國。
- 欄位範例

region:cn-shanghai

查詢和分析語句

* | extend a = regexp_replace(region, 'cn.*','中國')

查詢和分析結果
```
1  12-18 19:34:20  1.2.3.4
   a: 中國
```
樣本2：刪除server_protocol欄位值中的版本號碼部分。
- 欄位範例

server_protocol:HTTP/2.0

查詢和分析語句（調試）

* | extend a = regexp_replace(server_protocol, '.\d+')

查詢和分析結果

調試結果返回一條日誌條目，包含時間戳記及目標 IP 位址 1.2.3.4，其中 server_protocol 欄位的版本號碼部分已被成功刪除。

regexp_split函數

regexp_split函數用於分割目標字串，返回被分割後的子串集合。

文法

regexp_split(x, regular expression)

參數說明

參數	說明
x	參數值為varchar類型。
regular expression	Regex。

傳回值類型

array類型。

樣本

使用正斜線（/）分割request_uri欄位的值。

欄位範例
```
request_uri:/request/path-0/file-7
```

查詢和分析語句（調試）

* | SELECT regexp_split(request_uri,'/')

查詢和分析結果為 ["","request","path-0","file-7"]。