Aracılığıyla paylaş

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

  • Makale

Önemli

Bu özellik Genel Önizlemededir.

Unity Kataloğu'nda kullanıcı tanımlı işlevler (UDF' ler), Azure Databricks'teki 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 işlev olarak kaydedilen Python UDF'lerinin kapsamı ve desteği, kapsamı not defteri veya SparkSession olan 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 gereksinimlerin karşılanması 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.
  • Bir görünümde UC Python UDF varsa, bu görünüm SQL Klasik Ambarlarında başarısız olur.

Unity Kataloğu'nda UDF oluşturma

Unity Kataloğu'nda UDF oluşturmak için kullanıcıların şema üzerinde KULLANIM ve CREATE iznine ve katalogda KULLANIM 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.

Aşağıdaki örnek, Unity Kataloğu şemasına my_schema yeni bir işlev kaydeder:

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

Unity Kataloğu için Python UDF'leri çift dolar işaretine ($$) göre ifadeleri kullanır. Ayrıca bir veri türü eşlemesi de belirtmeniz gerekir. Aşağıdaki örnek, gövde kütle dizinini hesaplayan bir UDF kaydeder:

CREATE 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;

PySpark'ta Unity Kataloğu UDF'sini 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ı UDF'leri yükseltme

Not

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.

Azure Databricks not defterinde aşağıdaki oturum tabanlı UDF göz önünde bulundurulduğunda:

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 .

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.

! [Çalışma Alanı Kullanıcı Arabirimindeki İzinler](.. /_static/images/udf/high res udf permission.gif)

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 komutunu kullanın REVOKE :

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

UDF'ler için En İyi Yöntemler

Tüm kullanıcılar için erişilebilir olması gereken UDF'ler için Databricks, uygun erişim denetimleriyle ayrılmış bir katalog ve şema oluşturmanızı önerir.

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

Azure Databricks, UDF'nin docstring'ine 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'nin amacı, parametreleri ve dönüş değeri
  • UDF'yi kullanma örneği

Aşağıda aşağıdaki en iyi yöntemlerin bir UDF örneği verilmiştir:

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

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.

Not

Python UDF'leri, sunucusuz işlem veya paylaşılan erişim moduyla yapılandırılmış işlem kullanarak 80, 443 ve 53 numaralı bağlantı noktaları ü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()
   # Assuming 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
AS $$
parts = email.split('@')
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 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 |
+---+------------+------------------------+------------------------+

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.
  • Azure Databricks tarafından eklenen standart Python kitaplıklarını içeri aktarabilirsiniz, ancak özel kitaplıklar veya dış bağımlılıklar içeremezsiniz.
  • 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.