|
| 1 | +<!-- $PostgreSQL: pgsql/doc/src/sgml/rowtypes.sgml,v 2.1 2004/06/07 04:04:47 tgl Exp $ --> |
| 2 | + |
| 3 | +<sect1 id="rowtypes"> |
| 4 | + <title>Composite Types</title> |
| 5 | + |
| 6 | + <indexterm> |
| 7 | + <primary>composite type</primary> |
| 8 | + </indexterm> |
| 9 | + |
| 10 | + <indexterm> |
| 11 | + <primary>row type</primary> |
| 12 | + </indexterm> |
| 13 | + |
| 14 | + <para> |
| 15 | + A <firstterm>composite type</> describes the structure of a row or record; |
| 16 | + it is in essence just a list of field names and their datatypes. |
| 17 | + <productname>PostgreSQL</productname> allows values of composite types to be |
| 18 | + used in many of the same ways that simple types can be used. For example, a |
| 19 | + column of a table can be declared to be of a composite type. |
| 20 | + </para> |
| 21 | + |
| 22 | + <sect2> |
| 23 | + <title>Declaration of Composite Types</title> |
| 24 | + |
| 25 | + <para> |
| 26 | + Here are two simple examples of defining composite types: |
| 27 | +<programlisting> |
| 28 | +CREATE TYPE complex AS ( |
| 29 | + r double precision, |
| 30 | + i double precision |
| 31 | +); |
| 32 | + |
| 33 | +CREATE TYPE inventory_item AS ( |
| 34 | + name text, |
| 35 | + supplier_id integer, |
| 36 | + price numeric |
| 37 | +); |
| 38 | +</programlisting> |
| 39 | + The syntax is comparable to <command>CREATE TABLE</>, except that only |
| 40 | + field names and types can be specified; no constraints (such as <literal>NOT |
| 41 | + NULL</>) can presently be included. Note that the <literal>AS</> keyword |
| 42 | + is essential; without it, the system will think a quite different kind |
| 43 | + of <command>CREATE TYPE</> command is meant, and you'll get odd syntax |
| 44 | + errors. |
| 45 | + </para> |
| 46 | + |
| 47 | + <para> |
| 48 | + Having defined the types, we can use them to create tables: |
| 49 | + |
| 50 | +<programlisting> |
| 51 | +CREATE TABLE on_hand ( |
| 52 | + item inventory_item, |
| 53 | + count integer |
| 54 | +); |
| 55 | + |
| 56 | +INSERT INTO on_hand VALUES (ROW('fuzzy dice', 42, 1.99), 1000); |
| 57 | +</programlisting> |
| 58 | + |
| 59 | + or functions: |
| 60 | + |
| 61 | +<programlisting> |
| 62 | +CREATE FUNCTION price_extension(inventory_item, integer) RETURNS numeric |
| 63 | +AS 'SELECT $1.price * $2' LANGUAGE SQL; |
| 64 | + |
| 65 | +SELECT price_extension(item, 10) FROM on_hand; |
| 66 | +</programlisting> |
| 67 | + |
| 68 | + </para> |
| 69 | + </sect2> |
| 70 | + |
| 71 | + <sect2> |
| 72 | + <title>Composite Value Input</title> |
| 73 | + |
| 74 | + <indexterm> |
| 75 | + <primary>composite type</primary> |
| 76 | + <secondary>constant</secondary> |
| 77 | + </indexterm> |
| 78 | + |
| 79 | + <para> |
| 80 | + To write a composite value as a literal constant, enclose the field |
| 81 | + values within parentheses and separate them by commas. You may put double |
| 82 | + quotes around any field value, and must do so if it contains commas or |
| 83 | + parentheses. (More details appear below.) Thus, the general format of a |
| 84 | + composite constant is the following: |
| 85 | +<synopsis> |
| 86 | +'( <replaceable>val1</replaceable> , <replaceable>val2</replaceable> , ... )' |
| 87 | +</synopsis> |
| 88 | + An example is |
| 89 | +<programlisting> |
| 90 | +'("fuzzy dice",42,1.99)' |
| 91 | +</programlisting> |
| 92 | + which would be a valid value of the <literal>inventory_item</> type |
| 93 | + defined above. To make a field be NULL, write no characters at all |
| 94 | + in its position in the list. For example, this constant specifies |
| 95 | + a NULL third field: |
| 96 | +<programlisting> |
| 97 | +'("fuzzy dice",42,)' |
| 98 | +</programlisting> |
| 99 | + If you want an empty string rather than NULL, write double quotes: |
| 100 | +<programlisting> |
| 101 | +'("",42,)' |
| 102 | +</programlisting> |
| 103 | + Here the first field is a non-NULL empty string, the third is NULL. |
| 104 | + </para> |
| 105 | + |
| 106 | + <para> |
| 107 | + (These constants are actually only a special case of |
| 108 | + the generic type constants discussed in <xref |
| 109 | + linkend="sql-syntax-constants-generic">. The constant is initially |
| 110 | + treated as a string and passed to the composite-type input conversion |
| 111 | + routine. An explicit type specification might be necessary.) |
| 112 | + </para> |
| 113 | + |
| 114 | + <para> |
| 115 | + The <literal>ROW</literal> expression syntax may also be used to |
| 116 | + construct composite values. In most cases this is considerably |
| 117 | + simpler to use than the string-literal syntax, since you don't have |
| 118 | + to worry about multiple layers of quoting. We already used this |
| 119 | + method above: |
| 120 | +<programlisting> |
| 121 | +ROW('fuzzy dice', 42, 1.99) |
| 122 | +ROW('', 42, NULL) |
| 123 | +</programlisting> |
| 124 | + The ROW keyword is actually optional as long as you have more than one |
| 125 | + field in the expression, so these can simplify to |
| 126 | +<programlisting> |
| 127 | +('fuzzy dice', 42, 1.99) |
| 128 | +('', 42, NULL) |
| 129 | +</programlisting> |
| 130 | + The <literal>ROW</> expression syntax is discussed in more detail in <xref |
| 131 | + linkend="sql-syntax-row-constructors">. |
| 132 | + </para> |
| 133 | + </sect2> |
| 134 | + |
| 135 | + <sect2> |
| 136 | + <title>Accessing Composite Types</title> |
| 137 | + |
| 138 | + <para> |
| 139 | + To access a field of a composite column, one writes a dot and the field |
| 140 | + name, much like selecting a field from a table name. In fact, it's so |
| 141 | + much like selecting from a table name that you often have to use parentheses |
| 142 | + to keep from confusing the parser. For example, you might try to select |
| 143 | + some subfields from our <literal>on_hand</> example table with something |
| 144 | + like: |
| 145 | + |
| 146 | +<programlisting> |
| 147 | +SELECT item.name FROM on_hand WHERE item.price > 9.99; |
| 148 | +</programlisting> |
| 149 | + |
| 150 | + This will not work since the name <literal>item</> is taken to be a table |
| 151 | + name, not a field name, per SQL syntax rules. You must write it like this: |
| 152 | + |
| 153 | +<programlisting> |
| 154 | +SELECT (item).name FROM on_hand WHERE (item).price > 9.99; |
| 155 | +</programlisting> |
| 156 | + |
| 157 | + or if you need to use the table name as well (for instance in a multi-table |
| 158 | + query), like this: |
| 159 | + |
| 160 | +<programlisting> |
| 161 | +SELECT (on_hand.item).name FROM on_hand WHERE (on_hand.item).price > 9.99; |
| 162 | +</programlisting> |
| 163 | + |
| 164 | + Now the parenthesized object is correctly interpreted as a reference to |
| 165 | + the <literal>item</> column, and then the subfield can be selected from it. |
| 166 | + </para> |
| 167 | + |
| 168 | + <para> |
| 169 | + Similar syntactic issues apply whenever you select a field from a composite |
| 170 | + value. For instance, to select just one field from the result of a function |
| 171 | + that returns a composite value, you'd need to write something like |
| 172 | + |
| 173 | +<programlisting> |
| 174 | +SELECT (my_func(...)).field FROM ... |
| 175 | +</programlisting> |
| 176 | + |
| 177 | + Without the extra parentheses, this will provoke a syntax error. |
| 178 | + </para> |
| 179 | + </sect2> |
| 180 | + |
| 181 | + <sect2> |
| 182 | + <title>Composite Type Input and Output Syntax</title> |
| 183 | + |
| 184 | + <para> |
| 185 | + The external text representation of a composite value consists of items that |
| 186 | + are interpreted according to the I/O conversion rules for the individual |
| 187 | + field types, plus decoration that indicates the composite structure. |
| 188 | + The decoration consists of parentheses (<literal>(</> and <literal>)</>) |
| 189 | + around the whole value, plus commas (<literal>,</>) between adjacent |
| 190 | + items. Whitespace outside the parentheses is ignored, but within the |
| 191 | + parentheses it is considered part of the field value, and may or may not be |
| 192 | + significant depending on the input conversion rules for the field datatype. |
| 193 | + For example, in |
| 194 | +<programlisting> |
| 195 | +'( 42)' |
| 196 | +</programlisting> |
| 197 | + the whitespace will be ignored if the field type is integer, but not if |
| 198 | + it is text. |
| 199 | + </para> |
| 200 | + |
| 201 | + <para> |
| 202 | + As shown previously, when writing a composite value you may write double |
| 203 | + quotes around any individual field value. |
| 204 | + You <emphasis>must</> do so if the field value would otherwise |
| 205 | + confuse the composite-value parser. In particular, fields containing |
| 206 | + parentheses, commas, double quotes, or backslashes must be double-quoted. |
| 207 | + To put a double quote or backslash in a quoted composite field value, |
| 208 | + precede it with a backslash. (Also, a pair of double quotes within a |
| 209 | + double-quoted field value is taken to represent a double quote character, |
| 210 | + analogously to the rules for single quotes in SQL literal strings.) |
| 211 | + Alternatively, you can use backslash-escaping to protect all data characters |
| 212 | + that would otherwise be taken as composite syntax. |
| 213 | + </para> |
| 214 | + |
| 215 | + <para> |
| 216 | + A completely empty field value (no characters at all between the commas |
| 217 | + or parentheses) represents a NULL. To write a value that is an empty |
| 218 | + string rather than NULL, write <literal>""</>. |
| 219 | + </para> |
| 220 | + |
| 221 | + <para> |
| 222 | + The composite output routine will put double quotes around field values |
| 223 | + if they are empty strings or contain parentheses, commas, |
| 224 | + double quotes, backslashes, or white space. (Doing so for white space |
| 225 | + is not essential, but aids legibility.) Double quotes and backslashes |
| 226 | + embedded in field values will be doubled. |
| 227 | + </para> |
| 228 | + |
| 229 | + <note> |
| 230 | + <para> |
| 231 | + Remember that what you write in an SQL command will first be interpreted |
| 232 | + as a string literal, and then as a composite. This doubles the number of |
| 233 | + backslashes you need. For example, to insert a <type>text</> field |
| 234 | + containing a double quote and a backslash in a composite |
| 235 | + value, you'd need to write |
| 236 | +<programlisting> |
| 237 | +INSERT ... VALUES ('("\\"\\\\")'); |
| 238 | +</programlisting> |
| 239 | + The string-literal processor removes one level of backslashes, so that |
| 240 | + what arrives at the composite-value parser looks like |
| 241 | + <literal>("\"\\")</>. In turn, the string |
| 242 | + fed to the <type>text</> data type's input routine |
| 243 | + becomes <literal>"\</>. (If we were working |
| 244 | + with a data type whose input routine also treated backslashes specially, |
| 245 | + <type>bytea</> for example, we might need as many as eight backslashes |
| 246 | + in the command to get one backslash into the stored composite field.) |
| 247 | + </para> |
| 248 | + </note> |
| 249 | + |
| 250 | + <tip> |
| 251 | + <para> |
| 252 | + The <literal>ROW</> constructor syntax is usually easier to work with |
| 253 | + than the composite-literal syntax when writing composite values in SQL |
| 254 | + commands. |
| 255 | + In <literal>ROW</>, individual field values are written the same way |
| 256 | + they would be written when not members of a composite. |
| 257 | + </para> |
| 258 | + </tip> |
| 259 | + </sect2> |
| 260 | + |
| 261 | +</sect1> |
0 commit comments