Invocação de função

  • Artigo

Aplica-se a: Marque Sim Databricks SQL Marque Sim Databricks Runtime

Uma invocação de função executa uma função interna ou uma função definida pelo usuário depois de associar argumentos aos parâmetros da função.

O Azure Databricks dá suporte à invocação de parâmetros posicionais, bem como à invocação de parâmetros nomeados.

Invocação de parâmetro posicional

Cada argumento é atribuído ao parâmetro correspondente na posição especificada.

Essa notação pode ser usada por todas as funções, a menos que esteja explicitamente documentado que a invocação de parâmetro nomeado é necessária.

Se a função suportar parâmetros opcionais, os parâmetros à direita para os quais nenhum argumento foi especificado serão padronizados.

Invocação de parâmetro nomeado

Os argumentos são explicitamente atribuídos aos parâmetros usando os nomes de parâmetros publicados pela função.

Esta notação deve ser usada para um subconjunto selecionado de funções incorporadas que permitem inúmeros parâmetros opcionais, tornando a invocação de parâmetros posicionais impraticável. Estas funções podem permitir uma invocação mista em que se espera que um conjunto principal de parâmetros seja atribuído por posição e o conjunto de parâmetros opcional à direita por nome.

A chamada de parâmetros nomeados, incluindo a chamada mista, também pode ser usada para SQL UDF e Python UDF.

Sintaxe

function_name ( [ argExpr | table_argument | star_clause ] [, ...]
                [ namedParameter => [ argExpr | table_argument ] [, ...] )

table_argument
  { TABLE ( { table_name | query } )
    [ table_partition ]
    [ table_order ]

table_partitioning
  { WITH SINGLE PARTITION |
    { PARTITION | DISTRIBUTE } BY { partition_expr | ( partition_expr [, ...] ) } }

table_ordering
  { { ORDER | SORT } BY { order_by_expr | ( order_by_expr [, ...] } }

Parâmetros

  • function_name

    O nome da função interna ou definida pelo usuário. Ao resolver um Azure Databricks não qualificado function_name , primeiro considerará uma função interna ou temporária e, em seguida, uma função no esquema atual.

  • argExpr

    Qualquer expressão que possa ser implicitamente convertida no parâmetro ao qual está associada.

    A função pode impor restrições adicionais ao argumento, como a imposição de literais, expressões constantes ou valores específicos.

  • star_clause

    Uma abreviatura para nomear todas as colunas referenciadas na FROM cláusula ou as colunas ou campos de uma referência de tabela específica na FROM cláusula.

  • table_argument

    ! [marque marcado sim] (.. /.. /_static/images/icons/check.png Databricks SQL ! [marque marcado sim] (.. /.. /_static/images/icons/check.png Databricks Runtime 14.0 e superior)

    Especifica um argumento para um parâmetro que é uma tabela.

    • TABLE( table_name )

      Identifica uma tabela a ser passada para a função pelo nome.

    • TABLE( consulta )

      Passa o resultado de query para a função.

    • particionamento de tabelas

      ! [marque marcado sim] (.. /.. /_static/images/icons/check.png Databricks SQL ! [marque marcado sim] (.. /.. /_static/images/icons/check.png Databricks Runtime 14.1 e superior)

      Opcionalmente, especifica que o argumento table é particionado. Se não for especificado, o particionamento será determinado pelo Azure Databricks.

      • WITH SINGLE PARTITION

        O argumento table não está particionado.

      • partition_expr

        Uma ou mais expressões que definem como particionar o argumento da tabela. Cada expressão pode ser composta de colunas presentes no argumento da tabela, literais, parâmetros, variáveis e funções determinísticas.

    • table-ordering

      ! [marque marcado sim] (.. /.. /_static/images/icons/check.png Databricks SQL ! [marque marcado sim] (.. /.. /_static/images/icons/check.png Databricks Runtime 14.1 e superior)

      Opcionalmente, especifica uma ordem na qual as linhas de resultado de cada partição do argumento da tabela são passadas para a função.

      Por padrão, a ordem é indefinida.

      • order_by_expr

        Uma ou mais expressões. Cada expressão pode ser composta de colunas presentes no argumento da tabela, literais, parâmetros, variáveis e funções determinísticas.

  • namedParameter

    ! [marque marcado sim] (.. /.. /_static/images/icons/check.png Databricks SQL ! [marque marcado sim] (.. /.. /_static/images/icons/check.png Databricks Runtime 14.0 e superior)

    O nome não qualificado de um parâmetro ao qual o argExpr é atribuído.

    A notação de parâmetro nomeado é suportada para SQL UDF, Python UDF e funções internas específicas.

Exemplos

-- The substr function has three parameter and expects arguents to be passed by position.
> SELECT substr('hello', 3, 2);
  ll

-- The last parameter, the length, of substr is optional, when it is ommited it retrns the remainder of the string.
> SELECT substr('hello', 3);
  llo

-- Use the star clause to turn a set of columns into an array.
> SELECT array(*) FROM VALUES (1, 2, 3) AS t(a, b, c);
  [1, 2, 3]

-- The second parameter, start position, is not optional
> SELECT substr('hello');
  Error: WRONG_NUM_ARGS

-- read_files() is a function that accepts numerous parameters, many of which depend on the data source
-- The first parameter is positional, after that use named parameter invocation
> SELECT * FROM read_files(
    's3://bucket/path',
    format => 'csv',
    schema => 'id int, ts timestamp, event string');

-- cloud_files_state() is a function that expects a table name as an argument
> SELECT path FROM cloud_files_state(TABLE(mytable));
  /some/input/path
  /other/input/path

-- Invoking a SQL UDF using named parameter invocation
> CREATE TEMPORARY FUNCTION increase(base INT, factor FLOAT DEFAULT 1) RETURNS INT RETURN base * factor;

-- Out of order assignment
> SELECT increase(factor => 1.2, base => 100);
 120

-- Mixed invocation
> SELECT increase(100, factor => 1.3);
 130

-- Using default
> SELECT increase(base => 100);
 100

-- No position invocation after named invocation is allowed
> SELECT increase(base => 100, 1.4);
 Error: UNEXPECTED_POSITIONAL_ARGUMENT