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>