Invocação de função

Aplica-se a: SQL do Databricks Runtime do Databricks

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âmetro posicional, bem como à invocação de parâmetro nomeado.

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âmetros nomeados é obrigatória.

Se a função der suporte a 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 a parâmetros usando os nomes de parâmetro publicados pela função.

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

A invocação de parâmetro nomeado, incluindo a invocação mista, também pode ser usada na UDF do SQL e na UDF do Python.

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 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 mais restrições ao argumento, como a obrigatoriedade de literais, expressões de constante ou valores específicos.

• star_clause

  Uma abreviação nomear todas as colunas referenciáveis na cláusula FROM, ou as colunas ou campos de uma referência específica de tabela na cláusula FROM.

• table_argument

  

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

  • TABLE ( table_name )

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

  • TABLE ( consulta )

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

  • table-partitioning

    

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

    • WITH SINGLE PARTITION

      O argumento da tabela não é 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 de tabela, literais, parâmetros, variáveis e funções determinísticas.

  • table-ordering

    

    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 de tabela, literais, parâmetros, variáveis e funções determinísticas.

• namedParameter

  

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

  Há suporte para a notação de parâmetro nomeado na UDF do SQL, na UDF do Python e em 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 internas
• CREATE FUNCTION (SQL e Python)
• CREATE FUNCTION (Externa)
• * (estrela) cláusula