Skip to content

Commit 85e0047

Browse files
tglsfdctglsfdc
committed
Improve documentation for \crosstabview.
Fix misleading syntax summary (there cannot be a space between colH and scolH). Provide a link from the existing crosstab() function's documentation to \crosstabview. Copy-edit the command's description. Christoph Berg and Tom Lane
1 parent cbb2a81 commit 85e0047

File tree

2 files changed

+51
-71
lines changed

2 files changed

+51
-71
lines changed

‎doc/src/sgml/ref/psql-ref.sgml‎

Lines changed: 43 additions & 71 deletions
Original file line numberDiff line numberDiff line change
@@ -989,106 +989,78 @@ testdb=>
989989
</listitem>
990990
</varlistentry>
991991

992-
<varlistentry>
992+
993+
<varlistentry id="APP-PSQL-meta-commands-crosstabview">
993994
<term><literal>\crosstabview [
994995
<replaceable class="parameter">colV</replaceable>
995-
<replaceable class="parameter">colH</replaceable>
996-
[:<replaceable class="parameter">scolH</replaceable>]
996+
<replaceable class="parameter">colH</replaceable>[:<replaceable class="parameter">scolH</replaceable>]
997997
[<replaceable class="parameter">colD</replaceable>]
998998
] </literal></term>
999999
<listitem>
10001000
<para>
1001-
Execute the current query buffer (like <literal>\g</literal>) and shows
1002-
the results inside a crosstab grid.
1001+
Executes the current query buffer (like <literal>\g</literal>) and
1002+
shows the results in a crosstab grid.
10031003
The query must return at least three columns.
1004-
The output column <replaceable class="parameter">colV</replaceable>
1005-
becomes a vertical header
1006-
and the output column <replaceable class="parameter">colH</replaceable>
1004+
The output column identified by <replaceable class="parameter">colV</>
1005+
becomes a vertical header and the output column identified by
1006+
<replaceable class="parameter">colH</replaceable>
10071007
becomes a horizontal header, optionally sorted by ranking data obtained
1008-
from <replaceable class="parameter">scolH</replaceable>.
1009-
<replaceable class="parameter">colD</replaceable>
1010-
is the output column to project into the grid. If this is not
1008+
from column <replaceable class="parameter">scolH</replaceable>.
1009+
<replaceable class="parameter">colD</replaceable> identifies
1010+
the output column to display within the grid.
1011+
If <replaceable class="parameter">colD</replaceable> is not
10111012
specified and there are exactly three columns in the result set,
1012-
the column that isn't
1013+
the column that is neither
10131014
<replaceable class="parameter">colV</replaceable> nor
10141015
<replaceable class="parameter">colH</replaceable>
1015-
is displayed; if there are more columns, an error is thrown.
1016+
is displayed; if there are more columns, an error is reported.
10161017
</para>
10171018

10181019
<para>
1019-
All columns can be refered to by their position (starting at 1), or by
1020-
their name. Normal case folding and quoting rules apply on column
1021-
names. By default,
1022-
<replaceable class="parameter">colV</replaceable> corresponds to column 1
1023-
and <replaceable class="parameter">colH</replaceable> to column 2.
1024-
A query having only one output column cannot be viewed in crosstab, and
1020+
Each column specification can be a column number (starting at 1) or
1021+
a column name. The usual SQL case folding and quoting rules apply to
1022+
column names. If omitted,
1023+
<replaceable class="parameter">colV</replaceable> is taken as column 1
1024+
and <replaceable class="parameter">colH</replaceable> as column 2.
10251025
<replaceable class="parameter">colH</replaceable> must differ from
10261026
<replaceable class="parameter">colV</replaceable>.
10271027
</para>
10281028

10291029
<para>
1030-
The vertical header, displayed as the leftmost column,
1031-
contains the deduplicated values found in
1032-
column <replaceable class="parameter">colV</replaceable>, in the same
1033-
order as in the query results.
1030+
The vertical header, displayed as the leftmost column, contains the
1031+
values found in column <replaceable class="parameter">colV</>, in the
1032+
same order as in the query results, but with duplicates removed.
10341033
</para>
10351034

10361035
<para>
1037-
The horizontal header, displayed as the first row,
1038-
contains the deduplicated values found in
1039-
column <replaceable class="parameter">colH</replaceable>, in
1040-
the order of appearance in the query results.
1041-
If specified, the optional <replaceable class="parameter">scolH</replaceable>
1042-
argument refers to a column whose values should be integer numbers
1043-
by which <replaceable class="parameter">colH</replaceable> will be sorted
1044-
to be positioned in the horizontal header.
1036+
The horizontal header, displayed as the first row, contains the values
1037+
found in column <replaceable class="parameter">colH</replaceable>,
1038+
with duplicates removed. By default, these appear in the same order
1039+
as in the query results. But if the
1040+
optional <replaceable class="parameter">scolH</> argument is given, it
1041+
identifies a column whose values must be integer numbers, and the
1042+
values from <replaceable class="parameter">colH</replaceable> will
1043+
appear in the horizontal header sorted according to the
1044+
corresponding <replaceable class="parameter">scolH</> values.
10451045
</para>
10461046

10471047
<para>
1048-
Inside the crosstab grid,
1049-
given a query output with <literal>N</literal> columns
1050-
(including <replaceable class="parameter">colV</replaceable> and
1051-
<replaceable class="parameter">colH</replaceable>),
1052-
for each distinct value <literal>x</literal> of
1053-
<replaceable class="parameter">colH</replaceable>
1054-
and each distinct value <literal>y</literal> of
1055-
<replaceable class="parameter">colV</replaceable>,
1056-
the contents of a cell located at the intersection
1057-
<literal>(x,y)</literal> is determined by these rules:
1058-
<itemizedlist>
1059-
<listitem>
1060-
<para>
1061-
if there is no corresponding row in the query results such that the
1062-
value for <replaceable class="parameter">colH</replaceable>
1063-
is <literal>x</literal> and the value
1064-
for <replaceable class="parameter">colV</replaceable>
1065-
is <literal>y</literal>, the cell is empty.
1066-
</para>
1067-
</listitem>
1068-
1069-
<listitem>
1070-
<para>
1071-
if there is exactly one row such that the value
1072-
for <replaceable class="parameter">colH</replaceable>
1073-
is <literal>x</literal> and the value
1074-
for <replaceable class="parameter">colV</replaceable>
1075-
is <literal>y</literal>, then the <literal>colD</literal> column
1076-
is displayed.
1048+
Inside the crosstab grid, for each distinct value <literal>x</literal>
1049+
of <replaceable class="parameter">colH</replaceable> and each distinct
1050+
value <literal>y</literal>
1051+
of <replaceable class="parameter">colV</replaceable>, the cell located
1052+
at the intersection <literal>(x,y)</literal> contains the value of
1053+
the <literal>colD</literal> column in the query result row for which
1054+
the value of <replaceable class="parameter">colH</replaceable>
1055+
is <literal>x</literal> and the value
1056+
of <replaceable class="parameter">colV</replaceable>
1057+
is <literal>y</>. If there is no such row, the cell is empty. If
1058+
there are multiple such rows, an error is reported.
10771059
</para>
10781060
</listitem>
1079-
1080-
<listitem>
1081-
<para>
1082-
if there are several such rows, an error is thrown.
1083-
</para>
1084-
</listitem>
1085-
1086-
</itemizedlist>
1087-
</para>
1088-
1089-
</listitem>
10901061
</varlistentry>
10911062

1063+
10921064
<varlistentry>
10931065
<term><literal>\d[S+] [ <link linkend="APP-PSQL-patterns"><replaceable class="parameter">pattern</replaceable></link> ]</literal></term>
10941066

‎doc/src/sgml/tablefunc.sgml‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -293,6 +293,14 @@ AS ct(row_name text, category_1 text, category_2 text, category_3 text);
293293
required <literal>FROM</> clause in a view definition.
294294
</para>
295295

296+
<note>
297+
<para>
298+
See also the <command><link linkend="APP-PSQL-meta-commands-crosstabview">\crosstabview</link></command>
299+
command in <application>psql</>, which provides functionality similar
300+
to <function>crosstab()</>.
301+
</para>
302+
</note>
303+
296304
</sect3>
297305

298306
<sect3>

0 commit comments

Comments
 (0)