Aracılığıyla paylaş

CREATE FUNCTION (SQL ve Python)

  • Makale

Şunlar için geçerlidir: onay işareti evet olarak işaretlenmiş Databricks SQL onay işareti evet olarak işaretlenmiş Databricks Runtime

Bir dizi bağımsız değişken alan ve skaler değer veya satır kümesi döndüren bir SQL skaler veya tablo işlevi oluşturur.

Şunlar için geçerlidir: onay işareti evet olarak işaretlenmiş Databricks SQL onay işareti evet olarak işaretlenmiş Databricks Runtime 13.3 LTS ve üzeri

Bir dizi bağımsız değişken alan ve bir skaler değer döndüren bir Python skaler işlevi oluşturur.

Python UDF'leri sunucusuz veya profesyonel SQL ambarlarında Unity Kataloğu'nu ya da paylaşılan veya tek bir kullanıcı Unity Kataloğu kümesini gerektirir.

Şunlar için geçerlidir: onay işareti evet olarak işaretlenmiş Databricks SQL onay işareti evet olarak işaretlenmiş Databricks Runtime 14.1 ve üzeri

Konumsal parametre çağırmaya ek olarak, adlandırılmış parametre çağırmayı kullanarak SQL ve Python UDF'yi de çağırabilirsiniz.

Sözdizimi

CREATE [OR REPLACE] [TEMPORARY] FUNCTION [IF NOT EXISTS]
    function_name ( [ function_parameter [, ...] ] )
    { [ RETURNS data_type ] |
      RETURNS TABLE [ ( column_spec [, ...]) ] }
    [ characteristic [...] ]
    { AS dollar_quoted_string | RETURN { expression | query } }

function_parameter
    parameter_name data_type [DEFAULT default_expression] [COMMENT parameter_comment]

column_spec
    column_name data_type [COMMENT column_comment]

characteristic
  { LANGUAGE { SQL | PYTHON } |
    [NOT] DETERMINISTIC |
    COMMENT function_comment |
    [CONTAINS SQL | READS SQL DATA] }

Parametreler

  • VEYA DEĞİşTİr

    Belirtilirse, aynı ad ve imzaya (parametre sayısı ve parametre türü) sahip işlev değiştirilir. Mevcut bir işlevi farklı bir imzayla değiştiremezsiniz. Bu temel olarak işlev gövdesini ve işlevin dönüş türünü güncelleştirmek için yararlıdır. Bu parametreyi ile IF NOT EXISTSbelirtemezsiniz.

  • GEÇİCİ

    Oluşturulan işlevin kapsamı. belirttiğinizde TEMPORARY, oluşturulan işlev geçerli olur ve geçerli oturumda görünür. Katalogda kalıcı girdi yapılmaz.

  • YOKSA

    Belirtilirse, işlevi yalnızca mevcut olmadığında oluşturur. Belirtilen işlev sistemde zaten varsa, işlevin oluşturulması başarılı olur (hata oluşturulmaz). Bu parametreyi ile OR REPLACEbelirtemezsiniz.

  • function_name

    İşlev için bir ad. Kalıcı bir işlev için, isteğe bağlı olarak işlev adını bir şema adıyla niteleyebilirsiniz. Ad nitelenmiş değilse, geçerli şemada kalıcı işlev oluşturulur.

  • function_parameter

    İşlevin bir parametresini belirtir.

    • parameter_name

      Parametre adı işlevi içinde benzersiz olmalıdır.

    • data_type

      Desteklenen herhangi bir veri türü. Python için, data_type bu dil eşlemesine göre bir Python veri türüne yayınlanır.

    • DEFAULT default_expression

      Şunlar için geçerlidir: onay işareti evet olarak işaretlenmiş Databricks SQL onay işareti evet olarak işaretlenmiş Databricks Runtime 10.4 LTS ve üzeri

      bir işlev çağrısı parametreye bağımsız değişken atamadığında kullanılacak isteğe bağlı varsayılan değerdir. default_expressionolarak atanabilir data_typeolmalıdır. İfade başka bir parametreye başvurmamalı veya bir alt sorgu içermemelidir.

      Bir parametre için varsayılan değer belirttiğinizde, aşağıdaki tüm parametrelerin de varsayılanı olmalıdır.

      DEFAULT yalnızca için LANGUAGE SQL desteklenir.

    • YORUM açıklaması

      Parametresinin isteğe bağlı açıklaması. comment değişmez değer STRING olmalıdır.

  • RETURNS data_type

    Skaler işlevin dönüş veri türü. Python UDF'leri için, dönüş değerleri içinde data_typebelirtilen veri türüyle tam olarak eşleşmelidir. Aksi takdirde, beklenmeyen tür dönüştürmelerini önlemek için işlev başarısız olur.

    SQL UDF için bu yan tümce isteğe bağlıdır. Veri türü sağlanmadıysa işlev gövdesinden türetilir.

  • RETURNS TABLE [ (column_spec [,...] ) ]

    Bu yan tümce işlevi tablo işlevi olarak işaretler. İsteğe bağlı olarak tablo işlevinin sonucunun imzasını da belirtir. column_spec belirtilmezse, SQL UDF'nin gövdesinden türetilir.

    RETURNS TABLE yalnızca için LANGUAGE SQL desteklenir.

    • column_name

      Sütun adı imza içinde benzersiz olmalıdır.

    • data_type

      Desteklenen herhangi bir veri türü.

    • COMMENT column_comment

      Sütunun isteğe bağlı açıklaması. comment değişmez değer STRING olmalıdır.

  • RETURN { ifade | sorgusu }

    İşlevin gövdesi. Skaler bir işlev için sorgu veya ifade olabilir. Tablo işlevi için yalnızca bir sorgu olabilir. İfade aşağıdakileri içeremez:

    İşlevin gövdesinde parametreye nitelenmemiş adıyla veya parametreyi işlev adıyla niteleyerek başvurabilirsiniz.

  • AS dollar_quoted_definition

    dollar_quoted_definition, iki eşleşen $[tag]$body$[tag]$ile çevrelenmiş Python işlevidirbody. tag boş bir dize olabilir.

    Örnekler:

    $$
  return “Hello world”
$$

$py$
  return "Hello World"
$py$

  • özellik

    Tüm karakteristik yan tümceler isteğe bağlıdır. Herhangi bir sırada istediğiniz sayıda belirtebilirsiniz, ancak her yan tümceyi yalnızca bir kez belirtebilirsiniz.

    • LANGUAGE SQL veya LANGUAGE PYTHON

      İşlev uygulamasının dili.

    • [DEĞİl] DETERMİNİSTİC

      İşlevin belirleyici olup olmadığı. İşlev, belirli bir bağımsız değişken kümesi için yalnızca bir sonuç döndürdüğünde belirleyicidir. Bir işlevi gövdesi değilken veya tam tersi olduğunda olarak DETERMINISTIC işaretleyebilirsiniz. Bunun bir nedeni, sürekli katlama veya sorgu önbelleğe alma gibi sorgu iyileştirmelerini teşvik etmek veya önerilmez. ths seçeneğini belirtmezseniz, işlev gövdesinden türetilir.

    • COMMENT function_comment

      İşlev için bir açıklama. function_comment Dize değişmez değeri olmalıdır.

    • SQL veya READS SQL VERİSİ İçERİR

      İşlevin verileri tablo veya görünümden doğrudan veya dolaylı olarak okuması. İşlev SQL verilerini okuduğunda belirtemezsiniz CONTAINS SQL. İki yan tümceyi belirtmezseniz, özelliği işlev gövdesinden türetilir.

Python UDF'lerinde Desteklenen Kitaplıklar

Bağımlılıkları kullanmak için işlev gövdesi içinde kullanın import <package> . Örneğin, aşağıdakilere bakın:

CREATE FUNCTION […]
AS $$
   import json
   [... (rest of function definition)]
$$

Bağımlılıklar standart Python kitaplığı ve aşağıdaki kitaplıklarla sınırlıdır:

Paket Sürüm
çamaşır suyu 4.0.0
chardet 4.0.0
charset-normalizer 2.0.4
defusedxml 0.7.1
googleapis-common-protos 1.56.4
grpcio 1.47.0
grpcio-status 1.47.0
jmespath 0.10.0
joblib 1.1.0
numpy 1.20.3
Ambalaj 21.3
pandas 1.3.4
Patsy 0.5.2
protobuf 4.21.5
serçe 7.0.0
pyparsing 3.0.9
python-dateutil 2.8.2
pytz 2021.3
scikit-learn 0.24.2”
scipy 1.7.1”
kurulum araçları 65.2.0
Altı 1.16.0
threadpoolctl 3.1.0
webencodings 0.5.1
kullanıcı aracıları 2.2.0
şifreleme 38.0.4

Örnekler

SQL skaler işlevi oluşturma ve kullanma

> CREATE VIEW t(c1, c2) AS VALUES (0, 1), (1, 2);

-- Create a temporary function with no parameter.
> CREATE TEMPORARY FUNCTION hello() RETURNS STRING RETURN 'Hello World!';

> SELECT hello();
  Hello World!

-- Create a permanent function with parameters.
> CREATE FUNCTION area(x DOUBLE, y DOUBLE) RETURNS DOUBLE RETURN x * y;

-- Use a SQL function in the SELECT clause of a query.
> SELECT area(c1, c2) AS area FROM t;
 0.0
 2.0

-- Use a SQL function in the WHERE clause of a query.
> SELECT * FROM t WHERE area(c1, c2) > 0;
 1  2

-- Compose SQL functions.
> CREATE FUNCTION square(x DOUBLE) RETURNS DOUBLE RETURN area(x, x);

> SELECT c1, square(c1) AS square FROM t;
  0  0.0
  1  1.0

-- Create a non-deterministic function
> CREATE FUNCTION roll_dice()
    RETURNS INT
    NOT DETERMINISTIC
    CONTAINS SQL
    COMMENT 'Roll a single 6 sided die'
    RETURN (rand() * 6)::INT + 1;
-- Roll a single 6-sided die
> SELECT roll_dice();
 3

DEFAULTS kullanan bir işlev oluşturma ve kullanma

-- Extend the function to support variable number of sides and dice.
-- Use defaults to support a variable number of arguments
> DROP FUNCTION roll_dice;
> CREATE FUNCTION roll_dice(num_dice  INT DEFAULT 1 COMMENT 'number of dice to roll (Default: 1)',
                            num_sides INT DEFAULT 6 COMMENT 'number of sides per die (Default: 6)')
    RETURNS INT
    NOT DETERMINISTIC
    CONTAINS SQL
    COMMENT 'Roll a number of n-sided dice'
    RETURN aggregate(sequence(1, roll_dice.num_dice, 1),
                     0,
                     (acc, x) -> (rand() * roll_dice.num_sides)::int,
                     acc -> acc + roll_dice.num_dice);

-- Roll a single 6-sided die still works
> SELECT roll_dice();
 3

-- Roll 3 6-sided dice
> SELECT roll_dice(3);
 15

-- Roll 3 10-sided dice
> SELECT roll_dice(3, 10)
 21

-- Roll 3 10-sided dice using named parameter invocation
> SELECT roll_dice(10 => num_sides, num_dice => 3)
 17

-- Create a SQL function with a scalar subquery.
> CREATE VIEW scores(player, score) AS VALUES (0, 1), (0, 2), (1, 2), (1, 5);

> CREATE FUNCTION avg_score(p INT) RETURNS FLOAT
    COMMENT 'get an average score of the player'
    RETURN SELECT AVG(score) FROM scores WHERE player = p;

> SELECT c1, avg_score(c1) FROM t;
 0  1.5
 1  3.5

SQL tablo işlevi oluşturma

-- Produce all weekdays between two dates
> CREATE FUNCTION weekdays(start DATE, end DATE)
    RETURNS TABLE(day_of_week STRING, day DATE)
    RETURN SELECT extract(DAYOFWEEK_ISO FROM day), day
             FROM (SELECT sequence(weekdays.start, weekdays.end)) AS T(days)
                  LATERAL VIEW explode(days) AS day
             WHERE extract(DAYOFWEEK_ISO FROM day) BETWEEN 1 AND 5;

-- Return all weekdays
> SELECT weekdays.day_of_week, day
    FROM weekdays(DATE'2022-01-01', DATE'2022-01-14');
  1     2022-01-03
  2     2022-01-04
  3     2022-01-05
  4     2022-01-06
  5     2022-01-07
  1     2022-01-10
  2     2022-01-11
  3     2022-01-12
  4     2022-01-13
  5     2022-01-14

-- Return weekdays for date ranges originating from a LATERAL correlation
> SELECT weekdays.*
    FROM VALUES (DATE'2020-01-01'),
                (DATE'2021-01-01'),
                (DATE'2022-01-01') AS starts(start),
         LATERAL weekdays(start, start + INTERVAL '7' DAYS);
  3     2020-01-01
  4     2020-01-02
  5     2020-01-03
  1     2020-01-06
  2     2020-01-07
  3     2020-01-08
  5     2021-01-01
  1     2021-01-04
  2     2021-01-05
  3     2021-01-06
  4     2021-01-07
  5     2021-01-08
  1     2022-01-03
  2     2022-01-04
  3     2022-01-05
  4     2022-01-06
  5     2022-01-07

SQL işlevini değiştirme

-- Replace a SQL scalar function.
> CREATE OR REPLACE FUNCTION square(x DOUBLE) RETURNS DOUBLE RETURN x * x;

-- Replace a SQL table function.
> CREATE OR REPLACE FUNCTION getemps(deptno INT)
    RETURNS TABLE (name STRING)
    RETURN SELECT name FROM employee e WHERE e.deptno = getemps.deptno;

-- Describe a SQL table function.
> DESCRIBE FUNCTION getemps;
 Function: default.getemps
 Type:     TABLE
 Input:    deptno INT
 Returns:  id   INT
           name STRING

Not

Mevcut bir işlevi farklı bir imzayla değiştiremezsiniz.

SQL işlevini açıklama

> DESCRIBE FUNCTION hello;
 Function: hello
 Type:     SCALAR
 Input:    ()
 Returns:  STRING

> DESCRIBE FUNCTION area;
 Function: default.area
 Type:     SCALAR
 Input:    x DOUBLE
           y DOUBLE
 Returns:  DOUBLE

> DESCRIBE FUNCTION roll_dice;
 Function: default.roll_dice
 Type:     SCALAR
 Input:    num_dice  INT
           num_sides INT
 Returns:  INT

> DESCRIBE FUNCTION EXTENDED roll_dice;
 Function:      default.roll_dice
 Type:          SCALAR
 Input:         num_dice  INT DEFAULT 1 'number of dice to roll (Default: 1)'
                num_sides INT DEFAULT 6 'number of sides per dice (Default: 6)'
 Returns:       INT
 Comment:       Roll a number of m-sided dice
 Deterministic: false
 Data Access:   CONTAINS SQL
 Configs:       ...
 Owner:         the.house@always.wins
 Create Time:   Sat Feb 12 09:29:02 PST 2022
 Body:          aggregate(sequence(1, roll_dice.num_dice, 1),
                      0,
                      (acc, x) -> (rand() * roll_dice.num_sides)::int,
                      acc -> acc + roll_dice.num_dice)

Python işlevleri oluşturma

—- Hello World-like functionality using Python UDFs
> CREATE FUNCTION main.default.greet(s STRING)
  RETURNS STRING
  LANGUAGE PYTHON
  AS $$
    def greet(name):
      return "Hello " + name + "!"

    return greet(s) if s else None
  $$

—- Can import functions from std library and environment
> CREATE FUNCTION main.default.isleapyear(year INT)
  RETURNS BOOLEAN
  LANGUAGE PYTHON
  AS $$
    import calendar
    return calendar.isleap(year) if year else None
  $$

—- Must return the correct type. Otherwise will fail at runtime.
> CREATE FUNCTION main.default.a_number()
  RETURNS INTEGER
  LANGUAGE PYTHON
  AS $$
    # does not work: return "10"
    # does not work: return 3.14
    return 10
  $$

—- Deal with exceptions.
> CREATE FUNCTION main.default.custom_divide(n1 INT, n2 INT)
  RETURNS FLOAT
  LANGUAGE PYTHON
  AS $$
    try:
      return n1/n2
    except ZeroDivisionException:
    # in case of 0, we can return NULL.
    return None
  $$