## F.40. tablefunc

[F.40.1. Functions Provided](tablefunc.html#id-1.11.7.49.5)[F.40.2. Author](tablefunc.html#id-1.11.7.49.6)

[]()

 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](tablefunc.html#TABLEFUNC-FUNCTIONS) summarizes the functions provided by the `tablefunc` module.

**Table F.31. `tablefunc` Functions**

|                                                                                                                              Function<br/><br/> Description                                                                                                                              |
|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|                                                             `normal_rand` ( *`numvals`* `integer`, *`mean`* `float8`, *`stddev`* `float8` ) → `setof float8`<br/><br/> Produces a set of normally distributed random values.                                                             |
|                                        `crosstab` ( *`sql`* `text` ) → `setof record`<br/><br/> Produces a “pivot table” containing row names plus *`N`* value columns, where *`N`* is determined by the row type specified in the calling query.                                        |
|`crosstab*`N`*` ( *`sql`* `text` ) → `setof table_crosstab_*`N`*`<br/><br/> Produces a “pivot table” containing row names plus *`N`* value columns. `crosstab2`, `crosstab3`, and `crosstab4` are predefined, but you can create additional `crosstab*`N`*` functions as described below. |
|                                                          `crosstab` ( *`source_sql`* `text`, *`category_sql`* `text` ) → `setof record`<br/><br/> Produces a “pivot table” with the value columns specified by a second query.                                                           |
|                             `crosstab` ( *`sql`* `text`, *`N`* `integer` ) → `setof record`<br/><br/> Obsolete version of `crosstab(text)`. The parameter *`N`* is now ignored, since the number of value columns is always determined by the calling query.                             |
|[]() `connectby` ( *`relname`* `text`, *`keyid_fld`* `text`, *`parent_keyid_fld`* `text` [, *`orderby_fld`* `text` ], *`start_with`* `text`, *`max_depth`* `integer` [, *`branch_delim`* `text` ] ) → `setof record`<br/><br/> Produces a representation of a hierarchical tree structure.|

#### 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 one `text` parameter and returning `setof your_type_name`, but linking to the same underlying `crosstab` C function. For example, if your source data produces row names that are `text`, and values that are `float8`, 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

