CREATE FUNCTION (TVF)

Syntax

CREATE [OR REPLACE] FUNCTION function_name ( [parameter_list] )
  RETURNS TABLE AS RETURN function_body ;

parameter_list:
  variable_name data_type [data_type_modifier] [, ...]

data_type_modifier:
  DEFAULT default_value | NOT NULL | NULL | COLLATE collation_name

Return Type

• return_type: A scalar value or a TABLE value. If a TABLE value, includes a list of <column name> <data_type> values such as TABLE(a TEXT, b INT).

Arguments

OR REPLACE

If specified, replaces a TVF if one already exists with the same name.

function_name

The name of the function. Function names must be unique within a database, and cannot be duplicates of names for other TVFs, tables, views, user-defined functions (UDFs), user-defined aggregate functions (UDAFs), or stored procedures.

You can also specify database_name and function_name together by replacing function_name with database_name.function_name instead of defaulting to the current context database. For example, you can write the following:

CREATE FUNCTION db.some_func(a int)
...

Table Valued Function names are case-sensitive. For details on case-sensitivity, refer to the Database Object Case-Sensitivity topic.

parameter_list

Input parameters are optional. Any number of input parameters can be specified, and each must be delimited by a comma (,). Each input parameter must be given a unique identifier name within the scope of the function.

The following example shows how to declare a single input parameter:

CREATE FUNCTION single_param_example(a INT) ...

The following example demonstrates how to declare more than one input parameter:

CREATE FUNCTION multi_param_example(a INT, b VARCHAR(255), c DECIMAL(19,4)) ...

Only scalar data types are allowed for TVF input parameters, and each valid type is enumerated in the syntax block above. Non-scalar types, such as ARRAY or RECORD, cannot be declared as input parameters for TVFs.

Default values can be specified for input parameters by using the DEFAULT constraint. Consider the following example:

CREATE FUNCTION default_example(a INT DEFAULT 5) ...

Input parameters can also specify data type modifiers, namely NOT NULL, NULL, and COLLATE. Consider the following example:

CREATE FUNCTION modifier_example(a TEXT NOT NULL COLLATE utf8_bin) ...

You can use parameters with any supported character sets using the following syntax.

CREATE FUNCTION function_name(product_id INT, feedback VARCHAR(20) COLLATE utf8_general_ci);
…

In a similar fashion, you can use variables with any supported character sets.

For more information, see Character Encoding.

data_type

Any scalar-valued data type as described in the Data Types topic. Non-scalar valued types are not allowed in TVFs, including ARRAY and RECORD types.

function_body

The function body of a TVF may contain any valid SELECT statement.

Remarks

Table-valued functions (TVFs) in SingleStoreDB provide a mechanism to return a result set from a single user-defined SELECT statement, much like a view. Unlike views, however, TVFs accept scalar-type input parameters that can be used inside the function body. Consider the following example TVF, which accepts a DECIMAL input type and returns the items in a store’s inventory that match the desired price:

CREATE FUNCTION inventory_with_price(price DECIMAL(19,4))
  RETURNS TABLE AS RETURN
    SELECT * FROM store_inventory WHERE item_price = price;

This TVF specifies an input parameter named price, which is used to query the store_inventory table and find all items of the specified price. The function is executed in the following way:

SELECT * FROM inventory_with_price(1.9900);

Once the inventory_with_price function has been created, it can be executed with different DECIMAL input values to query the store_inventory table in a dynamic, reusable manner.

TVFs can also reference other TVFs in the function body. When a referenced TVF is executed inside the function body of a TVF, the result set from the referenced TVF can be queried like a table. Consider the following example where tvf_2 references tvf_1:

CREATE FUNCTION tvf_1(a INT)
  RETURNS TABLE AS RETURN
    SELECT * FROM store_inventory
    LIMIT a;

CREATE FUNCTION tvf_2()
  RETURNS TABLE AS RETURN
    SELECT * FROM tvf_1(10)
    GROUP BY item_price
    ORDER BY item_price
    LIMIT 10;

In the example above, a table named store_inventory contains a item_price column. The tvf_1 function is referenced in tvf_2 and its logical result set is queried as a table type.

This command causes implicit commits. See COMMIT for more information.

Refer to the Permission Matrix for the required permission.

% cat userFile.sql

USE db1;
CREATE OR REPLACE FUNCTION tvf_2(num INT)
  RETURNS TABLE AS
  RETURN SELECT * FROM stock
  LIMIT num;
SELECT * FROM  tvf_2();

% singlestore < userFile.sql

MySQL Client Delimiters

When creating a TVF using a MySQL-compatible client connected to SingleStoreDB, you must change the client delimiter to ensure that the function definition is correctly passed to the server and then set it back to a semicolon after the alternate delimiter is no longer needed. See the MySQL Client Delimiters topic for details on MySQL client delimiters.

Security and Permissions

TVFs in SingleStoreDB use the Definer Security Model. The TVF’s definer must have the permissions to execute the SELECT statement that makes up the TVF’s function body. The invoker of a TVF must have EXECUTE permissions on the TVF. Also, the TVF’s definer must have EXECUTE permissions on any TVFs used in the function’s body.

Limitations

TVFs are limited in the following ways:

CREATE FUNCTION cross_database_invalid()
  RETURNS TABLE AS RETURN
    SELECT * FROM otherdb.other_tvf();

Related Topics

• DROP FUNCTION

• SHOW FUNCTIONS

• SHOW CREATE FUNCTION