function_invocation

Se aplica a: Databricks SQL Databricks Runtime

Una invocación de función ejecuta una función integrada o una función definida por el usuario después de asociar argumentos a los parámetros de la función.

Azure Databricks admite la invocación de parámetros posicionales, así como la invocación de parámetros con nombre.

Invocación de parámetros posicionales

Cada argumento se asigna al parámetro coincidente en la posición especificada.

Esta notación se usa para todas las funciones a menos que se documente explícitamente que se permita o requiera la invocación de parámetros con nombre.

Si la función admite parámetros opcionales, los parámetros finales para los que no se han especificado argumentos, son predeterminados.

Invocación de parámetros con nombre

Los argumentos se asignan explícitamente a parámetros mediante los nombres de parámetro publicados por la función.

Esta notación se debe usar para un subconjunto selecto de funciones integradas que permiten numerosos parámetros opcionales, lo que hace que la invocación de parámetros posicionales no sea práctica. Estas funciones pueden permitir una invocación mixta en la que se espera que un conjunto inicial de parámetros se asigne por posición y el conjunto opcional final de parámetros por nombre.

La invocación de parámetros con nombre, incluida la invocación mixta, también se puede usar para UDF de SQL y UDF de Python.

Sintaxis

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

  Nombre de la función integrada o definida por el usuario. Al resolver una instancia de Azure Databricks no calificada function_name, primero tendrá en cuenta una función integrada o temporal y, a continuación, una función en el esquema actual.

• argExpr

  Cualquier expresión que se pueda convertir implícitamente en el parámetro al que está asociada.

  La función puede imponer más restricciones en el argumento, como exigir literales, expresiones constantes o valores específicos.

• star_clause

  Una abreviatura para asignar un nombre a todas las columnas a las que se hace referencia en la FROMcláusula, o bien a las columnas o campos de una tabla específica de la cláusula FROM.

• table_argument

  

  Especifica un argumento para un parámetro que es una tabla.

  • TABLE ( table_name )

    Identifica una tabla para pasar a la función por nombre.

  • TABLE( consulta )

    Pasa el resultado de query a la función.

  • table-partitioning

    

    Opcionalmente, especifica que el argumento de tabla está particionado. Si no se especifica, Azure Databricks determinará la creación de particiones.

    • WITH SINGLE PARTITION

      El argumento de tabla no tiene particiones.

    • partition_expr

      Una o varias expresiones que definen cómo particionar el argumento de tabla. Cada expresión se puede componer de columnas que se presentan en el argumento, literales, parámetros, variables y funciones deterministas de tabla.

  • table-ordering

    

    Opcionalmente, especifica un orden en el que se pasan a la función las filas de resultados de cada partición del argumento de tabla.

    De forma predeterminada, el orden no está definido.

    • order_by_expr

      Una o varias expresiones. Cada expresión se puede componer de columnas que se presentan en el argumento, literales, parámetros, variables y funciones deterministas de tabla.

• namedParameter

  

  Nombre incompleto de un parámetro al que argExprse asigna.

  La notación de parámetros con nombre es compatible con UDF de SQL, UDF de Python y funciones integradas específicas.

Ejemplos

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

Artículos relacionados

• Expresión SQL
• Funciones integradas
• CREAR FUNCIONES (SQL y Python)
• CREATE FUNCTION (externo)
• * (star) cláusula