CREATE FUNCTION(SQL, Python, Scala e Java)

Aplica-se a: SQL do Databricks Databricks Runtime

Cria uma função SQL escalar ou de tabela que aceita um conjunto de argumentos e retorna um valor escalar ou um conjunto de linhas.

Aplica-se a: SQL do Databricks LTS do Databricks Runtime 13.3 e superior

Cria uma função escalar do Python que usa um conjunto de argumentos e retorna um valor escalar.

Os UDFs Python requerem o Unity Catalog em armazéns sem servidor ou pro SQL, ou um recurso de computação habilitado para o Unity Catalog.

Aplica-se a: SQL do Databricks Databricks Runtime 14.1 e superior

Além da invocação de parâmetro posicional, você também pode invocar a UDF do SQL e do Python usando a invocação de parâmetro nomeado.

Aplica-se a: Databricks SQL Databricks Runtime 16.2 e versões superiores

Use a ENVIRONMENT cláusula para instalar dependências personalizadas e defina a versão do ambiente para uma função declarada com LANGUAGE PYTHON. Na computação clássica, um environment_version outro requer 'None' Databricks Runtime 18.2 ou superior.

Aplica-se a: Databricks SQL Databricks Runtime 16.3 e superior

Use PARAMETER STYLE PANDAS com a HANDLER cláusula para definir uma função em lote LANGUAGE PYTHON . O handler processa os dados de entrada como iteradores de pandas.Series objetos e gera pandas.Series objetos como saída.

Aplica-se a: Databricks SQL Databricks Runtime 18.1 and above

Use a HANDLER cláusula com uma função escalar LANGUAGE PYTHON linha a linha para nomear a função Python que lida com entradas UDF. Em computação serverless e em warehouses SQL pro e serverless, defina explicitamente os UDFs environment_version para 6 ou acima.

Aplica-se a: Databricks SQL Databricks Runtime 16.3 e superior

Use a CREDENTIALS cláusula para declarar credenciais de serviço do Unity Catalog que uma função escalar LANGUAGE PYTHON em lote ou linha a linha acessa. Veja Usar uma credencial de serviço em um UDF Python para requisitos de tipo de função, computação, ambiente e rede.

Aplica-se a: Databricks SQL Runtime 19 e acima

Use a SECRETS cláusula para declarar segredos do Unity Catalog que uma função escalar, batch LANGUAGE PYTHON ou uma função escalar LANGUAGE SCALA acessa. Veja requisitos e permissões do UDF para requisitos de computação, ambiente e permissões.

Aplica-se a: Databricks SQL Databricks Runtime 18.2 and above

Cria uma função escalar Scala ou Java que executa a lógica JVM compilada empacotada como um JAR. As UDFs scala e Java exigem o Catálogo do Unity. O suporte a SQL Warehouse é limitado a SQL Warehouses Pro e serverless. Você faz referência ao código compilado com a HANDLER cláusula e fornece o JAR por meio da ENVIRONMENT chave da java_dependencies cláusula. Para obter o fluxo de trabalho completo, incluindo como criar o JAR e registrar a função, consulte Scala e Java UDFs (funções definidas pelo usuário) no Catálogo do Unity.

Permissions

Para criar uma função no Unity Catalog, você deve ter todas as seguintes opções:

• USE CATALOG no catálogo e USE SCHEMA no esquema onde você cria a função
• CREATE FUNCTION privilégio no esquema onde você cria a função
• SELECT em cada tabela ou visualização do Catálogo Unity referenciada, além USE CATALOGUSE SCHEMA do catálogo e esquema que a contêm
• EXECUTE em cada função definida pelo usuário referenciada, além USE CATALOG de e USE SCHEMA no catálogo e esquema que a contêm
• READ FILES no local externo que apoia cada caminho de armazenamento em nuvem referenciado, por exemplo read_files('s3://bucket/path')
• READ VOLUME em cada volume referenciado por um /Volumes/... caminho, além USE CATALOG do USE SCHEMA catálogo e esquema que o contêm

Esses privilégios são verificados quando você cria a função. Para saber como as instruções dentro do corpo da função são autorizadas quando a função é executada, veja Usuário autorizado e usuário da sessão.

No Unity Catalog, substituir uma função existente por CREATE OR REPLACE FUNCTION também exige que você possua a função ou tenha MANAGE nela, ou possua ou tenha MANAGE em seu esquema ou catálogo pai. Os privilégios de uso que você também precisa dependem do nível do objeto no qual você detém a propriedade ou MANAGE. Veja Requisitos de privilégio de uso para MANAGE. A nova definição de função pode exigir privilégios adicionais em tabelas, vistas, funções e caminhos referenciados.

Sintaxe

CREATE [OR REPLACE] [TEMPORARY] FUNCTION [IF NOT EXISTS]
    function_name ( [ function_parameter [, ...] ] )
    { [ RETURNS data_type ] |
      RETURNS TABLE [ ( column_spec [, ...]) ] }
    [ characteristic [...] ]
    { AS dollar_quoted_string | HANDLER handler_name [ 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 | SCALA | JAVA } |
    [NOT] DETERMINISTIC |
    COMMENT function_comment |
    [CONTAINS SQL | READS SQL DATA] |
    DEFAULT COLLATION default_collation_name |
    PARAMETER STYLE PANDAS |
    CREDENTIALS ( service_credential [, ...] ) |
    SECRETS ( secret_name [, ...] ) } |
    environment }

service_credential
    credential_name [ DEFAULT | AS credential_alias ]

secret_name
    catalog_name.schema_name.secret_name

environment
  ENVIRONMENT ( { environment_key = environment_value } [, ...] )

Parâmetros

• OU SUBSTITUIR

  Se especificado, uma função ou procedimento existente com o mesmo nome é substituído. A assinatura da nova função (número de parâmetros e tipos de parâmetros), o tipo de retorno e o corpo podem diferir da função existente. Não é possível especificar esse parâmetro com IF NOT EXISTS.

• TEMPORARY

  É o escopo da função que está sendo criada. Quando você especifica TEMPORARY, a função criada é válida e visível na sessão atual. Nenhuma entrada persistente é feita no catálogo.

• SE NÃO EXISTIR

  Se especificado, cria a função somente quando ela não existir. A criação da função terá êxito (nenhum erro será gerado) se a função especificada já existir no sistema. Não é possível especificar esse parâmetro com OR REPLACE.

• function_name

  Nome da função. Para uma função permanente, você pode qualificar o nome da função com um nome de esquema. Se o nome não for qualificado, a função permanente será criada no esquema atual.

  O nome da função deve ser exclusivo para todas as rotinas (procedimentos e funções) no esquema.

• function_parameter

  Especifica um parâmetro da função.

  • parameter_name

    O nome do parâmetro deve ser exclusivo na função.

  • tipo_de_dado

    Qualquer tipo de dados com suporte. Para Python, data_type é convertido em um tipo de dados Python de acordo com esse mapeamento de linguagem.

    Para um STRINGdata_type, a ordenação padrão é a função default_collation_name.

  • PADRÃO default_expression

    Aplica-se a: SQL do Databricks LTS do Databricks Runtime 10.4 e superior

    Um padrão opcional a ser usado quando uma invocação de função não atribui um argumento ao parâmetro. default_expression deve ser conversível em data_type. A expressão não deve fazer referência a outro parâmetro nem conter uma subconsulta.

    Quando você especifica um padrão para um parâmetro, todos os parâmetros seguintes também devem ter um padrão.

    DEFAULT é compatível apenas com LANGUAGE SQL .

  • Comentário COMMENT

    Uma descrição opcional do parâmetro. comment deve ser uma literal de STRING.

• RETORNA data_type

  O tipo de dados de retorno da função escalar. Para UDFs em Python, os valores de retorno devem corresponder ao .data_type

  Para a UDF do SQL, essa cláusula é opcional. O tipo de dado é derivado do corpo da função caso não seja fornecido.

• RETURNS TABLE [ (especificação_de_coluna [,...] ) ]

  Essa cláusula marca a função como uma função de tabela. Opcionalmente, ele também especifica a assinatura do resultado da função de tabela. Se nenhuma column_spec for especificada, ela será derivada do corpo da UDF do SQL.

  RETURNS TABLE há suporte para LANGUAGE SQL e para LANGUAGE PYTHONUDTFs polimórficos (Databricks Runtime 18.1 e superior).

  • nome_da_coluna

    O nome da coluna deve ser exclusivo na assinatura.

  • tipo_de_dado

    Qualquer tipo de dados com suporte.

  • COMENTÁRIO column_comment

    Uma descrição opcional da coluna. comment deve ser uma literal de STRING.

• RETURN { expressão | consulta }

  O corpo da função. Para uma função escalar, pode ser uma consulta ou expressão. Para uma função de tabela, só pode ser uma consulta. A expressão não pode conter:

  • Funções de agregação
  • Funções da janela
  • Funções de classificação
  • Funções de produção de linha, como detalhar

  No corpo da função, você pode consultar o parâmetro pelo seu nome não qualificado ou qualificando-o com o nome da função.

• COMO dollar_quoted_definition

  dollar_quoted_definition é a função body do Python incluída por dois $[tag]$body$[tag]$ correspondentes. tag pode ser uma cadeia de caracteres vazia.

  Exemplos:

  $$
    return “Hello world”
  $$
  
  $py$
    return "Hello World"
  $py$
  

• MANIPULADOR handler_name

  Para uma função escalar LANGUAGE PYTHON de linha por vez:

  Aplica-se a: Databricks SQL Databricks Runtime 18.1 and above

  handler_nameé um STRING literal que nomeia a função Python na definição citada por dólar, que implementa o UDF. O manipulador aceita os argumentos UDF e retorna um valor que corresponde ao tipo de retorno declarado. Em computação serverless e em warehouses SQL pro e serverless, defina explicitamente os UDFs environment_version para 6 ou acima. Veja: Use um handler nomeado em um UDF escalar de Python.

  Para uma função batch LANGUAGE PYTHON declarada com PARAMETER STYLE PANDAS:

  Aplica-se a: Databricks SQL Databricks Runtime 16.3 e superior

  handler_nameé um STRING literal que nomeia a função Python na definição citada por dólar, que implementa o UDF. O manipulador aceita um iterador sobre um ou mais pandas.Series objetos e gera pandas.Series objetos com o mesmo número de linhas que a entrada. Veja a função do handler UDF em lote.

  Para uma LANGUAGE SCALA função ou LANGUAGE JAVA :

  Aplica-se a: Databricks SQL Databricks Runtime 18.2 and above

  O caminho totalmente qualificado para o método que implementa uma função ou LANGUAGE SCALA uma LANGUAGE JAVA função, como um STRING literal. Use o formato 'package.Object.method' para Scala e 'package.ClassName.method' para Java. O código compilado deve ser fornecido como um JAR por meio da java_dependencies chave da ENVIRONMENT cláusula.

• CREDENTIALS ( service_credential [, ...] )

  Aplica-se a: Databricks SQL Databricks Runtime 16.3 e superior

  Declara uma ou mais credenciais de serviço do Unity Catalog que uma função batch LANGUAGE PYTHON pode usar. Funções escalares LANGUAGE PYTHON linha a linha exigem Databricks Runtime 18.1 ou superior na computação clássica. Em computação serverless e em repositórios SQL pro e serverless, funções escalares devem ser explicitamente definidas environment_version como 6 ou acima. Veja Usar uma credencial de serviço em um UDF Python para requisitos completos.

  Cada um credential_name nomeia uma credencial de serviço do Catálogo Unity. O criador do UDF deve ter o ACCESS privilégio de cada credencial de serviço. Marque no máximo uma credencial para DEFAULT que SDKs de nuvem atualizados a usem automaticamente. Use AS credential_alias para atribuir um alias único a uma credencial não padrão.

• SEGREDOS ( secret_name [, ...] )

  Aplica-se a: Databricks SQL Runtime 19 e acima

  Declara os segredos do Catálogo Unity que uma função escalar ou batch LANGUAGE PYTHON ou uma função escalar LANGUAGE SCALA pode acessar. A definição do UDF deve definir environment_version explicitamente como 6 ou acima. Cada secret_name um deve ser um nome em três partes na forma catalog.schema.secret. Para criar ou substituir o UDF, você deve ter READ SECRET em cada segredo e USE CATALOGUSE SCHEMA em seu catálogo pai e esquema. Veja requisitos e permissões do UDF para suporte de computação e comportamento de permissões em tempo de execução. Para exemplos, veja UDFs em Python ou UDFs em Scala.

• característica

  Todas as cláusulas de característica são opcionais. Você pode especificar qualquer número delas, em qualquer ordem, mas só pode especificar cada cláusula uma vez.

  • IDIOMA SQL, PYTHON DE LINGUAGEM, SCALA DE LINGUAGEM ou JAVA DE LINGUAGEM

    A linguagem da implementação da função. LANGUAGE SCALA e LANGUAGE JAVA exigir o Catálogo do Unity e uma HANDLER cláusula que faça referência ao código compilado fornecido por meio da ENVIRONMENT cláusula. Consulte Scala e Java UDFs (funções definidas pelo usuário) no Catálogo do Unity.

  • PANDAS DE ESTILO DE PARÂMETROS

    Aplica-se a: Databricks SQL Databricks Runtime 16.3 e superior

    Declara uma função batch LANGUAGE PYTHON que troca dados com o handler como iteradores de pandas.Series objetos. Você também deve especificar uma HANDLER cláusula. Consulte O Lote Python UDFs (funções definidas pelo usuário) no Catálogo do Unity.

  • [NÃO] DETERMINÍSTICO

    Se a função é determinística. Uma função é determinística quando retorna apenas um resultado para determinado conjunto de argumentos. Você pode marcar uma função como DETERMINISTIC quando seu corpo não é e vice-versa. Um motivo para isso pode ser incentivar ou desencorajar otimizações de consulta, como dobramento constante ou cache de consulta. Se você não especificar essa opção, o padrão depende da linguagem da função. Para funções SQL, ele é derivado do corpo da função. Para funções em Python, Scala e Java, a função é NOT DETERMINISTIC.

  • COMENTÁRIO function_comment

    Um comentário para a função. function_comment deve ser um literal de cadeia de caracteres.

  • CONTAINS SQL ou READS SQL DATA

    Se uma função lê dados direta ou indiretamente de uma tabela ou exibição. Quando a função lê SQL dados, você não pode especificar CONTAINS SQL. Se você não especificar nenhuma das cláusulas, a propriedade será derivada do corpo da função.

  • COLOCAÇÃO PADRÃO default_collation_name

    Aplica-se a: Databricks SQL Databricks Runtime 17.0 e superior

    Define a ordenação padrão a ser usada para:

    • STRING parâmetros, RETURNS tipo de dados e RETURNS TABLE campos da função.
    • Expressão DEFAULT.
    • O corpo da função SQL.

    Se não for especificado, a ordenação padrão será derivada do esquema no qual a função é criada.

• ambiente

  Especifica o ambiente para uma função declarada com LANGUAGE PYTHON, LANGUAGE SCALAou LANGUAGE JAVA. A ENVIRONMENT cláusula não tem suporte para funções SQL. Você deve especificar environment_version sempre que incluir a ENVIRONMENT cláusula.

  • Dependências

    Uma matriz JSON de cadeias de caracteres especificando os pacotes Python necessários ou arquivos de roda para uma LANGUAGE PYTHON função. A chave dependencies não diferencia maiúsculas de minúsculas. Formatos com suporte:

    • Pacote PyPI com versão opcional, por exemplo: "simplejson==3.19.3"
    • Caminho absoluto para um arquivo de roda armazenado em um volume do Unity Catalog, por exemplo: "/Volumes/my_catalog/my_schema/my_volume/packages/custom_package-1.0.0.whl"
    • URL HTTPS para um arquivo wheel no armazenamento externo, por exemplo: "https://my-bucket.s3.amazonaws.com/packages/special_package-2.0.0.whl?Expires=..."

    Para uma dependência armazenada em um volume do Unity Catalog, o criador da função deve estar READ VOLUME no volume de origem. Os requisitos do chamador dependem da versão do ambiente. Veja Permissões para dependências em volumes do Catálogo Unity.

  • java_dependencies

    Aplica-se a: Databricks SQL Databricks Runtime 18.2 and above

    Uma matriz JSON de cadeias de caracteres que especifica os arquivos JAR que contêm o código compilado para uma LANGUAGE SCALA ou LANGUAGE JAVA função. Cada entrada é um caminho absoluto para um arquivo JAR armazenado em um volume do Catálogo do Unity, por exemplo: "/Volumes/my_catalog/my_schema/my_volume/packages/my-udf-assembly-0.1.0.jar". Empacote o código como um JAR gordo que inclui todas as dependências de terceiros usadas pelo UDF.

  • environment_version

    Uma string especificando a versão do ambiente.

    • Para LANGUAGE PYTHON, valores suportados são uma versão ambiental de 3 ou superior, como '6', ou 'None'. O valor 'None' seleciona o ambiente Python padrão. Na computação clássica, definir environment_version para um valor diferente 'None' requer Databricks Runtime 18.2 ou superior. No Databricks Runtime 16.2 a 18.1, apenas 'None' é suportado. Quando versões fixas do ambiente forem suportadas, selecione explicitamente uma para comportamento previsível.

      Em computação serverless e em repositórios SQL pro e serverless, alguns recursos exigem uma versão explícita do ambiente. Definido environment_version para a versão requerida ou acima em cada definição de UDF. Omitir a cláusula ou configuração environment_version = 'None' não habilita esses recursos. Veja requisitos de recursos do Python UDF.

      Para compatibilidade com versões de computação clássica, veja Versões do Ambiente na computação clássica. Para ver a lista de versões disponíveis, consulte Versões de ambiente.

    • Para LANGUAGE SCALA e LANGUAGE JAVA, o valor deve ser '4' ou superior. A versão 4 do Ambiente especifica Scala 2.13.16 e JDK 17. Veja Versões do Ambiente.

Bibliotecas compatíveis em UDFs do Python

Para usar quaisquer dependências, use import <package> dentro do corpo da função. Por exemplo, confira a seguir:

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

Por padrão, as dependências são limitadas à biblioteca padrão do Python e às seguintes bibliotecas:

Pacote	Versão
bleach	4.0.0
chardet	4.0.0
normalizador de conjunto de caracteres	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
empacotamento	21,3
Pandas	1.3.4
patsy	0.5.2
protobuf	4.21.5
pyarrow	7.0.0
pyparsing	3.0.9
python-dateutil	2.8.2
pytz	2021.3
scikit-learn	0.24.2”
scipy	1.7.1”
setuptools	65.2.0
seis	1.16.0
threadpoolctl	3.1.0
codificações web	0.5.1
user-agents	2.2.0
criptografia	38.0.4

Dependências personalizadas em UDFs do Python

Para usar dependências adicionais além da biblioteca padrão e dos pacotes internos com suporte, especifique-as na ENVIRONMENT cláusula.

Exemplos

• Criar e usar uma função escalar SQL
• Criar e usar uma função que usa PADRÃO
• Criar uma função de tabela SQL
• Substituir uma função SQL
• Descrever uma função SQL
• Criar funções do Python
• Definir dependências personalizadas em funções do Python
• Criar funções Scala e Java

Criar e usar uma função escalar SQL

> 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

Criar e usar uma função que usa padrões

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

Criar uma função de tabela SQL

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

Substituir uma função SQL

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

Descrever uma função SQL

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

Criar funções do Python

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

-- Return values should match the declared data type.
> CREATE FUNCTION main.default.a_number()
  RETURNS INTEGER
  LANGUAGE PYTHON
  AS $$
    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
  $$

Definir dependências personalizadas em funções do Python

-- Create a Python function with additional dependencies using the ENVIRONMENT clause.
> CREATE FUNCTION main.default.dump_json(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))
    $$;

-- Use the Python function in a query.
> SELECT dump_json('{"foo": "bar"}');

Criar funções Scala e Java

Os exemplos a seguir registram um UDF do código JVM compilado empacotado como um JAR em um volume do Catálogo do Unity. A HANDLER cláusula faz referência ao método no JAR e a java_dependencies chave aponta para o JAR. Para obter o fluxo de trabalho completo, incluindo como criar o JAR, consulte Scala e Java UDFs (funções definidas pelo usuário) no Catálogo do Unity.

-- Register a Scala UDF from a JAR in a Unity Catalog volume.
> CREATE OR REPLACE FUNCTION my_catalog.my_schema.add_one_scala(x INT)
    RETURNS INT
    LANGUAGE SCALA
    DETERMINISTIC
    ENVIRONMENT (
      java_dependencies = '["/Volumes/my_catalog/my_schema/udf_jars/my-udf-assembly-0.1.0.jar"]',
      environment_version = '4'
    )
    HANDLER 'com.example.ScalaUDF.addOne';

-- Register a Java UDF from a JAR in a Unity Catalog volume.
> CREATE OR REPLACE FUNCTION my_catalog.my_schema.add_one_java(x INT)
    RETURNS INT
    LANGUAGE JAVA
    DETERMINISTIC
    ENVIRONMENT (
      java_dependencies = '["/Volumes/my_catalog/my_schema/udf_jars/my-udf-1.0.jar"]',
      environment_version = '4'
    )
    HANDLER 'com.example.JavaUDF.addOne';

-- Use the functions in a query.
> SELECT my_catalog.my_schema.add_one_scala(5);
 6
> SELECT my_catalog.my_schema.add_one_java(5);
 6

Artigos relacionados

• Escala e Java UDFs (funções definidas pelo usuário) no Catálogo do Unity
• DROP FUNCTION
• SHOW FUNCTIONS
• DESCRIBE FUNCTION
• GRANT
• REVOKE