全部產品
Search
文件中心

DataWorks:開發SQL組件任務

更新時間:Mar 13, 2025

組件是一種帶有多個輸入參數和輸出參數的SQL代碼過程模板,而SQL代碼過程可通過引入一個或多個來源資料表,並進行過濾、串連、彙總等操作,加工出業務所需的目標表,因此,您可通過組件快速加工出符合業務需求的目標表。本文為您介紹組件的相關內容以及定義與使用。

SQL組件概述

組件介紹

在實際業務實踐中,存在大量類似的SQL代碼過程,過程中輸入表和輸出表的結構一致或結構類型相容,僅名稱不同。此時,組件的開發人員可將該SQL過程抽象為一個SQL元件節點,將可變的輸入表抽象為輸入參數,可變的輸出表抽象為輸出參數,實現SQL代碼的複用。

後續在使用SQL元件節點時,只需從程式碼群組件列表中選擇和自己的業務處理過程類似的組件,並為該組件配置自己業務中特定的輸入表和輸出表,無需再次編輯代碼,便可直接產生新的SQL元件節點,極大提升了開發效率,避免重複開發。SQL元件節點產生後的發布、調度操作,與普通SQL節點的操作方式相同。

許可權說明

您需具備DataWorks工作空間的開發許可權,才可建立並使用組件。授權詳情請參見增加空間成員並管理成員角色許可權

使用限制

  • 僅DataWorks標準版及以上版本,才可使用SQL元件節點功能。詳情請參見DataWorks各版本詳解

  • 本工作空間成員建立的組件在組件下。

  • 租戶成員建立的組件在公用組件下。

組件類型

組件分為專案組件及公用組件,組件開發人員(即建立組件的使用者)在建立組件時可自行定義。

  • 專案組件:組件發布後,預設僅該DataWorks工作空間的使用者均可使用。若您希望使用該類組件,則需成為此工作空間的成員,詳情請參見增加空間成員並管理成員角色許可權

  • 公用組件:組件的開發人員可進入公開組件頁簽,將具有全域通用性的組件發布到整個租戶內,發布後,租戶內所有使用者均可使用該公用組件。

組件使用流程

在DataWorks中建立的組件需與DataWorks的SQL元件節點配合使用,具體流程如下:

  1. 定義SQL組件

    組件開發人員可通過資料開發(DataStudio)的組件管理介面,定義通用邏輯的過程體代碼及輸入輸出參數,通過編寫抽象的SQL加工過程,將指定的輸入表通過輸入參數進行加工處理,產生有業務價值的輸出表(即輸出參數)。代碼中輸入參數和輸出參數的格式為@@{參數名}

    • 輸入參數支援如下類型:

      • 表類型的參數:若加工表時,輸出結果類別單一恒定,請使用該類型。

      • 字串類型的參數:若加工表時,需通過變數控制輸入參數的取值,請使用該類型。

    • 輸出參數實際使用時請配置為表類型的參數。

  2. 引用SQL組件

    組件使用者需在資料開發介面,通過建立SQL元件節點引用所需組件,替換組件中的輸入與輸出參數,實現代碼複用。

定義SQL組件

進入組件管理頁面

  1. 進入資料開發頁面。

    登入DataWorks控制台,切換至目標地區後,單擊左側導覽列的資料開發與營運 > 資料開發,在下拉框中選擇對應工作空間後單擊進入資料開發

  2. 在左側導覽列單擊組件管理,進入組件管理頁面。

    說明

    若左側導覽列不存在組件管理,則可單擊左下角的設定表徵圖,根據模組管理自行添加。

建立並配置組件

以下為您介紹組件開發人員如何通過組件管理新群組件,將指定的SQL過程抽象為一個SQL模板。一個組件通常由過程體、輸入參數、輸出參數組成。過程體用於定義組件功能的實現代碼,在過程體中,通過@@{變數名}格式,將可變的輸入表或輸入字串抽象為組件的輸入參數,將可變的輸出表抽象為組件的輸出參數,實現SQL代碼的複用。

說明

一個組件可配置多個輸入參數和輸出參數,具體請根據實際使用進行配置。

過程體

步驟一:建立組件

組件管理頁面,您可通過如下方式建立組件並輸入組件名稱。建立組件

說明
  • 本工作空間成員建立的組件在組件下。

  • 租戶成員建立的組件在公用組件下。

步驟二:配置組件資訊

  1. 配置過程體。

    過程體即為組件的實現代碼。通過編寫抽象的SQL代碼(即SQL加工過程),使用@@{參數名}格式,引入輸入參數和輸出參數,將指定的輸入表通過輸入參數進行加工處理,產生有業務價值的輸出表。後續使用組件時,只需配置不同的輸入參數和輸出參數,便可通過該代碼模板產生正確可啟動並執行SQL代碼。

  2. 配置輸入參數。

    定義過程體的輸入參數,支援TableString類型,即過程體的輸入參數為某表或某字串,具體如下。

    • Table:若使用組件加工源表資料時,輸出結果類別單一恒定,則請使用該類型。

      該類型的主要配置說明如下。

      配置項

      描述

      配置樣本

      參數定義

      用於將輸入表的結構進行文本化呈現,其中可包含表的欄位、欄位類型及欄位含義等內容。通過該形式,告知組件使用者,在使用組件時需為輸入參數配置與輸入表結構參數個數相同,類型相容的輸入表。防止配置的輸入表和組件定義的輸入表欄位個數不一致、欄位類型不相容,導致組件運行時出錯。

      說明

      該定義僅為參考,為您提供輸出參數配置的協助指示,並不會即時強制檢查。

      參數定義的格式建議為:

      欄位1名 欄位1類型 欄位1注釋 
      欄位2名 欄位2類型 欄位2注釋 
      ……
      欄位n名 欄位n類型 欄位n注釋

      樣本如下:

      area_id string ‘地區id’ 
      city_id string ‘城市id’ 
      order_amt double ‘訂單金額’ 
    • String:若使用組件加工源表資料時,需通過變數控制輸入參數的取值,則請使用該類型。

      該類型的主要配置說明如下。

      配置相關

      描述

      預設值

      該類型支援設定參數預設值,設定後,組件使用過程中預設使用所配置的參數預設值。

      情境樣本

      • 情境一:組件過程的輸出表需輸出每個地區前N個城市的銷售額,則可設定N為該組件的輸入參數,N的取值可通過字串型別參數進行控制。

      • 情境二:組件過程的輸出表需輸出省份的銷售總額,可設定一個省份字串參數作為該組件的輸入參數,通過指定不同的省份,擷取相應省份的銷售資料。

  3. 配置輸出參數。

    定義過程體的輸出參數,即組件最終產出表。為便於組件使用者使用組件,您可在輸出參數配置中,填寫使用該組件後輸出表的表結構,供組件使用者參考。

    輸出參數的主要配置說明如下:

    配置項

    描述

    配置樣本

    參數定義

    用於將輸出表的結構進行文本化呈現,其中可包含表的欄位、欄位類型及欄位含義等內容。通過該形式,告知組件使用者,在使用組件時需為輸出參數配置與輸出表結構參數個數相同,類型相容的輸出表。防止配置的輸出表和組件定義的輸出表欄位個數不一致、欄位類型不相容,導致組件運行時出錯。

    說明

    該定義僅為參考,為您提供輸出參數配置的協助指示,並不會即時強制檢查。

    參數定義的格式建議為:

    欄位1名 欄位1類型 欄位1注釋 
    欄位2名 欄位2類型 欄位2注釋 
    ……
    欄位n名 欄位n類型 欄位n注釋

    除此之外,輸出參數定義還可根據您所需的處理結果,添加匯總輸出結果欄位。例如,排名、總收入等。

    樣本如下:

    area_id string ‘地區id’ 
    city_id string ‘城市id’ 
    order_amt double ‘訂單金額’ 
    rank bigint ‘排名’

步驟三:儲存並提交組件

單擊儲存表徵圖,儲存組件;單擊提交表徵圖,提交組件。組件建立完成後,可在SQL元件節點中引用,協助您快速產生業務所需的目標表。使用詳情請參見引用SQL組件

引用SQL組件

前提條件

引用組件

您需在已建立的SQL元件節點的編輯頁面引用組件:image.png

  1. 選擇所需引用的組件。

    如果沒有可用組件,請參考定義SQL組件建立。

    • 若所選組件存在最新版本,您可根據業務需要選擇是否更新代碼版本,引用最新組件版本。

    • 單擊開啟組件即可查看組件詳情。

  2. 根據實際使用配置組件參數值。

後續步驟

當您完成當前節點的任務開發後,通常您可進行以下操作。

  • 調度配置:配置節點的周期性調度屬性。任務需要周期性調度運行時,您需要設定節點後續實際運行過程中的重跑屬性、調度依賴關係等,操作詳情請參見任務調度屬性配置概述

  • 任務調試:對當前節點的代碼進行測試回合,確認代碼邏輯符合預期,操作詳情請參見任務調試流程

  • 任務發布:完成所有開發相關操作後,您需要將所有任務節點進行發布,發布後節點將根據調度配置結果進行周期性運行,操作詳情請參見發布任務

管理組件

分享及查看組件的引用記錄

您可根據業務需要分享組件或查看組件的引用記錄。分享及查看引用記錄

  • 分享組件(序號1):組件發布後,預設為專案組件,即僅支援當前DataWorks工作空間的使用者使用該組件。組件開發人員可通過分享組件,將具有全域通用性的組件發布到整個租戶內,分享組件並發布後,租戶內所有使用者均可使用該組件。

  • 查看組件的引用記錄(序號2):可查看哪些節點引用了當前組件,用於進行組件變更時提前預估影響。

升級組件

升級操作:組件開發人員

組件開發人員可根據需要編輯組件代碼及相關參數配置,編輯完成後儲存提交即可升級為新版本組件,您可在地區3查看組件各個版本的詳情。組件升級

組件版本的使用影響:組件使用者

組件升級後,若您的SQL元件節點引用了該組件,則引用時可選擇是否使用該組件已升級的最新版本。若無需使用,則繼續引用原有版本;若使用,需確認新版本組件對於SQL元件節點的參數配置是否繼續生效,並根據新版本組件的說明進行相關調整,編輯完成後進行提交發布。提交發布流程同普通SQL節點相同。image.png

升級情境樣本

組件開發人員使用者C建立了V1.0版本組件,使用者A使用了該V1.0版本組件;隨後,使用者C將組件升級為V2.0版本。使用者A在使用過程中發現該組件已存在最新版本V2.0,則可開啟組件,查看不同版本詳情,對比後發現新版本組件業務效果更好,則可更新升級到最新的組件版本使用。

更多參考

使用組件介面功能介紹

介面

功能

說明

儲存

儲存當前組件的設定。

偷鎖編輯

非組件責任人可以鎖定編輯此節點。

提交

將當前組件提交到開發環境。

公開組件

將具有全域通用性的組件發布到整個租戶內,所有租戶的使用者都能看到該公用組件並可使用。

輸入輸出參數解析

解析當前代碼的輸入輸出參數。

運行

在本地(開發環境)運行組件。

停止運行

停止啟動並執行組件。

格式化

對當前組件代碼根據關鍵字格式排列。

參數配置

組件資訊、輸入參數、輸出參數配置。

版本

組件提交發布的記錄。

引用記錄

匯總組件被引用的記錄。

最佳實務

前提條件

步驟一:定義組件

您需先參考定義SQL組件建立get_top_n組件,組件配置詳情如下。image.png

  • 組件參數配置

    參數分類

    參數名稱

    參數類型

    參數描述

    參數定義

    輸入參數

    myinputtable

    table

    指定的銷售詳細資料表。

    area_id string
    city_id string
    order_amt double
    rank bigint

    topn

    string

    取銷售排行的前N名。

    不涉及

    輸出參數

    myoutput

    table

    目標輸出表,用於擷取各個地區下指定前N名的城市排行。

    area_id string
    city_id string
    order_amt double
    rank bigint
  • 組件過程體定義

    INSERT OVERWRITE TABLE  @@{myoutput}  PARTITION (pt='${bizdate}')
     SELECT r3.area_id,
     r3.city_id,
     r3.order_amt,
     r3.rank
    from (
    SELECT
       area_id,
       city_id,
       rank,
       order_amt_1505468133993_sum as order_amt ,
       order_number_1505468133991_sum,
       profit_amt_1505468134000_sum
    FROM
       (SELECT
       area_id,
       city_id,
       ROW_NUMBER() OVER (PARTITION BY r1.area_id ORDER BY r1.order_amt_1505468133993_sum DESC) AS rank,
       order_amt_1505468133993_sum,
       order_number_1505468133991_sum,
       profit_amt_1505468134000_sum
    FROM
       (SELECT
       area AS area_id,
       city AS city_id,
       SUM(order_amt) AS order_amt_1505468133993_sum,
       SUM(order_number) AS order_number_1505468133991_sum,
       SUM(profit_amt) AS profit_amt_1505468134000_sum
    FROM
      @@{myinputtable}
    WHERE
       SUBSTR(pt, 1, 8) IN ( '${bizdate}' )
    GROUP BY
       area,
       city )
       r1 ) r2
    WHERE
       r2.rank >= 1 AND r2.rank <= @@{topn}
    ORDER BY
       area_id,
       rank limit 10000) r3;

步驟二:使用組件

您需參考引用SQL組件建立xc_引用組件_get_top_nSQL元件節點,引用步驟一建立的get_top_n組件,並配置相應的參數值,步驟如下圖。image.png參數值說明如下:

  • 輸入參數myinputtable:為該參數指定一個輸入表company_sales_record,作為資料輸入源。輸入表的結構如下:

    company_sales_record

    CREATE TABLE IF NOT EXISTS company_sales_record
    (
        order_id         STRING COMMENT '訂單編號(PK)',
        report_date      STRING COMMENT '訂單日期',
        customer_name    STRING COMMENT '客戶名稱',
        order_level      STRING COMMENT '訂單等級',
        order_number     DOUBLE COMMENT '訂單數量',
        order_amt        DOUBLE COMMENT '訂單金額',
        back_point       DOUBLE COMMENT '折扣點',
        shipping_type    STRING COMMENT '運輸方式',
        profit_amt       DOUBLE COMMENT '利潤金額',
        price            DOUBLE COMMENT '單價',
        shipping_cost    DOUBLE COMMENT '運輸成本',
        area             STRING COMMENT '地區',
        province         STRING COMMENT '省份',
        city             STRING COMMENT '城市',
        product_type     STRING COMMENT '產品類型',
        product_sub_type STRING COMMENT '產品小類',
        product_name     STRING COMMENT '產品名稱',
        product_box      STRING COMMENT '產品包箱',
        shipping_date    STRING COMMENT '運輸日期'
    ) 
    COMMENT '銷售資料的明細資訊'
    PARTITIONED BY
    (
        pt               STRING
    )
    LIFECYCLE 365;
  • 輸入參數topn:為該參數指定按照銷售額正序排序,每個地區的城市排行取前多少名。樣本取前10名。

  • 輸出參數myoutput:為該參數指定加工輸出的結果的表名稱company_sales_top_n。輸出表的結構如下:

    company_sales_top_n

    CREATE TABLE IF NOT EXISTS company_sales_top_n
    ( 
    area STRING COMMENT '地區', 
    city STRING COMMENT '城市', 
    sales_amount DOUBLE COMMENT '銷售額', 
    rank BIGINT COMMENT '排名'
    )
    COMMENT '公司銷售熱門排行榜'
    PARTITIONED BY (pt STRING COMMENT '')
    LIFECYCLE 365;