From 504c662be21dc344a161b81a9c627a8f6d7861cd Mon Sep 17 00:00:00 2001 From: Lisa Owen Date: Wed, 5 Oct 2016 14:33:36 -0700 Subject: [PATCH 1/5] add file discussing hawq built-in languages --- plext/builtin_langs.html.md.erb | 104 ++++++++++++++++++++++++++++++++ 1 file changed, 104 insertions(+) create mode 100644 plext/builtin_langs.html.md.erb diff --git a/plext/builtin_langs.html.md.erb b/plext/builtin_langs.html.md.erb new file mode 100644 index 0000000..8b408a9 --- /dev/null +++ b/plext/builtin_langs.html.md.erb @@ -0,0 +1,104 @@ +--- +title: 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, internal, and C language user-defined functions is enabled by default for all HAWQ databases. + +## SQL + +SQL functions execute an arbitrary list of SQL statements. The SQL statements in the body of an 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 an SQL function to count the number of rows of the database named `orders`: + +``` sql +gpadmin=# CREATE FUNCTION count_orders() RETURNS bigint AS $$ + SELECT count(*) FROM orders; +$$ LANGUAGE SQL; +CREATE FUNCTION +gpadmin=# select count_orders(); + my_count +---------- + 830513 +(1 row) +``` + +For additional information on creating SQL functions, refer to [Query Language (SQL) Functions](https://www.postgresql.org/docs/8.2/static/xfunc-sql.html) in the PostgreSQL documentation. + +## Internal + +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. + +While users cannot define new internal functions, they can create aliases for existing internal functions. + +The following example creates a new function named `to_upper` that will be an alias for the `upper` internal HAWQ function: + + +``` sql +gpadmin=# CREATE FUNCTION to_upper (text) RETURNS text AS 'upper' + LANGUAGE internal STRICT; +CREATE FUNCTION +gpadmin=# SELECT to_upper('change me'); + to_upper +----------- + CHANGE ME +(1 row) + +``` + +For more information on aliasing internal functions, refer to [Internal Functions](https://www.postgresql.org/docs/8.2/static/xfunc-internal.html) in the PostgreSQL documentation. + +## C + +User-defined functions written in C must be compiled into shared libraries to be loaded by the HAWQ server 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 HAWQ PostgreSQL library directory (obtained via the `pg_config --pkglibdir` command), the `dynamic_library_path` configuration value, and the current working directory, in that order. + +Example: + +``` c +#include "postgres.h" +#include "fmgr.h" + +#ifdef PG_MODULE_MAGIC +PG_MODULE_MAGIC; +#endif + +PG_FUNCTION_INFO_V1(double_it); + +Datum +double_it(PG_FUNCTION_ARGS) +{ + int32 arg = PG_GETARG_INT32(0); + + PG_RETURN_INT64(arg + arg); +} +``` + +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: + +``` sql +gpadmin=# CREATE FUNCTION double_it(integer) RETURNS integer + AS '/share/libs/libdoubleit', 'double_it' + LANGUAGE C STRICT; +CREATE FUNCTION +gpadmin=# SELECT double_it(27); + double_it +----------- + 54 +(1 row) + +``` + +The shared library `.so` extension may be omitted. + +For additional information on using the C language to create functions, refer to [C-Language Functions](https://www.postgresql.org/docs/8.2/static/xfunc-c.html) in the PostgreSQL documentation. + From 8e27e9093f1d27277d676386144ee895ad004f86 Mon Sep 17 00:00:00 2001 From: Lisa Owen Date: Wed, 5 Oct 2016 14:34:36 -0700 Subject: [PATCH 2/5] include built-in languages in PL lang landing page --- plext/UsingProceduralLanguages.html.md.erb | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/plext/UsingProceduralLanguages.html.md.erb b/plext/UsingProceduralLanguages.html.md.erb index 3ffba2c..c920486 100644 --- a/plext/UsingProceduralLanguages.html.md.erb +++ b/plext/UsingProceduralLanguages.html.md.erb @@ -1,13 +1,16 @@ --- -title: Using Procedural Languages and Extensions in HAWQ +title: Using Languages and Extensions in HAWQ --- -HAWQ allows user-defined functions to be written in other languages besides SQL and C. These other languages are generically called *procedural languages* (PLs). +HAWQ supports user-defined functions created with the SQL and C built-in languages, including supporting user-defined aliases for internal functions. + +HAWQ also allows user-defined functions to be written in languages other than SQL and C. These other languages are generically called *procedural languages* (PLs). For a function written in a procedural language, the database server has no built-in knowledge about how to interpret the function's source text. Instead, the task is passed to a special handler that knows the details of the language. The handler could either do all the work of parsing, syntax analysis, execution, and so on itself, or it could serve as "glue" between HAWQ and an existing implementation of a programming language. The handler itself is a C language function compiled into a shared object and loaded on demand, just like any other C function. This chapter describes the following: +- Using HAWQ Built-In Languages - Using PL/Java - Using PL/Perl - Using PL/pgSQL From bd85fdbc31cb463855c2606fde48d803dccb3de2 Mon Sep 17 00:00:00 2001 From: Lisa Owen Date: Wed, 5 Oct 2016 14:47:11 -0700 Subject: [PATCH 3/5] c user-defined function example - add _c to function name to avoid confusion --- plext/builtin_langs.html.md.erb | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/plext/builtin_langs.html.md.erb b/plext/builtin_langs.html.md.erb index 8b408a9..761a1d8 100644 --- a/plext/builtin_langs.html.md.erb +++ b/plext/builtin_langs.html.md.erb @@ -86,11 +86,11 @@ double_it(PG_FUNCTION_ARGS) 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: ``` sql -gpadmin=# CREATE FUNCTION double_it(integer) RETURNS integer +gpadmin=# CREATE FUNCTION double_it_c(integer) RETURNS integer AS '/share/libs/libdoubleit', 'double_it' LANGUAGE C STRICT; CREATE FUNCTION -gpadmin=# SELECT double_it(27); +gpadmin=# SELECT double_it_c(27); double_it ----------- 54 From 1332870d01d2f8da2f8284ac167253d7005c6dfd Mon Sep 17 00:00:00 2001 From: Lisa Owen Date: Mon, 10 Oct 2016 15:24:20 -0700 Subject: [PATCH 4/5] builtin langs - clarify and add some links --- plext/UsingProceduralLanguages.html.md.erb | 6 +++--- plext/builtin_langs.html.md.erb | 22 ++++++++++++++-------- 2 files changed, 17 insertions(+), 11 deletions(-) diff --git a/plext/UsingProceduralLanguages.html.md.erb b/plext/UsingProceduralLanguages.html.md.erb index c920486..ea23982 100644 --- a/plext/UsingProceduralLanguages.html.md.erb +++ b/plext/UsingProceduralLanguages.html.md.erb @@ -4,11 +4,11 @@ title: Using Languages and Extensions in HAWQ HAWQ supports user-defined functions created with the SQL and C built-in languages, including supporting user-defined aliases for internal functions. -HAWQ also allows user-defined functions to be written in languages other than SQL and C. These other languages are generically called *procedural languages* (PLs). +HAWQ also supports user-defined functions written in languages other than SQL and C. These other languages are generically called *procedural languages* (PLs) and are extensions to the core HAWQ functionality. HAWQ specifically supports the PL/Java, PL/Perl, PL/pgSQL, PL/Python, and PL/R procedural languages. -For a function written in a procedural language, the database server has no built-in knowledge about how to interpret the function's source text. Instead, the task is passed to a special handler that knows the details of the language. The handler could either do all the work of parsing, syntax analysis, execution, and so on itself, or it could serve as "glue" between HAWQ and an existing implementation of a programming language. The handler itself is a C language function compiled into a shared object and loaded on demand, just like any other C function. +HAWQ additionally provides the `pgcrypto` extension for password hashing and data encryption. -This chapter describes the following: +This chapter describes these languages and extensions: - Using HAWQ Built-In Languages - Using PL/Java diff --git a/plext/builtin_langs.html.md.erb b/plext/builtin_langs.html.md.erb index 761a1d8..a630732 100644 --- a/plext/builtin_langs.html.md.erb +++ b/plext/builtin_langs.html.md.erb @@ -13,7 +13,7 @@ Support for SQL, internal, and C language user-defined functions is enabled by d ## SQL -SQL functions execute an arbitrary list of SQL statements. The SQL statements in the body of an 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. +SQL functions execute an arbitrary list of SQL statements. The SQL statements in the body of an SQL function must be separated by semicolons. The final statement in a non-void-returning SQL function must be a [SELECT](../reference/sql/SELECT.html) 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 an SQL function to count the number of rows of the database named `orders`: @@ -33,19 +33,19 @@ For additional information on creating SQL functions, refer to [Query Language ( ## Internal -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. +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](../query/functions-operators.html#topic29) for detailed information on HAWQ internal functions. While users cannot define new internal functions, they can create aliases for existing internal functions. -The following example creates a new function named `to_upper` that will be an alias for the `upper` internal HAWQ function: +The following example creates a new function named `all_caps` that will be defined as an alias for the `upper` HAWQ internal function: ``` sql -gpadmin=# CREATE FUNCTION to_upper (text) RETURNS text AS 'upper' +gpadmin=# CREATE FUNCTION all_caps (text) RETURNS text AS 'upper' LANGUAGE internal STRICT; CREATE FUNCTION -gpadmin=# SELECT to_upper('change me'); - to_upper +gpadmin=# SELECT all_caps('change me'); + all_caps ----------- CHANGE ME (1 row) @@ -58,9 +58,15 @@ For more information on aliasing internal functions, refer to [Internal Function User-defined functions written in C must be compiled into shared libraries to be loaded by the HAWQ server 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. +The [CREATE FUNCTION](../reference/sql/CREATE-FUNCTION.html) 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 HAWQ PostgreSQL library directory (obtained via the `pg_config --pkglibdir` command), the `dynamic_library_path` configuration value, and the current working directory, in that order. +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: From 168cb22a0cc719441a46c98ff3c505cb88bffd2f Mon Sep 17 00:00:00 2001 From: Lisa Owen Date: Wed, 19 Oct 2016 09:08:30 -0700 Subject: [PATCH 5/5] make david's requested changes --- plext/UsingProceduralLanguages.html.md.erb | 2 +- plext/builtin_langs.html.md.erb | 26 +++++++++++----------- 2 files changed, 14 insertions(+), 14 deletions(-) diff --git a/plext/UsingProceduralLanguages.html.md.erb b/plext/UsingProceduralLanguages.html.md.erb index ea23982..bef1b93 100644 --- a/plext/UsingProceduralLanguages.html.md.erb +++ b/plext/UsingProceduralLanguages.html.md.erb @@ -2,7 +2,7 @@ title: Using Languages and Extensions in HAWQ --- -HAWQ supports user-defined functions created with the SQL and C built-in languages, including supporting user-defined aliases for internal functions. +HAWQ supports user-defined functions that are created with the SQL and C built-in languages, and also supports user-defined aliases for internal functions. HAWQ also supports user-defined functions written in languages other than SQL and C. These other languages are generically called *procedural languages* (PLs) and are extensions to the core HAWQ functionality. HAWQ specifically supports the PL/Java, PL/Perl, PL/pgSQL, PL/Python, and PL/R procedural languages. diff --git a/plext/builtin_langs.html.md.erb b/plext/builtin_langs.html.md.erb index a630732..931f2f2 100644 --- a/plext/builtin_langs.html.md.erb +++ b/plext/builtin_langs.html.md.erb @@ -9,13 +9,13 @@ HAWQ supports user-defined functions created with the SQL and C built-in languag ## Enabling Built-in Language Support -Support for SQL, internal, and C language user-defined functions is enabled by default for all HAWQ databases. +Support for SQL and C language user-defined functions and aliasing of internal functions is enabled by default for all HAWQ databases. -## SQL +## Defining SQL Functions -SQL functions execute an arbitrary list of SQL statements. The SQL statements in the body of an SQL function must be separated by semicolons. The final statement in a non-void-returning SQL function must be a [SELECT](../reference/sql/SELECT.html) 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. +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](../reference/sql/SELECT.html) 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 an SQL function to count the number of rows of the database named `orders`: +The following example creates and calls a SQL function to count the number of rows of the database named `orders`: ``` sql gpadmin=# CREATE FUNCTION count_orders() RETURNS bigint AS $$ @@ -29,15 +29,15 @@ gpadmin=# select count_orders(); (1 row) ``` -For additional information on creating SQL functions, refer to [Query Language (SQL) Functions](https://www.postgresql.org/docs/8.2/static/xfunc-sql.html) in the PostgreSQL documentation. +For additional information about creating SQL functions, refer to [Query Language (SQL) Functions](https://www.postgresql.org/docs/8.2/static/xfunc-sql.html) in the PostgreSQL documentation. -## Internal +## 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](../query/functions-operators.html#topic29) for detailed information on HAWQ 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](../query/functions-operators.html#topic29) for detailed information about HAWQ internal functions. -While users cannot define new internal functions, they can create aliases for existing 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 will be defined as an alias for the `upper` HAWQ internal function: +The following example creates a new function named `all_caps` that is an alias for the `upper` HAWQ internal function: ``` sql @@ -52,11 +52,11 @@ gpadmin=# SELECT all_caps('change me'); ``` -For more information on aliasing internal functions, refer to [Internal Functions](https://www.postgresql.org/docs/8.2/static/xfunc-internal.html) in the PostgreSQL documentation. +For more information about aliasing internal functions, refer to [Internal Functions](https://www.postgresql.org/docs/8.2/static/xfunc-internal.html) in the PostgreSQL documentation. -## C +## Defining C Functions -User-defined functions written in C must be compiled into shared libraries to be loaded by the HAWQ server on demand. This dynamic loading distinguishes C language functions from internal functions that are written in C. +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](../reference/sql/CREATE-FUNCTION.html) call for a user-defined C function must include both the name of the shared library and the name of the function. @@ -106,5 +106,5 @@ gpadmin=# SELECT double_it_c(27); The shared library `.so` extension may be omitted. -For additional information on using the C language to create functions, refer to [C-Language Functions](https://www.postgresql.org/docs/8.2/static/xfunc-c.html) in the PostgreSQL documentation. +For additional information about using the C language to create functions, refer to [C-Language Functions](https://www.postgresql.org/docs/8.2/static/xfunc-c.html) in the PostgreSQL documentation.