From: Tom Lane <tgl@sss.pgh.pa.us>
Date: Wed, 13 Apr 2016 15:49:47 +0000 (-0400)
Subject: Improve documentation for \crosstabview.
X-Git-Tag: REL9_6_BETA1~173
X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=85e004707715f5ee7a6bfc3d03d0fbc837fb2432;p=postgresql
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
---
diff --git a/doc/src/sgml/ref/psql-ref.sgml b/doc/src/sgml/ref/psql-ref.sgml
index 1f07956d42..b2b2adc3b6 100644
--- a/doc/src/sgml/ref/psql-ref.sgml
+++ b/doc/src/sgml/ref/psql-ref.sgml
@@ -989,106 +989,78 @@ testdb=>
</listitem>
</varlistentry>
- <varlistentry>
+
+ <varlistentry id="APP-PSQL-meta-commands-crosstabview">
<term><literal>\crosstabview [
<replaceable class="parameter">colV</replaceable>
- <replaceable class="parameter">colH</replaceable>
- [:<replaceable class="parameter">scolH</replaceable>]
+ <replaceable class="parameter">colH</replaceable>[:<replaceable class="parameter">scolH</replaceable>]
[<replaceable class="parameter">colD</replaceable>]
] </literal></term>
<listitem>
<para>
- Execute the current query buffer (like <literal>\g</literal>) and shows
- the results inside a crosstab grid.
+ Executes the current query buffer (like <literal>\g</literal>) and
+ shows the results in a crosstab grid.
The query must return at least three columns.
- The output column <replaceable class="parameter">colV</replaceable>
- becomes a vertical header
- and the output column <replaceable class="parameter">colH</replaceable>
+ The output column identified by <replaceable class="parameter">colV</>
+ becomes a vertical header and the output column identified by
+ <replaceable class="parameter">colH</replaceable>
becomes a horizontal header, optionally sorted by ranking data obtained
- from <replaceable class="parameter">scolH</replaceable>.
- <replaceable class="parameter">colD</replaceable>
- is the output column to project into the grid. If this is not
+ from column <replaceable class="parameter">scolH</replaceable>.
+ <replaceable class="parameter">colD</replaceable> identifies
+ the output column to display within the grid.
+ If <replaceable class="parameter">colD</replaceable> is not
specified and there are exactly three columns in the result set,
- the column that isn't
+ the column that is neither
<replaceable class="parameter">colV</replaceable> nor
<replaceable class="parameter">colH</replaceable>
- is displayed; if there are more columns, an error is thrown.
+ is displayed; if there are more columns, an error is reported.
</para>
<para>
- All columns can be refered to by their position (starting at 1), or by
- their name. Normal case folding and quoting rules apply on column
- names. By default,
- <replaceable class="parameter">colV</replaceable> corresponds to column 1
- and <replaceable class="parameter">colH</replaceable> to column 2.
- A query having only one output column cannot be viewed in crosstab, and
+ Each column specification can be a column number (starting at 1) or
+ a column name. The usual SQL case folding and quoting rules apply to
+ column names. If omitted,
+ <replaceable class="parameter">colV</replaceable> is taken as column 1
+ and <replaceable class="parameter">colH</replaceable> as column 2.
<replaceable class="parameter">colH</replaceable> must differ from
<replaceable class="parameter">colV</replaceable>.
</para>
<para>
- The vertical header, displayed as the leftmost column,
- contains the deduplicated values found in
- column <replaceable class="parameter">colV</replaceable>, in the same
- order as in the query results.
+ The vertical header, displayed as the leftmost column, contains the
+ values found in column <replaceable class="parameter">colV</>, in the
+ same order as in the query results, but with duplicates removed.
</para>
<para>
- The horizontal header, displayed as the first row,
- contains the deduplicated values found in
- column <replaceable class="parameter">colH</replaceable>, in
- the order of appearance in the query results.
- If specified, the optional <replaceable class="parameter">scolH</replaceable>
- argument refers to a column whose values should be integer numbers
- by which <replaceable class="parameter">colH</replaceable> will be sorted
- to be positioned in the horizontal header.
+ The horizontal header, displayed as the first row, contains the values
+ found in column <replaceable class="parameter">colH</replaceable>,
+ with duplicates removed. By default, these appear in the same order
+ as in the query results. But if the
+ optional <replaceable class="parameter">scolH</> argument is given, it
+ identifies a column whose values must be integer numbers, and the
+ values from <replaceable class="parameter">colH</replaceable> will
+ appear in the horizontal header sorted according to the
+ corresponding <replaceable class="parameter">scolH</> values.
</para>
<para>
- Inside the crosstab grid,
- given a query output with <literal>N</literal> columns
- (including <replaceable class="parameter">colV</replaceable> and
- <replaceable class="parameter">colH</replaceable>),
- for each distinct value <literal>x</literal> of
- <replaceable class="parameter">colH</replaceable>
- and each distinct value <literal>y</literal> of
- <replaceable class="parameter">colV</replaceable>,
- the contents of a cell located at the intersection
- <literal>(x,y)</literal> is determined by these rules:
- <itemizedlist>
- <listitem>
- <para>
- if there is no corresponding row in the query results such that the
- value for <replaceable class="parameter">colH</replaceable>
- is <literal>x</literal> and the value
- for <replaceable class="parameter">colV</replaceable>
- is <literal>y</literal>, the cell is empty.
- </para>
- </listitem>
-
- <listitem>
- <para>
- if there is exactly one row such that the value
- for <replaceable class="parameter">colH</replaceable>
- is <literal>x</literal> and the value
- for <replaceable class="parameter">colV</replaceable>
- is <literal>y</literal>, then the <literal>colD</literal> column
- is displayed.
+ Inside the crosstab grid, for each distinct value <literal>x</literal>
+ of <replaceable class="parameter">colH</replaceable> and each distinct
+ value <literal>y</literal>
+ of <replaceable class="parameter">colV</replaceable>, the cell located
+ at the intersection <literal>(x,y)</literal> contains the value of
+ the <literal>colD</literal> column in the query result row for which
+ the value of <replaceable class="parameter">colH</replaceable>
+ is <literal>x</literal> and the value
+ of <replaceable class="parameter">colV</replaceable>
+ is <literal>y</>. If there is no such row, the cell is empty. If
+ there are multiple such rows, an error is reported.
</para>
</listitem>
-
- <listitem>
- <para>
- if there are several such rows, an error is thrown.
- </para>
- </listitem>
-
- </itemizedlist>
- </para>
-
- </listitem>
</varlistentry>
+
<varlistentry>
<term><literal>\d[S+] [ <link linkend="APP-PSQL-patterns"><replaceable class="parameter">pattern</replaceable></link> ]</literal></term>
diff --git a/doc/src/sgml/tablefunc.sgml b/doc/src/sgml/tablefunc.sgml
index 1d8423d5ae..90f6df9545 100644
--- a/doc/src/sgml/tablefunc.sgml
+++ b/doc/src/sgml/tablefunc.sgml
@@ -293,6 +293,14 @@ AS ct(row_name text, category_1 text, category_2 text, category_3 text);
required <literal>FROM</> clause in a view definition.
</para>
+ <note>
+ <para>
+ See also the <command><link linkend="APP-PSQL-meta-commands-crosstabview">\crosstabview</link></command>
+ command in <application>psql</>, which provides functionality similar
+ to <function>crosstab()</>.
+ </para>
+ </note>
+
</sect3>
<sect3>