Github user dyozie commented on a diff in the pull request:
https://github.com/apache/incubator-hawq-docs/pull/77#discussion_r94512401
--- Diff: plext/using_plpython.html.md.erb ---
@@ -2,374 +2,608 @@
title: Using PL/Python in HAWQ
---
-This section contains an overview of the HAWQ PL/Python language extension.
+This section provides an overview of the HAWQ PL/Python procedural
language extension.
## <a id="abouthawqplpython"></a>About HAWQ PL/Python
-PL/Python is a loadable procedural language. With the HAWQ PL/Python
extension, you can write HAWQ user-defined functions in Python that take
advantage of Python features and modules to quickly build robust database
applications.
+PL/Python is embedded in your HAWQ product distribution or within your
HAWQ build if you chose to enable it as a build option.
+
+With the HAWQ PL/Python extension, you can write user-defined functions in
Python that take advantage of Python features and modules, enabling you to
quickly build robust HAWQ database applications.
HAWQ uses the system Python installation.
### <a id="hawqlimitations"></a>HAWQ PL/Python Limitations
-- HAWQ does not support PL/Python triggers.
+- HAWQ does not support PL/Python trigger functions.
- PL/Python is available only as a HAWQ untrusted language.
## <a id="enableplpython"></a>Enabling and Removing PL/Python Support
-To use PL/Python in HAWQ, you must either use a pre-compiled version of
HAWQ that includes PL/Python or specify PL/Python as a build option when
compiling HAWQ.
+To use PL/Python in HAWQ, you must either install a binary version of HAWQ
that includes PL/Python or specify PL/Python as a build option when compiling
HAWQ from source.
+
+PL/Python user-defined functions (UDFs) are registered at the database
level. To create and run a PL/Python UDF on a database, you must register the
PL/Python language with the database.
+
+On every database to which you want to install and enable PL/Python:
+
+1. Connect to the database using the `psql` client:
+
+ ``` shell
+ $ psql -d <dbname>
+ ```
+
+ Replace \<dbname\> with the name of the target database.
+
+2. Run the following SQL command to register the PL/Python procedural
language; you must be a database superuser to register new languages:
+
+ ``` sql
+ dbname=# CREATE LANGUAGE plpythonu;
+ ```
-To create and run a PL/Python user-defined function (UDF) in a database,
you must register the PL/Python language with the database. On every database
where you want to install and enable PL/Python, connect to the database using
the `psql` client.
+ **Note**: `plpythonu` is installed as an *untrusted* language; it
offers no way of restricting what you can program in UDFs created with the
language.
-```shell
-$ psql -d <dbname>
+To remove support for `plpythonu` from a database, run the following SQL
command; you must be a database superuser to remove a registered procedural
language:
+
+``` sql
+dbname=# DROP LANGUAGE plpythonu;
```
-Replace \<dbname\> with the name of the target database.
+## <a id="developfunctions"></a>Developing Functions with PL/Python
+
+PL/Python functions are defined using the standard SQL [CREATE
FUNCTION](../reference/sql/CREATE-FUNCTION.html) syntax.
+
+The body of a PL/Python user-defined function is a Python script. When the
function is called, its arguments are passed as elements of the array `args[]`.
You can also pass named arguments as ordinary variables to the Python script.
-Then, run the following SQL command:
+PL/Python function results are returned with a `return` statement, or a
`yield` statement in the case of a result-set statement.
-```shell
-psql# CREATE LANGUAGE plpythonu;
+The following PL/Python function computes and returns the maximum of two
integers:
+
+``` sql
+=> CREATE FUNCTION mypymax (a integer, b integer)
+ RETURNS integer
+ AS $$
+ if (a is None) or (b is None):
+ return None
+ if a > b:
+ return a
+ return b
+ $$ LANGUAGE plpythonu;
```
-Note that `plpythonu` is installed as an âuntrustedâ language, meaning
it does not offer any way of restricting what users can do in it.
+To execute the `mypymax` function:
-To remove support for `plpythonu` from a database, run the following SQL
command:
+``` sql
+=> SELECT mypymax(5, 7);
+ mypymax
+---------
+ 7
+(1 row)
+```
+
+Adding the `STRICT` keyword to the `LANGUAGE` subclause instructs HAWQ to
return null when any of the input arguments are null. When created as `STRICT`,
the function itself need not perform null checks.
-```shell
-psql# DROP LANGUAGE plpythonu;
+The following example uses an unnamed argument, the built-in Python
`max()` function, and the `STRICT` keyword to create a UDF named `mypymax2`:
+
+``` sql
+=> CREATE FUNCTION mypymax2 (a integer, integer)
+ RETURNS integer AS $$
+ return max(a, args[0])
+ $$ LANGUAGE plpythonu STRICT;
+=> SELECT mypymax(5, 3);
+ mypymax2
+----------
+ 5
+(1 row)
+=> SELECT mypymax(5, null);
+ mypymax2
+----------
+
+(1 row)
```
-## <a id="developfunctions"></a>Developing Functions with PL/Python
+## <a id="example_createtbl"></a>Preparing For Exercises
--- End diff --
Maybe change the title to "Preparing Sample Data" or "Creating the Sample
Data"?
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at [email protected] or file a JIRA ticket
with INFRA.
---
