関数呼び出し

適用対象: 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

  組み込み関数またはユーザー定義関数の名前。 Azure Databricks では、非修飾の function_name を解決するときに、まず組み込み関数か一時関数が考慮され、次に現在のスキーマ内の関数が考慮されます。

• argExpr

  関連付けられているパラメーターに暗黙的にキャストできる式。

  関数によって、必須のリテラル、定数式、特定の値など、引数にさらに制限が課される場合があります。

• star_clause

  FROM 句内のすべての参照可能な列、または FROM 句内の特定のテーブル参照の列またはフィールドに名前を付ける短縮形。

• table_argument

  !["はい" のチェック マーク](../../_static/images/icons/check.png Databricks SQL 

  テーブルである、パラメーターの引数を指定します。

  • TABLE ( テーブル名 )

    関数に渡すテーブルを名前で特定します。

  • TABLE ( クエリ )

    query の結果を関数に渡します。

  • テーブル パーティション分割

    !["はい" のチェック マーク](../../_static/images/icons/check.png Databricks SQL 

    オプションとして、テーブル引数がパーティション分割されることを指定します。 指定しない場合、パーティション分割は Azure Databricks によって決定されます。

    • WITH SINGLE PARTITION

      テーブル引数はパーティション分割されません。

    • partition 式

      テーブル引数のパーティション分割方法を定義する 1 つ以上の式。 各式は、テーブル引数内に存在する列、リテラル、パラメーター、変数、決定論的関数で構成できます。

  • table-ordering

    !["はい" のチェック マーク](../../_static/images/icons/check.png Databricks SQL 

    オプションとして、テーブル引数の各パーティションの結果行を関数に渡す順序を指定します。

    既定では、順序は未定義です。

    • order by 式

      1 つ以上の式。 各式は、テーブル引数内に存在する列、リテラル、パラメーター、変数、決定論的関数で構成できます。

• namedParameter

  !["はい" のチェック マーク](../../_static/images/icons/check.png Databricks SQL 

  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

関連記事

• SQL 式
• 組み込み関数
• CREATE FUNCTION (SQL および Python)
• CREATE FUNCTION (外部)
• * (star) 句