Megosztás a következőn keresztül:

Felhasználó által definiált függvények (UDF-ek) a Unity Katalógusban

  • Cikk

Fontos

Ez a funkció a nyilvános előzetes verzióban érhető el.

A Unity Catalog felhasználó által definiált függvényei (UDF-ek) kibővítik az SQL és a Python képességeit az Azure Databricksben. Lehetővé teszik az egyéni függvények meghatározását, használatát, biztonságos megosztását és szabályozását a számítási környezetekben.

A Unity-katalógusban függvényként regisztrált Python UDF-ek hatóköre és támogatása eltér a pySpark UDF-ektől a jegyzetfüzetig vagy a SparkSessionig. Lásd: Felhasználó által definiált skaláris függvények – Python.

A teljes SQL-nyelvi referenciaért tekintse meg a CREATE FÜGGVÉNYt (SQL és Python).

Követelmények

Az UDF-ek Unity Catalogban való használatához a következő követelményeknek kell teljesülniük:

  • A Unity Catalogban regisztrált UDF-ekben használt Python-kód használatához kiszolgáló nélküli vagy pro SQL-tárolót vagy Databricks Runtime 13.3 LTS-t vagy újabb verziót futtató fürtöt kell használnia.
  • Ha egy nézet tartalmaz egy UC Python UDF-et, az a klasszikus SQL-tárolókon sikertelen lesz.

UDF-ek létrehozása a Unity Katalógusban

Az UDF Unity-katalógusban való létrehozásához a felhasználóknak HASZNÁLATI és LÉTREHOZÁSi engedélyre van szükségük a katalógus sémájára és HASZNÁLATI engedélyére. További részletekért tekintse meg a Unity katalógusát .

Egy UDF futtatásához a felhasználóknak végrehajtási engedélyre van szükségük az UDF-en. A felhasználóknak használati engedélyre is szükségük van a sémához és a katalógushoz.

Az alábbi példa egy új függvényt regisztrál a my_schema Unity Catalog sémába:

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

A Unity Catalog pythonos UDF-jei dupla dollárjelekkel ($$) eltolt utasításokat használnak. Meg kell adnia egy adattípus-leképezést is. Az alábbi példa egy olyan UDF-t regisztrál, amely kiszámítja a testtömegindexet:

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

Most már használhatja ezt a Unity Catalog függvényt az SQL-lekérdezésekben vagy a PySpark-kódban:

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

A Unity Catalog UDF használata a PySparkban

from pyspark.sql.functions import expr

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

Munkamenet-hatókörű UDF frissítése

Feljegyzés

A Unity Catalog pythonos UDF-jeinek szintaxisa és szemantikája eltér a SparkSession-ben regisztrált Python UDF-ektől. Lásd: felhasználó által definiált skaláris függvények – Python.

Egy Azure Databricks-jegyzetfüzetben a következő munkamenet-alapú UDF-et használja:

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

Ha ezt Unity Catalog-függvényként szeretné regisztrálni, használjon egy SQL-utasítást CREATE FUNCTION , ahogyan az alábbi példában is látható:

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

UDF-ek megosztása a Unity Katalógusban

Az UDF-ek engedélyeinek kezelése a katalógusra, sémára vagy adatbázisra alkalmazott hozzáférés-vezérlők alapján történik, ahol az UDF regisztrálva van. További információt a Unity katalógusában talál.

Az Azure Databricks SQL vagy az Azure Databricks-munkaterület felhasználói felületének használatával adjon engedélyeket egy felhasználónak vagy csoportnak (ajánlott).

Engedélyek a munkaterület felhasználói felületén

  1. Keresse meg azt a katalógust és sémát, amelyben az UDF van tárolva, és válassza ki az UDF-et.
  2. Keresse meg az Engedélyek lehetőséget az UDF beállításai között. Adjon hozzá felhasználókat vagy csoportokat, és adja meg a hozzáférés típusát, például az EXECUTE vagy a MANAGE lehetőséget.

! [Engedélyek a munkaterület felhasználói felületén](.. /_static/images/udf/high res udf permission.gif)

Engedélyek az Azure Databricks SQL használatával

Az alábbi példa az EXECUTE engedélyt ad a felhasználónak egy függvényen:

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

Az engedélyek eltávolításához használja a parancsot az REVOKE alábbi példához hasonlóan:

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

Ajánlott eljárások az UDF-ekhez

Azoknak az UDF-eknek, amelyeknek minden felhasználó számára elérhetőnek kell lenniük, a Databricks azt javasolja, hogy hozzon létre egy dedikált katalógust és sémát a megfelelő hozzáférés-vezérléssel.

Csapatspecifikus UDF-ekhez használjon egy dedikált sémát a csapat katalógusában a tároláshoz és a felügyelethez.

Az Azure Databricks a következő információkat javasolja a UDF dokumentációjában:

  • Az aktuális verziószám
  • Változásnapló a verziók módosításainak nyomon követéséhez
  • Az UDF célja, paraméterei és visszatérési értéke
  • Példa az UDF használatára

Íme egy példa egy UDF-re, amely az alábbi ajánlott eljárásokat követi:

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

UDF-ek külső API-k eléréséhez

Az UDF-ekkel külső API-kat érhet el az SQL-ből. Az alábbi példa a Python-kódtár requests használatával hoz létre HTTP-kérést.

Feljegyzés

A Python UDF-ek lehetővé teszik a TCP/UDP hálózati forgalmat a 80-as, a 443-as és az 53-as porton a megosztott hozzáférési móddal konfigurált kiszolgáló nélküli számítással vagy számítással.

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

$$;

UDF-ek a biztonsághoz és a megfelelőséghez

Egyéni jogkivonatok, adatmaszkolás, adatátfedés vagy titkosítási mechanizmusok implementálása Python UDF-ekkel.

Az alábbi példa elfedi egy e-mail-cím identitását a hossz és a tartomány megőrzése mellett:

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

Az alábbi példa ezt az UDF-et egy dinamikus nézetdefinícióban alkalmazza:

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

Korlátozások

  • A Python UDF-ben tetszőleges számú Python-függvényt definiálhat, de mindegyiknek skaláris értéket kell visszaadnia.
  • A Python-függvényeknek egymástól függetlenül kell kezelnie a NULL értékeket, és minden típusleképezésnek követnie kell az Azure Databricks SQL nyelvi leképezéseit.
  • Az Azure Databricks által tartalmazott standard Python-kódtárakat importálhatja, de egyéni kódtárakat vagy külső függőségeket nem.
  • Ha nincs megadva katalógus vagy séma, a Python UDF-ek regisztrálva lesznek az aktuális aktív sémában.
  • A Python UDF-ek biztonságos, elkülönített környezetben futnak, és nem rendelkeznek hozzáféréssel a fájlrendszerekhez vagy a belső szolgáltatásokhoz.