Partilhar via

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 embutida ou uma função definida pelo usuário após associar os argumentos ao parametersda 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 parametersopcionais, os parameters subsequentes, para os quais não houver argumentos especificados, assumirão os valores padrão.

Invocação de parâmetro nomeado

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

Esta notação deve ser usada para um subconjunto select de funções integradas que permitem numerosos parâmetros opcionais parameters, tornando a invocação de parâmetros posicionais impraticável. Estas funções podem permitir uma invocação mistawhere, sendo esperado que um elemento principal set de parameters seja atribuído por posição e a parte final, opcional set de parameters pelo 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 [, ...] } }

Parameters

  • 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 schemaatual.

  • 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 obrigatoriedade de literais, expressões constantesou valuesespecíficas.

  • star_clause

    Uma abreviatura para nomear todos os columns referenciados na cláusula FROM ou os columns ou campos de uma referência table específica na cláusula FROM.

  • 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 é um table.

    • TABLE ( table_name )

      Identifica um table para ser passado para a função pelo nome.

    • TABLE ( consulta )

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

    • table-particionamento

      ! [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 é particionado.

      • partition_expr

        Uma ou mais expressões que definem como partition o argumento table. Cada expressão pode ser composta por columns presentes no argumento table, literais, parameters, 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 partition do argumento table 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 por ocorrências de columns no argumento table, literais, parameters, 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