|
1 |
| -<!-- $PostgreSQL: pgsql/doc/src/sgml/syntax.sgml,v 1.136 2009/09/22 23:52:53 petere Exp $ --> |
| 1 | +<!-- $PostgreSQL: pgsql/doc/src/sgml/syntax.sgml,v 1.137 2009/10/08 02:39:16 tgl Exp $ --> |
2 | 2 |
|
3 | 3 | <chapter id="sql-syntax">
|
4 | 4 | <title>SQL Syntax</title>
|
@@ -1505,6 +1505,11 @@ sqrt(2)
|
1505 | 1505 | The list of built-in functions is in <xref linkend="functions">.
|
1506 | 1506 | Other functions can be added by the user.
|
1507 | 1507 | </para>
|
| 1508 | + |
| 1509 | + <para> |
| 1510 | + The arguments can optionally have names attached. |
| 1511 | + See <xref linkend="sql-syntax-calling-funcs"> for details. |
| 1512 | + </para> |
1508 | 1513 | </sect2>
|
1509 | 1514 |
|
1510 | 1515 | <sect2 id="syntax-aggregates">
|
@@ -2123,4 +2128,168 @@ SELECT ... WHERE CASE WHEN x > 0 THEN y/x > 1.5 ELSE false END;
|
2123 | 2128 | </sect2>
|
2124 | 2129 | </sect1>
|
2125 | 2130 |
|
| 2131 | + <sect1 id="sql-syntax-calling-funcs"> |
| 2132 | + <title>Calling Functions</title> |
| 2133 | + |
| 2134 | + <indexterm zone="sql-syntax-calling-funcs"> |
| 2135 | + <primary>notation</primary> |
| 2136 | + <secondary>functions</secondary> |
| 2137 | + </indexterm> |
| 2138 | + |
| 2139 | + <para> |
| 2140 | + <productname>PostgreSQL</productname> allows functions that have named |
| 2141 | + parameters to be called using either <firstterm>positional</firstterm> or |
| 2142 | + <firstterm>named</firstterm> notation. Named notation is especially |
| 2143 | + useful for functions that have a large number of parameters, since it |
| 2144 | + makes the associations between parameters and actual arguments more |
| 2145 | + explicit and reliable. |
| 2146 | + In positional notation, a function call is written with |
| 2147 | + its argument values in the same order as they are defined in the function |
| 2148 | + declaration. In named notation, the arguments are matched to the |
| 2149 | + function parameters by name and can be written in any order. |
| 2150 | + </para> |
| 2151 | + |
| 2152 | + <para> |
| 2153 | + In either notation, parameters that have default values given in the |
| 2154 | + function declaration need not be written in the call at all. But this |
| 2155 | + is particularly useful in named notation, since any combination of |
| 2156 | + parameters can be omitted; while in positional notation parameters can |
| 2157 | + only be omitted from right to left. |
| 2158 | + </para> |
| 2159 | + |
| 2160 | + <para> |
| 2161 | + <productname>PostgreSQL</productname> also supports |
| 2162 | + <firstterm>mixed</firstterm> notation, which combines positional and |
| 2163 | + named notation. In this case, positional parameters are written first |
| 2164 | + and named parameters appear after them. |
| 2165 | + </para> |
| 2166 | + |
| 2167 | + <para> |
| 2168 | + The following examples will illustrate the usage of all three |
| 2169 | + notations, using the following function definition: |
| 2170 | +<programlisting> |
| 2171 | +CREATE FUNCTION concat_lower_or_upper(a text, b text, uppercase boolean DEFAULT false) |
| 2172 | +RETURNS text |
| 2173 | +AS |
| 2174 | +$$ |
| 2175 | + SELECT CASE |
| 2176 | + WHEN $3 THEN UPPER($1 || ' ' || $2) |
| 2177 | + ELSE LOWER($1 || ' ' || $2) |
| 2178 | + END; |
| 2179 | +$$ |
| 2180 | +LANGUAGE SQL IMMUTABLE STRICT; |
| 2181 | +</programlisting> |
| 2182 | + Function <function>concat_lower_or_upper</function> has two mandatory |
| 2183 | + parameters, <literal>a</literal> and <literal>b</literal>. Additionally |
| 2184 | + there is one optional parameter <literal>uppercase</literal> which defaults |
| 2185 | + to <literal>false</literal>. The <literal>a</literal> and |
| 2186 | + <literal>b</literal> inputs will be concatenated, and forced to either |
| 2187 | + upper or lower case depending on the <literal>uppercase</literal> |
| 2188 | + parameter. The remaining details of this function |
| 2189 | + definition are not important here (see <xref linkend="extend"> for |
| 2190 | + more information). |
| 2191 | + </para> |
| 2192 | + |
| 2193 | + <sect2 id="sql-syntax-calling-funcs-positional"> |
| 2194 | + <title>Using positional notation</title> |
| 2195 | + |
| 2196 | + <indexterm> |
| 2197 | + <primary>function</primary> |
| 2198 | + <secondary>positional notation</secondary> |
| 2199 | + </indexterm> |
| 2200 | + |
| 2201 | + <para> |
| 2202 | + Positional notation is the traditional mechanism for passing arguments |
| 2203 | + to functions in <productname>PostgreSQL</productname>. An example is: |
| 2204 | +<screen> |
| 2205 | +SELECT concat_lower_or_upper('Hello', 'World', true); |
| 2206 | + concat_lower_or_upper |
| 2207 | +----------------------- |
| 2208 | + HELLO WORLD |
| 2209 | +(1 row) |
| 2210 | +</screen> |
| 2211 | + All arguments are specified in order. The result is upper case since |
| 2212 | + <literal>uppercase</literal> is specified as <literal>true</literal>. |
| 2213 | + Another example is: |
| 2214 | +<screen> |
| 2215 | +SELECT concat_lower_or_upper('Hello', 'World'); |
| 2216 | + concat_lower_or_upper |
| 2217 | +----------------------- |
| 2218 | + hello world |
| 2219 | +(1 row) |
| 2220 | +</screen> |
| 2221 | + Here, the <literal>uppercase</literal> parameter is omitted, so it |
| 2222 | + receives its default value of <literal>false</literal>, resulting in |
| 2223 | + lower case output. In positional notation, arguments can be omitted |
| 2224 | + from right to left so long as they have defaults. |
| 2225 | + </para> |
| 2226 | + </sect2> |
| 2227 | + |
| 2228 | + <sect2 id="sql-syntax-calling-funcs-named"> |
| 2229 | + <title>Using named notation</title> |
| 2230 | + |
| 2231 | + <indexterm> |
| 2232 | + <primary>function</primary> |
| 2233 | + <secondary>named notation</secondary> |
| 2234 | + </indexterm> |
| 2235 | + |
| 2236 | + <para> |
| 2237 | + In named notation, each argument's name is specified using the |
| 2238 | + <literal>AS</literal> keyword. For example: |
| 2239 | +<screen> |
| 2240 | +SELECT concat_lower_or_upper('Hello' AS a, 'World' AS b); |
| 2241 | + concat_lower_or_upper |
| 2242 | +----------------------- |
| 2243 | + hello world |
| 2244 | +(1 row) |
| 2245 | +</screen> |
| 2246 | + Again, the argument <literal>uppercase</literal> was omitted |
| 2247 | + so it is set to <literal>false</literal> implicitly. One advantage of |
| 2248 | + using named notation is that the arguments may be specified in any |
| 2249 | + order, for example: |
| 2250 | +<screen> |
| 2251 | +SELECT concat_lower_or_upper('Hello' AS a, 'World' AS b, true AS uppercase); |
| 2252 | + concat_lower_or_upper |
| 2253 | +----------------------- |
| 2254 | + HELLO WORLD |
| 2255 | +(1 row) |
| 2256 | + |
| 2257 | +SELECT concat_lower_or_upper('Hello' AS a, true AS uppercase, 'World' AS b); |
| 2258 | + concat_lower_or_upper |
| 2259 | +----------------------- |
| 2260 | + HELLO WORLD |
| 2261 | +(1 row) |
| 2262 | +</screen> |
| 2263 | + </para> |
| 2264 | + </sect2> |
| 2265 | + |
| 2266 | + <sect2 id="sql-syntax-calling-funcs-mixed"> |
| 2267 | + <title>Using mixed notation</title> |
| 2268 | + |
| 2269 | + <indexterm> |
| 2270 | + <primary>function</primary> |
| 2271 | + <secondary>mixed notation</secondary> |
| 2272 | + </indexterm> |
| 2273 | + |
| 2274 | + <para> |
| 2275 | + The mixed notation combines positional and named notation. However, as |
| 2276 | + already mentioned, named arguments cannot precede positional arguments. |
| 2277 | + For example: |
| 2278 | +<screen> |
| 2279 | +SELECT concat_lower_or_upper('Hello', 'World', true AS uppercase); |
| 2280 | + concat_lower_or_upper |
| 2281 | +----------------------- |
| 2282 | + HELLO WORLD |
| 2283 | +(1 row) |
| 2284 | +</screen> |
| 2285 | + In the above query, the arguments <literal>a</literal> and |
| 2286 | + <literal>b</literal> are specified positionally, while |
| 2287 | + <literal>uppercase</> is specified by name. In this example, |
| 2288 | + that adds little except documentation. With a more complex function |
| 2289 | + having numerous parameters that have default values, named or mixed |
| 2290 | + notation can save a great deal of writing and reduce chances for error. |
| 2291 | + </para> |
| 2292 | + </sect2> |
| 2293 | + </sect1> |
| 2294 | + |
2126 | 2295 | </chapter>
|
0 commit comments