Funkcje zdefiniowane przez użytkownika (UDF) w wykazie aparatu Unity

Ważne

Ta funkcja jest dostępna w publicznej wersji zapoznawczej.

Usługa Azure Databricks udostępnia składnię natywną SQL umożliwiającą rejestrowanie funkcji niestandardowych w schematach zarządzanych przez wykaz aparatu Unity. Funkcje zdefiniowane przez użytkownika języka Python zarejestrowane jako funkcje w wykazie aparatu Unity różnią się zakresem i obsługą funkcji zdefiniowanych przez użytkownika PySpark w zakresie notesu lub platformy SparkSession. Zobacz Funkcje skalarne zdefiniowane przez użytkownika — Python.

Aby uzyskać pełną dokumentację języka SQL, zobacz CREATE FUNCTION (SQL i Python).

Aby uzyskać informacje o sposobie zarządzania uprawnieniami w usłudze Unity Catalog w funkcjach, zobacz CREATE FUNCTION (CREATE FUNCTION).

Wymagania

• Środowisko Databricks Runtime 13.3 LTS lub nowsze.
• Aby użyć kodu języka Python w funkcjach zdefiniowanych przez użytkownika zarejestrowanych w katalogu aparatu Unity, należy użyć bezserwerowego lub pro SQL Warehouse albo klastra z uruchomionym środowiskiem Databricks Runtime 13.3 LTS lub nowszym.
• Aby rozwiązać problemy z widokami utworzonymi przy użyciu funkcji zdefiniowanej przez użytkownika zarejestrowanej w katalogu aparatu Unity, musisz użyć usługi SQL Warehouse bezserwerowej lub pro.

Niestandardowe funkcje SQL w wykazie aparatu Unity

Podczas tworzenia funkcji SQL przy użyciu obliczeń skonfigurowanych dla wykazu aparatu Unity funkcja jest domyślnie zarejestrowana w aktualnie aktywnym schemacie. W poniższym przykładzie pokazano składnię, której można użyć do deklarowania wykazu docelowego i schematu dla nowej funkcji:

CREATE FUNCTION target_catalog.target_schema.roll_dice()
    RETURNS INT
    LANGUAGE SQL
    NOT DETERMINISTIC
    CONTAINS SQL
    COMMENT 'Roll a single 6 sided die'
    RETURN (rand() * 6)::INT + 1;

Wszyscy użytkownicy z wystarczającymi uprawnieniami funkcji mogą następnie używać funkcji w środowiskach obliczeniowych skonfigurowanych dla wykazu aparatu Unity, jak w poniższym przykładzie:

SELECT target_catalog.target_schema.roll_dice()

Uwaga

Funkcji zdefiniowanych przez użytkownika można używać do LANGUAGE SQL zwracania tabel lub wartości skalarnych.

Rejestrowanie funkcji zdefiniowanej przez użytkownika języka Python w wykazie aparatu Unity

W środowisku Databricks Runtime 13.3 LTS lub nowszym można użyć instrukcji SQL CREATE FUNCTION do zarejestrowania skalarnych funkcji zdefiniowanych przez użytkownika języka Python w katalogu aparatu Unity.

Ważne

Tylko serwery pro i bezserwerowe magazyny SQL obsługują funkcje zdefiniowane przez użytkownika języka Python dla katalogu aparatu Unity.

Funkcje zdefiniowane przez użytkownika języka Python zostały zaprojektowane tak, aby zapewnić pełną ekspresyjność języka Python bezpośrednio w funkcjach SQL, umożliwiając wykonywanie niestandardowych operacji, takich jak zaawansowane przekształcenia, maskowanie danych i tworzenie skrótów.

Funkcje zdefiniowane przez użytkownika języka Python są wykonywane w bezpiecznym, izolowanym środowisku i nie mają dostępu do systemów plików ani usług wewnętrznych.

Funkcje zdefiniowane przez użytkownika języka Python działające na bezserwerowych obliczeniach lub w trybie dostępu współdzielonego zezwalają na ruch sieciowy TCP/UDP przez porty 80, 443 i 53.

Zobacz Jakie funkcje zdefiniowane przez użytkownika są najbardziej wydajne?.

Uwaga

Składnia i semantyka funkcji zdefiniowanych przez użytkownika języka Python w katalogu aparatu Unity różnią się od zdefiniowanych przez użytkownika języka Python zarejestrowanych na platformie SparkSession. Zobacz Funkcje skalarne zdefiniowane przez użytkownika — Python.

Funkcje UDF języka Python dla wykazu aparatu Unity używają instrukcji użycia ustawionych przez znaki podwójnego dolara ($$), jak w poniższym przykładzie kodu:

CREATE FUNCTION target_catalog.target_schema.greet(s STRING)
RETURNS STRING
LANGUAGE PYTHON
AS $$
  return f"Hello, {s}"
$$

W poniższym przykładzie pokazano użycie tej funkcji w celu zwrócenia instrukcji powitania dla wszystkich nazw przechowywanych w first_name kolumnie tabeli o nazwie students:

SELECT target_catalog.target_schema.greet(first_name)
FROM students;

Można zdefiniować dowolną liczbę funkcji języka Python w funkcji zdefiniowanej przez użytkownika języka Python, ale musi zwrócić wartość skalarną.

Funkcje języka Python muszą obsługiwać NULL wartości niezależnie, a wszystkie mapowania typów muszą być zgodne z mapowaniami języka SQL usługi Azure Databricks.

Możesz zaimportować standardowe biblioteki języka Python dołączone przez usługę Azure Databricks, ale nie można dołączać bibliotek niestandardowych ani zależności zewnętrznych.

Jeśli nie określono wykazu lub schematu, funkcje zdefiniowane przez użytkownika języka Python są zarejestrowane w bieżącym aktywnym schemacie.

Poniższy przykład importuje bibliotekę i używa wielu funkcji w ramach funkcji zdefiniowanej przez użytkownika języka Python:

CREATE FUNCTION roll_dice(num_dice INTEGER, num_sides INTEGER)
RETURNS INTEGER
LANGUAGE PYTHON
AS $$
  import numpy as np

  def roll_die(num_sides):
    return np.random.randint(num_sides) + 1

  def sum_dice(num_dice,num_sides):
    return sum([roll_die(num_sides) for x in range(num_dice)])

  return sum_dice(num_dice, num_sides)
$$