Unity Kataloğu'nda kullanıcı tanımlı işlevler (UDF)

Önemli

Bu özellik Genel Önizlemededir.

Unity Kataloğu'nda kullanıcı tanımlı işlevler (UDF' ler), Azure Databricks içindeki SQL ve Python özelliklerini genişletir. Bunlar, özel işlevlerin bilgi işlem ortamlarında tanımlanmasına, kullanılmasına ve güvenli bir şekilde paylaşılıp yönetilmesine olanak tanır.

Unity Kataloğu'nda fonksiyon olarak kaydedilen Python UDF'lerinin kapsamı ve desteği, bir not defterine veya SparkSession'a kapsamlanan PySpark UDF'lerinden farklıdır. Bkz . Kullanıcı tanımlı skaler işlevler - Python.

Tam SQL dil başvurusu için bkz. CREATE FUNCTION (SQL ve Python).

Gereksinimler

Unity Kataloğu'nda UDF'leri kullanmak için aşağıdaki gereksinimleri karşılamanız gerekir:

• Unity Kataloğu'nda kayıtlı UDF'lerde Python kodunu kullanmak için sunucusuz veya profesyonel bir SQL ambarı ya da Databricks Runtime 13.3 LTS veya üzerini çalıştıran bir küme kullanmanız gerekir.
• Görünüm Unity Kataloğu Python UDF içerdiğinde, klasik SQL ambarlarında başarısız olur.

Unity Kataloğu'nda UDF oluşturma

Unity Kataloğu'nda bir UDF oluşturmak için kullanıcıların şema üzerinde KULLANMA ve OLUŞTURMA iznine ve katalogda KULLANMA iznine sahip olması gerekir. Diğer ayrıntılar için bkz. Unity Kataloğu .

UDF çalıştırmak için kullanıcıların UDF üzerinde YÜRÜTME iznine sahip olması gerekir. Kullanıcıların şema ve katalog üzerinde KULLANIM iznine de sahip olması gerekir.

Unity Kataloğu şemasında UDF oluşturmak ve kaydetmek için işlev adı biçiminde catalog.schema.function_nameolmalıdır. Alternatif olarak, SQL Düzenleyicisi'nde doğru kataloğu ve şemayı seçebilirsiniz. Bu durumda işlev adınız buna eklenmemiş catalog.schema olmalıdır:

Aşağıdaki örnek, katalogdaki my_schema şemaya my_catalog yeni bir işlev kaydeder:

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

Unity Catalog için Python UDF'leri, ifadeleri çift dolar işareti ($$) ile belirtir. Veri türü eşlemesi belirtmeniz gerekir. Aşağıdaki örnek, vücut kitle indeksini hesaplayan bir UDF'nin nasıl kaydedileceğini gösterir.

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)
$$;

Artık bu Unity Kataloğu işlevini SQL sorgularınızda veya PySpark kodunuzda kullanabilirsiniz:

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

Daha fazla UDF örneği için bkz. Satır filtresi örnekleri ve Sütun maskesi örnekleri .

Özel bağımlılıkları kullanarak UDF'leri genişletme

Önemli

Bu özellik Genel Önizlemededir.

Dış kitaplıklar için özel bağımlılıklar tanımlayarak Unity Kataloğu Python UDF'lerinin işlevselliğini Databricks Runtime ortamının ötesine genişletin.

Aşağıdaki kaynaklardan bağımlılıkları yükleyin:

• PyPI paketleri
• Unity Kataloğu birimlerinde depolanan dosyalar UDF'yi çağıran kullanıcının kaynak birim üzerinde izinleri olmalıdır READ VOLUME .
• Genel URL'lerde kullanılabilen dosyalar Çalışma alanı ağ güvenlik kurallarınız genel URL'lere erişime izin vermelidir.

Uyarı

Sunucusuz SQL ambarından genel URL'lere erişime izin verecek şekilde ağ güvenlik kurallarını yapılandırmak için bkz. Databricks SQL ile doğrulama.

• Sunucusuz SQL ambarları, Özel bağımlılıklar için İnternet'e erişmek üzere çalışma alanınızın Önizlemeler sayfasındaSunucusuz SQL Ambarları'ndaki UDF'ler için ağ oluşturmayı etkinleştirme Genel Önizleme özelliğini gerektirir.

Unity Kataloğu UDF'leri için özel bağımlılıklar aşağıdaki işlem türlerinde desteklenir:

• Sunucusuz not defterleri ve işler
• Databricks Runtime sürüm 16.2 ve üzerini kullanan tüm amaçlı işlem
• Pro veya sunucusuz SQL ambarı

ENVIRONMENT Bağımlılıkları belirtmek için UDF tanımının bölümünü kullanın:

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))
$$;

ENVIRONMENT bölümü aşağıdaki alanları içerir:

Alan	Açıklama	Türü	Örnek kullanım
dependencies	Yüklenecek virgülle ayrılmış bağımlılıkların listesi. Her girdi , pip Gereksinimleri Dosya Biçimi'ne uyan bir dizedir.	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	UDF'nin çalıştırıldığı sunucusuz ortam sürümünü belirtir. Şu anda yalnızca değer None desteklenmektedir.	STRING	environment_version = 'None'

PySpark'ta Unity Kataloğu UDF'lerini kullanma

from pyspark.sql.functions import expr

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

Oturum kapsamlı bir UDF'yi yükseltme

Uyarı

Unity Kataloğu'nda Python UDF'leri için söz dizimi ve semantik, SparkSession'a kayıtlı Python UDF'lerinden farklıdır. Bkz . kullanıcı tanımlı skaler işlevler - Python.

Aşağıdaki oturum tabanlı UDF, bir Azure Databricks defterinde:

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()

Bunu Unity Kataloğu işlevi olarak kaydetmek için aşağıdaki örnekte olduğu gibi bir SQL CREATE FUNCTION deyimi kullanın:

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

Unity Kataloğu'nda UDF'leri paylaşma

UDF'lerin izinleri, UDF'nin kayıtlı olduğu kataloğa, şemaya veya veritabanına uygulanan erişim denetimlerine göre yönetilir. Daha fazla bilgi için bkz. Unity Kataloğu'nda ayrıcalıkları yönetme .

Bir kullanıcıya veya gruba izin vermek için Azure Databricks SQL veya Azure Databricks çalışma alanı kullanıcı arabirimini kullanın (önerilir).

Çalışma alanı kullanıcı arabirimindeki izinler

1. UDF'nizin depolandığı kataloğu ve şemayı bulun ve UDF'yi seçin.
2. UDF ayarlarında İzinler seçeneğini arayın. Kullanıcıları veya grupları ekleyin ve EXECUTE veya MANAGE gibi sahip olmaları gereken erişim türünü belirtin.

Azure Databricks SQL'i kullanma izinleri

Aşağıdaki örnek kullanıcıya bir işlev üzerinde EXECUTE izni verir:

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

İzinleri kaldırmak için aşağıdaki örnekte olduğu gibi REVOKE komutunu kullanın:

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

Ortam yalıtımı

Uyarı

Paylaşılan yalıtım ortamları Databricks Runtime 18.0 ve üzerini gerektirir. Önceki sürümlerde, tüm Unity Kataloğu Python UDF'leri katı yalıtım modunda çalışır.

Aynı sahipli ve oturumlu Unity Catalog Python UDF'leri varsayılan olarak bir yalıtım ortamını paylaşabilir. Bu, başlatılması gereken ayrı ortamların sayısını azaltarak performansı artırır ve bellek kullanımını azaltır.

Katı yalıtım

UDF'nin her zaman kendi, tamamen yalıtılmış ortamında çalıştığından emin olmak için karakteristik yan tümcesini STRICT ISOLATION ekleyin.

Çoğu UDF'nin katı yalıtıma ihtiyacı yoktur. Standart veri işleme UDF'leri varsayılan paylaşılan yalıtım ortamından yararlanır ve daha düşük bellek tüketimiyle daha hızlı çalışır.

Şu özelliklere sahip STRICT ISOLATION UDF'lere karakteristik yan tümcesini ekleyin:

• , eval()veya benzer işlevleri kullanarak exec()girişi kod olarak çalıştırın.
• Dosyaları yerel dosya sistemine yazın.
• Genel değişkenleri veya sistem durumunu değiştirin.
• Ortam değişkenlerine erişme veya değişkenleri değiştirme.

Aşağıdaki kod, kullanılarak çalıştırılması gereken bir UDF örneğini gösterir. Bu UDF rastgele Python kodu yürütür, bu nedenle sistem durumunu değiştirebilir, ortam değişkenlerine erişebilir veya yerel dosya sistemine yazabilir. STRICT ISOLATION maddesinin kullanılması, UDF'ler arasında girişim veya veri sızıntılarını önlemeyi destekler.

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()
$$

İşlevinizin tutarlı sonuçlar üretip üretmediğini ayarlama DETERMINISTIC

Aynı girişler için aynı çıkışları oluşturuyorsa işlev tanımınıza ekleyin DETERMINISTIC . Bu, sorgu iyileştirmelerinin performansı geliştirmesine olanak tanır.

Varsayılan olarak, Batch Unity Kataloğu Python UDF'lerinin açıkça bildirilmediği sürece belirleyici olmadığı varsayılır. Belirlenemeyen işlevlere örnek olarak rastgele değerler oluşturma, geçerli saatlere veya tarihlere erişme veya dış API çağrıları yapma verilebilir.

Bkz.CREATE FUNCTION (SQL ve Python)

Yapay zeka ajanı araçları için Kullanıcı Tanımlı Fonksiyonlar (UDF'ler)

Üretken yapay zeka aracıları, görevleri gerçekleştirmek ve özel mantık yürütmek için Unity Kataloğu UDF'lerini araç olarak kullanabilir.

Bkz. Unity Kataloğu işlevlerini kullanarak yapay zeka aracısı araçları oluşturma.

Dış API'lere erişmek için UDF'ler

DıŞ API'lere SQL'den erişmek için UDF'leri kullanabilirsiniz. Aşağıdaki örnek, HTTP isteğinde bulunmak için Python requests kitaplığını kullanır.

Uyarı

Python UDF'leri, sunucusuz işlem veya standart erişim moduyla yapılandırılmış işlem kullanıldığında, 80, 443 ve 53 numaralı portlar üzerinden TCP/UDP ağ trafiğine izin verir.

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

$$;

Güvenlik ve uyumluluk için UDF'ler

Özel belirteç oluşturma, veri maskeleme, veri yeniden düzenleme veya şifreleme mekanizmaları uygulamak için Python UDF'lerini kullanın.

Aşağıdaki örnek, uzunluğu ve etki alanını korurken e-posta adresinin kimliğini maskeler:

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}"
$$

Aşağıdaki örnek, bu UDF'yi dinamik görünüm tanımına uygular:

-- 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 |
+---+------------+------------------------+------------------------+

En iyi yöntemler

UDF'lerin tüm kullanıcılar tarafından erişilebilir olması için uygun erişim denetimleriyle ayrılmış bir katalog ve şema oluşturmanızı öneririz.

Takıma özgü UDF'ler için, depolama ve yönetim için ekip kataloğu içinde ayrılmış bir şema kullanın.

Databricks, UDF docstring'e aşağıdaki bilgileri eklemenizi önerir:

• Geçerli sürüm numarası
• Sürümler arasında değişiklikleri izlemek için bir değişiklik günlüğü
• UDF amacı, parametreleri ve dönüş değeri
• UDF'yi kullanma örneği

İşte en iyi uygulamaları izleyen bir UDF örneği:

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)
$$;

Girişler için saat dilimi zaman damgası davranışı

Databricks Runtime 18.0 ve üzerinde değerler Python UDF'lerine geçirildiğinde TIMESTAMP değerler UTC'de kalır ancak saat dilimi meta verileri (tzinfo öznitelik) nesneye datetime dahil değildir.

Bu değişiklik, Unity Catalog Python UDF'lerini Apache Spark'ta Arrow ile optimize edilmiş Python UDF'leriyle hizalar.

Örneğin, aşağıdaki sorgu:

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');

Bu çıkışı daha önce 18.0 öncesi Databricks Runtime sürümlerinde üretmişti:

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

Databricks Runtime 18.0 ve üzeri sürümlerde artık şu çıktıyı üretir:

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

UDF'niz saat dilimi bilgilerine bağlıysa, bunu açıkça geri yüklemeniz gerekir:

from datetime import timezone

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

Sınırlamalar

• Python UDF içinde istediğiniz sayıda Python işlevi tanımlayabilirsiniz, ancak tümünün skaler değer döndürmesi gerekir.
• Python işlevlerinin NULL değerleri bağımsız olarak işlemesi ve tüm tür eşlemelerinin Azure Databricks SQL dil eşlemelerini izlemesi gerekir.
• Katalog veya şema belirtilmezse, Python UDF'leri geçerli etkin şemaya kaydedilir.
• Python UDF'leri güvenli, yalıtılmış bir ortamda yürütülür ve dosya sistemlerine veya iç hizmetlere erişimi yoktur.
• Sorgu başına beşten fazla UDF çağıramazsınız.