# F.40. tablefunc
F.40.1. Functions ProvidedF.40.2. Author
The tablefunc
module includes various functions that return tables (that is, multiple rows). These functions are useful both in their own right and as examples of how to write C functions that return multiple rows.
This module is considered “trusted”, that is, it can be installed by non-superusers who have CREATE
privilege on the current database.
# F.40.1. Functions Provided
Table F.31 summarizes the functions provided by the tablefunc
module.
Table F.31. tablefunc
Functions
# F.40.1.1. normal_rand
normal_rand(int numvals, float8 mean, float8 stddev) returns setof float8
normal_rand
produces a set of normally distributed random values (Gaussian distribution).
numvals
is the number of values to be returned from the function. mean
is the mean of the normal distribution of values and stddev
is the standard deviation of the normal distribution of values.
For example, this call requests 1000 values with a mean of 5 and a standard deviation of 3:
test=# SELECT * FROM normal_rand(1000, 5, 3);
normal_rand
#### F.40.1.2. `crosstab(text)`
[]()
crosstab(text sql) crosstab(text sql, int N)
The `crosstab` function is used to produce “pivot” displays, wherein data is listed across the page rather than down. For example, we might have data like
row1 val11 row1 val12 row1 val13 ... row2 val21 row2 val22 row2 val23 ...
which we wish to display like
row1 val11 val12 val13 ... row2 val21 val22 val23 ... ...
The `crosstab` function takes a text parameter that is an SQL query producing raw data formatted in the first way, and produces a table formatted in the second way.
The *`sql`* parameter is an SQL statement that produces the source set of data. This statement must return one `row_name` column, one `category` column, and one `value` column. *`N`* is an obsolete parameter, ignored if supplied (formerly this had to match the number of output value columns, but now that is determined by the calling query).
For example, the provided query might produce a set something like:
row_name cat value
# Note
See also the [\crosstabview](app-psql.html#APP-PSQL-META-COMMANDS-CROSSTABVIEW)
command in psql, which provides functionality similar to crosstab()
.
# F.40.1.3. crosstab*
N*(text)
crosstabN(text sql)
The crosstab*
N*
functions are examples of how to set up custom wrappers for the general crosstab
function, so that you need not write out column names and types in the calling SELECT
query. The tablefunc
module includes crosstab2
, crosstab3
, and crosstab4
, whose output row types are defined as
CREATE TYPE tablefunc_crosstab_N AS (
row_name TEXT,
category_1 TEXT,
category_2 TEXT,
.
.
.
category_N TEXT
);
Thus, these functions can be used directly when the input query produces row_name
and value
columns of type text
, and you want 2, 3, or 4 output values columns. In all other ways they behave exactly as described above for the general crosstab
function.
For instance, the example given in the previous section would also work as
SELECT *
FROM crosstab3(
'select rowid, attribute, value
from ct
where attribute = ''att2'' or attribute = ''att3''
order by 1,2');
These functions are provided mostly for illustration purposes. You can create your own return types and functions based on the underlying crosstab()
function. There are two ways to do it:
Create a composite type describing the desired output columns, similar to the examples in
contrib/tablefunc/tablefunc--1.0.sql
. Then define a unique function name accepting onetext
parameter and returningsetof your_type_name
, but linking to the same underlyingcrosstab
C function. For example, if your source data produces row names that aretext
, and values that arefloat8
, and you want 5 value columns:CREATE TYPE my_crosstab_float8_5_cols AS ( my_row_name text, my_category_1 float8, my_category_2 float8, my_category_3 float8, my_category_4 float8, my_category_5 float8 ); CREATE OR REPLACE FUNCTION crosstab_float8_5_cols(text) RETURNS setof my_crosstab_float8_5_cols AS '$libdir/tablefunc','crosstab' LANGUAGE C STABLE STRICT;
Use
OUT
parameters to define the return type implicitly. The same example could also be done this way:CREATE OR REPLACE FUNCTION crosstab_float8_5_cols( IN text, OUT my_row_name text, OUT my_category_1 float8, OUT my_category_2 float8, OUT my_category_3 float8, OUT my_category_4 float8, OUT my_category_5 float8) RETURNS setof record AS '$libdir/tablefunc','crosstab' LANGUAGE C STABLE STRICT;
# F.40.1.4. crosstab(text, text)
crosstab(text source_sql, text category_sql)
The main limitation of the single-parameter form of crosstab
is that it treats all values in a group alike, inserting each value into the first available column. If you want the value columns to correspond to specific categories of data, and some groups might not have data for some of the categories, that doesn't work well. The two-parameter form of crosstab
handles this case by providing an explicit list of the categories corresponding to the output columns.
source_sql
is an SQL statement that produces the source set of data. This statement must return one row_name
column, one category
column, and one value
column. It may also have one or more “extra” columns. The row_name
column must be first. The category
and value
columns must be the last two columns, in that order. Any columns between row_name
and category
are treated as “extra”. The “extra” columns are expected to be the same for all rows with the same row_name
value.
For example, source_sql
might produce a set something like:
SELECT row_name, extra_col, cat, value FROM foo ORDER BY 1;
row_name extra_col cat value
#### F.40.1.5. `connectby`
[]()
connectby(text relname, text keyid_fld, text parent_keyid_fld [, text orderby_fld ], text start_with, int max_depth [, text branch_delim ])
The `connectby` function produces a display of hierarchical data that is stored in a table. The table must have a key field that uniquely identifies rows, and a parent-key field that references the parent (if any) of each row. `connectby` can display the sub-tree descending from any row.
[Table F.32](tablefunc.html#TABLEFUNC-CONNECTBY-PARAMETERS) explains the parameters.
**Table F.32. `connectby` Parameters**
| Parameter | Description |
|--------------------|--------------------------------------------------------|
| *`relname`* | Name of the source relation |
| *`keyid_fld`* | Name of the key field |
|*`parent_keyid_fld`*| Name of the parent-key field |
| *`orderby_fld`* | Name of the field to order siblings by (optional) |
| *`start_with`* | Key value of the row to start at |
| *`max_depth`* |Maximum depth to descend to, or zero for unlimited depth|
| *`branch_delim`* |String to separate keys with in branch output (optional)|
The key and parent-key fields can be any data type, but they must be the same type. Note that the *`start_with`* value must be entered as a text string, regardless of the type of the key field.
The `connectby` function is declared to return `setof record`, so the actual names and types of the output columns must be defined in the `FROM` clause of the calling `SELECT` statement, for example:
SELECT * FROM connectby('connectby_tree', 'keyid', 'parent_keyid', 'pos', 'row2', 0, '~') AS t(keyid text, parent_keyid text, level int, branch text, pos int);
The first two output columns are used for the current row's key and its parent row's key; they must match the type of the table's key field. The third output column is the depth in the tree and must be of type `integer`. If a *`branch_delim`* parameter was given, the next output column is the branch display and must be of type `text`. Finally, if an *`orderby_fld`* parameter was given, the last output column is a serial number, and must be of type `integer`.
The “branch” output column shows the path of keys taken to reach the current row. The keys are separated by the specified *`branch_delim`* string. If no branch display is wanted, omit both the *`branch_delim`* parameter and the branch column in the output column list.
If the ordering of siblings of the same parent is important, include the *`orderby_fld`* parameter to specify which field to order siblings by. This field can be of any sortable data type. The output column list must include a final integer serial-number column, if and only if *`orderby_fld`* is specified.
The parameters representing table and field names are copied as-is into the SQL queries that `connectby` generates internally. Therefore, include double quotes if the names are mixed-case or contain special characters. You may also need to schema-qualify the table name.
In large tables, performance will be poor unless there is an index on the parent-key field.
It is important that the *`branch_delim`* string not appear in any key values, else `connectby` may incorrectly report an infinite-recursion error. Note that if *`branch_delim`* is not provided, a default value of `~` is used for recursion detection purposes.
Here is an example:
CREATE TABLE connectby_tree(keyid text, parent_keyid text, pos int);
INSERT INTO connectby_tree VALUES('row1',NULL, 0); INSERT INTO connectby_tree VALUES('row2','row1', 0); INSERT INTO connectby_tree VALUES('row3','row1', 0); INSERT INTO connectby_tree VALUES('row4','row2', 1); INSERT INTO connectby_tree VALUES('row5','row2', 0); INSERT INTO connectby_tree VALUES('row6','row4', 0); INSERT INTO connectby_tree VALUES('row7','row3', 0); INSERT INTO connectby_tree VALUES('row8','row6', 0); INSERT INTO connectby_tree VALUES('row9','row5', 0);
-- with branch, without orderby_fld (order of results is not guaranteed) SELECT * FROM connectby('connectby_tree', 'keyid', 'parent_keyid', 'row2', 0, '~') AS t(keyid text, parent_keyid text, level int, branch text); keyid | parent_keyid | level | branch
# F.40.2. Author
Joe Conway