Bu konu, Java kullanıcı tanımlı işlevlerin (UDF) nasıl geliştirileceğini ve kullanılacağını açıklar.
Genel bilgiler
StarRocks v2.2.0 sürümünden itibaren Java ile yazılmış kullanıcı tanımlı işlevleri (UDF) destekler.
StarRocks v3.0 sürümüyle birlikte genel UDF desteği sunulmuştur. İlgili SQL deyimlerine (CREATE, SHOW ve DROP) yalnızca GLOBAL anahtar sözcüğünü ekleyerek bu işlevleri genel düzeyde uygulayabilirsiniz. Bu sayede deyimleri her veritabanı için tek tek çalıştırmanıza gerek kalmaz. StarRocks yeteneklerini genişletmek amacıyla iş senaryolarınıza özel işlevler geliştirebilirsiniz.
StarRocks şu anda aşağıdaki UDF türlerini destekler:
skaler kullanıcı tanımlı işlev (skaler UDF)
kullanıcı tanımlı toplama işlevi (UDAF)
kullanıcı tanımlı pencere işlevi (UDWF)
kullanıcı tanımlı tablo değerli işlev (UDTF)
Ön koşullar
StarRocks'ta Java UDF kullanmadan önce aşağıdaki gereksinimleri karşıladığınızdan emin olun:
Java projelerini oluşturmak ve geliştirmek için Apache Maven yüklü olmalıdır.
Sunucunuzda JDK 1.8 yüklü olmalıdır.
Instance Configuration sayfasında FE yapılandırma öğesi
enable_udfdeğeriniTRUEolarak ayarlayarak UDF özelliğini etkinleştirin. Ardından değişikliği uygulamak üzere örneği yeniden başlatın.
Veri türü eşleme
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
UDF geliştirme ve kullanma
Bir Maven projesi oluşturacak ve işlevi Java ile yazacaksınız.
1. Adım: Maven projesi oluşturun
Aşağıdaki temel dizin yapısına sahip bir Maven projesi oluşturun.
project
|--pom.xml
|--src
| |--main
| | |--java
| | |--resources
| |--test
|--target
2. Adım: Bağımlılıkları ekleyin
pom.xml dosyasına aşağıdaki bağımlılıkları ekleyin.
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>org.example</groupId>
<artifactId>udf</artifactId>
<version>1.0-SNAPSHOT</version>
<properties>
<maven.compiler.source>8</maven.compiler.source>
<maven.compiler.target>8</maven.compiler.target>
</properties>
<dependencies>
<dependency>
<groupId>com.alibaba</groupId>
<artifactId>fastjson</artifactId>
<version>1.2.76</version>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-dependency-plugin</artifactId>
<version>2.10</version>
<executions>
<execution>
<id>copy-dependencies</id>
<phase>package</phase>
<goals>
<goal>copy-dependencies</goal>
</goals>
<configuration>
<outputDirectory>${project.build.directory}/lib</outputDirectory>
</configuration>
</execution>
</executions>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-assembly-plugin</artifactId>
<version>3.3.0</version>
<executions>
<execution>
<id>make-assembly</id>
<phase>package</phase>
<goals>
<goal>single</goal>
</goals>
</execution>
</executions>
<configuration>
<descriptorRefs>
<descriptorRef>jar-with-dependencies</descriptorRef>
</descriptorRefs>
</configuration>
</plugin>
</plugins>
</build>
</project>
3. Adım: UDF'yi geliştirin
Gerekli UDF'leri Java ile geliştirin.
Skaler UDF geliştirme
Skaler bir UDF, satır başına işleme yaparak her satır için tek bir değer döndürür. Bir sorguda skaler UDF kullandığınızda sonuç kümesinde her satır görünür. Tipik skaler işlevler arasında UPPER, LOWER, ROUND ve ABS bulunur.
Aşağıdaki örnek, bir JSON nesnesinden veri çıkarmayı gösterir. Bazı iş senaryolarında JSON verilerindeki bir alanın değeri JSON nesnesi yerine JSON dizesi olabilir. İç içe geçmiş JSON dizesini çıkarmak için GET_JSON_STRING işlevine iç içe çağrı yapmanız gerekir; örneğin: GET_JSON_STRING(GET_JSON_STRING('{"key":"{\\"k0\\":\\"v0\\"}"}', "$.key"), "$.k0").
SQL deyimini basitleştirmek amacıyla JSON dizesini doğrudan çıkaran bir UDF geliştirebilirsiniz; örneğin: MY_UDF_JSON_GET('{"key":"{\\"k0\\":\\"v0\\"}"}', "$.key.k0").
package com.starrocks.udf.sample;
import com.alibaba.fastjson.JSONPath;
public class UDFJsonGet {
public final String evaluate(String jsonObj, String key) {
if (obj == null || key == null) return null;
try {
// The JSONPath library can fully expand the path, even if a field value is a JSON-formatted string.
return JSONPath.read(jsonObj, key).toString();
} catch (Exception e) {
return null;
}
}
}
Özel sınıfınız aşağıdaki yöntemi uygulamalıdır.
Yöntemdeki istek parametrelerinin ve dönüş değerinin veri türleri, 6. Adımdaki CREATE FUNCTION deyimiyle bildirilenlerle eşleşmelidir. Veri türü eşleme, Veri türü eşleme bölümündeki kurallara uygun olmalıdır.
|
|
|
|
|
|
UDAF geliştirme
UDAF, bir satır grubu üzerinde çalışır ve tek bir değer döndürür. Tipik toplama işlevleri arasında SUM, COUNT, MAX ve MIN bulunur. Bu işlevler, her GROUP BY grubundaki birden çok satırdan gelen verileri toplayarak her grup için tek bir sonuç çıktısı verir.
Aşağıdaki örnekte MY_SUM_INT işlevi kullanılmaktadır. BIGINT değeri döndüren yerleşik SUM işlevinden farklı olarak MY_SUM_INT INT bağımsız değişkeni alır ve INT döndürür.
package com.starrocks.udf.sample;
public class SumInt {
public static class State {
int counter = 0;
public int serializeLength() { return 4; }
}
public State create() {
return new State();
}
public void destroy(State state) {
}
public final void update(State state, Integer val) {
if (val != null) {
state.counter+= val;
}
}
public void serialize(State state, java.nio.ByteBuffer buff) {
buff.putInt(state.counter);
}
public void merge(State state, java.nio.ByteBuffer buffer) {
int val = buffer.getInt();
state.counter += val;
}
public Integer finalize(State state) {
return state.counter;
}
}
Özel sınıfınız aşağıdaki yöntemleri uygulamalıdır.
Yöntemlerdeki istek parametrelerinin ve dönüş değerinin veri türleri, 6. Adımdaki CREATE FUNCTION deyimiyle bildirilenlerle eşleşmelidir. Veri türü eşleme, Veri türü eşleme bölümündeki kurallara uygun olmalıdır.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
UDAF geliştirirken ara sonucu depolamak için java.nio.ByteBuffer arabellek sınıfını ve serileştirilmiş ara sonucun uzunluğunu belirtmek için serializeLength yöntemini kullanmanız gerekir.
|
|
|
|
|
|
|
|
|
java.nio.ByteBuffer serileştirmesi için aşağıdaki gereksinimlere dikkat edin:
Durumu seri durumdan çıkarmak için
ByteBufferöğesininremaining()yöntemine güvenmeyin.ByteBufferüzerindeclear()yöntemini çağırmayın.serializeLength()tarafından döndürülen değer, arabelleğe yazılan verilerin gerçek uzunluğuyla eşleşmelidir. Eşleşmemesi serileştirme ve seri durumdan çıkarma hatalarına neden olur.
UDWF geliştirme
UDWF, özel bir toplama işlevi türüdür. Normal bir toplama işlevinden farklı olarak pencere işlevi, bir satır grubu (pencere) üzerinden bir değer hesaplar ve her satır için ayrı bir sonuç döndürür. Genellikle pencere işlevi, satırları bölümlere ayıran bir OVER yan tümcesi içerir. İşlev daha sonra ait olduğu satır penceresine göre her satır için bir sonuç hesaplar.
Aşağıdaki örnekte MY_WINDOW_SUM_INT işlevi kullanılmaktadır. BIGINT değeri döndüren yerleşik SUM işlevinden farklı olarak MY_WINDOW_SUM_INT INT bağımsız değişkeni alır ve INT döndürür.
package com.starrocks.udf.sample;
public class WindowSumInt {
public static class State {
int counter = 0;
public int serializeLength() { return 4; }
@Override
public String toString() {
return "State{" +
"counter=" + counter +
'}';
}
}
public State create() {
return new State();
}
public void destroy(State state) {
}
public void update(State state, Integer val) {
if (val != null) {
state.counter+=val;
}
}
public void serialize(State state, java.nio.ByteBuffer buff) {
buff.putInt(state.counter);
}
public void merge(State state, java.nio.ByteBuffer buffer) {
int val = buffer.getInt();
state.counter += val;
}
public Integer finalize(State state) {
return state.counter;
}
public void reset(State state) {
state.counter = 0;
}
public void windowUpdate(State state,
int peer_group_start, int peer_group_end,
int frame_start, int frame_end,
Integer[] inputs) {
for (int i = (int)frame_start; i < (int)frame_end; ++i) {
state.counter += inputs[i];
}
}
}
Pencere işlevi özel bir toplama işlevi türü olduğundan özel sınıfınız gerekli tüm UDAF yöntemlerinin yanı sıra windowUpdate() yöntemini de uygulamalıdır.
Yöntemlerdeki istek parametrelerinin ve dönüş değerinin veri türleri, 6. Adımdaki CREATE FUNCTION deyimiyle bildirilenlerle eşleşmelidir. Veri türü eşleme, Veri türü eşleme bölümündeki kurallara uygun olmalıdır.
Ek olarak uygulanması gereken yöntem
|
Yöntem |
Açıklama |
|
|
Pencere verilerini günceller. Pencere işlevleri hakkında ayrıntılı bilgi için bkz. Pencere işlevleri. Her giriş satırı için ilgili pencere bilgileri alınarak ara sonuç güncellenir.
|
UDTF geliştirme
UDTF, tek bir satırı giriş olarak alır ve çıktı satırlarından oluşan bir tablo üretir. UDTF'ler genellikle bir sütunu birden çok satıra bölmek gibi işlemler için kullanılır.
Şu anda UDTF'ler yalnızca tek bir sütunla birden çok satır döndürmeyi destekler.
Aşağıdaki örnekte MY_UDF_SPLIT işlevi kullanılmaktadır. Bu işlev, ayırıcı olarak boşluk kullanarak bir dizeyi böler. Hem giriş bağımsız değişkeni hem de dönüş değeri STRING türündedir.
package com.starrocks.udf.sample;
public class UDFSplit{
public String[] process(String in) {
if (in == null) return null;
return in.split(" ");
}
}
Özel sınıfınız aşağıdaki yöntemi uygulamalıdır.
Yöntemdeki istek parametrelerinin ve dönüş değerinin veri türleri, 6. Adımdaki CREATE FUNCTION deyimiyle bildirilenlerle eşleşmelidir. Veri türü eşleme, Veri türü eşleme bölümündeki kurallara uygun olmalıdır.
|
|
|
|
|
|
4. Adım: Java projesini paketleyin
Java projesini paketlemek için aşağıdaki komutu çalıştırın.
mvn package
Bu komut, target dizininde iki JAR dosyası oluşturur: udf-1.0-SNAPSHOT.jar ve udf-1.0-SNAPSHOT-jar-with-dependencies.jar.
5. Adım: Projeyi yükleyin
udf-1.0-SNAPSHOT-jar-with-dependencies.jar dosyasını bir OSS paketine yükleyin ve JAR dosyasına public-read izni verin. Daha fazla bilgi için bkz. Basit yükleme ve Paket ACL.
6. Adımda FE, UDF'nin JAR dosyasını doğrular ve bir sağlama toplamı hesaplar. BE daha sonra JAR dosyasını indirir ve yürütür.
6. Adım: StarRocks'ta UDF oluşturun
StarRocks, UDF'ler için veritabanı düzeyinde ve genel düzeyde olmak üzere iki ad alanı sağlar.
UDF'leriniz için görünürlük yalıtımı gerekmiyorsa genel bir UDF oluşturabilirsiniz. Genel bir UDF'ye başvururken katalog veya veritabanı öneki olmadan doğrudan işlev adıyla çağırabilirsiniz; bu da erişimi basitleştirir.
Görünürlük yalıtımı gerekiyorsa veya farklı veritabanlarında aynı ada sahip UDF'ler oluşturmanız gerekiyorsa veritabanı düzeyinde bir UDF oluşturabilirsiniz. Geçerli oturumunuz bu veritabanındaysa işlevi doğrudan adıyla çağırabilirsiniz. Oturumunuz farklı bir katalogta veya veritabanındaysa
catalog.database.functiongibi tam nitelikli bir ad kullanmanız gerekir.
Genel bir UDF oluşturmak için sistem düzeyinde CREATE GLOBAL FUNCTION izni gerekir. Veritabanı düzeyinde bir UDF oluşturmak için veritabanında CREATE FUNCTION izni gerekir. Herhangi bir UDF kullanmak için buna ilişkin USAGE izni gerekir. İzinlerin nasıl verileceği hakkında bilgi için bkz. GRANT.
JAR dosyasını yükledikten sonra StarRocks'ta ilgili UDF'yi oluşturun. Genel bir UDF oluşturmak için SQL deyimine yalnızca GLOBAL anahtar sözcüğünü eklemeniz yeterlidir.
Söz dizimi
CREATE [GLOBAL][AGGREGATE | TABLE] FUNCTION function_name(arg_type [, ...])
RETURNS return_type
[PROPERTIES ("key" = "value" [, ...]) ]
Parametreler
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Skaler UDF oluşturma
Önceki örnekteki skaler UDF'yi StarRocks'ta oluşturmak için aşağıdaki komutu çalıştırın.
CREATE [GLOBAL] FUNCTION MY_UDF_JSON_GET(string, string)
RETURNS string
PROPERTIES (
"symbol" = "com.starrocks.udf.sample.UDFJsonGet",
"type" = "StarrocksJar",
"file" = "http://<YourBucketName>.oss-cn-xxxx-internal.aliyuncs.com/<YourPath>/udf-1.0-SNAPSHOT-jar-with-dependencies.jar"
);
|
|
|
|
|
|
|
|
|
|
|
|
UDAF oluşturma
Önceki örnekteki UDAF'yi StarRocks'ta oluşturmak için aşağıdaki komutu çalıştırın.
CREATE [GLOBAL] AGGREGATE FUNCTION MY_SUM_INT(INT)
RETURNS INT
PROPERTIES
(
"symbol" = "com.starrocks.udf.sample.SumInt",
"type" = "StarrocksJar",
"file" = "http://<YourBucketName>.oss-cn-xxxx-internal.aliyuncs.com/<YourPath>/udf-1.0-SNAPSHOT-jar-with-dependencies.jar"
);
PROPERTIES yan tümcesindeki parametreler, Skaler UDF oluşturma bölümünde açıklananlarla aynıdır.
UDWF oluşturma
Önceki örnekteki UDWF'yi StarRocks'ta oluşturmak için aşağıdaki komutu çalıştırın.
CREATE [GLOBAL] AGGREGATE FUNCTION MY_WINDOW_SUM_INT(Int)
RETURNS Int
PROPERTIES
(
"analytic" = "true",
"symbol" = "com.starrocks.udf.sample.WindowSumInt",
"type" = "StarrocksJar",
"file" = "http://<YourBucketName>.oss-cn-xxxx-internal.aliyuncs.com/<YourPath>/udf-1.0-SNAPSHOT-jar-with-dependencies.jar"
);
analytic özelliği işlevi bir pencere işlevi olarak tanımlar. UDWF için bunu true olarak ayarlayın. Diğer parametreler, Skaler UDF oluşturma bölümünde açıklananlarla aynıdır.
UDTF oluşturma
Önceki örnekteki UDTF'yi StarRocks'ta oluşturmak için aşağıdaki komutu çalıştırın.
CREATE [GLOBAL] TABLE FUNCTION MY_UDF_SPLIT(string)
RETURNS string
PROPERTIES
(
"symbol" = "com.starrocks.udf.sample.UDFSplit",
"type" = "StarrocksJar",
"file" = "http://<YourBucketName>.oss-cn-xxxx-internal.aliyuncs.com/<YourPath>/udf-1.0-SNAPSHOT-jar-with-dependencies.jar"
);
PROPERTIES yan tümcesindeki parametreler, Skaler UDF oluşturma bölümünde açıklananlarla aynıdır.
7. Adım: UDF'yi kullanın
UDF'yi oluşturduktan sonra test edebilir ve kullanabilirsiniz.
Skaler UDF kullanma
6. Adımda oluşturulan skaler UDF'yi kullanmak için aşağıdaki komutu çalıştırın.
SELECT MY_UDF_JSON_GET('{"key":"{\\"in\\":2}"}', '$.key.in');
UDAF kullanma
6. Adımda oluşturulan UDAF'yi kullanmak için aşağıdaki komutu çalıştırın.
SELECT MY_SUM_INT(col1);
UDWF kullanma
6. Adımda oluşturulan UDWF'yi kullanmak için aşağıdaki komutu çalıştırın.
SELECT MY_WINDOW_SUM_INT(intcol)
OVER (PARTITION BY intcol2
ORDER BY intcol3
ROWS BETWEEN UNBOUNDED PRECEDING AND UNBOUNDED FOLLOWING)
FROM test_basic;
UDTF kullanma
Önceki örnekteki UDTF'yi kullanmak için aşağıdaki komutu çalıştırın.
-- Assume that table t1 exists with columns a, b, and c1.
SELECT t1.a,t1.b,t1.c1 FROM t1;
> output:
1,2.1,"hello world"
2,2.2,"hello UDTF."
-- Use the MY_UDF_SPLIT() function.
SELECT t1.a,t1.b, MY_UDF_SPLIT FROM t1, MY_UDF_SPLIT(t1.c1);
> output:
1,2.1,"hello"
1,2.1,"world"
2,2.2,"hello"
2,2.2,"UDTF."
SELECT listesinde ilk
MY_UDF_SPLITifadesi,MY_UDF_SPLITişlevinin çıktısı için varsayılan sütun diğer adıdır.Şu anda UDTF çıktısı için
AS t2(f1)gibi bir tablo diğer adı veya sütun diğer adları belirtemezsiniz.
UDF'leri görüntüleyin
UDF'ler hakkında bilgi görüntülemek için aşağıdaki komutu çalıştırın.
SHOW [GLOBAL] FUNCTIONS;
UDF'leri silin
Belirtilen bir UDF'yi silmek için aşağıdaki komutu çalıştırın.
DROP [GLOBAL] FUNCTION <function_name>(arg_type [, ...]);
SSS
S: UDF geliştirirken statik değişkenler kullanabilir miyim? Farklı UDF'lerden gelen statik değişkenler birbirini etkiler mi?
Y: Evet, statik değişkenler kullanabilirsiniz. Statik değişkenler farklı UDF'ler arasında yalıtılmıştır ve UDF'ler aynı sınıf adını paylaşsa bile birbirini etkilemez.