Using HAWQ Built-In Languages

This section provides an introduction to using the HAWQ built-in languages.

HAWQ supports user-defined functions created with the SQL and C built-in languages. HAWQ also supports user-defined aliases for internal functions.

Enabling Built-in Language Support

Support for SQL and C language user-defined functions and aliasing of internal functions is enabled by default for all HAWQ databases.

Defining SQL Functions

SQL functions execute an arbitrary list of SQL statements. The SQL statements in the body of a SQL function must be separated by semicolons. The final statement in a non-void-returning SQL function must be a SELECT that returns data of the type specified by the function’s return type. The function will return a single or set of rows corresponding to this last SQL query.

The following example creates and calls a SQL function to count the number of rows of the table named orders:

  1. gpadmin=# CREATE FUNCTION count_orders() RETURNS bigint AS $$
  2.  SELECT count(*) FROM orders;
  3. $$ LANGUAGE SQL;
  4. CREATE FUNCTION
  5. gpadmin=# SELECT count_orders();
  6.  my_count 
  7. ----------
  8.    830513
  9. (1 row)

For additional information about creating SQL functions, refer to Query Language (SQL) Functions in the PostgreSQL documentation.

Aliasing Internal Functions

Many HAWQ internal functions are written in C. These functions are declared during initialization of the database cluster and statically linked to the HAWQ server. See Built-in Functions and Operators for detailed information about HAWQ internal functions.

You cannot define new internal functions, but you can create aliases for existing internal functions.

The following example creates a new function named all_caps that is an alias for the upper HAWQ internal function:

  1. gpadmin=# CREATE FUNCTION all_caps (text) RETURNS text AS 'upper'
  2.             LANGUAGE internal STRICT;
  3. CREATE FUNCTION
  4. gpadmin=# SELECT all_caps('change me');
  5.  all_caps  
  6. -----------
  7.  CHANGE ME
  8. (1 row)

For more information about aliasing internal functions, refer to Internal Functions in the PostgreSQL documentation.

Defining C Functions

You must compile user-defined functions written in C into shared libraries so that the HAWQ server can load them on demand. This dynamic loading distinguishes C language functions from internal functions that are written in C.

The CREATE FUNCTION call for a user-defined C function must include both the name of the shared library and the name of the function.

If an absolute path to the shared library is not provided, an attempt is made to locate the library relative to the:

  1. HAWQ PostgreSQL library directory (obtained via the pg_config --pkglibdir command)
  2. dynamic_library_path configuration value
  3. current working directory

in that order.

Example:

  1. #include "postgres.h"
  2. #include "fmgr.h"
  4. #ifdef PG_MODULE_MAGIC
  5. PG_MODULE_MAGIC;
  6. #endif
  8. PG_FUNCTION_INFO_V1(double_it);
  10. Datum
  11. double_it(PG_FUNCTION_ARGS)
  12. {
  13.     int32   arg = PG_GETARG_INT32(0);
  15.     PG_RETURN_INT64(arg + arg);
  16. }

If the above function is compiled into a shared object named libdoubleit.so located in /share/libs, you would register and invoke the function with HAWQ as follows:

  1. gpadmin=# CREATE FUNCTION double_it_c(integer) RETURNS integer
  2.             AS '/share/libs/libdoubleit', 'double_it'
  3.             LANGUAGE C STRICT;
  4. CREATE FUNCTION
  5. gpadmin=# SELECT double_it_c(27);
  6.  double_it 
  7. -----------
  8.         54
  9. (1 row)

The shared library .so extension may be omitted.

For additional information about using the C language to create functions, refer to C-Language Functions in the PostgreSQL documentation.