2010-09-20 22:08:53 +02:00
|
|
|
<!-- doc/src/sgml/rowtypes.sgml -->
|
2004-06-07 06:04:47 +02:00
|
|
|
|
|
|
|
<sect1 id="rowtypes">
|
|
|
|
<title>Composite Types</title>
|
|
|
|
|
|
|
|
<indexterm>
|
|
|
|
<primary>composite type</primary>
|
|
|
|
</indexterm>
|
|
|
|
|
|
|
|
<indexterm>
|
|
|
|
<primary>row type</primary>
|
|
|
|
</indexterm>
|
|
|
|
|
|
|
|
<para>
|
2009-04-27 18:27:36 +02:00
|
|
|
A <firstterm>composite type</> represents the structure of a row or record;
|
|
|
|
it is essentially just a list of field names and their data types.
|
|
|
|
<productname>PostgreSQL</productname> allows composite types to be
|
2004-06-07 06:04:47 +02:00
|
|
|
used in many of the same ways that simple types can be used. For example, a
|
|
|
|
column of a table can be declared to be of a composite type.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<sect2>
|
|
|
|
<title>Declaration of Composite Types</title>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
Here are two simple examples of defining composite types:
|
|
|
|
<programlisting>
|
|
|
|
CREATE TYPE complex AS (
|
|
|
|
r double precision,
|
|
|
|
i double precision
|
|
|
|
);
|
|
|
|
|
|
|
|
CREATE TYPE inventory_item AS (
|
|
|
|
name text,
|
|
|
|
supplier_id integer,
|
|
|
|
price numeric
|
|
|
|
);
|
|
|
|
</programlisting>
|
|
|
|
The syntax is comparable to <command>CREATE TABLE</>, except that only
|
|
|
|
field names and types can be specified; no constraints (such as <literal>NOT
|
|
|
|
NULL</>) can presently be included. Note that the <literal>AS</> keyword
|
2009-04-27 18:27:36 +02:00
|
|
|
is essential; without it, the system will think a different kind
|
|
|
|
of <command>CREATE TYPE</> command is meant, and you will get odd syntax
|
2009-06-17 23:58:49 +02:00
|
|
|
errors.
|
2004-06-07 06:04:47 +02:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
Having defined the types, we can use them to create tables:
|
|
|
|
|
|
|
|
<programlisting>
|
|
|
|
CREATE TABLE on_hand (
|
|
|
|
item inventory_item,
|
|
|
|
count integer
|
|
|
|
);
|
|
|
|
|
|
|
|
INSERT INTO on_hand VALUES (ROW('fuzzy dice', 42, 1.99), 1000);
|
|
|
|
</programlisting>
|
|
|
|
|
|
|
|
or functions:
|
|
|
|
|
|
|
|
<programlisting>
|
|
|
|
CREATE FUNCTION price_extension(inventory_item, integer) RETURNS numeric
|
|
|
|
AS 'SELECT $1.price * $2' LANGUAGE SQL;
|
|
|
|
|
|
|
|
SELECT price_extension(item, 10) FROM on_hand;
|
|
|
|
</programlisting>
|
|
|
|
|
|
|
|
</para>
|
2004-06-09 21:08:20 +02:00
|
|
|
|
|
|
|
<para>
|
2009-06-17 23:58:49 +02:00
|
|
|
Whenever you create a table, a composite type is also automatically
|
|
|
|
created, with the same name as the table, to represent the table's
|
2007-02-01 01:28:19 +01:00
|
|
|
row type. For example, had we said:
|
2004-06-09 21:08:20 +02:00
|
|
|
<programlisting>
|
|
|
|
CREATE TABLE inventory_item (
|
|
|
|
name text,
|
|
|
|
supplier_id integer REFERENCES suppliers,
|
2005-01-22 23:56:36 +01:00
|
|
|
price numeric CHECK (price > 0)
|
2004-06-09 21:08:20 +02:00
|
|
|
);
|
|
|
|
</programlisting>
|
|
|
|
then the same <literal>inventory_item</> composite type shown above would
|
2010-11-23 21:27:50 +01:00
|
|
|
come into being as a
|
2004-06-09 21:08:20 +02:00
|
|
|
byproduct, and could be used just as above. Note however an important
|
|
|
|
restriction of the current implementation: since no constraints are
|
|
|
|
associated with a composite type, the constraints shown in the table
|
|
|
|
definition <emphasis>do not apply</> to values of the composite type
|
|
|
|
outside the table. (A partial workaround is to use domain
|
|
|
|
types as members of composite types.)
|
|
|
|
</para>
|
2004-06-07 06:04:47 +02:00
|
|
|
</sect2>
|
|
|
|
|
|
|
|
<sect2>
|
|
|
|
<title>Composite Value Input</title>
|
|
|
|
|
|
|
|
<indexterm>
|
|
|
|
<primary>composite type</primary>
|
|
|
|
<secondary>constant</secondary>
|
|
|
|
</indexterm>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
To write a composite value as a literal constant, enclose the field
|
Update documentation on may/can/might:
Standard English uses "may", "can", and "might" in different ways:
may - permission, "You may borrow my rake."
can - ability, "I can lift that log."
might - possibility, "It might rain today."
Unfortunately, in conversational English, their use is often mixed, as
in, "You may use this variable to do X", when in fact, "can" is a better
choice. Similarly, "It may crash" is better stated, "It might crash".
Also update two error messages mentioned in the documenation to match.
2007-01-31 21:56:20 +01:00
|
|
|
values within parentheses and separate them by commas. You can put double
|
2004-06-07 06:04:47 +02:00
|
|
|
quotes around any field value, and must do so if it contains commas or
|
|
|
|
parentheses. (More details appear below.) Thus, the general format of a
|
|
|
|
composite constant is the following:
|
|
|
|
<synopsis>
|
|
|
|
'( <replaceable>val1</replaceable> , <replaceable>val2</replaceable> , ... )'
|
|
|
|
</synopsis>
|
2007-02-01 01:28:19 +01:00
|
|
|
An example is:
|
2004-06-07 06:04:47 +02:00
|
|
|
<programlisting>
|
|
|
|
'("fuzzy dice",42,1.99)'
|
|
|
|
</programlisting>
|
|
|
|
which would be a valid value of the <literal>inventory_item</> type
|
|
|
|
defined above. To make a field be NULL, write no characters at all
|
|
|
|
in its position in the list. For example, this constant specifies
|
|
|
|
a NULL third field:
|
|
|
|
<programlisting>
|
|
|
|
'("fuzzy dice",42,)'
|
|
|
|
</programlisting>
|
|
|
|
If you want an empty string rather than NULL, write double quotes:
|
|
|
|
<programlisting>
|
|
|
|
'("",42,)'
|
|
|
|
</programlisting>
|
|
|
|
Here the first field is a non-NULL empty string, the third is NULL.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
(These constants are actually only a special case of
|
|
|
|
the generic type constants discussed in <xref
|
|
|
|
linkend="sql-syntax-constants-generic">. The constant is initially
|
|
|
|
treated as a string and passed to the composite-type input conversion
|
|
|
|
routine. An explicit type specification might be necessary.)
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
Update documentation on may/can/might:
Standard English uses "may", "can", and "might" in different ways:
may - permission, "You may borrow my rake."
can - ability, "I can lift that log."
might - possibility, "It might rain today."
Unfortunately, in conversational English, their use is often mixed, as
in, "You may use this variable to do X", when in fact, "can" is a better
choice. Similarly, "It may crash" is better stated, "It might crash".
Also update two error messages mentioned in the documenation to match.
2007-01-31 21:56:20 +01:00
|
|
|
The <literal>ROW</literal> expression syntax can also be used to
|
2004-06-07 06:04:47 +02:00
|
|
|
construct composite values. In most cases this is considerably
|
2009-04-27 18:27:36 +02:00
|
|
|
simpler to use than the string-literal syntax since you don't have
|
2004-06-07 06:04:47 +02:00
|
|
|
to worry about multiple layers of quoting. We already used this
|
|
|
|
method above:
|
|
|
|
<programlisting>
|
|
|
|
ROW('fuzzy dice', 42, 1.99)
|
|
|
|
ROW('', 42, NULL)
|
|
|
|
</programlisting>
|
|
|
|
The ROW keyword is actually optional as long as you have more than one
|
2007-02-01 01:28:19 +01:00
|
|
|
field in the expression, so these can simplify to:
|
2004-06-07 06:04:47 +02:00
|
|
|
<programlisting>
|
|
|
|
('fuzzy dice', 42, 1.99)
|
|
|
|
('', 42, NULL)
|
|
|
|
</programlisting>
|
|
|
|
The <literal>ROW</> expression syntax is discussed in more detail in <xref
|
|
|
|
linkend="sql-syntax-row-constructors">.
|
|
|
|
</para>
|
|
|
|
</sect2>
|
|
|
|
|
|
|
|
<sect2>
|
|
|
|
<title>Accessing Composite Types</title>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
To access a field of a composite column, one writes a dot and the field
|
|
|
|
name, much like selecting a field from a table name. In fact, it's so
|
|
|
|
much like selecting from a table name that you often have to use parentheses
|
|
|
|
to keep from confusing the parser. For example, you might try to select
|
|
|
|
some subfields from our <literal>on_hand</> example table with something
|
|
|
|
like:
|
|
|
|
|
|
|
|
<programlisting>
|
2005-01-22 23:56:36 +01:00
|
|
|
SELECT item.name FROM on_hand WHERE item.price > 9.99;
|
2004-06-07 06:04:47 +02:00
|
|
|
</programlisting>
|
|
|
|
|
|
|
|
This will not work since the name <literal>item</> is taken to be a table
|
2009-04-27 18:27:36 +02:00
|
|
|
name, not a column name of <literal>on_hand</>, per SQL syntax rules.
|
|
|
|
You must write it like this:
|
2004-06-07 06:04:47 +02:00
|
|
|
|
|
|
|
<programlisting>
|
2005-01-22 23:56:36 +01:00
|
|
|
SELECT (item).name FROM on_hand WHERE (item).price > 9.99;
|
2004-06-07 06:04:47 +02:00
|
|
|
</programlisting>
|
|
|
|
|
2005-11-05 00:14:02 +01:00
|
|
|
or if you need to use the table name as well (for instance in a multitable
|
2004-06-07 06:04:47 +02:00
|
|
|
query), like this:
|
|
|
|
|
|
|
|
<programlisting>
|
2005-01-22 23:56:36 +01:00
|
|
|
SELECT (on_hand.item).name FROM on_hand WHERE (on_hand.item).price > 9.99;
|
2004-06-07 06:04:47 +02:00
|
|
|
</programlisting>
|
|
|
|
|
|
|
|
Now the parenthesized object is correctly interpreted as a reference to
|
|
|
|
the <literal>item</> column, and then the subfield can be selected from it.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
Similar syntactic issues apply whenever you select a field from a composite
|
|
|
|
value. For instance, to select just one field from the result of a function
|
2007-02-01 01:28:19 +01:00
|
|
|
that returns a composite value, you'd need to write something like:
|
2004-06-07 06:04:47 +02:00
|
|
|
|
|
|
|
<programlisting>
|
|
|
|
SELECT (my_func(...)).field FROM ...
|
|
|
|
</programlisting>
|
|
|
|
|
2009-04-27 18:27:36 +02:00
|
|
|
Without the extra parentheses, this will generate a syntax error.
|
2004-06-07 06:04:47 +02:00
|
|
|
</para>
|
|
|
|
</sect2>
|
|
|
|
|
2004-06-09 21:08:20 +02:00
|
|
|
<sect2>
|
|
|
|
<title>Modifying Composite Types</title>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
Here are some examples of the proper syntax for inserting and updating
|
|
|
|
composite columns.
|
|
|
|
First, inserting or updating a whole column:
|
|
|
|
|
|
|
|
<programlisting>
|
|
|
|
INSERT INTO mytab (complex_col) VALUES((1.1,2.2));
|
|
|
|
|
|
|
|
UPDATE mytab SET complex_col = ROW(1.1,2.2) WHERE ...;
|
|
|
|
</programlisting>
|
|
|
|
|
|
|
|
The first example omits <literal>ROW</>, the second uses it; we
|
|
|
|
could have done it either way.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
We can update an individual subfield of a composite column:
|
|
|
|
|
|
|
|
<programlisting>
|
|
|
|
UPDATE mytab SET complex_col.r = (complex_col).r + 1 WHERE ...;
|
|
|
|
</programlisting>
|
|
|
|
|
|
|
|
Notice here that we don't need to (and indeed cannot)
|
|
|
|
put parentheses around the column name appearing just after
|
|
|
|
<literal>SET</>, but we do need parentheses when referencing the same
|
|
|
|
column in the expression to the right of the equal sign.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
And we can specify subfields as targets for <command>INSERT</>, too:
|
|
|
|
|
|
|
|
<programlisting>
|
|
|
|
INSERT INTO mytab (complex_col.r, complex_col.i) VALUES(1.1, 2.2);
|
|
|
|
</programlisting>
|
|
|
|
|
|
|
|
Had we not supplied values for all the subfields of the column, the
|
2004-12-13 19:05:10 +01:00
|
|
|
remaining subfields would have been filled with null values.
|
2004-06-09 21:08:20 +02:00
|
|
|
</para>
|
|
|
|
</sect2>
|
|
|
|
|
2004-06-07 06:04:47 +02:00
|
|
|
<sect2>
|
|
|
|
<title>Composite Type Input and Output Syntax</title>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
The external text representation of a composite value consists of items that
|
|
|
|
are interpreted according to the I/O conversion rules for the individual
|
|
|
|
field types, plus decoration that indicates the composite structure.
|
2009-06-17 23:58:49 +02:00
|
|
|
The decoration consists of parentheses (<literal>(</> and <literal>)</>)
|
2004-06-07 06:04:47 +02:00
|
|
|
around the whole value, plus commas (<literal>,</>) between adjacent
|
|
|
|
items. Whitespace outside the parentheses is ignored, but within the
|
Update documentation on may/can/might:
Standard English uses "may", "can", and "might" in different ways:
may - permission, "You may borrow my rake."
can - ability, "I can lift that log."
might - possibility, "It might rain today."
Unfortunately, in conversational English, their use is often mixed, as
in, "You may use this variable to do X", when in fact, "can" is a better
choice. Similarly, "It may crash" is better stated, "It might crash".
Also update two error messages mentioned in the documenation to match.
2007-01-31 21:56:20 +01:00
|
|
|
parentheses it is considered part of the field value, and might or might not be
|
2004-12-13 19:05:10 +01:00
|
|
|
significant depending on the input conversion rules for the field data type.
|
2007-02-01 01:28:19 +01:00
|
|
|
For example, in:
|
2004-06-07 06:04:47 +02:00
|
|
|
<programlisting>
|
|
|
|
'( 42)'
|
|
|
|
</programlisting>
|
|
|
|
the whitespace will be ignored if the field type is integer, but not if
|
|
|
|
it is text.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2009-06-17 23:58:49 +02:00
|
|
|
As shown previously, when writing a composite value you can write double
|
2004-06-07 06:04:47 +02:00
|
|
|
quotes around any individual field value.
|
|
|
|
You <emphasis>must</> do so if the field value would otherwise
|
|
|
|
confuse the composite-value parser. In particular, fields containing
|
|
|
|
parentheses, commas, double quotes, or backslashes must be double-quoted.
|
|
|
|
To put a double quote or backslash in a quoted composite field value,
|
|
|
|
precede it with a backslash. (Also, a pair of double quotes within a
|
|
|
|
double-quoted field value is taken to represent a double quote character,
|
|
|
|
analogously to the rules for single quotes in SQL literal strings.)
|
2009-04-27 18:27:36 +02:00
|
|
|
Alternatively, you can avoid quoting and use backslash-escaping to
|
|
|
|
protect all data characters
|
2004-06-07 06:04:47 +02:00
|
|
|
that would otherwise be taken as composite syntax.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
A completely empty field value (no characters at all between the commas
|
|
|
|
or parentheses) represents a NULL. To write a value that is an empty
|
|
|
|
string rather than NULL, write <literal>""</>.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
The composite output routine will put double quotes around field values
|
|
|
|
if they are empty strings or contain parentheses, commas,
|
|
|
|
double quotes, backslashes, or white space. (Doing so for white space
|
|
|
|
is not essential, but aids legibility.) Double quotes and backslashes
|
|
|
|
embedded in field values will be doubled.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<note>
|
|
|
|
<para>
|
|
|
|
Remember that what you write in an SQL command will first be interpreted
|
|
|
|
as a string literal, and then as a composite. This doubles the number of
|
2007-01-30 23:29:23 +01:00
|
|
|
backslashes you need (assuming escape string syntax is used).
|
|
|
|
For example, to insert a <type>text</> field
|
2004-06-07 06:04:47 +02:00
|
|
|
containing a double quote and a backslash in a composite
|
2007-02-01 01:28:19 +01:00
|
|
|
value, you'd need to write:
|
2004-06-07 06:04:47 +02:00
|
|
|
<programlisting>
|
2007-01-30 23:29:23 +01:00
|
|
|
INSERT ... VALUES (E'("\\"\\\\")');
|
2004-06-07 06:04:47 +02:00
|
|
|
</programlisting>
|
|
|
|
The string-literal processor removes one level of backslashes, so that
|
|
|
|
what arrives at the composite-value parser looks like
|
|
|
|
<literal>("\"\\")</>. In turn, the string
|
|
|
|
fed to the <type>text</> data type's input routine
|
|
|
|
becomes <literal>"\</>. (If we were working
|
|
|
|
with a data type whose input routine also treated backslashes specially,
|
|
|
|
<type>bytea</> for example, we might need as many as eight backslashes
|
|
|
|
in the command to get one backslash into the stored composite field.)
|
Update documentation on may/can/might:
Standard English uses "may", "can", and "might" in different ways:
may - permission, "You may borrow my rake."
can - ability, "I can lift that log."
might - possibility, "It might rain today."
Unfortunately, in conversational English, their use is often mixed, as
in, "You may use this variable to do X", when in fact, "can" is a better
choice. Similarly, "It may crash" is better stated, "It might crash".
Also update two error messages mentioned in the documenation to match.
2007-01-31 21:56:20 +01:00
|
|
|
Dollar quoting (see <xref linkend="sql-syntax-dollar-quoting">) can be
|
2004-12-23 06:37:40 +01:00
|
|
|
used to avoid the need to double backslashes.
|
2004-06-07 06:04:47 +02:00
|
|
|
</para>
|
|
|
|
</note>
|
|
|
|
|
|
|
|
<tip>
|
|
|
|
<para>
|
|
|
|
The <literal>ROW</> constructor syntax is usually easier to work with
|
|
|
|
than the composite-literal syntax when writing composite values in SQL
|
2010-11-23 21:27:50 +01:00
|
|
|
commands.
|
2004-06-07 06:04:47 +02:00
|
|
|
In <literal>ROW</>, individual field values are written the same way
|
|
|
|
they would be written when not members of a composite.
|
|
|
|
</para>
|
|
|
|
</tip>
|
|
|
|
</sect2>
|
|
|
|
|
|
|
|
</sect1>
|