[
https://issues.apache.org/jira/browse/HAWQ-1216?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=15796695#comment-15796695
]
ASF GitHub Bot commented on HAWQ-1216:
--------------------------------------
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"?
> PL/Python doc page - validate and enhance info
> ----------------------------------------------
>
> Key: HAWQ-1216
> URL: https://issues.apache.org/jira/browse/HAWQ-1216
> Project: Apache HAWQ
> Issue Type: Improvement
> Components: Documentation
> Reporter: Lisa Owen
> Assignee: David Yozie
> Priority: Minor
>
> PL/Python docs section:
> - review and validate current content
> - update module installation instructions - need to be root to install
> modules to system python dirs
> - make sure examples run and are relevant
> - develop new examples as appropriate
--
This message was sent by Atlassian JIRA
(v6.3.4#6332)
