Wywołanie funkcji

Artykuł
03/01/2024

Dotyczy: check marked yes Databricks SQL Databricks Runtime

Wywołanie funkcji wykonuje wbudowaną funkcję lub funkcję zdefiniowaną przez użytkownika po skojarzeniu argumentów z parametrami funkcji.

Usługa Azure Databricks obsługuje wywołanie parametrów pozycyjnych, a także wywoływanie nazwanych parametrów.

Wywołanie parametru pozycyjnego

Każdy argument jest przypisywany do pasującego parametru w określonej pozycji.

Ta notacja może być używana przez wszystkie funkcje, chyba że jest jawnie udokumentowana, że wymagane jest wywołanie nazwanego parametru.

Jeśli funkcja obsługuje parametry opcjonalne, końcowe parametry, dla których nie określono żadnych argumentów, są domyślne.

Wywołanie nazwanego parametru

Argumenty są jawnie przypisywane do parametrów przy użyciu nazw parametrów publikowanych przez funkcję.

Ta notacja musi być używana w przypadku wybranego podzestawu wbudowanych funkcji , które zezwalają na wiele parametrów opcjonalnych, co powoduje niepraktyczne wywołanie parametrów pozycyjnych. Te funkcje mogą zezwalać na wywołanie mieszane, w którym oczekuje się, że wiodący zestaw parametrów zostanie przypisany przez pozycję i końcowy opcjonalny zestaw parametrów według nazwy.

Wywołanie nazwanego parametru, w tym wywołanie mieszane, może być również używane dla funkcji zdefiniowanej przez użytkownika SQL i funkcji zdefiniowanej przez użytkownika języka Python.

Składnia

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

Parametry

function_name

Nazwa wbudowanej lub zdefiniowanej przez użytkownika funkcji. Podczas rozpoznawania niekwalifikowanej function_name usługi Azure Databricks należy najpierw rozważyć wbudowaną lub tymczasową funkcję, a następnie funkcję w bieżącym schemacie.
argExpr

Dowolne wyrażenie, z którym można niejawnie rzutować parametr, z którym jest skojarzony.

Funkcja może narzucić dalsze ograniczenie argumentu, takie jak wymuszanie literałów, wyrażeń stałych lub określonych wartości.
star_clause

Skrócona nazwa wszystkich kolumn, do których można odwołać się w klauzuli FROM , lub kolumny lub pola określonej tabeli w klauzuli FROM .
table_argument

! [zaznacz oznaczone tak] (.. /.. /_static/images/icons/check.png Databricks SQL ! [zaznacz oznaczone tak] (.. /.. /_static/images/icons/check.png Databricks Runtime 14.0 i nowszych)

Określa argument parametru, który jest tabelą.
- TABLE ( table_name )
  
  Identyfikuje tabelę, która ma być przekazywana do funkcji według nazwy.
- TABLE ( zapytanie )
  
  Przekazuje wynik query funkcji .
- partycjonowanie tabel
  
  ! [zaznacz oznaczone tak] (.. /.. /_static/images/icons/check.png Databricks SQL ! [zaznacz oznaczone tak] (.. /.. /_static/images/icons/check.png Databricks Runtime 14.1 lub nowszy)
  
  Opcjonalnie określa, że argument tabeli jest partycjonowany. Jeśli nie określono partycjonowania, jest określane przez usługę Azure Databricks.
  - WITH SINGLE PARTITION
    
    Argument tabeli nie jest partycjonowany.
  - partition_expr
    
    Co najmniej jedno wyrażenie definiujące sposób partycjonowania argumentu tabeli. Każde wyrażenie może składać się z kolumn znajdujących się w argumencie tabeli, literałach, parametrach, zmiennych i funkcjach deterministycznych.
- table-ordering
  
  ! [zaznacz oznaczone tak] (.. /.. /_static/images/icons/check.png Databricks SQL ! [zaznacz oznaczone tak] (.. /.. /_static/images/icons/check.png Databricks Runtime 14.1 lub nowszy)
  
  Opcjonalnie określa kolejność, w której do funkcji są przekazywane wiersze wyników poszczególnych partycji argumentu tabeli.
  
  Domyślnie kolejność jest niezdefiniowana.
  - order_by_expr
    
    Co najmniej jedno wyrażenie. Każde wyrażenie może składać się z kolumn znajdujących się w argumencie tabeli, literałach, parametrach, zmiennych i funkcjach deterministycznych.
namedParameter

! [zaznacz oznaczone tak] (.. /.. /_static/images/icons/check.png Databricks SQL ! [zaznacz oznaczone tak] (.. /.. /_static/images/icons/check.png Databricks Runtime 14.0 i nowszych)

Niekwalifikowana nazwa parametru, do którego przypisano argExpr parametr .

Nazwana notacja parametrów jest obsługiwana w przypadku funkcji zdefiniowanych przez użytkownika SQL, UDF języka Python i określonych wbudowanych funkcji.

Przykłady

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