Unity Kataloğu'nda SQL ve Python kullanıcı tanımlı işlevler (UDF)

Unity Kataloğu'nda kullanıcı tanımlı işlevler (UDF' ler), Azure Databricks içindeki SQL ve Python özelliklerini genişletir. Bunlar, bilgi işlem ortamlarında özel işlevleri tanımlamanıza, kullanmanıza ve güvenli bir şekilde paylaşmanıza ve yönetmenize olanak tanır.

Unity Kataloğu'nda fonksiyon olarak kaydedilen Python UDF'lerinin kapsamı ve desteği, bir not defterine veya SparkSession'a kapsamlanan PySpark UDF'lerinden farklıdır. Bkz. Python skaler kullanıcı tanımlı işlevler (UDF).

Unity Kataloğu'nda Scala veya Java yazılmış UDF'leri kaydetmek için bkz. Unity Kataloğu'nda Scala ve kullanıcı tanımlı işlevleri (UDF) Java.

Unity Catalog'da UDF'yi değiştirmeden önce hangi iş yüklerinin ve tabloların referans verdiğini görmek için View UDF lineage'e bakabilirsiniz.

Tam SQL dil başvurusu için bkz CREATE FUNCTION . (SQL, Python, Scala ve Java).

Gereksinimler

Unity Kataloğu'nda UDF'leri kullanmak için aşağıdaki gereksinimleri karşılamanız gerekir:

  • Unity Kataloğu'nda kayıtlı UDF'lerde Python kodunu kullanmak için sunucusuz veya profesyonel bir SQL ambarı ya da Databricks Runtime 13.3 LTS veya üzerini çalıştıran bir küme kullanmanız gerekir.
  • Görünüm Unity Kataloğu Python UDF içerdiğinde, klasik SQL ambarlarında başarısız olur.
  • Unity Kataloğu etkin kümelerde Scala UDF'leri için ARM örnek desteği, Databricks Runtime 15.2 ve üzeri sürümlerde mevcuttur.

Skaler ve Batch Unity Kataloğu Python UDF'leri genellikle desteklenen tüm hesaplama türlerinde mevcuttur.

Python UDF özellik gereksinimleri

Gereksinimler özelliğe göre değişir. Databricks Runtime 19 ve ortam sürüm 6, Unity Catalog Python UDF'leri için genel gereksinim değildir.

Sunucusuz dizüstü bilgisayarlar veya işler üzerindeki PySpark oturum UDF'leri için, ortam gereksinimleri oturum ortamına atıfta bulunur. SQL ile tanımlanan Python UDF'leri için, her işlevin environment_version yan tümcesinde ENVIRONMENT öğesine başvurulur. Oturum ortamını değiştirmek, mevcut bir Unity Kataloğu fonksiyonunun ortamını değiştirmez. Örneğin, ortam sürüm 6 kullanan bir oturum, ortam sürümü 5 ile tanımlanmış bir Unity Kataloğu fonksiyonunu çağırabilir.

Feature Gereksinimler
ENVIRONMENT Madde ve Özel Bağımlılıklar Sunucusuz dizüstü bilgisayarlar ve işler; profesyonel veya sunucusuz SQL depoları; Databricks Runtime 16.2 veya daha üzeri, klasik hesaplamada. Databricks Runtime 16.2'den 18.1'e kadar çalışan klasik hesaplamada, environment_version'None' olmalıdır.
Batch Unity Kataloğu Python UDF'leri Sunucusuz hesaplama; profesyonel ve sunucusuz SQL depoları; Databricks Runtime 16.3 veya üzeri klasik hesaplamada
Skaler Python UDF için adlandırılmış işleyici Databricks Runtime 18.1 veya daha üstü klasik hesaplamada. Sunucusuz işlemde ve Pro ile sunucusuz SQL ambarlarında, UDF'nin environment_version değerini açıkça 6 veya üzeri olarak ayarlayın.
Skaler Python UDF'de hizmet kimlik bilgileri Databricks Runtime 18.1 veya daha üstü klasik hesaplamada. Sunucusuz işlemde ve Pro ile sunucusuz SQL ambarlarında, UDF'nin environment_version değerini açıkça 6 veya üzeri olarak ayarlayın. Klasik hesaplama için ortam sürüm 6 gerekmez. Sunucusuz SQL ambarlarında, izole iş yükü ağı oluşturma için Genel Önizleme özelliğini de etkinleştirin.
Bir Batch Unity Catalog Python UDF’sinde hizmet kimlik bilgileri Sunucusuz hesaplama; profesyonel ve sunucusuz SQL depoları; Databricks Runtime 16.3 veya üzeri, klasik hesaplamada. Ortamın 6. sürümü gerekli değildir. Sunucusuz SQL ambarlarında, izole iş yükü ağı oluşturma için Genel Önizleme özelliğini de etkinleştirin.
Skalar veya Batch Unity Catalog Python UDF içindeki gizli bilgiler 6 değerini açıkça environment_version ya da daha yüksek bir değere ayarlayın; sunucusuz işlem; Pro ve sunucusuz SQL ambarları; klasik işlemde standart erişim moduna sahip Databricks Runtime 19 veya üzeri. Doğrudan çağırma, özel erişim modunda hesaplamada desteklenmez.
PySpark uyumlu TIMESTAMP giriş davranışı Databricks Runtime 18.1 veya daha üstü klasik hesaplamada. Sunucusuz işlemde ve Pro ile sunucusuz SQL ambarlarında, UDF'nin environment_version değerini açıkça 6 veya üzeri olarak ayarlayın.
Bir sorguda beşten fazla UDF çağrısı yapıldı Databricks Runtime 18.1 veya daha üstü klasik hesaplamada. Sunucusuz hesaplamada ve pro ile sunucusuz SQL ambarlarında, her UDF'nin environment_version değerini açıkça 6 veya üzerine ayarlayın.

Mevcut UDF'ler ve Public Preview sırasında mevcut özellikler, geçerli önceki çalışma zamanı sürümlerinde çalışmaya devam etmektedir.

Ortam sürümü ayrıca, çağıranların Unity Catalog biriminde depolanan bağımlılıklara doğrudan erişime ihtiyaç duyup duymadığını da belirler. Unity Kataloğu ciltlerindeki bağımlılıklar için izinlere bakınız.

Klasik hesaplamada ortam sürümleri

Klasik hesaplamada, başka bir değere 'None' ayarlamak environment_version için Databricks Runtime 18.2 veya daha fazlası gerekir. Databricks Runtime 16.2'den 18.1'e kadar, maddeyi ENVIRONMENT kullandığınızda ayarlayınenvironment_version = 'None'. Değer 'None' varsayılan Python ortamını kullanır.

Databricks Runtime 18.2 veya üzerinde, öngörülebilir davranış için Azure Databricks, her Unity Catalog Python UDF tanımında bir sabit environment_version belirlemeyi açıkça önerir. UDF'nin özellik gereksinimlerini karşılayan ve şu uyumluluk önerilerini takip eden bir sürüm seçin:

Databricks Runtime sürümü Önerilen maksimum ortam sürümü
18.2 ile 18.x arası 5
19.x 6

Unity Kataloğu'nda SQL ve Python UDF'leri oluşturma

Unity Kataloğu'nda SQL veya Python UDF oluşturmak için kullanıcıların şemada USAGE ve CREATE izinlerine, katalogda ise USAGE iznine sahip olması gerekir. Diğer ayrıntılar için bkz. Unity Kataloğu .

UDF çalıştırmak için kullanıcıların UDF üzerinde YÜRÜTME iznine sahip olması gerekir. Kullanıcıların şema ve katalog üzerinde KULLANIM iznine de sahip olması gerekir.

Unity Kataloğu şemasında UDF oluşturmak ve kaydetmek için işlev adının biçiminde catalog.schema.function_nameolması gerekir. Alternatif olarak, SQL Düzenleyicisi'nde doğru kataloğu ve şemayı seçebilirsiniz. Bu durumda, işlev adınızın başına catalog.schema eklenmemelidir:

Katalog ve şemanın önceden seçili olduğu bir UDF oluşturma.

Aşağıdaki örnek, katalogdaki my_schema şemaya my_catalog yeni bir işlev kaydeder:

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

Unity Catalog için Python UDF'leri, çift dolar işaretleriyle sınırlandırılmış ifadeler kullanır ($$). Veri türü eşlemesi belirtmeniz gerekir. Aşağıdaki örnek, vücut kitle indeksini hesaplayan bir UDF'nin nasıl kaydedileceğini gösterir.

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

Artık bu Unity Kataloğu işlevini SQL sorgularınızda veya PySpark kodunuzda kullanabilirsiniz:

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

Daha fazla UDF örneği için bkz. Satır filtresi örnekleri ve Sütun maskesi örnekleri .

Skaler Python UDF'de isimli bir handler kullanın

Klasik hesaplamada, adlandırılmış işleyiciler Databricks Runtime 18.1 veya üzeri gerektirir. Sunucusuz işlemde ve Pro ile sunucusuz SQL ambarlarında, UDF'nin environment_version değerini açıkça 6 veya üzeri olarak ayarlayın. Aşağıdaki örnek, ortam sürüm 6'yı kullanır. Databricks Runtime 18.1 çalıştıran klasik hesaplamada bu ENVIRONMENT cümleyi çıkarın. Daha sonraki çalışma süresi sürümlerinde, bu maddeyi eklerseniz uyumluluk önerilerine uyun.

UDF gövdesinde giriş noktası olarak bir Python işlevi adlandırmak için HANDLER yan tümcesini kullanın. Adı verilen yönetici UDF argümanlarını kabul eder ve ilan edilen dönüş tipine uygun bir değer döndürür. İşleyici dışındaki kod, her bir Python ortamı UDF’yi başlattığında, işleyici girdileri işlemeden önce çalışır. Bu kodu, handler çağrıları arasında yeniden kullanılabilen tek seferlik başlatma için kullanın.

Aşağıdaki örnek, UDF girdilerini işleyen fonksiyonu tanımlamadan greet_handlerönce başlatırgreeting_prefix:

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

Bir Python UDF'de sırlar kullanın

Skaler ve Toplu Unity Catalog Python UDF'leri, SECRETS yan tümcesinde tanımlanan gizli bilgilere erişebilir. UDF tanımı, açıkça 6environment_version veya üzeri olarak ayarlanmalıdır. Bir Unity Catalog gizi, üç parçalı bir ad (catalog.schema.secret) kullanır ve çalışma alanı düzeyindeki Azure Databricks gizinden farklıdır. Hesaplama desteği, izinler ve özel hesaplama sütun-maskesi istisnası için bkz. UDF gereksinimleri ve izinleri.

Bir UDF'den gizli bilgiye erişmek için:

  1. UDF tanımındaki SECRETS ifadesine gizli anahtarın üç parçalı adını ekleyin. Bir UDF yalnızca bu maddede ilan edilen sırları geri alabilir.
  2. UDF gövdesinde, katalog, şema ve gizli dizi adını kullanarak databricks.secrets.get() çağrısı yapın.

Aşağıdaki skaler UDF örneği, Unity Kataloğu sırrını hash tabanlı mesaj doğrulama kodu (HMAC) imza anahtarı olarak kullanır. Bir Batch UDF işleyicisinden tanımlanmış gizli bilgilere erişmek için PARAMETER STYLE PANDAS ile aynı SECRETS ifadesini kullanın.

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

Bir UDF'den gizli değerler döndürmeyin. Gizli redaksiyon, hatalarda ve loglarda kazara ortaya çıkmayı azaltmaya yardımcı olur, ancak UDF kodunun sorgu sonuçlarında gizli materyali açığa çıkarmasını engellemez.

Özel bağımlılıkları kullanarak UDF'leri genişletme

Uyarı

Özel bağımlılıkları İnternet'ten sunucusuz bir SQL ambarında yüklemek için, çalışma alanınızın Önizlemeler sayfasındaSunucusuz SQL Ambarları'nda yalıtılmış iş yükleri için ağı etkinleştirme Genel Önizleme özelliğine sahip olması gerekir.

Dış kitaplıklar için özel bağımlılıklar tanımlayarak Unity Kataloğu Python UDF'lerinin özelliklerini Databricks Runtime ortamının ötesine genişletebilirsiniz.

Gereksinimler

Unity Kataloğu UDF'leri için özel bağımlılıklar aşağıdaki işlem türlerinde desteklenir:

  • Sunucusuz not defterleri ve işler
  • Databricks Runtime sürüm 16.2 ve üzerini kullanan klasik çok amaçlı işlem
  • Pro veya sunucusuz SQL ambarı

Bağımlılık kaynakları

Aşağıdaki kaynaklardan bağımlılıkları yükleyin:

Uyarı

Çalışma alanınız sunucusuz ağ erişimini kısıtlarsa, ağ güvenlik kurallarını genel URL'lere izin verecek şekilde yapılandırmanız gerekir. Bkz. Çıkış kurallarını ayarlama.

Unity Kataloğu ciltlerindeki bağımlılıklar için izinler

İşlev oluşturucusunun, bu birimden bir UDF'ye bağımlılık eklemek için kaynak birim üzerinde READ VOLUME olması gerekir.

Tanımı, environment_version değerini açıkça EXECUTE veya üzerine ayarlayan bir UDF için, çağıranların UDF üzerinde READ VOLUME iznine sahip olması gerekir; ancak kaynak birim üzerinde 6 iznine ihtiyaç yoktur. Eğer UDF tanımı environment_version öğesini atlıyor, bunu None olarak ayarlıyor veya daha eski bir sürüme ayarlıyorsa, çağıranların kaynak birimde de READ VOLUME bulunmalıdır.

Bağımlılıkları tanımlama

ENVIRONMENT Bağımlılıkları belirtmek için UDF tanımının bölümünü kullanın:

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

ENVIRONMENT bölümü aşağıdaki alanları içerir:

Alan Açıklama Türü Örnek kullanım
dependencies Yüklenecek virgülle ayrılmış bağımlılıkların listesi. Her girdi , pip Gereksinimleri Dosya Biçimi'ne uyan bir dizedir. 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 UDF'nin çalıştırılacağı ortam sürümünü belirtir. Bu alan, ENVIRONMENT maddesi mevcut olduğunda gereklidir. Sabit bir ortam sürümü, Python sürümünden ve temel alınan Databricks Runtime'daki paketlerden bağımsız olarak UDF'yi belirli bir Python sürümü ve önceden yüklenmiş paketler kümesiyle çalıştırır.
Desteklenen değerler, '6' gibi 3 veya üzeri bir ortam sürümü ya da 'None' dizesidir. Değer'None', varsayılan Python ortamını seçer. Klasik hesaplamada, başka bir değere 'None' ayarlamak environment_version için Databricks Runtime 18.2 veya daha fazlası gerekir. Databricks Runtime 16.2'den 18.1'e kadar 'None' sadece destekleniyor. Sabit ortam sürümleri desteklendiğinde, tahmin edilebilir davranış için açıkça bir tane seçin.
Sunucusuz hesaplamada ve pro ile sunucusuz SQL depolarında bazı özellikler açık bir ortam sürümü gerektirir. environment_version öğesini her UDF tanımında gerekli sürüme veya üzerindeki bir sürüme ayarlayın. ENVIRONMENT maddesinin tamamını çıkarmak veya environment_version = 'None' ayarını yapmak bu özellikleri etkinleştirmez. Python UDF özellik gereksinimlerine bakınız.
Klasik hesaplama versiyonu uyumluluğu için , klasik hesaplamada Ortam sürümleri sayfasına bakınız. Mevcut sürümlerin listesi için Çevre sürümleri bölümüne bakınız.		 STRING environment_version = '6'

PySpark'ta Unity Kataloğu UDF'lerini kullanma

from pyspark.sql.functions import expr

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

Oturum kapsamlı bir UDF'yi yükseltme

Uyarı

Unity Kataloğu'nda Python UDF'leri için söz dizimi ve semantik, SparkSession'a kayıtlı Python UDF'lerinden farklıdır. Bkz . kullanıcı tanımlı skaler işlevler - Python.

Aşağıdaki oturum tabanlı UDF, bir Azure Databricks defterinde:

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

Bunu Unity Kataloğu işlevi olarak kaydetmek için aşağıdaki örnekte olduğu gibi bir SQL CREATE FUNCTION deyimi kullanın:

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

Unity Kataloğu'nda UDF'leri paylaşma

UDF’yi kaydettiğiniz katalog, şema veya veritabanına uygulanan erişim denetimleri, UDF’nin izinlerini yönetir. Daha fazla bilgi için bkz. Unity Kataloğu'nda ayrıcalıkları yönetme .

Bir kullanıcıya veya gruba izin vermek için Azure Databricks SQL veya Azure Databricks çalışma alanı kullanıcı arabirimini kullanın (önerilir).

Çalışma alanı kullanıcı arabirimindeki izinler

  1. UDF'nizin depolandığı kataloğu ve şemayı bulun ve UDF'yi seçin.
  2. UDF ayarlarında İzinler seçeneğini arayın. Kullanıcıları veya grupları ekleyin ve EXECUTE veya MANAGE gibi sahip olmaları gereken erişim türünü belirtin.

Çalışma Alanı Kullanıcı Arabirimi İzinleri

Azure Databricks SQL'i kullanma izinleri

Aşağıdaki örnek kullanıcıya bir işlev üzerinde EXECUTE izni verir:

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

İzinleri kaldırmak için aşağıdaki örnekte olduğu gibi REVOKE komutunu kullanın:

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

Ortam yalıtımı

Uyarı

Paylaşılan izolasyon ortamları için Databricks Runtime 18.1 ve üzeri gereklidir. Önceki sürümlerde, tüm Unity Kataloğu Python UDF'leri katı yalıtım modunda çalışır.

Aynı sahipli ve oturumlu Unity Catalog Python UDF'leri varsayılan olarak bir yalıtım ortamını paylaşabilir. Bu, başlatılması gereken ayrı ortamların sayısını azaltarak performansı artırır ve bellek kullanımını azaltır.

Katı yalıtım

UDF'nin her zaman kendi, tamamen yalıtılmış ortamında çalıştığını doğrulamak için karakteristik yan tümcesini STRICT ISOLATION ekleyin.

Çoğu UDF'nin katı yalıtıma ihtiyacı yoktur. Standart veri işleme UDF'leri varsayılan paylaşılan yalıtım ortamından yararlanır ve daha düşük bellek tüketimiyle daha hızlı çalışır.

Şu özelliklere sahip STRICT ISOLATION UDF'lere karakteristik yan tümcesini ekleyin:

  • Girişi eval(), exec() veya benzer işlevleri kullanarak kod olarak çalıştırın.
  • Dosyaları yerel dosya sistemine yazın.
  • Genel değişkenleri veya sistem durumunu değiştirin.
  • Ortam değişkenlerine erişme veya değişkenleri değiştirme.

Aşağıdaki kod, STRICT ISOLATION kullanılarak çalıştırılması gereken bir UDF örneğini gösterir. Bu UDF rastgele Python kodu çalıştırdığından sistem durumunu değiştirebilir, ortam değişkenlerine erişebilir veya yerel dosya sistemine yazabilir. STRICT ISOLATION maddesinin kullanılması, UDF'ler arasında girişim veya veri sızıntılarını önlemeyi destekler.

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

İşlevinizin tutarlı sonuçlar üretip üretmediğini ayarlama DETERMINISTIC

Aynı girişler için aynı çıkışları oluşturuyorsa işlev tanımınıza ekleyin DETERMINISTIC . Bu, sorgu iyileştirmelerinin performansı geliştirmesine olanak tanır.

Varsayılan olarak, Azure Databricks açıkça aksini bildirmediğiniz sürece Batch Unity Kataloğu Python UDF'leri belirlenemez olarak ele alır. Belirlenemeyen işlevlere örnek olarak rastgele değerler oluşturma, geçerli saatlere veya tarihlere erişme veya dış API çağrıları yapma verilebilir.

Bkz.CREATE FUNCTION (SQL, Python, Scala ve Java)

Ajan araçları için UDF'ler

Yapay zeka aracıları, görevleri gerçekleştirmek ve özel mantık çalıştırmak için Unity Kataloğu UDF'lerini araç olarak kullanabilir.

Bkz. Unity Kataloğu işlevlerini kullanarak aracı araçları oluşturma.

Dış API'lere erişmek için UDF'ler

DıŞ API'lere SQL'den erişmek için UDF'leri kullanabilirsiniz. Aşağıdaki örnek, HTTP isteğinde bulunmak için Python requests kitaplığını kullanır.

Uyarı

Python UDF'leri, sunucusuz işlem veya standart erişim moduyla yapılandırılmış işlem kullanıldığında, 80, 443 ve 53 numaralı portlar üzerinden TCP/UDP ağ trafiğine izin verir.

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

$$;

Güvenlik ve uyumluluk için UDF'ler

Özel belirteç oluşturma, veri maskeleme, veri yeniden düzenleme veya şifreleme mekanizmaları uygulamak için Python UDF'lerini kullanın.

Aşağıdaki örnek, uzunluğu ve etki alanını korurken e-posta adresinin kimliğini maskeler:

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

Aşağıdaki örnek, bu UDF'yi dinamik görünüm tanımına uygular:

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

En iyi yöntemler

UDF'lerin tüm kullanıcılar tarafından erişilebilir olması için Databricks, uygun erişim denetimleriyle ayrılmış bir katalog ve şema oluşturmanızı önerir.

Takıma özgü UDF'ler için, depolama ve yönetim için ekip kataloğu içinde ayrılmış bir şema kullanın.

Databricks, UDF docstring'e aşağıdaki bilgileri eklemenizi önerir:

  • Geçerli sürüm numarası
  • Sürümler arasında değişiklikleri izlemek için bir değişiklik günlüğü
  • UDF amacı, parametreleri ve dönüş değeri
  • UDF'yi kullanma örneği

Aşağıdaki örnekte en iyi yöntemleri izleyen bir UDF gösterilmektedir:

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

Satır bazlı girdiler için zaman damgalarının zaman dilimi davranışı

Bir TIMESTAMP girdi, satır bazında çalışan Python UDF'ye UTC'de zaman dilimi bilgisi olmayan bir datetime değeri olarak ulaşır. Klasik hesaplamada, bu davranış Databricks Runtime 18.1 veya üzeri gerektirir. Sunucusuz işlemde ve Pro ile sunucusuz SQL ambarlarında, UDF'nin environment_version değerini açıkça 6 veya üzeri olarak ayarlayın. Nesne, datetime özniteliğinde tzinfo zaman dilimi meta verisi içermez.

Batch Unity Kataloğu Python UDF'leri, zaman damgası girdilerini pandas.Series nesneleri içinde alır ve bu datetime eşlemesini kullanmaz.

Bu değişiklik, Unity Catalog Python UDF'lerini Apache Spark'ta Arrow ile optimize edilmiş Python UDF'leriyle hizalar.

Örneğin, aşağıdaki sorgu ortam sürüm 6 ve oturum zaman dilimi açıkça UTC olarak belirlenir:

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

Önceki çalıştırma yolu, oturum zaman diliminde zaman dilimi bilgisi içeren bir değer döndürür. Bu, Databricks Runtime 18.1'den önceki klasik hesaplamada geçerlidir. Ayrıca, ENVIRONMENT yan tümcesini atlarsanız, environment_version = 'None' ayarlarsanız veya 6'dan önceki bir sürüm seçerseniz, sunucusuz işlem ile Pro ve sunucusuz SQL ambarları için de geçerlidir. Oturum zaman dilimi UTC'ye ayarlandığında, önceki yol şunları üretir:

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

Gösterilen tanıma göre, sunucusuz işlem ile pro ve sunucusuz SQL ambarları PySpark uyumlu davranışını kullanır. Databricks Runtime 18.1 veya üzerini çalıştıran klasik hesaplama, maddeyi ENVIRONMENT ayarladığınızda veya çıkardığınızda aynı davranışı kullanır:

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

Bu değişiklik, saat alanlarının yanı sıra tzinfo öğesini de etkileyebilir. 2024-10-23T10:30:00Z anı için, bir America/Los_Angeles oturumundaki önceki davranış 2024-10-23 03:30:00-07:00 üretir. Yeni davranış, zaman dilimi bilgisi içermeyen UTC değerini 2024-10-23 10:30:00 üretir.

Eğer UDF'niz saat dilimi bilgisine güveniyorsa, UTC'yi açıkça geri getirin:

from datetime import timezone

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

UTC saat dilimi bilgisi eklemek, önceki oturum-yerel saat alanlarını geri yüklemez. Eğer mantığınız bu alanlara ihtiyaç duyuyorsa, farkında değeri de hedef alınan oturum zaman dilimine dönüştürün. Örneğin:

from zoneinfo import ZoneInfo

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

Sınırlamalar

  • Python UDF içinde istediğiniz sayıda Python işlevi tanımlayabilirsiniz, ancak tümünün skaler değer döndürmesi gerekir.
  • Python işlevlerinin NULL değerleri bağımsız olarak işlemesi ve tüm tür eşlemelerinin Azure Databricks SQL dil eşlemelerini izlemesi gerekir.
  • Bir katalog veya şema belirtmezseniz, Azure Databricks Python UDF'leri geçerli etkin şemaya kaydeder.
  • Python UDF'ler güvenli, yalıtılmış bir ortamda çalışır ve dosya sistemlerine veya iç hizmetlere erişimi yoktur.
  • Databricks Runtime 18.1 veya üzeri olan klasik hesaplamada bir sorguda beşten fazla UDF çağırabilirsiniz. Sunucusuz işlemde ve Pro ile sunucusuz SQL ambarlarında, her UDF tanımı 6 değerini açıkça environment_version ya da üzeri olarak ayarlamalıdır.
  • Son güncelleştirme: