本文為您介紹如何開發、註冊和使用Flink自訂純量涵式(UDSF)。
定義
自訂純量涵式(UDSF)將0個、1個或多個標量值對應到一個新的標量值。輸入與輸出是一對一的關係,即讀入一行資料,寫出一條輸出值。詳情參見User-defined Functions。
UDSF開發
Flink為您提供了UDF樣本,便於您快速開發業務。Flink UDF樣本中包含UDSF、UDAF和UDTF的實現,樣本中已為您配置對應版本的開發環境,您無需進行環境搭建。
下載並解壓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代碼。
在IntelliJ IDEA中,單擊,開啟剛才解壓縮完成的ASI_UDX-main。
雙擊開啟\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); } }雙擊開啟\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>在下載檔案中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,詳細的操作步驟如下。
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;在頁面,單擊目標作業名稱操作列的啟動。
啟動成功後,ASI_UDSF_Sink表每行會被插入ASI_UDSF_Source表中a欄位每行字串的第2~4位字元。