Invocation de la fonction

S’applique à : Databricks SQL Databricks Runtime

Un appel de fonction exécute une fonction intégrée ou une fonction définie par l’utilisateur après avoir associé des arguments aux paramètres de la fonction.

Azure Databricks prend en charge l’appel de paramètre positionnel ainsi que l’appel de paramètre nommé.

Appel de paramètre positionnel

Chaque argument est affecté au paramètre correspondant à la position spécifiée.

Cette notation peut être utilisée par toutes les fonctions à moins qu'il ne soit explicitement documenté que l'invocation de paramètre nommé est requise.

Si la fonction prend en charge des paramètres facultatifs, les paramètres de fin pour lesquels aucun argument n’a été spécifié sont définis par défaut.

Appel de paramètre nommé

Les arguments sont explicitement attribués aux paramètres à l’aide des noms de paramètres publiés par la fonction.

Cette notation doit être utilisée pour un sous-ensemble sélectionné de fonctions intégrées qui autorisent de nombreux paramètres facultatifs, ce qui rend l'invocation de paramètres de position peu pratique. Ces fonctions peuvent permettre une invocation mixte dans laquelle un ensemble de paramètres de début sont censés être attribués par position et l'ensemble de paramètres facultatif de fin par nom.

L'invocation de paramètres nommés, y compris l'invocation mixte, peut également être utilisée pour langage SQL UDF et Python UDF.

Syntaxe

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 [, ...] } }

Paramètres

• function_name

  Nom de la fonction intégrée ou définie par l’utilisateur. Lors de la résolution d’un function_name non qualifié, Azure Databricks prend d’abord en compte une fonction intégrée ou temporaire, puis une fonction dans le schéma actuel.

• argExpr

  Toute expression qui peut être implicitement castée vers le paramètre auquel elle est associée.

  La fonction peut imposer une restriction supplémentaire à l’argument, comme l’attribution de littéraux, d’expressions constantes ou de valeurs spécifiques.

• star_clause

  Raccourci pour nommer toutes les colonnes pouvant être référencées dans la clause FROM, ou les colonnes ou champs d’une référence de table spécifique dans la clause FROM.

• table_argument

  

  Spécifie un argument pour un paramètre qui est une table.

  • TABLE ( table_name )

    Identifie une table à passer à la fonction par son nom.

  • TABLE ( query )

    Transmet le résultat de query à la fonction.

  • table-partitioning

    

    Spécifie éventuellement que l'argument de table est partitionné. S’il n’est pas spécifié, le partitionnement est déterminé par Azure Databricks.

    • WITH SINGLE PARTITION

      L'argument table n'est pas partitionné.

    • partition_expr

      Une ou plusieurs expressions définissant comment partitionner l'argument de la table. Chaque expression peut être composée de colonnes présentes dans l'argument du tableau, de littéraux, de paramètres, de variables et de fonctions déterministes.

  • table-ordering

    

    Spécifie éventuellement un ordre dans lequel les lignes de résultat de chaque partition de l'argument de table sont transmises à la fonction.

    Par défaut, l'ordre n'est pas défini.

    • order_by_expr

      Une ou plusieurs expressions. Chaque expression peut être composée de colonnes présentes dans l'argument du tableau, de littéraux, de paramètres, de variables et de fonctions déterministes.

• namedParameter

  

  Nom non qualifié d’un paramètre auquel le argExpr est affecté.

  La notation des paramètres nommés est prise en charge pour langage SQL UDF, Python UDF et des fonctions intégrées spécifiques.

Exemples

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

Articles connexes

• Expression SQL
• Fonctions intégrées
• CREATE FUNCTION (SQL et Python)
• CREATE FUNCTION (externe)
• clause * (étoile)