SQL és Python felhasználó által definiált függvények (UDF-ek) a Unity Catalogban

A Unity Catalog felhasználó által definiált függvényei (UDF-ek) kibővítik az SQL- és Python-képességeket az Azure Databricksben. Lehetővé teszik az egyéni függvények meghatározását, használatát és 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 Python felhasználó által definiált skaláris függvényeket (UDF-eket).

A Scalában vagy Java a Unity Catalogban írt UDF-ek regisztrálásához lásd: Scala és Java felhasználó által definiált függvények (UDF-ek) a Unity Katalógusban.

Ha szeretné megnézni, hogy mely munkaterhelések és táblák hivatkoznak egy UDF-re a Unity Catalogban, mielőtt módosítaná azt, lásd a View UDF lineage című részt.

A teljes SQL-nyelvi referenciaért tekintse meg CREATE FUNCTION az (SQL, Python, Scala és Java) című témakört.

Követelmények

Ha az UDF-eket a Unity Katalógusban szeretné használni, az alábbi követelményeknek kell megfelelnie:

Ha Python-kódot szeretne használni a Unity Catalogban regisztrált UDF-ekben, 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 Unity Catalog Python UDF-t, az a klasszikus SQL-tárolókon meghiúsul.
A Scala UDF-ekhez készült ARM-példányok támogatása a Unity Catalog-kompatibilis klasztereken a Databricks Runtime 15.2 és ennél újabb verziókban érhető el.

A skaláris és Batch Unity Catalog Python UDF-ek általában elérhetők minden támogatott számítási típuson.

Python UDF funkciókövetelmények

A követelmények funkciónként változnak. A Databricks Runtime 19 és a környezet 6-os verziója nem általános követelmények a Unity Catalog Python UDF-ekhez.

PySpark session UDF-ek esetén szerver nélküli jegyzetfüzeken, vagy feladatokon, a környezeti követelmények a session környezetre vonatkoznak. SQL-definiált Python UDF-eknél minden függvény ENVIRONMENT záradékában hivatkoznak ráenvironment_version. A session környezet megváltoztatása nem változtatja meg egy meglévő Unity Catalog függvény környezetét. Például egy 6-os környezeti verziót használó munkamenet hívhat egy Unity Catalog függvényt, amely a környezet 5-ös verziójával definiált.

Funkció	Követelmények
`ENVIRONMENT` záradék és egyedi függőségek	Szerver nélküli jegyzetfüzetek és feladatok; pro vagy szerver nélküli SQL raktárak; Databricks Runtime 16.2 vagy annál magasabb klasszikus számítási rendszeren. Klasszikus számítási rendszeren, amely a Databricks Runtime 16.2-től 18.1-ig fut, `environment_version` a következőknek kell lennie `'None'`.
Batch Unity Katalógus Python függvények	szerver nélküli számítás; pro és szerver nélküli SQL raktárak; Databricks Runtime 16.3 vagy annál jobb klasszikus számításon
Skaláris Python UDF elnevezett kezelője	Databricks Runtime 18.1 vagy újabb klasszikus számítási környezeten. A szerver nélküli számítási környezetben, valamint a pro és szerver nélküli SQL-adattárházakban állítsa be az UDF `environment_version` elemét kifejezetten `6` vagy magasabb értékre.
Szolgáltatási hitelesítések egy skaláris Python UDF-ben	Databricks Runtime 18.1 vagy újabb klasszikus számítási környezeten. A szerver nélküli számítási környezetben, valamint a pro és szerver nélküli SQL-adattárházakban állítsa be az UDF `environment_version` elemét kifejezetten `6` vagy magasabb értékre. A Classic számítás nem igényel környezeti 6-os verziót. A szerver nélküli SQL-adattárak esetében engedélyezze az elkülönített számítási feladatok hálózatkezelésének nyilvános előzetes verzióját is.
Szolgáltatási hitelesítések egy Batch Unity Catalog Python UDF-ben	Szerver nélküli számítás; pro és szerver nélküli SQL raktárak; Databricks Runtime 16.3 vagy annál magasabb klasszikus számításon. A környezet 6-os verziója nem szükséges. A szerver nélküli SQL-adattárak esetében engedélyezze az elkülönített számítási feladatok hálózatkezelésének nyilvános előzetes verzióját is.
Titkok egy skaláris vagy batch Unity katalógusban Python UDF	A `environment_version` értékét állítsa kifejezetten `6` vagy magasabb értékre; szerver nélküli számítási környezet; pro és szerver nélküli SQL-adattárházak; Databricks Runtime 19-es vagy újabb verzió standard hozzáférési móddal klasszikus számítási környezetben. A közvetlen hívás nem támogatott dedikált hozzáférési módú számítási rendszeren.
PySpark-kompatibilis `TIMESTAMP` bemeneti viselkedés	Databricks Runtime 18.1 vagy újabb klasszikus számítási környezeten. A szerver nélküli számítási környezetben, valamint a pro és szerver nélküli SQL-adattárházakban állítsa be az UDF `environment_version` elemét kifejezetten `6` vagy magasabb értékre.
Ötnél több UDF-hívás egy lekérdezésben	Databricks Runtime 18.1 vagy újabb klasszikus számítási környezeten. A szerver nélküli számítási környezetben, valamint a pro és szerver nélküli SQL-adattárházakban állítsa minden UDF `environment_version` értékét kifejezetten `6` vagy magasabb értékre.

A Public Preview során elérhető meglévő UDF-ek és funkciók továbbra is működnek a releváns, korábbi futási idejű verziókon.

A környezeti verzió azt is meghatározza, hogy a hívóknak közvetlen hozzáférésre van szükségük a Unity Catalog kötetben tárolt függőségekhez. Lásd a következőt: A függőségekhez tartozó engedélyek a Unity Catalog-kötetekben.

Környezeti verziók klasszikus számítási környezetben

Klasszikus számításon egy olyan érték beállítása environment_version , amely nem 'None' szükséges, Databricks Runtime 18.2 vagy annál magasabb. A Databricks Runtime 16.2-től 18.1-ig állítsd environment_version = 'None' be, amikor használod a ENVIRONMENT klauzulát. Az érték 'None' az alapértelmezett Python környezetet használja.

A Databricks Runtime 18.2 vagy annál magasabb verziókon az előrelátható viselkedés érdekében az Azure Databricks kifejezetten beállít fix environment_version megoldást minden Unity Catalog Python UDF definíciójában. Válassz olyan verziót, amely megfelel az UDF funkciókövetelményeinek, és követi ezeket a kompatibilitási ajánlásokat:

A Databricks Runtime verziója	Maximális ajánlott környezeti verzió
18.2-től 18.x-ig	5
19.x	6

SQL- és Python UDF-ek létrehozása a Unity Catalogban

SQL- vagy Python UDF létrehozásához a Unity Catalogban a felhasználóknak HASZNÁLATI és LÉTREHOZÁSI engedéllyel kell rendelkezniük a sémára, valamint HASZNÁLATI engedéllyel a katalógusra. További részletekért lásd Unity Catalog.

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.

Ha egy Egységkatalógus-sémában szeretne UDF-t létrehozni és regisztrálni, a függvény nevének a formátumot catalog.schema.function_namekell követnie. Másik lehetőségként kiválaszthatja a megfelelő katalógust és sémát az SQL-szerkesztőben. Ebben az esetben a függvény neve előtt nem szerepelhet a(z) catalog.schema:

UDF létrehozása előre kiválasztott katalógussal és sémával.

Az alábbi példa egy új függvényt regisztrál a my_schema katalógus sémájához 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);

A Unity Cataloghoz készült Python UDF-ek kettős dollárjelekkel ($$) eltolva használnak utasításokat. Meg kell adnia egy adattípus-leképezést. Az alábbi példa egy olyan UDF-t regisztrál, amely kiszámítja a testtömegindexet:

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

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;

További UDF-példákért tekintse meg a Sorszűrő és az Oszlopmaszk példákat .

Használj egy nevelt kezelőt egy skaláris Python UDF-ben

Klasszikus számítási környezetben az elnevezett kezelőkhöz a Databricks Runtime 18.1-es vagy újabb verziója szükséges. A szerver nélküli számítási környezetben, valamint a pro és szerver nélküli SQL-adattárházakban állítsa be az UDF environment_version elemét kifejezetten 6 vagy magasabb értékre. A következő példa a 6. környezeti verziót használja. Klasszikus számítási rendszeren, amely a Databricks Runtime 18.1-et futtatja, hagyd ki a ENVIRONMENT záradékot. Későbbi futási idejű verzióknál kövesd a kompatibilitási ajánlásokat , ha beilleszted a záradékot.

Használd a HANDLER záradékot, hogy megnevezz egy Python függvényt az UDF testben belépési pontként. A nevelt kezelő elfogadja az UDF argumentumokat, és olyan értéket ad vissza, amely megegyezik a bejelentett visszaküldési típussal. A kezelőn kívüli kód akkor fut, amikor minden Python környezet inicializálja az UDF-et, mielőtt a kezelő feldolgozza a bemeneteket. Ezt a kódot használd egyszeri inicializációhoz, amely újrahasználható a kezelőhívások között.

A következő példa inicializálja greeting_prefix , mielőtt definiálná greet_handler, az UDF bemeneteket kezelő függvényt:

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

Titkok használata egy Python UDF-ben

A Skaláris és Batch Unity Catalog Python UDF-ek hozzáférhetnek a záradékban bejelentett SECRETS titkokhoz. Az UDF-definícióban a environment_version értékét kifejezetten 6 vagy magasabb értékre kell állítani. A Unity Catalog titkos három részből álló nevet (catalog.schema.secret) használ, és különbözik a munkaterületi szintű Azure Databricks titktól. A számítási támogatásról, jogosultságokról és a dedikált számítási oszlop-maszk kivételről lásd: UDF követelmények és jogosultságok.

Titkos adat elérése UDF-ből:

Hozzáadjuk a titok háromrészes nevét az UDF definíciójában szereplő SECRETS záradékhoz. Az UDF csak a ebben a záradékban bejelentett titkokat tud visszaszerezni.
Az UDF törzsében hívd meg a databricks.secrets.get() elemet a katalógus, a séma és a titok nevével.

A következő skaláris UDF példa egy Unity Catalog titkot használ hash-alapú üzenethitelesítési kódként (HMAC) aláíráskulcsként. Használd ugyanazt a SECRETS záradékot a PARAMETER STYLE PANDAS használatával az egy Batch UDF-kezelőben deklarált titkok eléréséhez.

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

Ne adjon vissza titkos értékeket egy UDF-ből. A bizalmas adatok kitakarása segít csökkenteni a hibákban és naplókban történő véletlen felfedést, de nem akadályozza meg, hogy az UDF-kód bizalmas adatokat tegyen közzé a lekérdezési eredményekben.

UDF-ek kiterjesztése egyéni függőségek használatával

Feljegyzés

Az internetről származó egyéni függőségek serverless SQL-adattárban történő telepítéséhez a munkaterületen engedélyezve kell lennie a Előzetes verziók lapon a Hálózatkezelés engedélyezése az elkülönített számítási feladatokhoz a Serverless SQL Warehouse-okban nyilvános előzetes funkciónak.

A Unity Catalog Python UDF-ek képességeit a Databricks Runtime-környezeten túl is kiterjesztheti a külső kódtárak egyéni függőségeinek definiálásával.

Követelmények

A Unity Catalog UDF-jeihez tartozó egyéni függőségek a következő számítási típusok esetében támogatottak:

Kiszolgáló nélküli jegyzetfüzetek és feladatok
Klasszikus, teljes körű számítás a Databricks Runtime 16.2-es és újabb verziójával
Pro vagy szerver nélküli SQL adattárház

Függőségi források

Telepítse a függőségeket a következő forrásokból:

PyPI-csomagok
A Unity Catalog-kötetekben tárolt fájlok Lásd: A Unity Catalog-kötetekben lévő függőségek engedélyei.
Nyilvános URL-címeken elérhető fájlok A munkaterület hálózati biztonsági szabályainak lehetővé kell tenni a nyilvános URL-címek elérését. Lásd: Követelmények.

Feljegyzés

Ha a munkaterület korlátozza a kiszolgáló nélküli hálózati hozzáférést, hálózati biztonsági szabályokat kell konfigurálnia a nyilvános URL-címek engedélyezéséhez. Lásd: Kimenő szabályok beállítása.

Jogosultságok függőségekhez Unity Catalog kötetekben

A függvény létrehozójának rendelkeznie kell READ VOLUME elemmel egy forrásköteten, hogy függőséget adhasson hozzá arról a kötetről egy UDF-hez.

Olyan UDF esetén, amelynek definíciója kifejezetten environment_version értékre vagy 6 vagy magasabb értékre van állítva, a hívóknak szükségük van EXECUTE jogosultságra az UDF-en, de nincs szükségük READ VOLUME jogosultságra a forrásköteten. Ha az UDF-definíció kihagyja a(z) environment_version elemet, None értékre állítja, vagy egy korábbi verzióra állítja, akkor a hívóknak a forrásköteten is rendelkezniük kell READ VOLUME-val.

Függőségek definiálása

A függőségek megadásához használja az UDF-definíció ENVIRONMENT szakaszát:

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

A ENVIRONMENT szakasz a következő mezőket tartalmazza:

Terület	Leírás	Típus	Példa használatra
`dependencies`	A telepíteni kívánt vesszővel tagolt függőségek listája. Minden bejegyzés egy karakterlánc, amely megfelel a pip követelmények fájlformátumának.	`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`	Megadja a környezeti verziót, amelyben az UDF futtatható. Ez a mező akkor kötelező, amikor a `ENVIRONMENT` záradék jelen van. A rögzített környezeti verzió az UDF-t egy adott Python verzióval és előre telepített csomagokkal futtatja, függetlenül a Python verziótól és a mögöttes Databricks Runtime-csomagoktól. A támogatott értékek: 3-as vagy újabb környezeti verzió, például `'6'`, vagy a `'None'` karakterlánc. Az érték `'None'` kiválasztja az alapértelmezett Python környezetet. Klasszikus számításon egy olyan érték beállítása `environment_version` , amely nem `'None'` szükséges, Databricks Runtime 18.2 vagy annál magasabb. A Databricks Runtime 16.2 és 18.1 közötti verzióiban csak a `'None'` támogatott. Ha fix környezetű verziókat támogatnak, kifejezetten válassz egyet a kiszámítható viselkedés miatt. Szerver nélküli számítás és pro és szerver nélküli SQL raktárakon egyes funkciók explicit környezeti verziót igényelnek. Minden UDF definícióban a szükséges verzióra vagy annál magasabbra állítsd `environment_version` be. Az egész `ENVIRONMENT` záradék vagy beállítás `environment_version = 'None'` elhagyása nem teszi lehetővé ezeket a funkciókat. Lásd a Python UDF funkciókövetelményeket. A klasszikus számítási verzió kompatibilitásért lásd: Környezeti verziók klasszikus számításon. Az elérhető verziók listájáért lásd: Környezeti verziók.	`STRING`	`environment_version = '6'`

Használj Unity Catalog UDF-eket 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.

Tegyük fel, hogy egy Azure Databricks jegyzetfüzetben a következő munkamenet-alapú UDF található:

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 CREATE FUNCTION utasítást, 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}!"
$$

Az UDF jogosultságait annak a katalógusnak, sémának vagy adatbázisnak a hozzáférés-szabályozási beállításai határozzák meg, amelyben az UDF-et regisztrálja. További információ : Jogosultságok kezelése a Unity Katalógusban .

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

Keresse meg azt a katalógust és sémát, amelyben az UDF van tárolva, és válassza ki az UDF-et.
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, hogy milyen típusú hozzáféréssel kell rendelkeznie, például AZ EXECUTE vagy a MANAGE.

engedélyek a Munkaterület felhasználói felületén

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 REVOKE parancsot, ahogyan az alábbi példában látható:

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

Környezet izolálása

Feljegyzés

A megosztott izolációs környezetekhez Databricks Runtime 18.1 vagy annál magasabb verziók szükségesek. A korábbi verziókban az összes Unity Catalog Python-UDF szigorú elkülönítési módban fut.

Az azonos tulajdonossal és munkamenettel rendelkező Unity Catalog Python UDF-ek alapértelmezés szerint megoszthatnak egy elkülönítési környezetet. Ez javítja a teljesítményt, és csökkenti a memóriahasználatot az indítandó különálló környezetek számának csökkentésével.

Szigorú elkülönítés

Ha ellenőrizni szeretné, hogy egy UDF mindig a saját, teljesen izolált környezetében fut-e, adja hozzá a STRICT ISOLATION jellemző záradékot.

A legtöbb UDF-nek nincs szüksége szigorú elkülönítésre. A standard adatfeldolgozási UDF-ek kihasználják az alapértelmezett megosztott elkülönítési környezetet, és gyorsabban futnak alacsonyabb memóriahasználat mellett.

Adja hozzá a STRICT ISOLATION jellemző záradékot az olyan UDF-ekhez, amelyek:

A beviteli adat futtatása kódként eval(), exec() vagy hasonló függvények használatával.
Fájlok írása a helyi fájlrendszerbe.
Globális változók vagy rendszerállapot módosítása.
Környezeti változók elérése vagy módosítása.

Az alábbi kód egy példát mutat be egy olyan UDF-re, amelyet a következővel STRICT ISOLATIONkell futtatni: Ez az UDF tetszőleges Python kódot futtat, így megváltoztathatja a rendszer állapotát, hozzáférhet a környezeti változókhoz, vagy írhat a helyi fájlrendszerbe. A záradék használata segít megelőzni az STRICT ISOLATION UDF-ek közötti interferencia- vagy adatszivárgást.

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

Állítsa be `DETERMINISTIC`, ha a függvény következetes eredményeket hoz létre.

Adja hozzá DETERMINISTIC a függvénydefinícióhoz, ha ugyanazokat a kimeneteket állítja elő ugyanazokhoz a bemenetekhez. Ez lehetővé teszi a lekérdezésoptimalizálást a teljesítmény javításához.

Alapértelmezés szerint Azure Databricks a Batch Unity Catalog Python UDF-eket nem determinisztikusként kezeli, kivéve, ha ön kifejezetten másként deklarál. A nem determinisztikus függvények például véletlenszerű értékek generálása, az aktuális időpontok vagy dátumok elérése vagy külső API-hívások kezdeményezése.

Lásd CREATE FUNCTION : (SQL, Python, Scala és Java)

UDF-ek ügynöki eszközökhöz

Az AI-ügynökök a Unity Catalog UDF-eket használhatják eszközökként a feladatok végrehajtásához és az egyéni logika futtatásához.

Lásd: Ügynökeszközök létrehozása Unity Catalog-függvényekkel.

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 engedélyezik a TCP/UDP hálózati forgalmat a 80-as, a 443-as és az 53-ai porton, amikor kiszolgáló nélküli számítást vagy standard hozzáférési móddal konfigurált számítást használnak.

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

$$;

UDF-ek a biztonság és megfelelés érdekében

Egyéni tokenizálás, adatmaszkolás, adatrejté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
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}"
$$

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

Ajánlott eljárások

Ahhoz, hogy az UDF-ek minden felhasználó számára elérhetők legyenek, 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 dedikált sémát a csapatkatalógusban a tároláshoz és a felügyelethez.

A Databricks azt javasolja, hogy az alábbi információkat tartalmazza az UDF docstringben:

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

Az alábbi példa egy ajánlott eljárásokat követő UDF-et mutat be:

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

Az időbélyegek időzóna-kezelése soronkénti bemenetek esetén

A TIMESTAMP bemenet UTC-ben megadott, időzóna nélküli datetime értékként jut el egy soronként működő Python UDF-hez. Klasszikus számítástechnikán ehhez a viselkedéshez Databricks Runtime 18.1 vagy annál magasabb verzió szükséges. A szerver nélküli számítási környezetben, valamint a pro és szerver nélküli SQL-adattárházakban állítsa be az UDF environment_version elemét kifejezetten 6 vagy magasabb értékre. Az datetime objektum nem tartalmazza az időzóna metaadatot az tzinfo attribútumában.

A Batch Unity Catalog Python UDF-ek az időbélyeg-bemeneteket pandas.Series objektumokban kapják meg, és nem ezt a datetime leképezést használják.

Ez a módosítás összhangba hozza a Unity Catalog Python UDF-jeit az Apache Arrow-ral optimalizált Python UDF-ekkel az Apache Sparkban.

Például a következő lekérdezés kifejezetten beállítja a környezet 6-os verzióját és az ülés időzónáját UTC-re:

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

A korábbi végrehajtási útvonal időzóna alapú értéket ad vissza a session időzónában. Ez a klasszikus számításra vonatkozik a Databricks Runtime 18.1 előtt. Ez szerver nélküli számításra és pro és szerver nélküli SQL raktárakra is érvényes, ha kihagyod a ENVIRONMENT záradékot, beállítod environment_version = 'None', vagy választasz egy 6 előtti verziót. Ha az ülés időzónája UTC-re van állítva, a korábbi út a következőket eredményezi:

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

A bemutatott definícióval a szerver nélküli számítás, valamint a pro és szerver nélküli SQL raktárak a PySpark-kompatibilis viselkedést használják. A klasszikus számítástechnika, amely a Databricks Runtime 18.1 vagy annál jobb rendszert futtat, ugyanazt a viselkedést használja, amikor módosítjuk vagy kihagyjuk a ENVIRONMENT záradékot:

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

Ez a változás hatással lehet az óramezőkre, valamint a tzinfo-ra. Egyelőre a korábbi viselkedés egy America/Los_Angeles munkamenetben 2024-10-23 03:30:00-07:00 eredményez 2024-10-23T10:30:00Z. Az új viselkedés az időzóna-naiv UTC értéket 2024-10-23 10:30:00eredményezi.

Ha az UDF-ed időzóna információra támaszkodik, állítsd vissza az UTC-t kifejezetten a következőként:

from datetime import timezone

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

Az UTC időzóna információ hozzáadása nem állítja vissza a korábbi session-helyi óramezőket. Ha a logikádnak szüksége van ezekre a mezőkre, akkor az aware értéket is konvertáld a tervezett időzónára. Példa:

from zoneinfo import ZoneInfo

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

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.
Ha nem ad meg katalógust vagy sémát, Azure Databricks regisztrálja Python UDF-eket az aktuális aktív sémába.
Python UDF-ek biztonságos, elkülönített környezetben futnak, és nem férnek hozzá a fájlrendszerekhez vagy a belső szolgáltatásokhoz.
Klasszikus számítási rendszeren, Databricks Runtime 18.1 vagy annál magasabb rendszeren futtatva több mint öt UDF-et is hívhatsz egy lekérdezésben. Szerver nélküli számítási környezetben, valamint pro és szerver nélküli SQL-adattárházakban minden UDF-definícióban kifejezetten environment_version értékét 6 értékre vagy magasabbra kell állítani.

Visszajelzés

Hasznosnak találta ezt az oldalt?

Last updated on 2026-10-01

SQL és Python felhasználó által definiált függvények (UDF-ek) a Unity Catalogban

Követelmények

Python UDF funkciókövetelmények

Környezeti verziók klasszikus számítási környezetben

SQL- és Python UDF-ek létrehozása a Unity Catalogban

Használj egy nevelt kezelőt egy skaláris Python UDF-ben

Titkok használata egy Python UDF-ben

UDF-ek kiterjesztése egyéni függőségek használatával

Követelmények

Függőségi források

Jogosultságok függőségekhez Unity Catalog kötetekben

Függőségek definiálása

Használj Unity Catalog UDF-eket a PySparkban

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

UDF-ek megosztása a Unity Katalógusban

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

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

Környezet izolálása

Szigorú elkülönítés

Állítsa be DETERMINISTIC, ha a függvény következetes eredményeket hoz létre.

UDF-ek ügynöki eszközökhöz

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

UDF-ek a biztonság és megfelelés érdekében

Ajánlott eljárások

Az időbélyegek időzóna-kezelése soronkénti bemenetek esetén

Korlátozások

Visszajelzés

További források

Állítsa be `DETERMINISTIC`, ha a függvény következetes eredményeket hoz létre.