Fungsi yang ditentukan pengguna (UDF) di Unity Catalog

Penting

Fitur ini ada di Pratinjau Publik.

Fungsi yang ditentukan pengguna (UDF) di Unity Catalog memperluas kemampuan SQL dan Python dalam Azure Databricks. Fungsi kustom memungkinkan untuk didefinisikan, digunakan, serta dibagikan dan diatur dengan aman di seluruh lingkungan komputasi.

UDF Python yang terdaftar sebagai fungsi di dalam Unity Catalog berbeda dalam cakupan dan dukungan dari UDF PySpark yang ruang lingkupnya terbatas pada notebook atau SparkSession. Lihat Fungsi skalar yang ditentukan pengguna - Python.

Lihat CREATE FUNCTION (SQL dan Python) untuk referensi bahasa SQL lengkap.

Persyaratan

Untuk menggunakan UDF di Unity Catalog, Anda harus memenuhi persyaratan berikut:

  • Untuk menggunakan kode Python di UDF yang terdaftar di Unity Catalog, Anda harus menggunakan gudang SQL tanpa server atau pro atau kluster yang menjalankan Databricks Runtime 13.3 LTS atau lebih tinggi.
  • Jika tampilan menyertakan Unity Catalog Python UDF, tampilan gagal pada gudang SQL klasik.
  • Dukungan instans ARM untuk Scala UDF pada kluster yang mendukung Unity Catalog tersedia di Databricks Runtime 15.2 ke atas.

Membuat UDF di Unity Catalog

Untuk membuat UDF di Katalog Unity, pengguna memerlukan izin USAGE dan CREATE pada skema dan izin USAGE pada katalog. Lihat Unity Catalog untuk detail selengkapnya.

Untuk menjalankan UDF, pengguna memerlukan izin EXECUTE pada UDF. Pengguna juga memerlukan izin PENGGUNAAN pada skema dan katalog.

Untuk membuat dan mendaftarkan UDF dalam skema Katalog Unity, nama fungsi harus mengikuti format catalog.schema.function_name. Atau, Anda dapat memilih katalog dan skema yang benar di Editor SQL. Dalam hal ini, nama fungsi Anda seharusnya tidak catalog.schema diletakkan di depannya.

Membuat UDF dengan katalog dan skema yang telah dipilih sebelumnya.

Contoh berikut mendaftarkan fungsi baru ke my_schema skema dalam my_catalog katalog:

CREATE OR REPLACE FUNCTION my_catalog.my_schema.calculate_bmi(weight DOUBLE, height DOUBLE)
RETURNS DOUBLE
LANGUAGE SQL
RETURN
SELECT weight / (height * height);

UDF Python untuk Katalog Unity menggunakan pernyataan dengan awalan tanda dolar ganda ($$). Anda harus menentukan pemetaan tipe data. Contoh berikut mendaftarkan UDF yang menghitung indeks massa tubuh:

CREATE OR REPLACE FUNCTION my_catalog.my_schema.calculate_bmi(weight_kg DOUBLE, height_m DOUBLE)
RETURNS DOUBLE
LANGUAGE PYTHON
AS $$
return weight_kg / (height_m ** 2)
$$;

Sekarang Anda dapat menggunakan fungsi Katalog Unity ini dalam kueri SQL atau kode PySpark Anda:

SELECT person_id, my_catalog.my_schema.calculate_bmi(weight_kg, height_m) AS bmi
FROM person_data;

Lihat Contoh filter baris dan Contoh masker kolom untuk contoh UDF lainnya.

Perluas UDF menggunakan dependensi kustom

Penting

Fitur ini ada di Pratinjau Publik.

Perluas fungsionalitas Unity Catalog Python UDF di luar lingkungan Databricks Runtime dengan menentukan dependensi kustom untuk pustaka eksternal.

Instal dependensi dari sumber berikut:

  • Paket PyPI
  • File yang disimpan dalam volume Katalog Unity Pengguna yang memanggil UDF harus memiliki izin READ VOLUME pada volume sumber.
  • File tersedia di URL publik Aturan keamanan jaringan ruang kerja Anda harus mengizinkan akses ke URL publik.

Catatan

Untuk mengonfigurasi aturan keamanan jaringan untuk mengizinkan akses ke URL publik dari gudang SQL tanpa server, lihat Memvalidasi dengan Databricks SQL.

  • Gudang SQL Tanpa Server memerlukan fitur Pratinjau Publik Mengaktifkan jaringan untuk beban kerja terisolasi di Gudang SQL Tanpa Server untuk diaktifkan di halaman Pratinjau ruang kerja Anda untuk mengakses internet untuk dependensi kustom.

Dependensi kustom untuk UDF Unity Catalog didukung pada jenis komputasi berikut:

  • Buku catatan dan pekerjaan tanpa server
  • Komputasi serba guna menggunakan Databricks Runtime versi 16.2 ke atas
  • Gudang SQL pro atau tanpa server

Gunakan bagian ENVIRONMENT definisi UDF untuk menentukan dependensi:

CREATE OR REPLACE FUNCTION my_catalog.my_schema.mixed_process(data STRING)
RETURNS STRING
LANGUAGE PYTHON
ENVIRONMENT (
  dependencies = '["simplejson==3.19.3", "/Volumes/my_catalog/my_schema/my_volume/packages/custom_package-1.0.0.whl", "https://my-bucket.s3.amazonaws.com/packages/special_package-2.0.0.whl?Expires=2043167927&Signature=abcd"]',
  environment_version = 'None'
)
AS $$
import simplejson as json
import custom_package
return json.dumps(custom_package.process(data))
$$;

Bagian ENVIRONMENT berisi bidang berikut:

Bidang Deskripsi Tipe Contoh penggunaan
dependencies Daftar dependensi yang dipisahkan oleh koma untuk diinstal. Setiap entri adalah string yang sesuai dengan Format File Persyaratan pip . STRING dependencies = '["simplejson==3.19.3", "/Volumes/catalog/schema/volume/packages/my_package-1.0.0.whl"]'
dependencies = '["https://my-bucket.s3.amazonaws.com/packages/my_package-2.0.0.whl?Expires=2043167927&Signature=abcd"]'
environment_version Menentukan versi lingkungan tanpa server untuk menjalankan UDF.
Saat ini, hanya nilai None yang didukung.		 STRING environment_version = 'None'

Menggunakan Unity Catalog UDF di PySpark

from pyspark.sql.functions import expr

result = df.withColumn("bmi", expr("my_catalog.my_schema.calculate_bmi(weight_kg, height_m)"))
display(result)

Memperbarui UDF yang dibatasi oleh sesi

Catatan

Sintaksis dan semantik untuk UDF Python di Unity Catalog berbeda dari UDF Python yang terdaftar di SparkSession. Lihat fungsi skalar yang ditentukan pengguna - Python.

Diberikan UDF berbasis sesi berikut pada notebook Azure Databricks:

from pyspark.sql.functions import udf
from pyspark.sql.types import StringType

@udf(StringType())
def greet(name):
    return f"Hello, {name}!"

# Using the session-based UDF
result = df.withColumn("greeting", greet("name"))
result.show()

Untuk mendaftarkan ini sebagai fungsi Katalog Unity, gunakan pernyataan CREATE FUNCTION SQL, seperti dalam contoh berikut:

CREATE OR REPLACE FUNCTION my_catalog.my_schema.greet(name STRING)
RETURNS STRING
LANGUAGE PYTHON
AS $$
return f"Hello, {name}!"
$$

Bagikan UDF di Unity Catalog

Izin untuk UDF dikelola berdasarkan kontrol akses yang diterapkan ke katalog, skema, atau database tempat UDF terdaftar. Lihat Mengelola hak istimewa di Katalog Unity untuk informasi selengkapnya.

Gunakan Azure Databricks SQL atau UI ruang kerja Azure Databricks untuk memberikan izin kepada pengguna atau grup (disarankan).

Izin di UI ruang kerja

  1. Temukan katalog dan skema tempat UDF Anda disimpan dan pilih UDF.
  2. Cari opsi Izin di pengaturan UDF. Tambahkan pengguna atau grup dan tentukan jenis akses yang harus mereka miliki, seperti EXECUTE atau MANAGE.

Hak Akses di UI Ruang Kerja

Izin untuk menggunakan Azure Databricks SQL

Contoh berikut memberi pengguna izin EXECUTE pada fungsi:

GRANT EXECUTE ON FUNCTION my_catalog.my_schema.calculate_bmi TO `user@example.com`;

Untuk menghapus izin, gunakan perintah REVOKE seperti dalam contoh berikut:

REVOKE EXECUTE ON FUNCTION my_catalog.my_schema.calculate_bmi FROM `user@example.com`;

Isolasi lingkungan

Catatan

Lingkungan isolasi bersama memerlukan Databricks Runtime 18.0 ke atas. Dalam versi sebelumnya, semua Unity Catalog Python UDF berjalan dalam mode isolasi yang ketat.

Unity Catalog Python UDFs dengan pemilik dan sesi yang sama dapat berbagi lingkungan isolasi secara default. Ini meningkatkan performa dan mengurangi penggunaan memori dengan mengurangi jumlah lingkungan terpisah yang perlu diluncurkan.

Isolasi ketat

Untuk memastikan UDF selalu berjalan di lingkungannya sendiri yang sepenuhnya terisolasi, tambahkan STRICT ISOLATION klausa karakteristik.

Sebagian besar UDF tidak memerlukan isolasi yang ketat. UDF pemrosesan data standar mendapat manfaat dari lingkungan isolasi bersama default dan berjalan lebih cepat dengan konsumsi memori yang lebih rendah.

Tambahkan klausa karakteristik STRICT ISOLATION ke UDF yang:

  • Jalankan input sebagai kode menggunakan eval(), exec(), atau fungsi serupa.
  • Tulis file ke sistem file lokal.
  • Ubah variabel global atau status sistem.
  • Mengakses atau mengubah variabel lingkungan.

Kode berikut menunjukkan contoh UDF yang harus dijalankan menggunakan STRICT ISOLATION. UDF ini menjalankan kode Python sewenang-wenang, sehingga dapat mengubah status sistem, mengakses variabel lingkungan, atau menulis ke sistem file lokal. Menggunakan klausa STRICT ISOLATION membantu mencegah gangguan atau kebocoran data antar UDF.

CREATE OR REPLACE TEMPORARY FUNCTION run_python_snippet(python_code STRING)
RETURNS STRING
LANGUAGE PYTHON
STRICT ISOLATION
AS $$
import sys
from io import StringIO

# Capture standard output and error streams
captured_output = StringIO()
captured_errors = StringIO()
sys.stdout = captured_output
sys.stderr = captured_errors

try:
    # Execute the user-provided Python code in an empty namespace
    exec(python_code, {})
except SyntaxError:
    # Retry with escaped characters decoded (for cases like "\n")
    def decode_code(raw_code):
        return raw_code.encode('utf-8').decode('unicode_escape')
    python_code = decode_code(python_code)
    exec(python_code, {})

# Return everything printed to stdout and stderr
return captured_output.getvalue() + captured_errors.getvalue()
$$

Atur DETERMINISTIC jika fungsi Anda menghasilkan hasil yang konsisten

Tambahkan DETERMINISTIC ke definisi fungsi Anda jika menghasilkan output yang sama untuk input yang sama. Ini memungkinkan pengoptimalan kueri untuk meningkatkan performa.

Secara bawaan, UDF Python Unity Catalog Batch diasumsikan tidak deterministik kecuali dinyatakan secara eksplisit. Contoh fungsi non-deterministik termasuk menghasilkan nilai acak, mengakses waktu atau tanggal saat ini, atau melakukan panggilan API eksternal.

Lihat CREATE FUNCTION (SQL dan Python)

UDF untuk alat agen AI

Agen AI generatif dapat menggunakan UDF Unity Catalog sebagai alat untuk melakukan tugas dan menjalankan logika kustom.

Lihat Membuat alat agen AI menggunakan fungsi Unity Catalog.

UDF untuk mengakses API eksternal

Anda dapat menggunakan UDF untuk mengakses API eksternal dari SQL. Contoh berikut menggunakan pustaka Python requests untuk membuat permintaan HTTP.

Catatan

UDF Python memungkinkan lalu lintas jaringan TCP/UDP melalui port 80, 443, dan 53 saat menggunakan komputasi atau komputasi tanpa server yang dikonfigurasi dengan mode akses standar.

CREATE FUNCTION my_catalog.my_schema.get_food_calories(food_name STRING)
RETURNS DOUBLE
LANGUAGE PYTHON
AS $$
import requests

api_url = f"https://example-food-api.com/nutrition?food={food_name}"
response = requests.get(api_url)

if response.status_code == 200:
   data = response.json()
   # Assume the API returns a JSON object with a 'calories' field
   calories = data.get('calories', 0)
   return calories
else:
   return None  # API request failed

$$;

UDF untuk keamanan dan kepatuhan

Gunakan UDF Python untuk menerapkan tokenisasi kustom, masking data, redaksi data, atau mekanisme enkripsi.

Contoh berikut menutupi identitas alamat email sambil mempertahankan panjang dan domain:

CREATE OR REPLACE FUNCTION my_catalog.my_schema.mask_email(email STRING)
RETURNS STRING
LANGUAGE PYTHON
DETERMINISTIC
AS $$
parts = email.split('@', 1)
if len(parts) == 2:
  username, domain = parts
else:
  return None
masked_username = username[0] + '*' * (len(username) - 2) + username[-1]
return f"{masked_username}@{domain}"
$$

Contoh berikut menerapkan UDF ini dalam definisi tampilan dinamis:

-- First, create the view
CREATE OR REPLACE VIEW my_catalog.my_schema.masked_customer_view AS
SELECT
  id,
  name,
  my_catalog.my_schema.mask_email(email) AS masked_email
FROM my_catalog.my_schema.customer_data;

-- Now you can query the view
SELECT * FROM my_catalog.my_schema.masked_customer_view;

+---+------------+------------------------+------------------------+
| id|        name|                   email|           masked_email |
+---+------------+------------------------+------------------------+
|  1|    John Doe|   john.doe@example.com |  j*******e@example.com |
|  2| Alice Smith|alice.smith@company.com |a**********h@company.com|
|  3|   Bob Jones|    bob.jones@email.org |   b********s@email.org |
+---+------------+------------------------+------------------------+

Praktik terbaik

Agar UDF dapat diakses oleh semua pengguna, sebaiknya buat katalog dan skema khusus dengan kontrol akses yang sesuai.

Untuk UDF khusus tim, gunakan skema khusus dalam katalog tim untuk penyimpanan dan manajemen.

Databricks merekomendasikan Anda menyertakan informasi berikut dalam docstring UDF:

  • Nomor versi saat ini
  • Changelog untuk melacak modifikasi di seluruh versi
  • Tujuan UDF, parameter, dan nilai pengembalian
  • Contoh cara menggunakan UDF

Berikut adalah contoh UDF yang mengikuti praktik terbaik:

CREATE OR REPLACE FUNCTION my_catalog.my_schema.calculate_bmi(weight_kg DOUBLE, height_m DOUBLE)
RETURNS DOUBLE
COMMENT "Calculates Body Mass Index (BMI) from weight and height."
LANGUAGE PYTHON
DETERMINISTIC
AS $$
 """
Parameters:
calculate_bmi (version 1.2):
- weight_kg (float): Weight of the individual in kilograms.
- height_m (float): Height of the individual in meters.

Returns:
- float: The calculated BMI.

Example Usage:

SELECT calculate_bmi(weight, height) AS bmi FROM person_data;

Change Log:
- 1.0: Initial version.
- 1.1: Improved error handling for zero or negative height values.
- 1.2: Optimized calculation for performance.

 Note: BMI is calculated as weight in kilograms divided by the square of height in meters.
 """
if height_m <= 0:
 return None  # Avoid division by zero and ensure height is positive
return weight_kg / (height_m ** 2)
$$;

Perilaku zona waktu cap waktu untuk masukan

Dalam Databricks Runtime 18.0 ke atas, ketika TIMESTAMP nilai diteruskan ke UDF Python, nilai tetap dalam UTC tetapi metadata zona waktu (tzinfo atribut) tidak disertakan dalam datetime objek.

Perubahan ini menyelaraskan Unity Catalog Python UDFs dengan Python UDF yang dioptimalkan menggunakan Arrow di Apache Spark.

Misalnya, kueri berikut:

CREATE FUNCTION timezone_udf(date TIMESTAMP)
RETURNS STRING
LANGUAGE PYTHON
AS $$
return f"{type(date)} {date} {date.tzinfo}"
$$;

SELECT timezone_udf(TIMESTAMP '2024-10-23 10:30:00');

Sebelumnya menghasilkan output ini dalam versi Databricks Runtime sebelum 18.0:

<class 'datetime.datetime'> 2024-10-23 10:30:00+00:00 Etc/UTC

Di Databricks Runtime 18.0 ke atas, sekarang menghasilkan output ini:

<class 'datetime.datetime'> 2024-10-23 10:30:00+00:00 None

Jika UDF Anda bergantung pada informasi zona waktu, Anda perlu memulihkannya secara eksplisit:

from datetime import timezone

date = date.replace(tzinfo=timezone.utc)

Batasan

  • Anda dapat menentukan sejumlah fungsi Python dalam UDF Python, tetapi semuanya harus mengembalikan nilai skalar.
  • Fungsi Python harus menangani nilai NULL secara independen, dan semua pemetaan jenis harus mengikuti pemetaan bahasa Azure Databricks SQL.
  • Jika tidak ada katalog atau skema yang ditentukan, UDF Python terdaftar ke skema aktif saat ini.
  • UDF Python dijalankan di lingkungan yang aman dan terisolasi dan tidak memiliki akses ke sistem file atau layanan internal.
  • Anda tidak dapat memanggil lebih dari lima UDF per kueri.
  • Last updated on