函式引動過程

  • 發行項

適用於：check marked yes Databricks SQL check marked yes Databricks Runtime

函式調用會在 將自變數關聯至函式的參數之後，執行內建函 式或使用者定義函式。

Azure Databricks 支援 位置參數調用 ，以及 具名參數調用。

位置參數調用

每個自變數都會指派給指定位置的相符參數。

除非已明確記載具名參數調用，否則所有函式都可以使用此表示法。

如果函式支援選擇性參數，則預設不會指定任何自變數的尾端參數。

具名參數調用

自變數會使用函式所發行的參數名稱，明確指派給參數。

這個表示法必須用於內建函式的選取子集，以允許許多選擇性參數，使位置參數調用不切實際。 這些函式可能會允許 混合調用 ，其中一組前置參數預期會依位置指派，以及依名稱指派的尾端選擇性參數集。

具名參數調用，包括 混合調用，也可用於 SQL UDF 和 Python UDF。

語法

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

參數

  • function_name

    內建或使用者定義函數的名稱。 解析未限定 function_name 的 Azure Databricks 時，會先考慮內建或暫存函式，然後再考慮目前架構中的函式。

  • argExpr

    任何可隱含轉換成其相關聯參數的表達式。

    函式可能會對自變數施加進一步的限制，例如強制常值、 常數表達式或特定值。

  • star_clause

    用來命名 子句中 FROM 所有可參考數據行的速記，或子句中 FROM 特定數據表參考的數據行或欄位。

  • table_argument

    ![檢查標示為是](../../_static/images/icons/check.png Databricks SQL ！[檢查標示為是](../../_static/images/icons/check.png Databricks Runtime 14.0 及更新版本）

    指定數據表之參數的自變數。

    • TABLE （ table_name ）

      識別要依名稱傳遞至函式的數據表。

    • TABLE （ 查詢 ）

      將的結果 query 傳遞至 函式。

    • 數據表分割

      ![檢查標示為是](../../_static/images/icons/check.png Databricks SQL ！[檢查標示為是](../../_static/images/icons/check.png Databricks Runtime 14.1 和更新版本）

      選擇性地指定已分割數據表自變數。 如果未指定數據分割，則由 Azure Databricks 決定。

      • WITH SINGLE PARTITION

        數據表自變數未分割。

      • partition_expr

        定義如何分割數據表自變數的一或多個表達式。 每個表達式都可以由數據表自變數、常值、參數、變數和決定性函式中呈現的數據行組成。

    • table-ordering

      ![檢查標示為是](../../_static/images/icons/check.png Databricks SQL ！[檢查標示為是](../../_static/images/icons/check.png Databricks Runtime 14.1 和更新版本）

      選擇性地指定將數據表自變數之每個分割區的結果數據列傳遞至函式的順序。

      根據預設，順序為未定義。

      • order_by_expr

        一或多個表達式。 每個表達式都可以由數據表自變數、常值、參數、變數和決定性函式中呈現的數據行組成。

  • namedParameter

    ![檢查標示為是](../../_static/images/icons/check.png Databricks SQL ！[檢查標示為是](../../_static/images/icons/check.png Databricks Runtime 14.0 及更新版本）

    指派 之參數 argExpr 的不限定名稱。

    SQL UDF、Python UDF 和特定內建函式支援具名參數表示法。

範例

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