閱讀英文

共用方式為


函式引動過程

適用於:核取記號為「是」Databricks SQL 核取記號為「是」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 及更新版本)

    指定資料表的參數引數。

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