Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris. # Kueri dengan fungsi yang ditentukan pengguna User Defined Functions (UDF) di Amazon Athena memungkinkan Anda untuk membuat fungsi kustom untuk memproses catatan atau kelompok catatan. Sebuah UDF menerima parameter, melakukan tugas, kemudian mengembalikan hasilnya. Untuk menggunakan UDF di Athena, Anda menulis klausa `USING EXTERNAL FUNCTION` sebelum pernyataan `SELECT` dalam kueri SQL. Pernyataan `SELECT` mereferensikan UDF dan mendefinisikan variabel yang diteruskan ke UDF saat kueri berjalan. Kueri SQL memanggil fungsi Lambda menggunakan runtime Java saat memanggil UDF. UDFsdidefinisikan dalam fungsi Lambda sebagai metode dalam paket penyebaran Java. Beberapa UDFs dapat didefinisikan dalam paket penyebaran Java yang sama untuk fungsi Lambda. Anda juga menentukan nama fungsi Lambda di klausa `USING EXTERNAL FUNCTION`. Anda memiliki dua opsi untuk menerapkan fungsi Lambda untuk Athena. UDFs Anda dapat men-deploy fungsi langsung menggunakan Lambda, atau Anda dapat menggunakan AWS Serverless Application Repository. Untuk menemukan fungsi Lambda yang ada UDFs, Anda dapat mencari repositori publik AWS Serverless Application Repository atau pribadi Anda dan kemudian menyebarkan ke Lambda. Anda juga dapat membuat atau memodifikasi kode sumber Java, mengemasnya ke dalam file JAR, dan men-deploy menggunakan Lambda atau AWS Serverless Application Repository. Misalnya kode sumber Java dan paket untuk memulai, lihat [Buat dan terapkan UDF menggunakan Lambda](udf-creating-and-deploying.md). Untuk informasi selengkapnya tentang Lambda, lihat [AWS Lambda Panduan Developer](https://docs.aws.amazon.com/lambda/latest/dg/). Untuk informasi selengkapnya AWS Serverless Application Repository, lihat [Panduan AWS Serverless Application Repository Pengembang](https://docs.aws.amazon.com/serverlessrepo/latest/devguide/). Untuk contoh yang menggunakan Athena untuk menerjemahkan dan menganalisis teks, lihat artikel AWS Machine Learning Blog [Terjemahkan dan analisis teks menggunakan fungsi SQL UDFs dengan Amazon Athena, Amazon Translate, dan Amazon Comprehend](https://aws.amazon.com/blogs/machine-learning/translate-and-analyze-text-using-sql-functions-with-amazon-athena-amazon-translate-and-amazon-comprehend/), atau tonton. [video](udf-videos.md#udf-videos-xlate) *Untuk contoh penggunaan UDFs untuk memperluas kueri geospasial di Amazon Athena, [lihat Memperluas kueri geospasial di Amazon Athena dengan dan di Blog Big UDFs Data AWS Lambda](https://aws.amazon.com/blogs/big-data/extend-geospatial-queries-in-amazon-athena-with-udfs-and-aws-lambda/).AWS * **Topics** + [Video UDFs di Athena](udf-videos.md) + [Pertimbangan dan batasan](udf-considerations-limitations.md) + [Kueri menggunakan sintaks kueri UDF](udf-query-syntax.md) + [Buat dan terapkan UDF menggunakan Lambda](udf-creating-and-deploying.md) # Video UDFs di Athena Tonton video berikut untuk mempelajari lebih lanjut tentang penggunaan UDFs di Athena. **Video: Memperkenalkan Fungsi yang Ditentukan Pengguna (UDFs) di Amazon Athena** Video berikut menunjukkan bagaimana Anda dapat menggunakan UDFs di Amazon Athena untuk menyunting informasi sensitif. **catatan** Sintaks dalam video ini adalah pra-rilis, tetapi konsepnya sama. Gunakan Athena tanpa kelompok kerja. `AmazonAthenaPreviewFunctionality` [![AWS Videos](http://img.youtube.com/vi/https://www.youtube.com/embed/AxJ6jP4Pfmo/0.jpg)](http://www.youtube.com/watch?v=https://www.youtube.com/embed/AxJ6jP4Pfmo) **Video: Translate, menganalisis, dan redact bidang teks menggunakan kueri SQL di Amazon Athena** Video berikut menunjukkan bagaimana Anda dapat menggunakan UDFs di Amazon Athena bersama-sama dengan yang lain Layanan AWS untuk menerjemahkan dan menganalisis teks. **catatan** Sintaks dalam video ini adalah pra-rilis, tetapi konsepnya sama. Untuk sintaks yang benar, lihat postingan blog terkait [Menerjemahkan, menyunting, dan menganalisis teks menggunakan fungsi SQL dengan Amazon Athena, Amazon Translate, dan Amazon Comprehend](https://aws.amazon.com/blogs/machine-learning/translate-and-analyze-text-using-sql-functions-with-amazon-athena-amazon-translate-and-amazon-comprehend/) pada *AWS Blog Machine Learning*. [![AWS Videos](http://img.youtube.com/vi/https://www.youtube.com/embed/Od7rXG-WMO4/0.jpg)](http://www.youtube.com/watch?v=https://www.youtube.com/embed/Od7rXG-WMO4) # Pertimbangan dan batasan Pertimbangkan poin-poin berikut ketika Anda menggunakan fungsi yang ditentukan pengguna (UDFs) di Athena. + Fungsi **Athena bawaan - Fungsi** bawaan di Athena dirancang agar berkinerja tinggi. Kami menyarankan Anda menggunakan fungsi bawaan UDFs jika memungkinkan. Untuk informasi selengkapnya tentang fungsi bawaan, lihat [Fungsi di Amazon Athena](functions.md). + ** UDFs Hanya skalar** - Athena hanya mendukung UDFs skalar, yang memproses satu baris pada satu waktu dan mengembalikan nilai kolom tunggal. Athena melewati batch baris, berpotensi secara paralel, untuk UDF setiap kali memanggil Lambda. Saat merancang UDFs dan menanyakan, perhatikan dampak potensial terhadap lalu lintas jaringan dari pemrosesan ini. + **Fungsi handler UDF menggunakan format yang disingkat** - Gunakan format singkat (bukan format penuh), untuk fungsi UDF Anda (misalnya, bukan). `package.Class` `package.Class::method` + **Metode UDF harus huruf kecil** — metode UDF harus dalam huruf kecil; kasus unta tidak diizinkan. + **Metode UDF memerlukan parameter** — Metode UDF harus memiliki setidaknya satu parameter input. Mencoba memanggil UDF yang ditentukan tanpa parameter input menyebabkan pengecualian runtime. UDFs dimaksudkan untuk melakukan fungsi terhadap catatan data, tetapi UDF tanpa argumen tidak mengambil data, sehingga pengecualian terjadi. + **Dukungan runtime Java** - Saat ini, UDFs Athena mendukung runtime Java 8, Java 11, dan Java 17 untuk Lambda. Untuk informasi selengkapnya, lihat [Membangun fungsi Lambda dengan Java](https://docs.aws.amazon.com/lambda/latest/dg/lambda-java.html) dalam *AWS Lambda Panduan Developer*. **catatan** Untuk Java 17, Anda harus menetapkan nilai variabel `JAVA_TOOL_OPTIONS` lingkungan seperti `--add-opens=java.base/java.nio=ALL-UNNAMED` di Lambda Anda. + **Izin IAM**– Untuk menjalankan dan membuat pernyataan permintaan UDF di Athena, IAM utama menjalankan kueri harus diizinkan untuk melakukan tindakan selain fungsi Athena. Untuk informasi selengkapnya, lihat [Izinkan akses ke Athena UDFs: Contoh kebijakan](udf-iam-access.md). + Kuota **Lambda - Kuota** Lambda berlaku untuk. UDFs Untuk informasi selengkapnya, lihat [Kuota Lambda](https://docs.aws.amazon.com/lambda/latest/dg/limits.html) dalam *Panduan Pengembang AWS Lambda *. + Pemfilteran **tingkat baris - Pemfilteran** tingkat baris Lake Formation tidak didukung untuk. UDFs + **Tampilan** — Anda tidak dapat menggunakan tampilan dengan UDFs. + **Masalah yang diketahui** — Untuk sebagian besar up-to-date daftar masalah yang diketahui, lihat [Batasan dan masalah](https://github.com/awslabs/aws-athena-query-federation/wiki/Limitations_And_Issues) di bagian awslabs/aws-athena-query-federation. GitHub # Kueri menggunakan sintaks kueri UDF `USING EXTERNAL FUNCTION`Klausa menentukan UDF atau beberapa UDFs yang dapat direferensikan oleh `SELECT` pernyataan berikutnya dalam kueri. Anda perlu nama metode untuk UDF dan nama fungsi Lambda yang host UDF. Di tempat nama fungsi Lambda, Anda dapat menggunakan Lambda ARN. Dalam skenario lintas akun, Lambda ARN diperlukan. ## Sinopsis ``` USING EXTERNAL FUNCTION UDF_name(variable1 data_type[, variable2 data_type][,...]) RETURNS data_type LAMBDA 'lambda_function_name_or_ARN' [, EXTERNAL FUNCTION UDF_name2(variable1 data_type[, variable2 data_type][,...]) RETURNS data_type LAMBDA 'lambda_function_name_or_ARN'[,...]] SELECT [...] UDF_name(expression) [, UDF_name2(expression)] [...] ``` ## Parameter **MENGGUNAKAN FUNGSI EKSTERNAL *UDF\$1name* (*variable1**data\$1type*[, *variable2**data\$1type*] [,...])** *UDF\$1name*menentukan nama UDF, yang harus sesuai dengan metode Java dalam fungsi Lambda yang direferensikan. Masing-masing *variable data\$1type* menentukan variabel bernama dan tipe data yang sesuai yang UDF menerima sebagai input. *data\$1type*Harus menjadi salah satu tipe data Athena yang didukung yang tercantum dalam tabel berikut dan peta ke tipe data Java yang sesuai. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/id_id/athena/latest/ug/udf-query-syntax.html) **PENGEMBALIAN *data\$1type*** `data_type`menentukan tipe data SQL bahwa UDF kembali sebagai output. Tipe data Athena yang tercantum dalam tabel di atas didukung. Untuk tipe `DECIMAL` data, gunakan sintaks `RETURNS DECIMAL(precision, scale)` di mana *precision* dan *scale* adalah bilangan bulat. **LAMBDA '' *lambda\$1function*** *lambda\$1function*menentukan nama fungsi Lambda yang akan dipanggil saat menjalankan UDF. **PILIH [...] *UDF\$1name*(*expression*) [...]** `SELECT`Kueri yang meneruskan nilai ke UDF dan mengembalikan hasilnya. *UDF\$1name*menentukan UDF untuk digunakan, diikuti oleh *expression* yang dievaluasi untuk lulus nilai. Nilai-nilai yang dilewatkan dan dikembalikan harus sesuai dengan tipe data yang sesuai ditentukan untuk UDF di`USING EXTERNAL FUNCTION`Klausul. ### Contoh Misalnya kueri berdasarkan kode [UDFHandlerAthena](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-udfs/src/main/java/com/amazonaws/athena/connectors/udfs/AthenaUDFHandler.java) .java, lihat GitHub halaman konektor UDF Amazon GitHub [Athena](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-udfs). # Buat dan terapkan UDF menggunakan Lambda Untuk membuat UDF kustom, Anda membuat kelas Java baru dengan memperluas`UserDefinedFunctionHandler`kelas. Kode sumber untuk [UserDefinedFunctionHandler.java](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-federation-sdk/src/main/java/com/amazonaws/athena/connector/lambda/handlers/UserDefinedFunctionHandler.java) di SDK tersedia GitHub di [repositori awslabs/aws-athena-query-federation/athena](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-federation-sdk) -federation-sdk, bersama dengan [contoh implementasi UDF yang dapat Anda periksa dan modifikasi untuk membuat UDF](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-udfs) khusus. Langkah-langkah dalam bagian ini menunjukkan penulisan dan membangun file UDF Jar kustom menggunakan[Apache Maven](https://maven.apache.org/index.html)dari baris perintah dan menerapkan. Lakukan langkah-langkah berikut untuk membuat UDF kustom untuk Athena menggunakan Maven 1. [Kloning SDK dan siapkan lingkungan pengembangan Anda](#udf-create-install-sdk-prep-environment) 1. [Buat proyek Maven Anda](#create-maven-project) 1. [Tambahkan dependensi dan plugin ke proyek Maven Anda](#udf-add-maven-dependencies) 1. [Tulis kode Java untuk UDFs](#udf-write-java) 1. [Membangun file JAR](#udf-create-package-jar) 1. [Menyebarkan JAR ke AWS Lambda](#udf-create-deploy) ## Kloning SDK dan siapkan lingkungan pengembangan Anda Sebelum memulai, pastikan bahwa git diinstal pada sistem Anda menggunakan`sudo yum install git -y`. **Untuk menginstal SDK federasi AWS kueri** + Masukkan yang berikut pada baris perintah untuk mengkloning repositori SDK. Repositori ini mencakup SDK, contoh dan rangkaian konektor sumber data. Untuk informasi selengkapnya tentang konektor sumber data, lihat [Gunakan Kueri Federasi Amazon Athena](federated-queries.md). ``` git clone https://github.com/awslabs/aws-athena-query-federation.git ``` **Untuk menginstal prasyarat untuk prosedur ini** Jika Anda sedang mengerjakan mesin pengembangan yang sudah memiliki Apache Maven, the AWS CLI, dan alat AWS Serverless Application Model build yang diinstal, Anda dapat melewati langkah ini. 1. Dari akar`aws-athena-query-federation`direktori yang Anda buat saat Anda kloning, jalankan[prepare\$1dev\$1env.sh](https://github.com/awslabs/aws-athena-query-federation/blob/master/tools/prepare_dev_env.sh)yang mempersiapkan lingkungan pengembangan Anda. 1. Perbarui shell Anda untuk sumber variabel baru yang dibuat oleh proses instalasi atau restart sesi terminal Anda. ``` source ~/.profile ``` **penting** Jika Anda melewati langkah ini, Anda akan mendapatkan kesalahan nanti tentang AWS CLI atau AWS SAM membangun alat yang tidak dapat mempublikasikan fungsi Lambda Anda. ## Buat proyek Maven Anda Jalankan perintah berikut untuk membuat proyek Maven Anda. Ganti *groupId* dengan ID unik organisasi Anda, dan ganti *my-athena-udf* dengan nama aplikasi Anda Untuk informasi selengkapnya, lihat [Bagaimana cara membuat proyek Maven pertama saya](https://maven.apache.org/guides/getting-started/index.html#How_do_I_make_my_first_Maven_project)? dalam dokumentasi Apache Maven. ``` mvn -B archetype:generate \ -DarchetypeGroupId=org.apache.maven.archetypes \ -DgroupId=groupId \ -DartifactId=my-athena-udfs ``` ## Tambahkan dependensi dan plugin ke proyek Maven Anda Tambahkan konfigurasi berikut ke file proyek Maven `pom.xml` Anda. Sebagai contoh, lihat file [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-udfs/pom.xml) di file GitHub. ``` 2022.47.1 com.amazonaws aws-athena-federation-sdk ${aws-athena-federation-sdk.version} org.apache.maven.plugins maven-shade-plugin 3.2.1 false *:* META-INF/*.SF META-INF/*.DSA META-INF/*.RSA package shade ``` ## Tulis kode Java untuk UDFs Buat kelas baru dengan memperluas [UserDefinedFunctionHandler.java.](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-federation-sdk/src/main/java/com/amazonaws/athena/connector/lambda/handlers/UserDefinedFunctionHandler.java) Tulis Anda UDFs di dalam kelas. Dalam contoh berikut, dua metode Java untuk UDFs, `compress()` dan`decompress()`, dibuat di dalam kelas`MyUserDefinedFunctions`. ``` *package *com.mycompany.athena.udfs; public class MyUserDefinedFunctions extends UserDefinedFunctionHandler { private static final String SOURCE_TYPE = "MyCompany"; public MyUserDefinedFunctions() { super(SOURCE_TYPE); } /** * Compresses a valid UTF-8 String using the zlib compression library. * Encodes bytes with Base64 encoding scheme. * * @param input the String to be compressed * @return the compressed String */ public String compress(String input) { byte[] inputBytes = input.getBytes(StandardCharsets.UTF_8); // create compressor Deflater compressor = new Deflater(); compressor.setInput(inputBytes); compressor.finish(); // compress bytes to output stream byte[] buffer = new byte[4096]; ByteArrayOutputStream byteArrayOutputStream = new ByteArrayOutputStream(inputBytes.length); while (!compressor.finished()) { int bytes = compressor.deflate(buffer); byteArrayOutputStream.write(buffer, 0, bytes); } try { byteArrayOutputStream.close(); } catch (IOException e) { throw new RuntimeException("Failed to close ByteArrayOutputStream", e); } // return encoded string byte[] compressedBytes = byteArrayOutputStream.toByteArray(); return Base64.getEncoder().encodeToString(compressedBytes); } /** * Decompresses a valid String that has been compressed using the zlib compression library. * Decodes bytes with Base64 decoding scheme. * * @param input the String to be decompressed * @return the decompressed String */ public String decompress(String input) { byte[] inputBytes = Base64.getDecoder().decode((input)); // create decompressor Inflater decompressor = new Inflater(); decompressor.setInput(inputBytes, 0, inputBytes.length); // decompress bytes to output stream byte[] buffer = new byte[4096]; ByteArrayOutputStream byteArrayOutputStream = new ByteArrayOutputStream(inputBytes.length); try { while (!decompressor.finished()) { int bytes = decompressor.inflate(buffer); if (bytes == 0 && decompressor.needsInput()) { throw new DataFormatException("Input is truncated"); } byteArrayOutputStream.write(buffer, 0, bytes); } } catch (DataFormatException e) { throw new RuntimeException("Failed to decompress string", e); } try { byteArrayOutputStream.close(); } catch (IOException e) { throw new RuntimeException("Failed to close ByteArrayOutputStream", e); } // return decoded string byte[] decompressedBytes = byteArrayOutputStream.toByteArray(); return new String(decompressedBytes, StandardCharsets.UTF_8); } } ``` ## Membangun file JAR Jalankan`mvn clean install`untuk membangun proyek Anda. Setelah berhasil dibangun, file JAR dibuat di `target` folder proyek Anda bernama`artifactId-version.jar`, di mana nama *artifactId* yang Anda berikan dalam proyek Maven, misalnya,. `my-athena-udfs` ## Menyebarkan JAR ke AWS Lambda Anda memiliki dua pilihan untuk men-deploy kode Anda untuk Lambda: + Menyebarkan Menggunakan AWS Serverless Application Repository (Disarankan) + Buat Fungsi Lambda dari file JAR ### Opsi 1: Menyebarkan ke AWS Serverless Application Repository Ketika Anda menyebarkan file JAR Anda ke AWS Serverless Application Repository, Anda membuat file YAMM AWS SAM template yang mewakili arsitektur aplikasi Anda. Anda kemudian menentukan file YAML ini dan bucket Amazon S3 tempat artifact untuk aplikasi Anda di-upload dan dibuat tersedia untuk AWS Serverless Application Repository. Prosedur di bawah ini menggunakan[publish.sh](https://github.com/awslabs/aws-athena-query-federation/blob/master/tools/publish.sh)skrip yang terletak di`athena-query-federation/tools`dari Athena Kueri Federation SDK yang Anda kloning sebelumnya. Untuk informasi dan persyaratan selengkapnya, lihat [Menerbitkan aplikasi](https://docs.aws.amazon.com/serverlessrepo/latest/devguide/serverlessrepo-publishing-applications.html) di *Panduan AWS Serverless Application Repository Pengembang*, [konsep AWS SAM templat](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-template-basics.html) di *Panduan AWS Serverless Application Model Pengembang*, dan [Menerbitkan aplikasi tanpa server menggunakan CLI AWS SAM](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-template-publishing-applications.html). Contoh berikut menunjukkan parameter dalam file YAML. Tambahkan parameter serupa ke file YAML dan simpan di direktori proyek Anda. Lihat [athena-udf.yaml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-udfs/athena-udfs.yaml) untuk contoh lengkapnya. GitHub ``` Transform: 'AWS::Serverless-2016-10-31' Metadata: 'AWS::ServerlessRepo::Application': Name: MyApplicationName Description: 'The description I write for my application' Author: 'Author Name' Labels: - athena-federation SemanticVersion: 1.0.0 Parameters: LambdaFunctionName: Description: 'The name of the Lambda function that will contain your UDFs.' Type: String LambdaTimeout: Description: 'Maximum Lambda invocation runtime in seconds. (min 1 - 900 max)' Default: 900 Type: Number LambdaMemory: Description: 'Lambda memory in MB (min 128 - 3008 max).' Default: 3008 Type: Number Resources: ConnectorConfig: Type: 'AWS::Serverless::Function' Properties: FunctionName: !Ref LambdaFunctionName Handler: "full.path.to.your.handler. For example, com.amazonaws.athena.connectors.udfs.MyUDFHandler" CodeUri: "Relative path to your JAR file. For example, ./target/athena-udfs-1.0.jar" Description: "My description of the UDFs that this Lambda function enables." Runtime: java8 Timeout: !Ref LambdaTimeout MemorySize: !Ref LambdaMemory ``` Salin`publish.sh`script ke direktori proyek tempat Anda menyimpan file YAML Anda, dan jalankan perintah berikut: ``` ./publish.sh MyS3Location MyYamlFile ``` Misalnya, jika lokasi bucket Anda`s3://amzn-s3-demo-bucket/mysarapps/athenaudf`dan file YAML Anda disimpan sebagai`my-athena-udfs.yaml`: ``` ./publish.sh amzn-s3-demo-bucket/mysarapps/athenaudf my-athena-udfs ``` **Untuk membuat fungsi Lambda** 1. Buka konsol Lambda di [https://console.aws.amazon.com/lambda/](https://console.aws.amazon.com/lambda/), pilih **Create function**, lalu pilih **Browse serverless** app repository 1. Pilih**Aplikasi privat**, temukan aplikasi Anda dalam daftar, atau cari menggunakan kata-kata kunci, dan pilih. 1. Tinjau dan berikan detail aplikasi, lalu pilih**Terapkan.** Anda sekarang dapat menggunakan nama metode yang ditentukan dalam file JAR fungsi Lambda Anda seperti di UDFs Athena. ### Opsi 2: Buat fungsi Lambda secara langsung Anda juga dapat membuat fungsi Lambda secara langsung menggunakan konsol atau. AWS CLI Contoh berikut menunjukkan menggunakan Lambda`create-function`Perintah CLI. ``` aws lambda create-function \ --function-name MyLambdaFunctionName \ --runtime java8 \ --role arn:aws:iam::1234567890123:role/my_lambda_role \ --handler com.mycompany.athena.udfs.MyUserDefinedFunctions \ --timeout 900 \ --zip-file fileb://./target/my-athena-udfs-1.0-SNAPSHOT.jar ```