doc-stats資料統計節點 - Cloud Monitor

doc-stats 節點對指定文字欄位計算多項文檔級統計指標（字元數、詞數、行數等），彙總輸出為一個 JSON 列。每條記錄獨立計算，不改變行數。

適用情境

資料品質檢查：基於文本長度過濾過短或過長的異常記錄。
Pipeline 運行統計：瞭解各處理階段的文本長度分布。
Dataset 中繼資料：為每條記錄附加標準化的文本統計資訊。

節點配置

在 Pipeline JSON 中添加 doc-stats 類型節點，配置樣本如下：

{
  "id": "node_1",
  "type": "doc-stats",
  "parameters": {
    "field": "<欄位名>",
    "as": "<輸出資料行名>",
    "output": "<輸出資料行列表>"
  }
}

參數說明

參數	類型	必填	預設值	說明
`field`	String	是	-	待統計的文字欄位名。
`as`	String	否	`__doc_stats`	輸出統計列的列名。
`output`	String	否	`*`	節點輸出資料行，多列以半形逗號分隔。`*`（預設）保留全部列含擴充列；指定時僅輸出資料行出的列。

輸入和輸出

輸入要求

上遊節點輸出的任意列資料。
要求包含 field 參數指定的欄位。

輸出資料行

列名	類型	來源	說明
`output` 指定列	-	透傳	`*` 保留全部原始輸入列。
`{as}`	JSON	新增	文檔統計 JSON，包含字元數、詞數、行數等指標。

統計指標（JSON 內部結構）

Key	類型	說明
`doc_len_char`	bigint	文本字元數。
`doc_len_words`	bigint	文本詞數（按空格分詞）。
`line_counts`	bigint	文本行數。

樣本輸出：

{"doc_len_char": 42, "doc_len_words": 8, "line_counts": 1}

行數變化

M to N（M = N）：1:1 變換，不增減行數。

效果預覽

處理前（3 條）：

question	input	output
什麼是機器學習？	請解釋	機器學習是人工智慧的一個分支
如何學習Python？請推薦一些入門資源	入門	推薦從官方教程開始然後做專案
AI	簡述	人工智慧

處理後（3 條，field = "question"）：

question	input	output	__doc_stats
什麼是機器學習？	請解釋	機器學習是...	`{"doc_len_char":8,"doc_len_words":1,"line_counts":1}`
如何學習Python？請推薦...	入門	推薦從...	`{"doc_len_char":18,"doc_len_words":1,"line_counts":1}`
AI	簡述	人工智慧	`{"doc_len_char":2,"doc_len_words":1,"line_counts":1}`

行數不變（3 to 3），每行新增統計 JSON 列。可結合 where 節點按字元數過濾過短或過長文本。

使用樣本

樣本 1：基礎文檔統計

統計 question 欄位，輸出資料行名為預設的 __doc_stats。

{
  "id": "n5",
  "type": "doc-stats",
  "parameters": {
    "field": "question"
  }
}

樣本 2：自訂輸出資料行名

通過 as 參數將輸出資料行名自訂為 question_stats。

{
  "id": "n5",
  "type": "doc-stats",
  "parameters": {
    "field": "question",
    "as": "question_stats"
  }
}

樣本 3：結合過濾使用

先通過 doc-stats 計算統計指標，再通過 where 節點過濾掉過短的文本。

{
  "nodes": [
    { "id": "n1", "type": "project", "parameters": { "question": "a", "output": "c" } },
    { "id": "n2", "type": "doc-stats", "parameters": { "field": "question" } },
    { "id": "n3", "type": "where", "parameters": { "filter": "json_extract_scalar(__doc_stats, '$.doc_len_char') > '10'" } }
  ]
}

使用建議

結合 where 節點實現資料品質過濾：先統計再按指標過濾過短或過長文本。
在 Pipeline 末尾使用，為 Dataset 輸出附加標準化的文本中繼資料。
在 LLM 處理後統計輸出文本長度，輔助品質監控。
使用 json_extract_scalar 提取具體指標值，例如 json_extract_scalar(__doc_stats, '$.doc_len_char')。
通過 as 參數自訂輸出資料行名（預設 __doc_stats），便於多欄位分別統計。
本節點不依賴遠程函數，計算開銷極低，可在 Pipeline 任意位置使用。

異常處理

情境	行為
`field` 缺失	校正失敗。
`field` 欄位值為 NULL	統計值為 `{"doc_len_char": 0, "doc_len_words": 1, "line_counts": 1}`。
文本為空白字串	與 NULL 處理類似。
輸入資料為空白	正常返回空結果集。

實現說明

doc-stats 在 SPL 層面不作為獨立運算元封裝，API 翻譯時直接產生等價的 extend 運算式。

API → SPL 翻譯樣本：

{ "field": "question", "as": "question_stats" }

↓ 翻譯為：

extend question_stats=cast(map(array['doc_len_char','doc_len_words','line_counts'],array[cast(length(coalesce(question,'')) as bigint),cast(cardinality(split(coalesce(question,''),' ')) as bigint),cast(cardinality(split(coalesce(question,''),chr(10))) as bigint)]) as json)

節點	關係說明
`where`	計算統計後可通過 `where` 按指標過濾
`llm-call`	可在 AI 處理後統計輸出文本的品質指標