Funkcje zdefiniowane przez użytkownika (UDF) w językach SQL i Python w Unity Catalog

Funkcje zdefiniowane przez użytkownika (FZU) w Unity Catalog rozszerzają możliwości SQL i Python w usłudze Azure Databricks. Umożliwiają one definiowanie, używanie i bezpieczne udostępnianie funkcji niestandardowych w środowiskach obliczeniowych oraz zarządzanie nimi.

Funkcje zdefiniowane przez użytkownika w języku Python, zarejestrowane jako funkcje w Unity Catalog, różnią się zakresem i obsługą od funkcji zdefiniowanych przez użytkownika PySpark, które są ograniczone do notesu lub SparkSession. Zobacz skalarne funkcje języka Python zdefiniowane przez użytkownika (UDF).

Aby zarejestrować funkcje definiowane przez użytkownika (UDF) napisane w językach Scala lub Java w Unity Catalog, zobacz artykuł Funkcje definiowane przez użytkownika (UDF) w językach Scala i Java w Unity Catalog.

Aby zobaczyć, które obciążenia i tabele odnoszą się do UDF w Unity Catalog przed jego modyfikacją, zobacz Zobacz linię UDF.

Zobacz CREATE FUNCTION (SQL, Python, Scala i Java), aby uzyskać pełną dokumentację języka SQL.

Wymagania

Aby korzystać z UDF w Unity Catalog, należy spełnić następujące wymagania:

• Aby użyć kodu Python w funkcjach zdefiniowanych przez użytkownika zarejestrowanych w Unity Catalog, należy użyć bezserwerowego lub pro SQL Warehouse albo klastra działającego na Databricks Runtime 13.3 LTS lub nowszym.
• Jeśli widok zawiera funkcję UDF Python katalogu Unity, zawodzi w klasycznych hurtowniach SQL.
• Obsługa wystąpień usługi ARM dla funkcji UDF języka Scala w klastrach z obsługą Unity Catalog jest dostępna w środowisku uruchomieniowym Databricks Runtime 15.2 lub nowszym.

Skalarne i Batch Unity Catalog Python UDF są zazwyczaj dostępne na wszystkich obsługiwanych typach obliczeniowych.

Wymagania dotyczące funkcji Python UDF

Wymagania różnią się w zależności od funkcji. Databricks Runtime 19 i środowisko w wersji 6 nie są wymaganiami ogólnymi dla funkcji Python UDF w Unity Catalog.

W przypadku sesji PySpark UDF na notebookach lub zleceniach bez serwera, wymagania środowiskowe odnoszą się do środowiska sesji. W przypadku funkcji UDF języka Python zdefiniowanych w SQL znacznik environment_version odwołuje się do nich w klauzuli ENVIRONMENT każdej funkcji. Zmiana środowiska sesji nie zmienia środowiska istniejącej funkcji Katalogu Unity. Na przykład sesja wykorzystująca środowisko w wersji 6 może wywołać funkcję Unity Catalog zdefiniowaną w środowisku wersji 5.

Funkcja	Wymagania
ENVIRONMENT Klauzule i zależności niestandardowe	Notebooki i zadania bezserwerowe; magazyny SQL pro lub bezserwerowe; Databricks Runtime 16.2 lub nowszy na klasycznych zasobach obliczeniowych. W klasycznym zasobie obliczeniowym z uruchomionym Databricks Runtime 16.2–18.1 environment_version musi mieć wartość 'None'.
Funkcje zdefiniowane przez użytkownika w usłudze Batch Unity w języku Python	Obliczenia bezserwerowe; magazyny SQL Pro i bezserwerowe; Databricks Runtime 16.3 lub nowszy w klasycznych zasobach obliczeniowych
Nazwany handler dla skalarnego UDF w Python	Databricks Runtime 18.1 lub nowszy na klasycznym komputerze. Na bezserwerowych zasobach obliczeniowych oraz w magazynach SQL typu pro i bezserwerowych jawnie ustaw dla funkcji UDF parametr environment_version na 6 lub wyższą wartość.
Poświadczenia serwisowe w skalarnym Python UDF	Databricks Runtime 18.1 lub nowszy na klasycznym komputerze. Na bezserwerowych zasobach obliczeniowych oraz w magazynach SQL typu pro i bezserwerowych jawnie ustaw dla funkcji UDF parametr environment_version na 6 lub wyższą wartość. Klasyczne obliczenia nie wymagają środowiska w wersji 6. W bezserwerowych magazynach SQL włącz także funkcję sieci obsługującej izolowane obciążenia w publicznej wersji zapoznawczej.
Poświadczenia serwisowe w katalogu Batch Unity Python UDF	Obliczenia serwerowe; magazyny SQL pro i serverless; Databricks Runtime 16.3 lub nowszy na klasycznym komputerze. Wersja środowiska 6 nie jest wymagana. W bezserwerowych magazynach SQL włącz także funkcję sieci obsługującej izolowane obciążenia w publicznej wersji zapoznawczej.
Sekrety w skalarnym lub Batch Unity Catalog Python UDF	Jawnie ustaw environment_version na 6 lub wyżej; obliczenia bezserwerowe; magazyny SQL Pro i bezserwerowe; Databricks Runtime 19 lub nowszy ze standardowym trybem dostępu na klasycznych zasobach obliczeniowych. Bezpośrednie wywołanie nie jest obsługiwane w zasobach obliczeniowych w trybie dedykowanego dostępu.
Zachowanie wejściowe zgodne z TIMESTAMP PySpark	Databricks Runtime 18.1 lub nowszy na klasycznym komputerze. Na bezserwerowych zasobach obliczeniowych oraz w magazynach SQL typu pro i bezserwerowych jawnie ustaw dla funkcji UDF parametr environment_version na 6 lub wyższą wartość.
Więcej niż pięć wywołań UDF w zapytaniu	Databricks Runtime 18.1 lub nowszy na klasycznym komputerze. W środowisku bezserwerowego przetwarzania oraz w hurtowniach SQL Pro i bezserwerowych jawnie ustaw dla każdej funkcji UDF wartość environment_version na 6 lub wyższą.

Istniejące UDF-y i funkcje dostępne podczas Public Preview nadal działają na odpowiednich wcześniejszych wersjach uruchomieniowych.

Wersja środowiskowa określa również, czy wywołujący potrzebują bezpośredniego dostępu do zależności przechowywanych w woluminie Unity Catalog. Zobacz Uprawnienia dotyczące zależności w woluminach Unity Catalog.

Wersje środowiskowe na klasycznym komputerze

W klasycznym trybie obliczeniowym ustawienie environment_version wartości innej 'None' niż wymaga Databricks Runtime 18.2 lub wyższej. W Databricks Runtime 16.2 do 18.1 ustawiaj environment_version = 'None' za każdym razem, gdy używasz klauzuli ENVIRONMENT . Wartość 'None' korzysta z domyślnego środowiska Python.

W Databricks Runtime 18.2 lub nowszym, dla przewidywalnego działania, Azure Databricks zaleca jawne ustawienie stałej environment_version w każdej definicji UDF języka Python w Unity Catalog. Wybierz wersję, która spełnia wymagania funkcjonalne UDF i stosuje się do następujących zaleceń kompatybilności:

Wersja środowiska uruchomieniowego usługi Databricks	Maksymalna zalecana wersja środowiska
18.2 do 18.x	5
19.x	6

Tworzenie funkcji UDF SQL i Python w Unity Catalog

Aby utworzyć funkcję UDF SQL lub Python w Unity Catalog, użytkownicy muszą mieć uprawnienia USAGE i CREATE do schematu oraz uprawnienie USAGE do katalogu. Aby uzyskać więcej informacji, zobacz Katalog Unity.

Aby uruchomić funkcję zdefiniowaną przez użytkownika (UDF), użytkownicy muszą mieć uprawnienie EXECUTE do uzyskania dostępu do tej funkcji. Użytkownicy potrzebują również uprawnień USAGE w schemacie i katalogu.

Aby utworzyć i zarejestrować funkcję UDF w schemacie Unity Catalog, nazwa funkcji musi mieć format catalog.schema.function_name. Alternatywnie możesz wybrać prawidłowy wykaz i schemat w edytorze SQL. W takim przypadku nazwa funkcji nie może mieć na początku elementu catalog.schema:

Poniższy przykład rejestruje nową funkcję do schematu my_schema w wykazie my_catalog :

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

Funkcje UDF języka Python w Unity Catalog używają instrukcji USE ograniczonych podwójnymi znakami dolara ($$). Musisz określić mapowanie typu danych. Poniższy przykład rejestruje funkcję zdefiniowaną przez użytkownika, która oblicza indeks masy ciała:

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

Teraz możesz skorzystać z funkcji Unity Catalog w zapytaniach SQL lub kodzie PySpark.

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

Zobacz Przykłady filtrów wierszy i przykłady maski kolumn, aby uzyskać więcej przykładów funkcji UDF.

Użyj handlera o nazwie w skalarnym UDF Python

W klasycznym trybie obliczeniowym nazwane handlery wymagają Databricks Runtime 18.1 lub wyższej. Na bezserwerowych zasobach obliczeniowych oraz w magazynach SQL typu pro i bezserwerowych jawnie ustaw dla funkcji UDF parametr environment_version na 6 lub wyższą wartość. Poniższy przykład wykorzystuje środowisko w wersji 6. W klasycznym trybie obliczeniowym uruchamiającym Databricks Runtime 18.1 pomiń tę ENVIRONMENT klauzulę. W późniejszych wersjach runtime postępuj zgodnie z zaleceniami dotyczącymi kompatybilności , jeśli uwzględniasz klauzulę.

Użyj klauzuli, HANDLER aby nazwać funkcję Python w ciele UDF jako punkt wejścia. Nazwany handler akceptuje argumenty UDF i zwraca wartość odpowiadającą zadeklarowanemu typowi zwrotu. Kod spoza handlera działa wtedy, gdy każde środowisko Python iinitializuje UDF, zanim handler przetworzy wejścia. Użyj tego kodu do jednorazowej inicjalizacji, którą można ponownie wykorzystać w różnych wywołaniach handlera.

Poniższy przykład inicjalizuje greeting_prefix przed zdefiniowaniem greet_handlerfunkcji obsługującej wejścia UDF:

CREATE OR REPLACE FUNCTION my_catalog.my_schema.greet(name STRING)
RETURNS STRING
LANGUAGE PYTHON
HANDLER 'greet_handler'
ENVIRONMENT (
  environment_version = '6'
)
AS $$
# Runs once when each Python environment initializes the UDF.
greeting_prefix = "Hello"

def greet_handler(name):
    return f"{greeting_prefix}, {name}!"
$$;

Używanie wpisów tajnych w funkcji UDF w języku Python

Skalarne i wsadowe funkcje UDF języka Python w Unity Catalog mogą uzyskiwać dostęp do sekretów zadeklarowanych w klauzuli SECRETS. Definicja UDF musi mieć jawnie ustawioną wartość environment_version na 6 lub wyższą. Sekret usługi Unity Catalog ma nazwę składającą się z trzech części (catalog.schema.secret) i różni się od sekretu Azure Databricks na poziomie obszaru roboczego. Informacje o obsłudze obliczeń, uprawnieniach i wyjątku dotyczącym maski kolumn dla dedykowanych obliczeń można znaleźć w sekcji Wymagania i uprawnienia UDF.

Aby uzyskać dostęp do sekretu z UDF:

1. Dodaj trzyczęściową nazwę sekretu do klauzuli SECRETS w definicji UDF. UDF może pobierać tylko tajemnice zadeklarowane w tej klauzuli.
2. W ciele UDF wywołaj databricks.secrets.get(), podając katalog, schemat i nazwę sekretu.

Poniższy przykład skalarnej funkcji UDF używa klucza tajnego w Unity Catalog jako klucza podpisywania HMAC. Użyj tej samej SECRETS klauzuli co PARAMETER STYLE PANDAS do dostępu do zadeklarowanych sekretów z obsługi UDF w partii.

CREATE OR REPLACE FUNCTION main.default.sign_value(value STRING)
RETURNS STRING
LANGUAGE PYTHON
SECRETS (main.default.hmac_key)
ENVIRONMENT (
  environment_version = '6'
)
AS $$
import hashlib
import hmac
from databricks.secrets import get

key = get(catalog="main", schema="default", key="hmac_key")
return hmac.new(key.encode(), value.encode(), hashlib.sha256).hexdigest()
$$;

Warning

Nie zwracaj wartości sekretów z UDF. Maskowanie informacji poufnych pomaga ograniczyć ryzyko ich przypadkowego ujawnienia w komunikatach o błędach i dziennikach, ale nie zapobiega ujawnianiu takich informacji przez kod UDF w wynikach zapytań.

Rozszerzanie funkcji UDF przy użyciu zależności niestandardowych

Uwaga

Aby zainstalować niestandardowe zależności z internetu w bezserwerowym magazynie danych SQL, obszar roboczy musi mieć włączoną funkcję publicznej wersji zapoznawczej Włącz obsługę sieci dla izolowanych obciążeń w bezserwerowych magazynach danych SQL na stronie Podglądy.

Możesz rozszerzyć możliwości funkcji UDF języka Python w Unity Catalog poza środowisko Databricks Runtime, definiując niestandardowe zależności dla bibliotek zewnętrznych.

Wymagania

Niestandardowe zależności dla funkcji zdefiniowanych przez użytkownika w katalogu Unity Catalog są obsługiwane na następujących typach obliczeń:

• Notesy i zadania bezserwerowe
• Klasyczne obliczenia ogólnego przeznaczenia przy użyciu środowiska Databricks Runtime w wersji 16.2 lub nowszej
• Pro lub bezserwerowa usługa SQL Warehouse

Źródła zależności

Zainstaluj zależności z następujących źródeł:

• Pakiety PyPI
• Pliki przechowywane w woluminach katalogu Unity Zobacz Uprawnienia dla zależności w woluminach katalogu Unity.
• Pliki dostępne na publicznych adresach URL Reguły zabezpieczeń sieci obszaru roboczego muszą zezwalać na dostęp do publicznych adresów URL. Zobacz Wymagania.

Uwaga

Jeśli obszar roboczy ogranicza dostęp do sieci bezserwerowej, należy skonfigurować reguły zabezpieczeń sieci, aby zezwolić na publiczne adresy URL. Zobacz Konfigurowanie reguł ruchu wychodzącego.

Uprawnienia do obiektów zależnych w woluminach Unity Catalog

Twórca funkcji musi mieć READ VOLUME na woluminie źródłowym, aby dodać zależność z tego woluminu do UDF.

W przypadku UDF, którego definicja jawnie ustawia environment_version na 6 lub wyżej, elementy wywołujące muszą mieć EXECUTE do UDF, ale nie potrzebują READ VOLUME dla wolumenu źródłowego. Jeśli definicja UDF pomija environment_version, ustawia ją na None lub ustawia ją na wcześniejszą wersję, programy wywołujące muszą również mieć READ VOLUME na woluminie źródłowym.

Definiowanie zależności

Użyj sekcji ENVIRONMENT definicji UDF, aby określić zależności.

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 = '6'
)
AS $$
import simplejson as json
import custom_package
return json.dumps(custom_package.process(data))
$$;

Sekcja ENVIRONMENT zawiera następujące pola:

(No changes needed)	Opis	Typ	Przykładowe użycie
dependencies	Lista zależności rozdzielonych przecinkami do zainstalowania. Każdy wpis jest ciągiem znaków zgodnym z formatem pliku wymagań pip.	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	Określa wersję środowiska, w której uruchamiać UDF. To pole jest wymagane za każdym razem, gdy klauzula ENVIRONMENT jest obecna. Wersja środowiska o stałej konfiguracji uruchamia UDF z określoną wersją języka Python i zestawem preinstalowanych pakietów, niezależnie od wersji języka Python i pakietów w bazowym środowisku Databricks Runtime. Wspierane wartości to środowiskowa wersja 3 lub wyższa, takie jak '6', lub ciąg 'None'. Wartość 'None' wybiera domyślne środowisko Python. W klasycznym trybie obliczeniowym ustawienie environment_version wartości innej 'None' niż wymaga Databricks Runtime 18.2 lub wyższej. Na Databricks Runtime 16.2 do 18.1 obsługiwane jest tylko 'None' to. Gdy obsługiwane są wersje środowiska stałego, należy wyraźnie wybrać taką dla przewidywalnego zachowania. W środowisku obliczeniowym bezserwerowym oraz w hurtowniach SQL Pro i bezserwerowych niektóre funkcje wymagają jawnie określonej wersji środowiska. Ustaw environment_version na wymaganą wersję lub wyższą w każdej definicji UDF. Pominięcie całej ENVIRONMENT klauzuli lub ustawienia environment_version = 'None' nie umożliwia tych funkcji. Zobacz wymagania dotyczące funkcji Python UDF. Aby uzyskać kompatybilność wersji klasycznego obliczeniowego, zobacz wersje środowiskowe na klasycznym komputerze. Listę dostępnych wersji można znaleźć w sekcji Wersje środowiskowe.	STRING	environment_version = '6'

Korzystanie z Unity Catalog UDFs w narzędziu PySpark

from pyspark.sql.functions import expr

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

Uaktualnianie funkcji zdefiniowanej przez użytkownika w zakresie sesji

Uwaga

Składnia i semantyka funkcji Python UDFs w Unity Catalog różnią się od Python UDFs zarejestrowanych w ramach SparkSession. Zobacz funkcje skalarne zdefiniowane przez użytkownika — Python.

Biorąc pod uwagę następującą funkcję zdefiniowaną przez użytkownika opartą na sesji w notesie usługi 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()

Aby zarejestrować to jako funkcję Katalogu Unity, użyj instrukcji SQL CREATE FUNCTION, jak pokazano w poniższym przykładzie:

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

Udostępnianie UDF w katalogu Unity

Mechanizmy kontroli dostępu stosowane do katalogu, schematu lub bazy danych, w którym rejestrujesz funkcję zdefiniowaną przez użytkownika (UDF), zarządzają jej uprawnieniami. Aby uzyskać więcej informacji, zobacz Zarządzanie uprawnieniami w katalogu Unity.

Użyj usługi Azure Databricks SQL lub interfejsu użytkownika obszaru roboczego usługi Azure Databricks, aby udzielić uprawnień użytkownikowi lub grupie (zalecane).

Uprawnienia w interfejsie użytkownika obszaru roboczego

1. Znajdź katalog i schemat, w którym są przechowywane funkcje zdefiniowane przez użytkownika, i wybierz funkcję zdefiniowanej przez użytkownika.
2. Poszukaj opcji Uprawnienia w ustawieniach UDF. Dodaj użytkowników lub grupy i określ, jaki rodzaj dostępu mają mieć, na przykład EXECUTE lub MANAGE.

Uprawnienia przy użyciu usługi Azure Databricks SQL

Poniższy przykład przyznaje użytkownikowi uprawnienie EXECUTE dla funkcji:

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

Aby usunąć uprawnienia, użyj polecenia REVOKE, jak w poniższym przykładzie:

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

Izolacja środowiskowa

Uwaga

Środowiska izolacji współdzielonej wymagają Databricks Runtime 18.1 lub nowszej. We wcześniejszych wersjach wszystkie funkcje Pythona zdefiniowane przez użytkownika w katalogu Unity działają w trybie ścisłej izolacji.

Funkcje Python UDFs w katalogu Unity z tym samym właścicielem i sesją mogą domyślnie współużytkować środowisko izolacyjne. Zwiększa to wydajność i zmniejsza użycie pamięci przez zmniejszenie liczby oddzielnych środowisk, które należy uruchomić.

Ścisła izolacja

Aby sprawdzić, czy funkcja UDF zawsze działa we własnym, w pełni izolowanym środowisku, dodaj klauzulę charakterystyczną STRICT ISOLATION .

Większość UDF nie wymaga ścisłej izolacji. Standardowe funkcje zdefiniowane przez użytkownika (UDF) przetwarzania danych czerpią korzyści z domyślnego środowiska współdzielonej izolacji i działają szybciej przy niższym zużyciu pamięci.

Dodaj klauzulę charakterystyczną do funkcji definiowanych przez użytkownika STRICT ISOLATION, które:

• Uruchom dane wejściowe jako kod przy użyciu funkcji eval(), exec() lub podobnych.
• Zapisywanie plików w lokalnym systemie plików.
• Modyfikowanie zmiennych globalnych lub stanu systemu.
• Uzyskaj dostęp do zmiennych środowiskowych lub zmodyfikuj je.

Poniższy kod przedstawia przykład funkcji UDF, którą należy uruchomić za pomocą STRICT ISOLATION. Ta funkcja UDF uruchamia dowolny kod Python, więc może zmienić stan systemu, uzyskać dostęp do zmiennych środowiskowych lub zapisać w lokalnym systemie plików. Użycie klauzuli STRICT ISOLATION pomaga zapobiegać ingerencji lub wyciekom danych między UDF-ami.

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

Ustaw DETERMINISTIC , czy funkcja generuje spójne wyniki

Dodaj DETERMINISTIC do definicji funkcji, jeśli generuje te same dane wyjściowe dla tych samych danych wejściowych. Dzięki temu optymalizacje zapytań mogą zwiększyć wydajność.

Domyślnie usługa Azure Databricks traktuje wsadowe funkcje UDF języka Python w Unity Catalog jako niedeterministyczne, o ile jawnie nie zadeklarujesz inaczej. Przykłady funkcji niedeterministycznych obejmują generowanie wartości losowych, uzyskiwanie dostępu do bieżących godzin lub dat lub wykonywanie zewnętrznych wywołań interfejsu API.

Zobacz CREATE FUNCTION (SQL, Python, Scala i Java)

UDF-y dla narzędzi agenta

Agenci AI mogą używać funkcji UDF usługi Unity Catalog jako narzędzi do wykonywania zadań i niestandardowej logiki.

Zobacz Tworzenie narzędzi agenta przy użyciu funkcji Unity Catalog.

Funkcje zdefiniowane przez użytkownika na potrzeby uzyskiwania dostępu do zewnętrznych interfejsów API

Za pomocą funkcji zdefiniowanych przez użytkownika można uzyskiwać dostęp do zewnętrznych interfejsów API z poziomu SQL. W poniższym przykładzie użyto biblioteki języka Python requests do utworzenia żądania HTTP.

Uwaga

UDF Python umożliwiają ruch sieciowy TCP/UDP przez porty 80, 443 i 53 podczas korzystania z architektury bezserwerowej lub obliczeń skonfigurowanych w standardowym trybie dostępu.

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

$$;

Funkcje użytkownika (UDFs) dla zabezpieczeń i zgodności

Użyj funkcji zdefiniowanych przez użytkownika (UDF) języka Python, aby zaimplementować niestandardową tokenizację, maskowanie danych, redagowanie danych lub mechanizmy szyfrowania.

Poniższy przykład maskuje tożsamość adresu e-mail przy zachowaniu długości i domeny:

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

Następujący przykład stosuje tę UDF w definicji widoku dynamicznego.

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

Najlepsze rozwiązania

Aby UDF były dostępne dla wszystkich użytkowników, Databricks zaleca utworzenie dedykowanego katalogu i schematu z odpowiednimi mechanizmami kontroli dostępu.

W przypadku funkcji zdefiniowanych przez zespół należy użyć dedykowanego schematu w katalogu zespołów na potrzeby magazynowania i zarządzania.

Usługa Databricks zaleca dołączenie następujących informacji do dokumentu usługi UDF:

• Bieżący numer wersji
• Dziennik zmian do śledzenia modyfikacji w różnych wersjach
• Cel, parametry i wartość zwracana funkcji definowanej przez użytkownika (UDF)
• Przykład użycia funkcji zdefiniowanej przez użytkownika

Poniższy przykład przedstawia funkcję UDF zgodną z najlepszymi praktykami:

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

Zachowanie strefy czasowej dla danych wejściowych przetwarzanych wiersz po wierszu

TIMESTAMP Dane wejściowe trafiają do funkcji UDF języka Python przetwarzającej po jednym wierszu naraz jako wartość datetime bez informacji o strefie czasowej w UTC. W klasycznym trybie obliczeniowym takie zachowanie wymaga Databricks Runtime 18.1 lub nowszego. Na bezserwerowych zasobach obliczeniowych oraz w magazynach SQL typu pro i bezserwerowych jawnie ustaw dla funkcji UDF parametr environment_version na 6 lub wyższą wartość. Obiekt datetime nie zawiera metadanych stref czasowych w swoim tzinfo atributie.

Wsadowe funkcje Python UDF w Unity Catalog otrzymują dane wejściowe typu znacznik czasu jako obiekty pandas.Series i nie używają tego mapowania datetime.

Ta zmiana dopasowuje funkcje zdefiniowane przez użytkownika (UDF) w języku Python katalogu Unity do zoptymalizowanych za pomocą Arrow funkcji UDF w Apache Spark.

Na przykład następujące zapytanie wyraźnie ustawia wersję środowiska 6 oraz strefę czasową sesji na UTC:

SET TIME ZONE 'UTC';

CREATE FUNCTION timezone_udf(date TIMESTAMP)
RETURNS STRING
LANGUAGE PYTHON
ENVIRONMENT (
  environment_version = '6'
)
AS $$
return f"{type(date)} {date} {date.tzinfo}"
$$;

SELECT timezone_udf(TIMESTAMP '2024-10-23 10:30:00');

Wcześniejsza ścieżka wykonania zwraca wartość uwzględniającą strefę czasową w strefie czasowej sesji. Dotyczy to klasycznych obliczeń przed Databricks Runtime 18.1. Dotyczy to również obliczeń bezserwerowych oraz hurtowni SQL typu pro i bezserwerowych, jeśli pominiesz klauzulę ENVIRONMENT, ustawisz environment_version = 'None' lub wybierzesz wersję wcześniejszą niż 6. Przy ustawieniu strefy czasowej sesji na UTC, wcześniejsza ścieżka generuje:

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

Zgodnie z przedstawioną definicją, obliczenia serverless oraz hurtownie SQL Pro i serverless wykorzystują zachowanie zgodne z PySpark. Klasyczne obliczenia uruchamiające Databricks Runtime 18.1 lub wyższym stosują takie samo zachowanie, gdy zmieniasz lub pomijasz klauzulę ENVIRONMENT :

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

Ta zmiana może wpływać zarówno na pola zegara, jak i tzinfo. Dla momentu 2024-10-23T10:30:00Z wcześniejsze zachowanie w sesji America/Los_Angeles powoduje 2024-10-23 03:30:00-07:00. Nowe zachowanie generuje wartość 2024-10-23 10:30:00UTC naiwną względem strefy czasowej .

Jeśli Twój UDF opiera się na informacjach o strefach czasowych, przywróć UTC wyraźnie:

from datetime import timezone

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

Dodanie informacji o strefie czasowej UTC nie przywraca poprzednich pól zegara sesji lokalnej. Jeśli twoja logika potrzebuje tych pól, przekonwertuj wartość świadomą na zamierzoną strefę czasową sesji. Przykład:

from zoneinfo import ZoneInfo

date = date.astimezone(ZoneInfo("America/Los_Angeles"))

Ograniczenia

• Można zdefiniować dowolną liczbę funkcji języka Python w Python UDF, ale wszystkie muszą zwracać wartość skalarną.
• Funkcje języka Python muszą obsługiwać wartości NULL niezależnie, a wszystkie mapowania typów muszą być zgodne z mapowaniami języka SQL usługi Azure Databricks.
• Jeśli nie określisz katalogu ani schematu, Azure Databricks zarejestruje funkcje UDF języka Python w aktualnie aktywnym schemacie.
• Funkcje UDF języka Python działają w bezpiecznym, izolowanym środowisku i nie mają dostępu do systemu plików ani usług wewnętrznych.
• Możesz wywołać więcej niż pięć UDF-ów w zapytaniu na klasycznym komputerze działającym na Databricks Runtime 18.1 lub wyższym. W obliczeniach bezserwerowych oraz w magazynach SQL typu pro i serverless każda definicja UDF musi jawnie ustawiać environment_version na 6 lub wyższą wartość.