مشاركة عبر

الوظائف المعرفة من قبل المستخدم (UDFs) في كتالوج Unity

  • مقالة

هام

هذه الميزة في المعاينة العامة.

تعمل الوظائف المعرفة من قبل المستخدم (UDFs) في كتالوج Unity على توسيع قدرات SQL وPython داخل Azure Databricks. وهي تسمح بتعريف الوظائف المخصصة واستخدامها ومشاركتها وإدارتها بأمان عبر بيئات الحوسبة.

تختلف Python UDFs المسجلة كوظائف في كتالوج Unity في النطاق والدعم من PySpark UDFs النطاق إلى دفتر ملاحظات أو SparkSession. راجع الدالات العددية المعرفة من قبل المستخدم - Python.

راجع CREATE FUNCTION (SQL وPython) للحصول على مرجع لغة SQL الكامل.

المتطلبات

لاستخدام UDFs في كتالوج Unity، يجب استيفاء المتطلبات التالية:

  • لاستخدام تعليمة Python البرمجية في UDFs المسجلة في كتالوج Unity، يجب استخدام مستودع SQL بلا خادم أو pro أو نظام مجموعة يقوم بتشغيل Databricks Runtime 13.3 LTS أو أعلى.
  • إذا كانت طريقة العرض تتضمن UC Python UDF، فستفشل في SQL Classic Warehouses.

إنشاء UDFs في كتالوج Unity

لإنشاء UDF في كتالوج Unity، يحتاج المستخدمون إلى إذن USAGE وCREATE على المخطط وإذن USAGE في الكتالوج. راجع كتالوج Unity لمزيد من التفاصيل.

لتشغيل UDF، يحتاج المستخدمون إلى إذن EXECUTE على UDF. يحتاج المستخدمون أيضا إلى إذن USAGE على المخطط والكتالوج.

يسجل المثال التالي دالة جديدة إلى my_schema مخطط كتالوج Unity:

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

تستخدم Python UDFs ل Unity Catalog عبارات الاستخدام التي تعوضها علامات الدولار المزدوجة ($$). تحتاج أيضا إلى تحديد تعيين نوع البيانات. يسجل المثال التالي UDF الذي يحسب فهرس كتلة الجسم:

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

يمكنك الآن استخدام دالة كتالوج Unity هذه في استعلامات SQL أو التعليمات البرمجية PySpark:

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

استخدام كتالوج Unity UDF في PySpark

from pyspark.sql.functions import expr

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

ترقية UDF على نطاق جلسة عمل

إشعار

يختلف بناء الجملة ودلالات Python UDFs في كتالوج Unity عن Python UDFs المسجلة في SparkSession. راجع الوظائف العددية المعرفة من قبل المستخدم - Python.

نظرا إلى UDF المستند إلى جلسة العمل التالية في دفتر ملاحظات 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()

لتسجيل هذا كدالة كتالوج Unity، استخدم عبارة SQL CREATE FUNCTION ، كما في المثال التالي:

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

مشاركة UDFs في كتالوج Unity

تتم إدارة أذونات UDFs استنادا إلى عناصر التحكم في الوصول المطبقة على الكتالوج أو المخطط أو قاعدة البيانات حيث يتم تسجيل UDF. راجع كتالوج Unity لمزيد من المعلومات.

استخدم Azure Databricks SQL أو واجهة مستخدم مساحة عمل Azure Databricks لمنح أذونات لمستخدم أو مجموعة (مستحسن).

الأذونات في واجهة مستخدم مساحة العمل

  1. ابحث عن الكتالوج والمخطط حيث يتم تخزين UDF الخاص بك وحدد UDF.
  2. ابحث عن خيار الأذونات في إعدادات UDF. أضف مستخدمين أو مجموعات وحدد نوع الوصول الذي يجب أن يكون لديهم، مثل EXECUTE أو MANAGE.

! [الأذونات في واجهة مستخدم مساحة العمل](.. /_static/images/udf/high res udf permission.gif)

الأذونات باستخدام Azure Databricks SQL

يمنح المثال التالي المستخدم إذن EXECUTE على دالة:

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

لإزالة الأذونات REVOKE ، استخدم الأمر كما في المثال التالي:

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

أفضل الممارسات لUDFs

بالنسبة إلى UDFs التي يجب أن تكون متاحة لجميع المستخدمين، توصي Databricks بإنشاء كتالوج ومخطط مخصصين مع عناصر تحكم الوصول المناسبة.

بالنسبة إلى UDFs الخاصة بالفريق، استخدم مخططا مخصصا داخل كتالوج الفريق للتخزين والإدارة.

توصي Azure Databricks بتضمين المعلومات التالية في docstring الخاص ب UDF:

  • رقم الإصدار الحالي
  • سجل تغيير لتعقب التعديلات عبر الإصدارات
  • الغرض من UDF والمعلمات والقيمة المرجعة
  • مثال على كيفية استخدام UDF

فيما يلي مثال على UDF باتباع أفضل الممارسات:

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

UDFs للوصول إلى واجهات برمجة التطبيقات الخارجية

يمكنك استخدام UDFs للوصول إلى واجهات برمجة التطبيقات الخارجية من SQL. يستخدم المثال التالي مكتبة Python requests لتقديم طلب HTTP.

إشعار

تسمح Python UDFs بنسبة استخدام شبكة TCP/UDP عبر المنافذ 80 و443 و53 باستخدام حساب بلا خادم أو حساب تم تكوينه باستخدام وضع الوصول المشترك.

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

$$;

UDFs للأمان والتوافق

استخدم Python UDFs لتنفيذ الرموز المميزة المخصصة أو إخفاء البيانات أو تحويل البيانات أو آليات التشفير.

يخفي المثال التالي هوية عنوان البريد الإلكتروني مع الحفاظ على الطول والمجال:

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

يطبق المثال التالي UDF هذا في تعريف طريقة عرض ديناميكية:

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

القيود

  • يمكنك تحديد أي عدد من دوال Python داخل Python UDF ولكن يجب أن ترجع جميعها قيمة عددية.
  • يجب أن تتعامل دوال Python مع قيم NULL بشكل مستقل، ويجب أن تتبع جميع تعيينات النوع تعيينات لغة Azure Databricks SQL.
  • يمكنك استيراد مكتبات Python القياسية المضمنة في Azure Databricks، ولكن لا يمكنك تضمين مكتبات مخصصة أو تبعيات خارجية.
  • إذا لم يتم تحديد كتالوج أو مخطط، يتم تسجيل Python UDFs في المخطط النشط الحالي.
  • يتم تنفيذ Python UDFs في بيئة آمنة ومعزولة وليس لديها حق الوصول إلى أنظمة الملفات أو الخدمات الداخلية.