Appel d’une UDF¶

Appel d’une UDF¶

En général, vous appelez une UDF de la même manière que vous appelez d’autres fonctions.

Si une UDF a des arguments, vous pouvez spécifier ces arguments par leur nom ou leur position.

Par exemple, l’UDF suivante accepte trois arguments :

CREATE OR REPLACE FUNCTION udf_concatenate_strings(
    first VARCHAR,
    second VARCHAR,
    third VARCHAR)
  RETURNS VARCHAR
  LANGUAGE SQL
  AS
  $$
    RETURN first || second || third;
  $$;

Lorsque vous appelez une UDF, vous pouvez spécifier les arguments par leur nom :

SELECT udf_concatenate_strings(
  first => 'one',
  second => 'two',
  third => 'three');

Si vous spécifiez les arguments par leur nom, il n’est pas nécessaire de les spécifier dans un ordre particulier :

SELECT udf_concatenate_strings(
  third => 'three',
  first => 'one',
  second => 'two');

Vous pouvez également spécifier les arguments par position :

SELECT udf_concatenate_strings(
  'one',
  'two',
  'three');

Remarques :

• Vous devez spécifier tous les arguments soit par leur nom, soit par leur position. Vous ne pouvez pas spécifier certains arguments par leur nom et d’autres par leur position.

  Lorsque vous spécifiez un argument par son nom, vous ne pouvez pas utiliser de guillemets doubles autour du nom de l’argument.

• Si deux fonctions ou deux procédures ont le même nom, mais des types d’arguments différents, vous pouvez utiliser les noms des arguments pour spécifier la fonction ou la procédure à exécuter, si les noms des arguments sont différents. Reportez-vous à Surcharge de procédures et de fonctions.

Appeler un UDF qui a des arguments optionnels¶

Si l’UDF comporte des arguments facultatifs, vous pouvez omettre les arguments facultatifs dans l’appel. Chaque argument facultatif a une valeur par défaut qui est utilisée lorsque l’argument est omis.

Par exemple, l’UDF suivant a un argument obligatoire et deux arguments facultatifs. Chaque argument facultatif a une valeur par défaut.

CREATE OR REPLACE FUNCTION build_string_udf(
    word VARCHAR,
    prefix VARCHAR DEFAULT 'pre-',
    suffix VARCHAR DEFAULT '-post'
  )
  RETURNS VARCHAR
  AS
  $$
    SELECT prefix || word || suffix
  $$
  ;

Vous pouvez omettre tout argument facultatif dans l’appel. Lorsque vous omettez un argument, la valeur par défaut de l’argument est utilisée.

SELECT build_string_udf('hello');

+---------------------------+
| BUILD_STRING_UDF('HELLO') |
|---------------------------|
| pre-hello-post            |
+---------------------------+

SELECT build_string_udf('hello', 'before-');

+--------------------------------------+
| BUILD_STRING_UDF('HELLO', 'BEFORE-') |
|--------------------------------------|
| before-hello-post                    |
+--------------------------------------+

Si vous devez omettre un argument facultatif et spécifier un autre argument facultatif qui apparaît après l’argument omis dans la signature, utilisez des arguments nommés plutôt que des arguments positionnels.

Par exemple, supposons que vous souhaitiez omettre l’argument prefix et spécifier l’argument suffix. L’argument suffix apparaît après l’argument prefix dans la signature, vous devez donc spécifier les arguments par leur nom :

SELECT build_string_udf(word => 'hello', suffix => '-after');

+-------------------------------------------------------+
| BUILD_STRING_UDF(WORD => 'HELLO', SUFFIX => '-AFTER') |
|-------------------------------------------------------|
| pre-hello-after                                       |
+-------------------------------------------------------+

Appel d’une UDTF¶

Appelez une UDTF comme vous le feriez pour n’importe quelle fonction de table. Lorsque vous appelez une UDTF dans la clause FROM d’une requête, spécifiez le nom et les arguments de l’UDTF à l’intérieur des parenthèses qui suivent le mot-clé TABLE, comme vous le feriez lors de l’appel d’une fonction de table intégrée.

En d’autres termes, utilisez une forme telle que la suivante pour le mot-clé TABLE lorsque vous appelez une UDTF :

SELECT ...
  FROM TABLE ( udtf_name (udtf_arguments) )

Le code de l’exemple suivant appelle la fonction de table my_java_udtf, en spécifiant un littéral DATE dans l’argument '2021-01-16'::DATE.

SELECT ...
  FROM TABLE(my_java_udtf('2021-01-16'::DATE));

L’argument d’une fonction de table peut être une expression et pas seulement un littéral. Par exemple, une fonction de table peut être appelée en utilisant une colonne d’une table. Vous trouverez quelques exemples ci-dessous, notamment dans la section Exemples.

Comme dans le cas avec l’appel d’UDFs, vous pouvez spécifier les arguments par nom ou par position.

Pour plus d’informations sur les fonctions de table en général, voir fonction de table.

create table file_names (file_name varchar);
insert into file_names (file_name) values ('sample.txt'),
                                          ('sample_2.txt');

select f.file_name, w.word
   from file_names as f, table(split_file_into_words(f.file_name)) as w;

+-------------------+------------+
| FILE_NAME         | WORD       |
+-------------------+------------+
| sample_data.txt   | some       |
| sample_data.txt   | words      |
| sample_data_2.txt | additional |
| sample_data_2.txt | words      |
+-------------------+------------+

create function split_file_into_words(inputFileName string)
    ...
    imports = ('@inline_jars/sample.txt', '@inline_jars/sample_2.txt')
    ...

SELECT *
    FROM stocks_table AS st,
         TABLE(my_udtf(st.symbol, st.transaction_date, st.price) OVER (PARTITION BY st.symbol))

SELECT *
    FROM stocks_table AS st,
         TABLE(my_udtf(st.symbol, st.transaction_date, st.price) OVER (PARTITION BY 1))

SELECT *
     FROM stocks_table AS st,
          TABLE(my_udtf(st.symbol, st.transaction_date, st.price) OVER (PARTITION BY st.symbol ORDER BY st.transaction_date))

SELECT *
    FROM stocks_table AS st,
         TABLE(my_udtf(st.symbol, st.transaction_date, st.price) OVER (PARTITION BY st.symbol ORDER BY st.transaction_date))
    ORDER BY st.symbol, st.transaction_date, st.transaction_time;

SELECT * FROM udtf_table, TABLE(my_func(col1) OVER (PARTITION BY udtf_table.col2 * 2));   -- NO!