Sdílet prostřednictvím

Uživatelem definované funkce (UDF) v katalogu Unity

  • Článek

Důležité

Tato funkce je ve verzi Public Preview.

Uživatelem definované funkce (UDF) v katalogu Unity rozšiřují možnosti SQL a Pythonu v Rámci Azure Databricks. Umožňují definovat, používat a bezpečně sdílet a řídit vlastní funkce napříč výpočetními prostředími.

Uživatelem definované funkce (UDF) Pythonu zaregistrované jako funkce v Unity Catalog se liší v rozsahu a podpoře ve srovnání s PySpark UDF, které jsou omezeny na poznámkový blok nebo SparkSession. Viz uživatelem definované skalární funkce – Python.

Kompletní referenční informace k jazyku SQL najdete v (SQL a Python).

Požadavky

Používání uživatelsky definovaných funkcí v katalogu Unity vyžaduje splnění následujících požadavků:

  • Pokud chcete použít kód Pythonu v UDFs registrovaných v katalogu Unity, musíte použít bezserverový nebo profi SQL Warehouse nebo cluster s Databricks Runtime 13.3 LTS nebo novějším.
  • Pokud zobrazení obsahuje uživatelem definovanou uživatelem v UC Pythonu, u sql Classic Warehouse selže.

Vytváření uživatelem definovaných funkcí v Unity Catalogu

Pokud chcete vytvořit uživatelem definovanou funkci (UDF) v katalogu Unity, uživatelé potřebují oprávnění USAGE a CREATE ke schématu a oprávnění USAGE k katalogu. Podívejte se na Unity Catalog pro více podrobností.

Aby uživatelé mohli spustit UDF, musí mít oprávnění EXECUTE pro UDF. Uživatelé také potřebují oprávnění USAGE pro schéma a katalog.

Následující příklad zaregistruje novou funkci do schématu katalogu 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);

Pythonové UDF pro Unity Catalog používají příkazy odsazené dvojitými dolarovými znaky ($$). Musíte také zadat mapování datového typu. Následující příklad zaregistruje UDF, který vypočítá index hmotnosti těla:

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

Teď můžete použít tuto funkci Katalogu Unity v dotazech SQL nebo kódu PySpark:

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

Použití UDF katalogu Unity v PySparku

from pyspark.sql.functions import expr

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

Upgrade UDF s vymezeným oborem relace

Poznámka:

Syntaxe a sémantika uživatelem definovaných funkcí Pythonu v katalogu Unity se liší od funkcí definovaných uživatelem Pythonu registrovaných ve SparkSession. Viz uživatelem definované skalární funkce – Python.

Vzhledem k následujícímu uživatelem definovanému uživatelem založenému na relacích v poznámkovém bloku 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()

Pokud chcete tuto funkci zaregistrovat jako funkci Katalogu Unity, použijte příkaz SQL CREATE FUNCTION, jak je znázorněno v následujícím příkladu:

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

Sdílení uživatelem definovaných souborů v katalogu Unity

Oprávnění pro UDF se spravují na základě řízení přístupu použitého v katalogu, schématu nebo databázi, kde je UDF registrován. Pro více informací se podívejte na Unity katalog.

Pomocí azure Databricks SQL nebo uživatelského rozhraní pracovního prostoru Azure Databricks udělte oprávnění uživateli nebo skupině (doporučeno).

Oprávnění v uživatelském rozhraní pracovního prostoru

  1. Vyhledejte katalog a schéma, kde je uložená vaše uživatelsky definovaná funkce, a vyberte tuto funkci.
  2. V nastavení UDF vyhledejte možnost Oprávnění . Přidejte uživatele nebo skupiny a zadejte typ přístupu, který mají mít, například EXECUTE nebo MANAGE.

oprávnění v uživatelském rozhraní pracovního prostoru

Oprávnění pomocí Azure Databricks SQL

Následující příklad uživateli udělí oprávnění EXECUTE pro funkci:

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

Pokud chcete oprávnění odebrat, použijte příkaz REVOKE jako v následujícím příkladu:

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

Osvědčené postupy pro uživatelem definované uživatelem

Pro UDF, které musí být přístupné všem uživatelům, Databricks doporučuje vytvořit vyhrazený katalog a schéma s odpovídajícími přístupovými právy.

Pro uživatelem definované funkce specifické pro tým použijte vyhrazené schéma v katalogu týmu pro ukládání a správu.

Azure Databricks doporučuje zahrnout do souboru docstring uživatelem následující informace:

  • Číslo aktuální verze
  • Protokol změn pro sledování změn napříč verzemi
  • Účel, parametry a návratová hodnota uživatelsky definované funkce
  • Příklad použití funkce definované uživatelem

Tady je příklad osvědčených postupů definovaných uživatelem:

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

Definované funkce pro přístup k externím rozhraním API

Funkce definované uživatelem můžete použít pro přístup k externím rozhraním API z SQL. Následující příklad používá knihovnu Pythonu requests k vytvoření požadavku HTTP.

Poznámka:

Definované funkce Pythonu umožňují síťový provoz TCP/UDP přes porty 80, 443 a 53 pomocí bezserverového výpočetního prostředí nebo výpočetních prostředků nakonfigurovaných v režimu sdíleného přístupu.

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

$$;

Funkce definované uživatelem pro zabezpečení a dodržování předpisů

Pomocí funkcí definovaných uživatelem v Pythonu můžete implementovat vlastní tokenizaci, maskování dat, redakci dat nebo mechanismy šifrování.

Následující příklad maskuje identitu e-mailové adresy při zachování délky a domény:

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

Následující příklad použije tuto funkci definovanou uživatelem v definici dynamického zobrazení:

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

Omezení

  • Můžete definovat libovolný počet funkcí Pythonu v rámci definované uživatelem Pythonu, ale všechny musí vrátit skalární hodnotu.
  • Funkce Pythonu musí zpracovávat hodnoty NULL nezávisle a všechna mapování typů musí následovat po mapování jazyka SQL v Azure Databricks.
  • Můžete importovat standardní knihovny Pythonu zahrnuté službou Azure Databricks, ale nemůžete zahrnout vlastní knihovny ani externí závislosti.
  • Pokud není zadán žádný katalog nebo schéma, uživatelsky definované funkce v Pythonu se zaregistrují do aktuálního aktivního schématu.
  • Funkce definované uživatelem Pythonu se spouštějí v zabezpečeném izolovaném prostředí a nemají přístup k systémům souborů ani interním službám.