Funktionsaufruf

Gilt für: Databricks SQL Databricks Runtime

Mit einem Funktionsaufruf wird eine integrierte Funktion oder eine benutzerdefinierte Funktion ausgeführt, nachdem Argumente den Parametern der Funktion zugeordnet wurden.

Azure Databricks unterstützt sowohl das Aufrufen von Positionsparametern als auch das Aufrufen benannter Parameter.

Aufrufen von Positionsparametern

Jedes Argument wird dem entsprechenden Parameter an der angegebenen Position zugewiesen.

Diese Notation kann für alle Funktionen verwendet werden, es sei denn, es wird explizit dokumentiert, dass benannte Parameteraufrufe erforderlich sind.

Wenn die Funktion optionale Parameter unterstützt, werden standardmäßig nachstehende Parameter verwendet, für die keine Argumente angegeben wurden.

Aufrufen benannter Parameter

Argumente werden Parametern mithilfe der mit der Funktion veröffentlichten Parameternamen explizit zugewiesen.

Diese Notation muss für eine ausgewählte Teilmenge von integrierten Funktionen verwendet werden, die zahlreiche optionale Parameter ermöglichen, wodurch positionsbezogene Parameteraufrufe unpraktisch werden. Diese Funktionen können einen gemischten Aufruf zulassen, bei dem erwartet wird, dass vorstehende Parameter nach Position und nachstehende, optionale Parameter nach Name zugewiesen werden.

Benannter Parameteraufruf, einschließlich gemischten Aufruf, kann auch für SQL UDF- und Python-UDF verwendet werden.

Syntax

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

Parameter

• function_name

  Der Name der integrierten oder benutzerdefinierten Funktion. Beim Auflösen eines nicht qualifizierten function_name wird bei Azure Databricks zuerst eine integrierte oder temporäre Funktion und dann eine Funktion im aktuellen Schema berücksichtigt.

• argExpr

  Jeder Ausdruck, der implizit in den Parameter umgewandelt werden kann, dem er zugeordnet ist.

  Die Funktion kann weitere Einschränkungen für das Argument festlegen, z. B. das Voraussetzen von Literalen, konstanten Ausdrücken oder bestimmten Werten.

• star_clause

  Eine Abkürzung, um alle referenzierbaren Spalten in der FROM-Klausel oder die Spalten oder Felder eines bestimmten Tabellenverweises in der FROM-Klausel zu benennen.

• table_argument

  

  Gibt ein Argument für einen Parameter an, bei dem es sich um eine Tabelle handelt.

  • TABLE ( table_name )

    Ermittelt anhand des Namens eine Tabelle, die an die Funktion übergeben werden soll

  • TABLE ( Abfrage )

    Übergibt das Ergebnis von query an die Funktion

  • table-partitioning

    

    Gibt optional an, dass das Tabellenargument partitioniert ist. Wird diese Option nicht angegeben, wird die Partitionierung von Azure Databricks bestimmt.

    • WITH SINGLE PARTITION

      Das Tabellenargument ist nicht partitioniert.

    • partition_expr

      Mindestens ein Ausdruck, der die Partitionierung des Tabellenarguments definiert. Jeder Ausdruck kann aus Spalten aus dem Tabellenargument sowie aus Literalen, Parametern, Variablen und deterministischen Funktionen bestehen.

  • table-ordering

    

    Gibt optional eine Reihenfolge an, in der die Ergebniszeilen jeder Partition des Tabellenarguments an die Funktion übergeben werden.

    Standardmäßig ist die Reihenfolge nicht definiert.

    • order_by_expr

      Mindestens ein Ausdruck. Jeder Ausdruck kann aus Spalten aus dem Tabellenargument sowie aus Literalen, Parametern, Variablen und deterministischen Funktionen bestehen.

• namedParameter

  

  Der nicht qualifizierte Name eines Parameters, dem argExpr zugewiesen wird.

  Die Notation Benannter Parameter wird für SQL UDF, Python UDF und bestimmte integrierten Funktionen unterstützt.

Beispiele

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

Verwandte Artikel

• SQL-Ausdruck
• Integrierte Funktionen
• CREATE FUNCTION (SQL und Python)
• CREATE FUNCTION (Extern)
• * (star) clause