extend（欄位擴充） - Cloud Monitor

extend 節點基於運算式計算新列或覆蓋已有列，適用於正則提取、類型轉換、欄位拼接和資料清洗等情境。

功能說明

extend 節點對每一行資料計算運算式，將結果作為新列追加或覆蓋同名已有列。支援所有內建 SQL 函數，包括字串函數、數學函數、正則函數和日期函數等。

每條記錄獨立計算，不改變行數。

正則提取：從原始文本中提取特定內容，例如使用者提問部分。
類型轉換：將字串轉為數值等。
拼接計算：組合多個欄位產生新的派生欄位。
資料清洗：去除空白字元、統一格式等。

節點配置

extend 節點的基本 JSON 配置結構如下：

{
  "id": "node_1",
  "type": "extend",
  "parameters": {
    "<欄位名>": "<運算式>",
    "<欄位名>": "<運算式>"
  }
}

參數說明

參數	類型	必填	預設值	說明
`<欄位名>`	String	是	-	鍵為目標列名，值為計算運算式。至少包含一組索引值對。列名已存在則覆蓋，不存在則新增。

說明

支援的函數：所有 SQL 內建函數均可使用，包括但不限於：

字串函數：concat、substr、regexp_extract、replace、trim、lower、upper
數學函數：abs、ceil、floor、round
類型轉換：cast、try_cast
條件函數：if、case when、coalesce、nullif

輸入與輸出

輸入要求

上遊節點輸出的任意列資料。
運算式中引用的欄位必須存在於輸入資料中。

輸出資料行

列名	類型	來源	說明
全部原始輸入列	-	透傳	保留全部上遊列
`parameters` 中的每個鍵	由運算式決定	新增/覆蓋	同名列被覆蓋，新名稱列被追加

行數變化

輸出行數等於輸入行數（M = N），每行獨立計算。

使用樣本

樣本 1：正則提取

{
  "id": "n2",
  "type": "extend",
  "parameters": {
    "question": "regexp_extract(question, '使用者提問：(.*)', 1)"
  }
}

從 question 欄位中提取"使用者提問："後面的內容，覆蓋原 question 列。

樣本 2：新增衍生的資料行

{
  "id": "n2",
  "type": "extend",
  "parameters": {
    "summary": "concat(question, ' - ', output)",
    "q_len": "length(question)"
  }
}

新增 summary 和 q_len 兩個衍生的資料行。summary 拼接 question 和 output 欄位，q_len 計算 question 欄位的長度。

樣本 3：管道組合

以下樣本展示 project（欄位選取）→ extend → where（篩選過濾）的組合模式，完成映射、轉換、過濾的完整流程。

{
  "nodes": [
    {
      "id": "n1", "type": "project",
      "parameters": { "question": "a", "input": "b", "output": "c" }
    },
    {
      "id": "n2", "type": "extend",
      "parameters": { "question": "regexp_extract(question, '使用者提問：(.*)', 1)" }
    },
    {
      "id": "n3", "type": "where",
      "parameters": { "filter": "length(question) > 10" }
    }
  ]
}

常見用法與異常處理

常見用法

適用於欄位派生計算：正則提取、字串處理、類型轉換、JSON 欄位提取等。
列名與已有列同名時覆蓋原列，可利用此特性做原地轉換（如清洗、格式化）。
常與where（篩選過濾）搭配：先用 extend 計算衍生的資料行，再用 where 基於衍生的資料行過濾。
運算式支援所有 SQL 純量涵式，例如 regexp_extract、length、json_extract 等。
一個 extend 節點可同時定義多個衍生的資料行，無需拆分為多個節點。
LLM 輸出的 JSON 結果可通過 extend + json_extract 提取具體欄位。

異常處理

情境	行為
`parameters` 為空白	校正失敗，至少需要一組運算式。
運算式中引用的欄位不存在	運行時報錯。
運算式語法錯誤	運行時報錯，提示運算式解析失敗。
列名與已有列衝突	覆蓋已有列（設計意圖，用於原地轉換）。

節點	關係說明
project（欄位選取）	通常在 `project` 之後使用 `extend` 做欄位擴充。
where（篩選過濾）	`extend` 計算的新列可作為 `where` 的過濾條件。
llm-call（LLM調用）	`extend` 產生的派生欄位可傳入 LLM 處理。