函数调用

适用于： 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

  

  指定作为表的参数的参数。

  • TABLE ( table_name )

    标识按名称传递给函数的表。

  • TABLE ( query )

    将 query 的结果传递给函数。

  • 表分区

    

    （可选）指定表参数已分区。 如果未指定，则分区由 Azure Databricks 确定。

    • WITH SINGLE PARTITION

      表参数不分区。

    • partition_expr

      定义如何对表参数进行分区的一个或多个表达式。 每个表达式都可以由表参数、文本、参数、变量和确定性函数中的列组成。

  • table-ordering

    

    （可选）指定将表参数的每个分区的结果行传递到函数的顺序。

    默认情况下，顺序是未定义的。

    • order_by_expr

      一个或多个表达式。 每个表达式都可以由表参数、文本、参数、变量和确定性函数中的列组成。

• namedParameter

  

  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 表达式 (SQL expression)
• 内置函数
• CREATE FUNCTION（SQL 和 Python）
• CREATE FUNCTION（外部）
• * (star) 子句