Invocação de função

Aplica-se a: Databricks SQL Databricks Runtime

Uma invocação de função executa uma função interna incorporada ou uma função definida pelo utilizador 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 definidos como padrão.

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 de invocação mista, onde se espera que um conjunto inicial de parâmetros seja atribuído por posição e o conjunto de parâmetros opcionais que vem depois por nome.

A invocação de parâmetros nomeados, incluindo invocação 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 function_name não qualificado, o Azure Databricks considerará primeiro 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

  Databricks SQL Databricks Runtime 14.0 e versões superiores

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

  • (TABLEtable_name)

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

  • TABLE ( consulta )

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

  • particionamento de tabelas

    Databricks SQL Databricks Runtime 14.1 e versões superiores

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

    • WITH SINGLE PARTITION

      O argumento da tabela 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

    Databricks SQL Databricks Runtime 14.1 e versões superiores

    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

  Databricks SQL Databricks Runtime 14.0 e versões superiores

  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

Artigos relacionados

• Expressão SQL
• Funções incorporadas
• CREATE FUNCTION (SQL e Python)
• CREATE FUNCTION (Externo)
• Cláusula * (estrela)