全部產品
Search
文件中心

Realtime Compute for Apache Flink:自訂純量涵式(UDSF)

更新時間:Sep 22, 2026

本文為您介紹如何開發、註冊和使用Flink自訂純量涵式(UDSF)。

定義

自訂純量涵式(UDSF)將0個、1個或多個標量值對應到一個新的標量值。輸入與輸出是一對一的關係,即讀入一行資料,寫出一條輸出值。詳情參見User-defined Functions。

UDSF開發

說明

Flink為您提供了UDF樣本,便於您快速開發業務。Flink UDF樣本中包含UDSF、UDAF和UDTF的實現,樣本中已為您配置對應版本的開發環境,您無需進行環境搭建。

  1. 下載並解壓ASI_UDX_Demo樣本到本地。

    說明

    ASI_UDX_Demo屬於第三方搭建的網站,訪問時可能會存在無法開啟或訪問延遲的問題。

    解壓完成後,會產生ASI_UDX-main檔案夾。其中:

    • pom.xml:專案層級的設定檔,主要描述了專案的Maven座標、依賴關係,開發人員需要遵循的規則、缺陷管理系統,組織和Licenses,以及其他所有的專案相關因素。

    • \ASI_UDX-main\src\main\java\ASI_UDF\ASI_UDF.java:自訂純量涵式(UDSF)樣本的Java代碼。

  2. 在IntelliJ IDEA中,單擊file > open,開啟剛才解壓縮完成的ASI_UDX-main。

  3. 雙擊開啟\ASI_UDX-main\src\main\java\ASI_UDF後,根據您的業務,配置ASI_UDF.java。

    該樣本中,ASI_UDF.java已配置了擷取每條資料中從begin~end位的字元的代碼。

    package ASI_UDF;
    
    import org.apache.flink.table.functions.ScalarFunction;
    
    public class ASI_UDF extends ScalarFunction {
        public String eval(String s, Integer begin, Integer end) {
            return s.substring(begin, end);
        }
    }
  4. 雙擊開啟\ASI_UDX-main\後,配置pom.xml。

    該樣本中,pom.xml檔案已配置了Flink 1.11版依賴的主要JAR包資訊。如果您的業務:

    • 不依賴其他JAR包:不用配置pom.xml檔案,繼續下一步。

    • 依賴其他JAR包:在pom.xml檔案中添加您所需依賴的JAR包資訊。

    Flink 1.11版依賴的主要JAR包如下。

    <dependencies>
            <dependency>
                <groupId>org.apache.flink</groupId>
                <artifactId>flink-streaming-java_2.12</artifactId>
                <version>1.11.0</version>
                <!--<scope>provided</scope>-->
            </dependency>
            <dependency>
                <groupId>org.apache.flink</groupId>
                <artifactId>flink-table</artifactId>
                <version>1.11.0</version>
                <type>pom</type>
                <!--<scope>provided</scope>-->
            </dependency>
            <dependency>
                <groupId>org.apache.flink</groupId>
                <artifactId>flink-core</artifactId>
                <version>1.11.0</version>
            </dependency>
            <dependency>
                <groupId>org.apache.flink</groupId>
                <artifactId>flink-table-common</artifactId>
                <version>1.11.0</version>
            </dependency>
        </dependencies>
  5. 在下載檔案中pom.xml所在的目錄執行如下命令打包檔案。

    mvn package -Dcheckstyle.skip

    \ASI_UDX-main\target\目錄下會出現ASI_UDX-1.0-SNAPSHOT.jar的JAR包,即代表完成了UDSF開發工作。

自訂非同步純量涵式(AsyncScalarFunction)

不同於普通純量涵式,自訂非同步純量涵式需要繼承 AsyncScalarFunction,並通過 CompletableFuture 返回結果。

函數需要查詢外部資料庫、調用 HTTP 介面等存在 I/O 等待的操作時,可以使用非同步純量涵式並發處理多條記錄,減少等待對作業吞吐的影響。字串截取、數值計算等無需等待外部服務的操作,通常使用同步純量涵式即可。

配置參數

通過以下參數控制非同步純量涵式的運行行為。參數應在提交查詢或產生執行計畫前設定。

參數

預設值

說明

table.exec.async-scalar.max-concurrent-operations

10

每個非同步運算元執行個體允許的最大並發非同步作業數。增大該值會增加對外部服務的並發訪問壓力。

table.exec.async-scalar.timeout

3 min

單條記錄非同步處理的逾時時間,包含重試耗時。

table.exec.async-scalar.retry-strategy

FIXED_DELAY

FIXED_DELAY 表示失敗後按固定間隔重試;NO_RETRY 表示不重試。

table.exec.async-scalar.retry-delay

100 ms

固定間隔重試的等待時間,僅在重試策略為 FIXED_DELAY 時生效。

table.exec.async-scalar.max-attempts

3

最大重試次數,僅在重試策略為 FIXED_DELAY 時生效。

table.exec.async-scalar.output-mode

ORDERED

ORDERED 表示保持輸入順序;ALLOW_UNORDERED 表示在輸入為純追加流時允許無序輸出。VVR 11.8.0 正式版及後續版本支援。

配置無序輸出

預設情況下,非同步函數雖然可以並發執行,但後續記錄已完成的結果仍需等待前面的記錄完成後再輸出。當外部請求耗時差異較大,且業務允許結果亂序時,可以開啟無序輸出,減少慢請求造成的等待。

說明

非同步呼叫和無序輸出是兩個獨立的概念。非同步純量涵式預設並發調用、按輸入順序輸出;配置為允許無序輸出後,系統會根據輸入資料的變更類型決定是否啟用無序輸出。

在執行查詢前增加以下配置:

SET 'table.exec.async-scalar.output-mode' = 'ALLOW_UNORDERED';

自訂非同步純量涵式樣本

以下樣本通過商品服務的 HTTP 介面查詢商品名稱。函數在 open 中建立並複用一個 HttpClient,在 eval 中調用 sendAsync() 發起請求,通過完成回調返回結果。sendAsync() 返回 CompletableFuture,適合將 HTTP 調用與非同步純量涵式銜接,詳情請參見 JDK HttpClient 文檔。

樣本使用 3 秒連線逾時、5 秒請求逾時,適用於響應體較小的商品名稱查詢。請根據實際介面的回應時間調整。

package com.example.udf;

import org.apache.flink.table.functions.AsyncScalarFunction;
import org.apache.flink.table.functions.FunctionContext;

import java.io.IOException;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;
import java.time.Duration;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.CompletionException;

/**
 * 通過非同步 HTTP 介面查詢商品名稱。
 *
 * <p>介面約定:200 返回 UTF-8 商品名稱,404 表示商品不存在。
 * 本樣本適用於返回短文本的唯讀查詢;其他狀態代碼作為調用失敗交給引擎處理。
 */
public class AsyncProductName extends AsyncScalarFunction {

    private transient HttpClient client;
    private transient URI serviceBaseUri;

    @Override
    public void open(FunctionContext context) {
        String baseUrl = context.getJobParameter("product.service.base-url", null);
        if (baseUrl == null || baseUrl.isBlank()) {
            throw new IllegalArgumentException("請配置 product.service.base-url");
        }
        serviceBaseUri = URI.create(baseUrl);
        if (!("https".equalsIgnoreCase(serviceBaseUri.getScheme())
                        || "http".equalsIgnoreCase(serviceBaseUri.getScheme()))
                || serviceBaseUri.getHost() == null
                || serviceBaseUri.getRawQuery() != null
                || serviceBaseUri.getRawFragment() != null
                || !baseUrl.endsWith("/")) {
            throw new IllegalArgumentException("服務地址須為以 / 結尾的 HTTP(S) 基礎地址");
        }
        client = HttpClient.newBuilder().connectTimeout(Duration.ofSeconds(3)).build();
    }

    @Override
    public boolean isDeterministic() {
        // 商品資訊可能變化,相同 ID 在不同時間查詢可能得到不同結果。
        return false;
    }

    public void eval(CompletableFuture<String> result, Long productId) {
        if (productId == null) {
            result.complete(null);
            return;
        }

        try {
            HttpRequest request =
                    HttpRequest.newBuilder(
                                    serviceBaseUri.resolve("products/" + productId + "/name"))
                            .timeout(Duration.ofSeconds(5))
                            .header("Accept", "text/plain")
                            .GET()
                            .build();

            client.sendAsync(request, HttpResponse.BodyHandlers.ofString(StandardCharsets.UTF_8))
                    .thenApply(
                            response -> {
                                if (response.statusCode() == 200) {
                                    return response.body();
                                }
                                if (response.statusCode() == 404) {
                                    return null;
                                }
                                throw new CompletionException(
                                        new IOException(
                                                "商品查詢失敗,HTTP 狀態代碼:" + response.statusCode()));
                            })
                    .whenComplete(
                            (name, error) -> {
                                if (error != null) {
                                    result.completeExceptionally(error);
                                } else {
                                    result.complete(name);
                                }
                            });
        } catch (RuntimeException e) {
            result.completeExceptionally(e);
        }
    }
}

開發時請注意:

  • 調用 result.complete(value) 返回結果;需要返回 SQL NULL 時,調用 result.complete(null)。

  • 調用失敗時,通過 result.completeExceptionally(exception) 返回異常,交由引擎按重試策略處理。

  • eval 在發起請求後直接返回。使用 sendAsync() 的完成回調傳遞結果,避免在 eval 或回調中調用阻塞式 send()、get()、join(),或執行耗時計算。

  • 每個函數執行個體在 open 中初始化並複用用戶端,避免每條記錄建立用戶端。JDK 11/17 的 HttpClient 沒有公開的 close() 方法,其內部資源由 JDK 管理。使用提供關閉介面的其他非同步用戶端時,應在函數的 close 中釋放用戶端。

  • 商品資訊會隨時間變化,因此樣本將 isDeterministic() 設定為 false。涉及更新流時,還需結合查詢語義處理非確定性結果。

UDSF註冊

UDSF註冊過程,請參見管理自訂函數(UDF)。

UDSF使用

在註冊UDSF完成後,您就可以使用UDSF,詳細的操作步驟如下。

  1. Flink SQL作業開發。詳情請參見作業開發地圖。

    擷取ASI_UDSF_Source表中a欄位中每行字串中第2~4位的字元,程式碼範例如下。

    CREATE TEMPORARY TABLE ASI_UDSF_Source (
      a VARCHAR,
      b INT,
      c INT
    ) WITH (
      'connector' = 'datagen'
    );
    
    CREATE TEMPORARY TABLE ASI_UDSF_Sink (
      a VARCHAR
    ) WITH (
      'connector' = 'blackhole'
    );
    
    INSERT INTO ASI_UDSF_Sink
    SELECT ASI_UDSF(a,2,4)
    FROM ASI_UDSF_Source;
  2. 在營運中心 > 作業營運頁面,單擊目標作業名稱操作列的啟動。

    啟動成功後,ASI_UDSF_Sink表每行會被插入ASI_UDSF_Source表中a欄位每行字串的第2~4位字元。