استخدام Java UDF مع Apache Hive في HDInsight

مقالة
07/20/2023

تعرف على كيفية إنشاء دالة معرفة من قبل المستخدم (UDF) مستندة إلى Java تعمل مع Apache Hive. يحول Java UDF في هذا المثال جدول سلاسل نصية إلى أحرف صغيرة بالكامل.

المتطلبات الأساسية

نظام مجموعة Linux-based Hadoop المُتاحة على HDInsight. راجع بدء العمل باستخدام HDInsight على Linux.
Java Developer Kit (JDK) الإصدار 8
Apache Maven مثبت بشكل صحيح وفقاً لـ Apache. Maven هو نظام بناء مشروع لمشاريع Java.
مخطط URI للتخزين الأساسي لأنظمة مجموعاتك. سيكون هذا wasb:// لـ Azure Storage، وabfs:// لـ Azure Data Lake Storage Gen2 أو adl:// for Azure Data Lake Storage Gen1. إذا تم تمكين النقل الآمن لـAzure Storage، فسيكون عنوان URI هو wasbs://. راجع أيضًا، النقل الآمن.
محرر نصوص أو Java IDE

هام

إذا قمت بإنشاء ملفات Python على عميل Windows، يجب استخدام محرر يستخدم LF كنهاية سطر. إذا لم تكن متأكدًا مما إذا كان المحرر الخاص بك يستخدم LF أو CRLF، فراجع قسم استكشاف الأخطاء وإصلاحها للحصول على خطوات إزالة حرف CR.

بيئة الاختبار

كانت البيئة المستخدمة في هذه المقالة عبارة عن جهاز كمبيوتر يعمل بنظام التشغيل Windows 10. تم تنفيذ الأوامر في موجّه الأوامر، وتم تحرير الملفات المختلفة باستخدام برنامج "المفكرة". قم بالتعديل وفقاً لبيئتك.

من موجه الأوامر، أدخل الأوامر أدناه لإنشاء بيئة عمل:

IF NOT EXIST C:\HDI MKDIR C:\HDI
cd C:\HDI

إنشاء Java UDF نموذجي

إنشاء مشروع Maven جديد بإدخال الأمر التالي:
```
mvn archetype:generate -DgroupId=com.microsoft.examples -DartifactId=ExampleUDF -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false
```
ينشئ هذا الأمر دليلاً باسم ⁧exampleudf⁩ يحتوي على مشروع Maven.
بمجرد إنشاء المشروع، احذف الدليل exampleudf/src/test الذي تم إنشاؤه كجزء من المشروع عن طريق إدخال الأمر التالي:
```
cd ExampleUDF
rmdir /S /Q "src/test"
```

افتح pom.xml عن طريق إدخال الأمر التالي أدناه:

notepad pom.xml

بعد ذلك، استبدل الإدخال الموجود <dependencies> بـ XML التالي:

<dependencies>
    <dependency>
        <groupId>org.apache.hadoop</groupId>
        <artifactId>hadoop-client</artifactId>
        <version>2.7.3</version>
        <scope>provided</scope>
    </dependency>
    <dependency>
        <groupId>org.apache.hive</groupId>
        <artifactId>hive-exec</artifactId>
        <version>1.2.1</version>
        <scope>provided</scope>
    </dependency>
</dependencies>

تحدد هذه الإدخالات إصدار Hadoop وHive المضمن مع HDInsight 3.6. يمكنك العثور على معلومات حول إصدارات Hadoop وHive المتوفرة مع HDInsight من مستند إصدار مكون HDInsight.

أضف قسم <build> قبل السطر </project> في نهاية الملف. يجب أن يحتوي هذا القسم على XML التالي:

<build>
    <plugins>
        <!-- build for Java 1.8. This is required by HDInsight 3.6  -->
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-compiler-plugin</artifactId>
            <version>3.3</version>
            <configuration>
                <source>1.8</source>
                <target>1.8</target>
            </configuration>
        </plugin>
        <!-- build an uber jar -->
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-shade-plugin</artifactId>
            <version>3.2.1</version>
            <configuration>
                <!-- Keep us from getting a can't overwrite file error -->
                <transformers>
                    <transformer
                            implementation="org.apache.maven.plugins.shade.resource.ApacheLicenseResourceTransformer">
                    </transformer>
                    <transformer implementation="org.apache.maven.plugins.shade.resource.ServicesResourceTransformer">
                    </transformer>
                </transformers>
                <!-- Keep us from getting a bad signature error -->
                <filters>
                    <filter>
                        <artifact>*:*</artifact>
                        <excludes>
                            <exclude>META-INF/*.SF</exclude>
                            <exclude>META-INF/*.DSA</exclude>
                            <exclude>META-INF/*.RSA</exclude>
                        </excludes>
                    </filter>
                </filters>
            </configuration>
            <executions>
                <execution>
                    <phase>package</phase>
                    <goals>
                        <goal>shade</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

تحدد هذه الإدخالات كيفية إنشاء المشروع. على وجه التحديد، إصدار Java الذي يستخدمه المشروع وكيفية إنشاء uberjar للتوزيع إلى نظام المجموعة.

احفظ الملف بمجرد إجراء التغييرات.

أدخل الأمر أدناه لإنشاء ملف جديد وفتحه ExampleUDF.java:

notepad src/main/java/com/microsoft/examples/ExampleUDF.java

ثم انسخ والصق التعليمة البرمجية Java أدناه في الملف الجديد. ثم أغلق الملف.

package com.microsoft.examples;

import org.apache.hadoop.hive.ql.exec.Description;
import org.apache.hadoop.hive.ql.exec.UDF;
import org.apache.hadoop.io.*;

// Description of the UDF
@Description(
    name="ExampleUDF",
    value="returns a lower case version of the input string.",
    extended="select ExampleUDF(deviceplatform) from hivesampletable limit 10;"
)
public class ExampleUDF extends UDF {
    // Accept a string input
    public String evaluate(String input) {
        // If the value is null, return a null
        if(input == null)
            return null;
        // Lowercase the input string and return it
        return input.toLowerCase();
    }
}

تقوم هذه التعليمة البرمجية بتنفيذ UDF يقبل قيمة سلسلة، ويعيد إصدارًا صغيرًا من السلسلة.

إنشاء وتثبيت UDF

في الأوامر أدناه، استبدل sshuser باسم المستخدم الفعلي إذا كان مختلفًا. استبدل mycluster باسم نظام المجموعة الفعلي.

قم بالتحويل البرمجي وإعداد الحزمة لـ UDF بإدخال الأمر التالي:
```
mvn compile package
```
ينشئ هذا الأمر حزم UDF في الملف exampleudf/target/ExampleUDF-1.0-SNAPSHOT.jar.
استخدم الأمر scp لنسخ الملف إلى نظام مجموعة HDInsight بإدخال الأمر التالي:
```
scp ./target/ExampleUDF-1.0-SNAPSHOT.jar sshuser@mycluster-ssh.azurehdinsight.net:
```
اتصل بنظام المجموعة باستخدام SSH عن طريق إدخال الأمر التالي:
```
ssh sshuser@mycluster-ssh.azurehdinsight.net
```
من جلسة SSH المفتوحة، انسخ ملف jar إلى تخزين HDInsight.
```
hdfs dfs -put ExampleUDF-1.0-SNAPSHOT.jar /example/jars
```

استخدام UDF من Hive

بدء تشغيل عميل Beeline من جلسة عمل SSH بإدخال الأمر التالي:
```
beeline -u 'jdbc:hive2://localhost:10001/;transportMode=http'
```
يفترض هذا الأمر أنك استخدمت الإعداد الافتراضي المسؤول لحساب تسجيل الدخول لنظام مجموعتك.
بمجرد وصولك إلى موجه الأوامر jdbc:hive2://localhost:10001/>، أدخل ما يلي لإضافة UDF إلى Hive وتعريضه كدالة.
```
ADD JAR wasbs:///example/jars/ExampleUDF-1.0-SNAPSHOT.jar;
CREATE TEMPORARY FUNCTION tolower as 'com.microsoft.examples.ExampleUDF';
```

استخدم UDF لتحويل القيم التي تم استردادها من جدول إلى سلاسل الأحرف الصغيرة.

SELECT tolower(state) AS ExampleUDF, state FROM hivesampletable LIMIT 10;

يحدد هذا الاستعلام الحالة من الجدول، ويحول السلسلة إلى أحرف صغيرة، ثم يعرضها مع الاسم غير المعدل. الإخراج يظهر مشابهة للنص التالي:

+---------------+---------------+--+
|  exampleudf   |     state     |
+---------------+---------------+--+
| california    | California    |
| pennsylvania  | Pennsylvania  |
| pennsylvania  | Pennsylvania  |
| pennsylvania  | Pennsylvania  |
| colorado      | Colorado      |
| colorado      | Colorado      |
| colorado      | Colorado      |
| utah          | Utah          |
| utah          | Utah          |
| colorado      | Colorado      |
+---------------+---------------+--+

استكشاف الأخطاء وإصلاحها

عند تشغيل مهمة hive، قد تصادف خطأ مشابه للنص التالي:

Caused by: org.apache.hadoop.hive.ql.metadata.HiveException: [Error 20001]: An error occurred while reading or writing to your custom script. It may have crashed with an error.

قد يكون سبب هذه المشكلة نهايات الأسطر في ملف Python. العديد من محرري Windows يستخدمون CRLF بصورة افتراضية كنهاية الخط، ولكن تطبيقات Linux عادة ما تتوقع LF.

يمكنك استخدام عبارات PowerShell التالية لإزالة أحرف CR قبل تحميل الملف إلى HDInsight:

# Set $original_file to the Python file path
$text = [IO.File]::ReadAllText($original_file) -replace "`r`n", "`n"
[IO.File]::WriteAllText($original_file, $text)

الخطوات التالية

للحصول على طرق أخرى للعمل مع Hive، راجع استخدام Apache Hive مع HDInsight.

لمزيد من المعلومات حول وظائف Hive المعرفة من قبل المستخدم، راجع القسم مشغلي Apache Hive وقسم الوظائف المعرفة من قبل المستخدم في ويكي Hive في apache.org.

Share via