Location via proxy:   [ UP ]  
[Report a bug]   [Manage cookies]                
Skip to content

Commit 9b19c12

Browse files
committed
Document collation handling in SQL and plpgsql functions.
This is pretty minimal but covers the bare facts.
1 parent a4425e3 commit 9b19c12

File tree

3 files changed

+132
-0
lines changed

3 files changed

+132
-0
lines changed

doc/src/sgml/charset.sgml

+2
Original file line numberDiff line numberDiff line change
@@ -316,6 +316,8 @@ initdb --locale=sv_SE
316316
<sect1 id="collation">
317317
<title>Collation Support</title>
318318

319+
<indexterm zone="collation"><primary>collation</></>
320+
319321
<para>
320322
The collation feature allows specifying the sort order and certain
321323
other locale aspects of data per-column, or even per-operation.

doc/src/sgml/plpgsql.sgml

+75
Original file line numberDiff line numberDiff line change
@@ -706,6 +706,81 @@ SELECT merge_fields(t.*) FROM table1 t WHERE ... ;
706706
structure on-the-fly.
707707
</para>
708708
</sect2>
709+
710+
<sect2 id="plpgsql-declaration-collation">
711+
<title>Collation of <application>PL/pgSQL</application> Variables</title>
712+
713+
<indexterm>
714+
<primary>collation</>
715+
<secondary>in PL/pgSQL</>
716+
</indexterm>
717+
718+
<para>
719+
When a <application>PL/pgSQL</application> function has one or more
720+
parameters of collatable data types, a collation is identified for each
721+
function call depending on the collations assigned to the actual
722+
arguments, as described in <xref linkend="collation">. If a collation is
723+
successfully identified (i.e., there are no conflicts of implicit
724+
collations among the arguments) then all the collatable parameters are
725+
treated as having that collation implicitly. This will affect the
726+
behavior of collation-sensitive operations within the function.
727+
For example, consider
728+
729+
<programlisting>
730+
CREATE FUNCTION less_than(a text, b text) RETURNS boolean AS $$
731+
BEGIN
732+
RETURN a &lt; b;
733+
END;
734+
$$ LANGUAGE plpgsql;
735+
736+
SELECT less_than(text_field_1, text_field_2) FROM table1;
737+
SELECT less_than(text_field_1, text_field_2 COLLATE "C") FROM table1;
738+
</programlisting>
739+
740+
The first use of <function>less_than</> will use the common collation
741+
of <structfield>text_field_1</> and <structfield>text_field_2</> for
742+
the comparison, while the second use will use <literal>C</> collation.
743+
</para>
744+
745+
<para>
746+
Furthermore, the identified collation is also assumed as the collation of
747+
any local variables that are of collatable types. Thus this function
748+
would not work any differently if it were written as
749+
750+
<programlisting>
751+
CREATE FUNCTION less_than(a text, b text) RETURNS boolean AS $$
752+
DECLARE
753+
local_a text := a;
754+
local_b text := b;
755+
BEGIN
756+
RETURN local_a &lt; local_b;
757+
END;
758+
$$ LANGUAGE plpgsql;
759+
</programlisting>
760+
</para>
761+
762+
<para>
763+
If there are no parameters of collatable data types, or no common
764+
collation can be identified for them, then parameters and local variables
765+
use the default collation of their data type (which is usually the
766+
database's default collation, but could be different for variables of
767+
domain types).
768+
</para>
769+
770+
<para>
771+
Explicit <literal>COLLATE</> clauses can be written inside a function
772+
if it is desired to force a particular collation to be used regardless
773+
of what the function is called with. For example,
774+
775+
<programlisting>
776+
CREATE FUNCTION less_than_c(a text, b text) RETURNS boolean AS $$
777+
BEGIN
778+
RETURN a &lt; b COLLATE "C";
779+
END;
780+
$$ LANGUAGE plpgsql;
781+
</programlisting>
782+
</para>
783+
</sect2>
709784
</sect1>
710785

711786
<sect1 id="plpgsql-expressions">

doc/src/sgml/xfunc.sgml

+55
Original file line numberDiff line numberDiff line change
@@ -1100,6 +1100,61 @@ SELECT concat_values('|', 1, 4, 2);
11001100
</screen>
11011101
</para>
11021102
</sect2>
1103+
1104+
<sect2>
1105+
<title><acronym>SQL</acronym> Functions with Collations</title>
1106+
1107+
<indexterm>
1108+
<primary>collation</>
1109+
<secondary>in SQL functions</>
1110+
</indexterm>
1111+
1112+
<para>
1113+
When a SQL function has one or more parameters of collatable data types,
1114+
a collation is identified for each function call depending on the
1115+
collations assigned to the actual arguments, as described in <xref
1116+
linkend="collation">. If a collation is successfully identified
1117+
(i.e., there are no conflicts of implicit collations among the arguments)
1118+
then all the collatable parameters are treated as having that collation
1119+
implicitly. This will affect the behavior of collation-sensitive
1120+
operations within the function. For example, using the
1121+
<function>anyleast</> function described above, the result of
1122+
<programlisting>
1123+
SELECT anyleast('abc'::text, 'ABC');
1124+
</programlisting>
1125+
will depend on the database's default collation. In <literal>C</> locale
1126+
the result will be <literal>ABC</>, but in many other locales it will
1127+
be <literal>abc</>. The collation to use can be forced by adding
1128+
a <literal>COLLATE</> clause to any of the arguments, for example
1129+
<programlisting>
1130+
SELECT anyleast('abc'::text, 'ABC' COLLATE "C");
1131+
</programlisting>
1132+
Alternatively, if you wish a function to operate with a particular
1133+
collation regardless of what it is called with, insert
1134+
<literal>COLLATE</> clauses as needed in the function definition.
1135+
This version of <function>anyleast</> would always use <literal>en_US</>
1136+
locale to compare strings:
1137+
<programlisting>
1138+
CREATE FUNCTION anyleast (VARIADIC anyarray) RETURNS anyelement AS $$
1139+
SELECT min($1[i] COLLATE "en_US") FROM generate_subscripts($1, 1) g(i);
1140+
$$ LANGUAGE SQL;
1141+
</programlisting>
1142+
But note that this will throw an error if applied to a non-collatable
1143+
data type.
1144+
</para>
1145+
1146+
<para>
1147+
If no common collation can be identified among the actual arguments,
1148+
then a SQL function treats its parameters as having their data types'
1149+
default collation (which is usually the database's default collation,
1150+
but could be different for parameters of domain types).
1151+
</para>
1152+
1153+
<para>
1154+
The behavior of collatable parameters can be thought of as a limited
1155+
form of polymorphism, applicable only to textual data types.
1156+
</para>
1157+
</sect2>
11031158
</sect1>
11041159

11051160
<sect1 id="xfunc-overload">

0 commit comments

Comments
 (0)