Write a User Defined Function in C - Aster Execution Engine

Teradata Aster® Developer Guide

Product
Aster Execution Engine
Release Number
7.00.02
Published
July 2017
Language
English (United States)
Last Update
2018-04-13
dita:mapPath
xnl1494366523182.ditamap
dita:ditavalPath
Generic_no_ie_no_tempfilter.ditaval
dita:id
ffu1489104705746
lifecycle
previous
Product Category
Software

This section guides you through writing a simple user defined function. It assumes you have downloaded the C SDK (see Getting and Unpacking the SQL-MapReduce C SDK) and also have the proper setup for build tools (see Building C API Functions). You may want to follow one or more of the example functions provided in the SDK.

To write a user defined function in C or C++, you write C code that will build into a .so shared library:

  1. Headers to include: Import the needed headers from sqlmr/api/c/ (in the sqlmr-sdk/include directory). Most user defined C functions will include Core.h, FunctionModule.h, NativeValue.h, and RuntimeContract.h, and so on. Depending on the type of your user define C function, you may also include one of the following:
    • sqlmr/udf/api/c/ScalarFunction.h for a scalar function
    • sqlmr/udf/api/c/AggregatorFunction.h for an aggregate function
    • sqlmr/udf/api/c/DecomposableAggregatorFunction.h for a decomposable aggregate function
  2. Module Definition: Your code must contain one module definition for an Aster instance to identify the entry point of your function and the interface it implements. See Module Definition.
  3. Factory Method: Your code must implement a factory method or a "constructor" for an Aster instance to create an instance of your function for execution. In this factory method, you can check the number and data types of the input parameters given and set the data type of the output value. You can also create a custom context for the internal state of this function instance. See Factory Method with RuntimeContract and Custom Context.
  4. Processing Methods: Depending on the type of your user defined function, your code should implement a set of methods providing the processing logic of your function. See Processing Method for Scalar Functions, Processing Methods for Aggregate Functions, or Additional Processing Methods for Decomposable Aggregate Functions.
  5. Miscellaneous:
    • HelpInfo: HelpInfo enables you to add and compile with SQL-MapReduce function code and provides information on how to run the functions. See HelpInfo for User Defined Functions.
    • Handling arguments: If your user defined C function will take key-value arguments in the SQL command, use the facilities provided in ArgumentClause.h (SqlmrArgumentClauseH) to add argument clauses to your function. For an example of this, see sqlmr-sdk/example/c/repeat_input/repeat_input.c.
    • Helper files: An Aster instance allows you to install files on the cluster to act as user defined function helper files or to hold data that you do not wish to store in the database. If your user defined function will use or operate on an installed file, use the functions of InstalledFile.h (like sqlmr_if_getInstalledFiles and sqlmr_if_openForRead). For an example of this, see sqlmr-sdk/example/c/list_files/list_files.c.
    • Error handling: Handle errors and return error information using the methods of sqlmr-sdk/include/sqlmr/api/c/core/Error.h.
    • Memory Management: See Memory Management in C API Functions.